docs/man3/SDL_OpenAudio.3
author Aaron Wishnick <schnarf@gmail.com>
Wed, 18 Jun 2008 04:51:10 +0000
branchgsoc2008_audio_resampling
changeset 2655 b8e736c8a5a8
parent 2283 546f7c1eb755
child 4311 1238da4a7112
permissions -rw-r--r--
Added beginnings of resampling code.
slouken@181
     1
.TH "SDL_OpenAudio" "3" "Tue 11 Sep 2001, 22:58" "SDL" "SDL API Reference" 
slouken@0
     2
.SH "NAME"
slouken@2283
     3
SDL_OpenAudio \- Opens the audio device with the desired parameters\&.
slouken@0
     4
.SH "SYNOPSIS"
slouken@0
     5
.PP
slouken@0
     6
\fB#include "SDL\&.h"
slouken@0
     7
.sp
slouken@0
     8
\fBint \fBSDL_OpenAudio\fP\fR(\fBSDL_AudioSpec *desired, SDL_AudioSpec *obtained\fR);
slouken@0
     9
.SH "DESCRIPTION"
slouken@0
    10
.PP
slouken@0
    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\&.
slouken@0
    12
.PP
slouken@0
    13
To open the audio device a \fBdesired\fR \fI\fBSDL_AudioSpec\fR\fR must be created\&. 
slouken@0
    14
.PP
slouken@0
    15
.nf
slouken@0
    16
\f(CWSDL_AudioSpec *desired;
slouken@0
    17
\&.
slouken@0
    18
\&.
slouken@0
    19
desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));\fR
slouken@0
    20
.fi
slouken@0
    21
.PP
slouken@0
    22
 You must then fill this structure with your desired audio specifications\&.
slouken@0
    23
.IP "\fBdesired\fR->\fBfreq\fR" 10The desired audio frequency in samples-per-second\&.
slouken@0
    24
.IP "\fBdesired\fR->\fBformat\fR" 10The desired audio format (see \fI\fBSDL_AudioSpec\fR\fR)
slouken@0
    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
slouken@0
    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: 
slouken@0
    27
.PP
slouken@0
    28
.nf
slouken@0
    29
\f(CWvoid callback(void *userdata, Uint8 *stream, int len);\fR
slouken@0
    30
.fi
slouken@0
    31
.PP
slouken@0
    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\&.
slouken@0
    33
.IP "\fBdesired\fR->\fBuserdata\fR" 10This pointer is passed as the first parameter to the \fBcallback\fP function\&.
slouken@0
    34
.PP
slouken@0
    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\&.
slouken@0
    36
.PP
slouken@0
    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\&.
slouken@0
    38
.PP
slouken@0
    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
slouken@0
    40
.PP
slouken@0
    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\&.
slouken@0
    42
.SH "EXAMPLES"
slouken@0
    43
.PP
slouken@0
    44
.nf
slouken@0
    45
\f(CW/* Prototype of our callback function */
slouken@0
    46
void my_audio_callback(void *userdata, Uint8 *stream, int len);
slouken@0
    47
slouken@0
    48
/* Open the audio device */
slouken@0
    49
SDL_AudioSpec *desired, *obtained;
slouken@0
    50
SDL_AudioSpec *hardware_spec;
slouken@0
    51
slouken@0
    52
/* Allocate a desired SDL_AudioSpec */
slouken@0
    53
desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
slouken@0
    54
slouken@0
    55
/* Allocate space for the obtained SDL_AudioSpec */
slouken@0
    56
obtained=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
slouken@0
    57
slouken@0
    58
/* 22050Hz - FM Radio quality */
slouken@0
    59
desired->freq=22050;
slouken@0
    60
slouken@0
    61
/* 16-bit signed audio */
slouken@0
    62
desired->format=AUDIO_S16LSB;
slouken@0
    63
slouken@181
    64
/* Mono */
slouken@181
    65
desired->channels=0;
slouken@181
    66
slouken@0
    67
/* Large audio buffer reduces risk of dropouts but increases response time */
slouken@0
    68
desired->samples=8192;
slouken@0
    69
slouken@0
    70
/* Our callback function */
slouken@0
    71
desired->callback=my_audio_callback;
slouken@0
    72
slouken@0
    73
desired->userdata=NULL;
slouken@0
    74
slouken@0
    75
/* Open the audio device */
slouken@0
    76
if ( SDL_OpenAudio(desired, obtained) < 0 ){
slouken@0
    77
  fprintf(stderr, "Couldn\&'t open audio: %s
slouken@0
    78
", SDL_GetError());
slouken@0
    79
  exit(-1);
slouken@0
    80
}
slouken@0
    81
/* desired spec is no longer needed */
slouken@0
    82
free(desired);
slouken@0
    83
hardware_spec=obtained;
slouken@0
    84
\&.
slouken@0
    85
\&.
slouken@0
    86
/* Prepare callback for playing */
slouken@0
    87
\&.
slouken@0
    88
\&.
slouken@0
    89
\&.
slouken@0
    90
/* Start playing */
slouken@0
    91
SDL_PauseAudio(0);\fR
slouken@0
    92
.fi
slouken@0
    93
.PP
slouken@0
    94
.SH "SEE ALSO"
slouken@0
    95
.PP
slouken@0
    96
\fI\fBSDL_AudioSpec\fP\fR, \fI\fBSDL_LockAudio\fP\fR, \fI\fBSDL_UnlockAudio\fP\fR, \fI\fBSDL_PauseAudio\fP\fR
slouken@181
    97
...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 22:58