From 2b6cb7bfb2508c0f5bbffbd9caabbde4f1d7024e Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 9 May 2023 14:24:22 -0400
Subject: [PATCH] include: SDL_ConvertAudioSamples docs now warn about
converting in chunks.
Fixes #7154.
---
include/SDL3/SDL_audio.h | 13 +++++++++++--
1 file changed, 11 insertions(+), 2 deletions(-)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 36ed3556ede4..8bc393aef16e 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -1221,11 +1221,20 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
*/
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
-/* !!! FIXME: maybe remove this before SDL3's API is locked down. */
-
/**
* Convert some audio data of one format to another format.
*
+ * Please note that this function is for convenience, but should not
+ * be used to resample audio in blocks, as it will introduce audio
+ * artifacts on the boundaries. You should only use this function if
+ * you are converting audio data in its entirety in one call. If you
+ * want to convert audio in smaller chunks, use an SDL_AudioStream,
+ * which is designed for this situation.
+ *
+ * Internally, this function creates and destroys an SDL_AudioStream
+ * on each use, so it's also less efficient than using one directly,
+ * if you need to convert multiple times.
+ *
* \param src_format The format of the source audio
* \param src_channels The number of channels of the source audio
* \param src_rate The sampling rate of the source audio