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

  ViewVC Help
Powered by ViewVC