From d0f6264f95b2c1e6646b512b13cc3b9540157bc0 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 26 May 2026 09:56:07 -0400
Subject: [PATCH] docs: Update notes on SDL_AudioStream format management.
Fixes #15688.
---
include/SDL3/SDL_audio.h | 17 ++++++++++++++---
1 file changed, 14 insertions(+), 3 deletions(-)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index c72fe04cc320a..46a73b1c90b41 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -434,7 +434,8 @@ typedef struct SDL_AudioSpec
* - It can handle incoming data in any variable size.
* - It can handle input/output format changes on the fly.
* - It can remap audio channels between inputs and outputs.
- * - You push data as you have it, and pull it when you need it
+ * - You push data as you have it, and pull it when you need it; the
+ * stream will buffer data as needed.
* - It can also function as a basic audio data queue even if you just have
* sound that needs to pass from one place to another.
* - You can hook callbacks up to them when more data is added or requested,
@@ -1054,8 +1055,15 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
/**
* Create a new audio stream.
*
- * \param src_spec the format details of the input audio.
- * \param dst_spec the format details of the output audio.
+ * Note that `src_spec` or `dst_spec` may be NULL, but any attempts to
+ * put or get data from an audio stream will fail until it has valid
+ * specs assigned to both ends of the stream. Specs can be assigned later
+ * through SDL_SetAudioStreamFormat(), or binding the stream to an audio
+ * device (which will set the format of only the input or output,
+ * depending on what kind of device the stream was bound to).
+ *
+ * \param src_spec the format details of the input audio. May be NULL.
+ * \param dst_spec the format details of the output audio. May be NULL.
* \returns a new audio stream on success or NULL on failure; call
* SDL_GetError() for more information.
*
@@ -1137,6 +1145,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *strea
* be ignored, but this will not report an error. The other side's format can
* be changed.
*
+ * `src_spec` and `dst_spec` may each be NULL; a NULL spec signals not to
+ * change the current format for that side of the stream.
+ *
* \param stream the stream the format is being changed.
* \param src_spec the new format of the audio input; if NULL, it is not
* changed.