9c6cc70c314b21f6e802cd35d095995df5b7dd41
[blender-staging.git] / intern / audaspace / intern / AUD_Space.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_SPACE
27 #define AUD_SPACE
28
29 /// The size of a format in bytes.
30 #define AUD_FORMAT_SIZE(format) (format & 0x0F)
31 /// The size of a sample in the specified format in bytes.
32 #define AUD_SAMPLE_SIZE(specs) (specs.channels * (specs.format & 0x0F))
33 /// Throws a AUD_Exception with the provided error code.
34 #define AUD_THROW(exception) { AUD_Exception e; e.error = exception; throw e; }
35
36 /// Returns the smaller of the two values.
37 #define AUD_MIN(a, b) (((a) < (b)) ? (a) : (b))
38 /// Returns the bigger of the two values.
39 #define AUD_MAX(a, b) (((a) > (b)) ? (a) : (b))
40
41 // 5 sec * 44100 samples/sec * 4 bytes/sample * 6 channels
42 /// The size by which a buffer should be resized if the final extent is unknown.
43 #define AUD_BUFFER_RESIZE_BYTES 5292000
44
45 /// The default playback buffer size of a device.
46 #define AUD_DEFAULT_BUFFER_SIZE 1024
47
48 // Capability defines
49
50 /// This capability checks whether a device is a 3D device. See AUD_I3DDevice.h.
51 #define AUD_CAPS_3D_DEVICE                      0x0001
52
53 /**
54  * This capability checks whether a device is a software device. See
55  * AUD_SoftwareDevice.
56  */
57 #define AUD_CAPS_SOFTWARE_DEVICE        0x0002
58
59 /**
60  * This capability enables the user to set the overall volume of the device.
61  * You can set and get it with the pointer pointing to a float value between
62  * 0.0 (muted) and 1.0 (maximum volume).
63  */
64 #define AUD_CAPS_VOLUME                         0x0101
65
66 /**
67  * This capability enables the user to set the volume of a source.
68  * You can set and get it with the pointer pointing to a AUD_SourceValue
69  * structure defined in AUD_SourceCaps.h.
70  */
71 #define AUD_CAPS_SOURCE_VOLUME          0x1001
72
73 /**
74  * This capability enables the user to set the pitch of a source.
75  * You can set and get it with the pointer pointing to a AUD_SourceValue
76  * structure defined in AUD_SourceCaps.h.
77  */
78 #define AUD_CAPS_SOURCE_PITCH           0x1002
79
80 /**
81  * This capability enables the user to buffer a factory into the device.
82  * Setting with the factory as pointer loads the factory into a device internal
83  * buffer. Play function calls with the buffered factory as argument result in
84  * the internal buffer being played back, so there's no reader created, what
85  * also results in not being able to send messages to that handle.
86  * A repeated call with the same factory doesn't do anything.
87  * A set call with a NULL pointer results in all buffered factories being
88  * deleted.
89  * \note This is only possible with factories that create readers of the buffer
90  *       type.
91  */
92 #define AUD_CAPS_BUFFERED_FACTORY       0x2001
93
94 // Used for debugging memory leaks.
95 //#define AUD_DEBUG_MEMORY
96
97 #ifdef AUD_DEBUG_MEMORY
98 int AUD_References(int count = 0, const char* text = "");
99 #define AUD_NEW(text) AUD_References(1, text);
100 #define AUD_DELETE(text) AUD_References(-1, text);
101 #else
102 #define AUD_NEW(text)
103 #define AUD_DELETE(text)
104 #endif
105
106 /**
107  * The format of a sample.
108  * The last 4 bit save the byte count of the format.
109  */
110 typedef enum
111 {
112         AUD_FORMAT_INVALID = 0x00,              /// Invalid sample format.
113         AUD_FORMAT_U8      = 0x01,              /// 1 byte unsigned byte.
114         AUD_FORMAT_S16     = 0x12,              /// 2 byte signed integer.
115         AUD_FORMAT_S24     = 0x13,              /// 3 byte signed integer.
116         AUD_FORMAT_S32     = 0x14,              /// 4 byte signed integer.
117         AUD_FORMAT_FLOAT32 = 0x24,              /// 4 byte float.
118         AUD_FORMAT_FLOAT64 = 0x28               /// 8 byte float.
119 } AUD_SampleFormat;
120
121 /// The channel count.
122 typedef enum
123 {
124         AUD_CHANNELS_INVALID    = 0,    /// Invalid channel count.
125         AUD_CHANNELS_MONO       = 1,    /// Mono.
126         AUD_CHANNELS_STEREO     = 2,    /// Stereo.
127         AUD_CHANNELS_STEREO_LFE = 3,    /// Stereo with LFE channel.
128         AUD_CHANNELS_SURROUND4  = 4,    /// 4 channel surround sound.
129         AUD_CHANNELS_SURROUND5  = 5,    /// 5 channel surround sound.
130         AUD_CHANNELS_SURROUND51 = 6,    /// 5.1 surround sound.
131         AUD_CHANNELS_SURROUND61 = 7,    /// 6.1 surround sound.
132         AUD_CHANNELS_SURROUND71 = 8,    /// 7.1 surround sound.
133         AUD_CHANNELS_SURROUND72 = 9             /// 7.2 surround sound.
134 } AUD_Channels;
135
136 /**
137  * The sample rate tells how many samples are played back within one second.
138  * Some exotic formats may use other sample rates than provided here.
139  */
140 typedef enum
141 {
142         AUD_RATE_INVALID = 0,                   /// Invalid sample rate.
143         AUD_RATE_8000    = 8000,                /// 8000 Hz.
144         AUD_RATE_16000   = 16000,               /// 16000 Hz.
145         AUD_RATE_11025   = 11025,               /// 11025 Hz.
146         AUD_RATE_22050   = 22050,               /// 22050 Hz.
147         AUD_RATE_32000   = 32000,               /// 32000 Hz.
148         AUD_RATE_44100   = 44100,               /// 44100 Hz.
149         AUD_RATE_48000   = 48000,               /// 48000 Hz.
150         AUD_RATE_88200   = 88200,               /// 88200 Hz.
151         AUD_RATE_96000   = 96000,               /// 96000 Hz.
152         AUD_RATE_192000  = 192000               /// 192000 Hz.
153 } AUD_SampleRate;
154
155 /**
156  * Type of a reader.
157  * @see AUD_IReader for details.
158  */
159 typedef enum
160 {
161         AUD_TYPE_INVALID = 0,                   /// Invalid reader type.
162         AUD_TYPE_BUFFER,                                /// Reader reads from a buffer.
163         AUD_TYPE_STREAM                                 /// Reader reads from a stream.
164 } AUD_ReaderType;
165
166 /// Status of a playback handle.
167 typedef enum
168 {
169         AUD_STATUS_INVALID = 0,                 /// Invalid handle. Maybe due to stopping.
170         AUD_STATUS_PLAYING,                             /// Sound is playing.
171         AUD_STATUS_PAUSED                               /// Sound is being paused.
172 } AUD_Status;
173
174 /// Error codes for exceptions (C++ library) or for return values (C API).
175 typedef enum
176 {
177         AUD_NO_ERROR = 0,
178         AUD_ERROR_READER,
179         AUD_ERROR_FACTORY,
180         AUD_ERROR_FILE,
181         AUD_ERROR_FFMPEG,
182         AUD_ERROR_SDL,
183         AUD_ERROR_OPENAL
184 } AUD_Error;
185
186 /// Message codes.
187 typedef enum
188 {
189         AUD_MSG_INVALID = 0,                    /// Invalid message.
190         AUD_MSG_LOOP,                                   /// Loop reader message.
191         AUD_MSG_VOLUME                                  /// Volume reader message.
192 } AUD_MessageType;
193
194 /// Fading types.
195 typedef enum
196 {
197         AUD_FADE_IN,
198         AUD_FADE_OUT
199 } AUD_FadeType;
200
201 /// 3D device settings.
202 typedef enum
203 {
204         AUD_3DS_NONE,                                   /// No setting.
205         AUD_3DS_SPEED_OF_SOUND,                 /// Speed of sound.
206         AUD_3DS_DOPPLER_FACTOR,                 /// Doppler factor.
207         AUD_3DS_DISTANCE_MODEL                  /// Distance model.
208 } AUD_3DSetting;
209
210 /// Possible distance models for the 3D device.
211 #define AUD_DISTANCE_MODEL_NONE                                 0.0f
212 #define AUD_DISTANCE_MODEL_INVERSE                              1.0f
213 #define AUD_DISTANCE_MODEL_INVERSE_CLAMPED              2.0f
214 #define AUD_DISTANCE_MODEL_LINEAR                               3.0f
215 #define AUD_DISTANCE_MODEL_LINEAR_CLAMPED               4.0f
216 #define AUD_DISTANCE_MODEL_EXPONENT                             5.0f
217 #define AUD_DISTANCE_MODEL_EXPONENT_CLAMPED             6.0f
218
219 /// 3D source settings.
220 typedef enum
221 {
222         AUD_3DSS_NONE,                                  /// No setting.
223         AUD_3DSS_IS_RELATIVE,                   /// > 0 tells that the sound source is
224                                                                         /// relative to the listener
225         AUD_3DSS_MIN_GAIN,                              /// Minimum gain.
226         AUD_3DSS_MAX_GAIN,                              /// Maximum gain.
227         AUD_3DSS_REFERENCE_DISTANCE,    /// Reference distance.
228         AUD_3DSS_MAX_DISTANCE,                  /// Maximum distance.
229         AUD_3DSS_ROLLOFF_FACTOR,                /// Rolloff factor.
230         AUD_3DSS_CONE_INNER_ANGLE,              /// Cone inner angle.
231         AUD_3DSS_CONE_OUTER_ANGLE,              /// Cone outer angle.
232         AUD_3DSS_CONE_OUTER_GAIN                /// Cone outer gain.
233 } AUD_3DSourceSetting;
234
235 /// Sample pointer type.
236 typedef unsigned char sample_t;
237
238 /// Specification of a sound source or device.
239 typedef struct
240 {
241         /// Sample rate in Hz.
242         AUD_SampleRate rate;
243
244         /// Sample format.
245         AUD_SampleFormat format;
246
247         /// Channel count.
248         AUD_Channels channels;
249 } AUD_Specs;
250
251 /// Exception structure.
252 typedef struct
253 {
254         /**
255          * Error code.
256          * \see AUD_Error
257          */
258         AUD_Error error;
259
260         // void* userData; - for the case it is needed someday
261 } AUD_Exception;
262
263 /// Message structure.
264 typedef struct
265 {
266         /**
267          * The message type.
268          */
269         AUD_MessageType type;
270
271         union
272         {
273                 // loop reader
274                 int loopcount;
275
276                 // volume reader
277                 float volume;
278         };
279 } AUD_Message;
280
281 /// Handle structure, for inherition.
282 typedef struct
283 {
284         /// x, y and z coordinates of the object.
285         float position[3];
286
287         /// x, y and z coordinates telling the velocity and direction of the object.
288         float velocity[3];
289
290         /// 3x3 matrix telling the orientation of the object.
291         float orientation[9];
292 } AUD_3DData;
293
294 #endif //AUD_SPACE