From cd633b9a880889552504455e1916257c6e875ade Mon Sep 17 00:00:00 2001 From: Sam Lantinga Date: Tue, 12 Sep 2023 12:09:17 -0700 Subject: [PATCH] Renamed SDL_IsAudioDevicePaused() to SDL_AudioDevicePaused() This aligns with the SDL3 convention of removing "Is" from self-explanatory function names Also improved some documentation in SDL_audio.h --- docs/README-migration.md | 2 +- include/SDL3/SDL_audio.h | 17 +++++++++++------ src/audio/SDL_audio.c | 2 +- src/dynapi/SDL_dynapi.sym | 2 +- src/dynapi/SDL_dynapi_overrides.h | 2 +- src/dynapi/SDL_dynapi_procs.h | 2 +- test/testaudiocapture.c | 2 +- test/testaudiostreamdynamicresample.c | 4 ++-- 8 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/README-migration.md b/docs/README-migration.md index 5347eca8e3..5095f98d88 100644 --- a/docs/README-migration.md +++ b/docs/README-migration.md @@ -148,7 +148,7 @@ SDL_PauseAudioDevice() no longer takes a second argument; it always pauses the d Audio devices, opened by SDL_OpenAudioDevice(), no longer start in a paused state, as they don't begin processing audio until a stream is bound. -SDL_GetAudioDeviceStatus() has been removed; there is now SDL_IsAudioDevicePaused(). +SDL_GetAudioDeviceStatus() has been removed; there is now SDL_AudioDevicePaused(). SDL_QueueAudio(), SDL_DequeueAudio, and SDL_ClearQueuedAudio and SDL_GetQueuedAudioSize() have been removed; an SDL_AudioStream bound to a device provides the exact same functionality. diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index 6e6fbdb978..84894cebae 100644 --- a/include/SDL3/SDL_audio.h +++ b/include/SDL3/SDL_audio.h @@ -309,7 +309,8 @@ extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioCaptureDevices(int *count * * \since This function is available since SDL 3.0.0. * - * \sa SDL_GetNumAudioDevices + * \sa SDL_GetAudioOutputDevices + * \sa SDL_GetAudioCaptureDevices * \sa SDL_GetDefaultAudioInfo */ extern DECLSPEC char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid); @@ -440,7 +441,7 @@ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID * \since This function is available since SDL 3.0.0. * * \sa SDL_ResumeAudioDevice - * \sa SDL_IsAudioDevicePaused + * \sa SDL_AudioDevicePaused */ extern DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); @@ -468,7 +469,7 @@ extern DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); * \since This function is available since SDL 3.0.0. * * \sa SDL_ResumeAudioDevice - * \sa SDL_IsAudioDevicePaused + * \sa SDL_AudioDevicePaused */ extern DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); @@ -491,9 +492,9 @@ extern DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); * * \sa SDL_PauseAudioDevice * \sa SDL_ResumeAudioDevice - * \sa SDL_IsAudioDevicePaused + * \sa SDL_AudioDevicePaused */ -extern DECLSPEC SDL_bool SDLCALL SDL_IsAudioDevicePaused(SDL_AudioDeviceID dev); +extern DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); /** * Close a previously-opened audio device. @@ -1089,7 +1090,8 @@ extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream); * * Also unlike other functions, the audio device begins paused. This is to map * more closely to SDL2-style behavior, and since there is no extra step here - * to bind a stream to begin audio flowing. + * to bind a stream to begin audio flowing. The audio device should be resumed + * with SDL_ResumeAudioDevice(SDL_GetAudioStreamDevice(stream)); * * This function works with both playback and capture devices. * @@ -1123,6 +1125,9 @@ extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream); * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetAudioStreamDevice + * \sa SDL_ResumeAudioDevice */ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata); diff --git a/src/audio/SDL_audio.c b/src/audio/SDL_audio.c index 102c66a8ac..15e28e793c 100644 --- a/src/audio/SDL_audio.c +++ b/src/audio/SDL_audio.c @@ -1415,7 +1415,7 @@ int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID devid) return SetLogicalAudioDevicePauseState(devid, 0); } -SDL_bool SDL_IsAudioDevicePaused(SDL_AudioDeviceID devid) +SDL_bool SDL_AudioDevicePaused(SDL_AudioDeviceID devid) { SDL_LogicalAudioDevice *logdev = ObtainLogicalAudioDevice(devid); SDL_bool retval = SDL_FALSE; diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym index 0a34ccdc91..60366b0500 100644 --- a/src/dynapi/SDL_dynapi.sym +++ b/src/dynapi/SDL_dynapi.sym @@ -885,7 +885,7 @@ SDL3_0.0.0 { SDL_LoadWAV; SDL_PauseAudioDevice; SDL_ResumeAudioDevice; - SDL_IsAudioDevicePaused; + SDL_AudioDevicePaused; SDL_GetAudioStreamDevice; SDL_ShowWindowSystemMenu; SDL_ReadS16LE; diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h index a66a47a3d3..bd97d523d2 100644 --- a/src/dynapi/SDL_dynapi_overrides.h +++ b/src/dynapi/SDL_dynapi_overrides.h @@ -910,7 +910,7 @@ #define SDL_LoadWAV SDL_LoadWAV_REAL #define SDL_PauseAudioDevice SDL_PauseAudioDevice_REAL #define SDL_ResumeAudioDevice SDL_ResumeAudioDevice_REAL -#define SDL_IsAudioDevicePaused SDL_IsAudioDevicePaused_REAL +#define SDL_AudioDevicePaused SDL_AudioDevicePaused_REAL #define SDL_GetAudioStreamDevice SDL_GetAudioStreamDevice_REAL #define SDL_ShowWindowSystemMenu SDL_ShowWindowSystemMenu_REAL #define SDL_ReadS16LE SDL_ReadS16LE_REAL diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h index f9e3521aa0..ce7170667d 100644 --- a/src/dynapi/SDL_dynapi_procs.h +++ b/src/dynapi/SDL_dynapi_procs.h @@ -954,7 +954,7 @@ SDL_DYNAPI_PROC(int,SDL_GetSilenceValueForFormat,(SDL_AudioFormat a),(a),return) SDL_DYNAPI_PROC(int,SDL_LoadWAV,(const char *a, SDL_AudioSpec *b, Uint8 **c, Uint32 *d),(a,b,c,d),return) SDL_DYNAPI_PROC(int,SDL_PauseAudioDevice,(SDL_AudioDeviceID a),(a),return) SDL_DYNAPI_PROC(int,SDL_ResumeAudioDevice,(SDL_AudioDeviceID a),(a),return) -SDL_DYNAPI_PROC(SDL_bool,SDL_IsAudioDevicePaused,(SDL_AudioDeviceID a),(a),return) +SDL_DYNAPI_PROC(SDL_bool,SDL_AudioDevicePaused,(SDL_AudioDeviceID a),(a),return) SDL_DYNAPI_PROC(SDL_AudioDeviceID,SDL_GetAudioStreamDevice,(SDL_AudioStream *a),(a),return) SDL_DYNAPI_PROC(int,SDL_ShowWindowSystemMenu,(SDL_Window *a, int b, int c),(a,b,c),return) SDL_DYNAPI_PROC(SDL_bool,SDL_ReadS16LE,(SDL_RWops *a, Sint16 *b),(a,b),return) diff --git a/test/testaudiocapture.c b/test/testaudiocapture.c index 4bdb0dfdc4..ec7659df2e 100644 --- a/test/testaudiocapture.c +++ b/test/testaudiocapture.c @@ -54,7 +54,7 @@ static void loop(void) } } - if (!SDL_IsAudioDevicePaused(devid_in)) { + if (!SDL_AudioDevicePaused(devid_in)) { SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255); } else { SDL_SetRenderDrawColor(renderer, 255, 0, 0, 255); diff --git a/test/testaudiostreamdynamicresample.c b/test/testaudiostreamdynamicresample.c index 853c5386a6..15d6dec272 100644 --- a/test/testaudiostreamdynamicresample.c +++ b/test/testaudiostreamdynamicresample.c @@ -226,7 +226,7 @@ static void loop(void) if (e.type == SDL_EVENT_KEY_DOWN) { SDL_Keycode sym = e.key.keysym.sym; if (sym == SDLK_q) { - if (SDL_IsAudioDevicePaused(state->audio_id)) { + if (SDL_AudioDevicePaused(state->audio_id)) { SDL_ResumeAudioDevice(state->audio_id); } else { SDL_PauseAudioDevice(state->audio_id); @@ -325,7 +325,7 @@ static void loop(void) } draw_textf(rend, 0, draw_y, "%7s, Loop: %3s, Flush: %3s", - SDL_IsAudioDevicePaused(state->audio_id) ? "Paused" : "Playing", auto_loop ? "On" : "Off", auto_flush ? "On" : "Off"); + SDL_AudioDevicePaused(state->audio_id) ? "Paused" : "Playing", auto_loop ? "On" : "Off", auto_flush ? "On" : "Off"); draw_y += FONT_LINE_HEIGHT; draw_textf(rend, 0, draw_y, "Available: %4.2f (%i bytes)", available_seconds, available_bytes);