Mercurial > sdl-ios-xcode
annotate docs/html/sdlaudiocvt.html @ 4003:ea059917233c SDL-1.2
Added notes about audio callback behaviour.
| author | Ryan C. Gordon <icculus@icculus.org> |
|---|---|
| date | Thu, 05 Jul 2007 02:53:40 +0000 |
| parents | 355632dca928 |
| children |
| rev | line source |
|---|---|
| 0 | 1 <HTML |
| 2 ><HEAD | |
| 3 ><TITLE | |
| 4 >SDL_AudioCVT</TITLE | |
| 5 ><META | |
| 6 NAME="GENERATOR" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ |
| 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_FreeWAV" | |
| 17 HREF="sdlfreewav.html"><LINK | |
| 18 REL="NEXT" | |
| 19 TITLE="SDL_BuildAudioCVT" | |
| 20 HREF="sdlbuildaudiocvt.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 | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
31 SUMMARY="Header navigation table" |
| 0 | 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="sdlfreewav.html" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
49 ACCESSKEY="P" |
| 0 | 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="sdlbuildaudiocvt.html" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
63 ACCESSKEY="N" |
| 0 | 64 >Next</A |
| 65 ></TD | |
| 66 ></TR | |
| 67 ></TABLE | |
| 68 ><HR | |
| 69 ALIGN="LEFT" | |
| 70 WIDTH="100%"></DIV | |
| 71 ><H1 | |
| 72 ><A | |
| 73 NAME="SDLAUDIOCVT" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
74 ></A |
|
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
75 >SDL_AudioCVT</H1 |
| 0 | 76 ><DIV |
| 77 CLASS="REFNAMEDIV" | |
| 78 ><A | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
79 NAME="AEN6884" |
| 0 | 80 ></A |
| 81 ><H2 | |
| 82 >Name</H2 | |
| 83 >SDL_AudioCVT -- Audio Conversion Structure</DIV | |
| 84 ><DIV | |
| 85 CLASS="REFSECT1" | |
| 86 ><A | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
87 NAME="AEN6887" |
| 0 | 88 ></A |
| 89 ><H2 | |
| 90 >Structure Definition</H2 | |
| 91 ><PRE | |
| 92 CLASS="PROGRAMLISTING" | |
| 93 >typedef struct{ | |
| 94 int needed; | |
| 95 Uint16 src_format; | |
| 96 Uint16 dest_format; | |
| 97 double rate_incr; | |
| 98 Uint8 *buf; | |
| 99 int len; | |
| 100 int len_cvt; | |
| 101 int len_mult; | |
| 102 double len_ratio; | |
| 103 void (*filters[10])(struct SDL_AudioCVT *cvt, Uint16 format); | |
| 104 int filter_index; | |
| 105 } SDL_AudioCVT;</PRE | |
| 106 ></DIV | |
| 107 ><DIV | |
| 108 CLASS="REFSECT1" | |
| 109 ><A | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
110 NAME="AEN6890" |
| 0 | 111 ></A |
| 112 ><H2 | |
| 113 >Structure Data</H2 | |
| 114 ><DIV | |
| 115 CLASS="INFORMALTABLE" | |
| 116 ><A | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
117 NAME="AEN6892" |
| 0 | 118 ></A |
| 119 ><P | |
| 120 ></P | |
| 121 ><TABLE | |
| 122 BORDER="0" | |
| 123 CLASS="CALSTABLE" | |
| 124 ><TBODY | |
| 125 ><TR | |
| 126 ><TD | |
| 127 ALIGN="LEFT" | |
| 128 VALIGN="TOP" | |
| 129 ><TT | |
| 130 CLASS="STRUCTFIELD" | |
| 131 ><I | |
| 132 >needed</I | |
| 133 ></TT | |
| 134 ></TD | |
| 135 ><TD | |
| 136 ALIGN="LEFT" | |
| 137 VALIGN="TOP" | |
| 138 >Set to one if the conversion is possible</TD | |
| 139 ></TR | |
| 140 ><TR | |
| 141 ><TD | |
| 142 ALIGN="LEFT" | |
| 143 VALIGN="TOP" | |
| 144 ><TT | |
| 145 CLASS="STRUCTFIELD" | |
| 146 ><I | |
| 147 >src_format</I | |
| 148 ></TT | |
| 149 ></TD | |
| 150 ><TD | |
| 151 ALIGN="LEFT" | |
| 152 VALIGN="TOP" | |
| 153 >Audio format of the source</TD | |
| 154 ></TR | |
| 155 ><TR | |
| 156 ><TD | |
| 157 ALIGN="LEFT" | |
| 158 VALIGN="TOP" | |
| 159 ><TT | |
| 160 CLASS="STRUCTFIELD" | |
| 161 ><I | |
| 162 >dest_format</I | |
| 163 ></TT | |
| 164 ></TD | |
| 165 ><TD | |
| 166 ALIGN="LEFT" | |
| 167 VALIGN="TOP" | |
| 168 >Audio format of the destination</TD | |
| 169 ></TR | |
| 170 ><TR | |
| 171 ><TD | |
| 172 ALIGN="LEFT" | |
| 173 VALIGN="TOP" | |
| 174 ><TT | |
| 175 CLASS="STRUCTFIELD" | |
| 176 ><I | |
| 177 >rate_incr</I | |
| 178 ></TT | |
| 179 ></TD | |
| 180 ><TD | |
| 181 ALIGN="LEFT" | |
| 182 VALIGN="TOP" | |
| 183 >Rate conversion increment</TD | |
| 184 ></TR | |
| 185 ><TR | |
| 186 ><TD | |
| 187 ALIGN="LEFT" | |
| 188 VALIGN="TOP" | |
| 189 ><TT | |
| 190 CLASS="STRUCTFIELD" | |
| 191 ><I | |
| 192 >buf</I | |
| 193 ></TT | |
| 194 ></TD | |
| 195 ><TD | |
| 196 ALIGN="LEFT" | |
| 197 VALIGN="TOP" | |
| 198 >Audio buffer</TD | |
| 199 ></TR | |
| 200 ><TR | |
| 201 ><TD | |
| 202 ALIGN="LEFT" | |
| 203 VALIGN="TOP" | |
| 204 ><TT | |
| 205 CLASS="STRUCTFIELD" | |
| 206 ><I | |
| 207 >len</I | |
| 208 ></TT | |
| 209 ></TD | |
| 210 ><TD | |
| 211 ALIGN="LEFT" | |
| 212 VALIGN="TOP" | |
| 213 >Length of the original audio buffer in bytes</TD | |
| 214 ></TR | |
| 215 ><TR | |
| 216 ><TD | |
| 217 ALIGN="LEFT" | |
| 218 VALIGN="TOP" | |
| 219 ><TT | |
| 220 CLASS="STRUCTFIELD" | |
| 221 ><I | |
| 222 >len_cvt</I | |
| 223 ></TT | |
| 224 ></TD | |
| 225 ><TD | |
| 226 ALIGN="LEFT" | |
| 227 VALIGN="TOP" | |
| 228 >Length of converted audio buffer in bytes (calculated)</TD | |
| 229 ></TR | |
| 230 ><TR | |
| 231 ><TD | |
| 232 ALIGN="LEFT" | |
| 233 VALIGN="TOP" | |
| 234 ><TT | |
| 235 CLASS="STRUCTFIELD" | |
| 236 ><I | |
| 237 >len_mult</I | |
| 238 ></TT | |
| 239 ></TD | |
| 240 ><TD | |
| 241 ALIGN="LEFT" | |
| 242 VALIGN="TOP" | |
| 243 ><TT | |
| 244 CLASS="STRUCTFIELD" | |
| 245 ><I | |
| 246 >buf</I | |
| 247 ></TT | |
| 248 > must be <TT | |
| 249 CLASS="STRUCTFIELD" | |
| 250 ><I | |
| 251 >len</I | |
| 252 ></TT | |
| 253 >*<TT | |
| 254 CLASS="STRUCTFIELD" | |
| 255 ><I | |
| 256 >len_mult</I | |
| 257 ></TT | |
| 258 > bytes in size(calculated)</TD | |
| 259 ></TR | |
| 260 ><TR | |
| 261 ><TD | |
| 262 ALIGN="LEFT" | |
| 263 VALIGN="TOP" | |
| 264 ><TT | |
| 265 CLASS="STRUCTFIELD" | |
| 266 ><I | |
| 267 >len_ratio</I | |
| 268 ></TT | |
| 269 ></TD | |
| 270 ><TD | |
| 271 ALIGN="LEFT" | |
| 272 VALIGN="TOP" | |
| 273 >Final audio size is <TT | |
| 274 CLASS="STRUCTFIELD" | |
| 275 ><I | |
| 276 >len</I | |
| 277 ></TT | |
| 278 >*<TT | |
| 279 CLASS="STRUCTFIELD" | |
| 280 ><I | |
| 281 >len_ratio</I | |
| 282 ></TT | |
| 283 ></TD | |
| 284 ></TR | |
| 285 ><TR | |
| 286 ><TD | |
| 287 ALIGN="LEFT" | |
| 288 VALIGN="TOP" | |
| 289 ><TT | |
| 290 CLASS="STRUCTFIELD" | |
| 291 ><I | |
| 292 >filters[10](..)</I | |
| 293 ></TT | |
| 294 ></TD | |
| 295 ><TD | |
| 296 ALIGN="LEFT" | |
| 297 VALIGN="TOP" | |
| 298 >Pointers to functions needed for this conversion</TD | |
| 299 ></TR | |
| 300 ><TR | |
| 301 ><TD | |
| 302 ALIGN="LEFT" | |
| 303 VALIGN="TOP" | |
| 304 ><TT | |
| 305 CLASS="STRUCTFIELD" | |
| 306 ><I | |
| 307 >filter_index</I | |
| 308 ></TT | |
| 309 ></TD | |
| 310 ><TD | |
| 311 ALIGN="LEFT" | |
| 312 VALIGN="TOP" | |
| 313 >Current conversion function</TD | |
| 314 ></TR | |
| 315 ></TBODY | |
| 316 ></TABLE | |
| 317 ><P | |
| 318 ></P | |
| 319 ></DIV | |
| 320 ></DIV | |
| 321 ><DIV | |
| 322 CLASS="REFSECT1" | |
| 323 ><A | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
324 NAME="AEN6944" |
| 0 | 325 ></A |
| 326 ><H2 | |
| 327 >Description</H2 | |
| 328 ><P | |
| 329 >The <SPAN | |
| 330 CLASS="STRUCTNAME" | |
| 331 >SDL_AudioCVT</SPAN | |
| 332 > is used to convert audio data between different formats. A <SPAN | |
| 333 CLASS="STRUCTNAME" | |
| 334 >SDL_AudioCVT</SPAN | |
| 335 > structure is created with the <A | |
| 336 HREF="sdlbuildaudiocvt.html" | |
| 337 ><TT | |
| 338 CLASS="FUNCTION" | |
| 339 >SDL_BuildAudioCVT</TT | |
| 340 ></A | |
| 341 > function, while the actual conversion is done by the <A | |
| 342 HREF="sdlconvertaudio.html" | |
| 343 ><TT | |
| 344 CLASS="FUNCTION" | |
| 345 >SDL_ConvertAudio</TT | |
| 346 ></A | |
| 347 > function.</P | |
| 348 ><P | |
| 349 >Many of the fields in the <SPAN | |
| 350 CLASS="STRUCTNAME" | |
| 351 >SDL_AudioCVT</SPAN | |
| 352 > structure should be considered private and their function will not be discussed here.</P | |
| 353 ><P | |
| 354 ></P | |
| 355 ><DIV | |
| 356 CLASS="VARIABLELIST" | |
| 357 ><DL | |
| 358 ><DT | |
| 359 ><SPAN | |
| 360 CLASS="TYPE" | |
| 361 >Uint8 *</SPAN | |
| 362 ><TT | |
| 363 CLASS="STRUCTFIELD" | |
| 364 ><I | |
| 365 >buf</I | |
| 366 ></TT | |
| 367 ></DT | |
| 368 ><DD | |
| 369 ><P | |
| 370 >This points to the audio data that will be used in the conversion. It is both the source and the destination, which means the converted audio data overwrites the original data. It also means that the converted data may be larger than the original data (if you were converting from 8-bit to 16-bit, for instance), so you must ensure <TT | |
| 371 CLASS="STRUCTFIELD" | |
| 372 ><I | |
| 373 >buf</I | |
| 374 ></TT | |
| 375 > is large enough. See below.</P | |
| 376 ></DD | |
| 377 ><DT | |
| 378 ><SPAN | |
| 379 CLASS="TYPE" | |
| 380 >int</SPAN | |
| 381 > <TT | |
| 382 CLASS="STRUCTFIELD" | |
| 383 ><I | |
| 384 >len</I | |
| 385 ></TT | |
| 386 ></DT | |
| 387 ><DD | |
| 388 ><P | |
| 389 >This is the length of the original audio data in bytes.</P | |
| 390 ></DD | |
| 391 ><DT | |
| 392 ><SPAN | |
| 393 CLASS="TYPE" | |
| 394 >int</SPAN | |
| 395 > <TT | |
| 396 CLASS="STRUCTFIELD" | |
| 397 ><I | |
| 398 >len_mult</I | |
| 399 ></TT | |
| 400 ></DT | |
| 401 ><DD | |
| 402 ><P | |
| 403 >As explained above, the audio buffer needs to be big enough to store the converted data, which may be bigger than the original audio data. The length of <TT | |
| 404 CLASS="STRUCTFIELD" | |
| 405 ><I | |
| 406 >buf</I | |
| 407 ></TT | |
| 408 > should be <TT | |
| 409 CLASS="STRUCTFIELD" | |
| 410 ><I | |
| 411 >len</I | |
| 412 ></TT | |
| 413 >*<TT | |
| 414 CLASS="STRUCTFIELD" | |
| 415 ><I | |
| 416 >len_mult</I | |
| 417 ></TT | |
| 418 >.</P | |
| 419 ></DD | |
| 420 ><DT | |
| 421 ><SPAN | |
| 422 CLASS="TYPE" | |
| 423 >double</SPAN | |
| 424 > <TT | |
| 425 CLASS="STRUCTFIELD" | |
| 426 ><I | |
| 427 >len_ratio</I | |
| 428 ></TT | |
| 429 ></DT | |
| 430 ><DD | |
| 431 ><P | |
| 432 >When you have finished converting your audio data, you need to know how much of your audio buffer is valid. <TT | |
| 433 CLASS="STRUCTFIELD" | |
| 434 ><I | |
| 435 >len</I | |
| 436 ></TT | |
| 437 >*<TT | |
| 438 CLASS="STRUCTFIELD" | |
| 439 ><I | |
| 440 >len_ratio</I | |
| 441 ></TT | |
| 442 > is the size of the converted audio data in bytes. This is very similar to <TT | |
| 443 CLASS="STRUCTFIELD" | |
| 444 ><I | |
| 445 >len_mult</I | |
| 446 ></TT | |
| 447 >, however when the convert audio data is shorter than the original <TT | |
| 448 CLASS="STRUCTFIELD" | |
| 449 ><I | |
| 450 >len_mult</I | |
| 451 ></TT | |
| 452 > would be 1. <TT | |
| 453 CLASS="STRUCTFIELD" | |
| 454 ><I | |
| 455 >len_ratio</I | |
| 456 ></TT | |
| 457 >, on the other hand, would be a fractional number between 0 and 1.</P | |
| 458 ></DD | |
| 459 ></DL | |
| 460 ></DIV | |
| 461 ></DIV | |
| 462 ><DIV | |
| 463 CLASS="REFSECT1" | |
| 464 ><A | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
465 NAME="AEN6989" |
| 0 | 466 ></A |
| 467 ><H2 | |
| 468 >See Also</H2 | |
| 469 ><P | |
| 470 ><A | |
| 471 HREF="sdlbuildaudiocvt.html" | |
| 472 ><TT | |
| 473 CLASS="FUNCTION" | |
| 474 >SDL_BuildAudioCVT</TT | |
| 475 ></A | |
| 476 >, | |
| 477 <A | |
| 478 HREF="sdlconvertaudio.html" | |
| 479 ><TT | |
| 480 CLASS="FUNCTION" | |
| 481 >SDL_ConvertAudio</TT | |
| 482 ></A | |
| 483 >, | |
| 484 <A | |
| 485 HREF="sdlaudiospec.html" | |
| 486 ><SPAN | |
| 487 CLASS="STRUCTNAME" | |
| 488 >SDL_AudioSpec</SPAN | |
| 489 ></A | |
| 490 ></P | |
| 491 ></DIV | |
| 492 ><DIV | |
| 493 CLASS="NAVFOOTER" | |
| 494 ><HR | |
| 495 ALIGN="LEFT" | |
| 496 WIDTH="100%"><TABLE | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
497 SUMMARY="Footer navigation table" |
| 0 | 498 WIDTH="100%" |
| 499 BORDER="0" | |
| 500 CELLPADDING="0" | |
| 501 CELLSPACING="0" | |
| 502 ><TR | |
| 503 ><TD | |
| 504 WIDTH="33%" | |
| 505 ALIGN="left" | |
| 506 VALIGN="top" | |
| 507 ><A | |
| 508 HREF="sdlfreewav.html" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
509 ACCESSKEY="P" |
| 0 | 510 >Prev</A |
| 511 ></TD | |
| 512 ><TD | |
| 513 WIDTH="34%" | |
| 514 ALIGN="center" | |
| 515 VALIGN="top" | |
| 516 ><A | |
| 517 HREF="index.html" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
518 ACCESSKEY="H" |
| 0 | 519 >Home</A |
| 520 ></TD | |
| 521 ><TD | |
| 522 WIDTH="33%" | |
| 523 ALIGN="right" | |
| 524 VALIGN="top" | |
| 525 ><A | |
| 526 HREF="sdlbuildaudiocvt.html" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
527 ACCESSKEY="N" |
| 0 | 528 >Next</A |
| 529 ></TD | |
| 530 ></TR | |
| 531 ><TR | |
| 532 ><TD | |
| 533 WIDTH="33%" | |
| 534 ALIGN="left" | |
| 535 VALIGN="top" | |
| 536 >SDL_FreeWAV</TD | |
| 537 ><TD | |
| 538 WIDTH="34%" | |
| 539 ALIGN="center" | |
| 540 VALIGN="top" | |
| 541 ><A | |
| 542 HREF="audio.html" | |
|
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
543 ACCESSKEY="U" |
| 0 | 544 >Up</A |
| 545 ></TD | |
| 546 ><TD | |
| 547 WIDTH="33%" | |
| 548 ALIGN="right" | |
| 549 VALIGN="top" | |
| 550 >SDL_BuildAudioCVT</TD | |
| 551 ></TR | |
| 552 ></TABLE | |
| 553 ></DIV | |
| 554 ></BODY | |
| 555 ></HTML | |
| 556 > |