Mercurial > sdl-ios-xcode
annotate docs/html/sdlopenaudio.html @ 803:355632dca928
Updated SDL HTML documentation
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Tue, 10 Feb 2004 15:15:40 +0000 |
parents | e5bc29de3f0a |
children |
rev | line source |
---|---|
0 | 1 <HTML |
2 ><HEAD | |
3 ><TITLE | |
4 >SDL_OpenAudio</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_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 | |
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="sdlaudiospec.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="sdlpauseaudio.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="SDLOPENAUDIO" | |
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_OpenAudio</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="AEN6650" |
0 | 80 ></A |
81 ><H2 | |
82 >Name</H2 | |
83 >SDL_OpenAudio -- Opens the audio device with the desired parameters.</DIV | |
84 ><DIV | |
85 CLASS="REFSYNOPSISDIV" | |
86 ><A | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
87 NAME="AEN6653" |
0 | 88 ></A |
89 ><H2 | |
90 >Synopsis</H2 | |
91 ><DIV | |
92 CLASS="FUNCSYNOPSIS" | |
93 ><A | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
94 NAME="AEN6654" |
0 | 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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
118 NAME="AEN6660" |
0 | 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 . | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
163 desired = malloc(sizeof(SDL_AudioSpec));</PRE |
0 | 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 >-><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 >-><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 >-><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 >-><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 >-><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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
424 NAME="AEN6747" |
0 | 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 */ | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
438 desired = malloc(sizeof(SDL_AudioSpec)); |
0 | 439 |
440 /* Allocate space for the obtained SDL_AudioSpec */ | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
441 obtained = malloc(sizeof(SDL_AudioSpec)); |
0 | 442 |
443 /* 22050Hz - FM Radio quality */ | |
444 desired->freq=22050; | |
445 | |
446 /* 16-bit signed audio */ | |
447 desired->format=AUDIO_S16LSB; | |
448 | |
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
449 /* Mono */ |
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
450 desired->channels=0; |
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
451 |
0 | 452 /* Large audio buffer reduces risk of dropouts but increases response time */ |
453 desired->samples=8192; | |
454 | |
455 /* Our callback function */ | |
456 desired->callback=my_audio_callback; | |
457 | |
458 desired->userdata=NULL; | |
459 | |
460 /* Open the audio device */ | |
461 if ( SDL_OpenAudio(desired, obtained) < 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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
480 NAME="AEN6750" |
0 | 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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
519 SUMMARY="Footer navigation table" |
0 | 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" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
531 ACCESSKEY="P" |
0 | 532 >Prev</A |
533 ></TD | |
534 ><TD | |
535 WIDTH="34%" | |
536 ALIGN="center" | |
537 VALIGN="top" | |
538 ><A | |
539 HREF="index.html" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
540 ACCESSKEY="H" |
0 | 541 >Home</A |
542 ></TD | |
543 ><TD | |
544 WIDTH="33%" | |
545 ALIGN="right" | |
546 VALIGN="top" | |
547 ><A | |
548 HREF="sdlpauseaudio.html" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
549 ACCESSKEY="N" |
0 | 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" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
565 ACCESSKEY="U" |
0 | 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 > |