include/SDL_audio.h
changeset 7191 75360622e65f
parent 6885 700f1b25f77f
child 7546 f9ff5e066e49
     1.1 --- a/include/SDL_audio.h	Sat May 18 12:48:50 2013 -0700
     1.2 +++ b/include/SDL_audio.h	Sat May 18 14:17:52 2013 -0700
     1.3 @@ -21,7 +21,7 @@
     1.4  
     1.5  /**
     1.6   *  \file SDL_audio.h
     1.7 - *  
     1.8 + *
     1.9   *  Access to the raw audio mixing buffer for the SDL library.
    1.10   */
    1.11  
    1.12 @@ -38,17 +38,15 @@
    1.13  #include "begin_code.h"
    1.14  /* Set up for C function definitions, even when using C++ */
    1.15  #ifdef __cplusplus
    1.16 -/* *INDENT-OFF* */
    1.17  extern "C" {
    1.18 -/* *INDENT-ON* */
    1.19  #endif
    1.20  
    1.21  /**
    1.22   *  \brief Audio format flags.
    1.23 - *  
    1.24 + *
    1.25   *  These are what the 16 bits in SDL_AudioFormat currently mean...
    1.26   *  (Unspecified bits are always zero).
    1.27 - *  
    1.28 + *
    1.29   *  \verbatim
    1.30      ++-----------------------sample is signed if set
    1.31      ||
    1.32 @@ -60,7 +58,7 @@
    1.33      ||       ||          || |                     |
    1.34      15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
    1.35      \endverbatim
    1.36 - *  
    1.37 + *
    1.38   *  There are macros in SDL 2.0 and later to query these bits.
    1.39   */
    1.40  typedef Uint16 SDL_AudioFormat;
    1.41 @@ -82,42 +80,38 @@
    1.42  #define SDL_AUDIO_ISLITTLEENDIAN(x)  (!SDL_AUDIO_ISBIGENDIAN(x))
    1.43  #define SDL_AUDIO_ISUNSIGNED(x)      (!SDL_AUDIO_ISSIGNED(x))
    1.44  
    1.45 -/** 
    1.46 +/**
    1.47   *  \name Audio format flags
    1.48   *
    1.49   *  Defaults to LSB byte order.
    1.50   */
    1.51  /*@{*/
    1.52 -#define AUDIO_U8	0x0008  /**< Unsigned 8-bit samples */
    1.53 -#define AUDIO_S8	0x8008  /**< Signed 8-bit samples */
    1.54 -#define AUDIO_U16LSB	0x0010  /**< Unsigned 16-bit samples */
    1.55 -#define AUDIO_S16LSB	0x8010  /**< Signed 16-bit samples */
    1.56 -#define AUDIO_U16MSB	0x1010  /**< As above, but big-endian byte order */
    1.57 -#define AUDIO_S16MSB	0x9010  /**< As above, but big-endian byte order */
    1.58 -#define AUDIO_U16	AUDIO_U16LSB
    1.59 -#define AUDIO_S16	AUDIO_S16LSB
    1.60 +#define AUDIO_U8        0x0008  /**< Unsigned 8-bit samples */
    1.61 +#define AUDIO_S8        0x8008  /**< Signed 8-bit samples */
    1.62 +#define AUDIO_U16LSB    0x0010  /**< Unsigned 16-bit samples */
    1.63 +#define AUDIO_S16LSB    0x8010  /**< Signed 16-bit samples */
    1.64 +#define AUDIO_U16MSB    0x1010  /**< As above, but big-endian byte order */
    1.65 +#define AUDIO_S16MSB    0x9010  /**< As above, but big-endian byte order */
    1.66 +#define AUDIO_U16       AUDIO_U16LSB
    1.67 +#define AUDIO_S16       AUDIO_S16LSB
    1.68  /*@}*/
    1.69  
    1.70  /**
    1.71   *  \name int32 support
    1.72 - *  
    1.73 - *  New to SDL 1.3.
    1.74   */
    1.75  /*@{*/
    1.76 -#define AUDIO_S32LSB	0x8020  /**< 32-bit integer samples */
    1.77 -#define AUDIO_S32MSB	0x9020  /**< As above, but big-endian byte order */
    1.78 -#define AUDIO_S32	AUDIO_S32LSB
    1.79 +#define AUDIO_S32LSB    0x8020  /**< 32-bit integer samples */
    1.80 +#define AUDIO_S32MSB    0x9020  /**< As above, but big-endian byte order */
    1.81 +#define AUDIO_S32       AUDIO_S32LSB
    1.82  /*@}*/
    1.83  
    1.84  /**
    1.85   *  \name float32 support
    1.86 - *  
    1.87 - *  New to SDL 1.3.
    1.88   */
    1.89  /*@{*/
    1.90 -#define AUDIO_F32LSB	0x8120  /**< 32-bit floating point samples */
    1.91 -#define AUDIO_F32MSB	0x9120  /**< As above, but big-endian byte order */
    1.92 -#define AUDIO_F32	AUDIO_F32LSB
    1.93 +#define AUDIO_F32LSB    0x8120  /**< 32-bit floating point samples */
    1.94 +#define AUDIO_F32MSB    0x9120  /**< As above, but big-endian byte order */
    1.95 +#define AUDIO_F32       AUDIO_F32LSB
    1.96  /*@}*/
    1.97  
    1.98  /**
    1.99 @@ -125,21 +119,21 @@
   1.100   */
   1.101  /*@{*/
   1.102  #if SDL_BYTEORDER == SDL_LIL_ENDIAN
   1.103 -#define AUDIO_U16SYS	AUDIO_U16LSB
   1.104 -#define AUDIO_S16SYS	AUDIO_S16LSB
   1.105 -#define AUDIO_S32SYS	AUDIO_S32LSB
   1.106 -#define AUDIO_F32SYS	AUDIO_F32LSB
   1.107 +#define AUDIO_U16SYS    AUDIO_U16LSB
   1.108 +#define AUDIO_S16SYS    AUDIO_S16LSB
   1.109 +#define AUDIO_S32SYS    AUDIO_S32LSB
   1.110 +#define AUDIO_F32SYS    AUDIO_F32LSB
   1.111  #else
   1.112 -#define AUDIO_U16SYS	AUDIO_U16MSB
   1.113 -#define AUDIO_S16SYS	AUDIO_S16MSB
   1.114 -#define AUDIO_S32SYS	AUDIO_S32MSB
   1.115 -#define AUDIO_F32SYS	AUDIO_F32MSB
   1.116 +#define AUDIO_U16SYS    AUDIO_U16MSB
   1.117 +#define AUDIO_S16SYS    AUDIO_S16MSB
   1.118 +#define AUDIO_S32SYS    AUDIO_S32MSB
   1.119 +#define AUDIO_F32SYS    AUDIO_F32MSB
   1.120  #endif
   1.121  /*@}*/
   1.122  
   1.123 -/** 
   1.124 +/**
   1.125   *  \name Allow change flags
   1.126 - *  
   1.127 + *
   1.128   *  Which audio format changes are allowed when opening a device.
   1.129   */
   1.130  /*@{*/
   1.131 @@ -209,7 +203,7 @@
   1.132  
   1.133  /**
   1.134   *  \name Driver discovery functions
   1.135 - *  
   1.136 + *
   1.137   *  These functions return the list of built in audio drivers, in the
   1.138   *  order that they are normally initialized by default.
   1.139   */
   1.140 @@ -220,9 +214,9 @@
   1.141  
   1.142  /**
   1.143   *  \name Initialization and cleanup
   1.144 - *  
   1.145 + *
   1.146   *  \internal These functions are used internally, and should not be used unless
   1.147 - *            you have a specific need to specify the audio driver you want to 
   1.148 + *            you have a specific need to specify the audio driver you want to
   1.149   *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
   1.150   */
   1.151  /*@{*/
   1.152 @@ -242,20 +236,20 @@
   1.153   *  structure pointed to by \c obtained.  If \c obtained is NULL, the audio
   1.154   *  data passed to the callback function will be guaranteed to be in the
   1.155   *  requested format, and will be automatically converted to the hardware
   1.156 - *  audio format if necessary.  This function returns -1 if it failed 
   1.157 + *  audio format if necessary.  This function returns -1 if it failed
   1.158   *  to open the audio device, or couldn't set up the audio thread.
   1.159 - *  
   1.160 + *
   1.161   *  When filling in the desired audio spec structure,
   1.162   *    - \c desired->freq should be the desired audio frequency in samples-per-
   1.163   *      second.
   1.164   *    - \c desired->format should be the desired audio format.
   1.165 - *    - \c desired->samples is the desired size of the audio buffer, in 
   1.166 - *      samples.  This number should be a power of two, and may be adjusted by 
   1.167 + *    - \c desired->samples is the desired size of the audio buffer, in
   1.168 + *      samples.  This number should be a power of two, and may be adjusted by
   1.169   *      the audio driver to a value more suitable for the hardware.  Good values
   1.170 - *      seem to range between 512 and 8096 inclusive, depending on the 
   1.171 - *      application and CPU speed.  Smaller values yield faster response time, 
   1.172 - *      but can lead to underflow if the application is doing heavy processing 
   1.173 - *      and cannot fill the audio buffer in time.  A stereo sample consists of 
   1.174 + *      seem to range between 512 and 8096 inclusive, depending on the
   1.175 + *      application and CPU speed.  Smaller values yield faster response time,
   1.176 + *      but can lead to underflow if the application is doing heavy processing
   1.177 + *      and cannot fill the audio buffer in time.  A stereo sample consists of
   1.178   *      both right and left channels in LR ordering.
   1.179   *      Note that the number of samples is directly related to time by the
   1.180   *      following formula:  \code ms = (samples*1000)/freq \endcode
   1.181 @@ -271,7 +265,7 @@
   1.182   *      and SDL_UnlockAudio() in your code.
   1.183   *    - \c desired->userdata is passed as the first parameter to your callback
   1.184   *      function.
   1.185 - *  
   1.186 + *
   1.187   *  The audio device starts out playing silence when it's opened, and should
   1.188   *  be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
   1.189   *  for your audio callback function to be called.  Since the audio driver
   1.190 @@ -283,7 +277,7 @@
   1.191  
   1.192  /**
   1.193   *  SDL Audio Device IDs.
   1.194 - *  
   1.195 + *
   1.196   *  A successful call to SDL_OpenAudio() is always device id 1, and legacy
   1.197   *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
   1.198   *  always returns devices >= 2 on success. The legacy calls are good both
   1.199 @@ -299,7 +293,7 @@
   1.200   *  not an error. For example, if SDL is set up to talk to a remote audio
   1.201   *  server, it can't list every one available on the Internet, but it will
   1.202   *  still allow a specific host to be specified to SDL_OpenAudioDevice().
   1.203 - *  
   1.204 + *
   1.205   *  In many common cases, when this function returns a value <= 0, it can still
   1.206   *  successfully open the default device (NULL for first argument of
   1.207   *  SDL_OpenAudioDevice()).
   1.208 @@ -313,7 +307,7 @@
   1.209   *  The values returned by this function reflect the latest call to
   1.210   *  SDL_GetNumAudioDevices(); recall that function to redetect available
   1.211   *  hardware.
   1.212 - *  
   1.213 + *
   1.214   *  The string returned by this function is UTF-8 encoded, read-only, and
   1.215   *  managed internally. You are not to free it. If you need to keep the
   1.216   *  string for any length of time, you should make your own copy of it, as it
   1.217 @@ -326,14 +320,14 @@
   1.218  /**
   1.219   *  Open a specific audio device. Passing in a device name of NULL requests
   1.220   *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
   1.221 - *  
   1.222 + *
   1.223   *  The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
   1.224   *  some drivers allow arbitrary and driver-specific strings, such as a
   1.225   *  hostname/IP address for a remote audio server, or a filename in the
   1.226   *  diskaudio driver.
   1.227 - *  
   1.228 + *
   1.229   *  \return 0 on error, a valid device ID that is >= 2 on success.
   1.230 - *  
   1.231 + *
   1.232   *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
   1.233   */
   1.234  extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
   1.235 @@ -351,7 +345,7 @@
   1.236  
   1.237  /**
   1.238   *  \name Audio state
   1.239 - *  
   1.240 + *
   1.241   *  Get the current audio state.
   1.242   */
   1.243  /*@{*/
   1.244 @@ -369,7 +363,7 @@
   1.245  
   1.246  /**
   1.247   *  \name Pause audio functions
   1.248 - *  
   1.249 + *
   1.250   *  These functions pause and unpause the audio callback processing.
   1.251   *  They should be called with a parameter of 0 after opening the audio
   1.252   *  device to start playing sound.  This is so you can safely initialize
   1.253 @@ -387,18 +381,18 @@
   1.254   *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
   1.255   *  you could do:
   1.256   *  \code
   1.257 - *  	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
   1.258 + *      SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
   1.259   *  \endcode
   1.260   *
   1.261   *  If this function succeeds, it returns the given SDL_AudioSpec,
   1.262   *  filled with the audio data format of the wave data, and sets
   1.263   *  \c *audio_buf to a malloc()'d buffer containing the audio data,
   1.264   *  and sets \c *audio_len to the length of that audio buffer, in bytes.
   1.265 - *  You need to free the audio buffer with SDL_FreeWAV() when you are 
   1.266 + *  You need to free the audio buffer with SDL_FreeWAV() when you are
   1.267   *  done with it.
   1.268   *
   1.269 - *  This function returns NULL and sets the SDL error message if the 
   1.270 - *  wave file cannot be opened, uses an unknown data format, or is 
   1.271 + *  This function returns NULL and sets the SDL error message if the
   1.272 + *  wave file cannot be opened, uses an unknown data format, or is
   1.273   *  corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
   1.274   */
   1.275  extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
   1.276 @@ -407,12 +401,12 @@
   1.277                                                        Uint8 ** audio_buf,
   1.278                                                        Uint32 * audio_len);
   1.279  
   1.280 -/** 
   1.281 +/**
   1.282   *  Loads a WAV from a file.
   1.283   *  Compatibility convenience function.
   1.284   */
   1.285  #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
   1.286 -	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
   1.287 +    SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
   1.288  
   1.289  /**
   1.290   *  This function frees data previously allocated with SDL_LoadWAV_RW()
   1.291 @@ -424,7 +418,7 @@
   1.292   *  and rate, and initializes the \c cvt structure with information needed
   1.293   *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
   1.294   *  to the other.
   1.295 - *  
   1.296 + *
   1.297   *  \return -1 if the format conversion is not supported, 0 if there's
   1.298   *  no conversion needed, or 1 if the audio filter is set up.
   1.299   */
   1.300 @@ -441,7 +435,7 @@
   1.301   *  created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
   1.302   *  audio data in the source format, this function will convert it in-place
   1.303   *  to the desired format.
   1.304 - *  
   1.305 + *
   1.306   *  The data conversion may expand the size of the audio data, so the buffer
   1.307   *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
   1.308   *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
   1.309 @@ -471,9 +465,9 @@
   1.310  
   1.311  /**
   1.312   *  \name Audio lock functions
   1.313 - *  
   1.314 + *
   1.315   *  The lock manipulated by these functions protects the callback function.
   1.316 - *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that 
   1.317 + *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
   1.318   *  the callback function is not running.  Do not call these from the callback
   1.319   *  function or you will cause deadlock.
   1.320   */
   1.321 @@ -498,9 +492,7 @@
   1.322  
   1.323  /* Ends C function definitions when using C++ */
   1.324  #ifdef __cplusplus
   1.325 -/* *INDENT-OFF* */
   1.326  }
   1.327 -/* *INDENT-ON* */
   1.328  #endif
   1.329  #include "close_code.h"
   1.330