gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated headers with latest wikiheaders tweaks.

Browse Source
This commit is contained in:
Ryan C. Gordon
2024-06-14 02:09:55 -04:00
parent c0c0c64a1d
commit 51902d4ac5
44 changed files with 1699 additions and 1686 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
include/SDL3/SDL_audio.h
View File

@@ -141,8 +141,8 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
*
* \param x an SDL_AudioFormat value
* \returns data size in bits
* \param x an SDL_AudioFormat value.
* \returns data size in bits.
*
* \threadsafety It is safe to call this macro from any thread.
*
@@ -155,8 +155,8 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
*
* \param x an SDL_AudioFormat value
* \returns data size in bytes
* \param x an SDL_AudioFormat value.
* \returns data size in bytes.
*
* \threadsafety It is safe to call this macro from any thread.
*
@@ -169,7 +169,7 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
*
* \param x an SDL_AudioFormat value
* \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.
@@ -183,7 +183,7 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
*
* \param x an SDL_AudioFormat value
* \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.
@@ -197,7 +197,7 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
*
* \param x an SDL_AudioFormat value
* \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.
@@ -211,7 +211,7 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
*
* \param x an SDL_AudioFormat value
* \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.
@@ -225,7 +225,7 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
*
* \param x an SDL_AudioFormat value
* \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.
@@ -239,7 +239,7 @@ typedef Uint16 SDL_AudioFormat;
*
* For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
*
* \param x an SDL_AudioFormat value
* \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.
@@ -382,7 +382,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
* The returned string follows the SDL_GetStringRule.
*
* \param index the index of the audio driver; the value ranges from 0 to
* SDL_GetNumAudioDrivers() - 1
* SDL_GetNumAudioDrivers() - 1.
* \returns the name of the audio driver at the requested index, or NULL if an
* invalid index was specified.
*
@@ -512,8 +512,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID
* playback timing. Most apps do not need this.
*
* \param devid the instance ID of the device to query.
* \param spec On return, will be filled with device details.
* \param sample_frames Pointer to store device buffer size, in sample frames.
* \param spec on return, will be filled with device details.
* \param sample_frames pointer to store device buffer size, in sample frames.
* Can be NULL.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
@@ -618,7 +618,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic
* Physical devices can not be paused or unpaused, only logical devices
* created through SDL_OpenAudioDevice() can be.
*
* \param dev a device opened by SDL_OpenAudioDevice()
* \param dev a device opened by SDL_OpenAudioDevice().
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -646,7 +646,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
* Physical devices can not be paused or unpaused, only logical devices
* created through SDL_OpenAudioDevice() can be.
*
* \param dev a device opened by SDL_OpenAudioDevice()
* \param dev a device opened by SDL_OpenAudioDevice().
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -669,7 +669,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
* 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()
* \param dev a device opened by SDL_OpenAudioDevice().
* \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise.
*
* \threadsafety It is safe to call this function from any thread.
@@ -692,7 +692,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev
* supplied if terminating immediately afterwards.
*
* \param devid an audio device id previously returned by
* SDL_OpenAudioDevice()
* SDL_OpenAudioDevice().
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -725,7 +725,7 @@ extern SDL_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.
* \param num_streams number streams listed in the `streams` array.
* \returns 0 on success, -1 on error; call SDL_GetError() for more
* information.
*
@@ -770,7 +770,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL
* Unbinding a stream that isn't bound to a device is a legal no-op.
*
* \param streams an array of audio streams to unbind.
* \param num_streams Number streams listed in the `streams` array.
* \param num_streams number streams listed in the `streams` array.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -819,8 +819,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
/**
* Create a new audio stream.
*
* \param src_spec The format details of the input audio
* \param dst_spec The format details of the output audio
* \param src_spec the format details of the input audio.
* \param dst_spec the format details of the output audio.
* \returns a new audio stream on success, or NULL on failure.
*
* \threadsafety It is safe to call this function from any thread.
@@ -840,7 +840,7 @@ extern SDL_DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_Aud
/**
* Get the properties associated with an audio stream.
*
* \param stream the SDL_AudioStream to query
* \param stream the SDL_AudioStream to query.
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
@@ -855,8 +855,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au
* Query the current format of an audio stream.
*
* \param stream the SDL_AudioStream to query.
* \param src_spec Where to store the input audio format; ignored if NULL.
* \param dst_spec Where to store the output audio format; ignored if NULL.
* \param src_spec where to store the input audio format; ignored if NULL.
* \param dst_spec where to store the output audio format; ignored if NULL.
* \returns 0 on success, or -1 on error.
*
* \threadsafety It is safe to call this function from any thread, as it holds
@@ -881,10 +881,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream
* 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 src_spec The new format of the audio input; if NULL, it is not
* \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
* \param dst_spec the new format of the audio output; if NULL, it is not
* changed.
* \returns 0 on success, or -1 on error.
*
@@ -904,7 +904,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream
* Get the frequency ratio of an audio stream.
*
* \param stream the SDL_AudioStream to query.
* \returns the frequency ratio of the stream, or 0.0 on error
* \returns the frequency ratio of the stream, or 0.0 on error.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@@ -927,8 +927,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre
* This is applied during SDL_GetAudioStreamData, and can be continuously
* changed to create various effects.
*
* \param stream The stream the frequency ratio is being changed
* \param ratio The frequency ratio. 1.0 is normal speed. Must be between 0.01
* \param stream the stream the frequency ratio is being changed.
* \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
* and 100.
* \returns 0 on success, or -1 on error.
*
@@ -953,9 +953,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream
* different than SDL2, where data was converted during the Put call and the
* Get call would just dequeue the previously-converted data.
*
* \param stream The stream the audio data is being added to
* \param buf A pointer to the audio data to add
* \param len The number of bytes to write to the stream
* \param stream the stream the audio data is being added to.
* \param buf a pointer to the audio data to add.
* \param len the number of bytes to write to the stream.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -984,10 +984,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream,
* is different than SDL2, where that work was done while inputting new data
* to the stream and requesting the output just copied the converted data.
*
* \param stream The stream the audio is being requested from
* \param buf A buffer to fill with audio data
* \param len The maximum number of bytes to fill
* \returns the number of bytes read from the stream, or -1 on error
* \param stream the stream the audio is being requested from.
* \param buf a buffer to fill with audio data.
* \param len the maximum number of bytes to fill.
* \returns the number of bytes read from the stream, or -1 on error.
*
* \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage
@@ -1014,7 +1014,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream,
* SDL_GetAudioStreamData before this function's return value is no longer
* clamped.
*
* \param stream The audio stream to query
* \param stream the audio stream to query.
* \returns the number of converted/resampled bytes available.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1046,7 +1046,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str
* SDL_GetAudioStreamData before this function's return value is no longer
* clamped.
*
* \param stream The audio stream to query
* \param stream the audio stream to query.
* \returns the number of bytes queued.
*
* \threadsafety It is safe to call this function from any thread.
@@ -1067,7 +1067,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream
* audio gaps in the output. Generally this is intended to signal the end of
* input, so the complete output becomes available.
*
* \param stream The audio stream to flush
* \param stream the audio stream to flush.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -1085,7 +1085,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *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
* SDL_GetError() for more information.
*
@@ -1112,7 +1112,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
* audio streams. This might be useful while a game is paused, or a level is
* loading, etc.
*
* \param stream The audio stream associated with the audio device to pause
* \param stream the audio stream associated with the audio device to pause.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -1132,7 +1132,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stre
* previously been paused. Once unpaused, any bound audio streams will begin
* to progress again, and audio can be generated.
*
* \param stream The audio stream associated with the audio device to resume
* \param stream the audio stream associated with the audio device to resume.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -1160,7 +1160,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *str
* 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.
* \param stream the audio stream to lock.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -1178,7 +1178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
*
* This unlocks an audio stream after a call to SDL_LockAudioStream.
*
* \param stream The audio stream to unlock.
* \param stream the audio stream to unlock.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -1212,12 +1212,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
* appropriate, but the system goes on with the data currently available to it
* if this callback does nothing.
*
* \param stream The SDL audio stream associated with this callback.
* \param additional_amount The amount of data, in bytes, that is needed right
* \param stream the SDL audio stream associated with this callback.
* \param additional_amount the amount of data, in bytes, that is needed right
* now.
* \param total_amount The total amount of data requested, in bytes, that is
* \param total_amount the total amount of data requested, in bytes, that is
* requested or available.
* \param userdata An opaque pointer provided by the app for their personal
* \param userdata an opaque pointer provided by the app for their personal
* use.
*
* \threadsafety This callbacks may run from any thread, so if you need to
@@ -1338,7 +1338,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *s
* device that was opened alongside this stream's creation will be closed,
* too.
*
* \param stream The audio stream to destroy.
* \param stream the audio stream to destroy.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -1390,11 +1390,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
* \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
* SDL_AUDIO_DEVICE_DEFAULT_CAPTURE.
* \param spec the audio stream's data format. Can be NULL.
* \param callback A callback where the app will provide new data for
* \param callback a callback where the app will provide new data for
* playback, or receive new data for capture. Can be NULL, in
* which case the app will need to call SDL_PutAudioStreamData
* or SDL_GetAudioStreamData as necessary.
* \param userdata App-controlled pointer passed to callback. Can be NULL.
* \param userdata app-controlled pointer passed to callback. Can be NULL.
* Ignored if callback is NULL.
* \returns an audio stream on success, ready to use. NULL on error; call
* SDL_GetError() for more information. When done with this stream,
@@ -1485,9 +1485,9 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio
*
* Setting a NULL callback function disables any previously-set callback.
*
* \param devid The ID of an opened audio device.
* \param callback A callback function to be called. Can be NULL.
* \param userdata App-controlled pointer passed to callback. Can be NULL.
* \param devid the ID of an opened audio device.
* \param callback a callback function to be called. Can be NULL.
* \param userdata app-controlled pointer passed to callback. Can be NULL.
* \returns zero on success, -1 on error; call SDL_GetError() for more
* information.
*
@@ -1549,15 +1549,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID de
* SDL_LoadWAV("sample.wav", &spec, &buf, &len);
* ```
*
* \param src The data source for the WAVE data
* \param closeio If SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error
* \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
* \param src the data source for the WAVE data.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error.
* \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 0 on success. `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.
@@ -1589,13 +1589,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool clos
* SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
* ```
*
* \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 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 audio_buf A pointer filled with the audio data, allocated by the
* \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
* \param audio_len a pointer filled with the length of the audio data buffer
* in bytes.
* \returns 0 on success. `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.
@@ -1637,13 +1637,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * sp
* SDL_MixAudio() is really only needed when you're mixing a single audio
* stream with a volume adjustment.
*
* \param dst the destination for the mixed audio
* \param src the source audio buffer to be mixed
* \param dst the destination for the mixed audio.
* \param src the source audio buffer to be mixed.
* \param format the SDL_AudioFormat structure representing the desired audio
* format
* \param len the length of the audio buffer in bytes
* format.
* \param len the length of the audio buffer in bytes.
* \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full
* audio volume
* audio volume.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -1669,14 +1669,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_MixAudio(Uint8 * dst,
* use, so it's also less efficient than using one directly, if you need to
* convert multiple times.
*
* \param src_spec The format details of the input audio
* \param src_data The audio data to be converted
* \param src_len The len of src_data
* \param dst_spec The format details of the output audio
* \param dst_data Will be filled with a pointer to converted audio data,
* \param src_spec the format details of the input audio.
* \param src_data the audio data to be converted.
* \param src_len the len of src_data.
* \param dst_spec the format details of the output audio.
* \param dst_data will be filled with a pointer to converted audio data,
* which should be freed with SDL_free(). On error, it will be
* NULL.
* \param dst_len Will be filled with the len of dst_data
* \param dst_len will be filled with the len of dst_data.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*