From bd3185b243c15e9631bf0210a263b8f40b57f4cf Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 24 Jul 2025 00:16:52 -0400
Subject: [PATCH] include: Clarify lifetime of RWops in Mix_LoadMUS* calls with
freesrc!=0.
Fixes #683.
---
include/SDL_mixer.h | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/include/SDL_mixer.h b/include/SDL_mixer.h
index 52eaf77d0..202d215c2 100644
--- a/include/SDL_mixer.h
+++ b/include/SDL_mixer.h
@@ -665,9 +665,11 @@ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
* fly. Also, crucially, there are as many channels for chunks as the app can
* allocate, but SDL_mixer only offers a single "music" channel.
*
- * If `freesrc` is non-zero, the RWops will be closed before returning,
- * whether this function succeeds or not. SDL_mixer reads everything it needs
- * from the RWops during this call in any case.
+ * If `freesrc` is non-zero, the RWops will be closed when SDL_mixer is done
+ * with it, which will be before this function call returns if there is an
+ * error, or perhaps much later if the music is streaming for some time. The
+ * app should not attempt to use the RWops again, as it may become invalid
+ * without warning.
*
* As a convenience, there is a function to read files from disk without
* having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage
@@ -725,9 +727,11 @@ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
* - `MUS_OPUS` (Opus files)
* - `MUS_WAVPACK` (WavPack files)
*
- * If `freesrc` is non-zero, the RWops will be closed before returning,
- * whether this function succeeds or not. SDL_mixer reads everything it needs
- * from the RWops during this call in any case.
+ * If `freesrc` is non-zero, the RWops will be closed when SDL_mixer is done
+ * with it, which will be before this function call returns if there is an
+ * error, or perhaps much later if the music is streaming for some time. The
+ * app should not attempt to use the RWops again, as it may become invalid
+ * without warning.
*
* As a convenience, there is a function to read files from disk without
* having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage