|
Size: 4766
Comment: update content - filled in with
|
Size: 4903
Comment: Added a little info about SDL_LockAudio()/SDL_UnlockAudio().
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| Line 14: | Line 13: |
| == Function Parameters == ||'''desired''' ||the desired audio parameters ''-or-'' an [[SDL_AudioSpec]] structure representing the desired output format; see [[#desired|Remarks]] for more information || ||'''obtained''' ||an [[SDL_AudioSpec]] structure filled in with the actual parameters || |
|
| Line 15: | Line 17: |
| == Function Parameters == ||'''desired'''||the desired audio parameters ''-or-'' an [[SDL_AudioSpec]] structure representing the desired output format; see [[#desired|Remarks]] for more information|| ||'''obtained'''||an [[SDL_AudioSpec]] structure filled in with the actual parameters|| |
|
| Line 20: | Line 19: |
| This function opens the audio device with the desired parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by '''obtained'''. | This function opens the audio device with the desired parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by '''obtained'''. |
| Line 22: | Line 21: |
| If '''obtained''' is NULL, the audio data passed to the callback function will be guaranteed to be in the requested format, and will be automatically converted to the hardware audio format if necessary. | If '''obtained''' is NULL, the audio data passed to the callback function will be guaranteed to be in the requested format, and will be automatically converted to the hardware audio format if necessary. |
| Line 64: | Line 63: |
| == Remarks == <<Anchor(desired)>> To open the audio device a desired [[SDL_AudioSpec]] must be created. |
|
| Line 65: | Line 66: |
| == Remarks == <<Anchor(desired)>> To open the audio device a desired [[SDL_AudioSpec]] must be created. |
|
| Line 73: | Line 72: |
| When filling in the '''desired''' audio spec structure, *`desired->freq` should be the desired audio frequency in samples-per-second *`desired->format` should be the desired audio format *`desired->samples` is the desired size of the audio buffer, in samples. This number should be a power of two, and may be adjusted by the audio driver to a value more suitable for the hardware. Good values seem to range between 512 and 8096 inclusive, depending on the application and CPU speed. Smaller values yield faster response time, but can lead to underflow if the application is doing heavy processing and cannot fill the audio buffer in time. A stereo sample consists of both right and left channels in LR ordering. Note that the number of samples is directly related to time by the following formula: ms = (samples*1000)/freq *`desired->size` is the size in bytes of the audio buffer, and is calculated by [[SDL_OpenAudio]]() *`desired->silence` is the value used to set the buffer to silence, and is calculated by [[SDL_OpenAudio]]() *`desired->callback` should be set to a function that will be called when the audio device is ready for more data. It is passed a pointer to the audio buffer, and the length in bytes of the audio buffer. This function usually runs in a separate thread, so you should protect data structures that it accesses by calling [[SDL_LockAudio]]() and [[SDL_UnlockAudio]]() in your code. *`desired->userdata` is passed as the first parameter to your callback function. |
When filling in the '''desired''' audio spec structure, * `desired->freq` should be the desired audio frequency in samples-per-second * `desired->format` should be the desired audio format * `desired->samples` is the desired size of the audio buffer, in samples. This number should be a power of two, and may be adjusted by the audio driver to a value more suitable for the hardware. Good values seem to range between 512 and 8096 inclusive, depending on the application and CPU speed. Smaller values yield faster response time, but can lead to underflow if the application is doing heavy processing and cannot fill the audio buffer in time. A stereo sample consists of both right and left channels in LR ordering. Note that the number of samples is directly related to time by the following formula: ms = (samples*1000)/freq * `desired->size` is the size in bytes of the audio buffer, and is calculated by [[SDL_OpenAudio]]() * `desired->silence` is the value used to set the buffer to silence, and is calculated by [[SDL_OpenAudio]]() * `desired->callback` should be set to a function that will be called when the audio device is ready for more data. It is passed a pointer to the audio buffer, and the length in bytes of the audio buffer. This function usually runs in a separate thread, so you should protect data structures that it accesses by calling [[SDL_LockAudio]]() and [[SDL_UnlockAudio]]() in your code. '''Note''': You should not call [[SDL_LockAudio]]()/[[SDL_UnlockAudio]]() from within your callback code, as it may cause a deadlock. * `desired->userdata` is passed as the first parameter to your callback function. |
| Line 90: | Line 89: |
| .[[SDL_CloseAudio]] .[[SDL_LockAudio]] .[[SDL_PauseAudio]] .[[SDL_UnlockAudio]] |
. [[SDL_CloseAudio]] . [[SDL_LockAudio]] . [[SDL_PauseAudio]] . [[SDL_UnlockAudio]] |
| Line 96: | Line 95: |
| [[CategoryAPI]], [[CategoryAudio]] | [[CategoryAPI]], CategoryAudio |
SDL_OpenAudio
Use this function to open the audio device with the desired parameters.
Contents
Syntax
int SDL_OpenAudio(SDL_AudioSpec* desired,
SDL_AudioSpec* obtained)
Function Parameters
desired |
the desired audio parameters -or- an SDL_AudioSpec structure representing the desired output format; see Remarks for more information |
obtained |
an SDL_AudioSpec structure filled in with the actual parameters |
Return Value
This function opens the audio device with the desired parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by obtained.
If obtained is NULL, the audio data passed to the callback function will be guaranteed to be in the requested format, and will be automatically converted to the hardware audio format if necessary.
This function returns a negative error code on failure to open the audio device or failure to set up the audio thread; call SDL_GetError() for more information.
Code Examples
/* Prototype of our callback function */
void my_audio_callback(void *userdata, Uint8 *stream, int len);
/* Open the audio device */
SDL_AudioSpec desired, obtained;
/* 22050Hz - FM Radio quality */
desired.freq=22050;
/* 16-bit signed audio */
desired.format=AUDIO_S16SYS;
/* Stereo */
desired.channels=2;
/* Large audio buffer reduces risk of dropouts but increases response time */
desired.samples=4096;
/* Our callback function */
desired.callback=my_audio_callback;
desired.userdata=NULL;
/* Open the audio device */
if ( SDL_OpenAudio(&desired, &obtained) < 0 ){
fprintf(stderr, "Couldn't open audio: %s\n", SDL_GetError());
exit(-1);
}
.
.
/* Prepare callback for playing */
.
.
.
/* Start playing */
SDL_PauseAudio(0);
Remarks
To open the audio device a desired SDL_AudioSpec must be created.
SDL_AudioSpec *desired;
.
.
desired = malloc(sizeof(SDL_AudioSpec));
When filling in the desired audio spec structure,
desired->freq should be the desired audio frequency in samples-per-second
desired->format should be the desired audio format
desired->samples is the desired size of the audio buffer, in samples. This number should be a power of two, and may be adjusted by the audio driver to a value more suitable for the hardware. Good values seem to range between 512 and 8096 inclusive, depending on the application and CPU speed. Smaller values yield faster response time, but can lead to underflow if the application is doing heavy processing and cannot fill the audio buffer in time. A stereo sample consists of both right and left channels in LR ordering. Note that the number of samples is directly related to time by the following formula: ms = (samples*1000)/freq
desired->size is the size in bytes of the audio buffer, and is calculated by SDL_OpenAudio()
desired->silence is the value used to set the buffer to silence, and is calculated by SDL_OpenAudio()
desired->callback should be set to a function that will be called when the audio device is ready for more data. It is passed a pointer to the audio buffer, and the length in bytes of the audio buffer. This function usually runs in a separate thread, so you should protect data structures that it accesses by calling SDL_LockAudio() and SDL_UnlockAudio() in your code. Note: You should not call SDL_LockAudio()/SDL_UnlockAudio() from within your callback code, as it may cause a deadlock.
desired->userdata is passed as the first parameter to your callback function.
SDL_OpenAudio() reads these fields from desired and attempts to find a matching audio configuration. As mentioned above, if obtained is NULL then SDL with convert from your desired audio settings to the hardware settings as it plays.
If obtained is NULL then desired is your working specification, otherwise obtained is filled in with the working specification. The data in the working specification is used when building SDL_AudioCVT's for converting loaded data to the hardware format.
The audio device starts out playing silence when it is opened, and should be enabled for playing by calling SDL_PauseAudio(0) when you are ready for your audio callback function to be called. Since the audio driver may modify the requested size of the audio buffer, you should allocate any local mixing buffers after you open the audio device.
