Sync SDL3 wiki -> header

main
SDL Wiki Bot 2023-08-04 01:28:15 +00:00
parent 18c59cc969
commit c0a88930bf
1 changed files with 182 additions and 174 deletions

View File

@ -248,18 +248,18 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
/**
* Get a list of currently-connected audio output devices.
*
* This returns of list of available devices that play sound, perhaps
* to speakers or headphones ("output" devices). If you want devices
* that record audio, like a microphone ("capture" devices), use
* This returns of list of available devices that play sound, perhaps to
* speakers or headphones ("output" devices). If you want devices that record
* audio, like a microphone ("capture" devices), use
* SDL_GetAudioCaptureDevices() instead.
*
* This only returns a list of physical devices; it will not have any
* device IDs returned by SDL_OpenAudioDevice().
* This only returns a list of physical devices; it will not have any device
* IDs returned by SDL_OpenAudioDevice().
*
* \param count a pointer filled in with the number of devices returned
* \returns a 0 terminated array of device instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* \returns a 0 terminated array of device instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -274,17 +274,17 @@ extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioOutputDevices(int *count)
* Get a list of currently-connected audio capture devices.
*
* This returns of list of available devices that record audio, like a
* microphone ("capture" devices). If you want devices
* that play sound, perhaps to speakers or headphones ("output" devices),
* use SDL_GetAudioOutputDevices() instead.
* microphone ("capture" devices). If you want devices that play sound,
* perhaps to speakers or headphones ("output" devices), use
* SDL_GetAudioOutputDevices() instead.
*
* This only returns a list of physical devices; it will not have any
* device IDs returned by SDL_OpenAudioDevice().
* This only returns a list of physical devices; it will not have any device
* IDs returned by SDL_OpenAudioDevice().
*
* \param count a pointer filled in with the number of devices returned
* \returns a 0 terminated array of device instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* \returns a 0 terminated array of device instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -316,15 +316,14 @@ extern DECLSPEC char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
/**
* Get the current audio format of a specific audio device.
*
* For an opened device, this will report the format the device is
* currently using. If the device isn't yet opened, this will report
* the device's preferred format (or a reasonable default if this
* can't be determined).
* For an opened device, this will report the format the device is currently
* using. If the device isn't yet opened, this will report the device's
* preferred format (or a reasonable default if this can't be determined).
*
* You may also specify SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
* SDL_AUDIO_DEVICE_DEFAULT_CAPTURE here, which is useful for getting
* a reasonable recommendation before opening the system-recommended
* default device.
* SDL_AUDIO_DEVICE_DEFAULT_CAPTURE here, which is useful for getting a
* reasonable recommendation before opening the system-recommended default
* device.
*
* \param devid the instance ID of the device to query.
* \param spec On return, will be filled with device details.
@ -341,67 +340,68 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SD
/**
* Open a specific audio device.
*
* You can open both output and capture devices through this function.
* Output devices will take data from bound audio streams, mix it, and
* send it to the hardware. Capture devices will feed any bound audio
* streams with a copy of any incoming data.
* You can open both output and capture devices through this function. Output
* devices will take data from bound audio streams, mix it, and send it to the
* hardware. Capture devices will feed any bound audio streams with a copy of
* any incoming data.
*
* An opened audio device starts out with no audio streams bound. To
* start audio playing, bind a stream and supply audio data to it. Unlike
* SDL2, there is no audio callback; you only bind audio streams and
* make sure they have data flowing into them (although, as an optional
* feature, each audio stream may have its own callback, which can be
* used to simulate SDL2's semantics).
* An opened audio device starts out with no audio streams bound. To start
* audio playing, bind a stream and supply audio data to it. Unlike SDL2,
* there is no audio callback; you only bind audio streams and make sure they
* have data flowing into them (although, as an optional feature, each audio
* stream may have its own callback, which can be used to simulate SDL2's
* semantics).
*
* If you don't care about opening a specific device, pass a `devid`
* of either `SDL_AUDIO_DEVICE_DEFAULT_OUTPUT` or
* `SDL_AUDIO_DEVICE_DEFAULT_CAPTURE`. In this case, SDL will try to
* pick the most reasonable default, and may also switch between
* physical devices seamlessly later, if the most reasonable default
* changes during the lifetime of this opened device (user changed
* the default in the OS's system preferences, the default got
* unplugged so the system jumped to a new default, the user plugged
* in headphones on a mobile device, etc). Unless you have a good
* reason to choose a specific device, this is probably what you want.
* If you don't care about opening a specific device, pass a `devid` of either
* `SDL_AUDIO_DEVICE_DEFAULT_OUTPUT` or `SDL_AUDIO_DEVICE_DEFAULT_CAPTURE`. In
* this case, SDL will try to pick the most reasonable default, and may also
* switch between physical devices seamlessly later, if the most reasonable
* default changes during the lifetime of this opened device (user changed the
* default in the OS's system preferences, the default got unplugged so the
* system jumped to a new default, the user plugged in headphones on a mobile
* device, etc). Unless you have a good reason to choose a specific device,
* this is probably what you want.
*
* You may request a specific format for the audio device, but there is
* no promise the device will honor that request for several reasons. As
* such, it's only meant to be a hint as to what data your app will
* provide. Audio streams will accept data in whatever format you specify and
* manage conversion for you as appropriate. SDL_GetAudioDeviceFormat can
* tell you the preferred format for the device before opening and the
* actual format the device is using after opening.
* You may request a specific format for the audio device, but there is no
* promise the device will honor that request for several reasons. As such,
* it's only meant to be a hint as to what data your app will provide. Audio
* streams will accept data in whatever format you specify and manage
* conversion for you as appropriate. SDL_GetAudioDeviceFormat can tell you
* the preferred format for the device before opening and the actual format
* the device is using after opening.
*
* It's legal to open the same device ID more than once; each successful
* open will generate a new logical SDL_AudioDeviceID that is managed
* separately from others on the same physical device. This allows
* libraries to open a device separately from the main app and bind its own
* streams without conflicting.
* It's legal to open the same device ID more than once; each successful open
* will generate a new logical SDL_AudioDeviceID that is managed separately
* from others on the same physical device. This allows libraries to open a
* device separately from the main app and bind its own streams without
* conflicting.
*
* It is also legal to open a device ID returned by a previous call to
* this function; doing so just creates another logical device on the same
* physical device. This may be useful for making logical groupings of
* audio streams.
* It is also legal to open a device ID returned by a previous call to this
* function; doing so just creates another logical device on the same physical
* device. This may be useful for making logical groupings of audio streams.
*
* This function returns the opened device ID on success. This is a new,
* unique SDL_AudioDeviceID that represents a logical device.
*
* Some backends might offer arbitrary devices (for example, a networked
* audio protocol that can connect to an arbitrary server). For these, as
* a change from SDL2, you should open a default device ID and use an SDL
* hint to specify the target if you care, or otherwise let the backend
* figure out a reasonable default. Most backends don't offer anything like
* this, and often this would be an end user setting an environment
* variable for their custom need, and not something an application should
* specifically manage.
* Some backends might offer arbitrary devices (for example, a networked audio
* protocol that can connect to an arbitrary server). For these, as a change
* from SDL2, you should open a default device ID and use an SDL hint to
* specify the target if you care, or otherwise let the backend figure out a
* reasonable default. Most backends don't offer anything like this, and often
* this would be an end user setting an environment variable for their custom
* need, and not something an application should specifically manage.
*
* When done with an audio device, possibly at the end of the app's life,
* one should call SDL_CloseAudioDevice() on the returned device id.
* When done with an audio device, possibly at the end of the app's life, one
* should call SDL_CloseAudioDevice() on the returned device id.
*
* \param devid the device instance id to open, or SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
* SDL_AUDIO_DEVICE_DEFAULT_CAPTURE for the most reasonable default device.
* \param spec the requested device configuration. Can be NULL to use reasonable defaults.
* \returns The device ID on success, 0 on error; call SDL_GetError() for more information.
* \param devid the device instance id to open, or
* SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
* SDL_AUDIO_DEVICE_DEFAULT_CAPTURE for the most reasonable
* default device.
* \param spec the requested device configuration. Can be NULL to use
* reasonable defaults.
* \returns The device ID on success, 0 on error; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -415,17 +415,17 @@ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID
/**
* Use this function to pause audio playback on a specified device.
*
* This function pauses audio processing for a given device. Any bound
* audio streams will not progress, and no audio will be generated.
* Pausing one device does not prevent other unpaused devices from running.
* This function pauses audio processing for a given device. Any bound audio
* streams will not progress, and no audio will be generated. Pausing one
* device does not prevent other unpaused devices from running.
*
* Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
* has to bind a stream before any audio will flow. Pausing a paused
* device is a legal no-op.
* has to bind a stream before any audio will flow. Pausing a paused device is
* a legal no-op.
*
* Pausing a device can be useful to halt all audio without unbinding all
* the audio streams. This might be useful while a game is paused, or
* a level is loading, etc.
* Pausing a device can be useful to halt all audio without unbinding all the
* audio streams. This might be useful while a game is paused, or a level is
* loading, etc.
*
* Physical devices can not be paused or unpaused, only logical devices
* created through SDL_OpenAudioDevice() can be.
@ -478,8 +478,8 @@ extern DECLSPEC int SDLCALL SDL_UnpauseAudioDevice(SDL_AudioDeviceID dev);
* has to bind a stream before any audio will flow.
*
* Physical devices can not be paused or unpaused, only logical devices
* created through SDL_OpenAudioDevice() can be. Physical and invalid
* device IDs will report themselves as unpaused here.
* created through SDL_OpenAudioDevice() can be. Physical and invalid device
* IDs will report themselves as unpaused here.
*
* \param dev a device opened by SDL_OpenAudioDevice()
* \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise.
@ -504,7 +504,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsAudioDevicePaused(SDL_AudioDeviceID dev);
* hardware, so that applications don't drop the last buffer of data they
* supplied if terminating immediately afterwards.
*
* \param devid an audio device id previously returned by SDL_OpenAudioDevice()
* \param devid an audio device id previously returned by
* SDL_OpenAudioDevice()
*
* \threadsafety It is safe to call this function from any thread.
*
@ -523,12 +524,12 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
* stream.
*
* Audio streams can only be bound to an open device. This operation is
* atomic--all streams bound in the same call will start processing at the same
* time, so they can stay in sync. Also: either all streams will be bound or
* none of them will be.
* atomic--all streams bound in the same call will start processing at the
* same time, so they can stay in sync. Also: either all streams will be bound
* or none of them will be.
*
* It is an error to bind an already-bound stream; it must be explicitly unbound
* first.
* It is an error to bind an already-bound stream; it must be explicitly
* unbound first.
*
* Binding a stream to a device will set its output format for output devices,
* and its input format for capture devices, so they match the device's
@ -538,7 +539,8 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
* \param devid an audio device to bind a stream to.
* \param streams an array of audio streams to unbind.
* \param num_streams Number streams listed in the `streams` array.
* \returns 0 on success, -1 on error; call SDL_GetError() for more information.
* \returns 0 on success, -1 on error; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -559,7 +561,8 @@ extern DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_Au
*
* \param devid an audio device to bind a stream to.
* \param stream an audio stream to bind to a device.
* \returns 0 on success, -1 on error; call SDL_GetError() for more information.
* \returns 0 on success, -1 on error; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -575,9 +578,10 @@ extern DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_Aud
/**
* Unbind a list of audio streams from their audio devices.
*
* 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 flowing
* through them all unbound streams on the same device at the same time).
* 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
* flowing through them all unbound streams on the same device at the same
* time).
*
* Unbinding a stream that isn't bound to a device is a legal no-op.
*
@ -619,7 +623,8 @@ extern DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
*
* This reports the audio device that an audio stream is currently bound to.
*
* If not bound, or invalid, this returns zero, which is not a valid device ID.
* If not bound, or invalid, this returns zero, which is not a valid device
* ID.
*
* \param stream the audio stream to query.
* \returns The bound audio device, or 0 if not bound or invalid.
@ -683,8 +688,10 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream,
* must provide data in the new input formats.
*
* \param stream The stream the format is being changed
* \param src_spec The new format of the audio input; if NULL, it is not changed.
* \param dst_spec The new format of the audio output; if NULL, it is not changed.
* \param src_spec The new format of the audio input; if NULL, it is not
* changed.
* \param dst_spec The new format of the audio output; if NULL, it is not
* changed.
* \returns 0 on success, or -1 on error.
*
* \threadsafety It is safe to call this function from any thread, as it holds
@ -843,21 +850,18 @@ extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
/**
* Lock an audio stream for serialized access.
*
* Each SDL_AudioStream has an internal mutex it uses to
* protect its data structures from threading conflicts. This function
* allows an app to lock that mutex, which could be useful if
* registering callbacks on this stream.
* Each SDL_AudioStream has an internal mutex it uses to protect its data
* structures from threading conflicts. This function allows an app to lock
* that mutex, which could be useful if registering callbacks on this stream.
*
* One does not need to lock a stream to use in it most cases,
* as the stream manages this lock internally. However, this lock
* is held during callbacks, which may run from arbitrary threads
* at any time, so if an app needs to protect shared data during
* those callbacks, locking the stream guarantees that the
* callback is not running while the lock is held.
* One does not need to lock a stream to use in it most cases, as the stream
* manages this lock internally. However, this lock is held during callbacks,
* which may run from arbitrary threads at any time, so if an app needs to
* protect shared data during those callbacks, locking the stream guarantees
* 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 all the same attributes (recursive locks are
* allowed, etc).
* As this is just a wrapper over SDL_LockMutex for an internal lock, it has
* all the same attributes (recursive locks are allowed, etc).
*
* \param stream The audio stream to lock.
* \returns 0 on success or a negative error code on failure; call
@ -916,37 +920,38 @@ typedef void (SDLCALL *SDL_AudioStreamRequestCallback)(SDL_AudioStream *stream,
/**
* Set a callback that runs when data is requested from an audio stream.
*
* This callback is called _before_ data is obtained from the stream,
* giving the callback the chance to add more on-demand.
* This callback is called _before_ data is obtained from the stream, giving
* the callback the chance to add more on-demand.
*
* The callback can (optionally) call SDL_PutAudioStreamData() to add
* more audio to the stream during this call; if needed, the request
* that triggered this callback will obtain the new data immediately.
* The callback can (optionally) call SDL_PutAudioStreamData() to add more
* audio to the stream during this call; if needed, the request that triggered
* this callback will obtain the new data immediately.
*
* The callback's `approx_request` argument is roughly how many bytes
* of _unconverted_ data (in the stream's input format) is needed by
* the caller, although this may overestimate a little for safety.
* This takes into account how much is already in the stream and only
* asks for any extra necessary to resolve the request, which means
* the callback may be asked for zero bytes, and a different amount
* on each call.
* The callback's `approx_request` argument is roughly how many bytes of
* _unconverted_ data (in the stream's input format) is needed by the caller,
* although this may overestimate a little for safety. This takes into account
* how much is already in the stream and only asks for any extra necessary to
* resolve the request, which means the callback may be asked for zero bytes,
* and a different amount on each call.
*
* The callback is not required to supply exact amounts; it is allowed
* to supply too much or too little or none at all. The caller will
* get what's available, up to the amount they requested, regardless
* of this callback's outcome.
* The callback is not required to supply exact amounts; it is allowed to
* supply too much or too little or none at all. The caller will get what's
* available, up to the amount they requested, regardless of this callback's
* outcome.
*
* Clearing or flushing an audio stream does not call this callback.
*
* This function obtains the stream's lock, which means any existing
* callback (get or put) in progress will finish running before setting
* the new callback.
* This function obtains the stream's lock, which means any existing callback
* (get or put) in progress will finish running before setting the new
* callback.
*
* Setting a NULL function turns off the callback.
*
* \param stream the audio stream to set the new callback on.
* \param callback the new callback function to call when data is added to the stream.
* \param userdata an opaque pointer provided to the callback for its own personal use.
* \param callback the new callback function to call when data is added to the
* stream.
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
* \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
*
* \threadsafety It is safe to call this function from any thread.
@ -960,40 +965,41 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *strea
/**
* Set a callback that runs when data is added to an audio stream.
*
* This callback is called _after_ the data is added to the stream,
* giving the callback the chance to obtain it immediately.
* This callback is called _after_ the data is added to the stream, giving the
* callback the chance to obtain it immediately.
*
* The callback can (optionally) call SDL_GetAudioStreamData() to
* obtain audio from the stream during this call.
* The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio
* from the stream during this call.
*
* The callback's `approx_request` argument is how many bytes
* of _converted_ data (in the stream's output format) was provided
* by the caller, although this may underestimate a little for safety.
* This value might be less than what is currently available in the
* stream, if data was already there, and might be less than the
* caller provided if the stream needs to keep a buffer to aid in
* resampling. Which means the callback may be provided with zero
* The callback's `approx_request` argument is how many bytes of _converted_
* data (in the stream's output format) was provided by the caller, although
* this may underestimate a little for safety. This value might be less than
* what is currently available in the stream, if data was already there, and
* might be less than the caller provided if the stream needs to keep a buffer
* to aid in resampling. Which means the callback may be provided with zero
* bytes, and a different amount on each call.
*
* The callback may call SDL_GetAudioStreamAvailable to see the
* total amount currently available to read from the stream, instead
* of the total provided by the current call.
* The callback may call SDL_GetAudioStreamAvailable to see the total amount
* currently available to read from the stream, instead of the total provided
* by the current call.
*
* The callback is not required to obtain all data. It is allowed
* to read less or none at all. Anything not read now simply remains
* in the stream for later access.
* The callback is not required to obtain all data. It is allowed to read less
* or none at all. Anything not read now simply remains in the stream for
* later access.
*
* Clearing or flushing an audio stream does not call this callback.
*
* This function obtains the stream's lock, which means any existing
* callback (get or put) in progress will finish running before setting
* the new callback.
* This function obtains the stream's lock, which means any existing callback
* (get or put) in progress will finish running before setting the new
* callback.
*
* Setting a NULL function turns off the callback.
*
* \param stream the audio stream to set the new callback on.
* \param callback the new callback function to call when data is added to the stream.
* \param userdata an opaque pointer provided to the callback for its own personal use.
* \param callback the new callback function to call when data is added to the
* stream.
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
* \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
*
* \threadsafety It is safe to call this function from any thread.
@ -1033,12 +1039,14 @@ extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
*
* The `spec` parameter represents the app's side of the audio stream. That
* is, for recording audio, this will be the output format, and for playing
* audio, this will be the input format. This function will set the other
* side of the audio stream to the device's format.
* audio, this will be the input format. This function will set the other side
* of the audio stream to the device's format.
*
* \param devid an audio device to bind a stream to. This must be an opened device, and can not be zero.
* \param devid an audio device to bind a stream to. This must be an opened
* device, and can not be zero.
* \param spec the audio stream's input format
* \returns a bound audio stream on success, ready to use. NULL on error; call SDL_GetError() for more information.
* \returns a bound audio stream on success, ready to use. NULL on error; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1070,8 +1078,8 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAndBindAudioStream(SDL_AudioD
* audio data allocated by the function is written to `audio_buf` and its
* length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
* `channels`, and `format` are set to the values of the audio data in the
* buffer. The `samples` member is set to a sane default and all
* others are set to zero.
* buffer. The `samples` member is set to a sane default and all others are
* set to zero.
*
* It's necessary to use SDL_free() to free the audio data returned in
* `audio_buf` when it is no longer used.
@ -1108,16 +1116,16 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAndBindAudioStream(SDL_AudioD
*
* \param src The data source for the WAVE data
* \param freesrc If non-zero, SDL will _always_ free the data source
* \param spec A pointer to an SDL_AudioSpec that will be set to the
* WAVE data's format details on successful return.
* \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
* data's format details on successful return.
* \param audio_buf A pointer filled with the audio data, allocated by the
* function.
* \param audio_len A pointer filled with the length of the audio data buffer
* in bytes
* \returns This function, if successfully called, returns 0. `audio_buf`
* will be filled with a pointer to an allocated buffer
* containing the audio data, and `audio_len` is filled with the
* length of that audio buffer in bytes.
* \returns This function, if successfully called, returns 0. `audio_buf` will
* be filled with a pointer to an allocated buffer containing the
* audio data, and `audio_len` is filled with the length of that
* audio buffer in bytes.
*
* This function returns -1 if the .WAV file cannot be opened, uses
* an unknown data format, or is corrupt; call SDL_GetError() for
@ -1149,16 +1157,16 @@ extern DECLSPEC int SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, int freesrc,
* 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 spec A pointer to an SDL_AudioSpec that will be set to the
* WAVE data's format details on successful return.
* \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
* data's format details on successful return.
* \param audio_buf A pointer filled with the audio data, allocated by the
* function.
* \param audio_len A pointer filled with the length of the audio data buffer
* in bytes
* \returns This function, if successfully called, returns 0. `audio_buf`
* will be filled with a pointer to an allocated buffer
* containing the audio data, and `audio_len` is filled with the
* length of that audio buffer in bytes.
* \returns This function, if successfully called, returns 0. `audio_buf` will
* be filled with a pointer to an allocated buffer containing the
* audio data, and `audio_len` is filled with the length of that
* audio buffer in bytes.
*
* This function returns -1 if the .WAV file cannot be opened, uses
* an unknown data format, or is corrupt; call SDL_GetError() for
@ -1261,9 +1269,9 @@ extern DECLSPEC int SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spe
/**
* Get the appropriate memset value for silencing an audio format.
*
* The value returned by this function can be used as the second
* argument to memset (or SDL_memset) to set an audio buffer in
* a specific format to silence.
* The value returned by this function can be used as the second argument to
* memset (or SDL_memset) to set an audio buffer in a specific format to
* silence.
*
* \param format the audio data format to query.
* \returns A byte value that can be passed to memset.