trunk/src/Sampler.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005, 2006 Christian Schoenebeck                        *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __LS_SAMPLER_H__
#define __LS_SAMPLER_H__

#include <vector>
#include <map>
#include "common/global.h"
#include "common/Exception.h"
#include "engines/EngineChannel.h"
#include "drivers/midi/MidiInputDevice.h"
#include "drivers/audio/AudioOutputDevice.h"

namespace LinuxSampler {

    // just symbol prototyping
    class Sampler;

    /** @brief LinuxSampler sampler channel
     *
     * Encapsulates a channel of a specific sampler engine type, one
     * connection to a MIDI input device and one connection to an audio
     * output device. You cannot create an instance of this class on your
     * own, you have to use the AddSamplerChannel() method of the Sampler
     * object to create a new sampler channel.
     */
    class SamplerChannel {
        public:
            /**
             * Assign a sampler engine type to this sampler channel.
             *
             * @param EngineType - type of the engine to use
             * @throws Exception - if \a EngineType is invalid
             */
            void SetEngineType(String EngineType) throw (Exception);

            /**
             * Connect this sampler channel to an audio output device, that
             * is an instance of an audio output driver. If this sampler
             * channel was already connected to an audio output device, then
             * the old connection will automatically be removed before.
             *
             * @param pDevice - audio output device to connect to
             */
            void SetAudioOutputDevice(AudioOutputDevice* pDevice);

            /**
             * Connect this sampler channel to a MIDI input device.
             *
             * @param pDevice - MIDI input device to connect to
             */
            void SetMidiInputDevice(MidiInputDevice *pDevice);

            /**
             * Connect this sampler channel to a MIDI input port.
             *
             * @param MidiPort - MIDI port to connect to
             */
            void SetMidiInputPort(int MidiPort);

            /**
             * Define on which MIDI channel(s) this sampler channel should
             * listen to. By default, that is after creation of a new
             * sampler channel, the sampler channel will listen to all MIDI
             * channels.
             *
             * @param MidiChannel - MIDI channel to listen
             */
            void SetMidiInputChannel(midi_chan_t MidiChannel);

            /**
             * Connect this sampler channel to a MIDI input triplet.
             *
             * @param pDevice - MIDI input device to connect to
             * @param iMidiPort - MIDI port to connect to
             * @param MidiChannel - optional: MIDI channel on which the
             *                      sampler channel should listen to
             *                      (default: listen on all MIDI channels)
             */
            void SetMidiInput(MidiInputDevice* pDevice, int iMidiPort, midi_chan_t MidiChannel = midi_chan_all);

            /**
             * Returns the EngineChannel object that was deployed on this
             * sampler channel appropriate to the given sampler engine type.
             *
             * @returns  pointer to engine or NULL if no engine deployed
             */
            EngineChannel* GetEngineChannel();

            /**
             * Returns the MIDI input channel to which this sampler
             * channel is currently connected to.
             *
             * @returns  The MIDI input channel on which the sampler
             *           channel is listening to.
             */
            midi_chan_t GetMidiInputChannel();

            /**
             * Returns the MIDI input port number to which this sampler
             * channel is currently connected to.
             *
             * @returns  MIDI input port number or -1 if not connected
             */
            int GetMidiInputPort();

            /**
             * 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();

            /**
             * 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 index number of this sampler channel within the
             * Sampler instance.
             */
            uint Index();

        protected:
            SamplerChannel(Sampler* pS);
            virtual ~SamplerChannel();

            /** Getting MIDI input device port given its index number. */
            MidiInputPort* __GetMidiInputDevicePort(int iMidiPort);

            Sampler*           pSampler;
            EngineChannel*     pEngineChannel;
            AudioOutputDevice* pAudioOutputDevice;
            MidiInputDevice*   pMidiInputDevice;
            int                iIndex;

            friend class Sampler;
        private:
            int                iMidiPort;   ///< Don't access directly, read GetMidiInputPort() instead !
            midi_chan_t        midiChannel; ///< Don't access directly, read GetMidiInputChannel() instead !
    };

