src/audiodriver/AudioOutputDevice.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __LS_AUDIOOUTPUTDEVICE_H__
#define __LS_AUDIOOUTPUTDEVICE_H__

#include <set>
#include <vector>
#include <stdexcept>

#include "../common/global.h"
#include "../common/LinuxSamplerException.h"
#include "../engines/common/Engine.h"
#include "AudioChannel.h"

namespace LinuxSampler {

    // just symbol prototyping
    class Engine;

    /** Abstract base class for audio output drivers in LinuxSampler
     *
     * This class will be derived by specialized classes which implement the
     * connection to a specific audio output system (e.g. Alsa, Jack,
     * CoreAudio).
     */
    class AudioOutputDevice {
        public:

            /////////////////////////////////////////////////////////////////
            // type definitions

            /**
             * List of all currently implemented audio output drivers.
             */
            enum type_t {
                type_alsa,
                type_jack
            };


            /////////////////////////////////////////////////////////////////
            // abstract methods
            //     (these have to be implemented by the descendant)

            /**
             * Start playback of audio signal on the audio device. It's the
             * responsibility of the implementing audio device to call the
             * RenderAudio(uint Samples) method of all connected engines.
             * This will cause the engines to continue to render 'Samples'
             * number of audio sample points and the engines will
             * automatically add their audio signals to the audio buffers of
             * the audio channels of this audio device. So the implementing
             * audio device just has to access the buffers of it's audio
             * channels.
             *
             * @throws AudioOutputException  if playback can not be started
             * @see AudioChannel
             */
            virtual void Play() = 0;

            /**
             * Returns true if the audio device is currently playing back.
             */
            virtual bool IsPlaying() = 0;

            /**
             * Stop playback of audio signal on the audio device. The
             * implementing audio device will stop calling the RenderAudio()
             * method of all connected engines and close it's connection to
             * audio output system.
             */
            virtual void Stop() = 0;

            /**
             * This method will usually be called by the sampler engines that
             * are connected to this audio device to inform the audio device
             * how much audio channels the engine(s) need. It's the
             * responsibility of the audio device to offer that amount of
             * audio channels - again: this is not an option this is a must!
             * The engines will assume to be able to access those audio
             * channels right after. If the audio driver is not able to offer
             * that much channels, it can simply create mix channels which
             * are then just mixed to the 'real' audio channels. See
             * AudioChannel.h for details about channels and mix channels.
             *
             * @param Channels - amount of output channels required by
             *                   a sampler engine
             * @throws AudioOutputException  if desired amount of channels
             *                               cannot be offered
             * @see AudioChannel
             */
            virtual void AcquireChannels(uint Channels) = 0;

            /**
             * Maximum amount of sample points the implementing audio
             * device will ever demand the sampler engines to write in one
             * fragment cycle / period. Simple audio device drivers usually
             * have a fixed fragment size, so those devices just would return
             * the fragment size in this method.
             *
             * @returns  max. amount of sample points ever
             */
            virtual uint MaxSamplesPerCycle() = 0;

            /**
             * Playback samplerate the audio device uses. The sampler engines
             * currently assume this to be a constant value for the whole
             * life time of an instance of the implementing audio device.
             *
             * @returns  sample rate in Hz
             */
            virtual uint SampleRate() = 0;


            /////////////////////////////////////////////////////////////////
            // normal methods
            //     (usually not to be overriden by descendant)

            /**
             * Connect given sampler engine to this audio output device. The
             * engine will be added to the Engines container of this audio
             * device and the engine will also automatically be informed
             * about the connection.
             *
             * @param pEngine - sampler engine
             */
            void Connect(Engine* pEngine);

            /**
             * Disconnect given sampler engine from this audio output device.
             * Removes given sampler engine reference from the Engines
             * container of this audio device.
             *
             * @param pEngine - sampler engine
             */
            void Disconnect(Engine* pEngine);

            /**
             * Returns audio channel with index \a ChannelIndex or NULL if
             * index out of bounds.
             */
            AudioChannel* Channel(uint ChannelIndex);

            /**
             * Returns the ID that identifies the implementing audio output
             * driver.
             */
            type_t Type();

