5131
clevermous
1
2
>
3
>
4
>SDL_OpenAudio
5
>
6
NAME="GENERATOR"
7
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
8
">
9
REL="HOME"
10
TITLE="SDL Library Documentation"
11
HREF="index.html">
12
REL="UP"
13
TITLE="Audio"
14
HREF="audio.html">
15
REL="PREVIOUS"
16
TITLE="SDL_AudioSpec"
17
HREF="sdlaudiospec.html">
18
REL="NEXT"
19
TITLE="SDL_PauseAudio"
20
HREF="sdlpauseaudio.html">
21
>
22
CLASS="REFENTRY"
23
BGCOLOR="#FFF8DC"
24
TEXT="#000000"
25
LINK="#0000ee"
26
VLINK="#551a8b"
27
ALINK="#ff0000"
28
>
29
CLASS="NAVHEADER"
30
>
31
WIDTH="100%"
32
BORDER="0"
33
CELLPADDING="0"
34
CELLSPACING="0"
35
>
36
>
37
COLSPAN="3"
38
ALIGN="center"
39
>SDL Library Documentation
40
>
41
>
42
>
43
WIDTH="10%"
44
ALIGN="left"
45
VALIGN="bottom"
46
>
47
HREF="sdlaudiospec.html"
48
>Prev
49
>
50
>
51
WIDTH="80%"
52
ALIGN="center"
53
VALIGN="bottom"
54
>
55
>
56
WIDTH="10%"
57
ALIGN="right"
58
VALIGN="bottom"
59
>
60
HREF="sdlpauseaudio.html"
61
>Next
62
>
63
>
64
>
65
>
66
ALIGN="LEFT"
67
WIDTH="100%">
68
>
69
>
70
NAME="SDLOPENAUDIO"
71
>SDL_OpenAudio
72
>
73
>
74
CLASS="REFNAMEDIV"
75
>
76
NAME="AEN6103"
77
>
78
>
79
>Name
80
>SDL_OpenAudio -- Opens the audio device with the desired parameters.
81
>
82
CLASS="REFSYNOPSISDIV"
83
>
84
NAME="AEN6106"
85
>
86
>
87
>Synopsis
88
>
89
CLASS="FUNCSYNOPSIS"
90
>
91
NAME="AEN6107"
92
>
93
>
94
>
95
>
96
CLASS="FUNCSYNOPSISINFO"
97
>#include "SDL.h"
98
>
99
>
100
>
101
CLASS="FUNCDEF"
102
>int
103
CLASS="FSFUNC"
104
>SDL_OpenAudio
105
>
106
>(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);
107
>
108
>
109
>
110
>
111
>
112
>
113
CLASS="REFSECT1"
114
>
115
NAME="AEN6113"
116
>
117
>
118
>Description
119
>
120
>This function opens the audio device with the
121
CLASS="PARAMETER"
122
>
123
>desired
124
>
125
> parameters, and
126
returns 0 if successful, placing the actual hardware parameters in the
127
structure pointed to by
128
CLASS="PARAMETER"
129
>
130
>obtained
131
>
132
>. If
133
CLASS="PARAMETER"
134
>
135
>obtained
136
>
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.
142
>
143
>To open the audio device a
144
CLASS="PARAMETER"
145
>
146
>desired
147
>
148
>
149
HREF="sdlaudiospec.html"
150
>
151
CLASS="STRUCTNAME"
152
>SDL_AudioSpec
153
>
154
> must be created.
155
156
CLASS="PROGRAMLISTING"
157
>SDL_AudioSpec *desired;
158
.
159
.
160
desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
161
>
162
You must then fill this structure with your desired audio specifications.
163
>
164
>
165
>
166
CLASS="VARIABLELIST"
167
>
168
>
169
>
170
CLASS="STRUCTNAME"
171
>desired
172
>->
173
CLASS="STRUCTFIELD"
174
>
175
>freq
176
>
177
>
178
>
179
>
180
>The desired audio frequency in samples-per-second.
181
>
182
>
183
>
184
CLASS="STRUCTNAME"
185
>desired
186
>->
187
CLASS="STRUCTFIELD"
188
>
189
>format
190
>
191
>
192
>
193
>
194
>The desired audio format (see
195
HREF="sdlaudiospec.html"
196
>
197
CLASS="STRUCTNAME"
198
>SDL_AudioSpec
199
>
200
>)
201
>
202
>
203
>
204
CLASS="STRUCTNAME"
205
>desired
206
>->
207
CLASS="STRUCTFIELD"
208
>
209
>samples
210
>
211
>
212
>
213
>
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
215
>
216
>
217
>
218
CLASS="STRUCTNAME"
219
>desired
220
>->
221
CLASS="STRUCTFIELD"
222
>
223
>callback
224
>
225
>
226
>
227
>
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
229
HREF="sdllockaudio.html"
230
>
231
CLASS="FUNCTION"
232
>SDL_LockAudio
233
>
234
> and
235
HREF="sdlunlockaudio.html"
236
>
237
CLASS="FUNCTION"
238
>SDL_UnlockAudio
239
>
240
> in your code. The callback prototype is:
241
242
CLASS="PROGRAMLISTING"
243
>void callback(void *userdata, Uint8 *stream, int len);
244
>
245
246
CLASS="PARAMETER"
247
>
248
>userdata
249
>
250
> is the pointer stored in
251
CLASS="STRUCTFIELD"
252
>
253
>userdata
254
>
255
> field of the
256
CLASS="STRUCTNAME"
257
>SDL_AudioSpec
258
>.
259
CLASS="PARAMETER"
260
>
261
>stream
262
>
263
> is a pointer to the audio buffer you want to fill with information and
264
CLASS="PARAMETER"
265
>
266
>len
267
>
268
> is the length of the audio buffer in bytes.
269
>
270
>
271
>
272
CLASS="STRUCTNAME"
273
>desired
274
>->
275
CLASS="STRUCTFIELD"
276
>
277
>userdata
278
>
279
>
280
>
281
>
282
>This pointer is passed as the first parameter to the
283
CLASS="FUNCTION"
284
>callback
285
> function.
286
>
287
>
288
>
289
>
290
>
291
CLASS="FUNCTION"
292
>SDL_OpenAudio
293
> reads these fields from the
294
CLASS="PARAMETER"
295
>
296
>desired
297
>
298
>
299
CLASS="STRUCTNAME"
300
>SDL_AudioSpec
301
> structure pass to the function and attempts to find an audio configuration matching your
302
CLASS="PARAMETER"
303
>
304
>desired
305
>
306
>. As mentioned above, if the
307
CLASS="PARAMETER"
308
>
309
>obtained
310
>
311
> parameter is
312
CLASS="LITERAL"
313
>NULL
314
> then SDL with convert from your
315
CLASS="PARAMETER"
316
>
317
>desired
318
>
319
> audio settings to the hardware settings as it plays.
320
>
321
>If
322
CLASS="PARAMETER"
323
>
324
>obtained
325
>
326
> is
327
CLASS="LITERAL"
328
>NULL
329
> then the
330
CLASS="PARAMETER"
331
>
332
>desired
333
>
334
>
335
CLASS="STRUCTNAME"
336
>SDL_AudioSpec
337
> is your working specification, otherwise the
338
CLASS="PARAMETER"
339
>
340
>obtained
341
>
342
>
343
CLASS="STRUCTNAME"
344
>SDL_AudioSpec
345
> becomes the working specification and the
346
CLASS="PARAMETER"
347
>
348
>desirec
349
>
350
> specification can be deleted. The data in the working specification is used when building
351
CLASS="STRUCTNAME"
352
>SDL_AudioCVT
353
>'s for converting loaded data to the hardware format.
354
>
355
>
356
CLASS="FUNCTION"
357
>SDL_OpenAudio
358
> calculates the
359
CLASS="STRUCTFIELD"
360
>
361
>size
362
>
363
> and
364
CLASS="STRUCTFIELD"
365
>
366
>silence
367
>
368
> fields for both the
369
CLASS="PARAMETER"
370
>
371
>desired
372
>
373
> and
374
CLASS="PARAMETER"
375
>
376
>obtained
377
>
378
> specifications. The
379
CLASS="STRUCTFIELD"
380
>
381
>size
382
>
383
> field stores the total size of the audio buffer in bytes, while the
384
CLASS="STRUCTFIELD"
385
>
386
>silence
387
>
388
> stores the value used to represent silence in the audio buffer
389
>
390
>The audio device starts out playing
391
CLASS="STRUCTFIELD"
392
>
393
>silence
394
>
395
> when it's opened, and should be enabled for playing by calling
396
HREF="sdlpauseaudio.html"
397
>
398
CLASS="FUNCTION"
399
>SDL_PauseAudio
400
>(
401
CLASS="PARAMETER"
402
>
403
>0
404
>
405
>)
406
> when you are ready for your audio
407
CLASS="STRUCTFIELD"
408
>
409
>callback
410
>
411
> function to be called. Since the audio driver may modify the requested
412
CLASS="STRUCTFIELD"
413
>
414
>size
415
>
416
> of the audio buffer, you should allocate any local mixing buffers after you open the audio device.
417
>
418
>
419
CLASS="REFSECT1"
420
>
421
NAME="AEN6200"
422
>
423
>
424
>Examples
425
>
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);
470
>
471
>
472
CLASS="REFSECT1"
473
>
474
NAME="AEN6203"
475
>
476
>
477
>See Also
478
>
479
>
480
HREF="sdlaudiospec.html"
481
>
482
CLASS="FUNCTION"
483
>SDL_AudioSpec
484
>
485
>,
486
487
HREF="sdllockaudio.html"
488
>
489
CLASS="FUNCTION"
490
>SDL_LockAudio
491
>
492
>,
493
494
HREF="sdlunlockaudio.html"
495
>
496
CLASS="FUNCTION"
497
>SDL_UnlockAudio
498
>
499
>,
500
501
HREF="sdlpauseaudio.html"
502
>
503
CLASS="FUNCTION"
504
>SDL_PauseAudio
505
>
506
>
507
>
508
>
509
CLASS="NAVFOOTER"
510
>
511
ALIGN="LEFT"
512
WIDTH="100%">
564
>
565
>
566
>
567
>