SDL_OpenAudio — Opens the audio device with the desired parameters.
#include "SDL.h"
int
SDL_OpenAudio( |
SDL_AudioSpec * | desired, |
SDL_AudioSpec * | 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
. 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 -1 if it failed to open the audio device, or couldn't
set up the audio thread.
To open the audio device a desired
SDL_AudioSpec
must be created.
SDL_AudioSpec *desired; . . desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
You must then fill this structure with your desired audio specifications.
desired
->freq
desired
->format
desired
->samples
desired
->callback
void callback(void *userdata, Uint8 *stream, int len);
userdata
is the
pointer stored in userdata
field of the
SDL_AudioSpec
. stream
is a pointer to the
audio buffer you want to fill with information and len
is the length of the
audio buffer in bytes.
desired
->userdata
SDL_OpenAudio
reads these
fields from the desired
SDL_AudioSpec
structure pass to the
function and attempts to find an audio configuration matching
your desired
. As
mentioned above, if the obtained
parameter is
NULL
then SDL with convert from
your desired
audio
settings to the hardware settings as it plays.
If obtained
is
NULL
then the desired
SDL_AudioSpec
is your working
specification, otherwise the obtained
SDL_AudioSpec
becomes the working
specification and the desirec
specification can be
deleted. The data in the working specification is used when
building SDL_AudioCVT
's for
converting loaded data to the hardware format.
SDL_OpenAudio
calculates the
size
and silence
fields for both the
desired
and
obtained
specifications. The size
field stores the total
size of the audio buffer in bytes, while the silence
stores the value used
to represent silence in the audio buffer
The audio device starts out playing silence
when it's 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.
/* Prototype of our callback function */ void my_audio_callback(void *userdata, Uint8 *stream, int len); /* Open the audio device */ SDL_AudioSpec *desired, *obtained; SDL_AudioSpec *hardware_spec; /* Allocate a desired SDL_AudioSpec */ desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec)); /* Allocate space for the obtained SDL_AudioSpec */ obtained=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec)); /* 22050Hz - FM Radio quality */ desired->freq=22050; /* 16-bit signed audio */ desired->format=AUDIO_S16LSB; /* Mono */ desired->channels=0; /* Large audio buffer reduces risk of dropouts but increases response time */ desired->samples=8192; /* 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 ", SDL_GetError()); exit(-1); } /* desired spec is no longer needed */ free(desired); hardware_spec=obtained; . . /* Prepare callback for playing */ . . . /* Start playing */ SDL_PauseAudio(0);
SDL_AudioSpec(3), SDL_LockAudio(3), SDL_UnlockAudio(3), SDL_PauseAudio(3)
COPYRIGHT |
---|
This manual page is taken from the SDL library, licensed under GNU LGPL. |