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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2198 - (show annotations) (download) (as text)
Sun Jul 3 18:06:51 2011 UTC (8 years, 10 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 /***************************************************************************
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__

  ViewVC Help
Powered by ViewVC