drivers/audio/AudioOutputDevice.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005 - 2010 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();
                    virtual bool   Fix();
                    virtual bool   Mandatory();
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters();
                    virtual optional<bool> DefaultAsBool(std::map<String,String> Parameters);
                    virtual void OnSetValue(bool b) throw (Exception);
                    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();
                    virtual bool   Fix();
                    virtual bool   Mandatory();
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters();
                    virtual optional<int>    DefaultAsInt(std::map<String,String> Parameters);
                    virtual optional<int>    RangeMinAsInt(std::map<String,String> Parameters);
                    virtual optional<int>    RangeMaxAsInt(std::map<String,String> Parameters);
                    virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters);
                    virtual int              ValueAsInt();
                    virtual void             OnSetValue(int i) throw (Exception);
                    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();
                    virtual bool   Fix();
                    virtual bool   Mandatory();
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters();
                    virtual optional<int>    DefaultAsInt(std::map<String,String> Parameters);
                    virtual optional<int>    RangeMinAsInt(std::map<String,String> Parameters);
                    virtual optional<int>    RangeMaxAsInt(std::map<String,String> Parameters);
                    virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters);
                    virtual void             OnSetValue(int i) throw (Exception);
                    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;


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

            /**
             * 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	/***************************************************************************
2	* *
3	* LinuxSampler - modular, streaming capable sampler *
4	* *
5	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	* Copyright (C) 2005 - 2010 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_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	#include "../../common/Exception.h"
34	#include "../Device.h"
35	#include "../DeviceParameter.h"
36	#include "../../engines/Engine.h"
37	#include "AudioChannel.h"
38	#include "../../common/SynchronizedConfig.h"
39	#include "../../effects/EffectChain.h"
40
41	namespace LinuxSampler {
42
43	// just symbol prototyping
44	class Engine;
45	class AudioOutputDeviceFactory;
46	class IDGenerator;
47
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	class AudioOutputDevice : public Device {
55	public:
56
57	/////////////////////////////////////////////////////////////////
58	// Device parameters
59
60	/** Device Parameter 'ACTIVE'
61	*
62	* Used to activate / deactivate the audio output device.
63	*/
64	class ParameterActive : public DeviceCreationParameterBool {
65	public:
66	ParameterActive();
67	ParameterActive(String s);
68	virtual String Description();
69	virtual bool Fix();
70	virtual bool Mandatory();
71	virtual std::map<String,DeviceCreationParameter*> DependsAsParameters();
72	virtual optional<bool> DefaultAsBool(std::map<String,String> Parameters);
73	virtual void OnSetValue(bool b) throw (Exception);
74	static String Name();
75	};
76
77	/** Device Parameter 'SAMPLERATE'
78	*
79	* Used to set the sample rate of the audio output device.
80	*/
81	class ParameterSampleRate : public DeviceCreationParameterInt {
82	public:
83	ParameterSampleRate();
84	ParameterSampleRate(String s);
85	virtual String Description();
86	virtual bool Fix();
87	virtual bool Mandatory();
88	virtual std::map<String,DeviceCreationParameter*> DependsAsParameters();
89	virtual optional<int> DefaultAsInt(std::map<String,String> Parameters);
90	virtual optional<int> RangeMinAsInt(std::map<String,String> Parameters);
91	virtual optional<int> RangeMaxAsInt(std::map<String,String> Parameters);
92	virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters);
93	virtual int ValueAsInt();
94	virtual void OnSetValue(int i) throw (Exception);
95	static String Name();
96	};
97
98	/** Device Parameters 'CHANNELS'
99	*
100	* Used to increase / decrease the number of audio channels of
101	* audio output device.
102	*/
103	class ParameterChannels : public DeviceCreationParameterInt {
104	public:
105	ParameterChannels();
106	ParameterChannels(String s);
107	virtual String Description();
108	virtual bool Fix();
109	virtual bool Mandatory();
110	virtual std::map<String,DeviceCreationParameter*> DependsAsParameters();
111	virtual optional<int> DefaultAsInt(std::map<String,String> Parameters);
112	virtual optional<int> RangeMinAsInt(std::map<String,String> Parameters);
113	virtual optional<int> RangeMaxAsInt(std::map<String,String> Parameters);
114	virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters);
115	virtual void OnSetValue(int i) throw (Exception);
116	static String Name();
117	};
118
119
120
121	/////////////////////////////////////////////////////////////////
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	* Return the audio output device driver name.
176	*/
177	virtual String Driver() = 0;
178
179	/**
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
185
186
187	/////////////////////////////////////////////////////////////////
188	// normal methods
189	// (usually not to be overriden by descendant)
190
191	/**
192	* Connect given sampler engine to this audio output device. The
193	* engine will be added to the Engines container of this audio
194	* device and the engine will also automatically be informed
195	* about the connection.
196	*
197	* @param pEngine - sampler engine
198	*/
199	void Connect(Engine* pEngine);
200
201	/**
202	* Disconnect given sampler engine from this audio output device.
203	* Removes given sampler engine reference from the Engines
204	* container of this audio device.
205	*
206	* @param pEngine - sampler engine
207	*/
208	void Disconnect(Engine* pEngine);
209
210	/**
211	* Returns audio channel with index \a ChannelIndex or NULL if
212	* index out of bounds.
213	*/
214	AudioChannel* Channel(uint ChannelIndex);
215
216	/**
217	* This method will usually be called by the sampler engines that
218	* are connected to this audio device to inform the audio device
219	* how much audio channels the engine(s) need. It's the
220	* responsibility of the audio device to offer that amount of
221	* audio channels - again: this is not an option this is a must!
222	* The engines will assume to be able to access those audio
223	* channels right after. If the audio driver is not able to offer
224	* that much channels, it can simply create mix channels which
225	* are then just mixed to the 'real' audio channels. See
226	* AudioChannel.h for details about channels and mix channels.
227	*
228	* @param Channels - amount of output channels required by
229	* a sampler engine
230	* @throws AudioOutputException if desired amount of channels
231	* cannot be offered
232	* @see AudioChannel
233	*/
234	void AcquireChannels(uint Channels);
235
236	/**
237	* Returns the amount of audio channels (including the so called
238	* "mix channels") the device is currently providing.
239	*/
240	uint ChannelCount();
241
242	/**
243	* Returns all device parameter settings.
244	*/
245	std::map<String,DeviceCreationParameter*> DeviceParameters();
246
247	/**
248	* Add a chain of send effects to this AudioOutputDevice.
249	* You actually have to add effects to that chain afterwards.
250	*/
251	EffectChain* AddSendEffectChain();
252
253	/**
254	* Remove the send effect chain given by @a iChain .
255	*
256	* @throws Exception - if given send effect chain doesn't exist
257	*/
258	void RemoveSendEffectChain(uint iChain) throw (Exception);
259
260	/**
261	* Returns send effect chain given by @a iChain or @c NULL if
262	* there's no such effect chain.
263	*/
264	EffectChain* SendEffectChain(uint iChain) const;
265
266	/**
267	* Returns send effect chain with ID @a iChainID or @c NULL if
268	* there's no such effect chain.
269	*/
270	EffectChain* SendEffectChainByID(uint iChainID) const;
271
272	/**
273	* Returns amount of send effect chains this AudioOutputDevice
274	* currently provides.
275	*/
276	uint SendEffectChainCount() const;
277
278	/**
279	* @deprecated This method will be removed, use AddSendEffectChain() instead!
280	*/
281	EffectChain* AddMasterEffectChain() DEPRECATED_API;
282
283	/**
284	* @deprecated This method will be removed, use RemoveSendEffectChain() instead!
285	*/
286	void RemoveMasterEffectChain(uint iChain) throw (Exception) DEPRECATED_API;
287
288	/**
289	* @deprecated This method will be removed, use SendEffectChain() instead!
290	*/
291	EffectChain* MasterEffectChain(uint iChain) const DEPRECATED_API;
292
293	/**
294	* @deprecated This method will be removed, use SendEffectChainCount() instead!
295	*/
296	uint MasterEffectChainCount() const DEPRECATED_API;
297
298	protected:
299	SynchronizedConfig<std::set<Engine*> > Engines; ///< All sampler engines that are connected to the audio output device.
300	SynchronizedConfig<std::set<Engine*> >::Reader EnginesReader; ///< Audio thread access to Engines.
301	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.
302	std::map<String,DeviceCreationParameter*> Parameters; ///< All device parameters.
303	std::vector<EffectChain*> vEffectChains;
304	IDGenerator* EffectChainIDs;
305
306	AudioOutputDevice(std::map<String,DeviceCreationParameter*> DriverParameters);
307
308	virtual ~AudioOutputDevice();
309
310	/**
311	* This method should be called by the AudioOutputDevice
312	* descendant to let all connected engines proceed to render the
313	* given amount of sample points. The engines will place their
314	* calculated audio data by themselfes into the buffers of the
315	* respective AudioChannel objects, so the implementing audio
316	* output device just has to copy the AudioChannel buffers to
317	* the output buffer(s) of its audio system.
318	*
319	* @returns 0 on success or the last error return code of one
320	* engine
321	*/
322	int RenderAudio(uint Samples);
323
324	/**
325	* This can be called as an alternative to RenderAudio() for
326	* just writing silence to the audio output buffers and not
327	* calling the connected sampler engines for rendering audio, so
328	* to provide a method to stop playback if the used audio output
329	* system doesn't provide a better way.
330	*
331	* @returns 0 on success
332	*/
333	int RenderSilence(uint Samples);
334
335	friend class AudioOutputDeviceFactory; // allow AudioOutputDeviceFactory class to destroy audio devices
336
337	};
338
339	/**
340	* Audio output exception that should be thrown by the AudioOutputDevice
341	* descendants in case initialization of the audio output system failed
342	* (which should be done in the constructor of the AudioOutputDevice
343	* descendant).
344	*/
345	class AudioOutputException : public Exception {
346	public:
347	AudioOutputException(const std::string& msg) : Exception(msg) {}
348	};
349	}
350
351	#endif // __LS_AUDIOOUTPUTDEVICE_H__