/[svn]/linuxsampler/trunk/src/drivers/audio/AudioOutputDevice.h
ViewVC logotype

Annotation of /linuxsampler/trunk/src/drivers/audio/AudioOutputDevice.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2198 - (hide annotations) (download) (as text)
Sun Jul 3 18:06:51 2011 UTC (12 years, 9 months ago) by iliev
File MIME type: text/x-c++hdr
File size: 15547 byte(s)
* bugfix: LSCP command "REMOVE FX_SEND EFFECT" was broken
* fixed a bug in FxSend::SetDestinationEffect
* bugfix: parent was not set when effect instance is appended
* bugfix: was able to remove effect chain while FX send is connected to it
* bugfix: was able to remove effect instance from effect chain while
  FX send is connected to that instance

1 schoenebeck 200 /***************************************************************************
2     * *
3     * LinuxSampler - modular, streaming capable sampler *
4     * *
5     * Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6 schoenebeck 2137 * Copyright (C) 2005 - 2010 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     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 schoenebeck 880 virtual void OnSetValue(bool b) throw (Exception);
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     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 schoenebeck 1607 virtual int ValueAsInt();
94 schoenebeck 880 virtual void OnSetValue(int i) throw (Exception);
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     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 schoenebeck 880 virtual void OnSetValue(int i) throw (Exception);
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    
185    
186    
187 schoenebeck 200 /////////////////////////////////////////////////////////////////
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 schoenebeck 412 * @param pEngine - sampler engine
198 schoenebeck 200 */
199 schoenebeck 412 void Connect(Engine* pEngine);
200 schoenebeck 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 schoenebeck 412 * @param pEngine - sampler engine
207 schoenebeck 200 */
208 schoenebeck 412 void Disconnect(Engine* pEngine);
209 schoenebeck 200
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 schoenebeck 221 /**
217 schoenebeck 226 * 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 schoenebeck 1001 * 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 schoenebeck 221 * Returns all device parameter settings.
244     */
245 schoenebeck 200 std::map<String,DeviceCreationParameter*> DeviceParameters();
246    
247 schoenebeck 1722 /**
248 schoenebeck 2137 * Add a chain of send effects to this AudioOutputDevice.
249 schoenebeck 1722 * You actually have to add effects to that chain afterwards.
250     */
251 schoenebeck 2137 EffectChain* AddSendEffectChain();
252 schoenebeck 1722
253     /**
254 schoenebeck 2137 * Remove the send effect chain given by @a iChain .
255 schoenebeck 1722 *
256 schoenebeck 2137 * @throws Exception - if given send effect chain doesn't exist
257 schoenebeck 1722 */
258 schoenebeck 2137 void RemoveSendEffectChain(uint iChain) throw (Exception);
259 schoenebeck 1722
260     /**
261 schoenebeck 2137 * Returns send effect chain given by @a iChain or @c NULL if
262 schoenebeck 1722 * there's no such effect chain.
263     */
264 schoenebeck 2137 EffectChain* SendEffectChain(uint iChain) const;
265 schoenebeck 1722
266     /**
267 iliev 2198 * 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 schoenebeck 2137 * Returns amount of send effect chains this AudioOutputDevice
274 schoenebeck 1722 * currently provides.
275     */
276 schoenebeck 2137 uint SendEffectChainCount() const;
277 schoenebeck 1722
278 schoenebeck 2137 /**
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 schoenebeck 200 protected:
299 persson 840 SynchronizedConfig<std::set<Engine*> > Engines; ///< All sampler engines that are connected to the audio output device.
300 persson 846 SynchronizedConfig<std::set<Engine*> >::Reader EnginesReader; ///< Audio thread access to Engines.
301 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.
302     std::map<String,DeviceCreationParameter*> Parameters; ///< All device parameters.
303 schoenebeck 1722 std::vector<EffectChain*> vEffectChains;
304 schoenebeck 2135 IDGenerator* EffectChainIDs;
305 schoenebeck 200
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 schoenebeck 1934 friend class AudioOutputDeviceFactory; // allow AudioOutputDeviceFactory class to destroy audio devices
336 schoenebeck 200
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 schoenebeck 880 class AudioOutputException : public Exception {
346 schoenebeck 200 public:
347 schoenebeck 880 AudioOutputException(const std::string& msg) : Exception(msg) {}
348 schoenebeck 200 };
349     }
350    
351     #endif // __LS_AUDIOOUTPUTDEVICE_H__

  ViewVC Help
Powered by ViewVC