--- linuxsampler/trunk/src/Sampler.h 2004/04/26 17:15:51 53 +++ linuxsampler/trunk/src/Sampler.h 2004/05/02 17:45:43 57 @@ -58,38 +58,230 @@ // just symbol prototyping class Sampler; + /** LinuxSampler sampler channel + * + * Encapsulates one sampler engine, one connection to a MIDI input + * device and one connection to an audio output device. You cannot + * create an instance of this class on you own, you have to use the + * AddSamplerChannel() method of the Sampler object to create a new + * sampler channel. + */ class SamplerChannel { public: - SamplerChannel(Sampler* pS); - ~SamplerChannel(); - void LoadEngine(engine_type_t EngineType); - void SetAudioOutputDevice(audio_output_type_t AudioType); - void SetMidiInputDevice(midi_input_type_t MidiType, MidiInputDevice::midi_chan_t MidiChannel = MidiInputDevice::midi_chan_all); - Engine* GetEngine(); - MidiInputDevice* GetMidiInputDevice(); + /** + * Deploy a sampler engine of the given type for this sampler + * channnel. If there was already a sampler engine deployed on + * this sampler channel, then the old engine will automatically + * be destroyed. + * + * @param EngineType - type of the engine to deploy + */ + void LoadEngine(engine_type_t EngineType); + + /** + * Connect this sampler channel to an audio output device (that + * is audio output driver) of the given type. If the audio + * output for the desired audio output system is not yet + * created, then it will be created automatically, but with + * default settings though. If this sampler channel was already + * connected to an audio output device, then the old connection + * will automatically be removed before. + * + * @param AudioType - audio output system to connect to + */ + void SetAudioOutputDevice(audio_output_type_t AudioType); + + /** + * Connect this sampler channel to and MIDI input device (that + * is MIDI input driver) of the given type. If the MIDI input + * driver for the desired MIDI input system is not yet created, + * then it will be created automatically, but with default + * settings though. If this sampler channel was already + * connected to a MIDI input device, then the old connection + * will automatically be removed before. + * + * @param MidiType - MIDI input system to connect to + * @param MidiChannel - optional: MIDI channel on which the + * sampler channel should listen to + * (default: listen on all MIDI channels) + */ + void SetMidiInputDevice(midi_input_type_t MidiType, MidiInputDevice::midi_chan_t MidiChannel = MidiInputDevice::midi_chan_all); + + /** + * Returns the engine that was deployed on this sampler channel. + * + * @returns pointer to engine or NULL if no engine deployed + */ + Engine* GetEngine(); + + /** + * Returns the MIDI input device to which this sampler channel + * is currently connected to. + * + * @returns pointer to MIDI input device or NULL if not + * connected + */ + MidiInputDevice* GetMidiInputDevice(); + + /** + * Returns the audio output device to which this sampler channel + * is currently connected to. + * + * @returns pointer to audio output device or NULL if not + * connected + */ AudioOutputDevice* GetAudioOutputDevice(); - uint Index(); + + /** + * Returns the index number of this sampler channel within the + * Sampler instance. + */ + uint Index(); + protected: + SamplerChannel(Sampler* pS); + ~SamplerChannel(); + Sampler* pSampler; Engine* pEngine; MidiInputDevice* pMidiInputDevice; AudioOutputDevice* pAudioOutputDevice; int iIndex; + + friend class Sampler; }; + /** LinuxSampler main class + * + * This is the toplevel class for a LinuxSampler instance. + * + * LinuxSampler can have arbitrary numbers of sampler channels. Each + * sampler channel can individually be deployed with it's own sampler + * engine, connected to an arbitrary MIDI input device and connected to + * an arbitrary audio output device. Here an example setup: + * + * S.Channel. MIDI in S.Engine Audio out + * ------------------------------------------------------------------- + * 0 Alsa -> gig::Engine -> Jack + * 1 VSTi -> Akai::Engine -> VSTi + * 2 Jack -> DLS::Engine -> Jack + * 3 Jack -> SF::Engine -> Alsa + * + * ... (and so on) ... + * + * Note that not all audio and MIDI backends and sampler engines listed + * in the example above are already implemented! + * + * As you can see in the example setup, LinuxSampler is capable to use + * several, different audio output and MIDI input systems + * simultaniously at the same time. Here the example setup shown in the + * ascpect of MIDI input and audio output devices / drivers: + * + * ######################### ######################### + * # AudioOutputDeviceJack # # AudioOutputDeviceVSTi # + * ######################### ######################### + * ^ ^ ^ + * /------------>|Sampler Channel 0|-----/ | | + * | /--------->|Sampler Channel 1|---------------------/ + * | | /---->|Sampler Channel 2|---------/ + * | | | /->|Sampler Channel 3|------------>######################### + * | | | | ... (and so on) ... # AudioOutputDeviceAlsa # + * | | | | ######################### + * | | | \----------------------------------------------------\ + * | | \-------------------------------------------\ | + * | \--------------------\ | | + * | | | | + * ####################### ####################### ####################### + * # MidiInputDeviceAlsa # # MidiInputDeviceVSTi # # MidiInputDeviceJack # + * ####################### ####################### ####################### + * + * As you can see in this example setup, one device (that is midi input + * driver / audio output driver) can be connected multiple times to + * different sampler channels. + */ class Sampler { public: + /** + * Constructor. Create a LinuxSampler instance. + */ Sampler(); + + /** + * Destructor. + */ ~Sampler(); - uint SamplerChannels(); - SamplerChannel* AddSamplerChannel(); - SamplerChannel* GetSamplerChannel(uint uiSamplerChannel); - void RemoveSamplerChannel(SamplerChannel* pSamplerChannel); - void RemoveSamplerChannel(uint uiSamplerChannel); + + /** + * Returns the number of sampler channels currently allocated. + */ + uint SamplerChannels(); + + /** + * Create and add a new sampler channel to this Sampler instance. + * + * @returns pointer to new sampler channel + */ + SamplerChannel* AddSamplerChannel(); + + /** + * Returns the sampler channel of the given sampler channel + * index. + * + * @returns pointer to sought sampler channel + */ + SamplerChannel* GetSamplerChannel(uint uiSamplerChannel); + + /** + * Destroy and remove the given sampler channel from this + * Sampler instance. + * + * @param pSamplerChannel - pointer to sampler channel to remove + */ + void RemoveSamplerChannel(SamplerChannel* pSamplerChannel); + + /** + * Destroy and remove the given sampler channel from this + * Sampler instance. + * + * @param uiSamplerChannel - index of the sampler channel to + * remove + */ + void RemoveSamplerChannel(uint uiSamplerChannel); + + /** + * Create an audio output device of the given type. + * + * @param AudioType - desired audio output system to use + * @returns pointer to created audio output device + */ AudioOutputDevice* CreateAudioOutputDevice(audio_output_type_t AudioType); + + /** + * Returns the audio output device of the given type. + * + * @param AudioType - desired audio output system to use + * @returns pointer to audio output device or NULL if device of + * desired type is not yet created + */ AudioOutputDevice* GetAudioOutputDevice(audio_output_type_t AudioType); - MidiInputDevice* CreateMidiInputDevice(midi_input_type_t MidiType); - MidiInputDevice* GetMidiInputDevice(midi_input_type_t MidiType); + + /** + * Create a MIDI input device of the given type. + * + * @param MidiType - desired MIDI input system to use + * @returns pointer to created MIDI input device + */ + MidiInputDevice* CreateMidiInputDevice(midi_input_type_t MidiType); + + /** + * Returns the MIDI input device of the given type. + * + * @param MidiType - desired MIDI input system to use + * @returns pointer to MIDI input device or NULL if device of + * desired type is not yet created + */ + MidiInputDevice* GetMidiInputDevice(midi_input_type_t MidiType); + protected: typedef std::map AudioOutputDeviceMap; typedef std::map MidiInputDeviceMap;