Ideas for SDL 3

[SDLBugzilla]

This bug report was migrated from our old Bugzilla tracker.

Reported in version: don't know
Reported for operating system, platform: All, All

Comments on the original bug report:

On 2020-01-22 15:55:25 +0000, David Demelier wrote:

Hi,

I already sent some ideas by email but I've been convinced by an individual on the IRC channel to do this on the bugzilla to get reviews.

Here's a list of things I'd love to see and implement (as a developer myself) for SDL 3.

Any feedback is welcomed.

Stricter coding, naming style.

For the moment there are high number of style issues in the API. Some symbols are SDL_lowerCased and some are SDL_UpperCased. Some are not even prefixed by SDL_.

Every functions that are tighed to a specific structure should:

• Be prefixed by its name: SDL_Foo (object), SDL_FooOpen, SDL_FooDestroy, SDL_FooUpdate, etc.
• Take the object as first argument: SDL_FooUpdate(SDL_Foo *, ...);

Getter and setters should be named as following:

• SDL_Namespace(Get|Set)What (e.g. SDL_Renderer(Get|Set)DrawColor)

Constructors and destructors should be named as following if applicable:

• SDL_NamespaceOpen (e.g. SDL_JoystickOpen)
• SDL_NamespaceDestroy (e.g. SDL_JoystickDestroy)

If objects are not meant to be dynamically allocated, the names "Init" and "Finish" or "Close" can also be used.

Proper semantic versioning.

One SDL 2.0.x version added sensor support, while it should be bugfix instead. The current versioning scheme makes too difficult to check what features were provided and when at a glance.

What did 2.0.1 provided? What 2.0.2 provided?

In the head of packagers, they feel like they are bugfixes while they've added new APIs!

The Semantic Versioning is the most appropriate versioning scheme for libraries.

• Major : massive breakage allowed in the API (not every year though, somewhat like every 5-6 years).
• Minor : improvements and new features added with API compatibility honored
• Patch : simple bugfixes

Simplify development process

At the moment there is no much information about the way to contribute to SDL. One can ping maintainer using patches via mail but are sometimes missed. Also they are linked to an individual and can not be reviewed by others.

Since SDL does not have a system for reviewing yet, I propose that a development mailing-list is re-opened and people could send their patch via hg email as the bugzilla is more tailored for bug reporting.

Removing useless platforms.

• arts: no longer used
• winrt: too, AFAIK

Fixing inconsistencies where some functions use plain primitives types rather than structs.

If we have structs, then functions should always operate on them. Since C99, compound literals makes life easier while passing temporaries to functions.

• SDL_SetRenderDrawColor takes 4 ints

• SDL_SetPaletteColor take a SDL_Color object

• SDL_RenderDrawLine takes 4 ints

• SDL_RenderSetClipRect takes a SDL_Rect

The color handling is sometimes in 4 ints, sometimes SDL_Color.

Getting rid of dozens of buildsystems to unique one: CMake.

There are just too many build systems in the tree and that is too complicated for users, developers and packagers. Also, having only one for a portable library that SDL is, makes difficult to merge all checks/operations in all build systems.

Also, lots of people do not rely on the SDL CMake configuration package files provided as autoconf does not install them. Having CMake only will simplify the integration and maintainance.

Use doxygen documentation to avoid outdated information on the wiki.

I've literally spent 3 hours to document the sensor API on the wiki. That's a big waste of time. SDL headers are already almost documented in doxygen, it should be completed with missing bits and the only source of truth.

Changing something in one enum results in editing the wiki as well.

Rename pkg-config files

The SDL pkg-config file is sdl2 while addons are SDL2_*.

Making addons first class citizen and built from the same source tree with proper naming.

The SDL addons feel they are separate projects as they still do not have any public visibility from the libsdl.org website. At a glance, a newcomer don't even know these libraries exist.

They have the same troubles as the above paragraphs (cmake, consistency, etc.).

I propose the simple inclusion of these addons with a new naming scheme for them and a simpler API. Also, they will be available as separate shared/static libraries controlled at build time. Thus, people who don't need SDL_mixer or SDL_ttf can simply not build/link theme.

SDL_ttf new API

Every functions start with SDL_Font.

• SDL_Font (struct)
• SDL_FontStyle (enum SDL_FONT_SOLID, SDL_FONT_SHADED, SDL_FONT_BLENDED)
• TTF_Init -> SDL_FontInit()
• TTF_OpenFont* -> SDL_FontOpen*
• TTF_(Get|Set)Font* -> SDL_Font(Get|Set)*
• TTF_FontHeight -> SDL_FontGetHeight
• TTF_FontAscent -> SDL_FontGetAscent
• TTF_FontDescent -> SDL_FontGetDescent
• TTF_FontLineSkip -> SDL_FontGetLineSkip
• TTF_FontFaces -> SDL_FontGetFaces
• TTF_GlyphIsProvided -> SDL_FontIsGlyphProvided
• TTF_GlyphMetrics -> SDL_FontGetGlyphMetrics
• TTF_SizeText -> Should be removed, UTF-8 is the standard
• TTF_SizeUTF8 -> SDL_FontTextMetrics
• TTF_SizeUNICODE -> Should be removed, UTF-16 is deprecated
• TTF_Render* -> SDL_FontRender(const char *, SDL_FontStyle) (UTF-8 only)

