drivers/audio/AudioOutputDevice.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005 - 2013 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_AUDIOOUTPUTDEVICE_H__
#define __LS_AUDIOOUTPUTDEVICE_H__

#include <set>
#include <map>
#include <vector>
#include <stdexcept>

#include "../../common/global.h"
#include "../../common/Exception.h"
#include "../Device.h"
#include "../DeviceParameter.h"
#include "../../engines/Engine.h"
#include "AudioChannel.h"
#include "../../common/SynchronizedConfig.h"
#include "../../effects/EffectChain.h"

namespace LinuxSampler {

    // just symbol prototyping
    class Engine;
    class AudioOutputDeviceFactory;
    class IDGenerator;

    /** Abstract base class for audio output drivers in LinuxSampler
     *
     * This class will be derived by specialized classes which implement the
     * connection to a specific audio output system (e.g. Alsa, Jack,
     * CoreAudio).
     */
    class AudioOutputDevice : public Device {
        public:

            /////////////////////////////////////////////////////////////////
            // Device parameters

            /** Device Parameter 'ACTIVE'
             *
             * Used to activate / deactivate the audio output device.
             */
            class ParameterActive : public DeviceCreationParameterBool {
                public:
                    ParameterActive();
                    ParameterActive(String s);
                    virtual String Description() OVERRIDE;
                    virtual bool   Fix() OVERRIDE;
                    virtual bool   Mandatory() OVERRIDE;
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() OVERRIDE;
                    virtual optional<bool> DefaultAsBool(std::map<String,String> Parameters) OVERRIDE;
                    virtual void OnSetValue(bool b) throw (Exception) OVERRIDE;
                    static String Name();
            };

            /** Device Parameter 'SAMPLERATE'
             *
             * Used to set the sample rate of the audio output device.
             */
            class ParameterSampleRate : public DeviceCreationParameterInt {
                public:
                    ParameterSampleRate();
                    ParameterSampleRate(String s);
                    virtual String Description() OVERRIDE;
                    virtual bool   Fix() OVERRIDE;
                    virtual bool   Mandatory() OVERRIDE;
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() OVERRIDE;
                    virtual optional<int>    DefaultAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual optional<int>    RangeMinAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual optional<int>    RangeMaxAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual int              ValueAsInt() OVERRIDE;
                    virtual void             OnSetValue(int i) throw (Exception) OVERRIDE;
                    static String Name();
            };

            /** Device Parameters 'CHANNELS'
             *
             * Used to increase / decrease the number of audio channels of
             * audio output device.
             */
            class ParameterChannels : public DeviceCreationParameterInt {
                public:
                    ParameterChannels();
                    ParameterChannels(String s);
                    virtual String Description() OVERRIDE;
                    virtual bool   Fix() OVERRIDE;
                    virtual bool   Mandatory() OVERRIDE;
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() OVERRIDE;
                    virtual optional<int>    DefaultAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual optional<int>    RangeMinAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual optional<int>    RangeMaxAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) OVERRIDE;
                    virtual void             OnSetValue(int i) throw (Exception) OVERRIDE;
                    static String Name();
            };


            /////////////////////////////////////////////////////////////////
            // abstract methods
            //     (these have to be implemented by the descendant)

            /**
             * Start playback of audio signal on the audio device. It's the
             * responsibility of the implementing audio device to call the
             * RenderAudio(uint Samples) method of all connected engines.
             * This will cause the engines to continue to render 'Samples'
             * number of audio sample points and the engines will
             * automatically add their audio signals to the audio buffers of
             * the audio channels of this audio device. So the implementing
             * audio device just has to access the buffers of it's audio
             * channels.
             *
             * @throws AudioOutputException  if playback can not be started
             * @see AudioChannel
             */
            virtual void Play() = 0;

            /**
             * Returns true if the audio device is currently playing back.
             */
            virtual bool IsPlaying() = 0;

            /**
             * Stop playback of audio signal on the audio device. The
             * implementing audio device will stop calling the RenderAudio()
             * method of all connected engines and close it's connection to
             * audio output system.
             */
            virtual void Stop() = 0;

            /**
             * Maximum amount of sample points the implementing audio
             * device will ever demand the sampler engines to write in one
             * fragment cycle / period. Simple audio device drivers usually
             * have a fixed fragment size, so those devices just would return
             * the fragment size in this method.
             *
             * @returns  max. amount of sample points ever
             */
            virtual uint MaxSamplesPerCycle() = 0;

