audio: Made SDL_LoadWAV a real function, not just a macro.

include/SDL3/SDL_audio.h

@@ -946,8 +946,8 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAndBindAudioStream(SDL_AudioD
  * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
  * ```
  *
- * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
- * messy way:
+ * Note that the SDL_LoadWAV function does this same thing for you, but in a
+ * less messy way:
  *
  * ```c
  * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
@@ -983,11 +983,42 @@ extern DECLSPEC int SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, int freesrc,
                                            Uint32 * audio_len);
 
 /**
- *  Loads a WAV from a file.
- *  Compatibility convenience function.
+ * Loads a WAV from a file path.
+ *
+ * This is a convenience function that is effectively the same as:
+ *
+ * ```c
+ * SDL_LoadWAV_RW(SDL_RWFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
+ * ```
+ *
+ * Note that in SDL2, this was a preprocessor macro and not a real function.
+ *
+ * \param path The file path of the WAV file to open.
+ * \param spec A pointer to an SDL_AudioSpec that will be set to the
+ *             WAVE data's format details on successful return.
+ * \param audio_buf A pointer filled with the audio data, allocated by the
+ *                  function.
+ * \param audio_len A pointer filled with the length of the audio data buffer
+ *                  in bytes
+ * \returns This function, if successfully called, returns 0. `audio_buf`
+ *          will be filled with a pointer to an allocated buffer
+ *          containing the audio data, and `audio_len` is filled with the
+ *          length of that audio buffer in bytes.
+ *
+ *          This function returns -1 if the .WAV file cannot be opened, uses
+ *          an unknown data format, or is corrupt; call SDL_GetError() for
+ *          more information.
+ *
+ *          When the application is done with the data returned in
+ *          `audio_buf`, it should call SDL_free() to dispose of it.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_free
+ * \sa SDL_LoadWAV_RW
  */
-#define SDL_LoadWAV(file, fmt, channels, freq, audio_buf, audio_len) \
-    SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1, fmt, channels, freq, audio_buf, audio_len)
+extern DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * spec,
+                                        Uint8 ** audio_buf, Uint32 * audio_len);
 
 
 

src/audio/SDL_wave.c

@@ -2110,3 +2110,9 @@ int SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **aud
 
     return result;
 }
+
+int SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
+{
+    return SDL_LoadWAV_RW(SDL_RWFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
+}
+

src/dynapi/SDL_dynapi.sym

@@ -873,16 +873,17 @@ SDL3_0.0.0 {
     SDL_GetAudioStreamAvailable;
     SDL_FlushAudioStream;
     SDL_ClearAudioStream;
-    SDL_DestroyAudioStream;
-    SDL_CreateAndBindAudioStream;
-    SDL_LoadWAV_RW;
-    SDL_MixAudioFormat;
-    SDL_ConvertAudioSamples;
-    SDL_GetSilenceValueForFormat;
     SDL_LockAudioStream;
     SDL_UnlockAudioStream;
     SDL_SetAudioStreamGetCallback;
     SDL_SetAudioStreamPutCallback;
+    SDL_DestroyAudioStream;
+    SDL_CreateAndBindAudioStream;
+    SDL_LoadWAV_RW;
+    SDL_LoadWAV;
+    SDL_MixAudioFormat;
+    SDL_ConvertAudioSamples;
+    SDL_GetSilenceValueForFormat;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -899,13 +899,14 @@
 #define SDL_GetAudioStreamAvailable SDL_GetAudioStreamAvailable_REAL
 #define SDL_FlushAudioStream SDL_FlushAudioStream_REAL
 #define SDL_ClearAudioStream SDL_ClearAudioStream_REAL
-#define SDL_DestroyAudioStream SDL_DestroyAudioStream_REAL
-#define SDL_CreateAndBindAudioStream SDL_CreateAndBindAudioStream_REAL
-#define SDL_LoadWAV_RW SDL_LoadWAV_RW_REAL
-#define SDL_MixAudioFormat SDL_MixAudioFormat_REAL
-#define SDL_ConvertAudioSamples SDL_ConvertAudioSamples_REAL
-#define SDL_GetSilenceValueForFormat SDL_GetSilenceValueForFormat_REAL
 #define SDL_LockAudioStream SDL_LockAudioStream_REAL
 #define SDL_UnlockAudioStream SDL_UnlockAudioStream_REAL
 #define SDL_SetAudioStreamGetCallback SDL_SetAudioStreamGetCallback_REAL
 #define SDL_SetAudioStreamPutCallback SDL_SetAudioStreamPutCallback_REAL
+#define SDL_DestroyAudioStream SDL_DestroyAudioStream_REAL
+#define SDL_CreateAndBindAudioStream SDL_CreateAndBindAudioStream_REAL
+#define SDL_LoadWAV_RW SDL_LoadWAV_RW_REAL
+#define SDL_LoadWAV SDL_LoadWAV_REAL
+#define SDL_MixAudioFormat SDL_MixAudioFormat_REAL
+#define SDL_ConvertAudioSamples SDL_ConvertAudioSamples_REAL
+#define SDL_GetSilenceValueForFormat SDL_GetSilenceValueForFormat_REAL