annotate ALmixer.h @ 61:72570fcd30e8

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