            /**
             * Playback samplerate the audio device uses. The sampler engines
             * currently assume this to be a constant value for the whole
             * life time of an instance of the implementing audio device.
             *
             * @returns  sample rate in Hz
             */
            virtual uint SampleRate() = 0;

            /**
             * Return the audio output device driver name.
             */
            virtual String Driver() = 0;

            /**
             * Create new audio channel. This will be called by
             * AcquireChannels(). Each driver must implement it.
             */
            virtual AudioChannel* CreateChannel(uint ChannelNr) = 0;
        
            /**
             * Might be optionally implemented by the deriving driver. If
             * implemented, this method will return the current audio
             * latency in seconds. The driver might measure the actual
             * latency with timing functions to return the real latency.
             *
             * If this method is not implemented / overridden by the
             * descending driver, it will simply return the theoretical
             * latency, that is MaxSamplesPerCycle() / SampleRate().
             *
             * Currently this method is not used by the sampler itself.
             * It can be used however for GUIs built on top of the sampler
             * for example, to i.e. display the user the currently
             * effective audio latency in real-time.
             */
            virtual float latency();


            /////////////////////////////////////////////////////////////////
            // normal methods
            //     (usually not to be overriden by descendant)

            /**
             * Connect given sampler engine to this audio output device. The
             * engine will be added to the Engines container of this audio
             * device and the engine will also automatically be informed
             * about the connection.
             *
             * @param pEngine - sampler engine
             */
            void Connect(Engine* pEngine);

            /**
             * Disconnect given sampler engine from this audio output device.
             * Removes given sampler engine reference from the Engines
             * container of this audio device.
             *
             * @param pEngine - sampler engine
             */
            void Disconnect(Engine* pEngine);
        
            /**
             * This method can or should be called by the deriving driver in
             * case some fundamental parameter changed, especially if the
             * values returned by MaxSamplesPerCycle() and SamplerRate() have
             * changed, those are values which the sampler engines assume to be
             * constant for the life time of an audio device !
             *
             * By forcing a re-connection with this method, the sampler engines
             * are forced to update those informations metntioned above as well,
             * avoiding crashes or other undesired misbehaviors in such
             * circumstances.
             */
            void ReconnectAll();

            /**
             * Returns audio channel with index \a ChannelIndex or NULL if
             * index out of bounds.
             */
            AudioChannel* Channel(uint ChannelIndex);

            /**
             * This method will usually be called by the sampler engines that
             * are connected to this audio device to inform the audio device
             * how much audio channels the engine(s) need. It's the
             * responsibility of the audio device to offer that amount of
             * audio channels - again: this is not an option this is a must!
             * The engines will assume to be able to access those audio
             * channels right after. If the audio driver is not able to offer
             * that much channels, it can simply create mix channels which
             * are then just mixed to the 'real' audio channels. See
             * AudioChannel.h for details about channels and mix channels.
             *
             * @param Channels - amount of output channels required by
             *                   a sampler engine
             * @throws AudioOutputException  if desired amount of channels
             *                               cannot be offered
             * @see AudioChannel
             */
            void AcquireChannels(uint Channels);

            /**
             * Returns the amount of audio channels (including the so called
             * "mix channels") the device is currently providing.
             */
            uint ChannelCount();

            /**
             * Returns all device parameter settings.
             */
            std::map<String,DeviceCreationParameter*> DeviceParameters();

            /**
             * Add a chain of send effects to this AudioOutputDevice.
             * You actually have to add effects to that chain afterwards.
             */
            EffectChain* AddSendEffectChain();

            /**
             * Remove the send effect chain given by @a iChain .
             *
             * @throws Exception - if given send effect chain doesn't exist
             */
            void RemoveSendEffectChain(uint iChain) throw (Exception);

            /**
             * Returns send effect chain given by @a iChain or @c NULL if
             * there's no such effect chain.
             */
            EffectChain* SendEffectChain(uint iChain) const;

            /**
             * Returns send effect chain with ID @a iChainID or @c NULL if
             * there's no such effect chain.
             */
            EffectChain* SendEffectChainByID(uint iChainID) const;

            /**
             * Returns amount of send effect chains this AudioOutputDevice
             * currently provides.
             */
            uint SendEffectChainCount() const;

            /**
             * @deprecated This method will be removed, use AddSendEffectChain() instead!
             */
            EffectChain* AddMasterEffectChain() DEPRECATED_API;

