docs/html/sdlopenaudio.html
changeset 3352 6dc250ebdd80
parent 3351 8e0182c236d8
child 3353 6b14223dd5c7
equal deleted inserted replaced
3351:8e0182c236d8 3352:6dc250ebdd80
     1 <HTML
       
     2 ><HEAD
       
     3 ><TITLE
       
     4 >SDL_OpenAudio</TITLE
       
     5 ><META
       
     6 NAME="GENERATOR"
       
     7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
       
     8 "><LINK
       
     9 REL="HOME"
       
    10 TITLE="SDL Library Documentation"
       
    11 HREF="index.html"><LINK
       
    12 REL="UP"
       
    13 TITLE="Audio"
       
    14 HREF="audio.html"><LINK
       
    15 REL="PREVIOUS"
       
    16 TITLE="SDL_AudioSpec"
       
    17 HREF="sdlaudiospec.html"><LINK
       
    18 REL="NEXT"
       
    19 TITLE="SDL_PauseAudio"
       
    20 HREF="sdlpauseaudio.html"></HEAD
       
    21 ><BODY
       
    22 CLASS="REFENTRY"
       
    23 BGCOLOR="#FFF8DC"
       
    24 TEXT="#000000"
       
    25 LINK="#0000ee"
       
    26 VLINK="#551a8b"
       
    27 ALINK="#ff0000"
       
    28 ><DIV
       
    29 CLASS="NAVHEADER"
       
    30 ><TABLE
       
    31 SUMMARY="Header navigation table"
       
    32 WIDTH="100%"
       
    33 BORDER="0"
       
    34 CELLPADDING="0"
       
    35 CELLSPACING="0"
       
    36 ><TR
       
    37 ><TH
       
    38 COLSPAN="3"
       
    39 ALIGN="center"
       
    40 >SDL Library Documentation</TH
       
    41 ></TR
       
    42 ><TR
       
    43 ><TD
       
    44 WIDTH="10%"
       
    45 ALIGN="left"
       
    46 VALIGN="bottom"
       
    47 ><A
       
    48 HREF="sdlaudiospec.html"
       
    49 ACCESSKEY="P"
       
    50 >Prev</A
       
    51 ></TD
       
    52 ><TD
       
    53 WIDTH="80%"
       
    54 ALIGN="center"
       
    55 VALIGN="bottom"
       
    56 ></TD
       
    57 ><TD
       
    58 WIDTH="10%"
       
    59 ALIGN="right"
       
    60 VALIGN="bottom"
       
    61 ><A
       
    62 HREF="sdlpauseaudio.html"
       
    63 ACCESSKEY="N"
       
    64 >Next</A
       
    65 ></TD
       
    66 ></TR
       
    67 ></TABLE
       
    68 ><HR
       
    69 ALIGN="LEFT"
       
    70 WIDTH="100%"></DIV
       
    71 ><H1
       
    72 ><A
       
    73 NAME="SDLOPENAUDIO"
       
    74 ></A
       
    75 >SDL_OpenAudio</H1
       
    76 ><DIV
       
    77 CLASS="REFNAMEDIV"
       
    78 ><A
       
    79 NAME="AEN6650"
       
    80 ></A
       
    81 ><H2
       
    82 >Name</H2
       
    83 >SDL_OpenAudio&nbsp;--&nbsp;Opens the audio device with the desired parameters.</DIV
       
    84 ><DIV
       
    85 CLASS="REFSYNOPSISDIV"
       
    86 ><A
       
    87 NAME="AEN6653"
       
    88 ></A
       
    89 ><H2
       
    90 >Synopsis</H2
       
    91 ><DIV
       
    92 CLASS="FUNCSYNOPSIS"
       
    93 ><A
       
    94 NAME="AEN6654"
       
    95 ></A
       
    96 ><P
       
    97 ></P
       
    98 ><PRE
       
    99 CLASS="FUNCSYNOPSISINFO"
       
   100 >#include "SDL.h"</PRE
       
   101 ><P
       
   102 ><CODE
       
   103 ><CODE
       
   104 CLASS="FUNCDEF"
       
   105 >int <B
       
   106 CLASS="FSFUNC"
       
   107 >SDL_OpenAudio</B
       
   108 ></CODE
       
   109 >(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);</CODE
       
   110 ></P
       
   111 ><P
       
   112 ></P
       
   113 ></DIV
       
   114 ></DIV
       
   115 ><DIV
       
   116 CLASS="REFSECT1"
       
   117 ><A
       
   118 NAME="AEN6660"
       
   119 ></A
       
   120 ><H2
       
   121 >Description</H2
       
   122 ><P
       
   123 >This function opens the audio device with the <TT
       
   124 CLASS="PARAMETER"
       
   125 ><I
       
   126 >desired</I
       
   127 ></TT
       
   128 > parameters, and
       
   129 returns 0 if successful, placing the actual hardware parameters in the
       
   130 structure pointed to by <TT
       
   131 CLASS="PARAMETER"
       
   132 ><I
       
   133 >obtained</I
       
   134 ></TT
       
   135 >.  If <TT
       
   136 CLASS="PARAMETER"
       
   137 ><I
       
   138 >obtained</I
       
   139 ></TT
       
   140 > is NULL, the audio
       
   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
       
   145 ><P
       
   146 >To open the audio device a <TT
       
   147 CLASS="PARAMETER"
       
   148 ><I
       
   149 >desired</I
       
   150 ></TT
       
   151 > <A
       
   152 HREF="sdlaudiospec.html"
       
   153 ><SPAN
       
   154 CLASS="STRUCTNAME"
       
   155 >SDL_AudioSpec</SPAN
       
   156 ></A
       
   157 > must be created.
       
   158 <PRE
       
   159 CLASS="PROGRAMLISTING"
       
   160 >SDL_AudioSpec *desired;
       
   161 .
       
   162 .
       
   163 desired = malloc(sizeof(SDL_AudioSpec));</PRE
       
   164 >
       
   165 You must then fill this structure with your desired audio specifications.</P
       
   166 ><P
       
   167 ></P
       
   168 ><DIV
       
   169 CLASS="VARIABLELIST"
       
   170 ><DL
       
   171 ><DT
       
   172 ><SPAN
       
   173 CLASS="STRUCTNAME"
       
   174 >desired</SPAN
       
   175 >-&#62;<TT
       
   176 CLASS="STRUCTFIELD"
       
   177 ><I
       
   178 >freq</I
       
   179 ></TT
       
   180 ></DT
       
   181 ><DD
       
   182 ><P
       
   183 >The desired audio frequency in samples-per-second.</P
       
   184 ></DD
       
   185 ><DT
       
   186 ><SPAN
       
   187 CLASS="STRUCTNAME"
       
   188 >desired</SPAN
       
   189 >-&#62;<TT
       
   190 CLASS="STRUCTFIELD"
       
   191 ><I
       
   192 >format</I
       
   193 ></TT
       
   194 ></DT
       
   195 ><DD
       
   196 ><P
       
   197 >The desired audio format (see <A
       
   198 HREF="sdlaudiospec.html"
       
   199 ><SPAN
       
   200 CLASS="STRUCTNAME"
       
   201 >SDL_AudioSpec</SPAN
       
   202 ></A
       
   203 >)</P
       
   204 ></DD
       
   205 ><DT
       
   206 ><SPAN
       
   207 CLASS="STRUCTNAME"
       
   208 >desired</SPAN
       
   209 >-&#62;<TT
       
   210 CLASS="STRUCTFIELD"
       
   211 ><I
       
   212 >samples</I
       
   213 ></TT
       
   214 ></DT
       
   215 ><DD
       
   216 ><P
       
   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
       
   218 ></DD
       
   219 ><DT
       
   220 ><SPAN
       
   221 CLASS="STRUCTNAME"
       
   222 >desired</SPAN
       
   223 >-&#62;<TT
       
   224 CLASS="STRUCTFIELD"
       
   225 ><I
       
   226 >callback</I
       
   227 ></TT
       
   228 ></DT
       
   229 ><DD
       
   230 ><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"
       
   233 ><TT
       
   234 CLASS="FUNCTION"
       
   235 >SDL_LockAudio</TT
       
   236 ></A
       
   237 > and <A
       
   238 HREF="sdlunlockaudio.html"
       
   239 ><TT
       
   240 CLASS="FUNCTION"
       
   241 >SDL_UnlockAudio</TT
       
   242 ></A
       
   243 > in your code. The callback prototype is:
       
   244 <PRE
       
   245 CLASS="PROGRAMLISTING"
       
   246 >void callback(void *userdata, Uint8 *stream, int len);</PRE
       
   247 >
       
   248 <TT
       
   249 CLASS="PARAMETER"
       
   250 ><I
       
   251 >userdata</I
       
   252 ></TT
       
   253 > is the pointer stored in <TT
       
   254 CLASS="STRUCTFIELD"
       
   255 ><I
       
   256 >userdata</I
       
   257 ></TT
       
   258 > field of the <SPAN
       
   259 CLASS="STRUCTNAME"
       
   260 >SDL_AudioSpec</SPAN
       
   261 >. <TT
       
   262 CLASS="PARAMETER"
       
   263 ><I
       
   264 >stream</I
       
   265 ></TT
       
   266 > is a pointer to the audio buffer you want to fill with information and <TT
       
   267 CLASS="PARAMETER"
       
   268 ><I
       
   269 >len</I
       
   270 ></TT
       
   271 > is the length of the audio buffer in bytes.</P
       
   272 ></DD
       
   273 ><DT
       
   274 ><SPAN
       
   275 CLASS="STRUCTNAME"
       
   276 >desired</SPAN
       
   277 >-&#62;<TT
       
   278 CLASS="STRUCTFIELD"
       
   279 ><I
       
   280 >userdata</I
       
   281 ></TT
       
   282 ></DT
       
   283 ><DD
       
   284 ><P
       
   285 >This pointer is passed as the first parameter to the <TT
       
   286 CLASS="FUNCTION"
       
   287 >callback</TT
       
   288 > function.</P
       
   289 ></DD
       
   290 ></DL
       
   291 ></DIV
       
   292 ><P
       
   293 ><TT
       
   294 CLASS="FUNCTION"
       
   295 >SDL_OpenAudio</TT
       
   296 > reads these fields from the <TT
       
   297 CLASS="PARAMETER"
       
   298 ><I
       
   299 >desired</I
       
   300 ></TT
       
   301 > <SPAN
       
   302 CLASS="STRUCTNAME"
       
   303 >SDL_AudioSpec</SPAN
       
   304 > structure pass to the function and attempts to find an audio configuration matching your <TT
       
   305 CLASS="PARAMETER"
       
   306 ><I
       
   307 >desired</I
       
   308 ></TT
       
   309 >. As mentioned above, if the <TT
       
   310 CLASS="PARAMETER"
       
   311 ><I
       
   312 >obtained</I
       
   313 ></TT
       
   314 > parameter is <TT
       
   315 CLASS="LITERAL"
       
   316 >NULL</TT
       
   317 > then SDL with convert from your <TT
       
   318 CLASS="PARAMETER"
       
   319 ><I
       
   320 >desired</I
       
   321 ></TT
       
   322 > audio settings to the hardware settings as it plays.</P
       
   323 ><P
       
   324 >If <TT
       
   325 CLASS="PARAMETER"
       
   326 ><I
       
   327 >obtained</I
       
   328 ></TT
       
   329 > is <TT
       
   330 CLASS="LITERAL"
       
   331 >NULL</TT
       
   332 > then the <TT
       
   333 CLASS="PARAMETER"
       
   334 ><I
       
   335 >desired</I
       
   336 ></TT
       
   337 > <SPAN
       
   338 CLASS="STRUCTNAME"
       
   339 >SDL_AudioSpec</SPAN
       
   340 > is your working specification, otherwise the <TT
       
   341 CLASS="PARAMETER"
       
   342 ><I
       
   343 >obtained</I
       
   344 ></TT
       
   345 > <SPAN
       
   346 CLASS="STRUCTNAME"
       
   347 >SDL_AudioSpec</SPAN
       
   348 > becomes the working specification and the <TT
       
   349 CLASS="PARAMETER"
       
   350 ><I
       
   351 >desirec</I
       
   352 ></TT
       
   353 > specification can be deleted. The data in the working specification is used when building <SPAN
       
   354 CLASS="STRUCTNAME"
       
   355 >SDL_AudioCVT</SPAN
       
   356 >'s for converting loaded data to the hardware format.</P
       
   357 ><P
       
   358 ><TT
       
   359 CLASS="FUNCTION"
       
   360 >SDL_OpenAudio</TT
       
   361 > calculates the <TT
       
   362 CLASS="STRUCTFIELD"
       
   363 ><I
       
   364 >size</I
       
   365 ></TT
       
   366 > and <TT
       
   367 CLASS="STRUCTFIELD"
       
   368 ><I
       
   369 >silence</I
       
   370 ></TT
       
   371 > fields for both the <TT
       
   372 CLASS="PARAMETER"
       
   373 ><I
       
   374 >desired</I
       
   375 ></TT
       
   376 > and <TT
       
   377 CLASS="PARAMETER"
       
   378 ><I
       
   379 >obtained</I
       
   380 ></TT
       
   381 > specifications. The <TT
       
   382 CLASS="STRUCTFIELD"
       
   383 ><I
       
   384 >size</I
       
   385 ></TT
       
   386 > field stores the total size of the audio buffer in bytes, while the <TT
       
   387 CLASS="STRUCTFIELD"
       
   388 ><I
       
   389 >silence</I
       
   390 ></TT
       
   391 > stores the value used to represent silence in the audio buffer</P
       
   392 ><P
       
   393 >The audio device starts out playing <TT
       
   394 CLASS="STRUCTFIELD"
       
   395 ><I
       
   396 >silence</I
       
   397 ></TT
       
   398 > when it's opened, and should be enabled for playing by calling <A
       
   399 HREF="sdlpauseaudio.html"
       
   400 ><TT
       
   401 CLASS="FUNCTION"
       
   402 >SDL_PauseAudio</TT
       
   403 >(<TT
       
   404 CLASS="PARAMETER"
       
   405 ><I
       
   406 >0</I
       
   407 ></TT
       
   408 >)</A
       
   409 > when you are ready for your audio <TT
       
   410 CLASS="STRUCTFIELD"
       
   411 ><I
       
   412 >callback</I
       
   413 ></TT
       
   414 > function to be called.  Since the audio driver may modify the requested <TT
       
   415 CLASS="STRUCTFIELD"
       
   416 ><I
       
   417 >size</I
       
   418 ></TT
       
   419 > of the audio buffer, you should allocate any local mixing buffers after you open the audio device.</P
       
   420 ></DIV
       
   421 ><DIV
       
   422 CLASS="REFSECT1"
       
   423 ><A
       
   424 NAME="AEN6747"
       
   425 ></A
       
   426 ><H2
       
   427 >Examples</H2
       
   428 ><PRE
       
   429 CLASS="PROGRAMLISTING"
       
   430 >/* Prototype of our callback function */
       
   431 void my_audio_callback(void *userdata, Uint8 *stream, int len);
       
   432 
       
   433 /* Open the audio device */
       
   434 SDL_AudioSpec *desired, *obtained;
       
   435 SDL_AudioSpec *hardware_spec;
       
   436 
       
   437 /* Allocate a desired SDL_AudioSpec */
       
   438 desired = malloc(sizeof(SDL_AudioSpec));
       
   439 
       
   440 /* Allocate space for the obtained SDL_AudioSpec */
       
   441 obtained = malloc(sizeof(SDL_AudioSpec));
       
   442 
       
   443 /* 22050Hz - FM Radio quality */
       
   444 desired-&#62;freq=22050;
       
   445 
       
   446 /* 16-bit signed audio */
       
   447 desired-&#62;format=AUDIO_S16LSB;
       
   448 
       
   449 /* Mono */
       
   450 desired-&#62;channels=0;
       
   451 
       
   452 /* Large audio buffer reduces risk of dropouts but increases response time */
       
   453 desired-&#62;samples=8192;
       
   454 
       
   455 /* Our callback function */
       
   456 desired-&#62;callback=my_audio_callback;
       
   457 
       
   458 desired-&#62;userdata=NULL;
       
   459 
       
   460 /* Open the audio device */
       
   461 if ( SDL_OpenAudio(desired, obtained) &#60; 0 ){
       
   462   fprintf(stderr, "Couldn't open audio: %s\n", SDL_GetError());
       
   463   exit(-1);
       
   464 }
       
   465 /* desired spec is no longer needed */
       
   466 free(desired);
       
   467 hardware_spec=obtained;
       
   468 .
       
   469 .
       
   470 /* Prepare callback for playing */
       
   471 .
       
   472 .
       
   473 .
       
   474 /* Start playing */
       
   475 SDL_PauseAudio(0);</PRE
       
   476 ></DIV
       
   477 ><DIV
       
   478 CLASS="REFSECT1"
       
   479 ><A
       
   480 NAME="AEN6750"
       
   481 ></A
       
   482 ><H2
       
   483 >See Also</H2
       
   484 ><P
       
   485 ><A
       
   486 HREF="sdlaudiospec.html"
       
   487 ><TT
       
   488 CLASS="FUNCTION"
       
   489 >SDL_AudioSpec</TT
       
   490 ></A
       
   491 >,
       
   492 <A
       
   493 HREF="sdllockaudio.html"
       
   494 ><TT
       
   495 CLASS="FUNCTION"
       
   496 >SDL_LockAudio</TT
       
   497 ></A
       
   498 >,
       
   499 <A
       
   500 HREF="sdlunlockaudio.html"
       
   501 ><TT
       
   502 CLASS="FUNCTION"
       
   503 >SDL_UnlockAudio</TT
       
   504 ></A
       
   505 >,
       
   506 <A
       
   507 HREF="sdlpauseaudio.html"
       
   508 ><TT
       
   509 CLASS="FUNCTION"
       
   510 >SDL_PauseAudio</TT
       
   511 ></A
       
   512 ></P
       
   513 ></DIV
       
   514 ><DIV
       
   515 CLASS="NAVFOOTER"
       
   516 ><HR
       
   517 ALIGN="LEFT"
       
   518 WIDTH="100%"><TABLE
       
   519 SUMMARY="Footer navigation table"
       
   520 WIDTH="100%"
       
   521 BORDER="0"
       
   522 CELLPADDING="0"
       
   523 CELLSPACING="0"
       
   524 ><TR
       
   525 ><TD
       
   526 WIDTH="33%"
       
   527 ALIGN="left"
       
   528 VALIGN="top"
       
   529 ><A
       
   530 HREF="sdlaudiospec.html"
       
   531 ACCESSKEY="P"
       
   532 >Prev</A
       
   533 ></TD
       
   534 ><TD
       
   535 WIDTH="34%"
       
   536 ALIGN="center"
       
   537 VALIGN="top"
       
   538 ><A
       
   539 HREF="index.html"
       
   540 ACCESSKEY="H"
       
   541 >Home</A
       
   542 ></TD
       
   543 ><TD
       
   544 WIDTH="33%"
       
   545 ALIGN="right"
       
   546 VALIGN="top"
       
   547 ><A
       
   548 HREF="sdlpauseaudio.html"
       
   549 ACCESSKEY="N"
       
   550 >Next</A
       
   551 ></TD
       
   552 ></TR
       
   553 ><TR
       
   554 ><TD
       
   555 WIDTH="33%"
       
   556 ALIGN="left"
       
   557 VALIGN="top"
       
   558 >SDL_AudioSpec</TD
       
   559 ><TD
       
   560 WIDTH="34%"
       
   561 ALIGN="center"
       
   562 VALIGN="top"
       
   563 ><A
       
   564 HREF="audio.html"
       
   565 ACCESSKEY="U"
       
   566 >Up</A
       
   567 ></TD
       
   568 ><TD
       
   569 WIDTH="33%"
       
   570 ALIGN="right"
       
   571 VALIGN="top"
       
   572 >SDL_PauseAudio</TD
       
   573 ></TR
       
   574 ></TABLE
       
   575 ></DIV
       
   576 ></BODY
       
   577 ></HTML
       
   578 >