include/SDL_audio.h
changeset 1964 071b6598d48f
parent 1895 c121d94672cb
child 1967 01e29c3e9a29
equal deleted inserted replaced
1963:2590b68531ef 1964:071b6598d48f
    42 /* *INDENT-OFF* */
    42 /* *INDENT-OFF* */
    43 extern "C" {
    43 extern "C" {
    44 /* *INDENT-ON* */
    44 /* *INDENT-ON* */
    45 #endif
    45 #endif
    46 
    46 
       
    47 typedef Uint16 SDL_AudioFormat;
       
    48 
    47 /* The calculated values in this structure are calculated by SDL_OpenAudio() */
    49 /* The calculated values in this structure are calculated by SDL_OpenAudio() */
    48 typedef struct SDL_AudioSpec
    50 typedef struct SDL_AudioSpec
    49 {
    51 {
    50     int freq;                   /* DSP frequency -- samples per second */
    52     int freq;                   /* DSP frequency -- samples per second */
    51     Uint16 format;              /* Audio data format */
    53     SDL_AudioFormat format;     /* Audio data format */
    52     Uint8 channels;             /* Number of channels: 1 mono, 2 stereo */
    54     Uint8 channels;             /* Number of channels: 1 mono, 2 stereo */
    53     Uint8 silence;              /* Audio buffer silence value (calculated) */
    55     Uint8 silence;              /* Audio buffer silence value (calculated) */
    54     Uint16 samples;             /* Audio buffer size in samples (power of 2) */
    56     Uint16 samples;             /* Audio buffer size in samples (power of 2) */
    55     Uint16 padding;             /* Necessary for some compile environments */
    57     Uint16 padding;             /* Necessary for some compile environments */
    56     Uint32 size;                /* Audio buffer size in bytes (calculated) */
    58     Uint32 size;                /* Audio buffer size in bytes (calculated) */
    62      */
    64      */
    63     void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
    65     void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
    64     void *userdata;
    66     void *userdata;
    65 } SDL_AudioSpec;
    67 } SDL_AudioSpec;
    66 
    68 
       
    69 
       
    70 /*
       
    71  These are what the 16 bits in SDL_AudioFormat currently mean...
       
    72  (Unspecified bits are always zero.)
       
    73 
       
    74  ++-----------------------sample is signed if set
       
    75  ||
       
    76  ||       ++-----------sample is bigendian if set
       
    77  ||       ||
       
    78  ||       ||          ++---sample is float if set
       
    79  ||       ||          ||
       
    80  ||       ||          || +---sample bit size---+
       
    81  ||       ||          || |                     |
       
    82  15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
       
    83 
       
    84  There are macros in SDL 1.3 and later to query these bits.
       
    85 */
       
    86 
       
    87 #define SDL_AUDIO_MASK_BITSIZE       (0xFF)
       
    88 #define SDL_AUDIO_MASK_DATATYPE      (1<<8)
       
    89 #define SDL_AUDIO_MASK_ENDIAN        (1<<12)
       
    90 #define SDL_AUDIO_MASK_SIGNED        (1<<15)
       
    91 #define SDL_AUDIO_BITSIZE(x)         (x & SDL_AUDIO_MASK_BITSIZE)
       
    92 #define SDL_AUDIO_ISFLOAT(x)         (x & SDL_AUDIO_MASK_DATATYPE)
       
    93 #define SDL_AUDIO_ISBIGENDIAN(x)     (x & SDL_AUDIO_MASK_ENDIAN)
       
    94 #define SDL_AUDIO_ISSIGNED(x)        (x & SDL_AUDIO_MASK_SIGNED)
       
    95 #define SDL_AUDIO_ISINT(x)           (!SDL_AUDIO_ISFLOAT(x))
       
    96 #define SDL_AUDIO_ISLITTLEENDIAN(x)  (!SDL_AUDIO_ISBIGENDIAN(x))
       
    97 #define SDL_AUDIO_ISUNSIGNED(x)      (!SDL_AUDIO_ISSIGNED(x))
       
    98 
    67 /* Audio format flags (defaults to LSB byte order) */
    99 /* Audio format flags (defaults to LSB byte order) */
    68 #define AUDIO_U8	0x0008  /* Unsigned 8-bit samples */
   100 #define AUDIO_U8	0x0008  /* Unsigned 8-bit samples */
    69 #define AUDIO_S8	0x8008  /* Signed 8-bit samples */
   101 #define AUDIO_S8	0x8008  /* Signed 8-bit samples */
    70 #define AUDIO_U16LSB	0x0010  /* Unsigned 16-bit samples */
   102 #define AUDIO_U16LSB	0x0010  /* Unsigned 16-bit samples */
    71 #define AUDIO_S16LSB	0x8010  /* Signed 16-bit samples */
   103 #define AUDIO_S16LSB	0x8010  /* Signed 16-bit samples */
    72 #define AUDIO_U16MSB	0x1010  /* As above, but big-endian byte order */
   104 #define AUDIO_U16MSB	0x1010  /* As above, but big-endian byte order */
    73 #define AUDIO_S16MSB	0x9010  /* As above, but big-endian byte order */
   105 #define AUDIO_S16MSB	0x9010  /* As above, but big-endian byte order */
    74 #define AUDIO_U16	AUDIO_U16LSB
   106 #define AUDIO_U16	AUDIO_U16LSB
    75 #define AUDIO_S16	AUDIO_S16LSB
   107 #define AUDIO_S16	AUDIO_S16LSB
    76 
   108 
       
   109 /* int32 support new to SDL 1.3 */
       
   110 #define AUDIO_S32LSB	0x8020  /* 32-bit integer samples */
       
   111 #define AUDIO_S32MSB	0x9020  /* As above, but big-endian byte order */
       
   112 #define AUDIO_S32	AUDIO_S32LSB
       
   113 #define AUDIO_U32LSB	0x0020  /* Unsigned 32-bit integer samples */
       
   114 #define AUDIO_U32MSB	0x1020  /* As above, but big-endian byte order */
       
   115 #define AUDIO_U32	AUDIO_U32LSB
       
   116 
       
   117 /* float32 support new to SDL 1.3 */
       
   118 #define AUDIO_F32LSB	0x8120  /* 32-bit floating point samples */
       
   119 #define AUDIO_F32MSB	0x9120  /* As above, but big-endian byte order */
       
   120 #define AUDIO_F32	AUDIO_F32LSB
       
   121 
    77 /* Native audio byte ordering */
   122 /* Native audio byte ordering */
    78 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
   123 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
    79 #define AUDIO_U16SYS	AUDIO_U16LSB
   124 #define AUDIO_U16SYS	AUDIO_U16LSB
    80 #define AUDIO_S16SYS	AUDIO_S16LSB
   125 #define AUDIO_S16SYS	AUDIO_S16LSB
       
   126 #define AUDIO_S32SYS	AUDIO_S32LSB
       
   127 #define AUDIO_U32SYS	AUDIO_U32LSB
       
   128 #define AUDIO_F32SYS	AUDIO_F32LSB
    81 #else
   129 #else
    82 #define AUDIO_U16SYS	AUDIO_U16MSB
   130 #define AUDIO_U16SYS	AUDIO_U16MSB
    83 #define AUDIO_S16SYS	AUDIO_S16MSB
   131 #define AUDIO_S16SYS	AUDIO_S16MSB
       
   132 #define AUDIO_S32SYS	AUDIO_S32MSB
       
   133 #define AUDIO_U32SYS	AUDIO_U32MSB
       
   134 #define AUDIO_F32SYS	AUDIO_F32MSB
    84 #endif
   135 #endif
    85 
   136 
    86 
   137 
    87 /* A structure to hold a set of audio conversion filters and buffers */
   138 /* A structure to hold a set of audio conversion filters and buffers */
    88 typedef struct SDL_AudioCVT
   139 typedef struct SDL_AudioCVT
   164  */
   215  */
   165 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
   216 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
   166                                           SDL_AudioSpec * obtained);
   217                                           SDL_AudioSpec * obtained);
   167 
   218 
   168 /*
   219 /*
       
   220  * SDL Audio Device IDs.
       
   221  * A successful call to SDL_OpenAudio() is always device id 1, and legacy
       
   222  *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
       
   223  *  always returns devices >= 2 on success. The legacy calls are good both
       
   224  *  for backwards compatibility and when you don't care about multiple,
       
   225  *  specific, or capture devices.
       
   226  */
       
   227 typedef Uint32 SDL_AudioDeviceID;
       
   228 
       
   229 /*
       
   230  * Get the number of available devices exposed by the current driver.
       
   231  *  Only valid after a successfully initializing the audio subsystem.
       
   232  */
       
   233 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
       
   234 
       
   235 /*
       
   236  * Get the human-readable name of a specific audio device.
       
   237  *  Must be a value between 0 and (number of audio devices-1).
       
   238  *  Only valid after a successfully initializing the audio subsystem.
       
   239  */
       
   240 extern DECLSPEC const char *SDLCALL SDL_GetAudioDevice(int index, int iscapture);
       
   241 
       
   242 
       
   243 /*
       
   244  * Open a specific audio device. Passing in a device name of NULL is
       
   245  *  equivalent to SDL_OpenAudio(). Returns 0 on error, a valid device ID
       
   246  *  on success.
       
   247  */
       
   248 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
       
   249                                                 const char * device,
       
   250                                                 int iscapture,
       
   251                                                 const SDL_AudioSpec * desired,
       
   252                                                 SDL_AudioSpec * obtained);
       
   253 
       
   254 
       
   255 
       
   256 /*
   169  * Get the current audio state:
   257  * Get the current audio state:
   170  */
   258  */
   171 typedef enum
   259 typedef enum
   172 {
   260 {
   173     SDL_AUDIO_STOPPED = 0,
   261     SDL_AUDIO_STOPPED = 0,
   174     SDL_AUDIO_PLAYING,
   262     SDL_AUDIO_PLAYING,
   175     SDL_AUDIO_PAUSED
   263     SDL_AUDIO_PAUSED
   176 } SDL_audiostatus;
   264 } SDL_audiostatus;
   177 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
   265 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
   178 
   266 
       
   267 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioDeviceStatus(
       
   268                                                         SDL_AudioDeviceID dev);
       
   269 
   179 /*
   270 /*
   180  * This function pauses and unpauses the audio callback processing.
   271  * This function pauses and unpauses the audio callback processing.
   181  * It should be called with a parameter of 0 after opening the audio
   272  * 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
   273  * device to start playing sound.  This is so you can safely initialize
   183  * data for your callback function after opening the audio device.
   274  * data for your callback function after opening the audio device.
   184  * Silence will be written to the audio device during the pause.
   275  * Silence will be written to the audio device during the pause.
   185  */
   276  */
   186 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   277 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
       
   278 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
       
   279                                                   int pause_on);
   187 
   280 
   188 /*
   281 /*
   189  * This function loads a WAVE from the data source, automatically freeing
   282  * 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,
   283  * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
   191  * you could do:
   284  * you could do:
   220 /*
   313 /*
   221  * This function takes a source format and rate and a destination format
   314  * This function takes a source format and rate and a destination format
   222  * and rate, and initializes the 'cvt' structure with information needed
   315  * and rate, and initializes the 'cvt' structure with information needed
   223  * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   316  * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   224  * to the other.
   317  * to the other.
   225  * This function returns 0, or -1 if there was an error.
   318  * Returns -1 if the format conversion is not supported, 0 if there's
       
   319  *  no conversion needed, or 1 if the audio filter is set up.
   226  */
   320  */
   227 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
   321 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
   228                                               Uint16 src_format,
   322                                               Uint16 src_format,
   229                                               Uint8 src_channels,
   323                                               Uint8 src_channels,
   230                                               int src_rate,
   324                                               int src_rate,
   252 #define SDL_MIX_MAXVOLUME 128
   346 #define SDL_MIX_MAXVOLUME 128
   253 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
   347 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
   254                                           Uint32 len, int volume);
   348                                           Uint32 len, int volume);
   255 
   349 
   256 /*
   350 /*
       
   351  * This works like SDL_MixAudio, but you specify the audio format instead of
       
   352  *  using the format of audio device 1. Thus it can be used when no audio
       
   353  *  device is open at all.
       
   354  */
       
   355 extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, const Uint8 * src,
       
   356                                                 SDL_AudioFormat format,
       
   357                                                 Uint32 len, int volume);
       
   358 
       
   359 /*
   257  * The lock manipulated by these functions protects the callback function.
   360  * The lock manipulated by these functions protects the callback function.
   258  * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   361  * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   259  * callback function is not running.  Do not call these from the callback
   362  * callback function is not running.  Do not call these from the callback
   260  * function or you will cause deadlock.
   363  * function or you will cause deadlock.
   261  */
   364  */
   262 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   365 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
       
   366 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
   263 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   367 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
       
   368 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
   264 
   369 
   265 /*
   370 /*
   266  * This function shuts down audio processing and closes the audio device.
   371  * This function shuts down audio processing and closes the audio device.
   267  */
   372  */
   268 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
   373 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
       
   374 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
       
   375 
       
   376 /*
       
   377  * Returns 1 if audio device is still functioning, zero if not, -1 on error.
       
   378  */
       
   379 extern DECLSPEC int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev);
   269 
   380 
   270 
   381 
   271 /* Ends C function definitions when using C++ */
   382 /* Ends C function definitions when using C++ */
   272 #ifdef __cplusplus
   383 #ifdef __cplusplus
   273 /* *INDENT-OFF* */
   384 /* *INDENT-OFF* */