trunk/src/Sampler.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and 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/LinuxSamplerException.h"
#include "engines/common/Engine.h"
#include "drivers/midi/MidiInputDevice.h"
#include "drivers/audio/AudioOutputDevice.h"

namespace LinuxSampler {

    // 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 your own, you have to use the
     * AddSamplerChannel() method of the Sampler object to create a new
     * sampler channel.
     */
    class SamplerChannel {
        public:
            /**
             * 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); // TODO: to be changed to 'void LoadEngine(String EngineType) throws (LinuxSamplerException);'

            /**
             * 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 and MIDI input device.
             *
             * @param pDevice - MIDI input device to connect to
             */
            void SetMidiInputDevice(MidiInputDevice *pDevice);

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

            /**
             * Connect this sampler channel to and MIDI input channel.
             *
             * @param MidiChannel - MIDI channel to connect to
             */
            void SetMidiInputChannel(MidiInputDevice::MidiInputPort::midi_chan_t MidiChannel);

            /**
             * Connect this sampler channel to a MIDI input triplet.
             *
             * @param pDevice - MIDI input device to connect to
             * @param MidiPort - 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 MidiPort, MidiInputDevice::MidiInputPort::midi_chan_t MidiChannel = MidiInputDevice::MidiInputPort::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 channel to which this sampler
             * channel is currently connected to.
             *
             * @returns  The MIDI input channel on which the sampler
             *           channel is listening to.
             */
            MidiInputDevice::MidiInputPort::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);
           ~SamplerChannel();

            /** Getting MIDI input device port given its index number. */
            MidiInputDevice::MidiInputPort* GetMidiInputDevicePort(int MidiPort);

            Sampler*           pSampler;
            Engine*            pEngine;
            AudioOutputDevice* pAudioOutputDevice;
            MidiInputDevice*   pMidiInputDevice;
            int                midiPort;
            MidiInputDevice::MidiInputPort::midi_chan_t midiChannel;
            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();

            /**
             * 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 LinuxSamplerException  if device could not be created
             */
            AudioOutputDevice* CreateAudioOutputDevice(String AudioDriver, std::map<String,String> Parameters) throw (LinuxSamplerException);

            /**
             * 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 LinuxSamplerException  if device could not be created
             */
            MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (LinuxSamplerException);

            /**
             * 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 LinuxSamplerException  if sampler channels are still
             *                                connected to the device
             */
            void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (LinuxSamplerException);

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

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