include/SDL_audio.h
changeset 1964 071b6598d48f
parent 1895 c121d94672cb
child 1967 01e29c3e9a29
     1.1 --- a/include/SDL_audio.h	Wed Aug 02 03:20:52 2006 +0000
     1.2 +++ b/include/SDL_audio.h	Thu Aug 03 19:34:05 2006 +0000
     1.3 @@ -44,11 +44,13 @@
     1.4  /* *INDENT-ON* */
     1.5  #endif
     1.6  
     1.7 +typedef Uint16 SDL_AudioFormat;
     1.8 +
     1.9  /* The calculated values in this structure are calculated by SDL_OpenAudio() */
    1.10  typedef struct SDL_AudioSpec
    1.11  {
    1.12      int freq;                   /* DSP frequency -- samples per second */
    1.13 -    Uint16 format;              /* Audio data format */
    1.14 +    SDL_AudioFormat format;     /* Audio data format */
    1.15      Uint8 channels;             /* Number of channels: 1 mono, 2 stereo */
    1.16      Uint8 silence;              /* Audio buffer silence value (calculated) */
    1.17      Uint16 samples;             /* Audio buffer size in samples (power of 2) */
    1.18 @@ -64,6 +66,36 @@
    1.19      void *userdata;
    1.20  } SDL_AudioSpec;
    1.21  
    1.22 +
    1.23 +/*
    1.24 + These are what the 16 bits in SDL_AudioFormat currently mean...
    1.25 + (Unspecified bits are always zero.)
    1.26 +
    1.27 + ++-----------------------sample is signed if set
    1.28 + ||
    1.29 + ||       ++-----------sample is bigendian if set
    1.30 + ||       ||
    1.31 + ||       ||          ++---sample is float if set
    1.32 + ||       ||          ||
    1.33 + ||       ||          || +---sample bit size---+
    1.34 + ||       ||          || |                     |
    1.35 + 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
    1.36 +
    1.37 + There are macros in SDL 1.3 and later to query these bits.
    1.38 +*/
    1.39 +
    1.40 +#define SDL_AUDIO_MASK_BITSIZE       (0xFF)
    1.41 +#define SDL_AUDIO_MASK_DATATYPE      (1<<8)
    1.42 +#define SDL_AUDIO_MASK_ENDIAN        (1<<12)
    1.43 +#define SDL_AUDIO_MASK_SIGNED        (1<<15)
    1.44 +#define SDL_AUDIO_BITSIZE(x)         (x & SDL_AUDIO_MASK_BITSIZE)
    1.45 +#define SDL_AUDIO_ISFLOAT(x)         (x & SDL_AUDIO_MASK_DATATYPE)
    1.46 +#define SDL_AUDIO_ISBIGENDIAN(x)     (x & SDL_AUDIO_MASK_ENDIAN)
    1.47 +#define SDL_AUDIO_ISSIGNED(x)        (x & SDL_AUDIO_MASK_SIGNED)
    1.48 +#define SDL_AUDIO_ISINT(x)           (!SDL_AUDIO_ISFLOAT(x))
    1.49 +#define SDL_AUDIO_ISLITTLEENDIAN(x)  (!SDL_AUDIO_ISBIGENDIAN(x))
    1.50 +#define SDL_AUDIO_ISUNSIGNED(x)      (!SDL_AUDIO_ISSIGNED(x))
    1.51 +
    1.52  /* Audio format flags (defaults to LSB byte order) */
    1.53  #define AUDIO_U8	0x0008  /* Unsigned 8-bit samples */
    1.54  #define AUDIO_S8	0x8008  /* Signed 8-bit samples */
    1.55 @@ -74,13 +106,32 @@
    1.56  #define AUDIO_U16	AUDIO_U16LSB
    1.57  #define AUDIO_S16	AUDIO_S16LSB
    1.58  
    1.59 +/* int32 support new to SDL 1.3 */
    1.60 +#define AUDIO_S32LSB	0x8020  /* 32-bit integer samples */
    1.61 +#define AUDIO_S32MSB	0x9020  /* As above, but big-endian byte order */
    1.62 +#define AUDIO_S32	AUDIO_S32LSB
    1.63 +#define AUDIO_U32LSB	0x0020  /* Unsigned 32-bit integer samples */
    1.64 +#define AUDIO_U32MSB	0x1020  /* As above, but big-endian byte order */
    1.65 +#define AUDIO_U32	AUDIO_U32LSB
    1.66 +
    1.67 +/* float32 support new to SDL 1.3 */
    1.68 +#define AUDIO_F32LSB	0x8120  /* 32-bit floating point samples */
    1.69 +#define AUDIO_F32MSB	0x9120  /* As above, but big-endian byte order */
    1.70 +#define AUDIO_F32	AUDIO_F32LSB
    1.71 +
    1.72  /* Native audio byte ordering */
    1.73  #if SDL_BYTEORDER == SDL_LIL_ENDIAN
    1.74  #define AUDIO_U16SYS	AUDIO_U16LSB
    1.75  #define AUDIO_S16SYS	AUDIO_S16LSB
    1.76 +#define AUDIO_S32SYS	AUDIO_S32LSB
    1.77 +#define AUDIO_U32SYS	AUDIO_U32LSB
    1.78 +#define AUDIO_F32SYS	AUDIO_F32LSB
    1.79  #else
    1.80  #define AUDIO_U16SYS	AUDIO_U16MSB
    1.81  #define AUDIO_S16SYS	AUDIO_S16MSB
    1.82 +#define AUDIO_S32SYS	AUDIO_S32MSB
    1.83 +#define AUDIO_U32SYS	AUDIO_U32MSB
    1.84 +#define AUDIO_F32SYS	AUDIO_F32MSB
    1.85  #endif
    1.86  
    1.87  
    1.88 @@ -166,6 +217,43 @@
    1.89                                            SDL_AudioSpec * obtained);
    1.90  
    1.91  /*
    1.92 + * SDL Audio Device IDs.
    1.93 + * A successful call to SDL_OpenAudio() is always device id 1, and legacy
    1.94 + *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
    1.95 + *  always returns devices >= 2 on success. The legacy calls are good both
    1.96 + *  for backwards compatibility and when you don't care about multiple,
    1.97 + *  specific, or capture devices.
    1.98 + */
    1.99 +typedef Uint32 SDL_AudioDeviceID;
   1.100 +
   1.101 +/*
   1.102 + * Get the number of available devices exposed by the current driver.
   1.103 + *  Only valid after a successfully initializing the audio subsystem.
   1.104 + */
   1.105 +extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
   1.106 +
   1.107 +/*
   1.108 + * Get the human-readable name of a specific audio device.
   1.109 + *  Must be a value between 0 and (number of audio devices-1).
   1.110 + *  Only valid after a successfully initializing the audio subsystem.
   1.111 + */
   1.112 +extern DECLSPEC const char *SDLCALL SDL_GetAudioDevice(int index, int iscapture);
   1.113 +
   1.114 +
   1.115 +/*
   1.116 + * Open a specific audio device. Passing in a device name of NULL is
   1.117 + *  equivalent to SDL_OpenAudio(). Returns 0 on error, a valid device ID
   1.118 + *  on success.
   1.119 + */
   1.120 +extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
   1.121 +                                                const char * device,
   1.122 +                                                int iscapture,
   1.123 +                                                const SDL_AudioSpec * desired,
   1.124 +                                                SDL_AudioSpec * obtained);
   1.125 +
   1.126 +
   1.127 +
   1.128 +/*
   1.129   * Get the current audio state:
   1.130   */
   1.131  typedef enum
   1.132 @@ -176,6 +264,9 @@
   1.133  } SDL_audiostatus;
   1.134  extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
   1.135  
   1.136 +extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioDeviceStatus(
   1.137 +                                                        SDL_AudioDeviceID dev);
   1.138 +
   1.139  /*
   1.140   * This function pauses and unpauses the audio callback processing.
   1.141   * It should be called with a parameter of 0 after opening the audio
   1.142 @@ -184,6 +275,8 @@
   1.143   * Silence will be written to the audio device during the pause.
   1.144   */
   1.145  extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   1.146 +extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
   1.147 +                                                  int pause_on);
   1.148  
   1.149  /*
   1.150   * This function loads a WAVE from the data source, automatically freeing
   1.151 @@ -222,7 +315,8 @@
   1.152   * and rate, and initializes the 'cvt' structure with information needed
   1.153   * by SDL_ConvertAudio() to convert a buffer of audio data from one format
   1.154   * to the other.
   1.155 - * This function returns 0, or -1 if there was an error.
   1.156 + * Returns -1 if the format conversion is not supported, 0 if there's
   1.157 + *  no conversion needed, or 1 if the audio filter is set up.
   1.158   */
   1.159  extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
   1.160                                                Uint16 src_format,
   1.161 @@ -254,18 +348,35 @@
   1.162                                            Uint32 len, int volume);
   1.163  
   1.164  /*
   1.165 + * This works like SDL_MixAudio, but you specify the audio format instead of
   1.166 + *  using the format of audio device 1. Thus it can be used when no audio
   1.167 + *  device is open at all.
   1.168 + */
   1.169 +extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, const Uint8 * src,
   1.170 +                                                SDL_AudioFormat format,
   1.171 +                                                Uint32 len, int volume);
   1.172 +
   1.173 +/*
   1.174   * The lock manipulated by these functions protects the callback function.
   1.175   * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
   1.176   * callback function is not running.  Do not call these from the callback
   1.177   * function or you will cause deadlock.
   1.178   */
   1.179  extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   1.180 +extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
   1.181  extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   1.182 +extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
   1.183  
   1.184  /*
   1.185   * This function shuts down audio processing and closes the audio device.
   1.186   */
   1.187  extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
   1.188 +extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
   1.189 +
   1.190 +/*
   1.191 + * Returns 1 if audio device is still functioning, zero if not, -1 on error.
   1.192 + */
   1.193 +extern DECLSPEC int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev);
   1.194  
   1.195  
   1.196  /* Ends C function definitions when using C++ */