Mercurial > sdl-ios-xcode
annotate docs/man3/SDL_OpenAudio.3 @ 4083:a66ac59b3939 SDL-1.2
Added patch note for bug #461
| author | Sam Lantinga <slouken@libsdl.org> |
|---|---|
| date | Thu, 19 Jul 2007 08:12:45 +0000 |
| parents | e5bc29de3f0a |
| children | 546f7c1eb755 |
| rev | line source |
|---|---|
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
1 .TH "SDL_OpenAudio" "3" "Tue 11 Sep 2001, 22:58" "SDL" "SDL API Reference" |
| 0 | 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 | |
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
64 /* Mono */ |
|
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
65 desired->channels=0; |
|
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
66 |
| 0 | 67 /* Large audio buffer reduces risk of dropouts but increases response time */ |
| 68 desired->samples=8192; | |
| 69 | |
| 70 /* Our callback function */ | |
| 71 desired->callback=my_audio_callback; | |
| 72 | |
| 73 desired->userdata=NULL; | |
| 74 | |
| 75 /* Open the audio device */ | |
| 76 if ( SDL_OpenAudio(desired, obtained) < 0 ){ | |
| 77 fprintf(stderr, "Couldn\&'t open audio: %s | |
| 78 ", SDL_GetError()); | |
| 79 exit(-1); | |
| 80 } | |
| 81 /* desired spec is no longer needed */ | |
| 82 free(desired); | |
| 83 hardware_spec=obtained; | |
| 84 \&. | |
| 85 \&. | |
| 86 /* Prepare callback for playing */ | |
| 87 \&. | |
| 88 \&. | |
| 89 \&. | |
| 90 /* Start playing */ | |
| 91 SDL_PauseAudio(0);\fR | |
| 92 .fi | |
| 93 .PP | |
| 94 .SH "SEE ALSO" | |
| 95 .PP | |
| 96 \fI\fBSDL_AudioSpec\fP\fR, \fI\fBSDL_LockAudio\fP\fR, \fI\fBSDL_UnlockAudio\fP\fR, \fI\fBSDL_PauseAudio\fP\fR | |
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
97 ...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 22:58 |