From e06a701e5433fc5cec3b15e132915f252ae13bf0 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.
(cherry picked from commit bd3185b243c15e9631bf0210a263b8f40b57f4cf)
---
include/SDL3_mixer/SDL_mixer.h | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/include/SDL3_mixer/SDL_mixer.h b/include/SDL3_mixer/SDL_mixer.h
index b912882e..6d4a3ae1 100644
--- a/include/SDL3_mixer/SDL_mixer.h
+++ b/include/SDL3_mixer/SDL_mixer.h
@@ -482,9 +482,11 @@ extern SDL_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 `closeio` is true, the IOStream will be closed before returning, whether
- * this function succeeds or not. SDL_mixer reads everything it needs from the
- * IOStream during this call in any case.
+ * If `closeio` is true, the SDL_IOStream 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 stream 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_IOStream: `Mix_LoadMUS("filename.mp3")` will manage
@@ -542,9 +544,11 @@ extern SDL_DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_IO(SDL_IOStream *src, bool c
* - `MUS_OPUS` (Opus files)
* - `MUS_WAVPACK` (WavPack files)
*
- * If `closeio` is true, the IOStream will be closed before returning, whether
- * this function succeeds or not. SDL_mixer reads everything it needs from the
- * IOStream during this call in any case.
+ * If `closeio` is true, the SDL_IOStream 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 stream 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_IOStream: `Mix_LoadMUS("filename.mp3")` will manage