Mercurial > almixer_isolated
comparison SDL_ALmixer.h @ 0:01e39f9f58d5
Bitkeeper era.
author | Eric Wing <ewing . public |-at-| gmail . com> |
---|---|
date | Wed, 27 Oct 2010 16:50:19 -0700 |
parents | |
children | a8a8fe374984 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:01e39f9f58d5 |
---|---|
1 /* | |
2 SDL_ALmixer: A library to make playing sounds and music easier, | |
3 which uses OpenAL to manage sounds and SDL_Sound (by Ryan C. Gordon) | |
4 to decode files. | |
5 Copyright 2002 Eric Wing | |
6 | |
7 This library is free software; you can redistribute it and/or | |
8 modify it under the terms of the GNU Library General Public | |
9 License as published by the Free Software Foundation; either | |
10 version 2 of the License, or (at your option) any later version. | |
11 | |
12 This library is distributed in the hope that it will be useful, | |
13 but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 Library General Public License for more details. | |
16 | |
17 You should have received a copy of the GNU Library General Public | |
18 License along with this library; if not, write to the Free | |
19 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
20 | |
21 */ | |
22 #ifndef _SDL_ALMIXER_H_ | |
23 #define _SDL_ALMIXER_H_ | |
24 | |
25 #include "SDL_types.h" | |
26 /* | |
27 #include "SDL_rwops.h" | |
28 #include "SDL_audio.h" | |
29 #include "SDL_byteorder.h" | |
30 */ | |
31 #include "SDL_version.h" | |
32 | |
33 /* | |
34 #include "begin_code.h" | |
35 */ | |
36 | |
37 #include "SDL_sound.h" | |
38 #include "altypes.h" | |
39 | |
40 /* Set up for C function definitions, even when using C++ */ | |
41 #ifdef __cplusplus | |
42 extern "C" { | |
43 #endif | |
44 | |
45 /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL | |
46 */ | |
47 #define ALMIXER_MAJOR_VERSION 0 | |
48 #define ALMIXER_MINOR_VERSION 1 | |
49 #define ALMIXER_PATCHLEVEL 0 | |
50 | |
51 /* This macro can be used to fill a version structure with the compile-time | |
52 * version of the SDL_mixer library. | |
53 */ | |
54 #define ALMIXER_VERSION(X) \ | |
55 { \ | |
56 (X)->major = ALMIXER_MAJOR_VERSION; \ | |
57 (X)->minor = ALMIXER_MINOR_VERSION; \ | |
58 (X)->patch = ALMIXER_PATCHLEVEL; \ | |
59 } | |
60 | |
61 /* This function gets the version of the dynamically linked SDL_ALmixer library. | |
62 it should NOT be used to fill a version structure, instead you should | |
63 use the ALMIXER_VERSION() macro. | |
64 */ | |
65 extern DECLSPEC const SDL_version * SDLCALL ALmixer_Linked_Version(); | |
66 | |
67 /* | |
68 #define ALmixer_AudioInfo Sound_AudioInfo | |
69 */ | |
70 | |
71 #define ALMIXER_DEFAULT_FREQUENCY 44100 | |
72 #define ALMIXER_DEFAULT_REFRESH 0 | |
73 #define ALMIXER_DEFAULT_NUM_CHANNELS 16 | |
74 #define ALMIXER_DEFAULT_NUM_SOURCES ALMIXER_DEFAULT_NUM_CHANNELS | |
75 | |
76 #define ALMIXER_DEFAULT_BUFFERSIZE 32768 | |
77 /* #define ALMIXER_DEFAULT_BUFFERSIZE 16384 */ | |
78 | |
79 /* Default Queue Buffers must be at least 2 */ | |
80 #define ALMIXER_DEFAULT_QUEUE_BUFFERS 5 | |
81 /* Default startup buffers should be at least 1 */ | |
82 #define ALMIXER_DEFAULT_STARTUP_BUFFERS 2 | |
83 | |
84 #define ALMIXER_DECODE_STREAM 0 | |
85 #define ALMIXER_DECODE_ALL 1 | |
86 | |
87 | |
88 #define ALmixer_GetError SDL_GetError | |
89 #define ALmixer_SetError SDL_SetError | |
90 | |
91 typedef struct { | |
92 ALuint albuffer; | |
93 Sint32 index; /* might not need */ | |
94 Uint8* data; | |
95 Uint32 num_bytes; | |
96 } Buffer_Map; | |
97 | |
98 typedef struct { | |
99 Uint8 decoded_all; /* dictates different behaviors */ | |
100 Sint32 total_time; /* total playing time of sample (msec) */ | |
101 | |
102 Uint32 in_use; /* needed to prevent sharing for streams */ | |
103 Uint8 eof; /* flag for eof, only used for streams */ | |
104 | |
105 Uint32 total_bytes; /* For predecoded */ | |
106 Uint32 loaded_bytes; /* For predecoded (for seek) */ | |
107 | |
108 Sound_Sample* sample; /* SDL_Sound provides the data */ | |
109 ALuint* buffer; /* array of OpenAL buffers (at least 1 for predecoded) */ | |
110 | |
111 /* Needed for streamed buffers */ | |
112 Uint32 max_queue_buffers; /* Max number of queue buffers */ | |
113 Uint32 num_startup_buffers; /* Number of ramp-up buffers */ | |
114 Uint8 num_buffers_in_use; /* number of buffers in use */ | |
115 | |
116 /* This stuff is for streamed buffers that require data access */ | |
117 Buffer_Map* buffer_map_list; /* translate ALbuffer to index | |
118 and holds pointer to copy of data for | |
119 data access */ | |
120 ALuint current_buffer; /* The current playing buffer */ | |
121 | |
122 /* Nvidia distribution refuses to recognize a simple buffer query command | |
123 * unlike all other distributions. It's forcing me to redo the code | |
124 * to accomodate this Nvidia flaw by making me maintain a "best guess" | |
125 * copy of what I think the buffer queue state looks like. | |
126 * A circular queue would a helpful data structure for this task, | |
127 * but I wanted to avoid making an additional header requirement, | |
128 * so I'm making it a void* | |
129 */ | |
130 void* circular_buffer_queue; | |
131 | |
132 | |
133 } ALmixer_Data; | |
134 | |
135 | |
136 #if 0 | |
137 typedef struct { | |
138 Sound_Sample* sample; | |
139 Mix_Chunk** chunk; /* provide two chunks for double buffering */ | |
140 Uint8** double_buffer; /* Only used for streaming */ | |
141 Uint8 active_buffer; /* used to index the above chunk */ | |
142 void (*channel_done_callback)(int channel); | |
143 } ALmixer_Chunk; | |
144 #endif | |
145 | |
146 /* | |
147 extern DECLSPEC int SDLCALL ALmixer_Init(int frequency, Uint16 format, int channels, int chunksize); | |
148 */ | |
149 /* Frequency == 0 means ALMIXER_DEFAULT_FREQUENCY */ | |
150 /* This is the recommended Init function. This will initialize the context, SDL_sound, | |
151 * and the mixer system. If you attempt to bypass this function, you do so at | |
152 * your own risk. | |
153 */ | |
154 extern DECLSPEC Sint32 SDLCALL ALmixer_Init(Uint32 frequency, Sint32 num_sources, Uint32 refresh); | |
155 | |
156 /* This is a backdoor in case you need to initialize the AL context and | |
157 * the mixer system separately. I strongly recommend avoiding these two functions | |
158 * and use the normal Init() function. | |
159 */ | |
160 /* Init_Context will only initialize the OpenAL context (and not the mixer part). | |
161 * Note that SDL_Sound is also initialized here because load order matters | |
162 * because SDL audio will conflict with OpenAL when using SMPEG. This is only | |
163 * provided as a backdoor and is not recommended. | |
164 */ | |
165 extern DECLSPEC Sint32 SDLCALL ALmixer_Init_Context(Uint32 frequency, Uint32 refresh); | |
166 /* Init_Mixer will only initialize the Mixer system. This is provided in the case | |
167 * that you need control over the loading of the context. You may load the context | |
168 * yourself, and then call this function. This is not recommended practice, but is | |
169 * provided as a backdoor in case you have good reason to | |
170 * do this. Be warned that if ALmixer_Init_Mixer() fails, | |
171 * it will not clean up the AL context. Also be warned that Quit() still does try to | |
172 * clean up everything. | |
173 */ | |
174 extern DECLSPEC Sint32 SDLCALL ALmixer_Init_Mixer(Sint32 num_sources); | |
175 | |
176 extern DECLSPEC void SDLCALL ALmixer_Quit(); | |
177 extern DECLSPEC Uint8 SDLCALL ALmixer_IsInitialized(); | |
178 | |
179 extern DECLSPEC Uint32 SDLCALL ALmixer_GetFrequency(); | |
180 | |
181 extern DECLSPEC Sint32 SDLCALL ALmixer_AllocateChannels(Sint32 numchans); | |
182 extern DECLSPEC Sint32 SDLCALL ALmixer_ReserveChannels(Sint32 num); | |
183 | |
184 extern DECLSPEC ALmixer_Data * SDLCALL ALmixer_LoadSample_RW(SDL_RWops* rwops, const char* fileext, Uint32 buffersize, Uint8 decode_mode, Uint32 max_queue_buffers, Uint32 num_startup_buffers, Uint8 access_data); | |
185 | |
186 | |
187 #define ALmixer_LoadStream_RW(rwops,fileext,buffersize,max_queue_buffers,num_startup_buffers,access_data) ALmixer_LoadSample_RW(rwops,fileext,buffersize,ALMIXER_DECODE_STREAM, max_queue_buffers, num_startup_buffers,access_data) | |
188 | |
189 #define ALmixer_LoadAll_RW(rwops,fileext,buffersize,access_data) ALmixer_LoadSample_RW(rwops,fileext,buffersize,ALMIXER_DECODE_ALL, 0, 0,access_data) | |
190 | |
191 | |
192 | |
193 extern DECLSPEC ALmixer_Data * SDLCALL ALmixer_LoadSample(const char* filename, Uint32 buffersize, Uint8 decode_mode, Uint32 max_queue_buffers, Uint32 num_startup_buffers, Uint8 access_data); | |
194 | |
195 | |
196 #define ALmixer_LoadStream(filename,buffersize,max_queue_buffers,num_startup_buffers,access_data) ALmixer_LoadSample(filename,buffersize,ALMIXER_DECODE_STREAM, max_queue_buffers, num_startup_buffers,access_data) | |
197 | |
198 #define ALmixer_LoadAll(filename,buffersize,access_data) ALmixer_LoadSample(filename,buffersize,ALMIXER_DECODE_ALL, 0, 0,access_data) | |
199 | |
200 | |
201 extern DECLSPEC ALmixer_Data * SDLCALL ALmixer_LoadSample_RAW_RW(SDL_RWops* rwops, const char* fileext, Sound_AudioInfo* desired, Uint32 buffersize, Uint8 decode_mode, Uint32 max_queue_buffers, Uint32 num_startup_buffers, Uint8 access_data); | |
202 | |
203 #define ALmixer_LoadStream_RAW_RW(rwops,fileext,desired,buffersize,max_queue_buffers,num_startup_buffers,access_data) ALmixer_LoadSample_RAW_RW(rwops,fileext,desired,buffersize,ALMIXER_DECODE_STREAM, max_queue_buffers, num_startup_buffers,access_data) | |
204 | |
205 #define ALmixer_LoadAll_RAW_RW(rwops,fileext,desired,buffersize,access_data) ALmixer_LoadSample_RAW_RW(rwops,fileext,desired,buffersize,ALMIXER_DECODE_ALL, 0, 0,access_data) | |
206 | |
207 extern DECLSPEC ALmixer_Data * SDLCALL ALmixer_LoadSample_RAW(const char* filename, Sound_AudioInfo* desired, Uint32 buffersize, Uint8 decode_mode, Uint32 max_queue_buffers, Uint32 num_startup_buffers, Uint8 access_data); | |
208 | |
209 | |
210 | |
211 extern DECLSPEC void SDLCALL ALmixer_FreeData(ALmixer_Data* data); | |
212 | |
213 extern DECLSPEC Sint32 SDLCALL ALmixer_GetTotalTime(ALmixer_Data* data); | |
214 | |
215 | |
216 /* If not using threads, this function must be periodically called | |
217 * to poll ALmixer to force streamed music and other events to | |
218 * take place. If threads are enabled, then this function just | |
219 * returns 0. | |
220 */ | |
221 extern DECLSPEC Sint32 SDLCALL ALmixer_Update(); | |
222 | |
223 | |
224 | |
225 | |
226 /* Play a sound on a channel with a time limit */ | |
227 extern DECLSPEC Sint32 SDLCALL ALmixer_PlayChannelTimed(Sint32 channel, ALmixer_Data* data, Sint32 loops, Sint32 ticks); | |
228 | |
229 /* The same as above, but the sound is played without time limits */ | |
230 #define ALmixer_PlayChannel(channel,data,loops) ALmixer_PlayChannelTimed(channel,data,loops,-1) | |
231 /* These functions are the same as PlayChannel*(), but use sources | |
232 * instead of channels | |
233 */ | |
234 extern DECLSPEC ALuint SDLCALL ALmixer_PlaySourceTimed(ALuint source, ALmixer_Data* data, Sint32 loops, Sint32 ticks); | |
235 | |
236 #define ALmixer_PlaySource(source,data,loops) ALmixer_PlaySourceTimed(source,data,loops,-1) | |
237 | |
238 /* This function will look up the source for the corresponding channel. | |
239 * If -1 is supplied, it will try to return a source not in use | |
240 * Must return 0 on error instead of -1 because of unsigned int | |
241 */ | |
242 extern DECLSPEC ALuint SDLCALL ALmixer_GetSource(Sint32 channel); | |
243 /* This function will look up the channel for the corresponding source. | |
244 * If -1 is supplied, it will try to return the first channel not in use. | |
245 * Returns -1 on error, or the channel. | |
246 */ | |
247 extern DECLSPEC Sint32 SDLCALL ALmixer_GetChannel(ALuint source); | |
248 | |
249 extern DECLSPEC Sint32 SDLCALL ALmixer_FindFreeChannel(Sint32 start_channel); | |
250 | |
251 extern DECLSPEC void SDLCALL ALmixer_ChannelFinished(void (*channel_finished)(Sint32 channel, void* userdata), void* userdata); | |
252 extern DECLSPEC void SDLCALL ALmixer_ChannelData(void (*channel_data)(Sint32 which_chan, Uint8* data, Uint32 num_bytes, Uint32 frequency, Uint8 channels, Uint8 bitdepth, Uint16 format, Uint8 decode_mode)); | |
253 | |
254 | |
255 extern DECLSPEC Sint32 SDLCALL ALmixer_HaltChannel(Sint32 channel); | |
256 extern DECLSPEC Sint32 SDLCALL ALmixer_HaltSource(ALuint source); | |
257 | |
258 | |
259 extern DECLSPEC Sint32 SDLCALL ALmixer_RewindData(ALmixer_Data* data); | |
260 | |
261 /* If decoded all, rewind will instantly rewind it. Data is not | |
262 * affected, so it will start at the "Seek"'ed positiond. | |
263 * Streamed data will rewind the actual data, but the effect | |
264 * will not be noticed until the currently buffered data is played. | |
265 * Use Halt before this call for instantaneous changes | |
266 */ | |
267 extern DECLSPEC Sint32 SDLCALL ALmixer_RewindChannel(Sint32 channel); | |
268 extern DECLSPEC Sint32 SDLCALL ALmixer_RewindSource(ALuint source); | |
269 | |
270 extern DECLSPEC Sint32 SDLCALL ALmixer_PauseChannel(Sint32 channel); | |
271 extern DECLSPEC Sint32 SDLCALL ALmixer_PauseSource(ALuint source); | |
272 | |
273 extern DECLSPEC Sint32 SDLCALL ALmixer_ResumeChannel(Sint32 channel); | |
274 extern DECLSPEC Sint32 SDLCALL ALmixer_ResumeSource(ALuint source); | |
275 | |
276 extern DECLSPEC Sint32 SDLCALL ALmixer_Seek(ALmixer_Data* data, Uint32 msec); | |
277 | |
278 | |
279 extern DECLSPEC Sint32 SDLCALL ALmixer_FadeInChannelTimed(Sint32 channel, ALmixer_Data* data, Sint32 loops, Uint32 fade_ticks, Sint32 expire_ticks); | |
280 | |
281 #define ALmixer_FadeInChannel(channel,data,loops,fade_ticks) ALmixer_FadeInChannelTimed(channel,data,loops,fade_ticks,-1) | |
282 | |
283 extern DECLSPEC ALuint SDLCALL ALmixer_FadeInSourceTimed(ALuint source, ALmixer_Data* data, Sint32 loops, Uint32 fade_ticks, Sint32 expire_ticks); | |
284 | |
285 #define ALmixer_FadeInSource(source,data,loops,fade_ticks) ALmixer_FadeInSourceTimed(source,data,loops,fade_ticks,-1) | |
286 | |
287 extern DECLSPEC Sint32 SDLCALL ALmixer_FadeOutChannel(Sint32 channel, Uint32 ticks); | |
288 extern DECLSPEC Sint32 SDLCALL ALmixer_FadeOutSource(ALuint source, Uint32 ticks); | |
289 | |
290 extern DECLSPEC Sint32 SDLCALL ALmixer_FadeChannel(Sint32 channel, Uint32 ticks, ALfloat volume); | |
291 extern DECLSPEC Sint32 SDLCALL ALmixer_FadeSource(ALuint source, Uint32 ticks, ALfloat volume); | |
292 | |
293 extern DECLSPEC Sint32 SDLCALL ALmixer_SetMaxVolumeChannel(Sint32 channel, ALfloat volume); | |
294 extern DECLSPEC Sint32 SDLCALL ALmixer_SetMaxVolumeSource(ALuint source, ALfloat volume); | |
295 extern DECLSPEC ALfloat SDLCALL ALmixer_GetMaxVolumeChannel(Sint32 channel); | |
296 extern DECLSPEC ALfloat SDLCALL ALmixer_GetMaxVolumeSource(ALuint source); | |
297 | |
298 extern DECLSPEC Sint32 SDLCALL ALmixer_SetMinVolumeChannel(Sint32 channel, ALfloat volume); | |
299 extern DECLSPEC Sint32 SDLCALL ALmixer_SetMinVolumeSource(ALuint source, ALfloat volume); | |
300 extern DECLSPEC ALfloat SDLCALL ALmixer_GetMinVolumeChannel(Sint32 channel); | |
301 extern DECLSPEC ALfloat SDLCALL ALmixer_GetMinVolumeSource(ALuint source); | |
302 | |
303 | |
304 extern DECLSPEC Sint32 SDLCALL ALmixer_SetMasterVolume(ALfloat volume); | |
305 extern DECLSPEC ALfloat SDLCALL ALmixer_GetMasterVolume(); | |
306 | |
307 | |
308 extern DECLSPEC Sint32 SDLCALL ALmixer_ExpireChannel(Sint32 channel, Sint32 ticks); | |
309 extern DECLSPEC Sint32 SDLCALL ALmixer_ExpireSource(ALuint source, Sint32 ticks); | |
310 | |
311 extern DECLSPEC Sint32 SDLCALL ALmixer_QueryChannel(Sint32 channel); | |
312 extern DECLSPEC Sint32 SDLCALL ALmixer_QuerySource(ALuint source); | |
313 extern DECLSPEC Sint32 SDLCALL ALmixer_PlayingChannel(Sint32 channel); | |
314 extern DECLSPEC Sint32 SDLCALL ALmixer_PlayingSource(ALuint source); | |
315 extern DECLSPEC Sint32 SDLCALL ALmixer_PausedChannel(Sint32 channel); | |
316 extern DECLSPEC Sint32 SDLCALL ALmixer_PausedSource(ALuint source); | |
317 | |
318 extern DECLSPEC Sint32 SDLCALL ALmixer_CountAllFreeChannels(); | |
319 extern DECLSPEC Sint32 SDLCALL ALmixer_CountUnreservedFreeChannels(); | |
320 extern DECLSPEC Sint32 SDLCALL ALmixer_CountAllUsedChannels(); | |
321 extern DECLSPEC Sint32 SDLCALL ALmixer_CountUnreservedUsedChannels(); | |
322 #define ALmixer_CountTotalChannels() ALmixer_AllocateChannels(-1) | |
323 #define ALmixer_CountReservedChannels() ALmixer_ReserveChannels(-1) | |
324 | |
325 | |
326 | |
327 /* For testing */ | |
328 #if 0 | |
329 extern DECLSPEC void SDLCALL ALmixer_Output_Attributes(); | |
330 #endif | |
331 extern DECLSPEC void SDLCALL ALmixer_Output_Decoders(); | |
332 extern DECLSPEC void SDLCALL ALmixer_Output_OpenAL_Info(); | |
333 | |
334 #if 0 | |
335 | |
336 | |
337 | |
338 extern DECLSPEC Uint32 SDLCALL ALmixer_Volume(Sint32 channel, Sint32 volume); | |
339 | |
340 | |
341 /* I'm going to blindly throw in the Mixer effects sections and | |
342 * hope they work. | |
343 */ | |
344 #define ALmixer_EffectFunc_t Mix_EffectFunc_t | |
345 #define ALmixer_EffectDone_t Mix_EffectDone_t | |
346 /* | |
347 #define ALmixer_RegisterEffect Mix_RegisterEffect | |
348 #define ALmixer_UnregisterEffect Mix_UnregisterEffect | |
349 #define ALmixer_UnregisterAllEffects Mix_RegisterEffect | |
350 */ | |
351 | |
352 #define ALmixer_SetPostMix Mix_SetPostMix | |
353 #define ALmixer_SetPanning Mix_SetPanning | |
354 #define ALmixer_SetDistance Mix_SetDistance | |
355 #define ALmixer_SetPosition Mix_SetPosition | |
356 #define ALmixer_SetReverseStereo Mix_SetReverseStereo | |
357 | |
358 /* Unfortunately, effects have a nasty behavior of unregistering | |
359 * themselves after the channel finishes. This is incompatible | |
360 * with the streaming system that this library uses. | |
361 * Implementing a proper effects system will take more time. | |
362 * For now, I need to be able to retrieve the playing data | |
363 * for an oscilloscope, so I am hacking together a 1 effect | |
364 * system. You can't have more than one. | |
365 */ | |
366 | |
367 extern DECLSPEC Sint32 SDLCALL ALmixer_RegisterEffect(Sint32 chan, ALmixer_EffectFunc_t f, ALmixer_EffectDone_t d, void* arg); | |
368 | |
369 extern DECLSPEC Sint32 SDLCALL ALmixer_UnregisterEffect(Sint32 chan, ALmixer_EffectFunc_t f); | |
370 | |
371 extern DECLSPEC Sint32 SDLCALL ALmixer_UnregisterAllEffects(Sint32 chan); | |
372 | |
373 #endif | |
374 | |
375 | |
376 | |
377 | |
378 /* Ends C function definitions when using C++ */ | |
379 #ifdef __cplusplus | |
380 } | |
381 #endif | |
382 /* | |
383 #include "close_code.h" | |
384 */ | |
385 | |
386 #endif /* _SDL_ALMIXER_H_ */ | |
387 | |
388 /* end of SDL_ALmixer.h ... */ | |
389 | |
390 |