# Announcing the SDL 3.1.0 Preview Release

**URL:** <https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076>\
**Category:** SDL Development\
**Created:** [March 24, 2024, 2:49pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076 "2024-03-24T14:49:39Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![slouken](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/s/ec9cab/32.png) [@slouken](https://discourse.libsdl.org/u/slouken)\
**Post date:** [March 24, 2024, 2:49pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/1 "2024-03-24T14:49:39Z")

</div>

The preview release of the new SDL 3.0 API is now available!  
[Release 3.1.0 Preview · libsdl-org/SDL (github.com)](https://github.com/libsdl-org/SDL/releases/tag/prerelease-3.1.0)

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

Check out [README-migration.md](https://github.com/libsdl-org/SDL/blob/main/docs/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](https://github.com/libsdl-org/SDL/issues)

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](mailto: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!

---

<div class="post-metadata">

**Author:** ![anon914446](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/a/a5b964/32.png) [@anon914446](https://discourse.libsdl.org/u/anon914446)\
**Post date:** [March 25, 2024, 4:29pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/3 "2024-03-25T16:29:23Z")

</div>

> [@slouken](#):
>
> Support for file open and save dialogs has been added in SDL\_dialog.h

 ![Screenshot from 2024-03-25 09-28-20](https://discourse.libsdl.org/uploads/default/original/2X/c/c7742441d9c7cff4c3a7e2a00717261cc78ce942.png)  
I can’t tell you how much I’ve wanted this!

---

<div class="post-metadata">

**Author:** ![anon914446](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/a/a5b964/32.png) [@anon914446](https://discourse.libsdl.org/u/anon914446)\
**Post date:** [March 30, 2024, 4:57am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/4 "2024-03-30T04:57:53Z")

</div>

> [@slouken](#):
>
> The shaped window API has been replaced with transparent windows

 ![Screenshot from 2024-03-29 21-55-04](https://discourse.libsdl.org/uploads/default/original/2X/5/549d4a6670952902646227bd15565edcec885c9c.png)

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.)

```auto
#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.

---

<div class="post-metadata">

**Author:** ![sjr](https://discourse.libsdl.org/user_avatar/discourse.libsdl.org/sjr/32/5749_2.png) [@sjr](https://discourse.libsdl.org/u/sjr)\
**Post date:** [April 1, 2024, 12:38am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/5 "2024-04-01T00:38:44Z")

</div>

> [@slouken](#):
>
> - Support for file open and save dialogs has been added in SDL\_dialog.h

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`

---

<div class="post-metadata">

**Author:** ![Mik](https://discourse.libsdl.org/user_avatar/discourse.libsdl.org/mik/32/5027_2.png) [@Mik](https://discourse.libsdl.org/u/Mik)\
**Post date:** [April 1, 2024, 9:48am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/6 "2024-04-01T09:48:21Z")

</div>

Should SDL3 work with Windows 7?  
Calling SDL\_Init(SDL\_INIT\_VIDEO) produces the following error:  
 ![grafik](https://discourse.libsdl.org/uploads/default/original/2X/5/5ea7b870a56e303ee167a123a0f7c8b98959aaf7.png)

---

<div class="post-metadata">

**Author:** ![slouken](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/s/ec9cab/32.png) [@slouken](https://discourse.libsdl.org/u/slouken)\
**Post date:** [April 2, 2024, 2:33am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/7 "2024-04-02T02:33:16Z")

</div>

The preview release has been updated!  
[Release 3.1.1 Preview · libsdl-org/SDL (github.com)](https://github.com/libsdl-org/SDL/releases/tag/prerelease-3.1.1)

---

<div class="post-metadata">

**Author:** ![Mik](https://discourse.libsdl.org/user_avatar/discourse.libsdl.org/mik/32/5027_2.png) [@Mik](https://discourse.libsdl.org/u/Mik)\
**Post date:** [April 2, 2024, 10:26am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/8 "2024-04-02T10:26:58Z")

</div>

The error above has gone in SDL 3.1.1.

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

```auto
#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:

 ![grafik](https://discourse.libsdl.org/uploads/default/original/2X/d/d833f232b2485b50891264d323325d321f487136.png)

---

<div class="post-metadata">

**Author:** ![Peter87](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/p/f07891/32.png) [@Peter87](https://discourse.libsdl.org/u/Peter87)\
**Post date:** [April 2, 2024, 10:47am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/9 "2024-04-02T10:47:06Z")

</div>

> [@Mik](#):
>
> error: unknown type name ‘SDL\_version\_renamed\_SDL\_Version’

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

---

<div class="post-metadata">

**Author:** ![Mik](https://discourse.libsdl.org/user_avatar/discourse.libsdl.org/mik/32/5027_2.png) [@Mik](https://discourse.libsdl.org/u/Mik)\
**Post date:** [April 2, 2024, 11:09am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/10 "2024-04-02T11:09:30Z")

</div>

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

> **[SDL3/SDL\_GetVersion](https://wiki.libsdl.org/SDL3/SDL_GetVersion)**
>
> The Simple Directmedia Layer Wiki

---

<div class="post-metadata">

**Author:** ![slouken](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/s/ec9cab/32.png) [@slouken](https://discourse.libsdl.org/u/slouken)\
**Post date:** [April 2, 2024, 2:40pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/11 "2024-04-02T14:40:34Z")

</div>

This is fixed, thanks!

---

<div class="post-metadata">

**Author:** ![Mik](https://discourse.libsdl.org/user_avatar/discourse.libsdl.org/mik/32/5027_2.png) [@Mik](https://discourse.libsdl.org/u/Mik)\
**Post date:** [April 12, 2024, 2:24pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/12 "2024-04-12T14:24:47Z")

</div>

I found another little bug in the SDL3 documentation.

> **[SDL3/SDL\_GetFullscreenDisplayModes](https://wiki.libsdl.org/SDL3/SDL_GetFullscreenDisplayModes)**
>
> The Simple Directmedia Layer Wiki

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

---

<div class="post-metadata">

**Author:** ![slouken](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/s/ec9cab/32.png) [@slouken](https://discourse.libsdl.org/u/slouken)\
**Post date:** [May 1, 2024, 5:26pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/13 "2024-05-01T17:26:46Z")

</div>

The preview release has been updated!

> **[Release 3.1.2 Preview · libsdl-org/SDL](https://github.com/libsdl-org/SDL/releases/tag/prerelease-3.1.2)**
>
> This is an update to the preview release of the new SDL 3.0 API.
> Here are some of the highlights since the last preview:
> 
> Added SDL\_GlobDirectory() and SDL\_GlobStorageDirectory()
> Added support for ...

---

<div class="post-metadata">

**Author:** ![PiotrGrochowski](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/p/ba9def/32.png) [@PiotrGrochowski](https://discourse.libsdl.org/u/PiotrGrochowski)\
**Post date:** [May 3, 2024, 6:03am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/14 "2024-05-03T06:03:53Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![jmr](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/j/d6d6ee/32.png) [@jmr](https://discourse.libsdl.org/u/jmr)\
**Post date:** [May 5, 2024, 12:44pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/15 "2024-05-05T12:44:02Z")

</div>

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).

---

<div class="post-metadata">

**Author:** ![slouken](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/s/ec9cab/32.png) [@slouken](https://discourse.libsdl.org/u/slouken)\
**Post date:** [May 6, 2024, 4:34pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/16 "2024-05-06T16:34:39Z")

</div>

The scale is assumed to be uniform.

---

<div class="post-metadata">

**Author:** ![slouken](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/s/ec9cab/32.png) [@slouken](https://discourse.libsdl.org/u/slouken)\
**Post date:** [May 6, 2024, 4:41pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/17 "2024-05-06T16:41:31Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![PiotrGrochowski](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/p/ba9def/32.png) [@PiotrGrochowski](https://discourse.libsdl.org/u/PiotrGrochowski)\
**Post date:** [May 6, 2024, 6:04pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/18 "2024-05-06T18:04:09Z")

</div>

But what if it’s not?

 ![](https://discourse.libsdl.org/uploads/default/original/2X/e/e5010bc60d2b60ae96986a6bb65acd85025f0d5b.png)

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

---

<div class="post-metadata">

**Author:** ![slouken](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/s/ec9cab/32.png) [@slouken](https://discourse.libsdl.org/u/slouken)\
**Post date:** [May 6, 2024, 6:39pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/19 "2024-05-06T18:39:01Z")

</div>

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”.

---

<div class="post-metadata">

**Author:** ![PiotrGrochowski](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/p/ba9def/32.png) [@PiotrGrochowski](https://discourse.libsdl.org/u/PiotrGrochowski)\
**Post date:** [May 6, 2024, 6:59pm UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/20 "2024-05-06T18:59:25Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![RogerFlores](https://discourse.libsdl.org/letter_avatar_proxy/v4/letter/r/e274bd/32.png) [@RogerFlores](https://discourse.libsdl.org/u/RogerFlores)\
**Post date:** [May 14, 2024, 5:49am UTC](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076/21 "2024-05-14T05:49:58Z")

</div>

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.](https://github.com/libsdl-org/SDL_image)

"SDL\_image 3.0

The latest version of this library is available from GitHub:  
[Releases · libsdl-org/SDL\_image · GitHub](https://github.com/libsdl-org/SDL_image/releases)"

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.

[Next page](https://discourse.libsdl.org/t/announcing-the-sdl-3-1-0-preview-release/50076.md?page=2)