Mercurial > almixer_isolated

comparison ALmixer.h @ 3:a929285e1db0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added CMake build system. There are problems with the SDL_sound module due to changes in CMake. Right now they just seem to be warnings, but I am unable to suppress them. Added license. Added README.
author Eric Wing <ewing . public |-at-| gmail . com>
date Wed, 27 Oct 2010 20:43:14 -0700
parents SDL_ALmixer.h@279d0427ef26
children 8cb13d89451a
comparison
equal deleted inserted replaced
2:279d0427ef26 3:a929285e1db0
1 /*
2 ALmixer: A library to make playing pre-loaded sounds and streams easier
3 with high performance and potential access to OpenAL effects.
4 Copyright 2002, 2010 Eric Wing <ewing . public @ playcontrol.net>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public
17 License along with this library; if not, write to the Free
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19
20 */
21
22
23 /**
24 * @mainpage
25 * ALmixer (which I sometimes call "SDL-OpenAL-Mixer" or "SDL_ALmixer") is a cross-platform audio library built
26 * on top of OpenAL to make playing and managing sounds easier.
27 * ALmixer provides a simple API inspired by SDL_mixer to make playing sounds easy
28 * with having to worry about directly dealing with OpenAL sources, buffers,
29 * and buffer queuing directly.
30 * ALmixer currently utilizes SDL_sound behind the scenes to decode
31 * various audio formats such as WAV, MP3, AAC, MP4, OGG, etc.
32 *
33 * This library is targeted towards two major groups:
34 * - People who just want an easy, high performance, way to play audio (don't care if its OpenAL or not)
35 * - People who want to an easy way to play audio in OpenAL but still want access to OpenAL directly.
36 *
37 * ALmixer exposes OpenAL sources in the API so you can freely use ALmixer
38 * in larger OpenAL applications that need to apply OpenAL 3D effects and features
39 * to playing sounds.
40 *
41 * The API is heavily influenced and inspired by SDL_mixer, though there is one major
42 * conceptual design difference. ALmixer doesn't divide sound and music playback into two
43 * separate play APIs. Instead, there is one unified play API and you specify via the
44 * load API whether you want the audio resource loaded as a stream or completely preloaded.
45 * This allows you to have any arbitrary number of streaming sources playing simultaneously
46 * (such as music and speech) unlike SDL_mixer where you are limited to only one "music"
47 * channel.
48 *
49 * A less major conceptual design difference is every "Channel" API has a corresponding "Source" API.
50 * Every "channel" (in the SDL_mixer definition context) maps to a corresponding OpenAL source id. You can use
51 * this source ID directly with OpenAL API commands to utilize OpenAL effects such as position, Doppler, etc.
52 * Convenience APIs are provided to let you convert channel numbers to source ids and vice-versa.
53 *
54 * Another change which is a pet-peev of mine with SDL_mixer is the lack of a user_data parameter in callbacks.
55 * ALmixer callbacks allow you to pass user_data (aka context) pointers through the callback functions.
56 *
57 * @note There are some #defines you can set to change the behavior at compile time. Most you shouldn't touch.
58 * The one worth noting is ENABLE_ALMIXER_THREADS. If enabled, ALmixer_Update() is automatically called on a
59 * background thread so you no longer have to explicitly call it. (The function turns into a no-op so your existing
60 * code won't break.) Having Update run in a separate thread has some advantages, particularly for streaming
61 * audio as all the OpenAL buffer queuing happens in this function. It is less likely the background thread will
62 * be blocked for long periods and thus less likely your buffer queues will be starved. However, this means you
63 * need to be extra careful about what you do in callback functions as they are invoked from the background thread.
64 * I still consider this feature a experimental (though I am starting to use it more myself) and there
65 * may still be bugs.
66 *
67 * @author Eric Wing
68 */
69
70 /**
71 * @file
72 * ALmixer (which I sometimes call "SDL-OpenAL-Mixer" or "SDL_ALmixer") is a cross-platform audio library built
73 * on top of OpenAL to make playing and managing sounds easier.
74 * ALmixer provides a simple API inspired by SDL_mixer to make playing sounds easy
75 * with having to worry about directly dealing with OpenAL sources, buffers,
76 * and buffer queuing directly.
77 * ALmixer currently utilizes SDL_sound behind the scenes to decode
78 * various audio formats such as WAV, MP3, AAC, MP4, OGG, etc.
79 *
80 * This library is targeted towards two major groups:
81 * - People who just want an easy, high performance, way to play audio (don't care if its OpenAL or not)
82 * - People who want to an easy way to play audio in OpenAL but still want access to OpenAL directly.
83 *
84 * ALmixer exposes OpenAL sources in the API so you can freely use ALmixer
85 * in larger OpenAL applications that need to apply OpenAL 3D effects and features
86 * to playing sounds.
87 *
88 * The API is heavily influenced and inspired by SDL_mixer, though there is one major
89 * conceptual design difference. ALmixer doesn't divide sound and music playback into two
90 * separate play APIs. Instead, there is one unified play API and you specify via the
91 * load API whether you want the audio resource loaded as a stream or completely preloaded.
92 * This allows you to have any arbitrary number of streaming sources playing simultaneously
93 * (such as music and speech) unlike SDL_mixer where you are limited to only one "music"
94 * channel.
95 *
96 * A less major conceptual design difference is every "Channel" API has a corresponding "Source" API.
97 * Every "channel" (in the SDL_mixer definition context) maps to a corresponding OpenAL source id. You can use
98 * this source ID directly with OpenAL API commands to utilize OpenAL effects such as position, Doppler, etc.
99 * Convenience APIs are provided to let you convert channel numbers to source ids and vice-versa.
100 *
101 * Another change which is a pet-peev of mine with SDL_mixer is the lack of a user_data parameter in callbacks.
102 * ALmixer callbacks allow you to pass user_data (aka context) pointers through the callback functions.
103 *
104 * @note There are some #defines you can set to change the behavior at compile time. Most you shouldn't touch.
105 * The one worth noting is ENABLE_ALMIXER_THREADS. If enabled, ALmixer_Update() is automatically called on a
106 * background thread so you no longer have to explicitly call it. (The function turns into a no-op so your existing
107 * code won't break.) Having Update run in a separate thread has some advantages, particularly for streaming
108 * audio as all the OpenAL buffer queuing happens in this function. It is less likely the background thread will
109 * be blocked for long periods and thus less likely your buffer queues will be starved. However, this means you
110 * need to be extra careful about what you do in callback functions as they are invoked from the background thread.
111 * I still consider this feature a experimental (though I am starting to use it more myself) and there
112 * may still be bugs.
113 *
114 * @author Eric Wing
115 */
116
117
118 #ifndef _SDL_ALMIXER_H_
119 #define _SDL_ALMIXER_H_
120
121
122 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
123 /** @cond DOXYGEN_SHOULD_IGNORE_THIS */
124
125 /* Note: For Doxygen to produce clean output, you should set the
126 * PREDEFINED option to remove ALMIXER_DECLSPEC, ALMIXER_CALL, and
127 * the DOXYGEN_SHOULD_IGNORE_THIS blocks.
128 * PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 ALMIXER_DECLSPEC= ALMIXER_CALL=
129 */
130
131 #ifdef ALMIXER_COMPILE_WITHOUT_SDL
132 #if defined(_WIN32)
133 #if defined(ALMIXER_BUILD_LIBRARY)
134 #define ALMIXER_DECLSPEC __declspec(dllexport)
135 #else
136 #define ALMIXER_DECLSPEC __declspec(dllimport)
137 #endif
138 #else
139 #if defined(ALMIXER_BUILD_LIBRARY)
140 #if defined (__GNUC__) && __GNUC__ >= 4
141 #define ALMIXER_DECLSPEC __attribute__((visibility("default")))
142 #else
143 #define ALMIXER_DECLSPEC
144 #endif
145 #else
146 #define ALMIXER_DECLSPEC
147 #endif
148 #endif
149
150 #if defined(_WIN32)
151 #define ALMIXER_CALL __cdecl
152 #else
153 #define ALMIXER_CALL
154 #endif
155 #else
156 #include "SDL_types.h" /* will include begin_code.h which is what I really want */
157 #define ALMIXER_DECLSPEC DECLSPEC
158 #define ALMIXER_CALL SDLCALL
159 #endif
160
161 /** @endcond DOXYGEN_SHOULD_IGNORE_THIS */
162 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */
163
164
165
166 /* Needed for OpenAL types since altypes.h was removed in 1.1 */
167 #include "al.h"
168
169 /* Set up for C function definitions, even when using C++ */
170 #ifdef __cplusplus
171 extern "C" {
172 #endif
173
174 #ifdef ALMIXER_COMPILE_WITHOUT_SDL
175 /**
176 * Struct that contains the version information of this library.
177 * This represents the library's version as three levels: major revision
178 * (increments with massive changes, additions, and enhancements),
179 * minor revision (increments with backwards-compatible changes to the
180 * major revision), and patchlevel (increments with fixes to the minor
181 * revision).
182 * @see ALMIXER_VERSION, ALmixer_GetLinkedVersion
183 */
184 typedef struct ALmixer_version
185 {
186 ALubyte major;
187 ALubyte minor;
188 ALubyte patch;
189 } ALmixer_version;
190 #else
191 #include "SDL_version.h"
192 #define ALmixer_version SDL_version
193 #endif
194
195 /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
196 */
197 #define ALMIXER_MAJOR_VERSION 0
198 #define ALMIXER_MINOR_VERSION 1
199 #define ALMIXER_PATCHLEVEL 0
200
201
202 /**
203 * @defgroup CoreOperation Initialization, Tear-down, and Core Operational Commands
204 * @{
205 * Functions for setting up and using ALmixer.
206 */
207
208
209 /**
210 * This macro fills in a version structure with the version of the
211 * library you compiled against. This is determined by what header the
212 * compiler uses. Note that if you dynamically linked the library, you might
213 * have a slightly newer or older version at runtime. That version can be
214 * determined with ALmixer_GetLinkedVersion(), which, unlike
215 * ALMIXER_GET_COMPILED_VERSION, is not a macro.
216 *
217 * @note When compiled with SDL, this macro can be used to fill a version structure
218 * compatible with SDL_version.
219 *
220 * @param X A pointer to a ALmixer_version struct to initialize.
221 *
222 * @see ALmixer_version, ALmixer_GetLinkedVersion
223 */
224 #define ALMIXER_GET_COMPILED_VERSION(X) \
225 { \
226 (X)->major = ALMIXER_MAJOR_VERSION; \
227 (X)->minor = ALMIXER_MINOR_VERSION; \
228 (X)->patch = ALMIXER_PATCHLEVEL; \
229 }
230
231 /**
232 * Gets the library version of the dynamically linked ALmixer you are using.
233 * This gets the version of ALmixer that is linked against your program.
234 * If you are using a shared library (DLL) version of ALmixer, then it is
235 * possible that it will be different than the version you compiled against.
236 *
237 * This is a real function; the macro ALMIXER_GET_COMPILED_VERSION
238 * tells you what version of tErrorLib you compiled against:
239 *
240 * @code
241 * ALmixer_version compiled;
242 * ALmixer_version linked;
243 *
244 * ALMIXER_GET_COMPILED_VERSION(&compiled);
245 * ALmixer_GetLinkedVersion(&linked);
246 * printf("We compiled against tError version %d.%d.%d ...\n",
247 * compiled.major, compiled.minor, compiled.patch);
248 * printf("But we linked against tError version %d.%d.%d.\n",
249 * linked.major, linked.minor, linked.patch);
250 * @endcode
251 *
252 * @see ALmixer_version, ALMIXER_GET_COMPILED_VERSION
253 */
254 extern ALMIXER_DECLSPEC const ALmixer_version* ALMIXER_CALL ALmixer_GetLinkedVersion(void);
255
256 #ifdef ALMIXER_COMPILE_WITHOUT_SDL
257 /**
258 * Gets the last error string that was set by the system and clears the error.
259 *
260 * @note When compiled with SDL, this directly uses SDL_GetError.
261 *
262 * @return Returns a string containing the last error or "" when no error is set.
263 */
264 extern ALMIXER_DECLSPEC const char* ALMIXER_CALL ALmixer_GetError(void);
265 /**
266 * Sets an error string that can be retrieved by ALmixer_GetError.
267 *
268 * @note When compiled with SDL, this directly uses SDL_SetError.
269 *
270 * param The error string to set.
271 */
272 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_SetError(const char *fmt, ...);
273 #else
274 #include "SDL_error.h"
275 /**
276 * Gets the last error string that was set by the system and clears the error.
277 *
278 * @note When compiled with SDL, this directly uses SDL_GetError.
279 *
280 * @return Returns a string containing the last error or "" when no error is set.
281 */
282 #define ALmixer_GetError SDL_GetError
283 /**
284 * Sets an error string that can be retrieved by ALmixer_GetError.
285 *
286 * @note When compiled with SDL, this directly uses SDL_SetError.
287 *
288 * param The error string to set.
289 */
290 #define ALmixer_SetError SDL_SetError
291 #endif
292
293
294 #ifdef ALMIXER_COMPILE_WITHOUT_SDL
295 #include "ALmixer_rwops.h"
296 #else
297 #include "SDL_rwops.h"
298 /**
299 * A struct that mimicks the SDL_RWops structure.
300 *
301 * @note When compiled with SDL, this directly uses SDL_RWops.
302 */
303 #define ALmixer_RWops SDL_RWops
304 #endif
305
306
307 #define ALMIXER_DEFAULT_FREQUENCY 0
308 #define ALMIXER_DEFAULT_REFRESH 0
309 #define ALMIXER_DEFAULT_NUM_CHANNELS 16
310 #define ALMIXER_DEFAULT_NUM_SOURCES ALMIXER_DEFAULT_NUM_CHANNELS
311
312 /**
313 * This is the recommended Init function. This will initialize the context, SDL_sound,
314 * and the mixer system. You should call this in the setup of your code, after SDL_Init.
315 * If you attempt to bypass this function, you do so at your own risk.
316 *
317 * @note ALmixer expects the SDL audio subsystem to be disabled. In some cases, an enabled
318 * SDL audio subsystem will interfere and cause problems in your app. This Init method explicitly
319 * disables the SDL subsystem if SDL is compiled in.
320 *
321 * @note The maximum number of sources is OpenAL implementation dependent.
322 * Currently 16 is lowest common denominator for all OpenAL implementations in current use.
323 * 32 is currently the second lowest common denominator.
324 * If you try to allocate more sources than are actually available, this function may return false depending
325 * if the OpenAL implementation returns an error or not. It is possible for OpenAL to silently fail
326 * so be very careful about picking too many sources.
327 *
328 * @param playback_frequency The sample rate you want OpenAL to play at, e.g. 44100
329 * Note that OpenAL is not required to actually respect this value.
330 * Pass in 0 or ALMIXER_DEFAULT_FREQUENCY to specify you want to use your implementation's default value.
331 * @param num_sources The number of OpenAL sources (also can be thought of as
332 * SDL_mixer channels) you wish to allocate.
333 * Pass in 0 or ALMIXER_DEFAULT_NUM_SOURCES to use ALmixer's default value.
334 * @param refresh_rate The refresh rate you want OpenAL to operate at.
335 * Note that OpenAL is not required to respect this value.
336 * Pass in 0 or ALMIXER_DEFAULT_REFRESH to use OpenAL default behaviors.
337 * @return Returns AL_FALSE on a failure or AL_TRUE if successfully initialized.
338 */
339 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_Init(ALuint playback_frequency, ALint num_sources, ALuint refresh_rate);
340
341 /**
342 * InitContext will only initialize the OpenAL context (and not the mixer part).
343 * Note that SDL_Sound is also initialized here because load order matters
344 * because SDL audio will conflict with OpenAL when using SMPEG. This is only
345 * provided as a backdoor and is not recommended.
346 *
347 * @note This is a backdoor in case you need to initialize the AL context and
348 * the mixer system separately. I strongly recommend avoiding these two functions
349 * and use the normal Init() function.
350 */
351 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_InitContext(ALuint playback_frequency, ALuint refresh_rate);
352
353 /**
354 * InitMixer will only initialize the Mixer system. This is provided in the case
355 * that you need control over the loading of the context. You may load the context
356 * yourself, and then call this function. This is not recommended practice, but is
357 * provided as a backdoor in case you have good reason to
358 * do this. Be warned that if ALmixer_InitMixer() fails,
359 * it will not clean up the AL context. Also be warned that Quit() still does try to
360 * clean up everything.
361 *
362 * @note This is a backdoor in case you need to initialize the AL context and
363 * the mixer system separately. I strongly recommend avoiding these two functions
364 * and use the normal Init() function.
365 */
366 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_InitMixer(ALint num_sources);
367
368 /**
369 * This shuts down ALmixer. Please remember to free your ALmixer_Data* instances
370 * before calling this method.
371 */
372 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_Quit(void);
373 /**
374 * Returns whether ALmixer has been initializatized (via Init) or not.
375 * @return Returns true for initialized and false for not initialized.
376 */
377 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_IsInitialized(void);
378
379 /**
380 * Returns the frequency that OpenAL is set to.
381 * @note This function is not guaranteed to give correct information and is OpenAL implementation dependent.
382 * @return Returns the frequency, e.g. 44100.
383 */
384 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_GetFrequency(void);
385
386 /**
387 * Let's you change the maximum number of channels/sources available.
388 * This function is not heavily tested. It is probably better to simply initialize
389 * ALmixer with the number of sources you want when you initialize it instead of
390 * dynamically changing it later.
391 */
392 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_AllocateChannels(ALint num_chans);
393
394 /**
395 * Allows you to reserve a certain number of channels so they won't be automatically
396 * allocated to play on.
397 * This function will effectively block off a certain number of channels so they won't
398 * be automatically assigned to be played on when you call various play functions
399 * (applies to both play-channel and play-source functions since they are the same under the hood).
400 * The lowest number channels will always be blocked off first.
401 * For example, if there are 16 channels available, and you pass 2 into this function,
402 * channels 0 and 1 will be reserved so they won't be played on automatically when you specify
403 * you want to play a sound on any available channel/source. You can
404 * still play on channels 0 and 1 if you explicitly designate you want to play on their channel
405 * number or source id.
406 * Setting back to 0 will clear all the reserved channels so all will be available again for
407 * auto-assignment.
408 * As an example, this feature can be useful if you always want your music to be on channel 0 and
409 * speech on channel 1 and you don't want sound effects to ever occupy those channels. This allows
410 * you to build in certain assumptions about your code, perhaps for deciding which data you want
411 * to analyze in a data callback.
412 * Specifying the number of reserve channels to the maximum number of channels will effectively
413 * disable auto-assignment.
414 * @param number_of_reserve_channels The number of channels/sources to reserve.
415 * Or pass -1 to find out how many channels are currently reserved.
416 * @return Returns the number of currently reserved channels.
417 */
418 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ReserveChannels(ALint number_of_reserve_channels);
419
420
421 /**
422 * The update function that allows ALmixer to update its internal state.
423 * If not compiled with/using threads, this function must be periodically called
424 * to poll ALmixer to force streamed music and other events to
425 * take place.
426 * The typical place to put this function is in your main-loop.
427 * If threads are enabled, then this function just
428 * returns 0 and is effectively a no-op. With threads, it is not necessary to call this function
429 * because updates are handled internally on another thread. However, because threads are still considered
430 * experimental, it is recommended you call this function in a proper place in your code in case
431 * future versions of this library need to abandon threads.
432 * @return Returns 0 if using threads. If not using threads, for debugging purposes, it returns
433 * the number of buffers queued during the loop, or a negative value indicating the numer of errors encountered.
434 * This is subject to change and should not be relied on.
435 */
436 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_Update(void);
437
438 /**
439 * @}
440 */
441
442 /**
443 * @defgroup LoadAPI Load Audio Functions
444 * @{
445 * Functions for loading and unloading audio data.
446 */
447
448
449
450 /*
451 #define ALmixer_AudioInfo Sound_AudioInfo
452 */
453
454 /*
455 #define ALMIXER_DEFAULT_BUFFERSIZE 32768
456 #define ALMIXER_DEFAULT_BUFFERSIZE 4096
457 */
458 #define ALMIXER_DEFAULT_BUFFERSIZE 16384
459
460 /* You probably never need to use these macros directly. */
461 #ifndef ALMIXER_DISABLE_PREDECODED_PRECOMPUTE_BUFFER_SIZE_OPTIMIZATION
462 #define ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE ALMIXER_DEFAULT_BUFFERSIZE * 4
463 #else
464 /* I'm picking a smaller buffer because ALmixer will try to create a new larger buffer
465 * based on the length of the audio. So creating a large block up-front might just be a waste.
466 * However, if my attempts fail for some reason, this buffer size becomes a fallback.
467 * Having too small of a buffer might cause performance bottlenecks.
468 */
469 #define ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE 1024
470 #endif
471
472 /**
473 * Specifies the maximum number of queue buffers to use for a sound stream.
474 * Default Queue Buffers must be at least 2.
475 */
476 #define ALMIXER_DEFAULT_QUEUE_BUFFERS 5
477 /**
478 * Specifies the number of queue buffers initially filled when first loading a stream.
479 * Default startup buffers should be at least 1. */
480 #define ALMIXER_DEFAULT_STARTUP_BUFFERS 2
481
482 /*
483 #define ALMIXER_DECODE_STREAM 0
484 #define ALMIXER_DECODE_ALL 1
485 */
486
487 /* This is a trick I picked up from Lua. Doing the typedef separately
488 * (and I guess before the definition) instead of a single
489 * entry: typedef struct {...} YourName; seems to allow me
490 * to use forward declarations. Doing it the other way (like SDL)
491 * seems to prevent me from using forward declarions as I get conflicting
492 * definition errors. I don't really understand why though.
493 */
494 typedef struct ALmixer_Data ALmixer_Data;
495 typedef struct ALmixer_AudioInfo ALmixer_AudioInfo;
496
497 /**
498 * Roughly the equvialent to the Sound_AudioInfo struct in SDL_sound.
499 * Types have been changed to use AL types because I know those are available.
500 * This is different than SDL which uses fixed types so there might be subtle
501 * things you need to pay attention to..
502 * @note Originally, I just used the Sound_AudioInfo directly, but
503 * I've been trying to reduce the header dependencies for this file.
504 * But more to the point, I've been interested in dealing with the
505 * WinMain override problem Josh faced when trying to use SDL components
506 * in an MFC app which didn't like losing control of WinMain.
507 * My theory is that if I can purge the header of any thing that
508 * #include's SDL_main.h, then this might work.
509 * So I am now introducing my own AudioInfo struct.
510 */
511 struct ALmixer_AudioInfo
512 {
513 ALushort format; /**< Equivalent of SDL_AudioSpec.format. */
514 ALubyte channels; /**< Number of sound channels. 1 == mono, 2 == stereo. */
515 ALuint rate; /**< Sample rate; frequency of sample points per second. */
516 };
517
518
519
520 /**
521 * This is a general loader function to load an audio resource from an RWops.
522 * Generally, you should use the LoadStream and LoadAll specializations of this function instead which call this.
523 * @param rw_ops The rwops pointing to the audio resource you want to load.
524 * @param file_ext The file extension of your audio type which is used as a hint by the backend to decide which
525 * decoder to use.
526 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
527 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
528 * If the file is to be predecoded, optimizations may occur and this value might be ignored.
529 * @param decode_mode_is_predecoded Specifies whether you want to completely preload the data or stream the data in chunks.
530 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
531 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
532 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
533 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
534 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
535 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
536 * using this feature, so if you don't need data callbacks, you should pass false to this function.
537 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
538 */
539 extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL ALmixer_LoadSample_RW(ALmixer_RWops* rw_ops, const char* file_ext, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
540
541 #ifdef DOXYGEN_ONLY
542 /**
543 * This is the loader function to load an audio resource from an RWops as a stream.
544 * @param rw_ops The rwops pointing to the audio resource you want to load.
545 * @param file_ext The file extension of your audio type which is used as a hint by the backend to decide which
546 * decoder to use.
547 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
548 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
549 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
550 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
551 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
552 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
553 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
554 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
555 * using this feature, so if you don't need data callbacks, you should pass false to this function.
556 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
557 */
558 ALmixer_Data* ALmixer_LoadStream_RW(ALmixer_RWops* rw_ops, const char* file_ext, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
559 #else
560 #define ALmixer_LoadStream_RW(rw_ops, file_ext, buffer_size, max_queue_buffers, num_startup_buffers, access_data) ALmixer_LoadSample_RW(rw_ops,file_ext, buffer_size, AL_FALSE, max_queue_buffers, num_startup_buffers, access_data)
561 #endif
562
563 #ifdef DOXYGEN_ONLY
564 /**
565 * This is the loader function to completely preload an audio resource from an RWops into RAM.
566 * @param rw_ops The rwops pointing to the audio resource you want to load.
567 * @param file_ext The file extension of your audio type which is used as a hint by the backend to decide which
568 * decoder to use.
569 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
570 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
571 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
572 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
573 * using this feature, so if you don't need data callbacks, you should pass false to this function.
574 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
575 */
576 ALmixer_Data* ALmixer_LoadAll_RW(ALmixer_RWops* rw_ops, const char* file_ext, ALboolean access_data);
577 #else
578 #define ALmixer_LoadAll_RW(rw_ops, file_ext, access_data) ALmixer_LoadSample_RW(rw_ops, fileext, ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE, AL_TRUE, 0, 0, access_data)
579 #endif
580
581 /**
582 * This is a general loader function to load an audio resource from a file.
583 * Generally, you should use the LoadStream and LoadAll specializations of this function instead which call this.
584 * @param file_name The file of the audio resource you want to load.
585 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
586 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
587 * If the file is to be predecoded, optimizations may occur and this value might be ignored.
588 * @param decode_mode_is_predecoded Specifies whether you want to completely preload the data or stream the data in chunks.
589 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
590 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
591 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
592 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
593 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
594 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
595 * using this feature, so if you don't need data callbacks, you should pass false to this function.
596 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
597 */
598 extern ALMIXER_DECLSPEC ALmixer_Data * ALMIXER_CALL ALmixer_LoadSample(const char* file_name, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
599
600 #ifdef DOXYGEN_ONLY
601 /**
602 * This is the loader function to load an audio resource from a file.
603 * @param file_name The file to the audio resource you want to load.
604 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
605 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
606 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
607 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
608 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
609 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
610 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
611 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
612 * using this feature, so if you don't need data callbacks, you should pass false to this function.
613 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
614 */
615 ALmixer_Data* ALmixer_LoadStream(const char* file_name, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
616 #else
617 #define ALmixer_LoadStream(file_name, buffer_size, max_queue_buffers, num_startup_buffers,access_data) ALmixer_LoadSample(file_name, buffer_size, AL_FALSE, max_queue_buffers, num_startup_buffers, access_data)
618 #endif
619
620 #ifdef DOXYGEN_ONLY
621 /**
622 * This is the loader function to completely preload an audio resource from a file into RAM.
623 * @param file_name The file to the audio resource you want to load.
624 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
625 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
626 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
627 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
628 * using this feature, so if you don't need data callbacks, you should pass false to this function.
629 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
630 */
631 ALmixer_Data* ALmixer_LoadAll(const char* file_name, ALboolean access_data);
632 #else
633 #define ALmixer_LoadAll(file_name, access_data) ALmixer_LoadSample(file_name, ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE, AL_TRUE, 0, 0, access_data)
634 #endif
635
636 /**
637 * This is a back door general loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field.
638 * Use at your own risk.
639 * Generally, you should use the LoadStream and LoadAll specializations of this function instead which call this.
640 * @param rw_ops The rwops pointing to the audio resource you want to load.
641 * @param file_ext The file extension of your audio type which is used as a hint by the backend to decide which
642 * decoder to use. Pass "raw" for raw formats.
643 * @param desired_format The format you want audio decoded to. NULL will pick a default for you.
644 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
645 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
646 * If the file is to be predecoded, optimizations may occur and this value might be ignored.
647 * @param decode_mode_is_predecoded Specifies whether you want to completely preload the data or stream the data in chunks.
648 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
649 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
650 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
651 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
652 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
653 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
654 * using this feature, so if you don't need data callbacks, you should pass false to this function.
655 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
656 */
657 extern ALMIXER_DECLSPEC ALmixer_Data * ALMIXER_CALL ALmixer_LoadSample_RAW_RW(ALmixer_RWops* rw_ops, const char* file_ext, ALmixer_AudioInfo* desired_format, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
658
659 #ifdef DOXYGEN_ONLY
660 /**
661 * This is a back door stream loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field.
662 * Use at your own risk.
663 * @param rw_ops The rwops pointing to the audio resource you want to load.
664 * @param file_ext The file extension of your audio type which is used as a hint by the backend to decide which
665 * decoder to use. Pass "raw" for raw formats.
666 * @param desired_format The format you want audio decoded to. NULL will pick a default for you.
667 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
668 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
669 * If the file is to be predecoded, optimizations may occur and this value might be ignored.
670 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
671 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
672 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
673 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
674 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
675 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
676 * using this feature, so if you don't need data callbacks, you should pass false to this function.
677 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
678 */
679 ALmixer_Data* ALmixer_LoadStream_RAW_RW(ALmixer_RWops* rw_ops, const char* file_ext, ALmixer_AudioInfo* desired_format, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
680 #else
681 #define ALmixer_LoadStream_RAW_RW(rw_ops, file_ext, desired_format, buffer_size, max_queue_buffers, num_startup_buffers, access_data) ALmixer_LoadSample_RAW_RW(rw_ops, file_ext, desired_format, buffer_size, AL_FALSE, max_queue_buffers, num_startup_buffers, access_data)
682 #endif
683
684 #ifdef DOXYGEN_ONLY
685 /**
686 * This is a back door loader function for complete preloading RAW samples into RAM or if you need to specify the ALmixer_AudioInfo field.
687 * Use at your own risk.
688 * @param rw_ops The rwops pointing to the audio resource you want to load.
689 * @param file_ext The file extension of your audio type which is used as a hint by the backend to decide which
690 * decoder to use. Pass "raw" for raw formats.
691 * @param desired_format The format you want audio decoded to. NULL will pick a default for you.
692 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
693 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
694 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
695 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
696 * using this feature, so if you don't need data callbacks, you should pass false to this function.
697 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
698 */
699 ALmixer_Data* ALmixer_LoadAll_RAW_RW(ALmixer_RWops* rw_ops, const char* file_ext, ALmixer_AudioInfo* desired_format, ALboolean access_data);
700 #else
701 #define ALmixer_LoadAll_RAW_RW(rw_ops, file_ext, desired_format, access_data) ALmixer_LoadSample_RAW_RW(rw_ops, file_ext, desired_format, ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE, AL_TRUE, 0, 0, access_data)
702 #endif
703
704 /**
705 * This is a back door general loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field.
706 * Use at your own risk.
707 * Generally, you should use the LoadStream and LoadAll specializations of this function instead which call this.
708 * @param file_name The file to the audio resource you want to load. Extension should be "raw" for raw formats.
709 * @param desired_format The format you want audio decoded to. NULL will pick a default for you.
710 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
711 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
712 * If the file is to be predecoded, optimizations may occur and this value might be ignored.
713 * @param decode_mode_is_predecoded Specifies whether you want to completely preload the data or stream the data in chunks.
714 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
715 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
716 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
717 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
718 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
719 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
720 * using this feature, so if you don't need data callbacks, you should pass false to this function.
721 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
722 */
723 extern ALMIXER_DECLSPEC ALmixer_Data * ALMIXER_CALL ALmixer_LoadSample_RAW(const char* file_name, ALmixer_AudioInfo* desired_format, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
724
725 #ifdef DOXYGEN_ONLY
726 /**
727 * This is a back door stream loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field.
728 * Use at your own risk.
729 * @param file_name The file to the audio resource you want to load.Extension should be "raw" for raw formats.
730 * @param desired_format The format you want audio decoded to. NULL will pick a default for you.
731 * @param buffer_size The size of a buffer to allocate for read chunks. This number should be in quantized with
732 * the valid frame sizes of your audio data. If the data is streamed, the data will be read in buffer_size chunks.
733 * If the file is to be predecoded, optimizations may occur and this value might be ignored.
734 * @param max_queue_buffers For streamed data, specifies the maximum number of buffers that can be queued at any given time.
735 * @param num_startup_buffers For streamed data, specifies the number of buffers to fill before playback starts.
736 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
737 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
738 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
739 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
740 * using this feature, so if you don't need data callbacks, you should pass false to this function.
741 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
742 */
743 ALmixer_Data* ALmixer_LoadStream_RAW(const char* file_name, ALmixer_AudioInfo* desired_format, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALboolean access_data);
744 #else
745 #define ALmixer_LoadStream_RAW(file_name, desired_format, buffer_size, max_queue_buffers, num_startup_buffers, access_data) ALmixer_LoadSample_RAW(file_name, desired_format, buffer_size, AL_FALSE, max_queue_buffers, num_startup_buffers, access_data)
746 #endif
747
748 #ifdef DOXYGEN_ONLY
749 /**
750 * This is a back door loader function for complete preloading RAW samples into RAM or if you need to specify the ALmixer_AudioInfo field.
751 * Use at your own risk.
752 * @param file_name The file to the audio resource you want to load. Extension should be "raw" for raw formats.
753 * @param desired_format The format you want audio decoded to. NULL will pick a default for you.
754 * @param access_data A boolean that specifies if you want the data contained in the currently playing buffer to be handed
755 * to you in a callback function. Note that for predecoded data, you get back the entire buffer in one callback when the
756 * audio first starts playing. With streamed data, you get the data in buffer_size chunks. Callbacks are not guarnanteed
757 * to be perfectly in-sync as this is a best-effort implementaiton. There are memory and performance considerations for
758 * using this feature, so if you don't need data callbacks, you should pass false to this function.
759 * @return Returns an ALmixer_Data* of the loaded sample or NULL if failed.
760 */
761 ALmixer_Data* ALmixer_LoadAll_RAW(const char* file_name, ALmixer_AudioInfo* desired_format, ALboolean access_data);
762 #else
763 #define ALmixer_LoadAll_RAW(file_name, desired_format, access_data) ALmixer_LoadSample_RAW(file_name, desired_format, ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE, AL_TRUE, 0, 0, access_data)
764 #endif
765
766 /**
767 * Frees an ALmixer_Data.
768 * Releases the memory associated with a ALmixer_Data. Use this when you are done playing the audio sample
769 * and wish to release the memory.
770 * @warning Do not try releasing data that is currently in use (e.g. playing, paused).
771 * @warning Make sure to free your data before calling ALmixer_Quit. Do not free data aftter ALmixer_Quit().
772 * @param almixer_data The ALmixer_Data* you want to free.
773 */
774 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_FreeData(ALmixer_Data* almixer_data);
775
776
777 /**
778 * Returns true if the almixer_data was completely loaded into memory or false if it was loaded
779 * as a stream.
780 * @param almixer_data The audio resource you want to know about.
781 * @return AL_TRUE is predecoded, or AL_FALSE if streamed.
782 */
783 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_IsPredecoded(ALmixer_Data* almixer_data);
784
785 /**
786 * @}
787 */
788
789 /**
790 * @defgroup CallbackAPI Callbacks
791 * @{
792 * Functions for callbacks
793 */
794
795 /**
796 * Allows you to set a callback for when a sound has finished playing on a channel/source.
797 * @param playback_finished_callback The function you want to be invoked when a sound finishes.
798 * The callback function will pass you back the channel number which just finished playing,
799 * the OpenAL source id associated with the channel, the ALmixer_Data* that was played,
800 * a boolean telling you whether a sound finished playing because it ended normally or because
801 * something interrupted the playback (such as the user calling ALmixer_Halt*), and the
802 * user_data supplied as the second parameter to this function.
803 * @param which_chan The ALmixer channel that the data is currently playing on.
804 * @param al_source The OpenAL source that the data is currently playing on.
805 * @param almixer_data The ALmixer_Data that was played.
806 * @param finished_naturally AL_TRUE if the sound finished playing because it ended normally
807 * or AL_FALSE because something interrupted playback (such as the user calling ALmixer_Halt*).
808 * @param user_data This will be passed back to you in the callback.
809 *
810 * @warning You should not call other ALmixer functions in this callback.
811 * Particularly in the case of when compiled with threads, recursive locking
812 * will occur which will lead to deadlocks. Also be aware that particularly in the
813 * threaded case, the callbacks may (and currently do) occur on a background thread.
814 * One typical thread safe strategy is to set flags or schedule events to occur on the
815 * main thread.
816 * One possible exception to the no-calling ALmixer functions rule is ALmixer_Free. ALmixer_Free
817 * currently does not lock so it might okay to call this to free your data. However, this is not
818 * tested and not the expected pattern to be used.
819 */
820 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_SetPlaybackFinishedCallback(void (*playback_finished_callback)(ALint which_channel, ALuint al_source, ALmixer_Data* almixer_data, ALboolean finished_naturally, void* user_data), void* user_data);
821
822 /**
823 * Allows you to set a callback for getting audio data.
824 * This is a callback function pointer that when set, will trigger a function
825 * anytime there is new data loaded for a sample. The appropriate load
826 * parameter must be set in order for a sample to appear here.
827 * Keep in mind the the current backend implementation must do an end run
828 * around OpenAL because OpenAL lacks support for this kind of thing.
829 * As such, buffers are copied at decode time, and there is no attempt to do
830 * fine grained timing syncronization. You will be provided the entire buffer
831 * that is decoded regardless of length. So if you predecoded the entire
832 * audio file, the entire data buffer will be provided in a single callback.
833 * If you stream the data, you will be getting chunk sizes that are the same as
834 * what you specified the decode size to be. Unfortunely, this means if you
835 * pick smaller buffers, you get finer detail at the expense/risk of buffer
836 * underruns. If you decode more data, you have to deal with the syncronization
837 * issues if you want to display the data during playback in something like an
838 * oscilloscope.
839 *
840 * @warning You should not call other ALmixer functions in this callback.
841 * Particularly in the case of when compiled with threads, recursive locking
842 * will occur which will lead to deadlocks. Also be aware that particularly in the
843 * threaded case, the callbacks may (and currently do) occur on a background thread.
844 * One typical thread safe strategy is to set flags or schedule events to occur on the
845 * main thread.
846 *
847 * @param playback_data_callback The function you want called back.
848 * @param which_channel The ALmixer channel that the data is currently playing on.
849 * @param al_source The OpenAL source that the data is currently playing on.
850 * @param pcm_data This is a pointer to the data buffer containing ALmixer's
851 * version of the decoded data. Consider this data as read-only. In the
852 * non-threaded backend, this data will persist until potentially the next call
853 * to Update(). Currently, data buffers are preallocated and not destroyed
854 * until FreeData() is called (though this behavior is subject to change),
855 * but the contents will change when the buffer needs to be reused for a
856 * future callback. The buffer reuse is tied to the amount of buffers that
857 * may be queued.
858 * But assuming I don't change this, this may allow for some optimization
859 * so you can try referencing data from these buffers without worrying
860 * about crashing. (You still need to be aware that the data could be
861 * modified behind the scenes on an Update().)
862 * The data type listed is an signed 8-bit format, but the real data may
863 * not actually be this. ALbyte was chosen as a convenience. If you have
864 * a 16 bit format, you will want to cast the data and divide the num_bytes by 2.
865 * Typically, data is either Sint16. This seems to be a
866 * convention audio people seem to follow though I'm not sure what the
867 * underlying reasons (if any) are for this. I suspect that there may be
868 * some nice alignment/conversion property if you need to cast between ALbyte
869 * and ALubyte.
870 *
871 * @param num_bytes This is the total length of the data buffer. It presumes
872 * that this length is measured for ALbyte. So if you have Sint16 data, you
873 * should divide num_bytes by two if you access the data as Sint16.
874 *
875 * @param frequency The frequency the data was decoded at.
876 *
877 * @param num_channels_in_sample 1 for mono, 2 for stereo. Not to be confused with the ALmixer which_channel.
878 *
879 * @param bit_depth Bits per sample. This is expected to be 8 or 16. This
880 * number will tell you if you if you need to treat the data buffer as
881 * 16 bit or not.
882 *
883 * @param is_unsigned 1 if the data is unsigned, 0 if signed. Using this
884 * combined with bit_depth will tell you if you need to treat the data
885 * as ALubyte, ALbyte, ALuint, or ALint.
886 *
887 * @param decode_mode_is_predecoded This is here to tell you if the data was totally
888 * predecoded or loaded as a stream. If predecoded, you will only get
889 * one data callback per playback instance. (This might also be true for
890 * looping the same sample...I don't remember how it was implemented.
891 * Maybe this should be fixed.)
892 * 0 (ALMIXER_DECODE_STREAM) for streamed.
893 * 1 (ALMIXER_DECODE_ALL) for predecoded.
894 *
895 * @param length_in_msec This returns the total length (time) of the data
896 * buffer in milliseconds. This could be computed yourself, but is provided
897 * as a convenince.
898 *
899 * @param user_data The user data you pass in will be passed back to you in the callback.
900 */
901 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_SetPlaybackDataCallback(void (*playback_data_callback)(ALint which_channel, ALuint al_source, ALbyte* pcm_data, ALuint num_bytes, ALuint frequency, ALubyte num_channels_in_sample, ALubyte bit_depth, ALboolean is_unsigned, ALboolean decode_mode_is_predecoded, ALuint length_in_msec, void* user_data), void* user_data);
902
903 /**
904 * @}
905 */
906
907 /**
908 * @defgroup PlayAPI Functions useful for playback.
909 * @{
910 * These are core functions that are useful for controlling playback.
911 * Also see the Volume functions for additional playback functions and Query functions for additional information.
912 */
913
914 /**
915 * Returns the total time in milliseconds of the audio resource.
916 * Returns the total time in milliseconds of the audio resource.
917 * If the total length cannot be determined, -1 will be returned.
918 * @param almixer_data The audio sample you want to know the total time of.
919 * @return The total time in milliseconds or -1 if some kind of failure.
920 */
921 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_GetTotalTime(ALmixer_Data* almixer_data);
922
923 /**
924 * This function will look up the OpenAL source id for the corresponding channel number.
925 * @param which_channel The channel which you want to find the corresponding OpenAL source id for.
926 * If -1 was specified, an available source for playback will be returned.
927 * @return The OpenAL source id corresponding to the channel. 0 if you specified an illegal channel value.
928 * Or 0 if you specified -1 and no sources were currently available.
929 * @note ALmixer assumes your OpenAL implementation does not use 0 as a valid source ID. While the OpenAL spec
930 * does not disallow 0 for valid source ids, as of now, there are no known OpenAL implementations in use that
931 * use 0 as a valid source id (partly due to problems this has caused developers in the past).
932 */
933 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_GetSource(ALint which_channel);
934
935 /**
936 * This function will look up the channel for the corresponding source.
937 * @param al_source The source id you want to find the corresponding channel number for.
938 * If -1 is supplied, it will try to return the first channel not in use.
939 * Returns -1 on error, or the channel.
940 */
941 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_GetChannel(ALuint al_source);
942
943 /**
944 * Will look for a channel available for playback.
945 * Given a start channel number, the search will increase to the highest channel until it finds one available.
946 * @param start_channel The channel number you want to start looking at.
947 * @return A channel available or -1 if none could be found.
948 */
949 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FindFreeChannel(ALint start_channel);
950
951
952
953 /**
954 * Play a sound on a channel with a time limit.
955 * Plays a sound on a channel and will auto-stop after a specified number of milliseconds.
956 * @param which_channel Allows you to specify the specific channel you want to play on.
957 * Channels range from 0 to the (Number of allocated channels - 1). If you specify -1,
958 * an available channel will be chosen automatically for you.
959 * @note While paused, the auto-stop clock will also be paused. This makes it easy to always stop
960 * a sample by a predesignated length without worrying about whether the user paused playback which would
961 * throw off your calculations.
962 * @param almixer_data The audio resource you want to play.
963 * @param number_of_loops The number of times to loop (repeat) playing the data.
964 * 0 means the data will play exactly once without repeat. -1 means infinitely loop.
965 * @param number_of_milliseconds The number of milliseconds that should be played until the sample is auto-stopped.
966 * -1 means don't auto-stop playing and let the sample finish playing normally (or if looping is set to infinite,
967 * the sample will never stop playing).
968 * @return Returns the channel that was selected for playback or -1 if no channels were available.
969 */
970 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_PlayChannelTimed(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops, ALint number_of_milliseconds);
971
972 #ifdef DOXYGEN_ONLY
973 /**
974 * The same as ALmixer_PlayChannelTimed, but the sound is played without time limits.
975 * @see ALmixer_PlayChannelTimed.
976 */
977 ALint ALmixer_PlayChannelTimed(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops);
978 #else
979 #define ALmixer_PlayChannel(channel,data,loops) ALmixer_PlayChannelTimed(channel,data,loops,-1)
980 #endif
981
982
983 /**
984 * Play a sound on an OpenAL source with a time limit.
985 * Plays a sound on an OpenAL source and will auto-stop after a specified number of milliseconds.
986 * @param al_source Allows you to specify the OpenAL source you want to play on.
987 * If you specify 0, an available source will be chosen automatically for you.
988 * @note Source values are not necessarily continguous and their values are implementation dependent.
989 * Always use ALmixer functions to determine source values.
990 * @note While paused, the auto-stop clock will also be paused. This makes it easy to always stop
991 * a sample by a predesignated length without worrying about whether the user paused playback which would
992 * throw off your calculations.
993 * @param almixer_data The audio resource you want to play.
994 * @param number_of_loops The number of times to loop (repeat) playing the data.
995 * 0 means the data will play exactly once without repeat. -1 means infinitely loop.
996 * @param number_of_milliseconds The number of milliseconds that should be played until the sample is auto-stopped.
997 * -1 means don't auto-stop playing and let the sample finish playing normally (or if looping is set to infinite,
998 * the sample will never stop playing).
999 * @return Returns the OpenAL source that was selected for playback or 0 if no sources were available.
1000 */
1001 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_PlaySourceTimed(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops, ALint number_of_milliseconds);
1002
1003 #ifdef DOXYGEN_ONLY
1004 /**
1005 * The same as ALmixer_PlaySourceTimed, but the sound is played without time limits.
1006 * @see ALmixer_PlaySourceTimed.
1007 */
1008 ALint ALmixer_PlayChannelTimed(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops);
1009 #else
1010 #define ALmixer_PlaySource(al_source, almixer_data, number_of_loops) ALmixer_PlaySourceTimed(al_source, almixer_data, number_of_loops, -1)
1011 #endif
1012
1013 /**
1014 * Stops playback on a channel.
1015 * Stops playback on a channel and clears the channel so it can be played on again.
1016 * @note Callbacks will still be invoked, but the finished_naturally flag will be set to AL_FALSE.
1017 * @param which_channel The channel to halt or -1 to halt all channels.
1018 * @return The actual number of channels halted on success or -1 on error.
1019 */
1020 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_HaltChannel(ALint which_channel);
1021
1022 /**
1023 * Stops playback on a channel.
1024 * Stops playback on a channel and clears the channel so it can be played on again.
1025 * @note Callbacks will still be invoked, but the finished_naturally flag will be set to AL_FALSE.
1026 * @param al_source The source to halt or 0 to halt all sources.
1027 * @return The actual number of sources halted on success or -1 on error.
1028 */
1029 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_HaltSource(ALuint al_source);
1030
1031 /**
1032 * Rewinds the sound to the beginning for a given data.
1033 * Rewinds the actual data, but the effect
1034 * may not be noticed until the currently buffered data is played.
1035 * @param almixer_data The data to rewind.
1036 * @returns 0 on success or -1 on error.
1037 */
1038 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_RewindData(ALmixer_Data* almixer_data);
1039
1040 /**
1041 * Rewinds the sound to the beginning that is playing on a specific channel.
1042 * If decoded all, rewind will instantly rewind it. Data is not
1043 * affected, so it will start at the "Seek"'ed positiond.
1044 * Streamed data will rewind the actual data, but the effect
1045 * may not be noticed until the currently buffered data is played.
1046 * @param which_channel The channel to rewind or -1 to rewind all channels.
1047 * @returns 0 on success or -1 on error.
1048 */
1049 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_RewindChannel(ALint which_channel);
1050 /**
1051 * Rewinds the sound to the beginning that is playing on a specific source.
1052 * If decoded all, rewind will instantly rewind it. Data is not
1053 * affected, so it will start at the "Seek"'ed positiond.
1054 * Streamed data will rewind the actual data, but the effect
1055 * may not be noticed until the currently buffered data is played.
1056 * @param al_source The source to rewind or 0 to rewind all sources.
1057 * @returns 1 on success or 0 on error.
1058 */
1059 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_RewindSource(ALuint al_source);
1060
1061 /**
1062 * Seek the sound for a given data.
1063 * Seeks the actual data to the given millisecond. It
1064 * may not be noticed until the currently buffered data is played.
1065 * @param almixer_data
1066 * @param msec_pos The time position to seek to in the audio in milliseconds.
1067 * @returns 0 on success or -1 on error.
1068 */
1069 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_SeekData(ALmixer_Data* almixer_data, ALuint msec_pos);
1070
1071 /**
1072 * Pauses playback on a channel.
1073 * Pauses playback on a channel. Should have no effect on channels that aren't playing.
1074 * @param which_channel The channel to pause or -1 to pause all channels.
1075 * @return The actual number of channels paused on success or -1 on error.
1076 */
1077 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_PauseChannel(ALint which_channel);
1078 /**
1079 * Pauses playback on a source.
1080 * Pauses playback on a source. Should have no effect on source that aren't playing.
1081 * @param al_source The source to pause or -1 to pause all source.
1082 * @return The actual number of source paused on success or -1 on error.
1083 */
1084 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_PauseSource(ALuint al_source);
1085
1086 /**
1087 * Resumes playback on a channel that is paused.
1088 * Resumes playback on a channel that is paused. Should have no effect on channels that aren't paused.
1089 * @param which_channel The channel to resume or -1 to resume all channels.
1090 * @return The actual number of channels resumed on success or -1 on error.
1091 */
1092 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ResumeChannel(ALint which_channel);
1093
1094 /**
1095 * Resumes playback on a source that is paused.
1096 * Resumes playback on a source that is paused. Should have no effect on sources that aren't paused.
1097 * @param al_source The source to resume or -1 to resume all sources.
1098 * @return The actual number of sources resumed on success or -1 on error.
1099 */
1100 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ResumeSource(ALuint al_source);
1101
1102
1103 /**
1104 * Will cause a currently playing channel to stop playing in the specified number of milliseconds.
1105 * Will cause a currently playing channel to stop playing in the specified number of milliseconds.
1106 * This will override the value that was set when PlayChannelTimed or PlaySourceTimed was called
1107 * or override any previous calls to ExpireChannel or ExpireSource.
1108 * @param which_channel The channel to expire or -1 to apply to all channels.
1109 * @param number_of_milliseconds How many milliseconds from now until the expire triggers.
1110 * @return The actual number of channels this action is applied to on success or -1 on error.
1111 */
1112 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ExpireChannel(ALint which_channel, ALint number_of_milliseconds);
1113 /**
1114 * Will cause a currently playing source to stop playing in the specified number of milliseconds.
1115 * Will cause a currently playing source to stop playing in the specified number of milliseconds.
1116 * This will override the value that was set when PlayChannelTimed or PlaySourceTimed was called
1117 * or override any previous calls to ExpireChannel or ExpireSource.
1118 * @param al_source The source to expire or 0 to apply to all sources.
1119 * @param number_of_milliseconds How many milliseconds from now until the expire triggers.
1120 * @return The actual number of sources this action is applied to on success or -1 on error.
1121 */
1122 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ExpireSource(ALuint al_source, ALint number_of_milliseconds);
1123
1124 /**
1125 * @}
1126 */
1127
1128 /**
1129 * @defgroup VolumeAPI Volume and Fading
1130 * @{
1131 * Fade and volume functions directly call OpenAL functions related to AL_GAIN.
1132 * These functions are provided mostly for those who just want to play audio but are not planning
1133 * to use OpenAL features directly.
1134 * If you are using OpenAL directly (e.g. for 3D effects), you may want to be careful about using these as
1135 * they may fight/override values you directly set yourself.
1136 */
1137
1138 /**
1139 * Similar to ALmixer_PlayChannelTimed except that sound volume fades in from the minimum volume to the current AL_GAIN over the specified amount of time.
1140 * @see ALmixer_PlayChannelTimed.
1141 */
1142 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeInChannelTimed(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks, ALint expire_ticks);
1143
1144 #ifdef DOXYGEN_ONLY
1145 /**
1146 * The same as ALmixer_FadeInChannelTimed, but the sound is played without time limits.
1147 * @see ALmixer_FadeInChannelTimed, ALmixer_PlayChannel.
1148 */
1149 ALint ALmixer_FadeInChannel(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks);
1150 #else
1151 #define ALmixer_FadeInChannel(which_channel, almixer_data, number_of_loops, fade_ticks) ALmixer_FadeInChannelTimed(which_channel, almixer_data, number_of_loops, fade_ticks, -1)
1152 #endif
1153
1154 /**
1155 * Similar to ALmixer_PlaySourceTimed except that sound volume fades in from the minimum volume to the max volume over the specified amount of time.
1156 * @see ALmixer_PlaySourceTimed.
1157 */
1158 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_FadeInSourceTimed(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks, ALint expire_ticks);
1159
1160 #ifdef DOXYGEN_ONLY
1161 /**
1162 * The same as ALmixer_FadeInSourceTimed, but the sound is played without time limits.
1163 * @see ALmixer_FadeInSourceTimed, ALmixer_PlaySource.
1164 */
1165 extern ALuint ALmixer_FadeInSource(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks);
1166 #else
1167 #define ALmixer_FadeInSource(al_source, almixer_data, number_of_loops, fade_ticks) ALmixer_FadeInSourceTimed(al_source, almixer_data, number_of_loops, fade_ticks, -1)
1168 #endif
1169
1170 /**
1171 * Fade out a current playing channel.
1172 * Will fade out a currently playing channel over the specified period of time starting from now.
1173 * The volume will be changed from the current AL_GAIN level to the AL_MIN_GAIN.
1174 * The volume fade will interpolate over the specified period of time.
1175 * The playback will halt at the end of the time period.
1176 * @param which_channel The channel to fade or -1 to fade all playing channels.
1177 * @param fade_ticks In milliseconds, the amount of time the fade out should take to complete.
1178 * @return Returns -1 on error or the number of channels faded.
1179 */
1180 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeOutChannel(ALint which_channel, ALuint fade_ticks);
1181
1182 /**
1183 * Fade out a current playing source.
1184 * Will fade out a currently playing source over the specified period of time starting from now.
1185 * The volume will be changed from the current AL_GAIN level to the AL_MIN_GAIN.
1186 * The volume fade will interpolate over the specified period of time.
1187 * The playback will halt at the end of the time period.
1188 * @param al_source The source to fade or -1 to fade all playing sources.
1189 * @param fade_ticks In milliseconds, the amount of time the fade out should take to complete.
1190 * @return Returns -1 on error or the number of sources faded.
1191 */
1192 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeOutSource(ALuint al_source, ALuint fade_ticks);
1193
1194 /**
1195 * Gradually changes the volume from the current AL_GAIN to the specified volume.
1196 * Gradually changes the volume from the current AL_GAIN to the specified volume over the specified period of time.
1197 * This is some times referred to as volume ducking.
1198 * Note that this function works for setting the volume higher as well as lower.
1199 * @param which_channel The channel to fade or -1 to fade all playing channels.
1200 * @param fade_ticks In milliseconds, the amount of time the volume change should take to complete.
1201 * @param volume The volume to change to. Valid values are 0.0 to 1.0.
1202 * @return Returns -1 on error or the number of channels faded.
1203 */
1204 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeChannel(ALint which_channel, ALuint fade_ticks, ALfloat volume);
1205
1206 /**
1207 * Gradually changes the volume from the current AL_GAIN to the specified volume.
1208 * Gradually changes the volume from the current AL_GAIN to the specified volume over the specified period of time.
1209 * This is some times referred to as volume ducking.
1210 * Note that this function works for setting the volume higher as well as lower.
1211 * @param al_source The source to fade or -1 to fade all playing sources.
1212 * @param fade_ticks In milliseconds, the amount of time the volume change should take to complete.
1213 * @param volume The volume to change to. Valid values are 0.0 to 1.0.
1214 * @return Returns -1 on error or the number of sources faded.
1215 */
1216 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeSource(ALuint al_source, ALuint fade_ticks, ALfloat volume);
1217
1218 /**
1219 * Sets the volume via the AL_GAIN source property.
1220 * Sets the volume for a given channel via the AL_GAIN source property.
1221 * @param which_channel The channel to set the volume to or -1 to set on all channels.
1222 * @param volume The new volume to use. Valid values are 0.0 to 1.0.
1223 * @return AL_TRUE on success or AL_FALSE on error.
1224 */
1225 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetVolumeChannel(ALint which_channel, ALfloat volume);
1226
1227 /**
1228 * Sets the volume via the AL_GAIN source property.
1229 * Sets the volume for a given source via the AL_GAIN source property.
1230 * @param al_source The source to set the volume to or 0 to set on all sources.
1231 * @param volume The new volume to use. Valid values are 0.0 to 1.0.
1232 * @return AL_TRUE on success or AL_FALSE on error.
1233 */
1234 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetVolumeSource(ALuint al_source, ALfloat volume);
1235
1236 /**
1237 * Gets the volume via the AL_GAIN source property.
1238 * Gets the volume for a given channel via the AL_GAIN source property.
1239 * @param which_channel The channel to get the volume from.
1240 * -1 will return the average volume set across all channels.
1241 * @return Returns the volume for the specified channel, or the average set volume for all channels, or -1.0 on error.
1242 */
1243 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetVolumeChannel(ALint which_channel);
1244
1245 /**
1246 * Gets the volume via the AL_GAIN source property.
1247 * Gets the volume for a given source via the AL_GAIN source property.
1248 * @param al_source The source to get the volume from.
1249 * -1 will return the average volume set across all source.
1250 * @return Returns the volume for the specified source, or the average set volume for all sources, or -1.0 on error.
1251 */
1252 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetVolumeSource(ALuint al_source);
1253
1254 /**
1255 * Sets the maximum volume via the AL_MAX_GAIN source property.
1256 * Sets the maximum volume for a given channel via the AL_MAX_GAIN source property.
1257 * Max volumes will be clamped to this value.
1258 * @param which_channel The channel to set the volume to or -1 to set on all channels.
1259 * @param volume The new volume to use. Valid values are 0.0 to 1.0.
1260 * @return AL_TRUE on success or AL_FALSE on error.
1261 */
1262 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMaxVolumeChannel(ALint which_channel, ALfloat volume);
1263
1264 /**
1265 * Sets the maximum volume via the AL_MAX_GAIN source property.
1266 * Sets the maximum volume for a given source via the AL_MAX_GAIN source property.
1267 * @param al_source The source to set the volume to or 0 to set on all sources.
1268 * @param volume The new volume to use. Valid values are 0.0 to 1.0.
1269 * @return AL_TRUE on success or AL_FALSE on error.
1270 */
1271 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMaxVolumeSource(ALuint al_source, ALfloat volume);
1272
1273 /**
1274 * Gets the max volume via the AL_MAX_GAIN source property.
1275 * Gets the max volume for a given channel via the AL_MAX_GAIN source property.
1276 * @param which_channel The channel to get the volume from.
1277 * -1 will return the average volume set across all channels.
1278 * @return Returns the volume for the specified channel, or the average set volume for all channels, or -1.0 on error.
1279 */
1280 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMaxVolumeChannel(ALint which_channel);
1281
1282 /**
1283 * Gets the maximum volume via the AL_MAX_GAIN source property.
1284 * Gets the maximum volume for a given source via the AL_MAX_GAIN source property.
1285 * @param al_source The source to set the volume to or 0 to set on all sources.
1286 * 0 will return the average volume set across all channels.
1287 * @return Returns the volume for the specified channel, or the average set volume for all channels, or -1.0 on error.
1288 */
1289 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMaxVolumeSource(ALuint al_source);
1290
1291 /**
1292 * Sets the minimum volume via the AL_MIN_GAIN source property.
1293 * Sets the minimum volume for a given channel via the AL_MIN_GAIN source property.
1294 * Min volumes will be clamped to this value.
1295 * @param which_channel The channel to set the volume to or -1 to set on all channels.
1296 * @param volume The new volume to use. Valid values are 0.0 to 1.0.
1297 * @return AL_TRUE on success or AL_FALSE on error.
1298 */
1299 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMinVolumeChannel(ALint which_channel, ALfloat volume);
1300
1301 /**
1302 * Sets the minimum volume via the AL_MIN_GAIN source property.
1303 * Sets the minimum volume for a given source via the AL_MIN_GAIN source property.
1304 * @param al_source The source to set the volume to or 0 to set on all sources.
1305 * @param volume The new volume to use. Valid values are 0.0 to 1.0.
1306 * @return AL_TRUE on success or AL_FALSE on error.
1307 */
1308 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMinVolumeSource(ALuint al_source, ALfloat volume);
1309
1310 /**
1311 * Gets the min volume via the AL_MIN_GAIN source property.
1312 * Gets the min volume for a given channel via the AL_MIN_GAIN source property.
1313 * @param which_channel The channel to get the volume from.
1314 * -1 will return the average volume set across all channels.
1315 * @return Returns the volume for the specified channel, or the average set volume for all channels, or -1.0 on error.
1316 */
1317 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMinVolumeChannel(ALint which_channel);
1318
1319 /**
1320 * Gets the min volume via the AL_MIN_GAIN source property.
1321 * Gets the min volume for a given source via the AL_MIN_GAIN source property.
1322 * @param al_source The source to set the volume to or 0 to set on all sources.
1323 * 0 will return the average volume set across all channels.
1324 * @return Returns the volume for the specified channel, or the average set volume for all channels, or -1.0 on error.
1325 */
1326 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMinVolumeSource(ALuint al_source);
1327
1328 /**
1329 * Sets the OpenAL listener AL_GAIN which can be thought of as the "master volume".
1330 * Sets the OpenAL listener AL_GAIN which can be thought of as the "master volume".
1331 * @param new_volume The new volume level to be set. Range is 0.0 to 1.0 where 1.0 is the max volume.
1332 * @return AL_TRUE on success or AL_FALSE on an error.
1333 */
1334 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMasterVolume(ALfloat new_volume);
1335
1336 /**
1337 * Gets the OpenAL listener AL_GAIN which can be thought of as the "master volume".
1338 * Gets the OpenAL listener AL_GAIN which can be thought of as the "master volume".
1339 * @return The current volume level on the listener. -1.0 will be returned on an error.
1340 */
1341 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMasterVolume(void);
1342
1343 /**
1344 * @}
1345 */
1346
1347 /**
1348 * @defgroup QueryAPI Query APIs
1349 * @{
1350 * Functions to query ALmixer.
1351 */
1352
1353
1354 /**
1355 * Returns true if the specified channel is currently playing or paused,
1356 * or if -1 is passed the number of channels that are currently playing or paused.
1357 * @param which_channel The channel you want to know about or -1 to get the count of
1358 * currently playing/paused channels.
1359 * @return For a specific channel, 1 if the channel is playing or paused, 0 if not.
1360 * Or returns the count of currently playing/paused channels.
1361 * Or -1 on an error.
1362 */
1363 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsActiveChannel(ALint which_channel);
1364
1365 /**
1366 * Returns true if the specified source is currently playing or paused,
1367 * or if -1 is passed the number of sources that are currently playing or paused.
1368 * @param al_source The channel you want to know about or -1 to get the count of
1369 * currently playing/paused sources.
1370 * @return For a specific sources, 1 if the channel is playing or paused, 0 if not.
1371 * Or returns the count of currently playing/paused sources.
1372 * Or -1 on an error.
1373 */
1374 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsActiveSource(ALuint al_source);
1375
1376 /**
1377 * Returns true if the specified channel is currently playing.
1378 * or if -1 is passed the number of channels that are currently playing.
1379 * @param which_channel The channel you want to know about or -1 to get the count of
1380 * currently playing channels.
1381 * @return For a specific channel, 1 if the channel is playing, 0 if not.
1382 * Or returns the count of currently playing channels.
1383 * Or -1 on an error.
1384 */
1385 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPlayingChannel(ALint which_channel);
1386
1387 /**
1388 * Returns true if the specified sources is currently playing.
1389 * or if -1 is passed the number of sources that are currently playing.
1390 * @param al_source The sources you want to know about or -1 to get the count of
1391 * currently playing sources.
1392 * @return For a specific source, 1 if the source is playing, 0 if not.
1393 * Or returns the count of currently playing sources.
1394 * Or -1 on an error.
1395 */
1396 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPlayingSource(ALuint al_source);
1397
1398 /**
1399 * Returns true if the specified channel is currently paused.
1400 * or if -1 is passed the number of channels that are currently paused.
1401 * @param which_channel The channel you want to know about or -1 to get the count of
1402 * currently paused channels.
1403 * @return For a specific channel, 1 if the channel is paused, 0 if not.
1404 * Or returns the count of currently paused channels.
1405 * Or -1 on an error.
1406 */
1407 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPausedChannel(ALint which_channel);
1408
1409 /**
1410 * Returns true if the specified sources is currently paused.
1411 * or if -1 is passed the number of sources that are currently paused.
1412 * @param al_source The source you want to know about or -1 to get the count of
1413 * currently paused sources.
1414 * @return For a specific source, 1 if the source is paused, 0 if not.
1415 * Or returns the count of currently paused sources.
1416 * Or -1 on an error.
1417 */
1418 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPausedSource(ALuint al_source);
1419
1420 /**
1421 * Returns the number of channels that are currently available for playback (not playing, not paused).
1422 * @return The number of channels that are currently free.
1423 */
1424 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountAllFreeChannels(void);
1425
1426 /**
1427 * Returns the number of channels that are currently available for playback (not playing, not paused),
1428 * excluding the channels that have been reserved.
1429 * @return The number of channels that are currently in free, excluding the channels that have been reserved.
1430 * @see ALmixer_ReserveChannels
1431 */
1432 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountUnreservedFreeChannels(void);
1433
1434 /**
1435 * Returns the number of channels that are currently in use (playing/paused),
1436 * excluding the channels that have been reserved.
1437 * @return The number of channels that are currently in use.
1438 * @see ALmixer_ReserveChannels
1439 */
1440 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountAllUsedChannels(void);
1441
1442 /**
1443 * Returns the number of channels that are currently in use (playing/paused),
1444 * excluding the channels that have been reserved.
1445 * @return The number of channels that are currently in use excluding the channels that have been reserved.
1446 * @see ALmixer_ReserveChannels
1447 */
1448 extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountUnreservedUsedChannels(void);
1449
1450
1451 #ifdef DOXYGEN_ONLY
1452 /**
1453 * Returns the number of allocated channels.
1454 * This is just a convenience alias to ALmixer_AllocateChannels(-1).
1455 * @see ALmixer_AllocateChannels
1456 */
1457 ALint ALmixer_CountTotalChannels(void);
1458 #else
1459 #define ALmixer_CountTotalChannels() ALmixer_AllocateChannels(-1)
1460 #endif
1461
1462
1463
1464
1465 #ifdef DOXYGEN_ONLY
1466 /**
1467 * Returns the number of allocated channels.
1468 * This is just a convenience alias to ALmixer_ReserveChannels(-1).
1469 * @see ALmixer_ReserveChannels
1470 */
1471 ALint ALmixer_CountReservedChannels(void);
1472 #else
1473 #define ALmixer_CountReservedChannels() ALmixer_ReserveChannels(-1)
1474 #endif
1475
1476
1477 /**
1478 * @}
1479 */
1480
1481 /**
1482 * @defgroup DebugAPI Debug APIs
1483 * @{
1484 * Functions for debugging purposes. These may be removed in future versions.
1485 */
1486
1487
1488 /* For testing */
1489 #if 0
1490 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_OutputAttributes(void);
1491 #endif
1492 /** This function may be removed in the future. For debugging. Prints to stderr. Lists the decoders available. */
1493 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_OutputDecoders(void);
1494 /** This function may be removed in the future. For debugging. Prints to stderr. */
1495 extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_OutputOpenALInfo(void);
1496
1497 /** This function may be removed in the future. Returns true if compiled with threads, false if not. */
1498 extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_CompiledWithThreadBackend(void);
1499
1500 /**
1501 * @}
1502 */
1503
1504
1505
1506
1507 /* Ends C function definitions when using C++ */
1508 #ifdef __cplusplus
1509 }
1510 #endif
1511
1512
1513 #endif /* _SDL_ALMIXER_H_ */
1514
1515 /* end of SDL_ALmixer.h ... */
1516
1517