SDL_image new API

Every function start with SDL_Image.

• SDL_ImageFormat (enum SDL_IMAGE_(CUR|ICO|BMP|PNM|...))
• IMG_Init -> SDL_ImageInit()
• IMG_Load -> SDL_ImageOpen(const char *path)
• IMG_Load_RW -> SDL_ImageOpen_RW
• IMG_LoadTyped_RW -> SDL_ImageOpenTyped_RW(SDL_RWOps *, SDL_ImageFormat)
• IMG_is* -> SDL_ImageGetType (returns SDL_ImageFormat)

SDL_mixer new API

Basic functions start with SDL_Mixer.

• Mix_Init -> SDL_MixerInit
• Mix_OpenAudio -> SDL_MixerOpen
• Mix_CloseAudio -> SDL_MixerClose
• Mix_GetNumChunkDecoders -> SDL_MixerGetNumChunkDecoders
• Mix_GetChunkDecoder -> SDL_MixerGetChunkDecoder

Channel and groups functions

• Mix_AllocateChannels -> SDL_ChannelsAllocate
• Mix_ReserveChannels -> SDL_ChannelsReserve
• Mix_Group* -> SDL_ChannelGroup*
• Mix_HaltGroup -> SDL_ChannelGroupHalt
• Mix_Volume -> SDL_ChannelVolume
• Mix_PlayChannel -> SDL_ChannelPlay
• Mix_PlayChannelTimed -> SDL_ChannelPlayTimed
• Mix_FadeInChannel -> SDL_ChannelFadeIn
• Mix_FadeInChannelTimed -> SDL_ChannelFadeInTimed
• Mix_Pause -> SDL_ChannelPause
• Mix_Resume -> SDL_ChannelResume
• Mix_HaltChannel -> SDL_ChannelHalt
• Mix_ExpireChannel -> SDL_ChannelExpire
• Mix_FadeOutChannel -> SDL_ChannelFadeOut
• Mix_ChannelFinished -> SDL_ChannelHasFinished
• Mix_Playing -> SDL_ChannelIsPlaying
• Mix_Paused -> SDL_ChannelIsPaused
• Mix_FadingChannel -> SDL_ChannelGetFading
• Mix_GetChunk -> SDL_ChannelGetChunk

Chunk functions

• Mix_LoadWAV -> SDL_ChunkOpen
• Mix_LoadWAV_RW -> SDL_ChunkOpen_RW
• Mix_QuickLoad -> SDL_ChunkQuickOpen
• Mix_QuickLoad_RW -> SDL_ChunkQuickOpen_RW
• Mix_FreeChunk -> SDL_ChunkDestroy
• Mix_VolumeChunk -> SDL_ChunkGetVolume

Music functions

• Mix_GetNumMusicDecoders -> SDL_MusicGetNumDecoders
• Mix_GetMusicDecoder -> SDL_MusicGetDecoder
• Mix_LoadMUS -> SDL_MusicOpen
• Mix_FreeMusic -> SDL_MusicDestroy
• Mix_PlayMusic -> SDL_MusicPlay
• Mix_FadeInMusic -> SDL_MusicFadeIn
• Mix_FadeInMusicPos -> SDL_MusicFadeInPos
• Mix_HookMusic -> SDL_MusicHook
• Mix_VolumeMusic -> SDL_MusicVolume
• Mix_PauseMusic -> SDL_MusicPause
• Mix_ResumeMusic -> SDL_MusicResume
• Mix_RewindMusic -> SDL_MusicRewind
• Mix_SetMusicPosition -> SDL_MusicSetPosition
• Mix_SetMusicCMD -> SDL_MusicSetCommand
• Mix_HaltMusic -> SDL_MusicHalt
• Mix_FadeOutMusic -> SDL_MusicFadeOut
• Mix_HookMusicFinished -> SDL_MusicSetHookFinished
• Mix_GetMusicType -> SDL_MusicGetType
• Mix_PlayingMusic -> SDL_MusicIsPlaying
• Mix_PausedMusic -> SDL_MusicIsPaused
• Mix_FadingMusic -> SDL_MusicIsFading
• Mix_GetMusicHookData -> SDL_MusicGetHookFinished

Effect functions

