/[svn]/linuxsampler/trunk/src/Sampler.h
ViewVC logotype

Contents of /linuxsampler/trunk/src/Sampler.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 900 - (show annotations) (download) (as text)
Wed Jul 5 17:53:22 2006 UTC (17 years, 9 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 16271 byte(s)
* src/Sampler.h, src/Sampler.cpp: allow 3rd party applications to
  retrieve available drivers and sampler engines
* src/linuxsampler.cpp: show available engines on startup (on the console)

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

  ViewVC Help
Powered by ViewVC