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.
             *
             * @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);

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

            uint AudioOutputDevices();
            uint MidiInputDevices();

            std::map<uint, AudioOutputDevice*> GetAudioOutputDevices();

            std::map<uint, MidiInputDevice*> GetMidiInputDevices();

            void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (LinuxSamplerException);
            void DestroyMidiInputDevice(MidiInputDevice* pDevice) throw (LinuxSamplerException);

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

            std::vector<SamplerChannel*> vSamplerChannels;   ///< contains all created sampler channels
            AudioOutputDeviceMap         mAudioOutputDevices; ///< contains all created audio output devices
            MidiInputDeviceMap           mMidiInputDevices;

            friend class SamplerChannel;
    };
}

#endif // __LS_SAMPLER_H__
1	schoenebeck	53	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5	schoenebeck	61	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	schoenebeck	53	* *
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	schoenebeck	203	#include "drivers/midi/MidiInputDevice.h"
32			#include "drivers/audio/AudioOutputDevice.h"
33	schoenebeck	53
34			namespace LinuxSampler {
35
36			// just symbol prototyping
37			class Sampler;
38
39	schoenebeck	57	/** 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	schoenebeck	123	* create an instance of this class on your own, you have to use the
44	schoenebeck	57	* AddSamplerChannel() method of the Sampler object to create a new
45			* sampler channel.
46			*/
47	schoenebeck	53	class SamplerChannel {
48			public:
49	schoenebeck	57	/**
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	schoenebeck	123	void LoadEngine(Engine::type_t EngineType); // TODO: to be changed to 'void LoadEngine(String EngineType) throws (LinuxSamplerException);'
58	schoenebeck	57
59			/**
60	schoenebeck	123	* 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	schoenebeck	57	*
65	schoenebeck	123	* @param pDevice - audio output device to connect to
66	schoenebeck	57	*/
67	schoenebeck	123	void SetAudioOutputDevice(AudioOutputDevice* pDevice);
68	schoenebeck	57
69			/**
70	capela	159	* Connect this sampler channel to and MIDI input device.
71	schoenebeck	57	*
72	capela	159	* @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	schoenebeck	57	* @param MidiChannel - optional: MIDI channel on which the
96			* sampler channel should listen to
97			* (default: listen on all MIDI channels)
98			*/
99	capela	159	void SetMidiInput(MidiInputDevice* pDevice, int MidiPort, MidiInputDevice::MidiInputPort::midi_chan_t MidiChannel = MidiInputDevice::MidiInputPort::midi_chan_all);
100	schoenebeck	57
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	capela	159	* Returns the MIDI input channel to which this sampler
110			* channel is currently connected to.
111	schoenebeck	57	*
112	capela	159	* @returns The MIDI input channel on which the sampler
113			* channel is listening to.
114	schoenebeck	57	*/
115	capela	159	MidiInputDevice::MidiInputPort::midi_chan_t GetMidiInputChannel();
116	schoenebeck	57
117			/**
118	capela	159	* 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	schoenebeck	57	* 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	capela	159	* Returns the MIDI input device to which this sampler channel
136	senkov	155	* is currently connected to.
137			*
138	capela	159	* @returns pointer to MIDI input device or NULL if not
139	senkov	155	* connected
140			*/
141			MidiInputDevice* GetMidiInputDevice();
142
143			/**
144	schoenebeck	57	* Returns the index number of this sampler channel within the
145			* Sampler instance.
146			*/
147			uint Index();
148
149			protected:
150	schoenebeck	53	SamplerChannel(Sampler* pS);
151			~SamplerChannel();
152	schoenebeck	57
153	capela	159	/** Getting MIDI input device port given its index number. */
154			MidiInputDevice::MidiInputPort* GetMidiInputDevicePort(int MidiPort);
155	schoenebeck	203
156	schoenebeck	53	Sampler* pSampler;
157			Engine* pEngine;
158			AudioOutputDevice* pAudioOutputDevice;
159	capela	159	MidiInputDevice* pMidiInputDevice;
160			int midiPort;
161			MidiInputDevice::MidiInputPort::midi_chan_t midiChannel;
162	schoenebeck	53	int iIndex;
163	schoenebeck	57
164			friend class Sampler;
165	schoenebeck	53	};
166
167	schoenebeck	57	/** 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	schoenebeck	53	class Sampler {
216			public:
217	schoenebeck	57	/**
218			* Constructor. Create a LinuxSampler instance.
219			*/
220	schoenebeck	53	Sampler();
221	schoenebeck	57
222			/**
223			* Destructor.
224			*/
225	schoenebeck	53	~Sampler();
226	schoenebeck	57
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 instance.
234			*
235			* @returns pointer to new sampler channel
236			*/
237			SamplerChannel* AddSamplerChannel();
238
239			/**
240			* Returns the sampler channel of the given sampler channel
241			* index.
242			*
243			* @returns pointer to sought sampler channel
244			*/
245			SamplerChannel* GetSamplerChannel(uint uiSamplerChannel);
246
247			/**
248			* Destroy and remove the given sampler channel from this
249			* Sampler instance.
250			*
251			* @param pSamplerChannel - pointer to sampler channel to remove
252			*/
253			void RemoveSamplerChannel(SamplerChannel* pSamplerChannel);
254
255			/**
256			* Destroy and remove the given sampler channel from this
257			* Sampler instance.
258			*
259			* @param uiSamplerChannel - index of the sampler channel to
260			* remove
261			*/
262			void RemoveSamplerChannel(uint uiSamplerChannel);
263
264	schoenebeck	123	std::vector<String> AvailableAudioOutputDrivers();
265
266	schoenebeck	57	/**
267	senkov	155	* Create an audio output device.
268	schoenebeck	57	*
269	schoenebeck	123	* @param AudioDriver - name of the audio driver
270			* @param Parameters - eventually needed driver parameters to
271			* create the device
272	schoenebeck	57	* @returns pointer to created audio output device
273	schoenebeck	123	* @throws LinuxSamplerException if device could not be created
274	schoenebeck	57	*/
275	schoenebeck	123	AudioOutputDevice* CreateAudioOutputDevice(String AudioDriver, std::map<String,String> Parameters) throw (LinuxSamplerException);
276	schoenebeck	57
277	senkov	155	/**
278			* Create a midi input device.
279			*
280			* @param MidiDriver - name of the midi driver
281			* @param Parameters - eventually needed driver parameters to
282			* create the device
283			* @returns pointer to created midi input device
284			* @throws LinuxSamplerException if device could not be created
285			*/
286			MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (LinuxSamplerException);
287
288	schoenebeck	123	uint AudioOutputDevices();
289	senkov	155	uint MidiInputDevices();
290	schoenebeck	57
291	schoenebeck	123	std::map<uint, AudioOutputDevice*> GetAudioOutputDevices();
292
293	senkov	155	std::map<uint, MidiInputDevice*> GetMidiInputDevices();
294
295	schoenebeck	123	void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (LinuxSamplerException);
296	senkov	155	void DestroyMidiInputDevice(MidiInputDevice* pDevice) throw (LinuxSamplerException);
297	schoenebeck	123
298	schoenebeck	53	protected:
299	schoenebeck	123	typedef std::map<uint, AudioOutputDevice*> AudioOutputDeviceMap;
300	senkov	155	typedef std::map<uint, MidiInputDevice*> MidiInputDeviceMap;
301	schoenebeck	53
302			std::vector<SamplerChannel*> vSamplerChannels; ///< contains all created sampler channels
303	schoenebeck	123	AudioOutputDeviceMap mAudioOutputDevices; ///< contains all created audio output devices
304	senkov	155	MidiInputDeviceMap mMidiInputDevices;
305	schoenebeck	53
306			friend class SamplerChannel;
307			};
308			}
309
310			#endif // __LS_SAMPLER_H__