Migrating to SDL_sound 3.0

SDL_sound 3.0 (aka "SDL3_sound") is almost identical in API to previous releases. In fact, most of the API is identical to the original 1.0 release! To keep migration simple, we didn't do a full modernization pass on the API, renaming functions, moving true/false "int" return values to "bool", etc.

There were extremely minor changes necessitated by the move to SDL3, however, and those are listed here.

SDL3_sound requires SDL3. It relies on features that are new to SDL3, both internally and in the public API, so if your project is on SDL 1.2 or SDL2, you'll have to move your project to SDL3 at the same time.

Including SDL3_sound

The proper way to include SDL3_sound's header is:

#include <SDL3_sound/SDL_sound.h>

Like SDL3, the new convention is to use <> brackets and a subdirectory.

SDL_sound.h used to be in the same directory as SDL_sound's source code. Now it is in a separate "include" directory. If you are working with the SDL_sound source tree directly, you will have to update the paths in your project files to accomodate this.

Versioning

Versions are now bits packed into a single int instead of a struct, using SDL3's usual magic for unpacking these. We did change this to match SDL3 conventions.

• SOUND_VER_MAJOR => SDL_SOUND_MAJOR_VERSION
• SOUND_VER_MINOR => SDL_SOUND_MINOR_VERSION
• SOUND_VER_PATCH => SDL_SOUND_MICRO_VERSION
• Sound_Version => Just use int instead of this removed struct.
• SOUND_VERSION(&v) => v = SDL_SOUND_VERSION;
• Sound_GetLinkedVersion(&v) => v = Sound_Version(); (yes, this is the same symbol that used to be a struct.)

Calling conventions

SNDDECLSPEC was removed, using SDL3's standard symbol instead. This is only important if, for some reason, your app decided to use this to declare its own functions, which is unlikely. A simple search/replace or #define will solve this problem.

• SNDDECLSPEC => SDL_DECLSPEC

SDL_RWops vs SDL_IOStream

SDL3 removed the SDL_RWops interface, replacing it with SDL_IOStream. Largely they are functionally equivalent, and in terms of SDL_sound's public API, there is only one place where it is directly used: Sound_NewSample().

Simply replace your SDL_RWops with SDL_IOStreams, as you would have to do moving to SDL3 anyhow, or use one of the other Sound_NewSample*() functions, which will manage SDL_IOStreams internally on your app's behalf.

Audio format information

Sound_AudioInfo is gone, replaced with the standard SDL_AudioSpec, which is almost exactly equivalent in SDL3. The individual types are different (ints instead of Uint32), so don't memcpy between them, but the fields of the two structs are otherwise functionally equivalent and in the same order.

This affects certain fields in Sound_Sample, and the parameters to the various Sound_NewSample*() functions.

A simple search/replace of Sound_AudioInfo => SDL_AudioSpec, or a #define of the former to the latter, will likely work.

That's all!

If you've run into a problem not covered here, please let us know through the bug tracker.

Thanks!