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

Sync SDL3 wiki -> header

Browse Source
This commit is contained in:
SDL Wiki Bot
2023-08-04 01:28:15 +00:00
parent 18c59cc969
commit c0a88930bf
1 changed files with 182 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

356
include/SDL3/SDL_audio.h
View File

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