trunk/src/Sampler.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003 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 {

    /**
     * Which sampler engine to be used.
     */
    enum engine_type_t {
        engine_type_gig
    };

    /**
     * Which audio output system to be used.
     */
    enum audio_output_type_t {
        audio_output_type_alsa,
        audio_output_type_jack
    };

    /**
     * Which MIDI input system to be used.
     */
    enum midi_input_type_t {
        midi_input_type_alsa
    };

    // just symbol prototyping
    class Sampler;

    /** LinuxSampler sampler channel
     *
     * Encapsulates one sampler engine, one connection to a MIDI input
     * device and one connection to an audio output device. You cannot
     * create an instance of this class on you own, you have to use the
     * AddSamplerChannel() method of the Sampler object to create a new
     * sampler channel.
     */
    class SamplerChannel {
        public:
            /**
             * Deploy a sampler engine of the given type for this sampler
             * channnel. If there was already a sampler engine deployed on
             * this sampler channel, then the old engine will automatically
             * be destroyed.
             *
             * @param EngineType - type of the engine to deploy
             */
            void LoadEngine(engine_type_t EngineType);

            /**
             * Connect this sampler channel to an audio output device (that
             * is audio output driver) of the given type. If the audio
             * output for the desired audio output system is not yet
             * created, then it will be created automatically, but with
             * default settings though. If this sampler channel was already
             * connected to an audio output device, then the old connection
             * will automatically be removed before.
             *
             * @param AudioType - audio output system to connect to
             */
            void SetAudioOutputDevice(audio_output_type_t AudioType);

            /**
             * Connect this sampler channel to and MIDI input device (that
             * is MIDI input driver) of the given type. If the MIDI input
             * driver for the desired MIDI input system is not yet created,
             * then it will be created automatically, but with default
             * settings though. If this sampler channel was already
             * connected to a MIDI input device, then the old connection
             * will automatically be removed before.
             *
             * @param MidiType    - MIDI input system to connect to
             * @param MidiChannel - optional: MIDI channel on which the
             *                      sampler channel should listen to
             *                      (default: listen on all MIDI channels)
             */
            void SetMidiInputDevice(midi_input_type_t MidiType, MidiInputDevice::midi_chan_t MidiChannel = MidiInputDevice::midi_chan_all);

            /**
             * Returns the engine that was deployed on this sampler channel.
             *
             * @returns  pointer to engine or NULL if no engine deployed
             */
            Engine* GetEngine();

            /**
             * Returns the MIDI input device to which this sampler channel
             * is currently connected to.
             *
             * @returns  pointer to MIDI input device or NULL if not
             *           connected
             */
            MidiInputDevice* GetMidiInputDevice();

            /**
             * Returns the audio output device to which this sampler channel
             * is currently connected to.
             *
             * @returns  pointer to audio output device or NULL if not
             *           connected
             */
            AudioOutputDevice* GetAudioOutputDevice();

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

            /**
             * Create an audio output device of the given type.
             *
             * @param AudioType - desired audio output system to use
             * @returns  pointer to created audio output device
             */
            AudioOutputDevice* CreateAudioOutputDevice(audio_output_type_t AudioType);

            /**
             * Returns the audio output device of the given type.
             *
             * @param AudioType - desired audio output system to use
             * @returns  pointer to audio output device or NULL if device of
             *           desired type is not yet created
             */
            AudioOutputDevice* GetAudioOutputDevice(audio_output_type_t AudioType);

            /**
             * Create a MIDI input device of the given type.
             *
             * @param MidiType - desired MIDI input system to use
             * @returns  pointer to created MIDI input device
             */
            MidiInputDevice* CreateMidiInputDevice(midi_input_type_t MidiType);

            /**
             * Returns the MIDI input device of the given type.
             *
             * @param MidiType - desired MIDI input system to use
             * @returns  pointer to MIDI input device or NULL if device of
             *           desired type is not yet created
             */
            MidiInputDevice* GetMidiInputDevice(midi_input_type_t MidiType);

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

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

            friend class SamplerChannel;
    };
}

