audio: better docs on conversion APIs, error if not init'd (thanks, Simon!). Fixes Bugzilla #3662.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index ada6058..24c3df5 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -450,10 +450,11 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
* This function takes a source format and rate and a destination format
* and rate, and initializes the \c cvt structure with information needed
* by SDL_ConvertAudio() to convert a buffer of audio data from one format
- * to the other.
+ * to the other. An unsupported format causes an error and -1 will be returned.
+ * The audio subsystem must be initialized before calling this function.
*
- * \return -1 if the format conversion is not supported, 0 if there's
- * no conversion needed, or 1 if the audio filter is set up.
+ * \return 0 if no conversion is needed, 1 if the audio filter is set up,
+ * or -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
SDL_AudioFormat src_format,
@@ -472,6 +473,8 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
* The data conversion may expand the size of the audio data, so the buffer
* \c cvt->buf should be allocated after the \c cvt structure is initialized by
* SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
+ *
+ * \return 0 on success or -1 if \c cvt->buf is NULL.
*/
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
diff --git a/src/audio/SDL_audiocvt.c b/src/audio/SDL_audiocvt.c
index 78e180d..0a99973 100644
--- a/src/audio/SDL_audiocvt.c
+++ b/src/audio/SDL_audiocvt.c
@@ -22,6 +22,7 @@
/* Functions for audio drivers to perform runtime conversion of audio format */
+#include "SDL.h"
#include "SDL_audio.h"
#include "SDL_audio_c.h"
@@ -555,7 +556,7 @@ SDL_BuildAudioTypeCVTToFloat(SDL_AudioCVT *cvt, const SDL_AudioFormat src_fmt)
}
if (!filter) {
- return SDL_SetError("No conversion available for these formats");
+ return SDL_SetError("No conversion from source format to float available");
}
if (SDL_AddAudioCVTFilter(cvt, filter) < 0) {
@@ -594,7 +595,7 @@ SDL_BuildAudioTypeCVTFromFloat(SDL_AudioCVT *cvt, const SDL_AudioFormat dst_fmt)
}
if (!filter) {
- return SDL_SetError("No conversion available for these formats");
+ return SDL_SetError("No conversion from float to destination format available");
}
if (SDL_AddAudioCVTFilter(cvt, filter) < 0) {
@@ -743,8 +744,8 @@ SDL_SupportedChannelCount(const int channels)
/* Creates a set of audio filters to convert from one format to another.
- Returns -1 if the format conversion is not supported, 0 if there's
- no conversion needed, or 1 if the audio filter is set up.
+ Returns 0 if no conversion is needed, 1 if the audio filter is set up,
+ or -1 if an error like invalid parameter, unsupported format, etc. occurred.
*/
int
@@ -757,6 +758,11 @@ SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
return SDL_InvalidParamError("cvt");
}
+ /* Conversions from and to float require the audio subsystem to be initialized */
+ if (!SDL_WasInit(SDL_INIT_AUDIO)) {
+ return SDL_SetError("Audio subsystem has not been initialized");
+ }
+
/* Make sure we zero out the audio conversion before error checking */
SDL_zerop(cvt);