• Mix_RegisterEffect -> SDL_EffectRegister
• Mix_UnregisterEffect -> SDL_EffectUnregister
• Mix_UnregisterAllEffects -> SDL_EffectUnregisterAll
• Mix_SetPostMix -> SDL_EffectSetPostMix
• Mix_SetPanning -> SDL_EffectSetPanning
• Mix_SetDistance -> SDL_EffectSetDistance
• Mix_SetPosition -> SDL_EffectSetPosition
• Mix_SetReverseStereo -> SDL_EffectSetReverseStereo

SDL_net

To my humble opinion, this library should be removed as they are many networking library in C including POSIX.

On 2020-01-23 02:56:03 +0000, Sam Lantinga wrote:

I agree with most of this feedback, and like the satellite library naming suggestions, thanks!

Some comments on the build system:

Not all platforms have CMake, and many developers don't have CMake installed. Windows developers should be able to use Visual Studio, Mac developers should be able to use Xcode. I should be able to use autoconf. :)

I'm fine with CMake being the recommended build environment, and even stripping out support for non-UNIX platforms from it, but I've run into enough problems with it over the years that I don't use CMake. Also, note that the official SDL windows binaries are built on Mac using mingw64, to integrate with build scripts and avoid C runtime dependencies, and that currently requires autotools.

On 2020-03-23 22:53:39 +0000, wrote:

Simplify development process

I think there should be more discussion on just moving the center of development to github / git. I'm aware that this has been proposed by many people over the years, but I feel it hasn't gotten the proper attention it needs.

Github or at least git, would make it much easier for people to contribute to the development of SDL.

On 2020-03-24 01:04:30 +0000, Ryan C. Gordon wrote:

