audio: better docs on conversion APIs, error if not init'd (thanks, Simon!).

Fixes Bugzilla #3662.

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);
 

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);