audio: better docs on conversion APIs, error if not init'd (thanks, Simon!).
authorRyan C. Gordon <icculus@icculus.org>
Fri, 18 Aug 2017 16:52:19 -0400
changeset 1131986b1fde471c6
parent 11318 06fd8421e8f6
child 11320 6b36980ae340
audio: better docs on conversion APIs, error if not init'd (thanks, Simon!).

Fixes Bugzilla #3662.
include/SDL_audio.h
src/audio/SDL_audiocvt.c
     1.1 --- a/include/SDL_audio.h	Fri Aug 18 16:35:55 2017 -0400
     1.2 +++ b/include/SDL_audio.h	Fri Aug 18 16:52:19 2017 -0400
     1.3 @@ -450,10 +450,11 @@
     1.4   *  This function takes a source format and rate and a destination format
     1.5   *  and rate, and initializes the \c cvt structure with information needed
     1.6   *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
     1.7 - *  to the other.
     1.8 + *  to the other. An unsupported format causes an error and -1 will be returned.
     1.9 + *  The audio subsystem must be initialized before calling this function.
    1.10   *
    1.11 - *  \return -1 if the format conversion is not supported, 0 if there's
    1.12 - *  no conversion needed, or 1 if the audio filter is set up.
    1.13 + *  \return 0 if no conversion is needed, 1 if the audio filter is set up,
    1.14 + *  or -1 on error.
    1.15   */
    1.16  extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
    1.17                                                SDL_AudioFormat src_format,
    1.18 @@ -472,6 +473,8 @@
    1.19   *  The data conversion may expand the size of the audio data, so the buffer
    1.20   *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
    1.21   *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
    1.22 + *
    1.23 + *  \return 0 on success or -1 if \c cvt->buf is NULL.
    1.24   */
    1.25  extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
    1.26  
     2.1 --- a/src/audio/SDL_audiocvt.c	Fri Aug 18 16:35:55 2017 -0400
     2.2 +++ b/src/audio/SDL_audiocvt.c	Fri Aug 18 16:52:19 2017 -0400
     2.3 @@ -22,6 +22,7 @@
     2.4  
     2.5  /* Functions for audio drivers to perform runtime conversion of audio format */
     2.6  
     2.7 +#include "SDL.h"
     2.8  #include "SDL_audio.h"
     2.9  #include "SDL_audio_c.h"
    2.10  
    2.11 @@ -555,7 +556,7 @@
    2.12          }
    2.13  
    2.14          if (!filter) {
    2.15 -            return SDL_SetError("No conversion available for these formats");
    2.16 +            return SDL_SetError("No conversion from source format to float available");
    2.17          }
    2.18  
    2.19          if (SDL_AddAudioCVTFilter(cvt, filter) < 0) {
    2.20 @@ -594,7 +595,7 @@
    2.21          }
    2.22  
    2.23          if (!filter) {
    2.24 -            return SDL_SetError("No conversion available for these formats");
    2.25 +            return SDL_SetError("No conversion from float to destination format available");
    2.26          }
    2.27  
    2.28          if (SDL_AddAudioCVTFilter(cvt, filter) < 0) {
    2.29 @@ -743,8 +744,8 @@
    2.30  
    2.31  
    2.32  /* Creates a set of audio filters to convert from one format to another.
    2.33 -   Returns -1 if the format conversion is not supported, 0 if there's
    2.34 -   no conversion needed, or 1 if the audio filter is set up.
    2.35 +   Returns 0 if no conversion is needed, 1 if the audio filter is set up,
    2.36 +   or -1 if an error like invalid parameter, unsupported format, etc. occurred.
    2.37  */
    2.38  
    2.39  int
    2.40 @@ -757,6 +758,11 @@
    2.41          return SDL_InvalidParamError("cvt");
    2.42      }
    2.43  
    2.44 +    /* Conversions from and to float require the audio subsystem to be initialized */
    2.45 +    if (!SDL_WasInit(SDL_INIT_AUDIO)) {
    2.46 +        return SDL_SetError("Audio subsystem has not been initialized");
    2.47 +    }
    2.48 +
    2.49      /* Make sure we zero out the audio conversion before error checking */
    2.50      SDL_zerop(cvt);
    2.51