Wayland

Wayland is a replacement for the X11 window system protocol and architecture and is favored over X11 by default in SDL3 for communicating with desktop compositors. It works well for the majority of applications, however, applications may encounter limitations or behavior that is different from other windowing systems.

# Common issues:

## Legacy, DPI-unaware applications are blurry

- Wayland handles high-DPI displays by scaling the desktop, which causes applications that are not designed to be DPI-aware to be automatically scaled by the window manager, which results in them being blurry. SDL can attempt to scale these applications such that they will be output with a 1:1 pixel aspect, however this may be buggy, especially with odd-sized windows and/or scale factors that aren't quarter-increments (125%, 150%, etc...). To enable this, set the environment variable SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY=1

## Window decorations are missing, or the decorations look strange

- On some desktops (i.e. GNOME), Wayland applications use a library called libdecor to provide window decorations. If this library is not installed, the decorations will be missing. This library uses plugins to generate different decoration styles, and if a plugin to generate native-looking decorations is not installed (i.e. the GTK plugin), the decorations will not appear to be 'native'.

## Windows do not appear immediately after creation

- Wayland requires that the application initially present a buffer before the window becomes visible. Additionally, applications must have an event loop and processes messages on a regular basis, or the application can appear unresponsive to both the user and desktop compositor.

## The display reported as the primary by SDL_GetPrimaryDisplay() is incorrect

- Wayland doesn't natively have the concept of a primary display, so SDL attempts to determine it by querying various system settings, and falling back to a selection algorithm if this fails. If it is incorrect, it can be manually overridden by setting the SDL_VIDEO_DISPLAY_PRIORITY hint.

## SDL_SetWindowPosition() doesn't work on non-popup windows

- Wayland does not allow toplevel windows to position themselves programmatically.

## Retrieving the global mouse cursor position when the cursor is outside a window doesn't work

- Wayland only provides applications with the cursor position within the borders of the application windows. Querying the global position when an application window does not have mouse focus returns 0,0 as the actual cursor position is unknown. In most cases, applications don't actually need the global cursor position and should use the window-relative coordinates as provided by the mouse movement event or from SDL_GetMouseState() instead.

## Warping the mouse cursor to or from a point outside the window doesn't work

- Warping the cursor on Wayland requires that either the wp_pointer_warp_v1 or zwp_pointer_confinement_v1 protocol is supported by the compositor. Compositors typically restrict pointer warps to be within the window that currently has mouse focus.

## Minimize/Restored window events are not sent, and the SDL_WINDOW_MINIMIZED flag is not set.

- Wayland windows do not currently report the minimized state, aside from when it is activated programmatically via
  _MinimizeWindow()
  . Minimizing a window from the window controls or a desktop shortcut will not send a minimized event or flag the window as being minimized.

## The application icon can't be set via SDL_SetWindowIcon()

- Wayland requires compositor support for the xdg-toplevel-icon-v1 protocol to set window icons programmatically. Otherwise, the launcher icon from the associated desktop entry file, aka a .desktop file, will typically be used. Please see the Desktop Entry Specification for more information on the format of this file. Note that if your application manually sets the application ID via the SDL_APP_ID hint string, the desktop entry file name should match the application ID. For example, if your application ID is set to org.my_org.sdl_app, the desktop entry file should be named org.my_org.sdl_app.desktop.

## The application progress bar can't be set via SDL_SetWindowProgressState() or SDL_SetWindowProgressValue()

- Only some Desktop Environemnts support the underlying API. Known compatible DEs: Unity, KDE
- The underlying API requires a desktop entry file, aka a .desktop file. Please see the Desktop Entry Specification for more information on the format of this file. Note that if your application manually sets the application ID via the SDL_APP_ID hint string, the desktop entry file name should match the application ID. For example, if your application ID is set to org.my_org.sdl_app, the desktop entry file should be named org.my_org.sdl_app.desktop.

## Keyboard grabs don't work when running under XWayland

- On GNOME based desktops, the dconf setting org/gnome/mutter/wayland/xwayland-allow-grabs must be enabled.

# Using custom Wayland windowing protocols with SDL windows

Under normal operation, an SDL_Window corresponds to an XDG toplevel window, which provides a standard desktop window. If an application wishes to use a different windowing protocol with an SDL window (e.g. wlr_layer_shell) while still having SDL handle input and rendering, it needs to create a custom, roleless surface and attach that surface to its own toplevel window.

This is done by using SDL_CreateWindowWithProperties() and setting the SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN property to true. Once the window has been successfully created, the wl_display and wl_surface objects can then be retrieved from the SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER and SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER properties respectively.