        protected:
            std::set<Engine*>          Engines;  ///< All sampler engines that are connected to the audio output device.
            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.
            type_t                     AudioOutputType;

            /**
             * Constructor. Has to be called by the implementing audio
             * output driver to define the ID of the driver. When a new
             * audio output driver is implemented, the
             * AudioOutputDevice::type_t enumeration has to be extended with
             * a new ID for the new audio output driver.
             */
            AudioOutputDevice(type_t Type);

            /**
             * This method should be called by the AudioOutputDevice
             * descendant to let all connected engines proceed to render the
             * given amount of sample points. The engines will place their
             * calculated audio data by themselfes into the buffers of the
             * respective AudioChannel objects, so the implementing audio
             * output device just has to copy the AudioChannel buffers to
             * the output buffer(s) of its audio system.
             *
             * @returns  0 on success or the last error return code of one
             *           engine
             */
            int RenderAudio(uint Samples);

            /**
             * This can be called as an alternative to RenderAudio() for
             * just writing silence to the audio output buffers and not
             * calling the connected sampler engines for rendering audio, so
             * to provide a method to stop playback if the used audio output
             * system doesn't provide a better way.
             *
             * @returns  0 on success
             */
            int RenderSilence(uint Samples);
    };

    /**
     * Audio output exception that should be thrown by the AudioOutputDevice
     * descendants in case initialization of the audio output system failed
     * (which should be done in the constructor of the AudioOutputDevice
     * descendant).
     */
    class AudioOutputException : public LinuxSamplerException {
        public:
            AudioOutputException(const std::string& msg) : LinuxSamplerException(msg) {}
    };
}

