From cd633b9a880889552504455e1916257c6e875ade Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
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 5347eca8e35b..5095f98d88c6 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 6e6fbdb978e8..84894cebae28 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 102c66a8ac48..15e28e793cc6 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 0a34ccdc9181..60366b050030 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 a66a47a3d380..bd97d523d23f 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 f9e3521aa081..ce7170667dec 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 4bdb0dfdc497..ec7659df2ed6 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 853c5386a6a3..15d6dec27271 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);