Surfaces don't receive any size change notifications, so if an application changes the window size, it must inform SDL that the surface size has changed by calling SDL_SetWindowSize() with the new dimensions.

Custom surfaces will automatically handle scaling internally if the window was created with the SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN property set to true. In this case, applications should not manually attach viewports or change the surface scale value, as SDL will handle this internally. Calls to SDL_SetWindowSize() should use the logical size of the window, and SDL_GetWindowSizeInPixels() should be used to query the size of the backbuffer surface in pixels. If this property is not set or is false, applications can attach their own viewports or change the surface scale manually, and the SDL backend will not interfere or change any values internally. In this case, calls to SDL_SetWindowSize() should pass the requested surface size in pixels, not the logical window size, as no scaling calculations will be done internally.

All window functions that control window state aside from SDL_SetWindowSize() are no-ops with custom surfaces.

Please see the minimal example in tests/testwaylandcustom.c for an example of how to use a custom, roleless surface and attach it to an application-managed toplevel window.

# Importing external surfaces into SDL windows

Wayland windows and surfaces are more intrinsically tied to the client library than other windowing systems, therefore, when importing surfaces, it is necessary for both SDL and the application or toolkit to use the same wl_display object. This can be set/queried via the global SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER property. To import an external wl_display, set this property before initializing the SDL video subsystem, and read the value to export the internal wl_display after the video subsystem has been initialized. Setting this property after the video subsystem has been initialized has no effect, and reading it when the video subsystem is uninitialized will either return the user provided value, if one was set while in the uninitialized state, or NULL.

Once this is done, and the application has created or obtained the wl_surface to be wrapped in an SDL_Window, the window is created with SDL_CreateWindowWithProperties() with the SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER property to set to the wl_surface object that is to be imported by SDL.

SDL receives no notification regarding size changes on external surfaces or toplevel windows, so if the external surface needs to be resized, SDL must be informed by calling SDL_SetWindowSize() with the new dimensions.

If desired, SDL can automatically handle the scaling for the surface by setting the SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN property to true, however, if the surface being imported already has, or will have, a viewport/fractional scale manager attached to it by the application or an external toolkit, a protocol violation will result. Avoid setting this property if importing surfaces from toolkits such as Qt or GTK.

If the window is flagged as high pixel density, calls to SDL_SetWindowSize() should pass the logical size of the window and SDL_GetWindowSizeInPixels() should be used to retrieve the backbuffer size in pixels. Otherwise, calls to SDL_SetWindowSize() should pass the requested surface size in pixels, not the logical window size, as no scaling calculations will be done internally.

All window functions that control window state aside from SDL_SetWindowSize() are no-ops with external surfaces.

An example of how to use external surfaces with a wl_display owned by SDL can be seen in tests/testnativewayland.c, and the following is a minimal example of interoperation with Qt 6, with Qt owning the wl_display:

