Atlas - README-wayland.md

Home / ext / SDL / docs
Rendered HTML view | Size: 13424 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 

[FILE BEGIN]


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



Window decorations are missing, or the decorations look strange



Windows do not appear immediately after creation



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



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



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



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



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



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



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



Keyboard grabs don't work when running under XWayland



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:


```c++


include 


include 


include 


include 


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;



}
```


[FILE END]

(C) 2025 0x4248
(C) 2025 4248 Media and 4248 Systems, All part of 0x4248
See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.