docs/html/sdlopenaudio.html

   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 >