From 2b6cb7bfb2508c0f5bbffbd9caabbde4f1d7024e Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" 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 36ed3556ed..8bc393aef1 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