            /**
             * @deprecated This method will be removed, use RemoveSendEffectChain() instead!
             */
            void RemoveMasterEffectChain(uint iChain) throw (Exception) DEPRECATED_API;

            /**
             * @deprecated This method will be removed, use SendEffectChain() instead!
             */
            EffectChain* MasterEffectChain(uint iChain) const DEPRECATED_API;

            /**
             * @deprecated This method will be removed, use SendEffectChainCount() instead!
             */
            uint MasterEffectChainCount() const DEPRECATED_API;

        protected:
            SynchronizedConfig<std::set<Engine*> >    Engines;     ///< All sampler engines that are connected to the audio output device.
            SynchronizedConfig<std::set<Engine*> >::Reader EnginesReader; ///< Audio thread access to Engines.
            std::vector<AudioChannel*>                Channels;    ///< All audio channels of the audio output device. This is just a container; the descendant has to create channels by himself.
            std::map<String,DeviceCreationParameter*> Parameters;  ///< All device parameters.
            std::vector<EffectChain*>                 vEffectChains;
            IDGenerator*                              EffectChainIDs;

            AudioOutputDevice(std::map<String,DeviceCreationParameter*> DriverParameters);

            virtual ~AudioOutputDevice();

            /**
             * This method should be called by the AudioOutputDevice
             * descendant to let all connected engines proceed to render the
             * given amount of sample points. The engines will place their
             * calculated audio data by themselfes into the buffers of the
             * respective AudioChannel objects, so the implementing audio
             * output device just has to copy the AudioChannel buffers to
             * the output buffer(s) of its audio system.
             *
             * @returns  0 on success or the last error return code of one
             *           engine
             */
            int RenderAudio(uint Samples);

            /**
             * This can be called as an alternative to RenderAudio() for
             * just writing silence to the audio output buffers and not
             * calling the connected sampler engines for rendering audio, so
             * to provide a method to stop playback if the used audio output
             * system doesn't provide a better way.
             *
             * @returns  0 on success
             */
            int RenderSilence(uint Samples);

            friend class AudioOutputDeviceFactory; // allow AudioOutputDeviceFactory class to destroy audio devices

    };

    /**
     * Audio output exception that should be thrown by the AudioOutputDevice
     * descendants in case initialization of the audio output system failed
     * (which should be done in the constructor of the AudioOutputDevice
     * descendant).
     */
    class AudioOutputException : public Exception {
        public:
            AudioOutputException(const std::string& msg) : Exception(msg) {}
    };
}

