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