[sdl_omap.git] / docs / html / sdlopenaudio.html

<HTML
><HEAD
><TITLE
>SDL_OpenAudio</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="SDL Library Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Audio"
HREF="audio.html"><LINK
REL="PREVIOUS"
TITLE="SDL_AudioSpec"
HREF="sdlaudiospec.html"><LINK
REL="NEXT"
TITLE="SDL_PauseAudio"
HREF="sdlpauseaudio.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFF8DC"
TEXT="#000000"
LINK="#0000ee"
VLINK="#551a8b"
ALINK="#ff0000"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>SDL Library Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="sdlaudiospec.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlpauseaudio.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SDLOPENAUDIO"
></A
>SDL_OpenAudio</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6650"
></A
><H2
>Name</H2
>SDL_OpenAudio&nbsp;--&nbsp;Opens the audio device with the desired parameters.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN6653"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN6654"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include "SDL.h"</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int <B
CLASS="FSFUNC"
>SDL_OpenAudio</B
></CODE
>(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6660"
></A
><H2
>Description</H2
><P
>This function opens the audio device with the <TT
CLASS="PARAMETER"
><I
>desired</I
></TT
> parameters, and
returns 0 if successful, placing the actual hardware parameters in the
structure pointed to by <TT
CLASS="PARAMETER"
><I
>obtained</I
></TT
>.  If <TT
CLASS="PARAMETER"
><I
>obtained</I
></TT
> is NULL, the audio
data passed to the callback function will be guaranteed to be in the
requested format, and will be automatically converted to the hardware
audio format if necessary.  This function returns -1 if it failed 
to open the audio device, or couldn't set up the audio thread.</P
><P
>To open the audio device a <TT
CLASS="PARAMETER"
><I
>desired</I
></TT
> <A
HREF="sdlaudiospec.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_AudioSpec</SPAN
></A
> must be created.
<PRE
CLASS="PROGRAMLISTING"
>SDL_AudioSpec *desired;
.
.
desired = malloc(sizeof(SDL_AudioSpec));</PRE
>
You must then fill this structure with your desired audio specifications.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="STRUCTNAME"
>desired</SPAN
>-&#62;<TT
CLASS="STRUCTFIELD"
><I
>freq</I
></TT
></DT
><DD
><P
>The desired audio frequency in samples-per-second.</P
></DD
><DT
><SPAN
CLASS="STRUCTNAME"
>desired</SPAN
>-&#62;<TT
CLASS="STRUCTFIELD"
><I
>format</I
></TT
></DT
><DD
><P
>The desired audio format (see <A
HREF="sdlaudiospec.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_AudioSpec</SPAN
></A
>)</P
></DD
><DT
><SPAN
CLASS="STRUCTNAME"
>desired</SPAN
>-&#62;<TT
CLASS="STRUCTFIELD"
><I
>samples</I
></TT
></DT
><DD
><P
>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
></DD
><DT
><SPAN
CLASS="STRUCTNAME"
>desired</SPAN
>-&#62;<TT
CLASS="STRUCTFIELD"
><I
>callback</I
></TT
></DT
><DD
><P
>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
HREF="sdllockaudio.html"
><TT
CLASS="FUNCTION"
>SDL_LockAudio</TT
></A
> and <A
HREF="sdlunlockaudio.html"
><TT
CLASS="FUNCTION"
>SDL_UnlockAudio</TT
></A
> in your code. The callback prototype is:
<PRE
CLASS="PROGRAMLISTING"
>void callback(void *userdata, Uint8 *stream, int len);</PRE
>
<TT
CLASS="PARAMETER"
><I
>userdata</I
></TT
> is the pointer stored in <TT
CLASS="STRUCTFIELD"
><I
>userdata</I
></TT
> field of the <SPAN
CLASS="STRUCTNAME"
>SDL_AudioSpec</SPAN
>. <TT
CLASS="PARAMETER"
><I
>stream</I
></TT
> is a pointer to the audio buffer you want to fill with information and <TT
CLASS="PARAMETER"
><I
>len</I
></TT
> is the length of the audio buffer in bytes.</P
></DD
><DT
><SPAN
CLASS="STRUCTNAME"
>desired</SPAN
>-&#62;<TT
CLASS="STRUCTFIELD"
><I
>userdata</I
></TT
></DT
><DD
><P
>This pointer is passed as the first parameter to the <TT
CLASS="FUNCTION"
>callback</TT
> function.</P
></DD
></DL
></DIV
><P
><TT
CLASS="FUNCTION"
>SDL_OpenAudio</TT
> reads these fields from the <TT
CLASS="PARAMETER"
><I
>desired</I
></TT
> <SPAN
CLASS="STRUCTNAME"
>SDL_AudioSpec</SPAN
> structure pass to the function and attempts to find an audio configuration matching your <TT
CLASS="PARAMETER"
><I
>desired</I
></TT
>. As mentioned above, if the <TT
CLASS="PARAMETER"
><I
>obtained</I
></TT
> parameter is <TT
CLASS="LITERAL"
>NULL</TT
> then SDL with convert from your <TT
CLASS="PARAMETER"
><I
>desired</I
></TT
> audio settings to the hardware settings as it plays.</P
><P
>If <TT
CLASS="PARAMETER"
><I
>obtained</I
></TT
> is <TT
CLASS="LITERAL"
>NULL</TT
> then the <TT
CLASS="PARAMETER"
><I
>desired</I
></TT
> <SPAN
CLASS="STRUCTNAME"
>SDL_AudioSpec</SPAN
> is your working specification, otherwise the <TT
CLASS="PARAMETER"
><I
>obtained</I
></TT
> <SPAN
CLASS="STRUCTNAME"
>SDL_AudioSpec</SPAN
> becomes the working specification and the <TT
CLASS="PARAMETER"
><I
>desirec</I
></TT
> specification can be deleted. The data in the working specification is used when building <SPAN
CLASS="STRUCTNAME"
>SDL_AudioCVT</SPAN
>'s for converting loaded data to the hardware format.</P
><P
><TT
CLASS="FUNCTION"
>SDL_OpenAudio</TT
> calculates the <TT
CLASS="STRUCTFIELD"
><I
>size</I
></TT
> and <TT
CLASS="STRUCTFIELD"
><I
>silence</I
></TT
> fields for both the <TT
CLASS="PARAMETER"
><I
>desired</I
></TT
> and <TT
CLASS="PARAMETER"
><I
>obtained</I
></TT
> specifications. The <TT
CLASS="STRUCTFIELD"
><I
>size</I
></TT
> field stores the total size of the audio buffer in bytes, while the <TT
CLASS="STRUCTFIELD"
><I
>silence</I
></TT
> stores the value used to represent silence in the audio buffer</P
><P
>The audio device starts out playing <TT
CLASS="STRUCTFIELD"
><I
>silence</I
></TT
> when it's opened, and should be enabled for playing by calling <A
HREF="sdlpauseaudio.html"
><TT
CLASS="FUNCTION"
>SDL_PauseAudio</TT
>(<TT
CLASS="PARAMETER"
><I
>0</I
></TT
>)</A
> when you are ready for your audio <TT
CLASS="STRUCTFIELD"
><I
>callback</I
></TT
> function to be called.  Since the audio driver may modify the requested <TT
CLASS="STRUCTFIELD"
><I
>size</I
></TT
> of the audio buffer, you should allocate any local mixing buffers after you open the audio device.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6747"
></A
><H2
>Examples</H2
><PRE
CLASS="PROGRAMLISTING"
>/* Prototype of our callback function */
void my_audio_callback(void *userdata, Uint8 *stream, int len);

/* Open the audio device */
SDL_AudioSpec *desired, *obtained;
SDL_AudioSpec *hardware_spec;

/* Allocate a desired SDL_AudioSpec */
desired = malloc(sizeof(SDL_AudioSpec));

/* Allocate space for the obtained SDL_AudioSpec */
obtained = malloc(sizeof(SDL_AudioSpec));

/* 22050Hz - FM Radio quality */
desired-&#62;freq=22050;

/* 16-bit signed audio */
desired-&#62;format=AUDIO_S16LSB;

/* Mono */
desired-&#62;channels=0;

/* Large audio buffer reduces risk of dropouts but increases response time */
desired-&#62;samples=8192;

/* Our callback function */
desired-&#62;callback=my_audio_callback;

desired-&#62;userdata=NULL;

/* Open the audio device */
if ( SDL_OpenAudio(desired, obtained) &#60; 0 ){
  fprintf(stderr, "Couldn't open audio: %s\n", SDL_GetError());
  exit(-1);
}
/* desired spec is no longer needed */
free(desired);
hardware_spec=obtained;
.
.
/* Prepare callback for playing */
.
.
.
/* Start playing */
SDL_PauseAudio(0);</PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN6750"
></A
><H2
>See Also</H2
><P
><A
HREF="sdlaudiospec.html"
><TT
CLASS="FUNCTION"
>SDL_AudioSpec</TT
></A
>,
<A
HREF="sdllockaudio.html"
><TT
CLASS="FUNCTION"
>SDL_LockAudio</TT
></A
>,
<A
HREF="sdlunlockaudio.html"
><TT
CLASS="FUNCTION"
>SDL_UnlockAudio</TT
></A
>,
<A
HREF="sdlpauseaudio.html"
><TT
CLASS="FUNCTION"
>SDL_PauseAudio</TT
></A
></P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sdlaudiospec.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sdlpauseaudio.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_AudioSpec</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="audio.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SDL_PauseAudio</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	1	<HTML
	2	><HEAD
	3	><TITLE
	4	>SDL_OpenAudio</TITLE
	5	><META
	6	NAME="GENERATOR"
	7	CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
	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	SUMMARY="Header navigation table"
	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"
	49	ACCESSKEY="P"
	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"
	63	ACCESSKEY="N"
	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"
74	></A
75	>SDL_OpenAudio</H1
76	><DIV
77	CLASS="REFNAMEDIV"
78	><A
79	NAME="AEN6650"
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
87	NAME="AEN6653"
88	></A
89	><H2
90	>Synopsis</H2
91	><DIV
92	CLASS="FUNCSYNOPSIS"
93	><A
94	NAME="AEN6654"
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
118	NAME="AEN6660"
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	.
163	desired = malloc(sizeof(SDL_AudioSpec));</PRE
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
424	NAME="AEN6747"
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 */
438	desired = malloc(sizeof(SDL_AudioSpec));
439
440	/* Allocate space for the obtained SDL_AudioSpec */
441	obtained = malloc(sizeof(SDL_AudioSpec));
442
443	/* 22050Hz - FM Radio quality */
444	desired->freq=22050;
445
446	/* 16-bit signed audio */
447	desired->format=AUDIO_S16LSB;
448
449	/* Mono */
450	desired->channels=0;
451
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
480	NAME="AEN6750"
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
519	SUMMARY="Footer navigation table"
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"
531	ACCESSKEY="P"
532	>Prev</A
533	></TD
534	><TD
535	WIDTH="34%"
536	ALIGN="center"
537	VALIGN="top"
538	><A
539	HREF="index.html"
540	ACCESSKEY="H"
541	>Home</A
542	></TD
543	><TD
544	WIDTH="33%"
545	ALIGN="right"
546	VALIGN="top"
547	><A
548	HREF="sdlpauseaudio.html"
549	ACCESSKEY="N"
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"
565	ACCESSKEY="U"
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	>