4170e27457462d12ae7f04db125c4fe52bb45552
[blender-staging.git] / intern / audaspace / intern / AUD_IDevice.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN LGPL LICENSE BLOCK *****
5  *
6  * Copyright 2009 Jörg Hermann Müller
7  *
8  * This file is part of AudaSpace.
9  *
10  * AudaSpace is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU Lesser General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * AudaSpace is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU Lesser General Public License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public License
21  * along with AudaSpace.  If not, see <http://www.gnu.org/licenses/>.
22  *
23  * ***** END LGPL LICENSE BLOCK *****
24  */
25
26 #ifndef AUD_IDEVICE
27 #define AUD_IDEVICE
28
29 #include "AUD_Space.h"
30 class AUD_IFactory;
31
32 /// Handle structure, for inherition.
33 struct AUD_Handle
34 {
35 };
36
37 /**
38  * This class represents an output device for sound sources.
39  * Output devices may be several backends such as plattform independand like
40  * SDL or OpenAL or plattform specific like DirectSound, but they may also be
41  * files, RAM buffers or other types of streams.
42  * \warning Thread safety must be insured so that no reader is beeing called
43  *          twice at the same time.
44  */
45 class AUD_IDevice
46 {
47 public:
48         /**
49          * Destroys the device.
50          */
51         virtual ~AUD_IDevice() {}
52
53         /**
54          * Returns the specification of the device.
55          */
56         virtual AUD_DeviceSpecs getSpecs() const=0;
57
58         /**
59          * Plays a sound source.
60          * \param factory The factory to create the reader for the sound source.
61          * \param keep When keep is true the sound source will not be deleted but
62          *             set to paused when its end has been reached.
63          * \return Returns a handle with which the playback can be controlled.
64          *         This is NULL if the sound couldn't be played back.
65          * \exception AUD_Exception Thrown if there's an unexpected (from the
66          *            device side) error during creation of the reader.
67          */
68         virtual AUD_Handle* play(AUD_IFactory* factory, bool keep = false)=0;
69
70         /**
71          * Pauses a played back sound.
72          * \param handle The handle returned by the play function.
73          * \return
74          *        - true if the sound has been paused.
75          *        - false if the sound isn't playing back or the handle is invalid.
76          */
77         virtual bool pause(AUD_Handle* handle)=0;
78
79         /**
80          * Resumes a paused sound.
81          * \param handle The handle returned by the play function.
82          * \return
83          *        - true if the sound has been resumed.
84          *        - false if the sound isn't paused or the handle is invalid.
85          */
86         virtual bool resume(AUD_Handle* handle)=0;
87
88         /**
89          * Stops a played back or paused sound. The handle is definitely invalid
90          * afterwards.
91          * \param handle The handle returned by the play function.
92          * \return
93          *        - true if the sound has been stopped.
94          *        - false if the handle is invalid.
95          */
96         virtual bool stop(AUD_Handle* handle)=0;
97
98         /**
99          * Gets the behaviour of the device for a played back sound when the sound
100          * doesn't return any more samples.
101          * \param handle The handle returned by the play function.
102          * \return
103          *        - true if the source will be paused when it's end is reached
104          *        - false if the handle won't kept or is invalid.
105          */
106         virtual bool getKeep(AUD_Handle* handle)=0;
107
108         /**
109          * Sets the behaviour of the device for a played back sound when the sound
110          * doesn't return any more samples.
111          * \param handle The handle returned by the play function.
112          * \param keep True when the source should be paused and not deleted.
113          * \return
114          *        - true if the behaviour has been changed.
115          *        - false if the handle is invalid.
116          */
117         virtual bool setKeep(AUD_Handle* handle, bool keep)=0;
118
119         /**
120          * Seeks in a played back sound.
121          * \param handle The handle returned by the play function.
122          * \param position The new position from where to play back, in seconds.
123          * \return
124          *        - true if the handle is valid.
125          *        - false if the handle is invalid.
126          * \warning Whether the seek works or not depends on the sound source.
127          */
128         virtual bool seek(AUD_Handle* handle, float position)=0;
129
130         /**
131          * Retrieves the current playback position of a sound.
132          * \param handle The handle returned by the play function.
133          * \return The playback position in seconds, or 0.0 if the handle is
134          *         invalid.
135          */
136         virtual float getPosition(AUD_Handle* handle)=0;
137
138         /**
139          * Returns the status of a played back sound.
140          * \param handle The handle returned by the play function.
141          * \return
142          *        - AUD_STATUS_INVALID if the sound has stopped or the handle is
143          *.         invalid
144          *        - AUD_STATUS_PLAYING if the sound is currently played back.
145          *        - AUD_STATUS_PAUSED if the sound is currently paused.
146          * \see AUD_Status
147          */
148         virtual AUD_Status getStatus(AUD_Handle* handle)=0;
149
150         /**
151          * Locks the device.
152          * Used to make sure that between lock and unlock, no buffers are read, so
153          * that it is possible to start, resume, pause, stop or seek several
154          * playback handles simultaneously.
155          * \warning Make sure the locking time is as small as possible to avoid
156          *          playback delays that result in unexpected noise and cracks.
157          */
158         virtual void lock()=0;
159
160         /**
161          * Unlocks the previously locked device.
162          */
163         virtual void unlock()=0;
164
165         /**
166          * Retrieves the overall device volume.
167          * \return The overall device volume.
168          */
169         virtual float getVolume() const=0;
170
171         /**
172          * Sets the overall device volume.
173          * \param handle The sound handle.
174          * \param volume The overall device volume.
175          */
176         virtual void setVolume(float volume)=0;
177
178         /**
179          * Retrieves the volume of a playing sound.
180          * \param handle The sound handle.
181          * \return The volume.
182          */
183         virtual float getVolume(AUD_Handle* handle)=0;
184
185         /**
186          * Sets the volume of a playing sound.
187          * \param handle The sound handle.
188          * \param volume The volume.
189          * \return
190          *        - true if the handle is valid.
191          *        - false if the handle is invalid.
192          */
193         virtual bool setVolume(AUD_Handle* handle, float volume)=0;
194
195         /**
196          * Retrieves the pitch of a playing sound.
197          * \return The pitch.
198          */
199         virtual float getPitch(AUD_Handle* handle)=0;
200
201         /**
202          * Sets the pitch of a playing sound.
203          * \param handle The sound handle.
204          * \param pitch The pitch.
205          * \return
206          *        - true if the handle is valid.
207          *        - false if the handle is invalid.
208          */
209         virtual bool setPitch(AUD_Handle* handle, float pitch)=0;
210 };
211
212 #endif //AUD_IDevice