(In reply to daegon.dhsk from comment # 2)

Github or at least git, would make it much easier for people to contribute
to the development of SDL.

This is a hard no from me, both to GitHub and git itself.

--ryan.

On 2020-03-24 01:15:27 +0000, wrote:

(In reply to Ryan C. Gordon from comment # 3)

(In reply to daegon.dhsk from comment # 2)

Github or at least git, would make it much easier for people to contribute
to the development of SDL.

This is a hard no from me, both to GitHub and git itself.

--ryan.

Could we get some details on the background?

On 2020-03-24 03:32:52 +0000, Ryan C. Gordon wrote:

(In reply to daegon.dhsk from comment # 4)

Could we get some details on the background?

Even if I didn't personally think git is a lousy system, Mercurial is working fine for us and changing it just introduces unnecessary friction.

As for GitHub: we have been burned by cloud providers several times over the past 20 years, and have spent significant effort engineering our infrastructure so we own all of it. Becoming reliant on an unnecessary for-profit company for the most crucial piece of our workflow is not something we're willing to do.

--ryan.

On 2020-03-24 08:15:06 +0000, David Demelier wrote:

(In reply to daegon.dhsk from comment # 2)

Simplify development process

I think there should be more discussion on just moving the center of
development to github / git. I'm aware that this has been proposed by many
people over the years, but I feel it hasn't gotten the proper attention it
needs.

Github or at least git, would make it much easier for people to contribute
to the development of SDL.

I can't understand this hype to request people to move to Git. Git is by far much more complicated than Mercurial so I'd like to know what's “easier” for you to contribute.

If by easier you mean that you can send a pull request, please not that sending a patch is by far much easier:

hg clone http://hg.libsdl.org/SDL && cd SDL
vim
hg ci
hg export OR hg email

That's it.

You can't come to a project and ask them to change their tooling, this is a subjective material. I don't like Git but I don't ask projects to move from Git to Mercurial. I don't like meson and I don't request projects that use meson to switch to CMake. I can go for a while.

The only way we could improve the contributing process for SDL is to provide a detailed documentation because for now there are not that much. So some people send emails and some tasks on bugzilla. We need a unified, detailed process. That's it.

On 2020-04-02 22:25:09 +0000, David Ludwig wrote:

(In reply to David Demelier from comment # 6)

If by easier you mean that you can send a pull request, please not that
sending a patch is by far much easier:

hg clone http://hg.libsdl.org/SDL && cd SDL
vim
hg ci
hg export OR hg email

That's it.

Wait, vim is now part of the easy route?! (and I like vim, for some things at least) ;-)

In all seriousness, a move to git sounds ok to me, though not one to GitHub and its partially-closed nature. I find git's overall ecosystem to be MUCH nicer than Mercurial's (enough that I am willing to argue that Mercurial isn't always the "easiest" option, not any more at least), and would probably welcome a move to git repos. I have, within the past few years, lost Mercurial support in some valuable-to-me tools (BitBucket, especially), and finding good, alternative tooling hasn't always been easy.

As for the initial suggestions, I'm in favor of a lot of it! I especially like the idea of iterating on SDL's function names. Having a scheme along the lines of SDL_ seems very helpful with regards to editor auto-completion.

I'd like to add one suggestion with regards to naming: include the major version number in the prefix. I.e. SDL3.h, SDL3_RenderSetDrawColor, etc. It would make SDL 3.x detection be a matter of finding a header, rather than finding a header and parsing it, which might not always be possible (with C++'s __has_include, for example). It would also help make it possible to distinguish SDL 1.x and 2.x code from 3.x code, which I could see helping if and when porting stuff to 3.x.

Regarding dropping WinRT, it's my understanding that Xbox One still requires using those APIs. Unless that changes, I think removing that support would be bad (though, that platform's SDL code could definitely use some improvement, with at least some pruning of older, WinRT SDK support).

Regarding build-systems, I like the idea of better CMake integration, but I would like to see file-globbing of SDL's src directory be an option, too, at least for platforms where this is possible. (One of these days, I should finish my support for this. I've had prototypes working on Apple-platforms, as well as Windows, at one point or another).

As for including satellite libraries in SDL-proper, this makes me leery as it seems like it would introduce a lot of additional dependencies in SDL, which is already inherently complex due to the number of platforms it supports. Having naming changes within them does sound nice, and perhaps possible without needing to include them in SDL itself.

On 2020-05-26 07:50:59 +0000, Jan Niklas Hasse wrote:

Windows developers should be able to use Visual Studio, Mac developers should be able to use Xcode.

Both can be generated using CMake :)

On 2020-11-28 11:36:22 +0000, Dominik Reichardt wrote:

Windows developers should be able to use Visual Studio, Mac developers should be able to use Xcode.

Both can be generated using CMake :)

I have only tried a few times but those projects all didn't generate a working xcode project. No idea if this is a problem with their CMake files but if you have to work extensively on the Xcode project file each time you generate it from code, then it is no good, IMO worse than a partially working included one.

So, when I see there is only CMake, I try to find whether someone else already built an Xcode project file or just turn away and don't bother.

Generation of the unix stuff generally works though.

On 2020-11-28 11:39:12 +0000, Jan Niklas Hasse wrote:

I have only tried a few times but those projects all didn't generate a working xcode project.

What do you mean by "those projects"?

On 2020-11-28 11:44:23 +0000, Dominik Reichardt wrote:

I have only tried a few times but those projects all didn't generate a working xcode project.

What do you mean by "those projects"?

the projects that had only Cmake and I tried to generate the Xcode project with

On 2020-11-28 11:59:54 +0000, Jan Niklas Hasse wrote:

Ah I see. I think some projects don't take Xcode into account and use some unidiomatic CMake constructs that break it.

It is definitely possible though and works great in my projects. It's a good idea to add a CI job which generates and builds with -GXcode.

[markand]

Since I was the author of the proposal on the bugzilla but not able to edit this one, let's summarize and remove irrelevant stuff (the hard no to move to git is no longer valid).

---

Stricter coding, naming style.

For the moment there are high number of style issues in the API. Some symbols are SDL_lowerCased and some are SDL_UpperCased. Some are not even prefixed by SDL_.

Every functions that are tighed to a specific structure should:

Be prefixed by its name: SDL_Foo (object), SDL_FooOpen, SDL_FooDestroy, SDL_FooUpdate, etc.
Take the object as first argument: SDL_FooUpdate(SDL_Foo *, ...);

Getter and setters should be named as following:

• SDL_Namespace(Get|Set)What (e.g. SDL_Renderer(Get|Set)DrawColor)

Constructors and destructors should be named as following if applicable:

• SDL_NamespaceOpen (e.g. SDL_JoystickOpen)
• SDL_NamespaceDestroy (e.g. SDL_JoystickDestroy)

If objects are not meant to be dynamically allocated, the names "Init" and "Finish" or "Close" can also be used.

Proper semantic versioning.

SDL 2.0.9 version added sensor support, while it should be bugfix instead. The current versioning scheme makes too difficult to check what features were provided and when at a glance.

What did 2.0.1 provided? What 2.0.2 provided?

In the head of packagers, they feel like they are bugfixes while they've added new APIs!

The Semantic Versioning is the most appropriate versioning scheme for libraries.

• Major: massive breakage allowed in the API (not every year though, somewhat like every 5-6 years).
• Minor: improvements and new features added with API compatibility honored
• Patch: simple bugfixes

Removing useless platforms.

• arts: no longer used
• winrt: too, AFAIK

Fixing inconsistencies

If we have structs, then functions should always operate on them. Since C99, compound literals makes life easier while passing temporaries to functions.

• SDL_SetRenderDrawColor takes 4 ints
• SDL_SetPaletteColor take a SDL_Color object
• SDL_RenderDrawLine takes 4 ints
• SDL_RenderSetClipRect takes a SDL_Rect

The color handling is sometimes in 4 ints, sometimes SDL_Color.

Getting rid of dozens of buildsystems to unique one: CMake.

There are just too many build systems in the tree and that is too complicated for users, developers and packagers. Also, having only one for a portable library that SDL is, makes difficult to merge all checks/operations in all build systems.

Also, lots of people do not rely on the SDL CMake configuration package files provided as autoconf does not install them. Having CMake only will simplify the integration and maintainance.

Use doxygen documentation to avoid outdated information on the wiki

I've literally spent 3 hours to document the sensor API on the wiki. That's a big waste of time. SDL headers are already almost documented in doxygen, it should be completed with missing bits and the only source of truth.

Changing something in one enum results in editing the wiki as well.

Rename pkg-config files

The SDL pkg-config file is sdl2 while addons are SDL2_*.

Making addons first class citizen and built from the same source tree with proper naming

The SDL addons feel they are separate projects as they still do not have any public visibility from the libsdl.org website. At a glance, a newcomer don't even know these libraries exist.

They have the same troubles as the above paragraphs (cmake, consistency, etc.).

I propose the simple inclusion of these addons with a new naming scheme for them and a simpler API. Also, they will be available as separate shared/static libraries controlled at build time. Thus, people who don't need SDL_mixer or SDL_ttf can simply not build/link theme.

SDL_ttf new API

Every functions start with SDL_Font.

• SDL_Font (struct)
• SDL_FontStyle (enum SDL_FONT_SOLID, SDL_FONT_SHADED, SDL_FONT_BLENDED)
• TTF_Init -> SDL_FontInit()
• TTF_OpenFont* -> SDL_FontOpen*
• TTF_(Get|Set)Font* -> SDL_Font(Get|Set)*
• TTF_FontHeight -> SDL_FontGetHeight
• TTF_FontAscent -> SDL_FontGetAscent
• TTF_FontDescent -> SDL_FontGetDescent
• TTF_FontLineSkip -> SDL_FontGetLineSkip
• TTF_FontFaces -> SDL_FontGetFaces
• TTF_GlyphIsProvided -> SDL_FontIsGlyphProvided
• TTF_GlyphMetrics -> SDL_FontGetGlyphMetrics
• TTF_SizeText -> Should be removed, UTF-8 is the standard
• TTF_SizeUTF8 -> SDL_FontTextMetrics
• TTF_SizeUNICODE -> Should be removed, UTF-16 is deprecated
• TTF_Render* -> SDL_FontRender(const char *, SDL_FontStyle) (UTF-8 only)

SDL_image new API

Every function start with SDL_Image.

• SDL_ImageFormat (enum SDL_IMAGE_(CUR|ICO|BMP|PNM|...))
• IMG_Init -> SDL_ImageInit()
• IMG_Load -> SDL_ImageOpen(const char *path)
• IMG_Load_RW -> SDL_ImageOpen_RW
• IMG_LoadTyped_RW -> SDL_ImageOpenTyped_RW(SDL_RWOps *, SDL_ImageFormat)
• IMG_is* -> SDL_ImageGetType (returns SDL_ImageFormat)

SDL_mixer new API

Basic functions start with SDL_Mixer.

• Mix_Init -> SDL_MixerInit
• Mix_OpenAudio -> SDL_MixerOpen
• Mix_CloseAudio -> SDL_MixerClose
• Mix_GetNumChunkDecoders -> SDL_MixerGetNumChunkDecoders
• Mix_GetChunkDecoder -> SDL_MixerGetChunkDecoder

Channel and groups functions

• Mix_AllocateChannels -> SDL_ChannelsAllocate
• Mix_ReserveChannels -> SDL_ChannelsReserve
• Mix_Group* -> SDL_ChannelGroup*
• Mix_HaltGroup -> SDL_ChannelGroupHalt
• Mix_Volume -> SDL_ChannelVolume
• Mix_PlayChannel -> SDL_ChannelPlay
• Mix_PlayChannelTimed -> SDL_ChannelPlayTimed
• Mix_FadeInChannel -> SDL_ChannelFadeIn
• Mix_FadeInChannelTimed -> SDL_ChannelFadeInTimed
• Mix_Pause -> SDL_ChannelPause
• Mix_Resume -> SDL_ChannelResume
• Mix_HaltChannel -> SDL_ChannelHalt
• Mix_ExpireChannel -> SDL_ChannelExpire
• Mix_FadeOutChannel -> SDL_ChannelFadeOut
• Mix_ChannelFinished -> SDL_ChannelHasFinished
• Mix_Playing -> SDL_ChannelIsPlaying
• Mix_Paused -> SDL_ChannelIsPaused
• Mix_FadingChannel -> SDL_ChannelGetFading
• Mix_GetChunk -> SDL_ChannelGetChunk

Chunk functions

• Mix_LoadWAV -> SDL_ChunkOpen
• Mix_LoadWAV_RW -> SDL_ChunkOpen_RW
• Mix_QuickLoad -> SDL_ChunkQuickOpen
• Mix_QuickLoad_RW -> SDL_ChunkQuickOpen_RW
• Mix_FreeChunk -> SDL_ChunkDestroy
• Mix_VolumeChunk -> SDL_ChunkGetVolume

Music functions

• Mix_GetNumMusicDecoders -> SDL_MusicGetNumDecoders
• Mix_GetMusicDecoder -> SDL_MusicGetDecoder
• Mix_LoadMUS -> SDL_MusicOpen
• Mix_FreeMusic -> SDL_MusicDestroy
• Mix_PlayMusic -> SDL_MusicPlay
• Mix_FadeInMusic -> SDL_MusicFadeIn
• Mix_FadeInMusicPos -> SDL_MusicFadeInPos
• Mix_HookMusic -> SDL_MusicHook
• Mix_VolumeMusic -> SDL_MusicVolume
• Mix_PauseMusic -> SDL_MusicPause
• Mix_ResumeMusic -> SDL_MusicResume
• Mix_RewindMusic -> SDL_MusicRewind
• Mix_SetMusicPosition -> SDL_MusicSetPosition
• Mix_SetMusicCMD -> SDL_MusicSetCommand
• Mix_HaltMusic -> SDL_MusicHalt
• Mix_FadeOutMusic -> SDL_MusicFadeOut
• Mix_HookMusicFinished -> SDL_MusicSetHookFinished
• Mix_GetMusicType -> SDL_MusicGetType
• Mix_PlayingMusic -> SDL_MusicIsPlaying
• Mix_PausedMusic -> SDL_MusicIsPaused
• Mix_FadingMusic -> SDL_MusicIsFading
• Mix_GetMusicHookData -> SDL_MusicGetHookFinished

Effect functions

• Mix_RegisterEffect -> SDL_EffectRegister
• Mix_UnregisterEffect -> SDL_EffectUnregister
• Mix_UnregisterAllEffects -> SDL_EffectUnregisterAll
• Mix_SetPostMix -> SDL_EffectSetPostMix
• Mix_SetPanning -> SDL_EffectSetPanning
• Mix_SetDistance -> SDL_EffectSetDistance
• Mix_SetPosition -> SDL_EffectSetPosition
• Mix_SetReverseStereo -> SDL_EffectSetReverseStereo

SDL_net

To my humble opinion, this library should be removed as they are many networking library in C including POSIX.

[slouken]

Here are my thoughts...

Stricter coding, naming style.

Generally agreed. We'll need to create an sdl2-compat library similar to sdl12-compat that preserves the old ABI for older programs while continuing new development in sdl3 with a more consistent API.

Proper semantic versioning.

We'd have to look at how library versioning is done on Linux. We need to guarantee that older binaries continue to run with newer versions of SDL, and the current versioning system does that. The version is actually generated by using the scheme in autotools:

# Making releases:
# Edit include/SDL_version.h and change the version, then:
#   SDL_MICRO_VERSION += 1;
#   SDL_INTERFACE_AGE += 1;
#   SDL_BINARY_AGE += 1;
# if any functions have been added, set SDL_INTERFACE_AGE to 0.
# if backwards compatibility has been broken,
# set SDL_BINARY_AGE and SDL_INTERFACE_AGE to 0.

and it turns out that this guarantees binary compatibility in the way that we need.

In terms of knowing when functions have been added, we now include that information in the headers and wiki so it's easy to find.

Removing useless platforms.

WinRT is still used by the UWP code for Windows Store games and Xbox, so it will continue to be relevant.

Fixing inconsistencies

If we have structs, then functions should always operate on them. Since C99, compound literals makes life easier while passing temporaries to functions.

We should review what compilers and platforms are still supported. I'm still occasionally surprised that people are still using platforms that require C89 code. But I agree we should be consistent here, with an eye toward the most efficient and easy to use interfaces.

Getting rid of dozens of buildsystems to unique one: CMake.

I think we should bite the bullet and just pick CMake over autotools. Maintaining two separate configuration and build systems is too high a tax, and enough people (and platform maintainers) are using CMake that it seems like the right choice for SDL 3. That said, we should still keep the Visual Studio and Xcode projects for people who are more comfortable using the IDE's.

Use doxygen documentation to avoid outdated information on the wiki

This is already done. Ryan has created a bridge between the headers and wiki so each side is automatically updated by changes in the other side.

Rename pkg-config files

👍

Making addons first class citizen and built from the same source tree with proper naming

The problem here, and the reason why the SDL addons have lagged behind in terms of releases, is these depend on a lot of third party libraries that are time consuming to build and maintain in-tree. git submodules may make this easier though, so this is definitely worth reviewing. The ability to easily add modules to your project with CMake makes this much more viable in the future.

I generally agree with the naming suggestions for the third party APIs above.

SDL_net

Agreed. There are lots more tools out there now than there were when this library was created.

[markand]

Proper semantic versioning.

We'd have to look at how library versioning is done on Linux. We need to guarantee that older binaries continue to run with newer versions of SDL, and the current versioning system does that. The version is actually generated by using the scheme in autotools:

Well semantic versioning does not really care about ABI, it only cares about API in the sense that a program that uses a specific minor version may get new features but with never incompatibilities.

Fixing inconsistencies

If we have structs, then functions should always operate on them. Since C99, compound literals makes life easier while passing temporaries to functions.

We should review what compilers and platforms are still supported. I'm still occasionally surprised that people are still using platforms that require C89 code. But I agree we should be consistent here, with an eye toward the most efficient and easy to use interfaces.

The C99 compound literals are for the user side, SDL does not need to have C99 support. This just means that if we take structures as argument the user can do:

SDL_DoSomethingWithARectangle(&(const SDL_Rect){.w = 10 }));

