3D Audio GSoC:
[blender.git] / intern / audaspace / intern / AUD_Space.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * Copyright 2009-2011 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 General Public License as published by
12  * the Free Software Foundation; either version 2 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 General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with Audaspace; if not, write to the Free Software Foundation,
22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23  *
24  * ***** END GPL LICENSE BLOCK *****
25  */
26
27 /** \file audaspace/intern/AUD_Space.h
28  *  \ingroup audaspaceintern
29  */
30
31
32 #ifndef AUD_SPACE
33 #define AUD_SPACE
34
35 /// The size of a format in bytes.
36 #define AUD_FORMAT_SIZE(format) (format & 0x0F)
37 /// The size of a sample in the specified device format in bytes.
38 #define AUD_DEVICE_SAMPLE_SIZE(specs) (specs.channels * (specs.format & 0x0F))
39 /// The size of a sample in the specified format in bytes.
40 #define AUD_SAMPLE_SIZE(specs) (specs.channels * sizeof(sample_t))
41 /// Throws a AUD_Exception with the provided error code.
42 #define AUD_THROW(exception, errorstr) { AUD_Exception e; e.error = exception; e.str = errorstr; throw e; }
43
44 /// Returns the bit for a channel mask.
45 #define AUD_CHANNEL_BIT(channel) (0x01 << channel)
46
47 /// Returns the smaller of the two values.
48 #define AUD_MIN(a, b) (((a) < (b)) ? (a) : (b))
49 /// Returns the bigger of the two values.
50 #define AUD_MAX(a, b) (((a) > (b)) ? (a) : (b))
51
52 // 5 sec * 44100 samples/sec * 4 bytes/sample * 6 channels
53 /// The size by which a buffer should be resized if the final extent is unknown.
54 #define AUD_BUFFER_RESIZE_BYTES 5292000
55
56 /// The default playback buffer size of a device.
57 #define AUD_DEFAULT_BUFFER_SIZE 1024
58
59 /**
60  * The format of a sample.
61  * The last 4 bit save the byte count of the format.
62  */
63 typedef enum
64 {
65         AUD_FORMAT_INVALID = 0x00,              /// Invalid sample format.
66         AUD_FORMAT_U8      = 0x01,              /// 1 byte unsigned byte.
67         AUD_FORMAT_S16     = 0x12,              /// 2 byte signed integer.
68         AUD_FORMAT_S24     = 0x13,              /// 3 byte signed integer.
69         AUD_FORMAT_S32     = 0x14,              /// 4 byte signed integer.
70         AUD_FORMAT_FLOAT32 = 0x24,              /// 4 byte float.
71         AUD_FORMAT_FLOAT64 = 0x28               /// 8 byte float.
72 } AUD_SampleFormat;
73
74 /// The channel count.
75 typedef enum
76 {
77         AUD_CHANNELS_INVALID    = 0,    /// Invalid channel count.
78         AUD_CHANNELS_MONO       = 1,    /// Mono.
79         AUD_CHANNELS_STEREO     = 2,    /// Stereo.
80         AUD_CHANNELS_STEREO_LFE = 3,    /// Stereo with LFE channel.
81         AUD_CHANNELS_SURROUND4  = 4,    /// 4 channel surround sound.
82         AUD_CHANNELS_SURROUND5  = 5,    /// 5 channel surround sound.
83         AUD_CHANNELS_SURROUND51 = 6,    /// 5.1 surround sound.
84         AUD_CHANNELS_SURROUND61 = 7,    /// 6.1 surround sound.
85         AUD_CHANNELS_SURROUND71 = 8     /// 7.1 surround sound.
86 } AUD_Channels;
87
88 /// The channel names.
89 typedef enum
90 {
91         AUD_CHANNEL_FRONT_LEFT = 0,
92         AUD_CHANNEL_FRONT_RIGHT,
93         AUD_CHANNEL_FRONT_CENTER,
94         AUD_CHANNEL_LFE,
95         AUD_CHANNEL_REAR_LEFT,
96         AUD_CHANNEL_REAR_RIGHT,
97         AUD_CHANNEL_REAR_CENTER,
98         AUD_CHANNEL_SIDE_LEFT,
99         AUD_CHANNEL_SIDE_RIGHT,
100         AUD_CHANNEL_MAX
101 } AUD_Channel;
102
103 /**
104  * The sample rate tells how many samples are played back within one second.
105  * Some exotic formats may use other sample rates than provided here.
106  */
107 typedef enum
108 {
109         AUD_RATE_INVALID = 0,                   /// Invalid sample rate.
110         AUD_RATE_8000    = 8000,                /// 8000 Hz.
111         AUD_RATE_16000   = 16000,               /// 16000 Hz.
112         AUD_RATE_11025   = 11025,               /// 11025 Hz.
113         AUD_RATE_22050   = 22050,               /// 22050 Hz.
114         AUD_RATE_32000   = 32000,               /// 32000 Hz.
115         AUD_RATE_44100   = 44100,               /// 44100 Hz.
116         AUD_RATE_48000   = 48000,               /// 48000 Hz.
117         AUD_RATE_88200   = 88200,               /// 88200 Hz.
118         AUD_RATE_96000   = 96000,               /// 96000 Hz.
119         AUD_RATE_192000  = 192000               /// 192000 Hz.
120 } AUD_DefaultSampleRate;
121
122 /// Status of a playback handle.
123 typedef enum
124 {
125         AUD_STATUS_INVALID = 0,                 /// Invalid handle. Maybe due to stopping.
126         AUD_STATUS_PLAYING,                             /// Sound is playing.
127         AUD_STATUS_PAUSED                               /// Sound is being paused.
128 } AUD_Status;
129
130 /// Error codes for exceptions (C++ library) or for return values (C API).
131 typedef enum
132 {
133         AUD_NO_ERROR = 0,
134         AUD_ERROR_SPECS,
135         AUD_ERROR_PROPS,
136         AUD_ERROR_FILE,
137         AUD_ERROR_SRC,
138         AUD_ERROR_FFMPEG,
139         AUD_ERROR_OPENAL,
140         AUD_ERROR_SDL,
141         AUD_ERROR_JACK
142 } AUD_Error;
143
144 /// Fading types.
145 typedef enum
146 {
147         AUD_FADE_IN,
148         AUD_FADE_OUT
149 } AUD_FadeType;
150
151 /// Possible distance models for the 3D device.
152 typedef enum
153 {
154         AUD_DISTANCE_MODEL_INVALID = 0,
155         AUD_DISTANCE_MODEL_INVERSE,
156         AUD_DISTANCE_MODEL_INVERSE_CLAMPED,
157         AUD_DISTANCE_MODEL_LINEAR,
158         AUD_DISTANCE_MODEL_LINEAR_CLAMPED,
159         AUD_DISTANCE_MODEL_EXPONENT,
160         AUD_DISTANCE_MODEL_EXPONENT_CLAMPED
161 } AUD_DistanceModel;
162
163 typedef enum
164 {
165         AUD_AP_VOLUME,
166         AUD_AP_PANNING,
167         AUD_AP_PITCH,
168         AUD_AP_LOCATION,
169         AUD_AP_ORIENTATION
170 } AUD_AnimateablePropertyType;
171
172 typedef enum
173 {
174         AUD_CONTAINER_INVALID = 0,
175         AUD_CONTAINER_AC3,
176         AUD_CONTAINER_FLAC,
177         AUD_CONTAINER_MATROSKA,
178         AUD_CONTAINER_MP2,
179         AUD_CONTAINER_MP3,
180         AUD_CONTAINER_OGG,
181         AUD_CONTAINER_WAV
182 } AUD_Container;
183
184 typedef enum
185 {
186         AUD_CODEC_INVALID = 0,
187         AUD_CODEC_AAC,
188         AUD_CODEC_AC3,
189         AUD_CODEC_FLAC,
190         AUD_CODEC_MP2,
191         AUD_CODEC_MP3,
192         AUD_CODEC_PCM,
193         AUD_CODEC_VORBIS
194 } AUD_Codec;
195
196 /// Sample type.(float samples)
197 typedef float sample_t;
198
199 /// Sample data type (format samples)
200 typedef unsigned char data_t;
201
202 /// Sample rate type.
203 typedef double AUD_SampleRate;
204
205 /// Specification of a sound source.
206 typedef struct
207 {
208         /// Sample rate in Hz.
209         AUD_SampleRate rate;
210
211         /// Channel count.
212         AUD_Channels channels;
213 } AUD_Specs;
214
215 /// Specification of a sound device.
216 typedef struct
217 {
218         /// Sample format.
219         AUD_SampleFormat format;
220
221         union
222         {
223                 struct
224                 {
225                         /// Sample rate in Hz.
226                         AUD_SampleRate rate;
227
228                         /// Channel count.
229                         AUD_Channels channels;
230                 };
231                 AUD_Specs specs;
232         };
233 } AUD_DeviceSpecs;
234
235 /// Exception structure.
236 typedef struct
237 {
238         /**
239          * Error code.
240          * \see AUD_Error
241          */
242         AUD_Error error;
243
244         /**
245          * Error string.
246          */
247         const char* str;
248
249         // void* userData; - for the case it is needed someday
250 } AUD_Exception;
251
252 #endif //AUD_SPACE