src/audiodriver/AudioOutputDevice.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and 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/LinuxSamplerException.h"
#include "../drivers/DeviceParameter.h"
#include "../engines/common/Engine.h"
#include "AudioChannel.h"

namespace LinuxSampler {

    // just symbol prototyping
    class Engine;

    /** 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:


            /////////////////////////////////////////////////////////////////
            // type definitions

            class ParameterActive : public DeviceCreationParameterBool {
                public:
                    ParameterActive(AudioOutputDevice* pDevice)                              { this->pDevice = pDevice; InitWithDefault();         }
                    ParameterActive(AudioOutputDevice* pDevice, String active) throw (LinuxSamplerException) : DeviceCreationParameterBool(active) { this->pDevice = pDevice; }
                    virtual String Description()                                             { return "Enable / disable device";                   }
                    virtual bool   Fix()                                                     { return false;                                       }
                    virtual bool   Mandatory()                                               { return false;                                       }
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters()  { return std::map<String,DeviceCreationParameter*>(); }
                    virtual optional<bool> DefaultAsBool(std::map<String,String> Parameters) { return true;                                        }
                    virtual void OnSetValue(bool b) throw (LinuxSamplerException)            { if (b) pDevice->Play(); else pDevice->Stop();       }
                protected:
                    AudioOutputDevice* pDevice;
            };

            class ParameterSampleRate : public DeviceCreationParameterInt {
                public:
                    ParameterSampleRate(AudioOutputDevice* pDevice)                                 { this->pDevice = pDevice; InitWithDefault();         }
                    ParameterSampleRate(AudioOutputDevice* pDevice, String samplerate) throw (LinuxSamplerException) : DeviceCreationParameterInt(samplerate) { this->pDevice = pDevice; }
                    virtual String Description()                                                    { return "Output sample rate";                        }
                    virtual bool   Fix()                                                            { return true;                                        }
                    virtual bool   Mandatory()                                                      { return false;                                       }
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters()         { return std::map<String,DeviceCreationParameter*>(); }
                    virtual optional<int>    DefaultAsInt(std::map<String,String> Parameters)       { return 44100;                                       }
                    virtual optional<int>    RangeMinAsInt(std::map<String,String> Parameters)      { return optional<int>::nothing;                      }
                    virtual optional<int>    RangeMaxAsInt(std::map<String,String> Parameters)      { return optional<int>::nothing;                      }
                    virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) { return std::vector<int>();                          }
                    virtual void             OnSetValue(int i) throw (LinuxSamplerException)        { /* cannot happen, as parameter is fix */            }
                protected:
                    AudioOutputDevice* pDevice;
            };

            class ParameterChannels : public DeviceCreationParameterInt {
                public:
                    ParameterChannels(AudioOutputDevice* pDevice)                                   { this->pDevice = pDevice; InitWithDefault();         }
                    ParameterChannels(AudioOutputDevice* pDevice, String channels) throw (LinuxSamplerException) : DeviceCreationParameterInt(channels) { this->pDevice = pDevice; }
                    virtual String Description()                                                    { return "Number of output channels";                 }
                    virtual bool   Fix()                                                            { return false;                                       }
                    virtual bool   Mandatory()                                                      { return false;                                       }
                    virtual std::map<String,DeviceCreationParameter*> DependsAsParameters()         { return std::map<String,DeviceCreationParameter*>(); }
                    virtual optional<int>    DefaultAsInt(std::map<String,String> Parameters)       { return 2;                                           }
                    virtual optional<int>    RangeMinAsInt(std::map<String,String> Parameters)      { return optional<int>::nothing;                      }
                    virtual optional<int>    RangeMaxAsInt(std::map<String,String> Parameters)      { return optional<int>::nothing;                      }
                    virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) { return std::vector<int>();                          }
                    virtual void             OnSetValue(int i) throw (LinuxSamplerException)        { pDevice->AcquireChannels(i);                        }
                protected:
                    AudioOutputDevice* pDevice;
            };

            template <class Parameter_T>
            class OptionalParameter {
                    public:
                    static Parameter_T* New(AudioOutputDevice* pDevice, String val)                               { if (val == "") return (new Parameter_T(pDevice)); return (new Parameter_T(pDevice, val)); }
            };

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

            /**
             * 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
             */
            virtual void AcquireChannels(uint Channels) = 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;

            static std::map<String,DeviceCreationParameter*> AvailableParameters();

            /**
             * Return the audio output device driver type name.
             */
            virtual String Driver() = 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);

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


        protected:
            std::set<Engine*>                         Engines;     ///< All sampler engines that are connected to the audio output device.
            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.

            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 Sampler; // allow Sampler class to destroy audio devices

        private:
             static std::map<String,DeviceCreationParameter*> CreateAvailableParameters();
    };

    /**
     * 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 LinuxSamplerException {
        public:
            AudioOutputException(const std::string& msg) : LinuxSamplerException(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	* *
7	* This program is free software; you can redistribute it and/or modify *
8	* it under the terms of the GNU General Public License as published by *
9	* the Free Software Foundation; either version 2 of the License, or *
10	* (at your option) any later version. *
11	* *
12	* This program is distributed in the hope that it will be useful, *
13	* but WITHOUT ANY WARRANTY; without even the implied warranty of *
14	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
15	* GNU General Public License for more details. *
16	* *
17	* You should have received a copy of the GNU General Public License *
18	* along with this program; if not, write to the Free Software *
19	* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
20	* MA 02111-1307 USA *
21	***************************************************************************/
22
23	#ifndef __LS_AUDIOOUTPUTDEVICE_H__
24	#define __LS_AUDIOOUTPUTDEVICE_H__
25
26	#include <set>
27	#include <map>
28	#include <vector>
29	#include <stdexcept>
30
31	#include "../common/global.h"
32	#include "../common/LinuxSamplerException.h"
33	#include "../drivers/DeviceParameter.h"
34	#include "../engines/common/Engine.h"
35	#include "AudioChannel.h"
36
37	namespace LinuxSampler {
38
39	// just symbol prototyping
40	class Engine;
41
42	/** Abstract base class for audio output drivers in LinuxSampler
43	*
44	* This class will be derived by specialized classes which implement the
45	* connection to a specific audio output system (e.g. Alsa, Jack,
46	* CoreAudio).
47	*/
48	class AudioOutputDevice {
49	public:
50
51
52	/////////////////////////////////////////////////////////////////
53	// type definitions
54
55	class ParameterActive : public DeviceCreationParameterBool {
56	public:
57	ParameterActive(AudioOutputDevice* pDevice) { this->pDevice = pDevice; InitWithDefault(); }
58	ParameterActive(AudioOutputDevice* pDevice, String active) throw (LinuxSamplerException) : DeviceCreationParameterBool(active) { this->pDevice = pDevice; }
59	virtual String Description() { return "Enable / disable device"; }
60	virtual bool Fix() { return false; }
61	virtual bool Mandatory() { return false; }
62	virtual std::map<String,DeviceCreationParameter> DependsAsParameters() { return std::map<String,DeviceCreationParameter>(); }
63	virtual optional<bool> DefaultAsBool(std::map<String,String> Parameters) { return true; }
64	virtual void OnSetValue(bool b) throw (LinuxSamplerException) { if (b) pDevice->Play(); else pDevice->Stop(); }
65	protected:
66	AudioOutputDevice* pDevice;
67	};
68
69	class ParameterSampleRate : public DeviceCreationParameterInt {
70	public:
71	ParameterSampleRate(AudioOutputDevice* pDevice) { this->pDevice = pDevice; InitWithDefault(); }
72	ParameterSampleRate(AudioOutputDevice* pDevice, String samplerate) throw (LinuxSamplerException) : DeviceCreationParameterInt(samplerate) { this->pDevice = pDevice; }
73	virtual String Description() { return "Output sample rate"; }
74	virtual bool Fix() { return true; }
75	virtual bool Mandatory() { return false; }
76	virtual std::map<String,DeviceCreationParameter> DependsAsParameters() { return std::map<String,DeviceCreationParameter>(); }
77	virtual optional<int> DefaultAsInt(std::map<String,String> Parameters) { return 44100; }
78	virtual optional<int> RangeMinAsInt(std::map<String,String> Parameters) { return optional<int>::nothing; }
79	virtual optional<int> RangeMaxAsInt(std::map<String,String> Parameters) { return optional<int>::nothing; }
80	virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) { return std::vector<int>(); }
81	virtual void OnSetValue(int i) throw (LinuxSamplerException) { /* cannot happen, as parameter is fix */ }
82	protected:
83	AudioOutputDevice* pDevice;
84	};
85
86	class ParameterChannels : public DeviceCreationParameterInt {
87	public:
88	ParameterChannels(AudioOutputDevice* pDevice) { this->pDevice = pDevice; InitWithDefault(); }
89	ParameterChannels(AudioOutputDevice* pDevice, String channels) throw (LinuxSamplerException) : DeviceCreationParameterInt(channels) { this->pDevice = pDevice; }
90	virtual String Description() { return "Number of output channels"; }
91	virtual bool Fix() { return false; }
92	virtual bool Mandatory() { return false; }
93	virtual std::map<String,DeviceCreationParameter> DependsAsParameters() { return std::map<String,DeviceCreationParameter>(); }
94	virtual optional<int> DefaultAsInt(std::map<String,String> Parameters) { return 2; }
95	virtual optional<int> RangeMinAsInt(std::map<String,String> Parameters) { return optional<int>::nothing; }
96	virtual optional<int> RangeMaxAsInt(std::map<String,String> Parameters) { return optional<int>::nothing; }
97	virtual std::vector<int> PossibilitiesAsInt(std::map<String,String> Parameters) { return std::vector<int>(); }
98	virtual void OnSetValue(int i) throw (LinuxSamplerException) { pDevice->AcquireChannels(i); }
99	protected:
100	AudioOutputDevice* pDevice;
101	};
102
103	template <class Parameter_T>
104	class OptionalParameter {
105	public:
106	static Parameter_T* New(AudioOutputDevice* pDevice, String val) { if (val == "") return (new Parameter_T(pDevice)); return (new Parameter_T(pDevice, val)); }
107	};
108
109	/////////////////////////////////////////////////////////////////
110	// abstract methods
111	// (these have to be implemented by the descendant)
112
113	/**
114	* Start playback of audio signal on the audio device. It's the
115	* responsibility of the implementing audio device to call the
116	* RenderAudio(uint Samples) method of all connected engines.
117	* This will cause the engines to continue to render 'Samples'
118	* number of audio sample points and the engines will
119	* automatically add their audio signals to the audio buffers of
120	* the audio channels of this audio device. So the implementing
121	* audio device just has to access the buffers of it's audio
122	* channels.
123	*
124	* @throws AudioOutputException if playback can not be started
125	* @see AudioChannel
126	*/
127	virtual void Play() = 0;
128
129	/**
130	* Returns true if the audio device is currently playing back.
131	*/
132	virtual bool IsPlaying() = 0;
133
134	/**
135	* Stop playback of audio signal on the audio device. The
136	* implementing audio device will stop calling the RenderAudio()
137	* method of all connected engines and close it's connection to
138	* audio output system.
139	*/
140	virtual void Stop() = 0;
141
142	/**
143	* This method will usually be called by the sampler engines that
144	* are connected to this audio device to inform the audio device
145	* how much audio channels the engine(s) need. It's the
146	* responsibility of the audio device to offer that amount of
147	* audio channels - again: this is not an option this is a must!
148	* The engines will assume to be able to access those audio
149	* channels right after. If the audio driver is not able to offer
150	* that much channels, it can simply create mix channels which
151	* are then just mixed to the 'real' audio channels. See
152	* AudioChannel.h for details about channels and mix channels.
153	*
154	* @param Channels - amount of output channels required by
155	* a sampler engine
156	* @throws AudioOutputException if desired amount of channels
157	* cannot be offered
158	* @see AudioChannel
159	*/
160	virtual void AcquireChannels(uint Channels) = 0;
161
162	/**
163	* Maximum amount of sample points the implementing audio
164	* device will ever demand the sampler engines to write in one
165	* fragment cycle / period. Simple audio device drivers usually
166	* have a fixed fragment size, so those devices just would return
167	* the fragment size in this method.
168	*
169	* @returns max. amount of sample points ever
170	*/
171	virtual uint MaxSamplesPerCycle() = 0;
172
173	/**
174	* Playback samplerate the audio device uses. The sampler engines
175	* currently assume this to be a constant value for the whole
176	* life time of an instance of the implementing audio device.
177	*
178	* @returns sample rate in Hz
179	*/
180	virtual uint SampleRate() = 0;
181
182	static std::map<String,DeviceCreationParameter*> AvailableParameters();
183
184	/**
185	* Return the audio output device driver type name.
186	*/
187	virtual String Driver() = 0;
188
189
190
191	/////////////////////////////////////////////////////////////////
192	// normal methods
193	// (usually not to be overriden by descendant)
194
195	/**
196	* Connect given sampler engine to this audio output device. The
197	* engine will be added to the Engines container of this audio
198	* device and the engine will also automatically be informed
199	* about the connection.
200	*
201	* @param pEngine - sampler engine
202	*/
203	void Connect(Engine* pEngine);
204
205	/**
206	* Disconnect given sampler engine from this audio output device.
207	* Removes given sampler engine reference from the Engines
208	* container of this audio device.
209	*
210	* @param pEngine - sampler engine
211	*/
212	void Disconnect(Engine* pEngine);
213
214	/**
215	* Returns audio channel with index \a ChannelIndex or NULL if
216	* index out of bounds.
217	*/
218	AudioChannel* Channel(uint ChannelIndex);
219
220	std::map<String,DeviceCreationParameter*> DeviceParameters();
221
222
223	protected:
224	std::set<Engine*> Engines; ///< All sampler engines that are connected to the audio output device.
225	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.
226	std::map<String,DeviceCreationParameter*> Parameters; ///< All device parameters.
227
228	AudioOutputDevice(std::map<String,DeviceCreationParameter*> DriverParameters);
229
230	virtual ~AudioOutputDevice();
231
232	/**
233	* This method should be called by the AudioOutputDevice
234	* descendant to let all connected engines proceed to render the
235	* given amount of sample points. The engines will place their
236	* calculated audio data by themselfes into the buffers of the
237	* respective AudioChannel objects, so the implementing audio
238	* output device just has to copy the AudioChannel buffers to
239	* the output buffer(s) of its audio system.
240	*
241	* @returns 0 on success or the last error return code of one
242	* engine
243	*/
244	int RenderAudio(uint Samples);
245
246	/**
247	* This can be called as an alternative to RenderAudio() for
248	* just writing silence to the audio output buffers and not
249	* calling the connected sampler engines for rendering audio, so
250	* to provide a method to stop playback if the used audio output
251	* system doesn't provide a better way.
252	*
253	* @returns 0 on success
254	*/
255	int RenderSilence(uint Samples);
256
257	friend class Sampler; // allow Sampler class to destroy audio devices
258
259	private:
260	static std::map<String,DeviceCreationParameter*> CreateAvailableParameters();
261	};
262
263	/**
264	* Audio output exception that should be thrown by the AudioOutputDevice
265	* descendants in case initialization of the audio output system failed
266	* (which should be done in the constructor of the AudioOutputDevice
267	* descendant).
268	*/
269	class AudioOutputException : public LinuxSamplerException {
270	public:
271	AudioOutputException(const std::string& msg) : LinuxSamplerException(msg) {}
272	};
273	}
274
275	#endif // __LS_AUDIOOUTPUTDEVICE_H__