audio: documentation improvements.
This commit is contained in:
Ryan C. Gordon
parent
4b78b789a7
commit
fd4c9f4e11
@ -19,8 +19,6 @@
|
||||
3. This notice may not be removed or altered from any source distribution.
|
||||
*/
|
||||
|
||||
/* !!! FIXME: several functions in here need Doxygen comments. */
|
||||
|
||||
/**
|
||||
* \file SDL_audio.h
|
||||
*
|
||||
@ -164,6 +162,8 @@ typedef struct SDL_AudioSpec
|
||||
- You push data as you have it, and pull it when you need it
|
||||
- It can also function as a basic audio data queue even if you
|
||||
just have sound that needs to pass from one place to another.
|
||||
- You can hook callbacks up to them when more data is added or
|
||||
requested, to manage data on-the-fly.
|
||||
*/
|
||||
struct SDL_AudioStream; /* this is opaque to the outside world. */
|
||||
typedef struct SDL_AudioStream SDL_AudioStream;
|
||||
@ -194,10 +194,10 @@ typedef struct SDL_AudioStream SDL_AudioStream;
|
||||
*
|
||||
* \returns the number of built-in audio drivers.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetAudioDriver
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
|
||||
@ -245,7 +245,6 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
|
||||
*/
|
||||
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
|
||||
|
||||
|
||||
/**
|
||||
* Get a list of currently-connected audio output devices.
|
||||
*
|
||||
@ -254,16 +253,20 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
|
||||
* 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().
|
||||
*
|
||||
* \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.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_OpenAudioDevice
|
||||
* \sa SDL_GetAudioCaptureDevices
|
||||
*/
|
||||
extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioOutputDevices(int *count);
|
||||
|
||||
@ -275,16 +278,20 @@ extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioOutputDevices(int *count)
|
||||
* 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().
|
||||
*
|
||||
* \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.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_OpenAudioDevice
|
||||
* \sa SDL_GetAudioOutputDevices
|
||||
*/
|
||||
extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioCaptureDevices(int *count);
|
||||
|
||||
@ -297,10 +304,10 @@ extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioCaptureDevices(int *count
|
||||
* \param devid the instance ID of the device to query.
|
||||
* \returns the name of the audio device, or NULL on error.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetNumAudioDevices
|
||||
* \sa SDL_GetDefaultAudioInfo
|
||||
*/
|
||||
@ -351,8 +358,6 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SD
|
||||
* 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.
|
||||
* Requesting the default will also allow the user to specify
|
||||
* preferences with hints/environment variables.
|
||||
*
|
||||
* 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
|
||||
@ -368,6 +373,11 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SD
|
||||
* 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.
|
||||
*
|
||||
* This function returns the opened device ID on success. This is a new,
|
||||
* unique SDL_AudioDeviceID that represents a logical device.
|
||||
*
|
||||
@ -388,10 +398,10 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SD
|
||||
* \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.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CloseAudioDevice
|
||||
* \sa SDL_GetAudioDeviceFormat
|
||||
*/
|
||||
@ -410,10 +420,10 @@ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID
|
||||
*
|
||||
* \param devid an audio device id previously returned by SDL_OpenAudioDevice()
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_OpenAudioDevice
|
||||
*/
|
||||
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
|
||||
@ -444,10 +454,10 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
|
||||
* \param num_streams Number streams listed in the `streams` array.
|
||||
* \returns 0 on success, -1 on error; call SDL_GetError() for more information.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_BindAudioStreams
|
||||
* \sa SDL_UnbindAudioStreams
|
||||
* \sa SDL_UnbindAudioStream
|
||||
@ -464,10 +474,10 @@ extern DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_Au
|
||||
* \param stream an audio stream to bind to a device.
|
||||
* \returns 0 on success, -1 on error; call SDL_GetError() for more information.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_BindAudioStreams
|
||||
* \sa SDL_UnbindAudioStreams
|
||||
* \sa SDL_UnbindAudioStream
|
||||
@ -486,10 +496,10 @@ extern DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_Aud
|
||||
* \param streams an array of audio streams to unbind.
|
||||
* \param num_streams Number streams listed in the `streams` array.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_BindAudioStreams
|
||||
* \sa SDL_BindAudioStream
|
||||
* \sa SDL_UnbindAudioStream
|
||||
@ -504,10 +514,10 @@ extern DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, i
|
||||
*
|
||||
* \param stream an audio stream to unbind from a device.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_BindAudioStream
|
||||
* \sa SDL_BindAudioStreams
|
||||
* \sa SDL_UnbindAudioStreams
|
||||
@ -597,6 +607,10 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream,
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \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
|
||||
* extra locking.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CreateAudioStream
|
||||
@ -625,6 +639,10 @@ extern DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, cons
|
||||
* \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
|
||||
* extra locking.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CreateAudioStream
|
||||
@ -653,6 +671,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void
|
||||
* \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.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CreateAudioStream
|
||||
@ -676,6 +696,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CreateAudioStream
|
||||
@ -694,6 +716,8 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CreateAudioStream
|
||||
@ -728,10 +752,10 @@ extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_UnlockAudioStream
|
||||
* \sa SDL_SetAudioStreamPutCallback
|
||||
* \sa SDL_SetAudioStreamGetCallback
|
||||
@ -748,11 +772,11 @@ extern DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety You should only call this from the same thread that
|
||||
* previously called SDL_LockAudioStream.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_LockAudioStream
|
||||
* \sa SDL_SetAudioStreamPutCallback
|
||||
* \sa SDL_SetAudioStreamGetCallback
|
||||
@ -814,10 +838,10 @@ typedef void (SDLCALL *SDL_AudioStreamRequestCallback)(SDL_AudioStream *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.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_SetAudioStreamPutCallback
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata);
|
||||
@ -861,10 +885,10 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *strea
|
||||
* \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.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_SetAudioStreamGetCallback
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata);
|
||||
@ -875,6 +899,8 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *strea
|
||||
*
|
||||
* \param stream The audio stream to free
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CreateAudioStream
|
||||
@ -903,10 +929,10 @@ extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
|
||||
* \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.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_BindAudioStreams
|
||||
* \sa SDL_UnbindAudioStreams
|
||||
* \sa SDL_UnbindAudioStream
|
||||
@ -989,6 +1015,8 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAndBindAudioStream(SDL_AudioD
|
||||
* When the application is done with the data returned in
|
||||
* `audio_buf`, it should call SDL_free() to dispose of it.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_free
|
||||
@ -1028,6 +1056,8 @@ extern DECLSPEC int SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, int freesrc,
|
||||
* When the application is done with the data returned in
|
||||
* `audio_buf`, it should call SDL_free() to dispose of it.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_free
|
||||
@ -1070,6 +1100,8 @@ extern DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * spec,
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_MixAudioFormat(Uint8 * dst,
|
||||
@ -1101,6 +1133,8 @@ extern DECLSPEC int SDLCALL SDL_MixAudioFormat(Uint8 * dst,
|
||||
* \returns 0 on success or a negative error code on failure; call
|
||||
* SDL_GetError() for more information.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_CreateAudioStream
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user