From fb7c2c06580298c27ecce74a37e1cb65460579b9 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 14 Jan 2026 14:12:58 -0500
Subject: [PATCH] api: Replaced MIX_TrackLooping() with MIX_GetTrackLoops().
This provides more fine-grained info and pairs better with MIX_SetTrackLoops().
The old functionality is accessible by just doing `MIX_GetTrackLoops() != 0`.
Fixes #799.
---
include/SDL3_mixer/SDL_mixer.h | 23 +++++++++++++++--------
src/SDL_mixer.c | 8 +++++---
src/SDL_mixer.exports | 2 +-
src/SDL_mixer.sym | 2 +-
4 files changed, 22 insertions(+), 13 deletions(-)
diff --git a/include/SDL3_mixer/SDL_mixer.h b/include/SDL3_mixer/SDL_mixer.h
index cf9ff6d2..4f55d736 100644
--- a/include/SDL3_mixer/SDL_mixer.h
+++ b/include/SDL3_mixer/SDL_mixer.h
@@ -1386,24 +1386,31 @@ extern SDL_DECLSPEC Sint64 SDLCALL MIX_GetTrackPlaybackPosition(MIX_Track *track
extern SDL_DECLSPEC Sint64 SDLCALL MIX_GetTrackFadeFrames(MIX_Track *track);
/**
- * Query whether a given track is looping.
+ * Query how many loops remain for a given track.
*
- * This specifically checks if the track is _not stopped_ (paused or playing),
- * and there is at least one loop remaining. If a track _was_ looping but is
- * on its final iteration of the loop, this will return false.
+ * This returns the number of loops still pending; if a track will eventually
+ * complete and loop to play again one more time, this will return 1. If a
+ * track _was_ looping but is on its final iteration of the loop (will stop
+ * when this iteration completes), this will return zero.
+ *
+ * A track that is looping infinitely will return -1. This value does not
+ * report an error in this case.
+ *
+ * A track that is stopped (not playing and not paused) will have zero loops
+ * remaining.
*
* On various errors (MIX_Init() was not called, the track is NULL), this
- * returns false, but there is no mechanism to distinguish errors from
+ * returns zero, but there is no mechanism to distinguish errors from
* non-looping tracks.
*
* \param track the track to query.
- * \returns true if looping, false otherwise.
+ * \returns the number of pending loops, zero if not looping, and -1 if looping infinitely.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL_mixer 3.0.0.
*/
-extern SDL_DECLSPEC bool SDLCALL MIX_TrackLooping(MIX_Track *track);
+extern SDL_DECLSPEC int SDLCALL MIX_GetTrackLoops(MIX_Track *track);
/**
* Change the number of times a currently-playing track will loop.
@@ -1432,7 +1439,7 @@ extern SDL_DECLSPEC bool SDLCALL MIX_TrackLooping(MIX_Track *track);
*
* \since This function is available since SDL_mixer 3.0.0.
*
- * \sa MIX_TrackLooping
+ * \sa MIX_GetTrackLoops
*/
extern SDL_DECLSPEC bool SDLCALL MIX_SetTrackLoops(MIX_Track *track, int num_loops);
diff --git a/src/SDL_mixer.c b/src/SDL_mixer.c
index 1d0412ec..5e235340 100644
--- a/src/SDL_mixer.c
+++ b/src/SDL_mixer.c
@@ -2020,12 +2020,14 @@ Sint64 MIX_GetTrackFadeFrames(MIX_Track *track)
return retval;
}
-bool MIX_TrackLooping(MIX_Track *track)
+int MIX_GetTrackLoops(MIX_Track *track)
{
- bool retval = false;
+ int retval = 0;
if (CheckTrackParam(track)) {
LockTrack(track);
- retval = ((track->state != MIX_STATE_STOPPED) && (track->loops_remaining != 0));
+ if (track->state != MIX_STATE_STOPPED) {
+ retval = track->loops_remaining;
+ }
UnlockTrack(track);
}
return retval;
diff --git a/src/SDL_mixer.exports b/src/SDL_mixer.exports
index b9335c78..1c92e31b 100644
--- a/src/SDL_mixer.exports
+++ b/src/SDL_mixer.exports
@@ -67,7 +67,7 @@ _MIX_SetTrackRawCallback
_MIX_SetTrackCookedCallback
_MIX_Generate
_MIX_GetAudioDuration
-_MIX_TrackLooping
+_MIX_GetTrackLoops
_MIX_GetTrackAudio
_MIX_GetTrackAudioStream
_MIX_GetTrackRemaining
diff --git a/src/SDL_mixer.sym b/src/SDL_mixer.sym
index 5296e7cb..9f8d6759 100644
--- a/src/SDL_mixer.sym
+++ b/src/SDL_mixer.sym
@@ -68,7 +68,7 @@ SDL3_mixer_0.0.0 {
MIX_SetTrackCookedCallback;
MIX_Generate;
MIX_GetAudioDuration;
- MIX_TrackLooping;
+ MIX_GetTrackLoops;
MIX_GetTrackAudio;
MIX_GetTrackAudioStream;
MIX_GetTrackRemaining;