diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index 3e7468cf3e..7f1fd42cd8 100644 --- a/include/SDL3/SDL_audio.h +++ b/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); diff --git a/src/audio/SDL_wave.c b/src/audio/SDL_wave.c index 9a3c3ea754..e7e5fc0327 100644 --- a/src/audio/SDL_wave.c +++ b/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); +} + diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym index 4cd53c2d68..e4da9c8d37 100644 --- a/src/dynapi/SDL_dynapi.sym +++ b/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: *; }; diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h index 6d623744b5..029c9b0f28 100644 --- a/src/dynapi/SDL_dynapi_overrides.h +++ b/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