7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
10 TITLE="SDL Library Documentation"
11 HREF="index.html"><LINK
14 HREF="audio.html"><LINK
17 HREF="sdlaudiospec.html"><LINK
19 TITLE="SDL_PauseAudio"
20 HREF="sdlpauseaudio.html"></HEAD
31 SUMMARY="Header navigation table"
40 >SDL Library Documentation</TH
48 HREF="sdlaudiospec.html"
62 HREF="sdlpauseaudio.html"
83 >SDL_OpenAudio -- Opens the audio device with the desired parameters.</DIV
85 CLASS="REFSYNOPSISDIV"
99 CLASS="FUNCSYNOPSISINFO"
100 >#include "SDL.h"</PRE
109 >(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);</CODE
123 >This function opens the audio device with the <TT
129 returns 0 if successful, placing the actual hardware parameters in the
130 structure pointed to by <TT
141 data passed to the callback function will be guaranteed to be in the
142 requested format, and will be automatically converted to the hardware
143 audio format if necessary. This function returns -1 if it failed
144 to open the audio device, or couldn't set up the audio thread.</P
146 >To open the audio device a <TT
152 HREF="sdlaudiospec.html"
159 CLASS="PROGRAMLISTING"
160 >SDL_AudioSpec *desired;
163 desired = malloc(sizeof(SDL_AudioSpec));</PRE
165 You must then fill this structure with your desired audio specifications.</P
183 >The desired audio frequency in samples-per-second.</P
197 >The desired audio format (see <A
198 HREF="sdlaudiospec.html"
217 >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 8192 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</P
231 >This 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, and so you should protect data structures that it accesses by calling <A
232 HREF="sdllockaudio.html"
238 HREF="sdlunlockaudio.html"
243 > in your code. The callback prototype is:
245 CLASS="PROGRAMLISTING"
246 >void callback(void *userdata, Uint8 *stream, int len);</PRE
253 > is the pointer stored in <TT
266 > is a pointer to the audio buffer you want to fill with information and <TT
271 > is the length of the audio buffer in bytes.</P
285 >This pointer is passed as the first parameter to the <TT
296 > reads these fields from the <TT
304 > structure pass to the function and attempts to find an audio configuration matching your <TT
309 >. As mentioned above, if the <TT
317 > then SDL with convert from your <TT
322 > audio settings to the hardware settings as it plays.</P
340 > is your working specification, otherwise the <TT
348 > becomes the working specification and the <TT
353 > specification can be deleted. The data in the working specification is used when building <SPAN
356 >'s for converting loaded data to the hardware format.</P
371 > fields for both the <TT
381 > specifications. The <TT
386 > field stores the total size of the audio buffer in bytes, while the <TT
391 > stores the value used to represent silence in the audio buffer</P
393 >The audio device starts out playing <TT
398 > when it's opened, and should be enabled for playing by calling <A
399 HREF="sdlpauseaudio.html"
409 > when you are ready for your audio <TT
414 > function to be called. Since the audio driver may modify the requested <TT
419 > of the audio buffer, you should allocate any local mixing buffers after you open the audio device.</P
429 CLASS="PROGRAMLISTING"
430 >/* Prototype of our callback function */
431 void my_audio_callback(void *userdata, Uint8 *stream, int len);
433 /* Open the audio device */
434 SDL_AudioSpec *desired, *obtained;
435 SDL_AudioSpec *hardware_spec;
437 /* Allocate a desired SDL_AudioSpec */
438 desired = malloc(sizeof(SDL_AudioSpec));
440 /* Allocate space for the obtained SDL_AudioSpec */
441 obtained = malloc(sizeof(SDL_AudioSpec));
443 /* 22050Hz - FM Radio quality */
444 desired->freq=22050;
446 /* 16-bit signed audio */
447 desired->format=AUDIO_S16LSB;
450 desired->channels=0;
452 /* Large audio buffer reduces risk of dropouts but increases response time */
453 desired->samples=8192;
455 /* Our callback function */
456 desired->callback=my_audio_callback;
458 desired->userdata=NULL;
460 /* Open the audio device */
461 if ( SDL_OpenAudio(desired, obtained) < 0 ){
462 fprintf(stderr, "Couldn't open audio: %s\n", SDL_GetError());
465 /* desired spec is no longer needed */
467 hardware_spec=obtained;
470 /* Prepare callback for playing */
475 SDL_PauseAudio(0);</PRE
486 HREF="sdlaudiospec.html"
493 HREF="sdllockaudio.html"
500 HREF="sdlunlockaudio.html"
507 HREF="sdlpauseaudio.html"
519 SUMMARY="Footer navigation table"
530 HREF="sdlaudiospec.html"
548 HREF="sdlpauseaudio.html"