#include <QApplication>
#include <QWindow>
#include <qpa/qplatformnativeinterface.h>
#include <SDL3/SDL.h>
int main(int argc, char *argv[])
{
int ret = -1;
int done = 0;
SDL_PropertiesID props;
SDL_Event e;
SDL_Window *sdlWindow = NULL;
SDL_Renderer *sdlRenderer = NULL;
struct wl_display *display = NULL;
struct wl_surface *surface = NULL;
/* Initialize Qt */
QApplication qtApp(argc, argv);
QWindow qtWindow;
/* The windowing system must be Wayland. */
if (QApplication::platformName() != "wayland") {
goto exit;
}
{
/* Get the wl_display object from Qt */
QNativeInterface::QWaylandApplication *qtWlApp = qtApp.nativeInterface<QNativeInterface::QWaylandApplication>();
display = qtWlApp->display();
if (!display) {
goto exit;
}
}
/* Set SDL to use the existing wl_display object from Qt and initialize. */
SDL_SetPointerProperty(SDL_GetGlobalProperties(), SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER, display);
SDL_Init(SDL_INIT_VIDEO | SDL_INIT_EVENTS);
/* Create a basic, frameless QWindow */
qtWindow.setFlags(Qt::FramelessWindowHint);
qtWindow.setGeometry(0, 0, 640, 480);
qtWindow.show();
{
/* Get the native wl_surface backing resource for the window */
QPlatformNativeInterface *qtNative = qtApp.platformNativeInterface();
surface = (struct wl_surface *)qtNative->nativeResourceForWindow("surface", &qtWindow);
if (!surface) {
goto exit;
}
}
/* Create a window that wraps the wl_surface from the QWindow.
* Qt objects should not be flagged as DPI-aware or protocol violations will result.
*/
props = SDL_CreateProperties();
SDL_SetPointerProperty(props, SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER, surface);
SDL_SetBooleanProperty(props, SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN, true);
SDL_SetNumberProperty(props, SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER, 640);
SDL_SetNumberProperty(props, SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER, 480);
sdlWindow = SDL_CreateWindowWithProperties(props);
SDL_DestroyProperties(props);
if (!sdlWindow) {
goto exit;
}
/* Create a renderer */
sdlRenderer = SDL_CreateRenderer(sdlWindow, NULL);
if (!sdlRenderer) {
goto exit;
}
/* Draw a blue screen for the window until ESC is pressed or the window is no longer visible. */
while (!done) {
while (SDL_PollEvent(&e)) {
if (e.type == SDL_EVENT_KEY_DOWN && e.key.key == SDLK_ESCAPE) {
done = 1;
}
}
qtApp.processEvents();
/* Update the backbuffer size if the window scale changed. */
qreal scale = qtWindow.devicePixelRatio();
SDL_SetWindowSize(sdlWindow, SDL_lround(640. * scale), SDL_lround(480. * scale));
if (qtWindow.isVisible()) {
SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 255, SDL_ALPHA_OPAQUE);
SDL_RenderClear(sdlRenderer);
SDL_RenderPresent(sdlRenderer);
} else {
done = 1;
}
}
ret = 0;
exit:
/* Cleanup */
if (sdlRenderer) {
SDL_DestroyRenderer(sdlRenderer);
}
if (sdlWindow) {
SDL_DestroyWindow(sdlWindow);
}
SDL_Quit();
return ret;
}
SDL.h
NULL
#define NULL
Definition SDL_begin_code.h:469
SDL_PollEvent
bool SDL_PollEvent(SDL_Event *event)
SDL_EVENT_KEY_DOWN
@ SDL_EVENT_KEY_DOWN
Definition SDL_events.h:170
SDL_Quit
void SDL_Quit(void)
SDL_Init
bool SDL_Init(SDL_InitFlags flags)
SDL_INIT_EVENTS
#define SDL_INIT_EVENTS
Definition SDL_init.h:85
SDL_INIT_VIDEO
#define SDL_INIT_VIDEO
Definition SDL_init.h:81
SDLK_ESCAPE
#define SDLK_ESCAPE
Definition SDL_keycode.h:66
main
#define main
Definition SDL_main_impl.h:147
SDL_ALPHA_OPAQUE
#define SDL_ALPHA_OPAQUE
Definition SDL_pixels.h:100
SDL_SetPointerProperty
bool SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value)
SDL_SetBooleanProperty
bool SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value)
SDL_PropertiesID
Uint32 SDL_PropertiesID
Definition SDL_properties.h:66
SDL_GetGlobalProperties
SDL_PropertiesID SDL_GetGlobalProperties(void)
SDL_SetNumberProperty
bool SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value)
SDL_CreateProperties
SDL_PropertiesID SDL_CreateProperties(void)
SDL_DestroyProperties
void SDL_DestroyProperties(SDL_PropertiesID props)
SDL_RenderPresent
bool SDL_RenderPresent(SDL_Renderer *renderer)
SDL_DestroyRenderer
void SDL_DestroyRenderer(SDL_Renderer *renderer)
SDL_CreateRenderer
SDL_Renderer * SDL_CreateRenderer(SDL_Window *window, const char *name)
SDL_RenderClear
bool SDL_RenderClear(SDL_Renderer *renderer)
SDL_Renderer
struct SDL_Renderer SDL_Renderer
Definition SDL_render.h:146
SDL_SetRenderDrawColor
bool SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
SDL_lround
long SDL_lround(double x)
SDL_SetWindowSize
bool SDL_SetWindowSize(SDL_Window *window, int w, int h)
SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER
#define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER
Definition SDL_video.h:103
SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER
#define SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER
Definition SDL_video.h:1435
SDL_Window
struct SDL_Window SDL_Window
Definition SDL_video.h:175
SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN
#define SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN
Definition SDL_video.h:1427
SDL_CreateWindowWithProperties
SDL_Window * SDL_CreateWindowWithProperties(SDL_PropertiesID props)
SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER
#define SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER
Definition SDL_video.h:1443
SDL_DestroyWindow
void SDL_DestroyWindow(SDL_Window *window)
SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER
#define SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER
Definition SDL_video.h:1418
SDL_KeyboardEvent::key
SDL_Keycode key
Definition SDL_events.h:368
SDL_Event
Definition SDL_events.h:1017
SDL_Event::type
Uint32 type
Definition SDL_events.h:1018
SDL_Event::key
SDL_KeyboardEvent key
Definition SDL_events.h:1023