Announcing the SDL 3.1.0 Preview Release

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

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

Check out 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 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!


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

1 Like

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_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_SetRenderDrawColor(screen, 255, 255, 25, SDL_ALPHA_OPAQUE);
        bool run = true;
                SDL_Event ev;
                                case SDL_EVENT_KEY_DOWN:
                                                case SDLK_ESCAPE:
                                                        run = false;
                                case SDL_EVENT_QUIT:
                                        run = false;

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.

1 Like

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

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

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

1 Like

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_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

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

1 Like

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

This is fixed, thanks!

I found another little bug in the SDL3 documentation.

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