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 "mididriver/MidiInputDevice.h"
#include "audiodriver/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 (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(MidiInputDevice::type_t MidiType, MidiInputDevice::midi_chan_t MidiChannel = MidiInputDevice::midi_chan_all); // TODO: 'MidiType' type to be changed to 'MidiInputDevice*'

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

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

            /**
             * 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 of the given type.
             *
             * @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);

            uint AudioOutputDevices();

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

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

            /**
             * 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(MidiInputDevice::type_t MidiType); //TODO: to be changed to 'MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (LinuxSamplerException);'

            /**
             * 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(MidiInputDevice::type_t MidiType);

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

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

            template<class T> inline String ToString(T o) {
                std::stringstream ss;
                ss << o;
                return ss.str();
            }

            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 "mididriver/MidiInputDevice.h"
32	#include "audiodriver/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 (that
71	* is MIDI input driver) of the given type. If the MIDI input
72	* driver for the desired MIDI input system is not yet created,
73	* then it will be created automatically, but with default
74	* settings though. If this sampler channel was already
75	* connected to a MIDI input device, then the old connection
76	* will automatically be removed before.
77	*
78	* @param MidiType - MIDI input system to connect to
79	* @param MidiChannel - optional: MIDI channel on which the
80	* sampler channel should listen to
81	* (default: listen on all MIDI channels)
82	*/
83	void SetMidiInputDevice(MidiInputDevice::type_t MidiType, MidiInputDevice::midi_chan_t MidiChannel = MidiInputDevice::midi_chan_all); // TODO: 'MidiType' type to be changed to 'MidiInputDevice*'
84
85	/**
86	* Returns the engine that was deployed on this sampler channel.
87	*
88	* @returns pointer to engine or NULL if no engine deployed
89	*/
90	Engine* GetEngine();
91
92	/**
93	* Returns the MIDI input device to which this sampler channel
94	* is currently connected to.
95	*
96	* @returns pointer to MIDI input device or NULL if not
97	* connected
98	*/
99	MidiInputDevice* GetMidiInputDevice();
100
101	/**
102	* Returns the audio output device to which this sampler channel
103	* is currently connected to.
104	*
105	* @returns pointer to audio output device or NULL if not
106	* connected
107	*/
108	AudioOutputDevice* GetAudioOutputDevice();
109
110	/**
111	* Returns the index number of this sampler channel within the
112	* Sampler instance.
113	*/
114	uint Index();
115
116	protected:
117	SamplerChannel(Sampler* pS);
118	~SamplerChannel();
119
120	Sampler* pSampler;
121	Engine* pEngine;
122	MidiInputDevice* pMidiInputDevice;
123	AudioOutputDevice* pAudioOutputDevice;
124	int iIndex;
125
126	friend class Sampler;
127	};
128
129	/** LinuxSampler main class
130	*
131	* This is the toplevel class for a LinuxSampler instance.
132	*
133	* LinuxSampler can have arbitrary numbers of sampler channels. Each
134	* sampler channel can individually be deployed with it's own sampler
135	* engine, connected to an arbitrary MIDI input device and connected to
136	* an arbitrary audio output device. Here an example setup:
137	*
138	* S.Channel. MIDI in S.Engine Audio out
139	* -------------------------------------------------------------------
140	* 0 Alsa -> gig::Engine -> Jack
141	* 1 VSTi -> Akai::Engine -> VSTi
142	* 2 Jack -> DLS::Engine -> Jack
143	* 3 Jack -> SF::Engine -> Alsa
144	*
145	* ... (and so on) ...
146	*
147	* Note that not all audio and MIDI backends and sampler engines listed
148	* in the example above are already implemented!
149	*
150	* As you can see in the example setup, LinuxSampler is capable to use
151	* several, different audio output and MIDI input systems
152	* simultaniously at the same time. Here the example setup shown in the
153	* ascpect of MIDI input and audio output devices / drivers:
154	*
155	* ######################### #########################
156	* # AudioOutputDeviceJack # # AudioOutputDeviceVSTi #
157	* ######################### #########################
158	* ^ ^ ^
159	* /------------>\|Sampler Channel 0\|-----/ \| \|
160	* \| /--------->\|Sampler Channel 1\|---------------------/
161	* \| \| /---->\|Sampler Channel 2\|---------/
162	* \| \| \| /->\|Sampler Channel 3\|------------>#########################
163	* \| \| \| \| ... (and so on) ... # AudioOutputDeviceAlsa #
164	* \| \| \| \| #########################
165	* \| \| \| \----------------------------------------------------\
166	* \| \| \-------------------------------------------\ \|
167	* \| \--------------------\ \| \|
168	* \| \| \| \|
169	* ####################### ####################### #######################
170	* # MidiInputDeviceAlsa # # MidiInputDeviceVSTi # # MidiInputDeviceJack #
171	* ####################### ####################### #######################
172	*
173	* As you can see in this example setup, one device (that is midi input
174	* driver / audio output driver) can be connected multiple times to
175	* different sampler channels.
176	*/
177	class Sampler {
178	public:
179	/**
180	* Constructor. Create a LinuxSampler instance.
181	*/
182	Sampler();
183
184	/**
185	* Destructor.
186	*/
187	~Sampler();
188
189	/**
190	* Returns the number of sampler channels currently allocated.
191	*/
192	uint SamplerChannels();
193
194	/**
195	* Create and add a new sampler channel to this Sampler instance.
196	*
197	* @returns pointer to new sampler channel
198	*/
199	SamplerChannel* AddSamplerChannel();
200
201	/**
202	* Returns the sampler channel of the given sampler channel
203	* index.
204	*
205	* @returns pointer to sought sampler channel
206	*/
207	SamplerChannel* GetSamplerChannel(uint uiSamplerChannel);
208
209	/**
210	* Destroy and remove the given sampler channel from this
211	* Sampler instance.
212	*
213	* @param pSamplerChannel - pointer to sampler channel to remove
214	*/
215	void RemoveSamplerChannel(SamplerChannel* pSamplerChannel);
216
217	/**
218	* Destroy and remove the given sampler channel from this
219	* Sampler instance.
220	*
221	* @param uiSamplerChannel - index of the sampler channel to
222	* remove
223	*/
224	void RemoveSamplerChannel(uint uiSamplerChannel);
225
226	std::vector<String> AvailableAudioOutputDrivers();
227
228	/**
229	* Create an audio output device of the given type.
230	*
231	* @param AudioDriver - name of the audio driver
232	* @param Parameters - eventually needed driver parameters to
233	* create the device
234	* @returns pointer to created audio output device
235	* @throws LinuxSamplerException if device could not be created
236	*/
237	AudioOutputDevice* CreateAudioOutputDevice(String AudioDriver, std::map<String,String> Parameters) throw (LinuxSamplerException);
238
239	uint AudioOutputDevices();
240
241	std::map<uint, AudioOutputDevice*> GetAudioOutputDevices();
242
243	void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (LinuxSamplerException);
244
245	/**
246	* Create a MIDI input device of the given type.
247	*
248	* @param MidiType - desired MIDI input system to use
249	* @returns pointer to created MIDI input device
250	*/
251	MidiInputDevice* CreateMidiInputDevice(MidiInputDevice::type_t MidiType); //TODO: to be changed to 'MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (LinuxSamplerException);'
252
253	/**
254	* Returns the MIDI input device of the given type.
255	*
256	* @param MidiType - desired MIDI input system to use
257	* @returns pointer to MIDI input device or NULL if device of
258	* desired type is not yet created
259	*/
260	MidiInputDevice* GetMidiInputDevice(MidiInputDevice::type_t MidiType);
261
262	protected:
263	typedef std::map<uint, AudioOutputDevice*> AudioOutputDeviceMap;
264	typedef std::map<MidiInputDevice::type_t, MidiInputDevice*> MidiInputDeviceMap;
265
266	std::vector<SamplerChannel*> vSamplerChannels; ///< contains all created sampler channels
267	AudioOutputDeviceMap mAudioOutputDevices; ///< contains all created audio output devices
268	MidiInputDeviceMap MidiInputDevices;
269
270	template<class T> inline String ToString(T o) {
271	std::stringstream ss;
272	ss << o;
273	return ss.str();
274	}
275
276	friend class SamplerChannel;
277	};
278	}
279
280	#endif // __LS_SAMPLER_H__