|
0
|
1 .TH "SDL_OpenAudio" "3" "Mon 12 Mar 2001, 01:02" "SDL" "SDL API Reference"
|
|
|
2 .SH "NAME"
|
|
|
3 SDL_OpenAudio\- Opens the audio device with the desired parameters\&.
|
|
|
4 .SH "SYNOPSIS"
|
|
|
5 .PP
|
|
|
6 \fB#include "SDL\&.h"
|
|
|
7 .sp
|
|
|
8 \fBint \fBSDL_OpenAudio\fP\fR(\fBSDL_AudioSpec *desired, SDL_AudioSpec *obtained\fR);
|
|
|
9 .SH "DESCRIPTION"
|
|
|
10 .PP
|
|
|
11 This function opens the audio device with the \fBdesired\fR parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by \fBobtained\fR\&. If \fBobtained\fR 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\&.
|
|
|
12 .PP
|
|
|
13 To open the audio device a \fBdesired\fR \fI\fBSDL_AudioSpec\fR\fR must be created\&.
|
|
|
14 .PP
|
|
|
15 .nf
|
|
|
16 \f(CWSDL_AudioSpec *desired;
|
|
|
17 \&.
|
|
|
18 \&.
|
|
|
19 desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));\fR
|
|
|
20 .fi
|
|
|
21 .PP
|
|
|
22 You must then fill this structure with your desired audio specifications\&.
|
|
|
23 .IP "\fBdesired\fR->\fBfreq\fR" 10The desired audio frequency in samples-per-second\&.
|
|
|
24 .IP "\fBdesired\fR->\fBformat\fR" 10The desired audio format (see \fI\fBSDL_AudioSpec\fR\fR)
|
|
|
25 .IP "\fBdesired\fR->\fBsamples\fR" 10The 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
|
|
|
26 .IP "\fBdesired\fR->\fBcallback\fR" 10This 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 \fI\fBSDL_LockAudio\fP\fR and \fI\fBSDL_UnlockAudio\fP\fR in your code\&. The callback prototype is:
|
|
|
27 .PP
|
|
|
28 .nf
|
|
|
29 \f(CWvoid callback(void *userdata, Uint8 *stream, int len);\fR
|
|
|
30 .fi
|
|
|
31 .PP
|
|
|
32 \fBuserdata\fR is the pointer stored in \fBuserdata\fR field of the \fBSDL_AudioSpec\fR\&. \fBstream\fR is a pointer to the audio buffer you want to fill with information and \fBlen\fR is the length of the audio buffer in bytes\&.
|
|
|
33 .IP "\fBdesired\fR->\fBuserdata\fR" 10This pointer is passed as the first parameter to the \fBcallback\fP function\&.
|
|
|
34 .PP
|
|
|
35 \fBSDL_OpenAudio\fP reads these fields from the \fBdesired\fR \fBSDL_AudioSpec\fR structure pass to the function and attempts to find an audio configuration matching your \fBdesired\fR\&. As mentioned above, if the \fBobtained\fR parameter is \fBNULL\fP then SDL with convert from your \fBdesired\fR audio settings to the hardware settings as it plays\&.
|
|
|
36 .PP
|
|
|
37 If \fBobtained\fR is \fBNULL\fP then the \fBdesired\fR \fBSDL_AudioSpec\fR is your working specification, otherwise the \fBobtained\fR \fBSDL_AudioSpec\fR becomes the working specification and the \fBdesirec\fR specification can be deleted\&. The data in the working specification is used when building \fBSDL_AudioCVT\fR\&'s for converting loaded data to the hardware format\&.
|
|
|
38 .PP
|
|
|
39 \fBSDL_OpenAudio\fP calculates the \fBsize\fR and \fBsilence\fR fields for both the \fBdesired\fR and \fBobtained\fR specifications\&. The \fBsize\fR field stores the total size of the audio buffer in bytes, while the \fBsilence\fR stores the value used to represent silence in the audio buffer
|
|
|
40 .PP
|
|
|
41 The audio device starts out playing \fBsilence\fR when it\&'s opened, and should be enabled for playing by calling \fI\fBSDL_PauseAudio\fP(\fB0\fR)\fR when you are ready for your audio \fBcallback\fR function to be called\&. Since the audio driver may modify the requested \fBsize\fR of the audio buffer, you should allocate any local mixing buffers after you open the audio device\&.
|
|
|
42 .SH "EXAMPLES"
|
|
|
43 .PP
|
|
|
44 .nf
|
|
|
45 \f(CW/* Prototype of our callback function */
|
|
|
46 void my_audio_callback(void *userdata, Uint8 *stream, int len);
|
|
|
47
|
|
|
48 /* Open the audio device */
|
|
|
49 SDL_AudioSpec *desired, *obtained;
|
|
|
50 SDL_AudioSpec *hardware_spec;
|
|
|
51
|
|
|
52 /* Allocate a desired SDL_AudioSpec */
|
|
|
53 desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
|
|
|
54
|
|
|
55 /* Allocate space for the obtained SDL_AudioSpec */
|
|
|
56 obtained=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
|
|
|
57
|
|
|
58 /* 22050Hz - FM Radio quality */
|
|
|
59 desired->freq=22050;
|
|
|
60
|
|
|
61 /* 16-bit signed audio */
|
|
|
62 desired->format=AUDIO_S16LSB;
|
|
|
63
|
|
|
64 /* Large audio buffer reduces risk of dropouts but increases response time */
|
|
|
65 desired->samples=8192;
|
|
|
66
|
|
|
67 /* Our callback function */
|
|
|
68 desired->callback=my_audio_callback;
|
|
|
69
|
|
|
70 desired->userdata=NULL;
|
|
|
71
|
|
|
72 /* Open the audio device */
|
|
|
73 if ( SDL_OpenAudio(desired, obtained) < 0 ){
|
|
|
74 fprintf(stderr, "Couldn\&'t open audio: %s
|
|
|
75 ", SDL_GetError());
|
|
|
76 exit(-1);
|
|
|
77 }
|
|
|
78 /* desired spec is no longer needed */
|
|
|
79 free(desired);
|
|
|
80 hardware_spec=obtained;
|
|
|
81 \&.
|
|
|
82 \&.
|
|
|
83 /* Prepare callback for playing */
|
|
|
84 \&.
|
|
|
85 \&.
|
|
|
86 \&.
|
|
|
87 /* Start playing */
|
|
|
88 SDL_PauseAudio(0);\fR
|
|
|
89 .fi
|
|
|
90 .PP
|
|
|
91 .SH "SEE ALSO"
|
|
|
92 .PP
|
|
|
93 \fI\fBSDL_AudioSpec\fP\fR, \fI\fBSDL_LockAudio\fP\fR, \fI\fBSDL_UnlockAudio\fP\fR, \fI\fBSDL_PauseAudio\fP\fR
|
|
|
94 ...\" created by instant / docbook-to-man, Mon 12 Mar 2001, 01:02
|
