Mercurial > sdl-ios-xcode
annotate docs/html/sdlopenaudio.html @ 77:1e7e61b9b0f9
Don't crash if freeing a cursor after quit...
| author | Sam Lantinga <slouken@lokigames.com> |
|---|---|
| date | Tue, 19 Jun 2001 21:07:12 +0000 |
| parents | 55f1f1b3e27d |
| children | e5bc29de3f0a |
| 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 | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
76 NAME="AEN6103" |
| 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 | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
84 NAME="AEN6106" |
| 0 | 85 ></A |
| 86 ><H2 | |
| 87 >Synopsis</H2 | |
| 88 ><DIV | |
| 89 CLASS="FUNCSYNOPSIS" | |
| 90 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
91 NAME="AEN6107" |
| 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 | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
115 NAME="AEN6113" |
| 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 | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
421 NAME="AEN6200" |
| 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 | |
| 446 /* Large audio buffer reduces risk of dropouts but increases response time */ | |
| 447 desired->samples=8192; | |
| 448 | |
| 449 /* Our callback function */ | |
| 450 desired->callback=my_audio_callback; | |
| 451 | |
| 452 desired->userdata=NULL; | |
| 453 | |
| 454 /* Open the audio device */ | |
| 455 if ( SDL_OpenAudio(desired, obtained) < 0 ){ | |
| 456 fprintf(stderr, "Couldn't open audio: %s\n", SDL_GetError()); | |
| 457 exit(-1); | |
| 458 } | |
| 459 /* desired spec is no longer needed */ | |
| 460 free(desired); | |
| 461 hardware_spec=obtained; | |
| 462 . | |
| 463 . | |
| 464 /* Prepare callback for playing */ | |
| 465 . | |
| 466 . | |
| 467 . | |
| 468 /* Start playing */ | |
| 469 SDL_PauseAudio(0);</PRE | |
| 470 ></DIV | |
| 471 ><DIV | |
| 472 CLASS="REFSECT1" | |
| 473 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
474 NAME="AEN6203" |
| 0 | 475 ></A |
| 476 ><H2 | |
| 477 >See Also</H2 | |
| 478 ><P | |
| 479 ><A | |
| 480 HREF="sdlaudiospec.html" | |
| 481 ><TT | |
| 482 CLASS="FUNCTION" | |
| 483 >SDL_AudioSpec</TT | |
| 484 ></A | |
| 485 >, | |
| 486 <A | |
| 487 HREF="sdllockaudio.html" | |
| 488 ><TT | |
| 489 CLASS="FUNCTION" | |
| 490 >SDL_LockAudio</TT | |
| 491 ></A | |
| 492 >, | |
| 493 <A | |
| 494 HREF="sdlunlockaudio.html" | |
| 495 ><TT | |
| 496 CLASS="FUNCTION" | |
| 497 >SDL_UnlockAudio</TT | |
| 498 ></A | |
| 499 >, | |
| 500 <A | |
| 501 HREF="sdlpauseaudio.html" | |
| 502 ><TT | |
| 503 CLASS="FUNCTION" | |
| 504 >SDL_PauseAudio</TT | |
| 505 ></A | |
| 506 ></P | |
| 507 ></DIV | |
| 508 ><DIV | |
| 509 CLASS="NAVFOOTER" | |
| 510 ><HR | |
| 511 ALIGN="LEFT" | |
| 512 WIDTH="100%"><TABLE | |
| 513 WIDTH="100%" | |
| 514 BORDER="0" | |
| 515 CELLPADDING="0" | |
| 516 CELLSPACING="0" | |
| 517 ><TR | |
| 518 ><TD | |
| 519 WIDTH="33%" | |
| 520 ALIGN="left" | |
| 521 VALIGN="top" | |
| 522 ><A | |
| 523 HREF="sdlaudiospec.html" | |
| 524 >Prev</A | |
| 525 ></TD | |
| 526 ><TD | |
| 527 WIDTH="34%" | |
| 528 ALIGN="center" | |
| 529 VALIGN="top" | |
| 530 ><A | |
| 531 HREF="index.html" | |
| 532 >Home</A | |
| 533 ></TD | |
| 534 ><TD | |
| 535 WIDTH="33%" | |
| 536 ALIGN="right" | |
| 537 VALIGN="top" | |
| 538 ><A | |
| 539 HREF="sdlpauseaudio.html" | |
| 540 >Next</A | |
| 541 ></TD | |
| 542 ></TR | |
| 543 ><TR | |
| 544 ><TD | |
| 545 WIDTH="33%" | |
| 546 ALIGN="left" | |
| 547 VALIGN="top" | |
| 548 >SDL_AudioSpec</TD | |
| 549 ><TD | |
| 550 WIDTH="34%" | |
| 551 ALIGN="center" | |
| 552 VALIGN="top" | |
| 553 ><A | |
| 554 HREF="audio.html" | |
| 555 >Up</A | |
| 556 ></TD | |
| 557 ><TD | |
| 558 WIDTH="33%" | |
| 559 ALIGN="right" | |
| 560 VALIGN="top" | |
| 561 >SDL_PauseAudio</TD | |
| 562 ></TR | |
| 563 ></TABLE | |
| 564 ></DIV | |
| 565 ></BODY | |
| 566 ></HTML | |
| 567 > |