mirror
/
SDL
mirror of https://github.com/libsdl-org/SDL.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

SDL_audio.h: Documentation updates.

This commit is contained in:
Ryan C. Gordon 2024-04-25 02:35:48 -04:00
parent 3959765b81
commit 2733345422
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
1 changed files with 188 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

248
include/SDL3/SDL_audio.h
View File

@ -74,59 +74,145 @@ extern "C" {
* There are macros to query these bits. * There are macros to query these bits.
* *
* \since This datatype is available since SDL 3.0.0. * \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_AUDIO_BITSIZE
* \sa SDL_AUDIO_BYTESIZE
* \sa SDL_AUDIO_ISINT
* \sa SDL_AUDIO_ISFLOAT
* \sa SDL_AUDIO_ISBIGENDIAN
* \sa SDL_AUDIO_ISLITTLEENDIAN
* \sa SDL_AUDIO_ISSIGNED
* \sa SDL_AUDIO_ISUNSIGNED
*/ */
typedef Uint16 SDL_AudioFormat; typedef Uint16 SDL_AudioFormat;
#define SDL_AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */
#define SDL_AUDIO_S8 0x8008 /**< Signed 8-bit samples */
#define SDL_AUDIO_S16LE 0x8010 /**< Signed 16-bit samples */
#define SDL_AUDIO_S16BE 0x9010 /**< As above, but big-endian byte order */
#define SDL_AUDIO_S32LE 0x8020 /**< 32-bit integer samples */
#define SDL_AUDIO_S32BE 0x9020 /**< As above, but big-endian byte order */
#define SDL_AUDIO_F32LE 0x8120 /**< 32-bit floating point samples */
#define SDL_AUDIO_F32BE 0x9120 /**< As above, but big-endian byte order */
/**
* \name Audio flags
*/
/* @{ */
#define SDL_AUDIO_MASK_BITSIZE (0xFF) #define SDL_AUDIO_MASK_BITSIZE (0xFF)
#define SDL_AUDIO_MASK_FLOAT (1<<8) #define SDL_AUDIO_MASK_FLOAT (1<<8)
#define SDL_AUDIO_MASK_BIG_ENDIAN (1<<12) #define SDL_AUDIO_MASK_BIG_ENDIAN (1<<12)
#define SDL_AUDIO_MASK_SIGNED (1<<15) #define SDL_AUDIO_MASK_SIGNED (1<<15)
/**
* Retrieve the size, in bits, from an SDL_AudioFormat.
*
* For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
*
* \param x an SDL_AudioFormat value
* \returns data size in bits
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE) #define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE)
/**
* Retrieve the size, in bytes, from an SDL_AudioFormat.
*
* For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
*
* \param x an SDL_AudioFormat value
* \returns data size in bytes
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8) #define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8)
/**
* Determine if an SDL_AudioFormat represents floating point data.
*
* For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
*
* \param x an SDL_AudioFormat value
* \returns non-zero if format is floating point, zero otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT) #define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT)
/**
* Determine if an SDL_AudioFormat represents bigendian data.
*
* For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
*
* \param x an SDL_AudioFormat value
* \returns non-zero if format is bigendian, zero otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN) #define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN)
/**
* Determine if an SDL_AudioFormat represents littleendian data.
*
* For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
*
* \param x an SDL_AudioFormat value
* \returns non-zero if format is littleendian, zero otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
/**
* Determine if an SDL_AudioFormat represents signed data.
*
* For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
*
* \param x an SDL_AudioFormat value
* \returns non-zero if format is signed, zero otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED) #define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED)
/**
* Determine if an SDL_AudioFormat represents integer data.
*
* For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
*
* \param x an SDL_AudioFormat value
* \returns non-zero if format is integer, zero otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
/**
* Determine if an SDL_AudioFormat represents unsigned data.
*
* For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
*
* \param x an SDL_AudioFormat value
* \returns non-zero if format is unsigned, zero otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
/**
* \name Audio format flags
*
* Defaults to LSB byte order.
*/
/* @{ */
#define SDL_AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */
#define SDL_AUDIO_S8 0x8008 /**< Signed 8-bit samples */
#define SDL_AUDIO_S16LE 0x8010 /**< Signed 16-bit samples */
#define SDL_AUDIO_S16BE 0x9010 /**< As above, but big-endian byte order */
/* @} */
/**
* \name int32 support
*/
/* @{ */
#define SDL_AUDIO_S32LE 0x8020 /**< 32-bit integer samples */
#define SDL_AUDIO_S32BE 0x9020 /**< As above, but big-endian byte order */
/* @} */
/**
* \name float32 support
*/
/* @{ */
#define SDL_AUDIO_F32LE 0x8120 /**< 32-bit floating point samples */
#define SDL_AUDIO_F32BE 0x9120 /**< As above, but big-endian byte order */
/* @} */
/**
* \name Native audio byte ordering
*/
/* @{ */
#if SDL_BYTEORDER == SDL_LIL_ENDIAN #if SDL_BYTEORDER == SDL_LIL_ENDIAN
#define SDL_AUDIO_S16 SDL_AUDIO_S16LE #define SDL_AUDIO_S16 SDL_AUDIO_S16LE
#define SDL_AUDIO_S32 SDL_AUDIO_S32LE #define SDL_AUDIO_S32 SDL_AUDIO_S32LE
@ -136,18 +222,36 @@ typedef Uint16 SDL_AudioFormat;
#define SDL_AUDIO_S32 SDL_AUDIO_S32BE #define SDL_AUDIO_S32 SDL_AUDIO_S32BE
#define SDL_AUDIO_F32 SDL_AUDIO_F32BE #define SDL_AUDIO_F32 SDL_AUDIO_F32BE
#endif #endif
/* @} */
/* @} *//* Audio flags */
/** /**
* SDL Audio Device instance IDs. * SDL Audio Device instance IDs.
* *
* Zero is used to signify an invalid/null device.
*
* \since This datatype is available since SDL 3.0.0. * \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint32 SDL_AudioDeviceID; typedef Uint32 SDL_AudioDeviceID;
/**
* A value used to request a default output audio device.
*
* Several functions that require an SDL_AudioDeviceID will accept this
* value to signify the app just wants the system to choose a default
* device instead of the app providing a specific one.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_DEVICE_DEFAULT_OUTPUT ((SDL_AudioDeviceID) 0xFFFFFFFF) #define SDL_AUDIO_DEVICE_DEFAULT_OUTPUT ((SDL_AudioDeviceID) 0xFFFFFFFF)
/**
* A value used to request a default capture audio device.
*
* Several functions that require an SDL_AudioDeviceID will accept this
* value to signify the app just wants the system to choose a default
* device instead of the app providing a specific one.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_DEVICE_DEFAULT_CAPTURE ((SDL_AudioDeviceID) 0xFFFFFFFE) #define SDL_AUDIO_DEVICE_DEFAULT_CAPTURE ((SDL_AudioDeviceID) 0xFFFFFFFE)
/** /**
@ -164,7 +268,19 @@ typedef struct SDL_AudioSpec
int freq; /**< sample rate: sample frames per second */ int freq; /**< sample rate: sample frames per second */
} SDL_AudioSpec; } SDL_AudioSpec;
/* Calculate the size of each audio frame (in bytes) */ /**
* Calculate the size of each audio frame (in bytes) from an SDL_AudioSpec.
*
* This reports on the size of an audio sample frame: stereo Sint16 data
* (2 channels of 2 bytes each) would be 4 bytes per frame, for example.
*
* \param x an SDL_AudioSpec to query.
* \returns the number of bytes used per sample frame.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)
/** /**
@ -615,7 +731,7 @@ extern DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_Aud
* *
* The streams being unbound do not all have to be on the same device. All * The streams being unbound do not all have to be on the same device. All
* streams on the same device will be unbound atomically (data will stop * streams on the same device will be unbound atomically (data will stop
* flowing through them all unbound streams on the same device at the same * flowing through all unbound streams on the same device at the same
* time). * time).
* *
* Unbinding a stream that isn't bound to a device is a legal no-op. * Unbinding a stream that isn't bound to a device is a legal no-op.
@ -667,7 +783,6 @@ extern DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
*/ */
extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStream *stream); extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStream *stream);
/** /**
* Create a new audio stream. * Create a new audio stream.
* *
@ -727,6 +842,13 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream,
* will reflect the new format, and future calls to SDL_PutAudioStreamData * will reflect the new format, and future calls to SDL_PutAudioStreamData
* must provide data in the new input formats. * must provide data in the new input formats.
* *
* Data that was previously queued in the stream will still be
* operated on in the format that was current when it was added, which is
* to say you can put the end of a sound file in one format to a stream,
* change formats for the next sound file, and start putting that new data
* while the previous sound file is still queued, and everything will still
* play back correctly.
*
* \param stream The stream the format is being changed * \param stream The stream the format is being changed
* \param src_spec The new format of the audio input; if NULL, it is not * \param src_spec The new format of the audio input; if NULL, it is not
* changed. * changed.
@ -909,7 +1031,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream);
* Tell the stream that you're done sending data, and anything being buffered * Tell the stream that you're done sending data, and anything being buffered
* should be converted/resampled and made available immediately. * should be converted/resampled and made available immediately.
* *
* It is legal to add more data to a stream after flushing, but there will be * It is legal to add more data to a stream after flushing, but there may be
* audio gaps in the output. Generally this is intended to signal the end of * audio gaps in the output. Generally this is intended to signal the end of
* input, so the complete output becomes available. * input, so the complete output becomes available.
* *
@ -926,7 +1048,10 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream);
extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
/** /**
* Clear any pending data in the stream without converting it. * Clear any pending data in the stream.
*
* This drops any queued data, so there will be nothing to read from
* the stream until more is added.
* *
* \param stream The audio stream to clear * \param stream The audio stream to clear
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
@ -956,7 +1081,7 @@ extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
* protect shared data during those callbacks, locking the stream guarantees * protect shared data during those callbacks, locking the stream guarantees
* that the callback is not running while the lock is held. * that the callback is not running while the lock is held.
* *
* As this is just a wrapper over SDL_LockMutex for an internal lock, it has * As this is just a wrapper over SDL_LockMutex for an internal lock; it has
* all the same attributes (recursive locks are allowed, etc). * all the same attributes (recursive locks are allowed, etc).
* *
* \param stream The audio stream to lock. * \param stream The audio stream to lock.
@ -1129,7 +1254,15 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *strea
/** /**
* Free an audio stream. * Free an audio stream.
* *
* \param stream The audio stream to free * This will release all allocated data, including any audio that is still
* queued. You do not need to manually clear the stream first.
*
* If this stream was bound to an audio device, it is unbound during this
* call. If this stream was created with SDL_OpenAudioDeviceStream, the
* audio device that was opened alongside this stream's creation will be
* closed, too.
*
* \param stream The audio stream to destroy.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -1146,7 +1279,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
* If all your app intends to do is provide a single source of PCM audio, this * If all your app intends to do is provide a single source of PCM audio, this
* function allows you to do all your audio setup in a single call. * function allows you to do all your audio setup in a single call.
* *
* This is intended to be a clean means to migrate apps from SDL2. * This is also intended to be a clean means to migrate apps from SDL2.
* *
* This function will open an audio device, create a stream and bind it. * This function will open an audio device, create a stream and bind it.
* Unlike other methods of setup, the audio device will be closed when this * Unlike other methods of setup, the audio device will be closed when this
@ -1154,9 +1287,9 @@ extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
* the only object needed to manage audio playback. * the only object needed to manage audio playback.
* *
* Also unlike other functions, the audio device begins paused. This is to map * Also unlike other functions, the audio device begins paused. This is to map
* more closely to SDL2-style behavior, and since there is no extra step here * more closely to SDL2-style behavior, since there is no extra step here
* to bind a stream to begin audio flowing. The audio device should be resumed * to bind a stream to begin audio flowing. The audio device should be resumed
* with SDL_ResumeAudioDevice(SDL_GetAudioStreamDevice(stream)); * with `SDL_ResumeAudioDevice(SDL_GetAudioStreamDevice(stream));`
* *
* This function works with both playback and capture devices. * This function works with both playback and capture devices.
* *
@ -1196,7 +1329,6 @@ extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
*/ */
extern DECLSPEC SDL_AudioStream *SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata); extern DECLSPEC SDL_AudioStream *SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata);
/** /**
* A callback that fires when data is about to be fed to an audio device. * A callback that fires when data is about to be fed to an audio device.
* *
@ -1345,10 +1477,9 @@ extern DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid,
* function * function
* \param audio_len A pointer filled with the length of the audio data buffer * \param audio_len A pointer filled with the length of the audio data buffer
* in bytes * in bytes
* \returns This function, if successfully called, returns 0. `audio_buf` will * \returns 0 on success. `audio_buf` will be filled with a pointer to an
* be filled with a pointer to an allocated buffer containing the * allocated buffer containing the audio data, and `audio_len` is
* audio data, and `audio_len` is filled with the length of that * filled with the length of that audio buffer in bytes.
* audio buffer in bytes.
* *
* This function returns -1 if the .WAV file cannot be opened, uses * This function returns -1 if the .WAV file cannot be opened, uses
* an unknown data format, or is corrupt; call SDL_GetError() for * an unknown data format, or is corrupt; call SDL_GetError() for
@ -1377,8 +1508,6 @@ extern DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool closeio,
* SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len); * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
* ``` * ```
* *
* Note that in SDL2, this was a preprocessor macro and not a real function.
*
* \param path The file path of the WAV file to open. * \param path The file path of the WAV file to open.
* \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
* data's format details on successful return. * data's format details on successful return.
@ -1386,10 +1515,9 @@ extern DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool closeio,
* function. * function.
* \param audio_len A pointer filled with the length of the audio data buffer * \param audio_len A pointer filled with the length of the audio data buffer
* in bytes * in bytes
* \returns This function, if successfully called, returns 0. `audio_buf` will * \returns 0 on success. `audio_buf` will be filled with a pointer to an
* be filled with a pointer to an allocated buffer containing the * allocated buffer containing the audio data, and `audio_len` is
* audio data, and `audio_len` is filled with the length of that * filled with the length of that audio buffer in bytes.
* audio buffer in bytes.
* *
* This function returns -1 if the .WAV file cannot be opened, uses * This function returns -1 if the .WAV file cannot be opened, uses
* an unknown data format, or is corrupt; call SDL_GetError() for * an unknown data format, or is corrupt; call SDL_GetError() for