This extends the display scaling mode to be global and work in terms of pixels everywhere, with the content scale value set on displays. The per-window property had some issues, and has been removed in favor of retaining only the global hint that changes all coordinates to pixel values, sets the content scale on the displays, and generally makes the Wayland backend behave similarly to Win32 or X11.
Some additional work was needed to fix cases where displays can appear to overlap, since Wayland desktops are always described in logical coordinates, and attempting to adjust the display positions so that they don't overlap can get very ugly in all but the simplest cases, as large gaps between displays can result.
Queries the "panel orientation" property on the connector and reports it in degrees of clockwise rotation via the 'SDL.display.KMSDRM.panel_orientation' display property.
This is provided by the kernel as a hint to userspace applications, and the application itself is ultimately responsible for any required coordinate transformations needed to conform to the requested orientation.
- Adds support for modal windows to Win32, Mac, and Haiku, and enhances functionality on Wayland and X11, which previous set only the parent window, but not the modal state.
- Windows can be declared modal at creation time, and the modal state can be toggled at any time via SDL_SetWindowModalFor() (tested with UE5 through sdl2-compat).
- Allows dynamic unparenting/reparenting of windows.
- Includes a modal window test.
The idea is that if you have a `typedef Uint32 MyFlags` that has a bunch of
defines that are meant to be bitflags, you can pack them into the same wiki
page automatically.
This only works with `typedef`s that are _not_ struct/union/enums, and it
only pulls in `#define` lines that immediately follow the typedef line.
Even a blank line or a comment will signal to stop including lines for
this page!
This is just stuff I noticed while working on the wikiheaders updates. A
thorough pass over all the docs would not be terrible, and maybe a simple
script to check for consistency (does everything have a `\since` on it? etc)
might be nice, too.
Add the xdg-foreign-unstable-v2 protocol and use it to create export handles for toplevel windows, which will be used when an external component, such as the file chooser portal, requires it.
This better reflects how HDR content is actually used, e.g. most content is in the SDR range, with specular highlights and bright details beyond the SDR range, in the HDR headroom.
This more closely matches how HDR is handled on Apple platforms, as EDR.
This also greatly simplifies application code which no longer has to think about color scaling. SDR content is rendered at the appropriate brightness automatically, and HDR content is scaled to the correct range for the display HDR headroom.
Renamed the following property define names to have a type suffix to
match other property names.
SDL_PROP_TEXTURE_OPENGL_TEXTURE_TARGET (number)
SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET (number)
SDL_PROP_WINDOW_CREATE_WAYLAND_SCALE_TO_DISPLAY (boolean)
SDL_PROP_WINDOW_RENDERER (pointer)
SDL_PROP_WINDOW_TEXTUREDATA (pointer)
Add a mode that forces Wayland windows to output with scaling that forces 1:1 pixel mapping.
This is intended to allow legacy applications to be displayed without desktop scaling being applied, and may have issues with some display configurations, as this forces the window to behave in a way that Wayland desktops were not designed to accommodate (rounding errors can result from certain combinations of window/scale values, the window may be unusably small, jump in size at times, or appear to be larger than the desktop space, and cursor precision may be reduced).
Windows flagged as DPI-aware are not affected by this.
The automated video test suite passes with the hint turned on.
Add the ability to import and wrap external surfaces from external toolkits such as Qt and GTK.
Wayland surfaces and windows are more intrinsically tied to the client library than other windowing systems, so it is necessary to provide a way to initialize SDL with an existing wl_display object, which needs to be set prior to video system initialization, or export the internal SDL wl_display object for use by external applications or toolkits. For this, the global property SDL_PROPERTY_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER is used.
A Wayland example was added to testnative, and a basic example of Qt 6 interoperation is provided in the Wayland readme to demonstrate the use of external windows with both SDL owning the wl_display, and an external toolkit owning it.
Allow for the creation of SDL windows with a roleless surface that applications can use for their own purposes, such as with a windowing protocol other than XDG toplevel.
The property `wayland.surface_role_custom` will create a window with a surface that SDL can render to and handles input for, but is not associated with a toplevel window, so applications can use it for their own, custom purposes (e.g. wlr_layer_shell).
A test/minimal example is included in tests/testwaylandcustom.c
A Wayland registry object can only have one listener attached at a time, so an application attempting to use the backend SDL registry object for its own purposes will just result in an error. Remove this property, as it is of no use to applications and will only result in errors.
If an application needs the registry, it needs to get the wl_display object via `SDL.window.wayland.display` and use wl_display_get_registry() to create a new registry object that it can attach its own listeners to.
SDL window size, state, and position functions have been considered immediate, with their effects assuming to have taken effect upon successful return of the function. However, several windowing systems handle these requests asynchronously, resulting in the functions blocking until the changes have taken effect, potentially for long periods of time. Additionally, some windowing systems treat these as requests, and can potentially deny or fulfill the request in a manner differently than the application expects, such as not allowing a window to be positioned or sized beyond desktop borders, prohibiting fullscreen, and so on.
With these changes, applications can make requests of the window manager that do not block, with the understanding that an associated event will be sent if the request is fulfilled. Currently, size, position, maximize, minimize, and fullscreen calls are handled as asynchronous requests, with events being returned if the request is honored. If the application requires that the change take effect immediately, it can call the new SDL_SyncWindow function, which will attempt to block until the request is fulfilled, or some arbitrary timeout period elapses, the duration of which depends not only on the windowing system, but on the operation requested as well (e.g. a 100ms timeout is fine for most X11 events, but maximizing a window can take considerably longer for some reason). There is also a new hint 'SDL_VIDEO_SYNC_ALL_WINDOW_OPS' that will mimic the old behavior by synchronizing after every window operation with, again, the understanding that using this may result in the associated calls blocking for a relatively long period.
The deferred model also results in the window size and position getters not reporting false coordinates anymore, as they only forward what the window manager reports vs allowing applications to set arbitrary values, and fullscreen enter/leave events that were initiated via the window manager update the window state appropriately, where they didn't before.
Care was taken to ensure that order of operations is maintained, and that requests are not ignored or dropped. This does require some implicit internal synchronization in the various backends if many requests are made in a short period, as some state and behavior depends on other bits of state that need to be known at that particular point in time, but this isn't something that typical applications will hit, unless they are sending a lot of window state in a short time as the tests do.
The automated tests developed to test the previous behavior also resulted in previously undefined behavior being defined and normalized across platforms, particularly when it comes to the sizing and positioning of windows when they are in a fixed-size state, such as maximized or fullscreen. Size and position requests made when the window is not in a movable or resizable state will be deferred until it can be applied, so no requests are lost. These changes fix another long-standing issue with renderers recreating maximized windows, where the original non-maximized size was lost, resulting in the window being restored to the wrong size. All automated video tests pass across all platforms.
Overall, the "make a request/get an event" model better reflects how most windowing systems work, and some backends avoid spending significant time blocking while waiting for operations to complete.
SDL Wiki Bot
Sam Lantinga
Ryan C. Gordon
Frank Praznik
Semphris
Petar Popovic
Cameron Gutman
Susko3
Zack Middleton