include/SDL_audio.h
branchSDL-1.2
changeset 4217 4c4113c2162c
parent 4159 a1b03ba2fcd0
child 6137 4720145f848b
     1.1 --- a/include/SDL_audio.h	Mon Sep 21 09:27:08 2009 +0000
     1.2 +++ b/include/SDL_audio.h	Mon Sep 21 09:38:10 2009 +0000
     1.3 @@ -20,7 +20,10 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* Access to the raw audio mixing buffer for the SDL library */
     1.8 +/**
     1.9 + *  @file SDL_audio.h
    1.10 + *  Access to the raw audio mixing buffer for the SDL library
    1.11 + */
    1.12  
    1.13  #ifndef _SDL_audio_h
    1.14  #define _SDL_audio_h
    1.15 @@ -38,89 +41,11 @@
    1.16  extern "C" {
    1.17  #endif
    1.18  
    1.19 -/* The calculated values in this structure are calculated by SDL_OpenAudio() */
    1.20 -typedef struct SDL_AudioSpec {
    1.21 -	int freq;		/* DSP frequency -- samples per second */
    1.22 -	Uint16 format;		/* Audio data format */
    1.23 -	Uint8  channels;	/* Number of channels: 1 mono, 2 stereo */
    1.24 -	Uint8  silence;		/* Audio buffer silence value (calculated) */
    1.25 -	Uint16 samples;		/* Audio buffer size in samples (power of 2) */
    1.26 -	Uint16 padding;		/* Necessary for some compile environments */
    1.27 -	Uint32 size;		/* Audio buffer size in bytes (calculated) */
    1.28 -	/* This function is called when the audio device needs more data.
    1.29 -	   'stream' is a pointer to the audio data buffer
    1.30 -	   'len' is the length of that buffer in bytes.
    1.31 -	   Once the callback returns, the buffer will no longer be valid.
    1.32 -	   Stereo samples are stored in a LRLRLR ordering.
    1.33 -	*/
    1.34 -	void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
    1.35 -	void  *userdata;
    1.36 -} SDL_AudioSpec;
    1.37 -
    1.38 -/* Audio format flags (defaults to LSB byte order) */
    1.39 -#define AUDIO_U8	0x0008	/* Unsigned 8-bit samples */
    1.40 -#define AUDIO_S8	0x8008	/* Signed 8-bit samples */
    1.41 -#define AUDIO_U16LSB	0x0010	/* Unsigned 16-bit samples */
    1.42 -#define AUDIO_S16LSB	0x8010	/* Signed 16-bit samples */
    1.43 -#define AUDIO_U16MSB	0x1010	/* As above, but big-endian byte order */
    1.44 -#define AUDIO_S16MSB	0x9010	/* As above, but big-endian byte order */
    1.45 -#define AUDIO_U16	AUDIO_U16LSB
    1.46 -#define AUDIO_S16	AUDIO_S16LSB
    1.47 -
    1.48 -/* Native audio byte ordering */
    1.49 -#if SDL_BYTEORDER == SDL_LIL_ENDIAN
    1.50 -#define AUDIO_U16SYS	AUDIO_U16LSB
    1.51 -#define AUDIO_S16SYS	AUDIO_S16LSB
    1.52 -#else
    1.53 -#define AUDIO_U16SYS	AUDIO_U16MSB
    1.54 -#define AUDIO_S16SYS	AUDIO_S16MSB
    1.55 -#endif
    1.56 -
    1.57 -
    1.58 -/* A structure to hold a set of audio conversion filters and buffers */
    1.59 -typedef struct SDL_AudioCVT {
    1.60 -	int needed;			/* Set to 1 if conversion possible */
    1.61 -	Uint16 src_format;		/* Source audio format */
    1.62 -	Uint16 dst_format;		/* Target audio format */
    1.63 -	double rate_incr;		/* Rate conversion increment */
    1.64 -	Uint8 *buf;			/* Buffer to hold entire audio data */
    1.65 -	int    len;			/* Length of original audio buffer */
    1.66 -	int    len_cvt;			/* Length of converted audio buffer */
    1.67 -	int    len_mult;		/* buffer must be len*len_mult big */
    1.68 -	double len_ratio; 	/* Given len, final size is len*len_ratio */
    1.69 -	void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
    1.70 -	int filter_index;		/* Current audio conversion function */
    1.71 -} SDL_AudioCVT;
    1.72 -
    1.73 -
    1.74 -/* Function prototypes */
    1.75 -
    1.76 -/* These functions are used internally, and should not be used unless you
    1.77 - * have a specific need to specify the audio driver you want to use.
    1.78 - * You should normally use SDL_Init() or SDL_InitSubSystem().
    1.79 - */
    1.80 -extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
    1.81 -extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
    1.82 -
    1.83 -/* This function fills the given character buffer with the name of the
    1.84 - * current audio driver, and returns a pointer to it if the audio driver has
    1.85 - * been initialized.  It returns NULL if no driver has been initialized.
    1.86 - */
    1.87 -extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
    1.88 -
    1.89 -/*
    1.90 - * This function opens the audio device with the desired parameters, and
    1.91 - * returns 0 if successful, placing the actual hardware parameters in the
    1.92 - * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
    1.93 - * data passed to the callback function will be guaranteed to be in the
    1.94 - * requested format, and will be automatically converted to the hardware
    1.95 - * audio format if necessary.  This function returns -1 if it failed 
    1.96 - * to open the audio device, or couldn't set up the audio thread.
    1.97 - *
    1.98 +/**
    1.99   * When filling in the desired audio spec structure,
   1.100 - *  'desired->freq' should be the desired audio frequency in samples-per-second.
   1.101 - *  'desired->format' should be the desired audio format.
   1.102 - *  'desired->samples' is the desired size of the audio buffer, in samples.
   1.103 + * - 'desired->freq' should be the desired audio frequency in samples-per-second.
   1.104 + * - 'desired->format' should be the desired audio format.
   1.105 + * - 'desired->samples' is the desired size of the audio buffer, in samples.
   1.106   *     This number should be a power of two, and may be adjusted by the audio
   1.107   *     driver to a value more suitable for the hardware.  Good values seem to
   1.108   *     range between 512 and 8096 inclusive, depending on the application and
   1.109 @@ -130,38 +55,138 @@
   1.110   *     and left channels in LR ordering.
   1.111   *     Note that the number of samples is directly related to time by the
   1.112   *     following formula:  ms = (samples*1000)/freq
   1.113 - *  'desired->size' is the size in bytes of the audio buffer, and is
   1.114 + * - 'desired->size' is the size in bytes of the audio buffer, and is
   1.115   *     calculated by SDL_OpenAudio().
   1.116 - *  'desired->silence' is the value used to set the buffer to silence,
   1.117 + * - 'desired->silence' is the value used to set the buffer to silence,
   1.118   *     and is calculated by SDL_OpenAudio().
   1.119 - *  'desired->callback' should be set to a function that will be called
   1.120 + * - 'desired->callback' should be set to a function that will be called
   1.121   *     when the audio device is ready for more data.  It is passed a pointer
   1.122   *     to the audio buffer, and the length in bytes of the audio buffer.
   1.123   *     This function usually runs in a separate thread, and so you should
   1.124   *     protect data structures that it accesses by calling SDL_LockAudio()
   1.125   *     and SDL_UnlockAudio() in your code.
   1.126 - *  'desired->userdata' is passed as the first parameter to your callback
   1.127 + * - 'desired->userdata' is passed as the first parameter to your callback
   1.128   *     function.
   1.129   *
   1.130 + * @note The calculated values in this structure are calculated by SDL_OpenAudio()
   1.131 + *
   1.132 + */
   1.133 +typedef struct SDL_AudioSpec {
   1.134 +	int freq;		/**< DSP frequency -- samples per second */
   1.135 +	Uint16 format;		/**< Audio data format */
   1.136 +	Uint8  channels;	/**< Number of channels: 1 mono, 2 stereo */
   1.137 +	Uint8  silence;		/**< Audio buffer silence value (calculated) */
   1.138 +	Uint16 samples;		/**< Audio buffer size in samples (power of 2) */
   1.139 +	Uint16 padding;		/**< Necessary for some compile environments */
   1.140 +	Uint32 size;		/**< Audio buffer size in bytes (calculated) */
   1.141 +	/**
   1.142 +	 *  This function is called when the audio device needs more data.
   1.143 +	 *
   1.144 +	 *  @param[out] stream	A pointer to the audio data buffer
   1.145 +	 *  @param[in]  len	The length of the audio buffer in bytes.
   1.146 +	 *
   1.147 +	 *  Once the callback returns, the buffer will no longer be valid.
   1.148 +	 *  Stereo samples are stored in a LRLRLR ordering.
   1.149 +	 */
   1.150 +	void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
   1.151 +	void  *userdata;
   1.152 +} SDL_AudioSpec;
   1.153 +
   1.154 +/**
   1.155 + *  @name Audio format flags
   1.156 + *  defaults to LSB byte order
   1.157 + */
   1.158 +/*@{*/
   1.159 +#define AUDIO_U8	0x0008	/**< Unsigned 8-bit samples */
   1.160 +#define AUDIO_S8	0x8008	/**< Signed 8-bit samples */
   1.161 +#define AUDIO_U16LSB	0x0010	/**< Unsigned 16-bit samples */
   1.162 +#define AUDIO_S16LSB	0x8010	/**< Signed 16-bit samples */
   1.163 +#define AUDIO_U16MSB	0x1010	/**< As above, but big-endian byte order */
   1.164 +#define AUDIO_S16MSB	0x9010	/**< As above, but big-endian byte order */
   1.165 +#define AUDIO_U16	AUDIO_U16LSB
   1.166 +#define AUDIO_S16	AUDIO_S16LSB
   1.167 +
   1.168 +/**
   1.169 + *  @name Native audio byte ordering
   1.170 + */
   1.171 +/*@{*/
   1.172 +#if SDL_BYTEORDER == SDL_LIL_ENDIAN
   1.173 +#define AUDIO_U16SYS	AUDIO_U16LSB
   1.174 +#define AUDIO_S16SYS	AUDIO_S16LSB
   1.175 +#else
   1.176 +#define AUDIO_U16SYS	AUDIO_U16MSB
   1.177 +#define AUDIO_S16SYS	AUDIO_S16MSB
   1.178 +#endif
   1.179 +/*@}*/
   1.180 +
   1.181 +/*@}*/
   1.182 +
   1.183 +
   1.184 +/** A structure to hold a set of audio conversion filters and buffers */
   1.185 +typedef struct SDL_AudioCVT {
   1.186 +	int needed;			/**< Set to 1 if conversion possible */
   1.187 +	Uint16 src_format;		/**< Source audio format */
   1.188 +	Uint16 dst_format;		/**< Target audio format */
   1.189 +	double rate_incr;		/**< Rate conversion increment */
   1.190 +	Uint8 *buf;			/**< Buffer to hold entire audio data */
   1.191 +	int    len;			/**< Length of original audio buffer */
   1.192 +	int    len_cvt;			/**< Length of converted audio buffer */
   1.193 +	int    len_mult;		/**< buffer must be len*len_mult big */
   1.194 +	double len_ratio; 	/**< Given len, final size is len*len_ratio */
   1.195 +	void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
   1.196 +	int filter_index;		/**< Current audio conversion function */
   1.197 +} SDL_AudioCVT;
   1.198 +
   1.199 +
   1.200 +/* Function prototypes */
   1.201 +
   1.202 +/**
   1.203 + * @name Audio Init and Quit
   1.204 + * These functions are used internally, and should not be used unless you
   1.205 + * have a specific need to specify the audio driver you want to use.
   1.206 + * You should normally use SDL_Init() or SDL_InitSubSystem().
   1.207 + */
   1.208 +/*@{*/
   1.209 +extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
   1.210 +extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
   1.211 +/*@}*/
   1.212 +
   1.213 +/**
   1.214 + * This function fills the given character buffer with the name of the
   1.215 + * current audio driver, and returns a pointer to it if the audio driver has
   1.216 + * been initialized.  It returns NULL if no driver has been initialized.
   1.217 + */
   1.218 +extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
   1.219 +
   1.220 +/**
   1.221 + * This function opens the audio device with the desired parameters, and
   1.222 + * returns 0 if successful, placing the actual hardware parameters in the
   1.223 + * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
   1.224 + * data passed to the callback function will be guaranteed to be in the
   1.225 + * requested format, and will be automatically converted to the hardware
   1.226 + * audio format if necessary.  This function returns -1 if it failed 
   1.227 + * to open the audio device, or couldn't set up the audio thread.
   1.228 + *
   1.229   * The audio device starts out playing silence when it's opened, and should
   1.230   * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
   1.231   * for your audio callback function to be called.  Since the audio driver
   1.232   * may modify the requested size of the audio buffer, you should allocate
   1.233   * any local mixing buffers after you open the audio device.
   1.234 + *
   1.235 + * @sa SDL_AudioSpec
   1.236   */
   1.237  extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);
   1.238  
   1.239 -/*
   1.240 - * Get the current audio state:
   1.241 - */
   1.242  typedef enum {
   1.243  	SDL_AUDIO_STOPPED = 0,
   1.244  	SDL_AUDIO_PLAYING,
   1.245  	SDL_AUDIO_PAUSED
   1.246  } SDL_audiostatus;
   1.247 +
   1.248 +/** Get the current audio state */
   1.249  extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
   1.250  
   1.251 -/*
   1.252 +/**
   1.253   * This function pauses and unpauses the audio callback processing.
   1.254   * It should be called with a parameter of 0 after opening the audio
   1.255   * device to start playing sound.  This is so you can safely initialize
   1.256 @@ -170,11 +195,11 @@
   1.257   */
   1.258  extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   1.259  
   1.260 -/*
   1.261 +/**
   1.262   * This function loads a WAVE from the data source, automatically freeing
   1.263   * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
   1.264   * you could do:
   1.265 - *	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
   1.266 + *	@code SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); @endcode
   1.267   *
   1.268   * If this function succeeds, it returns the given SDL_AudioSpec,
   1.269   * filled with the audio data format of the wave data, and sets
   1.270 @@ -189,27 +214,29 @@
   1.271   */
   1.272  extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
   1.273  
   1.274 -/* Compatibility convenience function -- loads a WAV from a file */
   1.275 +/** Compatibility convenience function -- loads a WAV from a file */
   1.276  #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
   1.277  	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
   1.278  
   1.279 -/*
   1.280 +/**
   1.281   * This function frees data previously allocated with SDL_LoadWAV_RW()
   1.282   */
   1.283  extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf);
   1.284  
   1.285 -/*
   1.286 +/**
   1.287   * This function takes a source format and rate and a destination format
   1.288   * and rate, and initializes the 'cvt' structure with information needed
   1.289   * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   1.290   * to the other.
   1.291 - * This function returns 0, or -1 if there was an error.
   1.292 + *
   1.293 + * @return This function returns 0, or -1 if there was an error.
   1.294   */
   1.295  extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt,
   1.296  		Uint16 src_format, Uint8 src_channels, int src_rate,
   1.297  		Uint16 dst_format, Uint8 dst_channels, int dst_rate);
   1.298  
   1.299 -/* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
   1.300 +/**
   1.301 + * Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
   1.302   * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
   1.303   * audio data in the source format, this function will convert it in-place
   1.304   * to the desired format.
   1.305 @@ -219,26 +246,30 @@
   1.306   */
   1.307  extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt);
   1.308  
   1.309 -/*
   1.310 +
   1.311 +#define SDL_MIX_MAXVOLUME 128
   1.312 +/**
   1.313   * This takes two audio buffers of the playing audio format and mixes
   1.314   * them, performing addition, volume adjustment, and overflow clipping.
   1.315   * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
   1.316   * for full audio volume.  Note this does not change hardware volume.
   1.317   * This is provided for convenience -- you can mix your own audio data.
   1.318   */
   1.319 -#define SDL_MIX_MAXVOLUME 128
   1.320  extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume);
   1.321  
   1.322 -/*
   1.323 +/**
   1.324 + * @name Audio Locks
   1.325   * The lock manipulated by these functions protects the callback function.
   1.326   * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   1.327   * callback function is not running.  Do not call these from the callback
   1.328   * function or you will cause deadlock.
   1.329   */
   1.330 +/*@{*/
   1.331  extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   1.332  extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   1.333 +/*@}*/
   1.334  
   1.335 -/*
   1.336 +/**
   1.337   * This function shuts down audio processing and closes the audio device.
   1.338   */
   1.339  extern DECLSPEC void SDLCALL SDL_CloseAudio(void);