Getting rid of dozens of buildsystems to unique one: CMake.

I think we should bite the bullet and just pick CMake over autotools. Maintaining two separate configuration and build systems is too high a tax, and enough people (and platform maintainers) are using CMake that it seems like the right choice for SDL 3. That said, we should still keep the Visual Studio and Xcode projects for people who are more
comfortable using the IDE's.

CMake generates proper Visual Studio and Xcode projects. Visual Studio even has a nice integration.

Making addons first class citizen and built from the same source tree with proper naming

The problem here, and the reason why the SDL addons have lagged behind in terms of releases, is these depend on a lot of third party libraries that are time consuming to build and maintain in-tree. git submodules may make this easier though, so this is definitely worth reviewing. The ability to easily add modules to your project with CMake makes this much more viable in the future.

We don't incorporate third party libraries. That's generally a very bad thing to do because of ABI incompatibilities (and there are too much systems and architectures). This just means that we conditionally add support to a feature if present. For example, if user selects MP3 support, then SDL_mixer will be linked against the system mad/mpg321 library. Nothing more :)

Once SDL targets the 3 version, please write a ping here so that I can start massive refactoring :)

[DanielGibson]

Make SDL_main a header-only lib

Right now using SDL_main can be painful, especially with MinGW: There you have to link -lmingw32 -lSDL2main -lSDL2 in that exact order (you can add other libs in between, but libmingw32 must be before libSDL2main, and libSDL2main must be before libSDL2) - especially getting libmingw32 there isn't trivial, see

