/[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 1607 - (hide annotations) (download) (as text)
Mon Dec 31 19:03:31 2007 UTC (16 years, 4 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 13381 byte(s)
* bugfix: the SAMPLERATE parameter of some drivers (e.g. JACK)
  reflected the wrong value

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

  ViewVC Help
Powered by ViewVC