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

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1934 - (show annotations) (download) (as text)
Sun Jul 12 10:35:55 2009 UTC (14 years, 9 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 29500 byte(s) 
* bugfix: don't allow to create or destroy audio devices and MIDI devices
  of host plugin implementations (e.g VST, AU, DSSI, LV2) on their own,
  as they only exist in the context of the plugin instance and would
  otherwise crash the application
1 /***************************************************************************
2 * *
3 * LinuxSampler - modular, streaming capable sampler *
4 * *
5 * Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6 * Copyright (C) 2005 - 2009 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 /** Returns the sampler to which this channel belongs */
155 Sampler* GetSampler();
156
157 ///////////////////////////////////////////////////////////////
158 // Event Listener methods
159
160 /**
161 * Registers the specified listener to be notified
162 * when the engine type of this sampler channel is changed.
163 */
164 void AddEngineChangeListener(EngineChangeListener* l);
165
166 /**
167 * Removes the specified listener.
168 */
169 void RemoveEngineChangeListener(EngineChangeListener* l);
170
171 /**
172 * Removes the specified listener.
173 */
174 void RemoveAllEngineChangeListeners();
175
176 /**
177 * Notifies listeners that the engine type of this sampler
178 * channel is going to be changed soon.
179 */
180 void fireEngineToBeChanged();
181
182 /**
183 * Notifies listeners that the engine
184 * type of this sampler channel is changed.
185 */
186 void fireEngineChanged();
187
188
189 protected:
190 SamplerChannel(Sampler* pS);
191 virtual ~SamplerChannel();
192
193 /** Getting MIDI input device port given its index number. */
194 MidiInputPort* __GetMidiInputDevicePort(int iMidiPort);
195
196 Sampler* pSampler;
197 EngineChannel* pEngineChannel;
198 AudioOutputDevice* pAudioOutputDevice;
199 MidiInputDevice* pMidiInputDevice;
200 int iIndex;
201
202 friend class Sampler;
203 private:
204 int iMidiPort; ///< Don't access directly, read GetMidiInputPort() instead !
205 midi_chan_t midiChannel; ///< Don't access directly, read GetMidiInputChannel() instead !
206 ListenerList<EngineChangeListener*> llEngineChangeListeners;
207 };
208
209 /** @brief LinuxSampler main class
210 *
211 * This is the toplevel class for a LinuxSampler instance.
212 *
213 * LinuxSampler can have arbitrary numbers of sampler channels. Each
214 * sampler channel can individually be deployed with it's own sampler
215 * engine, connected to an arbitrary MIDI input device and connected to
216 * an arbitrary audio output device. Here an example setup:
217 * @code
218 * S.Channel MIDI in S.Engine Audio out
219 * -------------------------------------------------------------------
220 * 0 Alsa -> gig::Engine -> Jack
221 * 1 VSTi -> Akai::Engine -> VSTi
222 * 2 Jack -> DLS::Engine -> Jack
223 * 3 Jack -> SF::Engine -> Alsa
224 *
225 * ... (and so on) ...
226 * @endcode
227 *
228 * Note that not all audio and MIDI backends and sampler engines listed
229 * in the example above might already been implemented!
230 *
231 * As you can see in the example setup, LinuxSampler is capable to use
232 * several, different audio output and MIDI input systems
233 * simultaniously at the same time. Here the example setup shown in the
234 * aspect of MIDI input and audio output devices / drivers:
235 * @code
236 * ######################### #########################
237 * # AudioOutputDeviceJack # # AudioOutputDeviceVSTi #
238 * ######################### #########################
239 * ^ ^ ^
240 * /------------>|Sampler Channel 0|-----/ | |
241 * | /--------->|Sampler Channel 1|---------------------/
242 * | | /------>|Sampler Channel 2|---------/
243 * | | | /--->|Sampler Channel 3|------------>#########################
244 * | | | | ... (and so on) ... # AudioOutputDeviceAlsa #
245 * | | | | #########################
246 * | | | \-----------------------------------------------------\
247 * | | \--------------------------------------------\ |
248 * | \--------------------\ | |
249 * | | | |
250 * ####################### ####################### #######################
251 * # MidiInputDeviceAlsa # # MidiInputDeviceVSTi # # MidiInputDeviceJack #
252 * ####################### ####################### #######################
253 * @endcode
254 *
255 * As you can see in this example setup, one device (that is midi input
256 * driver / audio output driver) can be connected multiple times to
257 * different sampler channels.
258 *
259 * It's even possible to create multiple instances of the same driver, for
260 * example multiple instances of the Alsa output driver to use multiple
261 * sound cards at the same time, or multiple instances of the JACK audio
262 * output driver to leverage SMP systems or boxes with several hard discs.
263 */
264 class Sampler {
265 public:
266 /**
267 * Constructor. Create a LinuxSampler instance.
268 */
269 Sampler();
270
271 /**
272 * Destructor.
273 */
274 virtual ~Sampler();
275
276 /**
277 * Returns the number of sampler channels currently allocated.
278 */
279 uint SamplerChannels();
280
281 /**
282 * Create and add a new sampler channel to this Sampler
283 * instance. For race condition reasons the new channel will use
284 * an index past the last already existing sampler channel
285 * index (in case the index limit was not reached yet, otherwise
286 * a free index starting from 0 is searched).
287 *
288 * @returns pointer to new sampler channel
289 */
290 SamplerChannel* AddSamplerChannel();
291
292 /**
293 * Returns the sampler channel of the given sampler channel
294 * index.
295 *
296 * @returns pointer to sought sampler channel
297 */
298 SamplerChannel* GetSamplerChannel(uint uiSamplerChannel);
299
300 /**
301 * Returns all created sampler channels.
302 */
303 std::map<uint, SamplerChannel*> GetSamplerChannels();
304
305 /**
306 * Destroy and remove the given sampler channel from this
307 * Sampler instance.
308 *
309 * @param pSamplerChannel - pointer to sampler channel to remove
310 */
311 void RemoveSamplerChannel(SamplerChannel* pSamplerChannel);
312
313 /**
314 * Destroy and remove the given sampler channel from this
315 * Sampler instance.
316 *
317 * @param uiSamplerChannel - index of the sampler channel to
318 * remove
319 */
320 void RemoveSamplerChannel(uint uiSamplerChannel);
321
322 /**
323 * Destroy and remove all sampler channels from this
324 * Sampler instance.
325 */
326 void RemoveAllSamplerChannels();
327
328 /**
329 * Returns the names of all available audio output drivers.
330 */
331 std::vector<String> AvailableAudioOutputDrivers();
332
333 /**
334 * Returns the names of all available MIDI input drivers.
335 */
336 std::vector<String> AvailableMidiInputDrivers();
337
338 /**
339 * Returns the names of all available sampler engine types.
340 * @see SamplerChannel::SetEngineType()
341 */
342 std::vector<String> AvailableEngineTypes();
343
344 /**
345 * Create an audio output device.
346 *
347 * @param AudioDriver - name of the audio driver
348 * @param Parameters - eventually needed driver parameters to
349 * create the device
350 * @returns pointer to created audio output device
351 * @throws Exception if device could not be created
352 */
353 AudioOutputDevice* CreateAudioOutputDevice(String AudioDriver, std::map<String,String> Parameters) throw (Exception);
354
355 /**
356 * Create a midi input device.
357 *
358 * @param MidiDriver - name of the midi driver
359 * @param Parameters - eventually needed driver parameters to
360 * create the device
361 * @returns pointer to created midi input device
362 * @throws Exception if device could not be created
363 */
364 MidiInputDevice* CreateMidiInputDevice(String MidiDriver, std::map<String,String> Parameters) throw (Exception);
365
366 /**
367 * Returns the number of all created audio output devices.
368 */
369 uint AudioOutputDevices();
370
371 /**
372 * Returns the number of all created MIDI input devices.
373 */
374 uint MidiInputDevices();
375
376 /**
377 * Returns all created audio output devices.
378 */
379 std::map<uint, AudioOutputDevice*> GetAudioOutputDevices();
380
381 /**
382 * Returns all created MIDI input devices.
383 */
384 std::map<uint, MidiInputDevice*> GetMidiInputDevices();
385
386 /**
387 * Destroy the given audio output device and takes care if there
388 * are still sampler engines connected to this device, etc.
389 *
390 * @throws Exception if sampler channels are still
391 * connected to the device
392 */
393 void DestroyAudioOutputDevice(AudioOutputDevice* pDevice) throw (Exception);
394
395 /**
396 * Destroy all audio output devices and takes care if there
397 * are still sampler engines connected to devices, etc.
398 *
399 * Note: non-autonomous devices, that is devices associated with
400 * host plugin instances like VST, AU, DSSI, LV2 are not
401 * destroyed by this method.
402 *
403 * @throws Exception if sampler channels are still
404 * connected to device
405 */
406 void DestroyAllAudioOutputDevices() throw (Exception);
407
408 /**
409 * Destroy the given MIDI input device and takes care if there
410 * are still sampler engines connected to this device, etc.
411 *
412 * @throws Exception if sampler channels are still
413 * connected to the device
414 */
415 void DestroyMidiInputDevice(MidiInputDevice* pDevice) throw (Exception);
416
417 /**
418 * Destroy all MIDI input devices and take care if there
419 * are still sampler engines connected to device, etc.
420 *
421 * Note: non-autonomous devices, that is devices associated with
422 * host plugin instances like VST, AU, DSSI, LV2 are not
423 * destroyed by this method.
424 *
425 * @throws Exception if sampler channels are still
426 * connected to device
427 */
428 void DestroyAllMidiInputDevices() throw (Exception);
429
430 /**
431 * Gets the current number of all active streams.
432 * @returns The current number of all active streams.
433 */
434 int GetDiskStreamCount();
435
436 /**
437 * Gets the current number of all active voices.
438 * @returns The current number of all active voices.
439 */
440 int GetVoiceCount();
441
442 /**
443 * Reset the whole sampler. Destroy all engines, sampler
444 * channels, MIDI input devices and audio output devices.
445 */
446 void Reset();
447
448 ///////////////////////////////////////////////////////////////
449 // Event Listener methods
450
451 /**
452 * Registers the specified listener to be notified
453 * when the number of sampler chanels is changed.
454 */
455 void AddChannelCountListener(ChannelCountListener* l);
456
457 /**
458 * Removes the specified listener.
459 */
460 void RemoveChannelCountListener(ChannelCountListener* l);
461
462 /**
463 * Registers the specified listener to be notified
464 * when the number of audio output devices is changed.
465 */
466 void AddAudioDeviceCountListener(AudioDeviceCountListener* l);
467
468 /**
469 * Removes the specified listener.
470 */
471 void RemoveAudioDeviceCountListener(AudioDeviceCountListener* l);
472
473 /**
474 * Registers the specified listener to be notified
475 * when the number of MIDI input devices is changed.
476 */
477 void AddMidiDeviceCountListener(MidiDeviceCountListener* l);
478
479 /**
480 * Removes the specified listener.
481 */
482 void RemoveMidiDeviceCountListener(MidiDeviceCountListener* l);
483
484 /**
485 * Registers the specified listener to be notified when the number
486 * of active voices in a particular sampler channel is changed.
487 */
488 void AddVoiceCountListener(VoiceCountListener* l);
489
490 /**
491 * Removes the specified listener.
492 */
493 void RemoveVoiceCountListener(VoiceCountListener* l);
494
495 /**
496 * Notifies listeners that the number of active voices
497 * on the specified sampler channel is changed.
498 * @param ChannelId The numerical ID of the sampler channel.
499 * @param NewCount The new number of active voices.
500 */
501 void fireVoiceCountChanged(int ChannelId, int NewCount);
502
503 /**
504 * Registers the specified listener to be notified when the number
505 * of active disk streams in a particular sampler channel is changed.
506 */
507 void AddStreamCountListener(StreamCountListener* l);
508
509 /**
510 * Removes the specified listener.
511 */
512 void RemoveStreamCountListener(StreamCountListener* l);
513
514 /**
515 * Notifies listeners that the number of active disk streams
516 * on the specified sampler channel is changed.
517 * @param ChannelId The numerical ID of the sampler channel.
518 * @param NewCount The new number of active disk streams.
519 */
520 void fireStreamCountChanged(int ChannelId, int NewCount);
521
522 /**
523 * Registers the specified listener to be
524 * notified when the fill state of the disk stream
525 * buffers on a specific sampler channel is changed.
526 */
527 void AddBufferFillListener(BufferFillListener* l);
528
529 /**
530 * Removes the specified listener.
531 */
532 void RemoveBufferFillListener(BufferFillListener* l);
533
534 /**
535 * Notifies listeners that the fill state of the disk stream
536 * buffers on the specified sampler channel is changed.
537 * @param ChannelId The numerical ID of the sampler channel.
538 * @param FillData The buffer fill data for the specified sampler channel.
539 */
540 void fireBufferFillChanged(int ChannelId, String FillData);
541
542 /**
543 * Registers the specified listener to be notified
544 * when total number of active voices is changed.
545 */
546 void AddTotalVoiceCountListener(TotalVoiceCountListener* l);
547
548 /**
549 * Removes the specified listener.
550 */
551 void RemoveTotalVoiceCountListener(TotalVoiceCountListener* l);
552
553 /**
554 * Notifies listeners that the total number of active voices is changed.
555 * @param NewCount The new number of active voices.
556 */
557 void fireTotalVoiceCountChanged(int NewCount);
558
559 /**
560 * Registers the specified listener to be notified when the number
561 * of total streams is changed.
562 */
563 void AddTotalStreamCountListener(TotalStreamCountListener* l);
564
565 /**
566 * Removes the specified listener.
567 */
568 void RemoveTotalStreamCountListener(TotalStreamCountListener* l);
569
570 /**
571 * Notifies listeners that the total number of total streams changed.
572 * @param NewCount The new number of total streams.
573 */
574 void fireTotalStreamCountChanged(int NewCount);
575
576 /**
577 * Registers the specified listener to be notified when the number
578 * of effect sends on a particular sampler channel is changed.
579 */
580 void AddFxSendCountListener(FxSendCountListener* l);
581
582 /**
583 * Removes the specified listener.
584 */
585 void RemoveFxSendCountListener(FxSendCountListener* l);
586
587 /**
588 * Notifies listeners about the current number of voices,
589 * streams and total voices, and the current fill state of
590 * the disk stream buffers.
591 */
592 void fireStatistics();
593
594 ///////////////////////////////////////////////////////////////
595 // system specific methods
596
597 /**
598 * Advise the FPU to treat denormal floating point numbers as
599 * zero, to avoid severe performance penalty when dealing with
600 * such extreme floating point values.
601 *
602 * @returns @c true if FPU supports it, @c false otherwise
603 */
604 static bool EnableDenormalsAreZeroMode();
605
606 #if defined(WIN32)
607 /**
608 * Gets the directory where the liblinuxsampler dll is located.
609 * Note: this method is currently only available for Windows.
610 * @returns installation directory
611 */
612 static String GetInstallDir();
613 #endif
614 protected:
615 /**
616 * Notifies listeners that the number of sampler channels has been changed.
617 * @param NewCount The new number of sampler channels.
618 */
619 void fireChannelCountChanged(int NewCount);
620
621 /**
622 * Notifies listeners that the specified sampler channel has just
623 * been added.
624 * @param pChannel The new sampler channel.
625 */
626 void fireChannelAdded(SamplerChannel* pChannel);
627
628 /**
629 * Notifies listeners that the specified sampler channel is
630 * going to be removed soon.
631 * @param pChannel sampler channel to be removed.
632 */
633 void fireChannelToBeRemoved(SamplerChannel* pChannel);
634
635 /**
636 * Notifies listeners that the number of audio output devices has been changed.
637 * @param NewCount The new number of audio output devices.
638 */
639 void fireAudioDeviceCountChanged(int NewCount);
640
641 /**
642 * Notifies listeners that the number of MIDI input devices has been changed.
643 * @param NewCount The new number of MIDI input devices.
644 */
645 void fireMidiDeviceCountChanged(int NewCount);
646
647 /**
648 * Notifies listeners that the supplied MIDI input device is
649 * going to be destroyed soon.
650 * @param pDevice MIDI input device to be destroyed
651 */
652 void fireMidiDeviceToBeDestroyed(MidiInputDevice* pDevice);
653
654 /**
655 * Notifies listeners that the supplied MIDI input device was
656 * just created.
657 * @param pDevice new MIDI input device
658 */
659 void fireMidiDeviceCreated(MidiInputDevice* pDevice);
660
661 /**
662 * Notifies listeners that the number of effect sends
663 * on a particular sampler channel is changed.
664 * @param ChannelId The numerical ID of the sampler channel.
665 * @param NewCount The new number of sampler channels.
666 */
667 void fireFxSendCountChanged(int ChannelId, int NewCount);
668
669 typedef std::map<uint, SamplerChannel*> SamplerChannelMap;
670
671 SamplerChannelMap mSamplerChannels; ///< contains all created sampler channels
672
673 // statistics cache
674 uint uiOldTotalVoiceCount;
675 uint uiOldTotalStreamCount;
676 std::map<uint, uint> mOldVoiceCounts;
677 std::map<uint, uint> mOldStreamCounts;
678
679 friend class SamplerChannel;
680
681 private:
682 ListenerList<ChannelCountListener*> llChannelCountListeners;
683 ListenerList<AudioDeviceCountListener*> llAudioDeviceCountListeners;
684 ListenerList<MidiDeviceCountListener*> llMidiDeviceCountListeners;
685 ListenerList<VoiceCountListener*> llVoiceCountListeners;
686 ListenerList<StreamCountListener*> llStreamCountListeners;
687 ListenerList<BufferFillListener*> llBufferFillListeners;
688 ListenerList<TotalStreamCountListener*> llTotalStreamCountListeners;
689 ListenerList<TotalVoiceCountListener*> llTotalVoiceCountListeners;
690 ListenerList<FxSendCountListener*> llFxSendCountListeners;
691
692 class EventHandler : public EngineChangeListener, public FxSendCountListener {
693 public:
694 void SetSampler(Sampler* pSampler) { this->pSampler = pSampler; }
695
696 /**
697 * Invoked when the engine type of the specified sampler
698 * channel is going to be changed soon.
699 * @param ChannelId The numerical ID of the sampler channel
700 */
701 virtual void EngineToBeChanged(int ChannelId);
702
703 /**
704 * Invoked when the engine type of the
705 * specified sampler channel is changed.
706 * @param ChannelId The numerical ID of the sampler
707 * channel, which engine type has been changed.
708 */
709 virtual void EngineChanged(int ChannelId);
710
711 /**
712 * Invoked when the number of effect sends
713 * on the specified sampler channel has changed.
714 * @param ChannelId The numerical ID of the sampler channel.
715 * @param NewCount The new number of effect sends.
716 */
717 virtual void FxSendCountChanged(int ChannelId, int NewCount);
718
719 private:
720 Sampler* pSampler;
721 } eventHandler;
722 };
723 }
724
725 #endif // __LS_SAMPLER_H__
  ViewVC Help
Powered by ViewVC