Announcing the SDL 3.1.0 Preview Release

slouken · March 24, 2024, 2:49pm

The preview release of the new SDL 3.0 API is now available!
Release 3.1.0 Preview · libsdl-org/SDL (github.com)

The ABI hasn’t been locked down yet, but it’s fairly stable and feedback is welcome!

Check out README-migration.md for details on API changes since SDL 2.0, and tips on transitioning your code from SDL2 code to SDL3.

There have been too many changes to list them all, but here are some of the highlights:

The API has been significantly reworked to be easier to use and more consistent
The 2D rendering API now has support for more advanced colorspaces and HDR rendering
The 2D rendering API now has a Vulkan backend
An example of hardware accelerated video playback using ffmpeg has been added in test/testffmpeg.c
The shaped window API has been replaced with transparent windows
Time and date functions have been added in SDL_time.h
Support for webcam video capture has been added in SDL_camera.h
Support for handling pens and tablets has been added in SDL_pen.h
Support for file open and save dialogs has been added in SDL_dialog.h
Cross-platform functions for working with files and directories are available in SDL_filesystem.h
A cross-platform abstraction for working with user and game data has been added in SDL_storage.h
Handling of main() has been moved to a header library and an optional callback-based program flow is available
Support for simple object properties has been added in SDL_properties.h. These properties are available on many SDL objects, and can be used for more advanced functionality.

Please let us know about issues and feedback at: Issues · libsdl-org/SDL · GitHub

The development team is focused on code, moving towards the final release, and we would love volunteers to help improve the documentation. Please send e-mail to slouken@libsdl.org if you’d like to help out!

Finally, a giant thank you to all the people who have contributed code and feedback to the SDL 3.0 improvements!

anon914446 · March 25, 2024, 4:29pm

I can’t tell you how much I’ve wanted this!

anon914446 · March 30, 2024, 4:57am

The new setup for creating shaped windows feels more solid this way. (Code below is reworked from SDL/test/testshape.c to be less verbose, but there’s still some cool stuff in the original testshape.c file to check out such as the hitTest callback functionality and loading an image from data held in a cString.)

#include <SDL3/SDL.h>
#include <SDL3/SDL_image.h>

int main()
{
        uint32_t initFlags = SDL_INIT_VIDEO | SDL_INIT_AUDIO | SDL_INIT_EVENTS;
        SDL_Init(initFlags);
        IMG_Init(IMG_INIT_PNG)
        uint32_t windowFlags = SDL_WINDOW_HIDDEN | SDL_WINDOW_TRANSPARENT | SDL_WINDOW_BORDERLESS;
        SDL_Surface * shapeSurface = IMG_Load("windowShape.png");
        SDL_Window * win = SDL_CreateWindow("title", shapeSurface->w, shapeSurface->h, windowFlags);
        SDL_Renderer * screen = SDL_CreateRenderer(win, 0, SDL_RENDERER_PRESENTVSYNC);
        SDL_SetWindowShape(win, shapeSurface);
        SDL_ShowWindow(win);

        SDL_SetRenderDrawColor(screen, 255, 255, 25, SDL_ALPHA_OPAQUE);
        bool run = true;
        while(run)
        {
                SDL_Event ev;
                while(SDL_PollEvent(&ev))
                {
                        switch(ev.type)
                        {
                                case SDL_EVENT_KEY_DOWN:
                                        switch(ev.key.keysym.sym)
                                        {
                                                case SDLK_ESCAPE:
                                                        run = false;
                                                        break;
                                        }
                                        break;
                                case SDL_EVENT_QUIT:
                                        run = false;
                                        break;
                        }
                }
                SDL_RenderClear(screen);
                SDL_RenderPresent(screen);
        }
        SDL_DestroyWindow(win);
        IMG_Quit();
        SDL_Quit();
}

Note to anyone interested in shaped windows that the SDL_Renderer must be created before calling SDL_SetWindowShape() for click-through and render-clipping to work properly.

I’m already back to considering a silly splash-screen where the characters are popping out past the window’s apparent draw area…Thanks for not killing off the shaped windows functionality.

sjr · April 1, 2024, 12:38am

Doesn’t work on macOS 11.0 and later. An exception is thrown: SDL_cocoadialog.m, line 95, in show_file_dialog():
[dialog setAllowedContentTypes:types];
fails because it’s being given an array of NSString when it’s expecting an array of UTType

