/[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 846 - (show annotations) (download) (as text)
Sun Mar 19 16:38:22 2006 UTC (18 years ago) by persson
File MIME type: text/x-c++hdr
File size: 13192 byte(s)
* more thread safety fixes: another fix for lscp "load engine" and
  midi thread. Sysex midi protected against lscp. Instrument loader
  thread protected against lscp thread.

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

  ViewVC Help
Powered by ViewVC