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

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1723 - (show annotations) (download) (as text)
Sun Apr 20 08:53:39 2008 UTC (16 years ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 26951 byte(s) 
* allow pan control of engine channels on C++ API level
* export denormals-are-zero mode feature to C++ API
1 /***************************************************************************
2 * *
3 * LinuxSampler - modular, streaming capable sampler *
4 * *
5 * Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6 * Copyright (C) 2005 - 2008 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 "EventListeners.h"
30 #include "common/global.h"
31 #include "common/Exception.h"
32 #include "engines/EngineChannel.h"
33 #include "drivers/midi/MidiInputDevice.h"
34 #include "drivers/audio/AudioOutputDevice.h"
35
36 namespace LinuxSampler {
37
38 // just symbol prototyping
39 class Sampler;
40
41 /** @brief LinuxSampler sampler channel
42 *
43 * Encapsulates a channel of a specific sampler engine type, one
44 * connection to a MIDI input device and one connection to an audio
45 * output device. You cannot create an instance of this class on your
46 * own, you have to use the AddSamplerChannel() method of the Sampler
47 * object to create a new sampler channel.
48 */
49 class SamplerChannel {
50 public:
51 /**
52 * Assign a sampler engine type to this sampler channel.
53 *
54 * @param EngineType - type of the engine to use
55 * @throws Exception - if \a EngineType is invalid
56 * @see Sampler::AvailableEngineTypes()
57 */
58 void SetEngineType(String EngineType) throw (Exception);
59
60 /**
61 * Connect this sampler channel to an audio output device, that
62 * is an instance of an audio output driver. If this sampler
63 * channel was already connected to an audio output device, then
64 * the old connection will automatically be removed before.
65 *
66 * @param pDevice - audio output device to connect to
67 */
68 void SetAudioOutputDevice(AudioOutputDevice* pDevice);
69
70 /**
71 * Connect this sampler channel to a MIDI input device.
72 *
73 * @param pDevice - MIDI input device to connect to
74 */
75 void SetMidiInputDevice(MidiInputDevice *pDevice);
76
77 /**
78 * Connect this sampler channel to a MIDI input port.
79 *
80 * @param MidiPort - MIDI port to connect to
81 */
82 void SetMidiInputPort(int MidiPort);
83
84 /**
85 * Define on which MIDI channel(s) this sampler channel should
86 * listen to. By default, that is after creation of a new
87 * sampler channel, the sampler channel will listen to all MIDI
88 * channels.
89 *
90 * @param MidiChannel - MIDI channel to listen
91 */
92 void SetMidiInputChannel(midi_chan_t MidiChannel);
93
94 /**
95 * Connect this sampler channel to a MIDI input triplet.
96 *
97 * @param pDevice - MIDI input device to connect to
98 * @param iMidiPort - MIDI port to connect to
99 * @param MidiChannel - optional: MIDI channel on which the
100 * sampler channel should listen to
101 * (default: listen on all MIDI channels)
102 */
103 void SetMidiInput(MidiInputDevice* pDevice, int iMidiPort, midi_chan_t MidiChannel = midi_chan_all);
104
105 /**
106 * Returns the EngineChannel object that was deployed on this
107 * sampler channel appropriate to the given sampler engine type.
108 *
109 * @returns pointer to engine or NULL if no engine deployed
110 */
111 EngineChannel* GetEngineChannel();
112
113 /**
114 * Returns the MIDI input channel to which this sampler
115 * channel is currently connected to.
116 *
117 * @returns The MIDI input channel on which the sampler
118 * channel is listening to.
119 */
120 midi_chan_t GetMidiInputChannel();
121
122 /**
123 * Returns the MIDI input port number to which this sampler
124 * channel is currently connected to.
125 *
126 * @returns MIDI input port number or -1 if not connected
127 */
128 int GetMidiInputPort();
129
130 /**
131 * Returns the audio output device to which this sampler channel
132 * is currently connected to.
133 *
134 * @returns pointer to audio output device or NULL if not
135 * connected
136 */
137 AudioOutputDevice* GetAudioOutputDevice();
138
139 /**
140 * Returns the MIDI input device to which this sampler channel
141 * is currently connected to.
142 *
143 * @returns pointer to MIDI input device or NULL if not
144 * connected
145 */
146 MidiInputDevice* GetMidiInputDevice();
147
148 /**
149 * Returns the index number of this sampler channel within the
150 * Sampler instance.
151 */
152 uint Index();
153
154 /**
155 * Registers the specified listener to be notified
156 * when the engine type of this sampler channel is changed.
157 */
158 void AddEngineChangeListener(EngineChangeListener* l);
159
160 /**
161 * Removes the specified listener.
162 */
163 void RemoveEngineChangeListener(EngineChangeListener* l);
164
165 /**
166 * Removes the specified listener.
167 */
168 void RemoveAllEngineChangeListeners();
169
170 /**
171 * Notifies listeners that the engine type of this sampler
172 * channel is going to be changed soon.
173 */
174 void fireEngineToBeChanged();
175
176 /**
177 * Notifies listeners that the engine
178 * type of this sampler channel is changed.
179 */
180 void fireEngineChanged();
181
182
183 protected:
184 SamplerChannel(Sampler* pS);
185 virtual ~SamplerChannel();
186
187 /** Getting MIDI input device port given its index number. */
188 MidiInputPort* __GetMidiInputDevicePort(int iMidiPort);
189
190 Sampler* pSampler;
191 EngineChannel* pEngineChannel;
192 AudioOutputDevice* pAudioOutputDevice;
193 MidiInputDevice* pMidiInputDevice;
194 int iIndex;
195
196 friend class Sampler;
197 private:
198 int iMidiPort; ///< Don't access directly, read GetMidiInputPort() instead !
199 midi_chan_t midiChannel; ///< Don't access directly, read GetMidiInputChannel() instead !
200 ListenerList<EngineChangeListener*> llEngineChangeListeners;
201 };
202
203 /** @brief LinuxSampler main class
204 *
205 * This is the toplevel class for a LinuxSampler instance.
206 *
207 * LinuxSampler can have arbitrary numbers of sampler channels. Each
208 * sampler channel can individually be deployed with it's own sampler
209 * engine, connected to an arbitrary MIDI input device and connected to
210 * an arbitrary audio output device. Here an example setup:
211 * @code
212 * S.Channel MIDI in S.Engine Audio out
213 * -------------------------------------------------------------------
214 * 0 Alsa -> gig::Engine -> Jack
215 * 1 VSTi -> Akai::Engine -> VSTi
216 * 2 Jack -> DLS::Engine -> Jack
217 * 3 Jack -> SF::Engine -> Alsa
218 *
219 * ... (and so on) ...
220 * @endcode
221 *
222 * Note that not all audio and MIDI backends and sampler engines listed
223 * in the example above might already been implemented!
224 *
225 * As you can see in the example setup, LinuxSampler is capable to use
226 * several, different audio output and MIDI input systems
227 * simultaniously at the same time. Here the example setup shown in the
228 * aspect of MIDI input and audio output devices / drivers:
229 * @code
230 * ######################### #########################
231 * # AudioOutputDeviceJack # # AudioOutputDeviceVSTi #
232 * ######################### #########################
233 * ^ ^ ^
234 * /------------>|Sampler Channel 0|-----/ | |
235 * | /--------->|Sampler Channel 1|---------------------/
236 * | | /------>|Sampler Channel 2|---------/
237 * | | | /--->|Sampler Channel 3|------------>#########################
238 * | | | | ... (and so on) ... # AudioOutputDeviceAlsa #
239 * | | | | #########################
240 * | | | \-----------------------------------------------------\
241 * | | \--------------------------------------------\ |
242 * | \--------------------\ | |
243 * | | | |
244 * ####################### ####################### #######################
245 * # MidiInputDeviceAlsa # # MidiInputDeviceVSTi # # MidiInputDeviceJack #
246 * ####################### ####################### #######################
247 * @endcode
248 *
249 * As you can see in this example setup, one device (that is midi input
250 * driver / audio output driver) can be connected multiple times to
251 * different sampler channels.
252 *
253 * It's even possible to create multiple instances of the same driver, for
254 * example multiple instances of the Alsa output driver to use multiple
255 * sound cards at the same time, or multiple instances of the JACK audio
256 * output driver to leverage SMP systems or boxes with several hard discs.
257 */
258 class Sampler {
259 public:
260 /**
261 * Constructor. Create a LinuxSampler instance.
262 */
263 Sampler();
264
265 /**
266 * Destructor.
267 */
268 virtual ~Sampler();
269
270 /**
271 * Returns the number of sampler channels currently allocated.
272 */
273 uint SamplerChannels();
274
275 /**
276 * Create and add a new sampler channel to this Sampler
277 * instance. For race condition reasons the new channel will use
278 * an index past the last already existing sampler channel
279 * index (in case the index limit was not reached yet, otherwise
280 * a free index starting from 0 is searched).
281 *
282 * @returns pointer to new sampler channel
283 */
284 SamplerChannel* AddSamplerChannel();
285
286 /**
287 * Returns the sampler channel of the given sampler channel
288 * index.
289 *
290 * @returns pointer to sought sampler channel
291 */
292 SamplerChannel* GetSamplerChannel(uint uiSamplerChannel);
293
294 /**
295 * Returns all created sampler channels.
296 */
297 std::map<uint, SamplerChannel*> GetSamplerChannels();
298
299 /**
300 * Destroy and remove the given sampler channel from this
301 * Sampler instance.
302 *
303 * @param pSamplerChannel - pointer to sampler channel to remove
304 */
305 void RemoveSamplerChannel(SamplerChannel* pSamplerChannel);
306
307 /**
308 * Destroy and remove the given sampler channel from this
309 * Sampler instance.
310 *
311 * @param uiSamplerChannel - index of the sampler channel to
312 * remove
313 */
314 void RemoveSamplerChannel(uint uiSamplerChannel);
315
316 /**
317 * Registers the specified listener to be notified
318 * when the number of sampler chanels is changed.
319 */
320 void AddChannelCountListener(ChannelCountListener* l);
321
322 /**
323 * Removes the specified listener.
324 */
325 void RemoveChannelCountListener(ChannelCountListener* l);
326
327 /**
328 * Registers the specified listener to be notified
329 * when the number of audio output devices is changed.
330 */
331 void AddAudioDeviceCountListener(AudioDeviceCountListener* l);
332
333 /**
334 * Removes the specified listener.
335 */
336 void RemoveAudioDeviceCountListener(AudioDeviceCountListener* l);
337
338
339 /**
340 * Registers the specified listener to be notified
341 * when the number of MIDI input devices is changed.
342 */
343 void AddMidiDeviceCountListener(MidiDeviceCountListener* l);
344
345 /**
346 * Removes the specified listener.
347 */
348 void RemoveMidiDeviceCountListener(MidiDeviceCountListener* l);
349
350 /**
351 * Registers the specified listener to be notified when the number
352 * of active voices in a particular sampler channel is changed.
353 */
354 void AddVoiceCountListener(VoiceCountListener* l);
355
356 /**
357 * Removes the specified listener.
358 */
359 void RemoveVoiceCountListener(VoiceCountListener* l);
360
361 /**
362 * Notifies listeners that the number of active voices
363 * on the specified sampler channel is changed.
364 * @param ChannelId The numerical ID of the sampler channel.
365 * @param NewCount The new number of active voices.
366 */
367 void fireVoiceCountChanged(int ChannelId, int NewCount);
368
369 /**
370 * Registers the specified listener to be notified when the number
371 * of active disk streams in a particular sampler channel is changed.
372 */
373 void AddStreamCountListener(StreamCountListener* l);
374
375 /**
376 * Removes the specified listener.
377 */
378 void RemoveStreamCountListener(StreamCountListener* l);
379
380 /**
381 * Notifies listeners that the number of active disk streams
382 * on the specified sampler channel is changed.
383 * @param ChannelId The numerical ID of the sampler channel.
384 * @param NewCount The new number of active disk streams.
385 */
386 void fireStreamCountChanged(int ChannelId, int NewCount);
387
388 /**
389 * Registers the specified listener to be
390 * notified when the fill state of the disk stream
391 * buffers on a specific sampler channel is changed.
392 */
393 void AddBufferFillListener(BufferFillListener* l);
394
395 /**
396 * Removes the specified listener.
397 */
398 void RemoveBufferFillListener(BufferFillListener* l);
399
400 /**
401 * Notifies listeners that the fill state of the disk stream
402 * buffers on the specified sampler channel is changed.
403 * @param ChannelId The numerical ID of the sampler channel.
404 * @param FillData The buffer fill data for the specified sampler channel.
405 */
406 void fireBufferFillChanged(int ChannelId, String FillData);
407
408 /**
409 * Registers the specified listener to be notified
410 * when total number of active voices is changed.
411 */
412 void AddTotalVoiceCountListener(TotalVoiceCountListener* l);
413
414 /**
415 * Removes the specified listener.
416 */
417 void RemoveTotalVoiceCountListener(TotalVoiceCountListener* l);
418
419 /**
420 * Notifies listeners that the total number of active voices is changed.
421 * @param NewCount The new number of active voices.
422 */
423 void fireTotalVoiceCountChanged(int NewCount);
424
425 void AddTotalStreamCountListener(TotalStreamCountListener* l);
426 void RemoveTotalStreamCountListener(TotalStreamCountListener* l);
427 void fireTotalStreamCountChanged(int NewCount);
428
429 /**
430 * Registers the specified listener to be notified when the number
431 * of effect sends on a particular sampler channel is changed.
432 */
433 void AddFxSendCountListener(FxSendCountListener* l);
434
435 /**
436 * Removes the specified listener.
437 */
438 void RemoveFxSendCountListener(FxSendCountListener* l);
439
440 /**
441 * Returns the names of all available audio output drivers.
442 */
443 std::vector<String> AvailableAudioOutputDrivers();
444
445 /**
446 * Returns the names of all available MIDI input drivers.
447 */
448 std::vector<String> AvailableMidiInputDrivers();
449
450 /**
451 * Returns the names of all available sampler engine types.
452 * @see SamplerChannel::SetEngineType()
453 */
454 std::vector<String> AvailableEngineTypes();
455
456 /**
457 * Create an audio output device.
458 *
459 * @param AudioDriver - name of the audio driver
460 * @param Parameters - eventually needed driver parameters to
461 * create the device
462 * @returns pointer to created audio output device
463 * @throws Exception if device could not be created
464 */
465 AudioOutputDevice* CreateAudioOutputDevice(String AudioDriver, std::map<String,String> Parameters) throw (Exception);
466
467 /**
468 * Create a midi input device.
469 *
470 * @param MidiDriver - name of the midi driver
471 * @param Parameters - eventually needed driver parameters to
472 * create the device
473 * @returns pointer to created midi input device
474 * @throws Exception if device could not be created
475 */
476 MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (Exception);
477
478 /**
479 * Returns the number of all created audio output devices.
480 */
481 uint AudioOutputDevices();
482
483 /**
484 * Returns the number of all created MIDI input devices.
485 */
486 uint MidiInputDevices();
487
488 /**
489 * Returns all created audio output devices.
490 */
491 std::map<uint, AudioOutputDevice*> GetAudioOutputDevices();
492
493 /**
494 * Returns all created MIDI input devices.
495 */
496 std::map<uint, MidiInputDevice*> GetMidiInputDevices();
497
498 /**
499 * Destroy the given audio output device and takes care if there
500 * are still sampler angines connected to this device, etc.
501 *
502 * @throws Exception if sampler channels are still
503 * connected to the device
504 */
505 void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (Exception);
506
507 /**
508 * Destroy the given MIDI input device and takes care if there
509 * are still sampler angines connected to this device, etc.
510 *
511 * @throws Exception if sampler channels are still
512 * connected to the device
513 */
514 void DestroyMidiInputDevice(MidiInputDevice* pDevice) throw (Exception);
515
516 /**
517 * Gets the current number of all active streams.
518 * @returns The current number of all active streams.
519 */
520 int GetDiskStreamCount();
521
522 /**
523 * Gets the current number of all active voices.
524 * @returns The current number of all active voices.
525 */
526 int GetVoiceCount();
527
528 /**
529 * Reset the whole sampler. Destroy all engines, sampler
530 * channels, MIDI input devices and audio output devices.
531 */
532 void Reset();
533
534 /**
535 * Advise the FPU to treat denormal floating point numbers as
536 * zero, to avoid severe performance penalty when dealing with
537 * such extreme floating point values.
538 *
539 * @returns @c true if FPU supports it, @c false otherwise
540 */
541 static bool EnableDenormalsAreZeroMode();
542
543 protected:
544 /**
545 * Notifies listeners that the number of sampler channels has been changed.
546 * @param NewCount The new number of sampler channels.
547 */
548 void fireChannelCountChanged(int NewCount);
549
550 /**
551 * Notifies listeners that the specified sampler channel has just
552 * been added.
553 * @param pChannel The new sampler channel.
554 */
555 void fireChannelAdded(SamplerChannel* pChannel);
556
557 /**
558 * Notifies listeners that the specified sampler channel is
559 * going to be removed soon.
560 * @param pChannel sampler channel to be removed.
561 */
562 void fireChannelToBeRemoved(SamplerChannel* pChannel);
563
564 /**
565 * Notifies listeners that the number of audio output devices has been changed.
566 * @param NewCount The new number of audio output devices.
567 */
568 void fireAudioDeviceCountChanged(int NewCount);
569
570 /**
571 * Notifies listeners that the number of MIDI input devices has been changed.
572 * @param NewCount The new number of MIDI input devices.
573 */
574 void fireMidiDeviceCountChanged(int NewCount);
575
576 /**
577 * Notifies listeners that the supplied MIDI input device is
578 * going to be destroyed soon.
579 * @param pDevice MIDI input device to be destroyed
580 */
581 void fireMidiDeviceToBeDestroyed(MidiInputDevice* pDevice);
582
583 /**
584 * Notifies listeners that the supplied MIDI input device was
585 * just created.
586 * @param pDevice new MIDI input device
587 */
588 void fireMidiDeviceCreated(MidiInputDevice* pDevice);
589
590 /**
591 * Notifies listeners that the number of effect sends
592 * on a particular sampler channel is changed.
593 * @param ChannelId The numerical ID of the sampler channel.
594 * @param NewCount The new number of sampler channels.
595 */
596 void fireFxSendCountChanged(int ChannelId, int NewCount);
597
598 typedef std::map<uint, AudioOutputDevice*> AudioOutputDeviceMap;
599 typedef std::map<uint, MidiInputDevice*> MidiInputDeviceMap;
600 typedef std::map<uint, SamplerChannel*> SamplerChannelMap;
601
602 SamplerChannelMap mSamplerChannels; ///< contains all created sampler channels
603 AudioOutputDeviceMap mAudioOutputDevices; ///< contains all created audio output devices
604 MidiInputDeviceMap mMidiInputDevices; ///< contains all created MIDI input devices
605
606 friend class SamplerChannel;
607
608 private:
609 ListenerList<ChannelCountListener*> llChannelCountListeners;
610 ListenerList<AudioDeviceCountListener*> llAudioDeviceCountListeners;
611 ListenerList<MidiDeviceCountListener*> llMidiDeviceCountListeners;
612 ListenerList<VoiceCountListener*> llVoiceCountListeners;
613 ListenerList<StreamCountListener*> llStreamCountListeners;
614 ListenerList<BufferFillListener*> llBufferFillListeners;
615 ListenerList<TotalStreamCountListener*> llTotalStreamCountListeners;
616 ListenerList<TotalVoiceCountListener*> llTotalVoiceCountListeners;
617 ListenerList<FxSendCountListener*> llFxSendCountListeners;
618
619 class EventHandler : public EngineChangeListener, public FxSendCountListener {
620 public:
621 void SetSampler(Sampler* pSampler) { this->pSampler = pSampler; }
622
623 /**
624 * Invoked when the engine type of the specified sampler
625 * channel is going to be changed soon.
626 * @param ChannelId The numerical ID of the sampler channel
627 */
628 virtual void EngineToBeChanged(int ChannelId);
629
630 /**
631 * Invoked when the engine type of the
632 * specified sampler channel is changed.
633 * @param ChannelId The numerical ID of the sampler
634 * channel, which engine type has been changed.
635 */
636 virtual void EngineChanged(int ChannelId);
637
638 /**
639 * Invoked when the number of effect sends
640 * on the specified sampler channel has changed.
641 * @param ChannelId The numerical ID of the sampler channel.
642 * @param NewCount The new number of effect sends.
643 */
644 virtual void FxSendCountChanged(int ChannelId, int NewCount);
645
646 private:
647 Sampler* pSampler;
648 } eventHandler;
649 };
650 }
651
652 #endif // __LS_SAMPLER_H__
  ViewVC Help
Powered by ViewVC