Added jack audio support, building with cmake only currently, feel free to add scons...
[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_JACK
185 } AUD_Error;
186
187 /// Message codes.
188 typedef enum
189 {
190         AUD_MSG_INVALID = 0,                    /// Invalid message.
191         AUD_MSG_LOOP,                                   /// Loop reader message.
192         AUD_MSG_VOLUME                                  /// Volume reader message.
193 } AUD_MessageType;
194
195 /// Fading types.
196 typedef enum
197 {
198         AUD_FADE_IN,
199         AUD_FADE_OUT
200 } AUD_FadeType;
201
202 /// 3D device settings.
203 typedef enum
204 {
205         AUD_3DS_NONE,                                   /// No setting.
206         AUD_3DS_SPEED_OF_SOUND,                 /// Speed of sound.
207         AUD_3DS_DOPPLER_FACTOR,                 /// Doppler factor.
208         AUD_3DS_DISTANCE_MODEL                  /// Distance model.
209 } AUD_3DSetting;
210
211 /// Possible distance models for the 3D device.
212 #define AUD_DISTANCE_MODEL_NONE                                 0.0f
213 #define AUD_DISTANCE_MODEL_INVERSE                              1.0f
214 #define AUD_DISTANCE_MODEL_INVERSE_CLAMPED              2.0f
215 #define AUD_DISTANCE_MODEL_LINEAR                               3.0f
216 #define AUD_DISTANCE_MODEL_LINEAR_CLAMPED               4.0f
217 #define AUD_DISTANCE_MODEL_EXPONENT                             5.0f
218 #define AUD_DISTANCE_MODEL_EXPONENT_CLAMPED             6.0f
219
220 /// 3D source settings.
221 typedef enum
222 {
223         AUD_3DSS_NONE,                                  /// No setting.
224         AUD_3DSS_IS_RELATIVE,                   /// > 0 tells that the sound source is
225                                                                         /// relative to the listener
226         AUD_3DSS_MIN_GAIN,                              /// Minimum gain.
227         AUD_3DSS_MAX_GAIN,                              /// Maximum gain.
228         AUD_3DSS_REFERENCE_DISTANCE,    /// Reference distance.
229         AUD_3DSS_MAX_DISTANCE,                  /// Maximum distance.
230         AUD_3DSS_ROLLOFF_FACTOR,                /// Rolloff factor.
231         AUD_3DSS_CONE_INNER_ANGLE,              /// Cone inner angle.
232         AUD_3DSS_CONE_OUTER_ANGLE,              /// Cone outer angle.
233         AUD_3DSS_CONE_OUTER_GAIN                /// Cone outer gain.
234 } AUD_3DSourceSetting;
235
236 /// Sample pointer type.
237 typedef unsigned char sample_t;
238
239 /// Specification of a sound source or device.
240 typedef struct
241 {
242         /// Sample rate in Hz.
243         AUD_SampleRate rate;
244
245         /// Sample format.
246         AUD_SampleFormat format;
247
248         /// Channel count.
249         AUD_Channels channels;
250 } AUD_Specs;
251
252 /// Exception structure.
253 typedef struct
254 {
255         /**
256          * Error code.
257          * \see AUD_Error
258          */
259         AUD_Error error;
260
261         // void* userData; - for the case it is needed someday
262 } AUD_Exception;
263
264 /// Message structure.
265 typedef struct
266 {
267         /**
268          * The message type.
269          */
270         AUD_MessageType type;
271
272         union
273         {
274                 // loop reader
275                 int loopcount;
276
277                 // volume reader
278                 float volume;
279         };
280 } AUD_Message;
281
282 /// Handle structure, for inherition.
283 typedef struct
284 {
285         /// x, y and z coordinates of the object.
286         float position[3];
287
288         /// x, y and z coordinates telling the velocity and direction of the object.
289         float velocity[3];
290
291         /// 3x3 matrix telling the orientation of the object.
292         float orientation[9];
293 } AUD_3DData;
294
295 #endif //AUD_SPACE