/[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 412 - (hide annotations) (download) (as text)
Sat Feb 26 22:44:51 2005 UTC (19 years, 1 month 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 schoenebeck 200 /***************************************************************************
2     * *
3     * LinuxSampler - modular, streaming capable sampler *
4     * *
5     * Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6 schoenebeck 411 * Copyright (C) 2005 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     #include "../../common/LinuxSamplerException.h"
34 schoenebeck 207 #include "../Device.h"
35 schoenebeck 200 #include "../DeviceParameter.h"
36 schoenebeck 412 #include "../../engines/common/Engine.h"
37 schoenebeck 200 #include "AudioChannel.h"
38    
39     namespace LinuxSampler {
40    
41     // just symbol prototyping
42 schoenebeck 412 class Engine;
43 schoenebeck 200
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 schoenebeck 207 class AudioOutputDevice : public Device {
51 schoenebeck 200 public:
52    
53     /////////////////////////////////////////////////////////////////
54     // Device parameters
55    
56 schoenebeck 221 /** Device Parameter 'ACTIVE'
57     *
58     * Used to activate / deactivate the audio output device.
59     */
60 schoenebeck 200 class ParameterActive : public DeviceCreationParameterBool {
61     public:
62 schoenebeck 226 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 schoenebeck 200 };
72    
73 schoenebeck 221 /** Device Parameter 'SAMPLERATE'
74     *
75     * Used to set the sample rate of the audio output device.
76     */
77 schoenebeck 200 class ParameterSampleRate : public DeviceCreationParameterInt {
78     public:
79 schoenebeck 226 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 schoenebeck 200 };
92    
93 schoenebeck 221 /** Device Parameters 'CHANNELS'
94     *
95     * Used to increase / decrease the number of audio channels of
96     * audio output device.
97     */
98 schoenebeck 200 class ParameterChannels : public DeviceCreationParameterInt {
99     public:
100 schoenebeck 226 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 schoenebeck 200 };
113    
114    
115 schoenebeck 221
116 schoenebeck 200 /////////////////////////////////////////////////////////////////
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 schoenebeck 226 * Return the audio output device driver name.
171 schoenebeck 200 */
172     virtual String Driver() = 0;
173    
174 schoenebeck 226 /**
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 schoenebeck 200 /////////////////////////////////////////////////////////////////
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 schoenebeck 412 * @param pEngine - sampler engine
193 schoenebeck 200 */
194 schoenebeck 412 void Connect(Engine* pEngine);
195 schoenebeck 200
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 schoenebeck 412 * @param pEngine - sampler engine
202 schoenebeck 200 */
203 schoenebeck 412 void Disconnect(Engine* pEngine);
204 schoenebeck 200
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 schoenebeck 221 /**
212 schoenebeck 226 * 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 schoenebeck 221 * Returns all device parameter settings.
233     */
234 schoenebeck 200 std::map<String,DeviceCreationParameter*> DeviceParameters();
235    
236     protected:
237 schoenebeck 412 std::set<Engine*> Engines; ///< All sampler engines that are connected to the audio output device.
238 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.
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