include/SDL_audio.h
changeset 7678 286c42d7c5ed
parent 7677 871d43c6968a
child 8149 681eb46b8ac4
equal deleted inserted replaced
7677:871d43c6968a 7678:286c42d7c5ed
    64 typedef Uint16 SDL_AudioFormat;
    64 typedef Uint16 SDL_AudioFormat;
    65 
    65 
    66 /**
    66 /**
    67  *  \name Audio flags
    67  *  \name Audio flags
    68  */
    68  */
    69 /*@{ */
    69 /* @{ */
    70 
    70 
    71 #define SDL_AUDIO_MASK_BITSIZE       (0xFF)
    71 #define SDL_AUDIO_MASK_BITSIZE       (0xFF)
    72 #define SDL_AUDIO_MASK_DATATYPE      (1<<8)
    72 #define SDL_AUDIO_MASK_DATATYPE      (1<<8)
    73 #define SDL_AUDIO_MASK_ENDIAN        (1<<12)
    73 #define SDL_AUDIO_MASK_ENDIAN        (1<<12)
    74 #define SDL_AUDIO_MASK_SIGNED        (1<<15)
    74 #define SDL_AUDIO_MASK_SIGNED        (1<<15)
    83 /**
    83 /**
    84  *  \name Audio format flags
    84  *  \name Audio format flags
    85  *
    85  *
    86  *  Defaults to LSB byte order.
    86  *  Defaults to LSB byte order.
    87  */
    87  */
    88 /*@{ */
    88 /* @{ */
    89 #define AUDIO_U8        0x0008  /**< Unsigned 8-bit samples */
    89 #define AUDIO_U8        0x0008  /**< Unsigned 8-bit samples */
    90 #define AUDIO_S8        0x8008  /**< Signed 8-bit samples */
    90 #define AUDIO_S8        0x8008  /**< Signed 8-bit samples */
    91 #define AUDIO_U16LSB    0x0010  /**< Unsigned 16-bit samples */
    91 #define AUDIO_U16LSB    0x0010  /**< Unsigned 16-bit samples */
    92 #define AUDIO_S16LSB    0x8010  /**< Signed 16-bit samples */
    92 #define AUDIO_S16LSB    0x8010  /**< Signed 16-bit samples */
    93 #define AUDIO_U16MSB    0x1010  /**< As above, but big-endian byte order */
    93 #define AUDIO_U16MSB    0x1010  /**< As above, but big-endian byte order */
    94 #define AUDIO_S16MSB    0x9010  /**< As above, but big-endian byte order */
    94 #define AUDIO_S16MSB    0x9010  /**< As above, but big-endian byte order */
    95 #define AUDIO_U16       AUDIO_U16LSB
    95 #define AUDIO_U16       AUDIO_U16LSB
    96 #define AUDIO_S16       AUDIO_S16LSB
    96 #define AUDIO_S16       AUDIO_S16LSB
    97 /*@} */
    97 /* @} */
    98 
    98 
    99 /**
    99 /**
   100  *  \name int32 support
   100  *  \name int32 support
   101  */
   101  */
   102 /*@{ */
   102 /* @{ */
   103 #define AUDIO_S32LSB    0x8020  /**< 32-bit integer samples */
   103 #define AUDIO_S32LSB    0x8020  /**< 32-bit integer samples */
   104 #define AUDIO_S32MSB    0x9020  /**< As above, but big-endian byte order */
   104 #define AUDIO_S32MSB    0x9020  /**< As above, but big-endian byte order */
   105 #define AUDIO_S32       AUDIO_S32LSB
   105 #define AUDIO_S32       AUDIO_S32LSB
   106 /*@} */
   106 /* @} */
   107 
   107 
   108 /**
   108 /**
   109  *  \name float32 support
   109  *  \name float32 support
   110  */
   110  */
   111 /*@{ */
   111 /* @{ */
   112 #define AUDIO_F32LSB    0x8120  /**< 32-bit floating point samples */
   112 #define AUDIO_F32LSB    0x8120  /**< 32-bit floating point samples */
   113 #define AUDIO_F32MSB    0x9120  /**< As above, but big-endian byte order */
   113 #define AUDIO_F32MSB    0x9120  /**< As above, but big-endian byte order */
   114 #define AUDIO_F32       AUDIO_F32LSB
   114 #define AUDIO_F32       AUDIO_F32LSB
   115 /*@} */
   115 /* @} */
   116 
   116 
   117 /**
   117 /**
   118  *  \name Native audio byte ordering
   118  *  \name Native audio byte ordering
   119  */
   119  */
   120 /*@{ */
   120 /* @{ */
   121 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
   121 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
   122 #define AUDIO_U16SYS    AUDIO_U16LSB
   122 #define AUDIO_U16SYS    AUDIO_U16LSB
   123 #define AUDIO_S16SYS    AUDIO_S16LSB
   123 #define AUDIO_S16SYS    AUDIO_S16LSB
   124 #define AUDIO_S32SYS    AUDIO_S32LSB
   124 #define AUDIO_S32SYS    AUDIO_S32LSB
   125 #define AUDIO_F32SYS    AUDIO_F32LSB
   125 #define AUDIO_F32SYS    AUDIO_F32LSB
   127 #define AUDIO_U16SYS    AUDIO_U16MSB
   127 #define AUDIO_U16SYS    AUDIO_U16MSB
   128 #define AUDIO_S16SYS    AUDIO_S16MSB
   128 #define AUDIO_S16SYS    AUDIO_S16MSB
   129 #define AUDIO_S32SYS    AUDIO_S32MSB
   129 #define AUDIO_S32SYS    AUDIO_S32MSB
   130 #define AUDIO_F32SYS    AUDIO_F32MSB
   130 #define AUDIO_F32SYS    AUDIO_F32MSB
   131 #endif
   131 #endif
   132 /*@} */
   132 /* @} */
   133 
   133 
   134 /**
   134 /**
   135  *  \name Allow change flags
   135  *  \name Allow change flags
   136  *
   136  *
   137  *  Which audio format changes are allowed when opening a device.
   137  *  Which audio format changes are allowed when opening a device.
   138  */
   138  */
   139 /*@{ */
   139 /* @{ */
   140 #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
   140 #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
   141 #define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
   141 #define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
   142 #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
   142 #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
   143 #define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE)
   143 #define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE)
   144 /*@} */
   144 /* @} */
   145 
   145 
   146 /*@} *//*Audio flags */
   146 /* @} *//* Audio flags */
   147 
   147 
   148 /**
   148 /**
   149  *  This function is called when the audio device needs more data.
   149  *  This function is called when the audio device needs more data.
   150  *
   150  *
   151  *  \param userdata An application-specific parameter saved in
   151  *  \param userdata An application-specific parameter saved in
   216  *  \name Driver discovery functions
   216  *  \name Driver discovery functions
   217  *
   217  *
   218  *  These functions return the list of built in audio drivers, in the
   218  *  These functions return the list of built in audio drivers, in the
   219  *  order that they are normally initialized by default.
   219  *  order that they are normally initialized by default.
   220  */
   220  */
   221 /*@{ */
   221 /* @{ */
   222 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
   222 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
   223 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
   223 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
   224 /*@} */
   224 /* @} */
   225 
   225 
   226 /**
   226 /**
   227  *  \name Initialization and cleanup
   227  *  \name Initialization and cleanup
   228  *
   228  *
   229  *  \internal These functions are used internally, and should not be used unless
   229  *  \internal These functions are used internally, and should not be used unless
   230  *            you have a specific need to specify the audio driver you want to
   230  *            you have a specific need to specify the audio driver you want to
   231  *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
   231  *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
   232  */
   232  */
   233 /*@{ */
   233 /* @{ */
   234 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
   234 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
   235 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
   235 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
   236 /*@} */
   236 /* @} */
   237 
   237 
   238 /**
   238 /**
   239  *  This function returns the name of the current audio driver, or NULL
   239  *  This function returns the name of the current audio driver, or NULL
   240  *  if no driver has been initialized.
   240  *  if no driver has been initialized.
   241  */
   241  */
   357 /**
   357 /**
   358  *  \name Audio state
   358  *  \name Audio state
   359  *
   359  *
   360  *  Get the current audio state.
   360  *  Get the current audio state.
   361  */
   361  */
   362 /*@{ */
   362 /* @{ */
   363 typedef enum
   363 typedef enum
   364 {
   364 {
   365     SDL_AUDIO_STOPPED = 0,
   365     SDL_AUDIO_STOPPED = 0,
   366     SDL_AUDIO_PLAYING,
   366     SDL_AUDIO_PLAYING,
   367     SDL_AUDIO_PAUSED
   367     SDL_AUDIO_PAUSED
   368 } SDL_AudioStatus;
   368 } SDL_AudioStatus;
   369 extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
   369 extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
   370 
   370 
   371 extern DECLSPEC SDL_AudioStatus SDLCALL
   371 extern DECLSPEC SDL_AudioStatus SDLCALL
   372 SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
   372 SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
   373 /*@} *//*Audio State */
   373 /* @} *//* Audio State */
   374 
   374 
   375 /**
   375 /**
   376  *  \name Pause audio functions
   376  *  \name Pause audio functions
   377  *
   377  *
   378  *  These functions pause and unpause the audio callback processing.
   378  *  These functions pause and unpause the audio callback processing.
   379  *  They should be called with a parameter of 0 after opening the audio
   379  *  They should be called with a parameter of 0 after opening the audio
   380  *  device to start playing sound.  This is so you can safely initialize
   380  *  device to start playing sound.  This is so you can safely initialize
   381  *  data for your callback function after opening the audio device.
   381  *  data for your callback function after opening the audio device.
   382  *  Silence will be written to the audio device during the pause.
   382  *  Silence will be written to the audio device during the pause.
   383  */
   383  */
   384 /*@{ */
   384 /* @{ */
   385 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   385 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
   386 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
   386 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
   387                                                   int pause_on);
   387                                                   int pause_on);
   388 /*@} *//*Pause audio functions */
   388 /* @} *//* Pause audio functions */
   389 
   389 
   390 /**
   390 /**
   391  *  This function loads a WAVE from the data source, automatically freeing
   391  *  This function loads a WAVE from the data source, automatically freeing
   392  *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
   392  *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
   393  *  you could do:
   393  *  you could do:
   480  *  The lock manipulated by these functions protects the callback function.
   480  *  The lock manipulated by these functions protects the callback function.
   481  *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
   481  *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
   482  *  the callback function is not running.  Do not call these from the callback
   482  *  the callback function is not running.  Do not call these from the callback
   483  *  function or you will cause deadlock.
   483  *  function or you will cause deadlock.
   484  */
   484  */
   485 /*@{ */
   485 /* @{ */
   486 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   486 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
   487 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
   487 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
   488 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   488 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
   489 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
   489 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
   490 /*@} *//*Audio lock functions */
   490 /* @} *//* Audio lock functions */
   491 
   491 
   492 /**
   492 /**
   493  *  This function shuts down audio processing and closes the audio device.
   493  *  This function shuts down audio processing and closes the audio device.
   494  */
   494  */
   495 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
   495 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);