Mercurial > sdl-ios-xcode

comparison docs/html/sdlopenaudio.html @ 0:74212992fb08

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial revision
author Sam Lantinga <slouken@lokigames.com>
date Thu, 26 Apr 2001 16:45:43 +0000
parents
children 55f1f1b3e27d
comparison
equal deleted inserted replaced
-1:000000000000 0:74212992fb08
1 <HTML
2 ><HEAD
3 ><TITLE
4 >SDL_OpenAudio</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.61
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
76 NAME="AEN6028"
77 ></A
78 ><H2
79 >Name</H2
80 >SDL_OpenAudio&nbsp;--&nbsp;Opens the audio device with the desired parameters.</DIV
81 ><DIV
82 CLASS="REFSYNOPSISDIV"
83 ><A
84 NAME="AEN6031"
85 ></A
86 ><H2
87 >Synopsis</H2
88 ><DIV
89 CLASS="FUNCSYNOPSIS"
90 ><A
91 NAME="AEN6032"
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
115 NAME="AEN6038"
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 >-&#62;<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 >-&#62;<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 >-&#62;<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 >-&#62;<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 >-&#62;<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
421 NAME="AEN6125"
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-&#62;freq=22050;
442
443 /* 16-bit signed audio */
444 desired-&#62;format=AUDIO_S16LSB;
445
446 /* Large audio buffer reduces risk of dropouts but increases response time */
447 desired-&#62;samples=8192;
448
449 /* Our callback function */
450 desired-&#62;callback=my_audio_callback;
451
452 desired-&#62;userdata=NULL;
453
454 /* Open the audio device */
455 if ( SDL_OpenAudio(desired, obtained) &#60; 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
474 NAME="AEN6128"
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 >