    /** @brief 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:
     * @code
     * 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) ...
     * @endcode
     *
     * Note that not all audio and MIDI backends and sampler engines listed
     * in the example above might already been 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
     * aspect of MIDI input and audio output devices / drivers:
     * @code
     *                      ######################### #########################
     *                      # AudioOutputDeviceJack # # AudioOutputDeviceVSTi #
     *                      ######################### #########################
     *                                        ^   ^           ^
     *  /------------>|Sampler Channel 0|-----/   |           |
     *  |  /--------->|Sampler Channel 1|---------------------/
     *  |  |  /------>|Sampler Channel 2|---------/
     *  |  |  |  /--->|Sampler Channel 3|------------>#########################
     *  |  |  |  |    ... (and so on) ...             # AudioOutputDeviceAlsa #
     *  |  |  |  |                                    #########################
     *  |  |  |  \-----------------------------------------------------\
     *  |  |  \--------------------------------------------\           |
     *  |  \--------------------\                          |           |
     *  |                       |                          |           |
     * ####################### ####################### #######################
     * # MidiInputDeviceAlsa # # MidiInputDeviceVSTi # # MidiInputDeviceJack #
     * ####################### ####################### #######################
     * @endcode
     *
     * 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.
     *
     * It's even possible to create multiple instances of the same driver, for
     * example multiple instances of the Alsa output driver to use multiple
     * sound cards at the same time, or multiple instances of the JACK audio
     * output driver to leverage SMP systems or boxes with several hard discs.
     */
    class Sampler {
        public:
            /**
             * Constructor. Create a LinuxSampler instance.
             */
            Sampler();

            /**
             * Destructor.
             */
            virtual ~Sampler();

            /**
             * Returns the number of sampler channels currently allocated.
             */
            uint SamplerChannels();

            /**
             * Create and add a new sampler channel to this Sampler
             * instance. For race condition reasons the new channel will use
             * an index past the last already existing sampler channel
             * index (in case the index limit was not reached yet, otherwise
             * a free index starting from 0 is searched).
             *
             * @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);

            /**
             * Returns all created sampler channels.
             */
            std::map<uint, SamplerChannel*> GetSamplerChannels();

            /**
             * 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);

            /**
             * Returns the names of all available audio output drivers.
             */
            std::vector<String> AvailableAudioOutputDrivers();

            /**
             * Create an audio output device.
             *
             * @param AudioDriver - name of the audio driver
             * @param Parameters - eventually needed driver parameters to
             *                     create the device
             * @returns  pointer to created audio output device
             * @throws Exception  if device could not be created
             */
            AudioOutputDevice* CreateAudioOutputDevice(String AudioDriver, std::map<String,String> Parameters) throw (Exception);

            /**
             * Create a midi input device.
             *
             * @param MidiDriver - name of the midi driver
             * @param Parameters - eventually needed driver parameters to
             *                     create the device
             * @returns  pointer to created midi input device
             * @throws Exception  if device could not be created
             */
            MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (Exception);

            /**
             * Returns the number of all created audio output devices.
             */
            uint AudioOutputDevices();

            /**
             * Returns the number of all created MIDI input devices.
             */
            uint MidiInputDevices();

            /**
             * Returns all created audio output devices.
             */
            std::map<uint, AudioOutputDevice*> GetAudioOutputDevices();

            /**
             * Returns all created MIDI input devices.
             */
            std::map<uint, MidiInputDevice*> GetMidiInputDevices();

            /**
             * Destroy the given audio output device and takes care if there
             * are still sampler angines connected to this device, etc.
             *
             * @throws Exception  if sampler channels are still
             *                    connected to the device
             */
            void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (Exception);

            /**
             * Destroy the given MIDI input device and takes care if there
             * are still sampler angines connected to this device, etc.
             *
             * @throws Exception  if sampler channels are still
             *                    connected to the device
             */
            void DestroyMidiInputDevice(MidiInputDevice* pDevice) throw (Exception);

            /**
             * Gets the current number of all active voices.
             * @returns The current number of all active voices.
             */
            int GetVoiceCount();

            /**
             * Reset the whole sampler. Destroy all engines, sampler
             * channels, MIDI input devices and audio output devices.
             */
            void Reset();

        protected:
            typedef std::map<uint, AudioOutputDevice*> AudioOutputDeviceMap;
            typedef std::map<uint, MidiInputDevice*> MidiInputDeviceMap;
            typedef std::map<uint, SamplerChannel*> SamplerChannelMap;