SDL/sdl2-config.cmake.in

Lines 27 to 41 in 1bfefb5

	if(WIN32 AND NOT MSVC)
	# MINGW needs very special handling, because the link order must be exactly -lmingw32 -lSDL2main -lSDL2
	# for it to work at all (and -mwindows somewhere); a normal SHARED IMPORTED or STATIC IMPORTED library always puts itself first
	# so handle this like a header-only lib and put everything in INTERFACE_LINK_LIBRARIES
	add_library(SDL2::SDL2 INTERFACE IMPORTED)
	set_target_properties(SDL2::SDL2 PROPERTIES
	INTERFACE_INCLUDE_DIRECTORIES "${SDL2_INCLUDE_DIRS}"
	INTERFACE_LINK_LIBRARIES "-L${SDL2_LIBDIR} -lSDL2")
	add_library(SDL2::SDL2main INTERFACE IMPORTED)
	set_target_properties(SDL2::SDL2main PROPERTIES
	INTERFACE_LINK_LIBRARIES "-L${SDL2_LIBDIR} -lmingw32 -lSDL2main -mwindows")
	else() # (not WIN32) or MSVC

I think this happens because main() (or WinMain() or whatever) being in a static lib (instead of a source file that gets compiled as part of the build, or a .o/.obj) seems to confuse MinGW, which otherwise would automagically link libmingw32.

