include/SDL_audio.h
branchSDL-1.3
changeset 1668 4da1ee79c9af
parent 1662 782fd950bd46
equal deleted inserted replaced
1667:1fddae038bc8 1668:4da1ee79c9af
   104 /* Function prototypes */
   104 /* Function prototypes */
   105 
   105 
   106 /* These functions return the list of built in video drivers, in the 
   106 /* These functions return the list of built in video drivers, in the 
   107  * order that they are normally initialized by default.
   107  * order that they are normally initialized by default.
   108  */
   108  */
   109 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers (void);
   109 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
   110 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver (int index);
   110 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
   111 
   111 
   112 /* These functions are used internally, and should not be used unless you
   112 /* These functions are used internally, and should not be used unless you
   113  * have a specific need to specify the audio driver you want to use.
   113  * have a specific need to specify the audio driver you want to use.
   114  * You should normally use SDL_Init() or SDL_InitSubSystem().
   114  * You should normally use SDL_Init() or SDL_InitSubSystem().
   115  */
   115  */
   116 extern DECLSPEC int SDLCALL SDL_AudioInit (const char *driver_name);
   116 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
   117 extern DECLSPEC void SDLCALL SDL_AudioQuit (void);
   117 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
   118 
   118 
   119 /* This function returns the name of the current audio driver, or NULL
   119 /* This function returns the name of the current audio driver, or NULL
   120  * if no driver has been initialized.
   120  * if no driver has been initialized.
   121  */
   121  */
   122 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver (void);
   122 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
   123 
   123 
   124 /*
   124 /*
   125  * This function opens the audio device with the desired parameters, and
   125  * This function opens the audio device with the desired parameters, and
   126  * returns 0 if successful, placing the actual hardware parameters in the
   126  * returns 0 if successful, placing the actual hardware parameters in the
   127  * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
   127  * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
   160  * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
   160  * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
   161  * for your audio callback function to be called.  Since the audio driver
   161  * for your audio callback function to be called.  Since the audio driver
   162  * may modify the requested size of the audio buffer, you should allocate
   162  * may modify the requested size of the audio buffer, you should allocate
   163  * any local mixing buffers after you open the audio device.
   163  * any local mixing buffers after you open the audio device.
   164  */
   164  */
   165 extern DECLSPEC int SDLCALL SDL_OpenAudio (SDL_AudioSpec * desired,
   165 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
   166                                            SDL_AudioSpec * obtained);
   166                                           SDL_AudioSpec * obtained);
   167 
   167 
   168 /*
   168 /*
   169  * Get the current audio state:
   169  * Get the current audio state:
   170  */
   170  */
   171 typedef enum
   171 typedef enum
   172 {
   172 {
   173     SDL_AUDIO_STOPPED = 0,
   173     SDL_AUDIO_STOPPED = 0,
   174     SDL_AUDIO_PLAYING,
   174     SDL_AUDIO_PLAYING,
   175     SDL_AUDIO_PAUSED
   175     SDL_AUDIO_PAUSED
   176 } SDL_audiostatus;
   176 } SDL_audiostatus;
   177 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus (void);
   177 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
   178 
   178 
   179 /*
   179 /*
   180  * This function pauses and unpauses the audio callback processing.
   180  * This function pauses and unpauses the audio callback processing.
   181  * It should be called with a parameter of 0 after opening the audio
   181  * It should be called with a parameter of 0 after opening the audio
   182  * device to start playing sound.  This is so you can safely initialize
   182  * device to start playing sound.  This is so you can safely initialize
   183  * data for your callback function after opening the audio device.
   183  * data for your callback function after opening the audio device.
   184  * Silence will be written to the audio device during the pause.
   184  * Silence will be written to the audio device during the pause.
   185  */
   185  */
   186 extern DECLSPEC void SDLCALL SDL_PauseAudio (int pause_on);
   186 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   187 
   187 
   188 /*
   188 /*
   189  * This function loads a WAVE from the data source, automatically freeing
   189  * This function loads a WAVE from the data source, automatically freeing
   190  * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
   190  * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
   191  * you could do:
   191  * you could do:
   200  *
   200  *
   201  * This function returns NULL and sets the SDL error message if the 
   201  * This function returns NULL and sets the SDL error message if the 
   202  * wave file cannot be opened, uses an unknown data format, or is 
   202  * wave file cannot be opened, uses an unknown data format, or is 
   203  * corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
   203  * corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
   204  */
   204  */
   205 extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW (SDL_RWops * src,
   205 extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
   206                                                        int freesrc,
   206                                                       int freesrc,
   207                                                        SDL_AudioSpec * spec,
   207                                                       SDL_AudioSpec * spec,
   208                                                        Uint8 ** audio_buf,
   208                                                       Uint8 ** audio_buf,
   209                                                        Uint32 * audio_len);
   209                                                       Uint32 * audio_len);
   210 
   210 
   211 /* Compatibility convenience function -- loads a WAV from a file */
   211 /* Compatibility convenience function -- loads a WAV from a file */
   212 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
   212 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
   213 	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
   213 	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
   214 
   214 
   215 /*
   215 /*
   216  * This function frees data previously allocated with SDL_LoadWAV_RW()
   216  * This function frees data previously allocated with SDL_LoadWAV_RW()
   217  */
   217  */
   218 extern DECLSPEC void SDLCALL SDL_FreeWAV (Uint8 * audio_buf);
   218 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
   219 
   219 
   220 /*
   220 /*
   221  * This function takes a source format and rate and a destination format
   221  * This function takes a source format and rate and a destination format
   222  * and rate, and initializes the 'cvt' structure with information needed
   222  * and rate, and initializes the 'cvt' structure with information needed
   223  * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   223  * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   224  * to the other.
   224  * to the other.
   225  * This function returns 0, or -1 if there was an error.
   225  * This function returns 0, or -1 if there was an error.
   226  */
   226  */
   227 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT (SDL_AudioCVT * cvt,
   227 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
   228                                                Uint16 src_format,
   228                                               Uint16 src_format,
   229                                                Uint8 src_channels,
   229                                               Uint8 src_channels,
   230                                                int src_rate,
   230                                               int src_rate,
   231                                                Uint16 dst_format,
   231                                               Uint16 dst_format,
   232                                                Uint8 dst_channels,
   232                                               Uint8 dst_channels,
   233                                                int dst_rate);
   233                                               int dst_rate);
   234 
   234 
   235 /* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
   235 /* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
   236  * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
   236  * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
   237  * audio data in the source format, this function will convert it in-place
   237  * audio data in the source format, this function will convert it in-place
   238  * to the desired format.
   238  * to the desired format.
   239  * The data conversion may expand the size of the audio data, so the buffer
   239  * The data conversion may expand the size of the audio data, so the buffer
   240  * cvt->buf should be allocated after the cvt structure is initialized by
   240  * cvt->buf should be allocated after the cvt structure is initialized by
   241  * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long.
   241  * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long.
   242  */
   242  */
   243 extern DECLSPEC int SDLCALL SDL_ConvertAudio (SDL_AudioCVT * cvt);
   243 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
   244 
   244 
   245 /*
   245 /*
   246  * This takes two audio buffers of the playing audio format and mixes
   246  * This takes two audio buffers of the playing audio format and mixes
   247  * them, performing addition, volume adjustment, and overflow clipping.
   247  * them, performing addition, volume adjustment, and overflow clipping.
   248  * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
   248  * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
   249  * for full audio volume.  Note this does not change hardware volume.
   249  * for full audio volume.  Note this does not change hardware volume.
   250  * This is provided for convenience -- you can mix your own audio data.
   250  * This is provided for convenience -- you can mix your own audio data.
   251  */
   251  */
   252 #define SDL_MIX_MAXVOLUME 128
   252 #define SDL_MIX_MAXVOLUME 128
   253 extern DECLSPEC void SDLCALL SDL_MixAudio (Uint8 * dst, const Uint8 * src,
   253 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
   254                                            Uint32 len, int volume);
   254                                           Uint32 len, int volume);
   255 
   255 
   256 /*
   256 /*
   257  * The lock manipulated by these functions protects the callback function.
   257  * The lock manipulated by these functions protects the callback function.
   258  * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   258  * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   259  * callback function is not running.  Do not call these from the callback
   259  * callback function is not running.  Do not call these from the callback
   260  * function or you will cause deadlock.
   260  * function or you will cause deadlock.
   261  */
   261  */
   262 extern DECLSPEC void SDLCALL SDL_LockAudio (void);
   262 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   263 extern DECLSPEC void SDLCALL SDL_UnlockAudio (void);
   263 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   264 
   264 
   265 /*
   265 /*
   266  * This function shuts down audio processing and closes the audio device.
   266  * This function shuts down audio processing and closes the audio device.
   267  */
   267  */
   268 extern DECLSPEC void SDLCALL SDL_CloseAudio (void);
   268 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
   269 
   269 
   270 
   270 
   271 /* Ends C function definitions when using C++ */
   271 /* Ends C function definitions when using C++ */
   272 #ifdef __cplusplus
   272 #ifdef __cplusplus
   273 /* *INDENT-OFF* */
   273 /* *INDENT-OFF* */