            SamplerChannelMap     mSamplerChannels;    ///< contains all created sampler channels
            AudioOutputDeviceMap  mAudioOutputDevices; ///< contains all created audio output devices
            MidiInputDeviceMap    mMidiInputDevices;   ///< contains all created MIDI input devices

            friend class SamplerChannel;
    };
}

#endif // __LS_SAMPLER_H__
1	/***************************************************************************
2	* *
3	* LinuxSampler - modular, streaming capable sampler *
4	* *
5	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	* Copyright (C) 2005, 2006 Christian Schoenebeck *
7	* *
8	* This program is free software; you can redistribute it and/or modify *
9	* it under the terms of the GNU General Public License as published by *
10	* the Free Software Foundation; either version 2 of the License, or *
11	* (at your option) any later version. *
12	* *
13	* This program is distributed in the hope that it will be useful, *
14	* but WITHOUT ANY WARRANTY; without even the implied warranty of *
15	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16	* GNU General Public License for more details. *
17	* *
18	* You should have received a copy of the GNU General Public License *
19	* along with this program; if not, write to the Free Software *
20	* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
21	* MA 02111-1307 USA *
22	***************************************************************************/
23
24	#ifndef __LS_SAMPLER_H__
25	#define __LS_SAMPLER_H__
26
27	#include <vector>
28	#include <map>
29	#include "common/global.h"
30	#include "common/Exception.h"
31	#include "engines/EngineChannel.h"
32	#include "drivers/midi/MidiInputDevice.h"
33	#include "drivers/audio/AudioOutputDevice.h"
34
35	namespace LinuxSampler {
36
37	// just symbol prototyping
38	class Sampler;
39
40	/** @brief LinuxSampler sampler channel
41	*
42	* Encapsulates a channel of a specific sampler engine type, one
43	* connection to a MIDI input device and one connection to an audio
44	* output device. You cannot create an instance of this class on your
45	* own, you have to use the AddSamplerChannel() method of the Sampler
46	* object to create a new sampler channel.
47	*/
48	class SamplerChannel {
49	public:
50	/**
51	* Assign a sampler engine type to this sampler channel.
52	*
53	* @param EngineType - type of the engine to use
54	* @throws Exception - if \a EngineType is invalid
55	*/
56	void SetEngineType(String EngineType) throw (Exception);
57
58	/**
59	* Connect this sampler channel to an audio output device, that
60	* is an instance of an audio output driver. If this sampler
61	* channel was already connected to an audio output device, then
62	* the old connection will automatically be removed before.
63	*
64	* @param pDevice - audio output device to connect to
65	*/
66	void SetAudioOutputDevice(AudioOutputDevice* pDevice);
67
68	/**
69	* Connect this sampler channel to a MIDI input device.
70	*
71	* @param pDevice - MIDI input device to connect to
72	*/
73	void SetMidiInputDevice(MidiInputDevice *pDevice);
74
75	/**
76	* Connect this sampler channel to a MIDI input port.
77	*
78	* @param MidiPort - MIDI port to connect to
79	*/
80	void SetMidiInputPort(int MidiPort);
81
82	/**
83	* Define on which MIDI channel(s) this sampler channel should
84	* listen to. By default, that is after creation of a new
85	* sampler channel, the sampler channel will listen to all MIDI
86	* channels.
87	*
88	* @param MidiChannel - MIDI channel to listen
89	*/
90	void SetMidiInputChannel(midi_chan_t MidiChannel);
91
92	/**
93	* Connect this sampler channel to a MIDI input triplet.
94	*
95	* @param pDevice - MIDI input device to connect to
96	* @param iMidiPort - MIDI port to connect to
97	* @param MidiChannel - optional: MIDI channel on which the
98	* sampler channel should listen to
99	* (default: listen on all MIDI channels)
100	*/
101	void SetMidiInput(MidiInputDevice* pDevice, int iMidiPort, midi_chan_t MidiChannel = midi_chan_all);
102
103	/**
104	* Returns the EngineChannel object that was deployed on this
105	* sampler channel appropriate to the given sampler engine type.
106	*
107	* @returns pointer to engine or NULL if no engine deployed
108	*/
109	EngineChannel* GetEngineChannel();
110
111	/**
112	* Returns the MIDI input channel to which this sampler
113	* channel is currently connected to.
114	*
115	* @returns The MIDI input channel on which the sampler
116	* channel is listening to.
117	*/
118	midi_chan_t GetMidiInputChannel();
119
120	/**
121	* Returns the MIDI input port number to which this sampler
122	* channel is currently connected to.
123	*
124	* @returns MIDI input port number or -1 if not connected
125	*/
126	int GetMidiInputPort();
127
128	/**
129	* Returns the audio output device to which this sampler channel
130	* is currently connected to.
131	*
132	* @returns pointer to audio output device or NULL if not
133	* connected
134	*/
135	AudioOutputDevice* GetAudioOutputDevice();
136
137	/**
138	* Returns the MIDI input device to which this sampler channel
139	* is currently connected to.
140	*
141	* @returns pointer to MIDI input device or NULL if not
142	* connected
143	*/
144	MidiInputDevice* GetMidiInputDevice();
145
146	/**
147	* Returns the index number of this sampler channel within the
148	* Sampler instance.
149	*/
150	uint Index();
151
152	protected:
153	SamplerChannel(Sampler* pS);
154	virtual ~SamplerChannel();
155
156	/** Getting MIDI input device port given its index number. */
157	MidiInputPort* __GetMidiInputDevicePort(int iMidiPort);
158
159	Sampler* pSampler;
160	EngineChannel* pEngineChannel;
161	AudioOutputDevice* pAudioOutputDevice;
162	MidiInputDevice* pMidiInputDevice;
163	int iIndex;
164
165	friend class Sampler;
166	private:
167	int iMidiPort; ///< Don't access directly, read GetMidiInputPort() instead !
168	midi_chan_t midiChannel; ///< Don't access directly, read GetMidiInputChannel() instead !
169	};
170
171	/** @brief LinuxSampler main class
172	*
173	* This is the toplevel class for a LinuxSampler instance.
174	*
175	* LinuxSampler can have arbitrary numbers of sampler channels. Each
176	* sampler channel can individually be deployed with it's own sampler
177	* engine, connected to an arbitrary MIDI input device and connected to
178	* an arbitrary audio output device. Here an example setup:
179	* @code
180	* S.Channel MIDI in S.Engine Audio out
181	* -------------------------------------------------------------------
182	* 0 Alsa -> gig::Engine -> Jack
183	* 1 VSTi -> Akai::Engine -> VSTi
184	* 2 Jack -> DLS::Engine -> Jack
185	* 3 Jack -> SF::Engine -> Alsa
186	*
187	* ... (and so on) ...
188	* @endcode
189	*
190	* Note that not all audio and MIDI backends and sampler engines listed
191	* in the example above might already been implemented!
192	*
193	* As you can see in the example setup, LinuxSampler is capable to use
194	* several, different audio output and MIDI input systems
195	* simultaniously at the same time. Here the example setup shown in the
196	* aspect of MIDI input and audio output devices / drivers:
197	* @code
198	* ######################### #########################
199	* # AudioOutputDeviceJack # # AudioOutputDeviceVSTi #
200	* ######################### #########################
201	* ^ ^ ^
202	* /------------>\|Sampler Channel 0\|-----/ \| \|
203	* \| /--------->\|Sampler Channel 1\|---------------------/
204	* \| \| /------>\|Sampler Channel 2\|---------/
205	* \| \| \| /--->\|Sampler Channel 3\|------------>#########################
206	* \| \| \| \| ... (and so on) ... # AudioOutputDeviceAlsa #
207	* \| \| \| \| #########################
208	* \| \| \| \-----------------------------------------------------\
209	* \| \| \--------------------------------------------\ \|
210	* \| \--------------------\ \| \|
211	* \| \| \| \|
212	* ####################### ####################### #######################
213	* # MidiInputDeviceAlsa # # MidiInputDeviceVSTi # # MidiInputDeviceJack #
214	* ####################### ####################### #######################
215	* @endcode
216	*
217	* As you can see in this example setup, one device (that is midi input
218	* driver / audio output driver) can be connected multiple times to
219	* different sampler channels.
220	*
221	* It's even possible to create multiple instances of the same driver, for
222	* example multiple instances of the Alsa output driver to use multiple
223	* sound cards at the same time, or multiple instances of the JACK audio
224	* output driver to leverage SMP systems or boxes with several hard discs.
225	*/
226	class Sampler {
227	public:
228	/**
229	* Constructor. Create a LinuxSampler instance.
230	*/
231	Sampler();
232
233	/**
234	* Destructor.
235	*/
236	virtual ~Sampler();
237
238	/**
239	* Returns the number of sampler channels currently allocated.
240	*/
241	uint SamplerChannels();
242
243	/**
244	* Create and add a new sampler channel to this Sampler
245	* instance. For race condition reasons the new channel will use
246	* an index past the last already existing sampler channel
247	* index (in case the index limit was not reached yet, otherwise
248	* a free index starting from 0 is searched).
249	*
250	* @returns pointer to new sampler channel
251	*/
252	SamplerChannel* AddSamplerChannel();
253
254	/**
255	* Returns the sampler channel of the given sampler channel
256	* index.
257	*
258	* @returns pointer to sought sampler channel
259	*/
260	SamplerChannel* GetSamplerChannel(uint uiSamplerChannel);
261
262	/**
263	* Returns all created sampler channels.
264	*/
265	std::map<uint, SamplerChannel*> GetSamplerChannels();
266
267	/**
268	* Destroy and remove the given sampler channel from this
269	* Sampler instance.
270	*
271	* @param pSamplerChannel - pointer to sampler channel to remove
272	*/
273	void RemoveSamplerChannel(SamplerChannel* pSamplerChannel);
274
275	/**
276	* Destroy and remove the given sampler channel from this
277	* Sampler instance.
278	*
279	* @param uiSamplerChannel - index of the sampler channel to
280	* remove
281	*/
282	void RemoveSamplerChannel(uint uiSamplerChannel);
283
284	/**
285	* Returns the names of all available audio output drivers.
286	*/
287	std::vector<String> AvailableAudioOutputDrivers();
288
289	/**
290	* Create an audio output device.
291	*
292	* @param AudioDriver - name of the audio driver
293	* @param Parameters - eventually needed driver parameters to
294	* create the device
295	* @returns pointer to created audio output device
296	* @throws Exception if device could not be created
297	*/
298	AudioOutputDevice* CreateAudioOutputDevice(String AudioDriver, std::map<String,String> Parameters) throw (Exception);
299
300	/**
301	* Create a midi input device.
302	*
303	* @param MidiDriver - name of the midi driver
304	* @param Parameters - eventually needed driver parameters to
305	* create the device
306	* @returns pointer to created midi input device
307	* @throws Exception if device could not be created
308	*/
309	MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (Exception);
310
311	/**
312	* Returns the number of all created audio output devices.
313	*/
314	uint AudioOutputDevices();
315
316	/**
317	* Returns the number of all created MIDI input devices.
318	*/
319	uint MidiInputDevices();
320
321	/**
322	* Returns all created audio output devices.
323	*/
324	std::map<uint, AudioOutputDevice*> GetAudioOutputDevices();
325
326	/**
327	* Returns all created MIDI input devices.
328	*/
329	std::map<uint, MidiInputDevice*> GetMidiInputDevices();
330
331	/**
332	* Destroy the given audio output device and takes care if there
333	* are still sampler angines connected to this device, etc.
334	*
335	* @throws Exception if sampler channels are still
336	* connected to the device
337	*/
338	void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (Exception);
339
340	/**
341	* Destroy the given MIDI input device and takes care if there
342	* are still sampler angines connected to this device, etc.
343	*
344	* @throws Exception if sampler channels are still
345	* connected to the device
346	*/
347	void DestroyMidiInputDevice(MidiInputDevice* pDevice) throw (Exception);
348
349	/**
350	* Gets the current number of all active voices.
351	* @returns The current number of all active voices.
352	*/
353	int GetVoiceCount();
354
355	/**
356	* Reset the whole sampler. Destroy all engines, sampler
357	* channels, MIDI input devices and audio output devices.
358	*/
359	void Reset();
360
361	protected:
362	typedef std::map<uint, AudioOutputDevice*> AudioOutputDeviceMap;
363	typedef std::map<uint, MidiInputDevice*> MidiInputDeviceMap;
364	typedef std::map<uint, SamplerChannel*> SamplerChannelMap;
365
366	SamplerChannelMap mSamplerChannels; ///< contains all created sampler channels
367	AudioOutputDeviceMap mAudioOutputDevices; ///< contains all created audio output devices
368	MidiInputDeviceMap mMidiInputDevices; ///< contains all created MIDI input devices
369
370	friend class SamplerChannel;
371	};
372	}
373
374	#endif // __LS_SAMPLER_H__