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