annotate docs/man3/SDL_OpenAudio.3 @ 1856:21f13c787b46

Date: Mon, 22 May 2006 01:16:47 -0400 From: Mike Frysinger Subject: [SDL] [patch] fix sed expression in sdl-config just noticed that sdl-config uses '[a-z]' with sed in sdl-config without forcing the locale to C ... this could cause problems with locales where the letter 'z' is not the last letter in the alphabet
author Sam Lantinga <slouken@libsdl.org>
date Tue, 23 May 2006 15:07:56 +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
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
2 .SH "NAME"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
3 SDL_OpenAudio\- Opens the audio device with the desired parameters\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
4 .SH "SYNOPSIS"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
5 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
6 \fB#include "SDL\&.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
7 .sp
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
8 \fBint \fBSDL_OpenAudio\fP\fR(\fBSDL_AudioSpec *desired, SDL_AudioSpec *obtained\fR);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
9 .SH "DESCRIPTION"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
10 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
12 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
13 To open the audio device a \fBdesired\fR \fI\fBSDL_AudioSpec\fR\fR must be created\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
14 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
15 .nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
16 \f(CWSDL_AudioSpec *desired;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
17 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
18 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
19 desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
20 .fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
21 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
22 You must then fill this structure with your desired audio specifications\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
23 .IP "\fBdesired\fR->\fBfreq\fR" 10The desired audio frequency in samples-per-second\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
24 .IP "\fBdesired\fR->\fBformat\fR" 10The desired audio format (see \fI\fBSDL_AudioSpec\fR\fR)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
27 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
28 .nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
29 \f(CWvoid callback(void *userdata, Uint8 *stream, int len);\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
30 .fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
31 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
33 .IP "\fBdesired\fR->\fBuserdata\fR" 10This pointer is passed as the first parameter to the \fBcallback\fP function\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
34 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
36 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
38 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
40 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
42 .SH "EXAMPLES"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
43 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
44 .nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
45 \f(CW/* Prototype of our callback function */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
46 void my_audio_callback(void *userdata, Uint8 *stream, int len);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
47
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
48 /* Open the audio device */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
49 SDL_AudioSpec *desired, *obtained;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
50 SDL_AudioSpec *hardware_spec;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
51
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
52 /* Allocate a desired SDL_AudioSpec */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
53 desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
54
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
55 /* Allocate space for the obtained SDL_AudioSpec */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
56 obtained=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
57
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
58 /* 22050Hz - FM Radio quality */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
59 desired->freq=22050;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
60
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
61 /* 16-bit signed audio */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
62 desired->format=AUDIO_S16LSB;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
67 /* Large audio buffer reduces risk of dropouts but increases response time */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
68 desired->samples=8192;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
69
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
70 /* Our callback function */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
71 desired->callback=my_audio_callback;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
72
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
73 desired->userdata=NULL;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
74
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
75 /* Open the audio device */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
76 if ( SDL_OpenAudio(desired, obtained) < 0 ){
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
77 fprintf(stderr, "Couldn\&'t open audio: %s
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
78 ", SDL_GetError());
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
79 exit(-1);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
80 }
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
81 /* desired spec is no longer needed */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
82 free(desired);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
83 hardware_spec=obtained;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
84 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
85 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
86 /* Prepare callback for playing */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
87 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
88 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
89 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
90 /* Start playing */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
91 SDL_PauseAudio(0);\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
92 .fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
93 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
94 .SH "SEE ALSO"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
95 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
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