Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4973 | right-hear | 1 | /* |
2 | SDL - Simple DirectMedia Layer |
||
3 | Copyright (C) 1997-2004 Sam Lantinga |
||
4 | |||
5 | This library is free software; you can redistribute it and/or |
||
6 | modify it under the terms of the GNU Library General Public |
||
7 | License as published by the Free Software Foundation; either |
||
8 | version 2 of the License, or (at your option) any later version. |
||
9 | |||
10 | This library is distributed in the hope that it will be useful, |
||
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
||
13 | Library General Public License for more details. |
||
14 | |||
15 | You should have received a copy of the GNU Library General Public |
||
16 | License along with this library; if not, write to the Free |
||
17 | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
||
18 | |||
19 | Sam Lantinga |
||
20 | slouken@libsdl.org |
||
21 | */ |
||
22 | |||
23 | #ifdef SAVE_RCSID |
||
24 | static char rcsid = |
||
25 | "@(#) $Id: SDL_audio.h,v 1.7 2004/01/04 16:49:07 slouken Exp $"; |
||
26 | #endif |
||
27 | |||
28 | /* Access to the raw audio mixing buffer for the SDL library */ |
||
29 | |||
30 | #ifndef _SDL_audio_h |
||
31 | #define _SDL_audio_h |
||
32 | |||
33 | #include |
||
34 | |||
35 | #include "SDL_main.h" |
||
36 | #include "SDL_types.h" |
||
37 | #include "SDL_error.h" |
||
38 | #include "SDL_rwops.h" |
||
39 | #include "SDL_byteorder.h" |
||
40 | |||
41 | #include "begin_code.h" |
||
42 | /* Set up for C function definitions, even when using C++ */ |
||
43 | #ifdef __cplusplus |
||
44 | extern "C" { |
||
45 | #endif |
||
46 | |||
47 | /* The calculated values in this structure are calculated by SDL_OpenAudio() */ |
||
48 | typedef struct { |
||
49 | int freq; /* DSP frequency -- samples per second */ |
||
50 | Uint16 format; /* Audio data format */ |
||
51 | Uint8 channels; /* Number of channels: 1 mono, 2 stereo */ |
||
52 | Uint8 silence; /* Audio buffer silence value (calculated) */ |
||
53 | Uint16 samples; /* Audio buffer size in samples (power of 2) */ |
||
54 | Uint16 padding; /* Necessary for some compile environments */ |
||
55 | Uint32 size; /* Audio buffer size in bytes (calculated) */ |
||
56 | /* This function is called when the audio device needs more data. |
||
57 | 'stream' is a pointer to the audio data buffer |
||
58 | 'len' is the length of that buffer in bytes. |
||
59 | Once the callback returns, the buffer will no longer be valid. |
||
60 | Stereo samples are stored in a LRLRLR ordering. |
||
61 | */ |
||
62 | void (*callback)(void *userdata, Uint8 *stream, int len); |
||
63 | void *userdata; |
||
64 | } SDL_AudioSpec; |
||
65 | |||
66 | /* Audio format flags (defaults to LSB byte order) */ |
||
67 | #define AUDIO_U8 0x0008 /* Unsigned 8-bit samples */ |
||
68 | #define AUDIO_S8 0x8008 /* Signed 8-bit samples */ |
||
69 | #define AUDIO_U16LSB 0x0010 /* Unsigned 16-bit samples */ |
||
70 | #define AUDIO_S16LSB 0x8010 /* Signed 16-bit samples */ |
||
71 | #define AUDIO_U16MSB 0x1010 /* As above, but big-endian byte order */ |
||
72 | #define AUDIO_S16MSB 0x9010 /* As above, but big-endian byte order */ |
||
73 | #define AUDIO_U16 AUDIO_U16LSB |
||
74 | #define AUDIO_S16 AUDIO_S16LSB |
||
75 | |||
76 | /* Native audio byte ordering */ |
||
77 | #if SDL_BYTEORDER == SDL_LIL_ENDIAN |
||
78 | #define AUDIO_U16SYS AUDIO_U16LSB |
||
79 | #define AUDIO_S16SYS AUDIO_S16LSB |
||
80 | #else |
||
81 | #define AUDIO_U16SYS AUDIO_U16MSB |
||
82 | #define AUDIO_S16SYS AUDIO_S16MSB |
||
83 | #endif |
||
84 | |||
85 | |||
86 | /* A structure to hold a set of audio conversion filters and buffers */ |
||
87 | typedef struct SDL_AudioCVT { |
||
88 | int needed; /* Set to 1 if conversion possible */ |
||
89 | Uint16 src_format; /* Source audio format */ |
||
90 | Uint16 dst_format; /* Target audio format */ |
||
91 | double rate_incr; /* Rate conversion increment */ |
||
92 | Uint8 *buf; /* Buffer to hold entire audio data */ |
||
93 | int len; /* Length of original audio buffer */ |
||
94 | int len_cvt; /* Length of converted audio buffer */ |
||
95 | int len_mult; /* buffer must be len*len_mult big */ |
||
96 | double len_ratio; /* Given len, final size is len*len_ratio */ |
||
97 | void (*filters[10])(struct SDL_AudioCVT *cvt, Uint16 format); |
||
98 | int filter_index; /* Current audio conversion function */ |
||
99 | } SDL_AudioCVT; |
||
100 | |||
101 | |||
102 | /* Function prototypes */ |
||
103 | |||
104 | /* These functions are used internally, and should not be used unless you |
||
105 | * have a specific need to specify the audio driver you want to use. |
||
106 | * You should normally use SDL_Init() or SDL_InitSubSystem(). |
||
107 | */ |
||
108 | extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name); |
||
109 | extern DECLSPEC void SDLCALL SDL_AudioQuit(void); |
||
110 | |||
111 | /* This function fills the given character buffer with the name of the |
||
112 | * current audio driver, and returns a pointer to it if the audio driver has |
||
113 | * been initialized. It returns NULL if no driver has been initialized. |
||
114 | */ |
||
115 | extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen); |
||
116 | |||
117 | /* |
||
118 | * This function opens the audio device with the desired parameters, and |
||
119 | * returns 0 if successful, placing the actual hardware parameters in the |
||
120 | * structure pointed to by 'obtained'. If 'obtained' is NULL, the audio |
||
121 | * data passed to the callback function will be guaranteed to be in the |
||
122 | * requested format, and will be automatically converted to the hardware |
||
123 | * audio format if necessary. This function returns -1 if it failed |
||
124 | * to open the audio device, or couldn't set up the audio thread. |
||
125 | * |
||
126 | * When filling in the desired audio spec structure, |
||
127 | * 'desired->freq' should be the desired audio frequency in samples-per-second. |
||
128 | * 'desired->format' should be the desired audio format. |
||
129 | * 'desired->samples' is the desired size of the audio buffer, in samples. |
||
130 | * This number should be a power of two, and may be adjusted by the audio |
||
131 | * driver to a value more suitable for the hardware. Good values seem to |
||
132 | * range between 512 and 8096 inclusive, depending on the application and |
||
133 | * CPU speed. Smaller values yield faster response time, but can lead |
||
134 | * to underflow if the application is doing heavy processing and cannot |
||
135 | * fill the audio buffer in time. A stereo sample consists of both right |
||
136 | * and left channels in LR ordering. |
||
137 | * Note that the number of samples is directly related to time by the |
||
138 | * following formula: ms = (samples*1000)/freq |
||
139 | * 'desired->size' is the size in bytes of the audio buffer, and is |
||
140 | * calculated by SDL_OpenAudio(). |
||
141 | * 'desired->silence' is the value used to set the buffer to silence, |
||
142 | * and is calculated by SDL_OpenAudio(). |
||
143 | * 'desired->callback' should be set to a function that will be called |
||
144 | * when the audio device is ready for more data. It is passed a pointer |
||
145 | * to the audio buffer, and the length in bytes of the audio buffer. |
||
146 | * This function usually runs in a separate thread, and so you should |
||
147 | * protect data structures that it accesses by calling SDL_LockAudio() |
||
148 | * and SDL_UnlockAudio() in your code. |
||
149 | * 'desired->userdata' is passed as the first parameter to your callback |
||
150 | * function. |
||
151 | * |
||
152 | * The audio device starts out playing silence when it's opened, and should |
||
153 | * be enabled for playing by calling SDL_PauseAudio(0) when you are ready |
||
154 | * for your audio callback function to be called. Since the audio driver |
||
155 | * may modify the requested size of the audio buffer, you should allocate |
||
156 | * any local mixing buffers after you open the audio device. |
||
157 | */ |
||
158 | extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained); |
||
159 | |||
160 | /* |
||
161 | * Get the current audio state: |
||
162 | */ |
||
163 | typedef enum { |
||
164 | SDL_AUDIO_STOPPED = 0, |
||
165 | SDL_AUDIO_PLAYING, |
||
166 | SDL_AUDIO_PAUSED |
||
167 | } SDL_audiostatus; |
||
168 | extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void); |
||
169 | |||
170 | /* |
||
171 | * This function pauses and unpauses the audio callback processing. |
||
172 | * It should be called with a parameter of 0 after opening the audio |
||
173 | * device to start playing sound. This is so you can safely initialize |
||
174 | * data for your callback function after opening the audio device. |
||
175 | * Silence will be written to the audio device during the pause. |
||
176 | */ |
||
177 | extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); |
||
178 | |||
179 | /* |
||
180 | * This function loads a WAVE from the data source, automatically freeing |
||
181 | * that source if 'freesrc' is non-zero. For example, to load a WAVE file, |
||
182 | * you could do: |
||
183 | * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); |
||
184 | * |
||
185 | * If this function succeeds, it returns the given SDL_AudioSpec, |
||
186 | * filled with the audio data format of the wave data, and sets |
||
187 | * 'audio_buf' to a malloc()'d buffer containing the audio data, |
||
188 | * and sets 'audio_len' to the length of that audio buffer, in bytes. |
||
189 | * You need to free the audio buffer with SDL_FreeWAV() when you are |
||
190 | * done with it. |
||
191 | * |
||
192 | * This function returns NULL and sets the SDL error message if the |
||
193 | * wave file cannot be opened, uses an unknown data format, or is |
||
194 | * corrupt. Currently raw and MS-ADPCM WAVE files are supported. |
||
195 | */ |
||
196 | extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); |
||
197 | |||
198 | /* Compatibility convenience function -- loads a WAV from a file */ |
||
199 | #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ |
||
200 | SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) |
||
201 | |||
202 | /* |
||
203 | * This function frees data previously allocated with SDL_LoadWAV_RW() |
||
204 | */ |
||
205 | extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf); |
||
206 | |||
207 | /* |
||
208 | * This function takes a source format and rate and a destination format |
||
209 | * and rate, and initializes the 'cvt' structure with information needed |
||
210 | * by SDL_ConvertAudio() to convert a buffer of audio data from one format |
||
211 | * to the other. |
||
212 | * This function returns 0, or -1 if there was an error. |
||
213 | */ |
||
214 | extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt, |
||
215 | Uint16 src_format, Uint8 src_channels, int src_rate, |
||
216 | Uint16 dst_format, Uint8 dst_channels, int dst_rate); |
||
217 | |||
218 | /* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(), |
||
219 | * created an audio buffer cvt->buf, and filled it with cvt->len bytes of |
||
220 | * audio data in the source format, this function will convert it in-place |
||
221 | * to the desired format. |
||
222 | * The data conversion may expand the size of the audio data, so the buffer |
||
223 | * cvt->buf should be allocated after the cvt structure is initialized by |
||
224 | * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long. |
||
225 | */ |
||
226 | extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt); |
||
227 | |||
228 | /* |
||
229 | * This takes two audio buffers of the playing audio format and mixes |
||
230 | * them, performing addition, volume adjustment, and overflow clipping. |
||
231 | * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME |
||
232 | * for full audio volume. Note this does not change hardware volume. |
||
233 | * This is provided for convenience -- you can mix your own audio data. |
||
234 | */ |
||
235 | #define SDL_MIX_MAXVOLUME 128 |
||
236 | extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume); |
||
237 | |||
238 | /* |
||
239 | * The lock manipulated by these functions protects the callback function. |
||
240 | * During a LockAudio/UnlockAudio pair, you can be guaranteed that the |
||
241 | * callback function is not running. Do not call these from the callback |
||
242 | * function or you will cause deadlock. |
||
243 | */ |
||
244 | extern DECLSPEC void SDLCALL SDL_LockAudio(void); |
||
245 | extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); |
||
246 | |||
247 | /* |
||
248 | * This function shuts down audio processing and closes the audio device. |
||
249 | */ |
||
250 | extern DECLSPEC void SDLCALL SDL_CloseAudio(void); |
||
251 | |||
252 | |||
253 | /* Ends C function definitions when using C++ */ |
||
254 | #ifdef __cplusplus |
||
255 | } |
||
256 | #endif |
||
257 | #include "close_code.h" |
||
258 | |||
259 | #endif /* _SDL_audio_h */ |