#endif // __LS_AUDIOOUTPUTDEVICE_H__
1	schoenebeck	200	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5			* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	schoenebeck	2434	* Copyright (C) 2005 - 2013 Christian Schoenebeck *
7	schoenebeck	200	* *
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_AUDIOOUTPUTDEVICE_H__
25			#define __LS_AUDIOOUTPUTDEVICE_H__
26
27			#include <set>
28			#include <map>
29			#include <vector>
30			#include <stdexcept>
31
32			#include "../../common/global.h"
33	schoenebeck	880	#include "../../common/Exception.h"
34	schoenebeck	207	#include "../Device.h"
35	schoenebeck	200	#include "../DeviceParameter.h"
36	schoenebeck	890	#include "../../engines/Engine.h"
37	schoenebeck	200	#include "AudioChannel.h"
38	persson	840	#include "../../common/SynchronizedConfig.h"
39	schoenebeck	1722	#include "../../effects/EffectChain.h"
40	schoenebeck	200
41			namespace LinuxSampler {
42
43			// just symbol prototyping
44	schoenebeck	412	class Engine;
45	schoenebeck	1934	class AudioOutputDeviceFactory;
46	schoenebeck	2135	class IDGenerator;
47	schoenebeck	200
48			/** Abstract base class for audio output drivers in LinuxSampler
49			*
50			* This class will be derived by specialized classes which implement the
51			* connection to a specific audio output system (e.g. Alsa, Jack,
52			* CoreAudio).
53			*/
54	schoenebeck	207	class AudioOutputDevice : public Device {
55	schoenebeck	200	public:
56
57			/////////////////////////////////////////////////////////////////
58			// Device parameters
59
60	schoenebeck	221	/** Device Parameter 'ACTIVE'
61			*
62			* Used to activate / deactivate the audio output device.
63			*/
64	schoenebeck	200	class ParameterActive : public DeviceCreationParameterBool {
65			public:
66	schoenebeck	226	ParameterActive();
67			ParameterActive(String s);
68	schoenebeck	2434	virtual String Description() OVERRIDE;
69			virtual bool Fix() OVERRIDE;
70			virtual bool Mandatory() OVERRIDE;
71			virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() OVERRIDE;
72			virtual optional<bool> DefaultAsBool(std::map<String,String> Parameters) OVERRIDE;
73			virtual void OnSetValue(bool b) throw (Exception) OVERRIDE;
74	schoenebeck	226	static String Name();
75	schoenebeck	200	};
76
77	schoenebeck	221	/** Device Parameter 'SAMPLERATE'
78			*
79			* Used to set the sample rate of the audio output device.
80			*/
81	schoenebeck	200	class ParameterSampleRate : public DeviceCreationParameterInt {
82			public:
83	schoenebeck	226	ParameterSampleRate();
84			ParameterSampleRate(String s);
85	schoenebeck	2434	virtual String Description() OVERRIDE;
86			virtual bool Fix() OVERRIDE;
87			virtual bool Mandatory() OVERRIDE;
88			virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() OVERRIDE;
89			virtual optional<int> DefaultAsInt(std::map<String,String> Parameters) OVERRIDE;
90			virtual optional<int> RangeMinAsInt(std::map<String,String> Parameters) OVERRIDE;
91			virtual optional<int> RangeMaxAsInt(std::map<String,String> Parameters) OVERRIDE;
92			virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) OVERRIDE;
93			virtual int ValueAsInt() OVERRIDE;
94			virtual void OnSetValue(int i) throw (Exception) OVERRIDE;
95	schoenebeck	226	static String Name();
96	schoenebeck	200	};
97
98	schoenebeck	221	/** Device Parameters 'CHANNELS'
99			*
100			* Used to increase / decrease the number of audio channels of
101			* audio output device.
102			*/
103	schoenebeck	200	class ParameterChannels : public DeviceCreationParameterInt {
104			public:
105	schoenebeck	226	ParameterChannels();
106			ParameterChannels(String s);
107	schoenebeck	2434	virtual String Description() OVERRIDE;
108			virtual bool Fix() OVERRIDE;
109			virtual bool Mandatory() OVERRIDE;
110			virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() OVERRIDE;
111			virtual optional<int> DefaultAsInt(std::map<String,String> Parameters) OVERRIDE;
112			virtual optional<int> RangeMinAsInt(std::map<String,String> Parameters) OVERRIDE;
113			virtual optional<int> RangeMaxAsInt(std::map<String,String> Parameters) OVERRIDE;
114			virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) OVERRIDE;
115			virtual void OnSetValue(int i) throw (Exception) OVERRIDE;
116	schoenebeck	226	static String Name();
117	schoenebeck	200	};
118
119
120	schoenebeck	221
121	schoenebeck	200	/////////////////////////////////////////////////////////////////
122			// abstract methods
123			// (these have to be implemented by the descendant)
124
125			/**
126			* Start playback of audio signal on the audio device. It's the
127			* responsibility of the implementing audio device to call the
128			* RenderAudio(uint Samples) method of all connected engines.
129			* This will cause the engines to continue to render 'Samples'
130			* number of audio sample points and the engines will
131			* automatically add their audio signals to the audio buffers of
132			* the audio channels of this audio device. So the implementing
133			* audio device just has to access the buffers of it's audio
134			* channels.
135			*
136			* @throws AudioOutputException if playback can not be started
137			* @see AudioChannel
138			*/
139			virtual void Play() = 0;
140
141			/**
142			* Returns true if the audio device is currently playing back.
143			*/
144			virtual bool IsPlaying() = 0;
145
146			/**
147			* Stop playback of audio signal on the audio device. The
148			* implementing audio device will stop calling the RenderAudio()
149			* method of all connected engines and close it's connection to
150			* audio output system.
151			*/
152			virtual void Stop() = 0;
153
154			/**
155			* Maximum amount of sample points the implementing audio
156			* device will ever demand the sampler engines to write in one
157			* fragment cycle / period. Simple audio device drivers usually
158			* have a fixed fragment size, so those devices just would return
159			* the fragment size in this method.
160			*
161			* @returns max. amount of sample points ever
162			*/
163			virtual uint MaxSamplesPerCycle() = 0;
164
165			/**
166			* Playback samplerate the audio device uses. The sampler engines
167			* currently assume this to be a constant value for the whole
168			* life time of an instance of the implementing audio device.
169			*
170			* @returns sample rate in Hz
171			*/
172			virtual uint SampleRate() = 0;
173
174			/**
175	schoenebeck	226	* Return the audio output device driver name.
176	schoenebeck	200	*/
177			virtual String Driver() = 0;
178
179	schoenebeck	226	/**
180			* Create new audio channel. This will be called by
181			* AcquireChannels(). Each driver must implement it.
182			*/
183			virtual AudioChannel* CreateChannel(uint ChannelNr) = 0;
184	schoenebeck	2410
185			/**
186			* Might be optionally implemented by the deriving driver. If
187			* implemented, this method will return the current audio
188			* latency in seconds. The driver might measure the actual
189			* latency with timing functions to return the real latency.
190			*
191			* If this method is not implemented / overridden by the
192			* descending driver, it will simply return the theoretical
193			* latency, that is MaxSamplesPerCycle() / SampleRate().
194			*
195			* Currently this method is not used by the sampler itself.
196			* It can be used however for GUIs built on top of the sampler
197			* for example, to i.e. display the user the currently
198			* effective audio latency in real-time.
199			*/
200			virtual float latency();
201	schoenebeck	226
202
203
204	schoenebeck	200	/////////////////////////////////////////////////////////////////
205			// normal methods
206			// (usually not to be overriden by descendant)
207
208			/**
209			* Connect given sampler engine to this audio output device. The
210			* engine will be added to the Engines container of this audio
211			* device and the engine will also automatically be informed
212			* about the connection.
213			*
214	schoenebeck	412	* @param pEngine - sampler engine
215	schoenebeck	200	*/
216	schoenebeck	412	void Connect(Engine* pEngine);
217	schoenebeck	200
218			/**
219			* Disconnect given sampler engine from this audio output device.
220			* Removes given sampler engine reference from the Engines
221			* container of this audio device.
222			*
223	schoenebeck	412	* @param pEngine - sampler engine
224	schoenebeck	200	*/
225	schoenebeck	412	void Disconnect(Engine* pEngine);
226	schoenebeck	2410
227			/**
228			* This method can or should be called by the deriving driver in
229			* case some fundamental parameter changed, especially if the
230			* values returned by MaxSamplesPerCycle() and SamplerRate() have
231			* changed, those are values which the sampler engines assume to be
232			* constant for the life time of an audio device !
233			*
234			* By forcing a re-connection with this method, the sampler engines
235			* are forced to update those informations metntioned above as well,
236			* avoiding crashes or other undesired misbehaviors in such
237			* circumstances.
238			*/
239			void ReconnectAll();
240	schoenebeck	200
241			/**
242			* Returns audio channel with index \a ChannelIndex or NULL if
243			* index out of bounds.
244			*/
245			AudioChannel* Channel(uint ChannelIndex);
246
247	schoenebeck	221	/**
248	schoenebeck	226	* This method will usually be called by the sampler engines that
249			* are connected to this audio device to inform the audio device
250			* how much audio channels the engine(s) need. It's the
251			* responsibility of the audio device to offer that amount of
252			* audio channels - again: this is not an option this is a must!
253			* The engines will assume to be able to access those audio
254			* channels right after. If the audio driver is not able to offer
255			* that much channels, it can simply create mix channels which
256			* are then just mixed to the 'real' audio channels. See
257			* AudioChannel.h for details about channels and mix channels.
258			*
259			* @param Channels - amount of output channels required by
260			* a sampler engine
261			* @throws AudioOutputException if desired amount of channels
262			* cannot be offered
263			* @see AudioChannel
264			*/
265			void AcquireChannels(uint Channels);
266
267			/**
268	schoenebeck	1001	* Returns the amount of audio channels (including the so called
269			* "mix channels") the device is currently providing.
270			*/
271			uint ChannelCount();
272
273			/**
274	schoenebeck	221	* Returns all device parameter settings.
275			*/
276	schoenebeck	200	std::map<String,DeviceCreationParameter*> DeviceParameters();
277
278	schoenebeck	1722	/**
279	schoenebeck	2137	* Add a chain of send effects to this AudioOutputDevice.
280	schoenebeck	1722	* You actually have to add effects to that chain afterwards.
281			*/
282	schoenebeck	2137	EffectChain* AddSendEffectChain();
283	schoenebeck	1722
284			/**
285	schoenebeck	2137	* Remove the send effect chain given by @a iChain .
286	schoenebeck	1722	*
287	schoenebeck	2137	* @throws Exception - if given send effect chain doesn't exist
288	schoenebeck	1722	*/
289	schoenebeck	2137	void RemoveSendEffectChain(uint iChain) throw (Exception);
290	schoenebeck	1722
291			/**
292	schoenebeck	2137	* Returns send effect chain given by @a iChain or @c NULL if
293	schoenebeck	1722	* there's no such effect chain.
294			*/
295	schoenebeck	2137	EffectChain* SendEffectChain(uint iChain) const;
296	schoenebeck	1722
297			/**
298	iliev	2198	* Returns send effect chain with ID @a iChainID or @c NULL if
299			* there's no such effect chain.
300			*/
301			EffectChain* SendEffectChainByID(uint iChainID) const;
302
303			/**
304	schoenebeck	2137	* Returns amount of send effect chains this AudioOutputDevice
305	schoenebeck	1722	* currently provides.
306			*/
307	schoenebeck	2137	uint SendEffectChainCount() const;
308	schoenebeck	1722
309	schoenebeck	2137	/**
310			* @deprecated This method will be removed, use AddSendEffectChain() instead!
311			*/
312			EffectChain* AddMasterEffectChain() DEPRECATED_API;
313
314			/**
315			* @deprecated This method will be removed, use RemoveSendEffectChain() instead!
316			*/
317			void RemoveMasterEffectChain(uint iChain) throw (Exception) DEPRECATED_API;
318
319			/**
320			* @deprecated This method will be removed, use SendEffectChain() instead!
321			*/
322			EffectChain* MasterEffectChain(uint iChain) const DEPRECATED_API;
323
324			/**
325			* @deprecated This method will be removed, use SendEffectChainCount() instead!
326			*/
327			uint MasterEffectChainCount() const DEPRECATED_API;
328
329	schoenebeck	200	protected:
330	persson	840	SynchronizedConfig<std::set<Engine*> > Engines; ///< All sampler engines that are connected to the audio output device.
331	persson	846	SynchronizedConfig<std::set<Engine*> >::Reader EnginesReader; ///< Audio thread access to Engines.
332	schoenebeck	200	std::vector<AudioChannel*> Channels; ///< All audio channels of the audio output device. This is just a container; the descendant has to create channels by himself.
333			std::map<String,DeviceCreationParameter*> Parameters; ///< All device parameters.
334	schoenebeck	1722	std::vector<EffectChain*> vEffectChains;
335	schoenebeck	2135	IDGenerator* EffectChainIDs;
336	schoenebeck	200
337			AudioOutputDevice(std::map<String,DeviceCreationParameter*> DriverParameters);
338
339			virtual ~AudioOutputDevice();
340
341			/**
342			* This method should be called by the AudioOutputDevice
343			* descendant to let all connected engines proceed to render the
344			* given amount of sample points. The engines will place their
345			* calculated audio data by themselfes into the buffers of the
346			* respective AudioChannel objects, so the implementing audio
347			* output device just has to copy the AudioChannel buffers to
348			* the output buffer(s) of its audio system.
349			*
350			* @returns 0 on success or the last error return code of one
351			* engine
352			*/
353			int RenderAudio(uint Samples);
354
355			/**
356			* This can be called as an alternative to RenderAudio() for
357			* just writing silence to the audio output buffers and not
358			* calling the connected sampler engines for rendering audio, so
359			* to provide a method to stop playback if the used audio output
360			* system doesn't provide a better way.
361			*
362			* @returns 0 on success
363			*/
364			int RenderSilence(uint Samples);
365
366	schoenebeck	1934	friend class AudioOutputDeviceFactory; // allow AudioOutputDeviceFactory class to destroy audio devices
367	schoenebeck	200
368			};
369
370			/**
371			* Audio output exception that should be thrown by the AudioOutputDevice
372			* descendants in case initialization of the audio output system failed
373			* (which should be done in the constructor of the AudioOutputDevice
374			* descendant).
375			*/
376	schoenebeck	880	class AudioOutputException : public Exception {
377	schoenebeck	200	public:
378	schoenebeck	880	AudioOutputException(const std::string& msg) : Exception(msg) {}
379	schoenebeck	200	};
380			}
381
382			#endif // __LS_AUDIOOUTPUTDEVICE_H__