From 35b002be824a8e3e4da850f56e691a4348fc083b Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 2 Oct 2024 15:25:31 -0400
Subject: [PATCH] audio: Clarified SDL_GetAudioStreamQueued docs.
---
include/SDL3/SDL_audio.h | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 7ac0d5be2cccc..67b31403f2673 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -1322,6 +1322,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str
/**
* Get the number of bytes currently queued.
*
+ * This is the number of bytes put into a stream as input, not the number
+ * that can be retrieved as output. Because of several details, it's not
+ * possible to calculate one number directly from the other. If you need to
+ * know how much usable data can be retrieved right now, you should use
+ * SDL_GetAudioStreamAvailable() and not this function.
+ *
* Note that audio streams can change their input format at any time, even if
* there is still data queued in a different format, so the returned byte
* count will not necessarily match the number of _sample frames_ available.