drivers/audio/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 "../Device.h"
#include "../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 Device {
        public:

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

            /** Device Parameter 'ACTIVE'
             *
             * Used to activate / deactivate the audio output device.
             */
            class ParameterActive : public DeviceCreationParameterBool {
                public:
                    ParameterActive( void ) : DeviceCreationParameterBool()                  { InitWithDefault();                                  }
                    ParameterActive( String s ) : DeviceCreationParameterBool(s)             {}
                    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) ((AudioOutputDevice*)pDevice)->Play(); else ((AudioOutputDevice*)pDevice)->Stop();       }
                    static String Name() { return "ACTIVE"; }
            };

            /** Device Parameter 'SAMPLERATE'
             *
             * Used to set the sample rate of the audio output device.
             */
            class ParameterSampleRate : public DeviceCreationParameterInt {
                public:
                    ParameterSampleRate() : DeviceCreationParameterInt()                            { InitWithDefault();                                  }
                    ParameterSampleRate( String s ) : DeviceCreationParameterInt(s)                 {}
                    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 */            }
                    static String Name() { return "SAMPLERATE"; }
            };

            /** Device Parameters 'CHANNELS'
             *
             * Used to increase / decrease the number of audio channels of
             * audio output device.
             */
            class ParameterChannels : public DeviceCreationParameterInt {
                public:
                    ParameterChannels() : DeviceCreationParameterInt()                              { InitWithDefault();                                  }
                    ParameterChannels( String s ) : DeviceCreationParameterInt(s)                   {}
                    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)        { ((AudioOutputDevice*)pDevice)->AcquireChannels(i);    }
                    static String Name() { return "CHANNELS"; }
            };


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

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

            /**
             * Returns all device parameter settings.
             */
            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

    };

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