#endif // __LS_AUDIOOUTPUTDEVICE_H__
1	schoenebeck	53	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5	schoenebeck	56	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	schoenebeck	53	* *
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 <vector>
28			#include <stdexcept>
29
30			#include "../common/global.h"
31			#include "../common/LinuxSamplerException.h"
32			#include "../engines/common/Engine.h"
33			#include "AudioChannel.h"
34
35			namespace LinuxSampler {
36
37			// just symbol prototyping
38			class Engine;
39
40			/** Abstract base class for audio output drivers in LinuxSampler
41			*
42			* This class will be derived by specialized classes which implement the
43			* connection to a specific audio output system (e.g. Alsa, Jack,
44			* CoreAudio).
45			*/
46			class AudioOutputDevice {
47			public:
48
49			/////////////////////////////////////////////////////////////////
50	schoenebeck	64	// type definitions
51
52			/**
53			* List of all currently implemented audio output drivers.
54			*/
55			enum type_t {
56			type_alsa,
57			type_jack
58			};
59
60
61
62			/////////////////////////////////////////////////////////////////
63	schoenebeck	53	// abstract methods
64			// (these have to be implemented by the descendant)
65
66			/**
67			* Start playback of audio signal on the audio device. It's the
68			* responsibility of the implementing audio device to call the
69			* RenderAudio(uint Samples) method of all connected engines.
70			* This will cause the engines to continue to render 'Samples'
71			* number of audio sample points and the engines will
72			* automatically add their audio signals to the audio buffers of
73			* the audio channels of this audio device. So the implementing
74			* audio device just has to access the buffers of it's audio
75			* channels.
76			*
77			* @throws AudioOutputException if playback can not be started
78			* @see AudioChannel
79			*/
80			virtual void Play() = 0;
81
82			/**
83			* Returns true if the audio device is currently playing back.
84			*/
85			virtual bool IsPlaying() = 0;
86
87			/**
88			* Stop playback of audio signal on the audio device. The
89			* implementing audio device will stop calling the RenderAudio()
90			* method of all connected engines and close it's connection to
91			* audio output system.
92			*/
93			virtual void Stop() = 0;
94
95			/**
96			* This method will usually be called by the sampler engines that
97			* are connected to this audio device to inform the audio device
98			* how much audio channels the engine(s) need. It's the
99			* responsibility of the audio device to offer that amount of
100			* audio channels - again: this is not an option this is a must!
101			* The engines will assume to be able to access those audio
102			* channels right after. If the audio driver is not able to offer
103			* that much channels, it can simply create mix channels which
104			* are then just mixed to the 'real' audio channels. See
105			* AudioChannel.h for details about channels and mix channels.
106			*
107			* @param Channels - amount of output channels required by
108			* a sampler engine
109			* @throws AudioOutputException if desired amount of channels
110			* cannot be offered
111			* @see AudioChannel
112			*/
113			virtual void AcquireChannels(uint Channels) = 0;
114
115			/**
116			* Maximum amount of sample points the implementing audio
117			* device will ever demand the sampler engines to write in one
118			* fragment cycle / period. Simple audio device drivers usually
119			* have a fixed fragment size, so those devices just would return
120			* the fragment size in this method.
121			*
122			* @returns max. amount of sample points ever
123			*/
124			virtual uint MaxSamplesPerCycle() = 0;
125
126			/**
127			* Playback samplerate the audio device uses. The sampler engines
128			* currently assume this to be a constant value for the whole
129			* life time of an instance of the implementing audio device.
130			*
131			* @returns sample rate in Hz
132			*/
133			virtual uint SampleRate() = 0;
134
135
136
137			/////////////////////////////////////////////////////////////////
138			// normal methods
139			// (usually not to be overriden by descendant)
140
141			/**
142			* Connect given sampler engine to this audio output device. The
143			* engine will be added to the Engines container of this audio
144			* device and the engine will also automatically be informed
145			* about the connection.
146			*
147			* @param pEngine - sampler engine
148			*/
149			void Connect(Engine* pEngine);
150
151			/**
152			* Disconnect given sampler engine from this audio output device.
153			* Removes given sampler engine reference from the Engines
154			* container of this audio device.
155			*
156			* @param pEngine - sampler engine
157			*/
158			void Disconnect(Engine* pEngine);
159
160			/**
161			* Returns audio channel with index \a ChannelIndex or NULL if
162			* index out of bounds.
163			*/
164			AudioChannel* Channel(uint ChannelIndex);
165
166	schoenebeck	64	/**
167			* Returns the ID that identifies the implementing audio output
168			* driver.
169			*/
170			type_t Type();
171
172	schoenebeck	53	protected:
173			std::set<Engine*> Engines; ///< All sampler engines that are connected to the audio output device.
174			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.
175	schoenebeck	64	type_t AudioOutputType;
176	schoenebeck	53
177			/**
178	schoenebeck	64	* Constructor. Has to be called by the implementing audio
179			* output driver to define the ID of the driver. When a new
180			* audio output driver is implemented, the
181			* AudioOutputDevice::type_t enumeration has to be extended with
182			* a new ID for the new audio output driver.
183			*/
184			AudioOutputDevice(type_t Type);
185
186			/**
187	schoenebeck	53	* This method should be called by the AudioOutputDevice
188			* descendant to let all connected engines proceed to render the
189			* given amount of sample points. The engines will place their
190			* calculated audio data by themselfes into the buffers of the
191			* respective AudioChannel objects, so the implementing audio
192			* output device just has to copy the AudioChannel buffers to
193			* the output buffer(s) of its audio system.
194			*
195			* @returns 0 on success or the last error return code of one
196			* engine
197			*/
198			int RenderAudio(uint Samples);
199
200			/**
201			* This can be called as an alternative to RenderAudio() for
202			* just writing silence to the audio output buffers and not
203			* calling the connected sampler engines for rendering audio, so
204			* to provide a method to stop playback if the used audio output
205			* system doesn't provide a better way.
206			*
207			* @returns 0 on success
208			*/
209			int RenderSilence(uint Samples);
210			};
211
212			/**
213			* Audio output exception that should be thrown by the AudioOutputDevice
214			* descendants in case initialization of the audio output system failed
215			* (which should be done in the constructor of the AudioOutputDevice
216			* descendant).
217			*/
218			class AudioOutputException : public LinuxSamplerException {
219			public:
220			AudioOutputException(const std::string& msg) : LinuxSamplerException(msg) {}
221			};
222			}
223
224			#endif // __LS_AUDIOOUTPUTDEVICE_H__