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

Contents of /linuxsampler/trunk/src/audiodriver/AudioOutputDevice.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 128 - (show annotations) (download) (as text)
Tue Jun 15 03:19:30 2004 UTC (13 years, 5 months ago) by senkov
File MIME type: text/x-c++hdr
File size: 14349 byte(s)
* Remove calls to pure virtual from constructor of base class
 to avoid runtime failure. InitWithDefault() will have to be called
 from the constructor of the class where virtuals are implemented.

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

  ViewVC Help
Powered by ViewVC