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