Mik · April 1, 2024, 9:48am

Should SDL3 work with Windows 7?
Calling SDL_Init(SDL_INIT_VIDEO) produces the following error:
grafik

slouken · April 2, 2024, 2:33am

The preview release has been updated!
Release 3.1.1 Preview · libsdl-org/SDL (github.com)

Mik · April 2, 2024, 10:26am

The error above has gone in SDL 3.1.1.

I tried the following little program but I got an error during compilation:

#include <SDL3/SDL.h>
#include <stdio.h>
#include <stdlib.h>
int main(int argc, char *argv[]) {
     SDL_version compiled;
     SDL_version linked;
 
     SDL_VERSION(&compiled);
     SDL_GetVersion(&linked);
 
     if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO | SDL_INIT_JOYSTICK | SDL_INIT_GAMEPAD) == 0) {
         SDL_Log("Hello SDL3");
         return 0;
     } else {
         SDL_Log("SDL_Init() failed, Error: %s",SDL_GetError());
         return -1;
     }
}

Use: SDL3-devel-3.1.1-mingw.tar.xz
compiler: mingw64: gcc 13.2.0
Error:

Peter87 · April 2, 2024, 10:47am

Sounds like SDL3 is trying to tell you to use SDL_Version (with capital V) instead of SDL_version.

Mik · April 2, 2024, 11:09am

Thank you Peter, that was the problem. Code example in the SDL3 documentation should be fixed.

slouken · April 2, 2024, 2:40pm

This is fixed, thanks!

Mik · April 12, 2024, 2:24pm

I found another little bug in the SDL3 documentation.

count is the not the number of displays but the number of modes.

slouken · May 1, 2024, 5:26pm

The preview release has been updated!

PiotrGrochowski · May 3, 2024, 6:03am

In Release 3.1.2 Preview, the SDL_GetDisplayContentScale function can be used to get the horizontal content scale, but what can be used to get the vertical content scale?

jmr · May 5, 2024, 12:44pm

What are the intended minimum macOS SDK version and deployment target for SDL 3? Currently it doesn’t seem to build with an SDK older than 11 (Big Sur).

slouken · May 6, 2024, 4:34pm

The scale is assumed to be uniform.

slouken · May 6, 2024, 4:41pm

We tend to track Xcode, as Apple is pretty aggressive about marching forward SDK requirements.

Currently the minimum build SDK is 11.3 and deployment targets are macOS 10.11, iOS 9.0 and tvOS 9.0. However in general we don’t guarantee anything except what is supported by the current version of Xcode.

PiotrGrochowski · May 6, 2024, 6:04pm

But what if it’s not?

How am I supposed to use the SDL3 API to detect horizontal and vertical content scales separately?

slouken · May 6, 2024, 6:39pm

The content scale is the user-adjustable scale slider in the Windows display settings. On Windows 10 it’s labeled “Change the size of text, apps, and other items”.

PiotrGrochowski · May 6, 2024, 6:59pm

In some Windows versions, the content scale can be set separately on the two axes. On the screenshot above I have shown the configuration with 144dpi (150%) horizontally, and 192dpi (200%) vertically. This results in a configuration with non-square pixels. To handle such cases properly, it is necessary for an application to detect content scale on both axes separately. How is SDL3 API supposed to be used in such a scenario?

RogerFlores · May 14, 2024, 5:49am

I tried today to migrate some of my code from SDL2 to SDL3 and got stuck with images and ttf.

Looking at things for quite a while, I think the problem is that SDL3 has releases for source and binaries but images and ttf do not, and that results in an error about #include “begin_code.h” not being found.

How exactly are people migrating their projects to SDL3? Is everyone cloning all the repos and building everything to get the latest includes and binaries? I was hoping to simply download releases for those three projects mentioned but I’m suspecting I’m trying to migrate too early.

The wording at GitHub - libsdl-org/SDL_image: Image decoding for many popular formats for Simple Directmedia Layer.

"SDL_image 3.0

The latest version of this library is available from GitHub:
Releases · libsdl-org/SDL_image · GitHub"

encouraged me to expect to find a 3.0 release. The latest I found (and tried) is 2.8.2, but, sensibly, it really does not combine with SDL3.

If anyone has migrated to SDL3 without cloning and building everything, I’d appreciate hearing what you did.