Announcing SDL 3.1.3 Stable ABI Preview!

slouken · October 4, 2024, 9:00pm

Announcing the SDL 3.1.3 Stable ABI Preview!

We have lots of bugs to fix before the 3.2.0 stable release, but SDL 3.0 has been battle tested by millions of people in DOTA, CS2 and Steam, and is ready for your eyes!

We have many many people to thank on the road to get here, but I’d like to call out special thanks to:

@slouken and @icculus, lead developers
@flibitijibibo, @thatcosmonaut, and @TheSpydog, the GPU API team
@1bsyl, @0x1F9F1, @Kontrabant, and @Semphriss, for general development and major contributions
@madebr, our CMake wizard and build guru
@smcv, for words of wisdom and sanity checks
@sezero and @Sackzement, for dotting all our i’s and crossing all our t’s
… and literally hundreds of other people who have contributed feedback, pull requests, and bug reports, helping make SDL what it is today.

If you’re migrating from SDL2, we’ve put a comprehensive list of changes and migration tips here:

github.com

libsdl-org/SDL/blob/main/docs/README-migration.md

# Migrating to SDL 3.0

This guide provides useful information for migrating applications from SDL 2.0 to SDL 3.0.

Details on API changes are organized by SDL 2.0 header below.

The file with your main() function should include <SDL3/SDL_main.h>, as that is no longer included in SDL.h.

Functions that previously returned a negative error code now return bool.

Code that used to look like this:
```c
    if (SDL_Function() < 0 || SDL_Function() == -1) {
        /* Failure... */
    }
```
or
```c
    if (SDL_Function() == 0) {
        /* Success... */

This file has been truncated. show original

Here are some of the highlights of what’s new in SDL 3.0:

Extremely good documentation: We’ve spent a ton of effort writing and revising the API reference.
Example programs to get you started, running in your web browser!
More consistent API naming conventions. Everything is named consistently across the API now, instead of different subsystems taking different approaches. Also, we’ve tended toward more descriptive names for things in SDL3.
GPU API: access to modern 3D rendering and GPU compute in a cross-platform way.
Dialog API: access to system file dialogs (file and folder selection UI for opening/saving).
Filesystem API: simple directory management and globbing, access to topic-specific user folders.
Storage API: Abstract interface to platform-specific storage.
Camera API: access to webcams.
Main Callbacks: optionally run your program from callbacks instead of main().
Pen API: access to pens (like Wacom tablets and Apple Pencil, etc).
Logical audio devices: different parts of an app can get their own unique audio device to use.
Audio streams: handle buffering, converting, resampling, mixing, channel mapping, pitch, and gain. Bind to an audio device and go!
Default audio devices: SDL3 will automatically manage migrating to new physical hardware as devices are plugged in, ripped out, or changed.
Properties API: fast, flexible dictionaries of name/value pairs.
Process API: Spawn child processes and communicate with them in various ways.
Colorspace support: Surfaces and the renderer, etc, can manage multiple colorspaces.
The Clipboard API can support any data type (SDL2 only handled text), and apps can provide data in multiple formats upon request in a provided callback.
Better keyboard input, for all your keypress needs.
Customizable virtual keyboards on iOS and Android.
High DPI support is dramatically improved over SDL2.
App metadata API for letting SDL report things about your app correctly (like in the About dialog on macOS, etc).
Read/write thread locks, to let multiple threads access rarely-changing data in parallel.
Init State to help with multiple threads that might need to initialize something on-demand without racing.

Please let us know what you think, and report any issues on GitHub:

Levo · October 5, 2024, 3:27am

One thing that bothers me is most of the functions I use want a SDL_FRect, except SDL_SetRenderClipRect. Can we get SDL_SetRenderClipFRect?

slouken · October 5, 2024, 5:08am

Clipping (and viewport) works on pixels in the framebuffer, so they naturally use integer values.

You can write a 3 line wrapper function for your code that does this yourself, and you’ll have control over the rounding modes that are used.

cottonears · October 6, 2024, 6:18pm

Amazing news, thank you!

Lord-of-Eldwood · October 7, 2024, 3:11pm

What’s the status of SDL_GPU on Emscripten? This should be possible through WebGPU, but I noticed that WGSL, the WebGPU shading language, is not among the options for SDL_GPUShaderFormat.

Luke_A_Guest · October 15, 2024, 12:52pm

What’s happening with the portable shader compiler and api?

slouken · November 1, 2024, 10:40pm

We’ve updated the SDL 3.0 stable API preview!

Levo · November 3, 2024, 9:48pm

Do you want us to report bugs? Last time I tried there was flickering on window startup (didn’t maximize before being shown). I can test the latest if you want reports

slouken · November 4, 2024, 12:30am

Of course!
Issues · libsdl-org/SDL

Levo · November 5, 2024, 10:22pm

I imagine this is known, and I don’t plan on making GH anytime soon

linux x11 xfce doesn’t show the windows as fullscreen at start up. You can also see the top left painted with the original body. It looks like this for about 18frames/300ms and IIRC it takes ~300ms for gl on x11 to initialize so it might be related to that

https://i.imgur.com/81A35J6.jpeg

Mathias · November 6, 2024, 7:39am

Could this be the same problem I have under Mint Cinnamon?
When I start an SDL3 program, the window always appears briefly in the usual X11 position until it moves.

slouken · January 8, 2025, 1:47am

We’ve updated the SDL 3.0 stable API preview!