#endif // __LS_SAMPLER_H__
1	schoenebeck	53	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5			* Copyright (C) 2003 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			/**
37			* Which sampler engine to be used.
38			*/
39			enum engine_type_t {
40			engine_type_gig
41			};
42
43			/**
44			* Which audio output system to be used.
45			*/
46			enum audio_output_type_t {
47			audio_output_type_alsa,
48			audio_output_type_jack
49			};
50
51			/**
52			* Which MIDI input system to be used.
53			*/
54			enum midi_input_type_t {
55			midi_input_type_alsa
56			};
57
58			// just symbol prototyping
59			class Sampler;
60
61	schoenebeck	57	/** LinuxSampler sampler channel
62			*
63			* Encapsulates one sampler engine, one connection to a MIDI input
64			* device and one connection to an audio output device. You cannot
65			* create an instance of this class on you own, you have to use the
66			* AddSamplerChannel() method of the Sampler object to create a new
67			* sampler channel.
68			*/
69	schoenebeck	53	class SamplerChannel {
70			public:
71	schoenebeck	57	/**
72			* Deploy a sampler engine of the given type for this sampler
73			* channnel. If there was already a sampler engine deployed on
74			* this sampler channel, then the old engine will automatically
75			* be destroyed.
76			*
77			* @param EngineType - type of the engine to deploy
78			*/
79			void LoadEngine(engine_type_t EngineType);
80
81			/**
82			* Connect this sampler channel to an audio output device (that
83			* is audio output driver) of the given type. If the audio
84			* output for the desired audio output system is not yet
85			* created, then it will be created automatically, but with
86			* default settings though. If this sampler channel was already
87			* connected to an audio output device, then the old connection
88			* will automatically be removed before.
89			*
90			* @param AudioType - audio output system to connect to
91			*/
92			void SetAudioOutputDevice(audio_output_type_t AudioType);
93
94			/**
95			* Connect this sampler channel to and MIDI input device (that
96			* is MIDI input driver) of the given type. If the MIDI input
97			* driver for the desired MIDI input system is not yet created,
98			* then it will be created automatically, but with default
99			* settings though. If this sampler channel was already
100			* connected to a MIDI input device, then the old connection
101			* will automatically be removed before.
102			*
103			* @param MidiType - MIDI input system to connect to
104			* @param MidiChannel - optional: MIDI channel on which the
105			* sampler channel should listen to
106			* (default: listen on all MIDI channels)
107			*/
108			void SetMidiInputDevice(midi_input_type_t MidiType, MidiInputDevice::midi_chan_t MidiChannel = MidiInputDevice::midi_chan_all);
109
110			/**
111			* Returns the engine that was deployed on this sampler channel.
112			*
113			* @returns pointer to engine or NULL if no engine deployed
114			*/
115			Engine* GetEngine();
116
117			/**
118			* Returns the MIDI input device to which this sampler channel
119			* is currently connected to.
120			*
121			* @returns pointer to MIDI input device or NULL if not
122			* connected
123			*/
124			MidiInputDevice* GetMidiInputDevice();
125
126			/**
127			* Returns the audio output device to which this sampler channel
128			* is currently connected to.
129			*
130			* @returns pointer to audio output device or NULL if not
131			* connected
132			*/
133			AudioOutputDevice* GetAudioOutputDevice();
134
135			/**
136			* Returns the index number of this sampler channel within the
137			* Sampler instance.
138			*/
139			uint Index();
140
141			protected:
142	schoenebeck	53	SamplerChannel(Sampler* pS);
143			~SamplerChannel();
144	schoenebeck	57
145	schoenebeck	53	Sampler* pSampler;
146			Engine* pEngine;
147			MidiInputDevice* pMidiInputDevice;
148			AudioOutputDevice* pAudioOutputDevice;
149			int iIndex;
150	schoenebeck	57
151			friend class Sampler;
152	schoenebeck	53	};
153
154	schoenebeck	57	/** LinuxSampler main class
155			*
156			* This is the toplevel class for a LinuxSampler instance.
157			*
158			* LinuxSampler can have arbitrary numbers of sampler channels. Each
159			* sampler channel can individually be deployed with it's own sampler
160			* engine, connected to an arbitrary MIDI input device and connected to
161			* an arbitrary audio output device. Here an example setup:
162			*
163			* S.Channel. MIDI in S.Engine Audio out
164			* -------------------------------------------------------------------
165			* 0 Alsa -> gig::Engine -> Jack
166			* 1 VSTi -> Akai::Engine -> VSTi
167			* 2 Jack -> DLS::Engine -> Jack
168			* 3 Jack -> SF::Engine -> Alsa
169			*
170			* ... (and so on) ...
171			*
172			* Note that not all audio and MIDI backends and sampler engines listed
173			* in the example above are already implemented!
174			*
175			* As you can see in the example setup, LinuxSampler is capable to use
176			* several, different audio output and MIDI input systems
177			* simultaniously at the same time. Here the example setup shown in the
178			* ascpect of MIDI input and audio output devices / drivers:
179			*
180			* ######################### #########################
181			* # AudioOutputDeviceJack # # AudioOutputDeviceVSTi #
182			* ######################### #########################
183			* ^ ^ ^
184			* /------------>\|Sampler Channel 0\|-----/ \| \|
185			* \| /--------->\|Sampler Channel 1\|---------------------/
186			* \| \| /---->\|Sampler Channel 2\|---------/
187			* \| \| \| /->\|Sampler Channel 3\|------------>#########################
188			* \| \| \| \| ... (and so on) ... # AudioOutputDeviceAlsa #
189			* \| \| \| \| #########################
190			* \| \| \| \----------------------------------------------------\
191			* \| \| \-------------------------------------------\ \|
192			* \| \--------------------\ \| \|
193			* \| \| \| \|
194			* ####################### ####################### #######################
195			* # MidiInputDeviceAlsa # # MidiInputDeviceVSTi # # MidiInputDeviceJack #
196			* ####################### ####################### #######################
197			*
198			* As you can see in this example setup, one device (that is midi input
199			* driver / audio output driver) can be connected multiple times to
200			* different sampler channels.
201			*/
202	schoenebeck	53	class Sampler {
203			public:
204	schoenebeck	57	/**
205			* Constructor. Create a LinuxSampler instance.
206			*/
207	schoenebeck	53	Sampler();
208	schoenebeck	57
209			/**
210			* Destructor.
211			*/
212	schoenebeck	53	~Sampler();
213	schoenebeck	57
214			/**
215			* Returns the number of sampler channels currently allocated.
216			*/
217			uint SamplerChannels();
218
219			/**
220			* Create and add a new sampler channel to this Sampler instance.
221			*
222			* @returns pointer to new sampler channel
223			*/
224			SamplerChannel* AddSamplerChannel();
225
226			/**
227			* Returns the sampler channel of the given sampler channel
228			* index.
229			*
230			* @returns pointer to sought sampler channel
231			*/
232			SamplerChannel* GetSamplerChannel(uint uiSamplerChannel);
233
234			/**
235			* Destroy and remove the given sampler channel from this
236			* Sampler instance.
237			*
238			* @param pSamplerChannel - pointer to sampler channel to remove
239			*/
240			void RemoveSamplerChannel(SamplerChannel* pSamplerChannel);
241
242			/**
243			* Destroy and remove the given sampler channel from this
244			* Sampler instance.
245			*
246			* @param uiSamplerChannel - index of the sampler channel to
247			* remove
248			*/
249			void RemoveSamplerChannel(uint uiSamplerChannel);
250
251			/**
252			* Create an audio output device of the given type.
253			*
254			* @param AudioType - desired audio output system to use
255			* @returns pointer to created audio output device
256			*/
257	schoenebeck	53	AudioOutputDevice* CreateAudioOutputDevice(audio_output_type_t AudioType);
258	schoenebeck	57
259			/**
260			* Returns the audio output device of the given type.
261			*
262			* @param AudioType - desired audio output system to use
263			* @returns pointer to audio output device or NULL if device of
264			* desired type is not yet created
265			*/
266	schoenebeck	53	AudioOutputDevice* GetAudioOutputDevice(audio_output_type_t AudioType);
267	schoenebeck	57
268			/**
269			* Create a MIDI input device of the given type.
270			*
271			* @param MidiType - desired MIDI input system to use
272			* @returns pointer to created MIDI input device
273			*/
274			MidiInputDevice* CreateMidiInputDevice(midi_input_type_t MidiType);
275
276			/**
277			* Returns the MIDI input device of the given type.
278			*
279			* @param MidiType - desired MIDI input system to use
280			* @returns pointer to MIDI input device or NULL if device of
281			* desired type is not yet created
282			*/
283			MidiInputDevice* GetMidiInputDevice(midi_input_type_t MidiType);
284
285	schoenebeck	53	protected:
286			typedef std::map<audio_output_type_t, AudioOutputDevice*> AudioOutputDeviceMap;
287			typedef std::map<midi_input_type_t, MidiInputDevice*> MidiInputDeviceMap;
288
289			std::vector<SamplerChannel*> vSamplerChannels; ///< contains all created sampler channels
290			AudioOutputDeviceMap AudioOutputDevices; ///< contains all created audio output devices
291			MidiInputDeviceMap MidiInputDevices;
292
293			friend class SamplerChannel;
294			};
295			}
296
297			#endif // __LS_SAMPLER_H__