Another (also Windows-specific) problem is that .lib files generated by MinGW don't work with modern MSVC versions ("module unsafe for SAFESEH"). For the SDL2.lib only used for linking the DLL it's not that bad, because it can relatively easily be generated from SDL2.dll (create a .def with mingw's gendef SDL2.dll and then use lib.exe /machine:x86 /def:SDL2.def /out:SDL2.lib in the VS developer console to generate the lib) - but that doesn't help for SDL2main.lib, which is a proper static lib and not just this stub-thing used on Windows to link DLLs.
So binary builds of SDL2 for Windows that have been built with MinGW aren't really compatible with MSVC, mostly because of SDL2main.

These problems would vanish if SDL2main was a header-only lib that you just #include in your source file that implements int main(int argc, char** argv) (and only there). It could still do its #define main SDL_main trick, and it could contain the platform-specific SDL_main code (or nothing at all for most of the platforms which don't use it). SDL.h wouldn't #include <SDL_main.h> anymore (maybe it shouldn't do that either way).
Like SDL_config.h it would be generated when SDL is built (or probably just copied from some dir in src/ to include/).

As a nice side-effect, it would make it clearer when it is used an when not:
Right now if you don't want to use it on e.g. Windows, you need to #define SDL_MAIN_HANDLED before #include <SDL.h> (or in your build process), which is not obvious - with SDL_main as a header-only lib, you'd just do nothing, and do #include <SDL_main.h> if you want to use it.
Also I think that right now if you have any variable (or function, enum member, ...) called main - in any file that just includes SDL.h, not just the one with main() in it! - and that #define main SDL_main is active on your platform, that variable will be renamed as well, which could lead to confusion..

Furthermore, it would make it easier to copy the SDL_main implementation into your own source and adjust it to your needs.

[slouken]

Make SDL_main a header-only lib

I like this idea. @icculus, what do you think? Is this something we can implement in 2.0.22?

[icculus]

I like the idea but would keep this in the SDL 3 bucket.

[slouken]

Another idea for SDL3:

• Remove all the complexity around removing API entry points. You can disable subsystems, but the API entry points will remain, with dummy implementations.

[slouken]

IMPORTANT: We will also need sdl20-compat from the very beginning.

[DanielGibson]

BTW, are there plans for a SDL2.1 before SDL3?
(If so, making SDL_main a header-only lib only requires very minor adjustments to applications using SDL2 - adding one #include in one file - so it IMO could be done in 2.1)

[slouken]

SDL3 is the next major ABI breaking revision - what we previously were calling SDL 2.1.

[icculus]

So I'm just catching up on this, so I wanted to throw in my current opinions.

I want to be clear that when suggesting big changes my instinct is to say no, and--as you can see from my "hard no" about GitHub--I don't make all the decisions and sometimes it turns out I'm proven wrong.

Stricter coding, naming style

I agree that SDL2 is extremely inconsistent in this regard, and we should definitely clean that up for SDL3, but I do not think it has to be as rigid as SDL_SubsystemVerbSubject.

Semantic versioning

SDL versioning can change, but semantic versioning is deeply overrated in my opinion.

We tend to never break even minor interfaces before we decide to change everything at once, and we do this less than once a decade in general. In the meantime, we add stuff all the time and constantly fix bugs and occasionally we bundle this up as production ready. We don't generally put out releases more than a few times a year.

Please do not reply with how the semver philosophy should be applied to this. It's just dogma, as far as I'm concerned.

Remove useless platforms

Every time I try to get rid of a platform or backend, someone pops up to say they still need it.

For various backends, this is largely harmless, because they can be ignored and even bitrot without a serious cost to the project.

But even things like Sony PSP and OS/2 have active users and maintainers. A lot of things would be hard to delete, is all I'm saying.

Arts can definitely go, though. :)

Build systems

I would love to drop to just CMake (or an equivalent, if there's a better option), but there is a value in telling people they can just double-click the Visual Studio project file and build. Even though CMake can generate vs project files, this adds friction for the average windows and Mac developer.

Between CMake and autotools though, CMake sucks less and we frequently have issues where we have to fix problems in one or the other, so dumping autotools is okay with me.

It might be interesting to find a way to automate this on Windows/Mac, so the user double clicks a small included .exe and it gets CMake installed if necessary and generates the project files.

Use doxygen documentation to avoid outdated information on the wiki

This is done. Changes to Doxygen comments in the headers automatically generate Wiki changes now and vice-versa. It generates manpages now, too!

This doesn't cover anything but functions...structs and stuff are not bridged, but this can change.

Making addons first class citizen and built from the same source tree with proper naming

100% no.

Get rid of SDL_net

100% yes.

[icculus]

Here's an old Trello board about ideas for future improvements to SDL that got propped up at some point, I think to collect stuff that was mentioned around other places. Not all of it is still relevant (or was ever necessarily good)...

https://trello.com/b/sXcrlXCD/sdl-wishlist

...but it's probably worth sifting through. I've made it read-only to prevent the discussion from migrating to there.

[mkalte666]

I might have missed mention of it, but for an abi breaking revision i would love to see a more consistent access to platform-dependent things.

The main thing that made me think about this was this issue over here (which, i realize, is another shameless bump, sorry x.x): #3360

The most use out of this would be in the rendering system - access window handles for video, texture and context access for the renderer.

Where to draw draw the line though?
While i never needed access to the stuff governing the event loop it might be easy to argue "hey, the rendering system got functions to pull out everthing from opengl to vulkan, we want it too!", and i don't know if thats a path one should walk.