From caf7d50167d6261663a820ba82eeab9597f22da4 Mon Sep 17 00:00:00 2001 From: Shawn Wallace Date: Wed, 16 Apr 2025 23:32:18 -0400 Subject: [PATCH] Add ARCHITECTURE.md --- ARCHITECTURE.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..c9932a1 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,79 @@ +# Architecture + +This is a high level overview of the architecture of xwayland-satellite. It has a +few different roles that can be confusing to understand if you aren't familiar with +how Wayland and X11 function. + +## Overview + +```mermaid +flowchart TD + host["Host compositor + (niri, sway, etc)"] + sat[xwayland-satellite] + Xwayland + client[X client] + + host --> sat + sat -->|Wayland server| Xwayland + Xwayland -->|X11 window manager| sat + sat -->|X11 window manager| client + Xwayland --> client +``` + +xwayland-satellite grants rootless Xwayland integration to any standard Wayland compositor through standard +Wayland protocols. As such, this means satellite has to function as three different things: + +1. An X11 window manager +2. A Wayland client +3. A Wayland server/compositor + +### X11 window manager + +The code for the X11 portion of satellite lives in `src/xstate`. Satellite must function largely the same way +as any other standard X11 window manager. This includes: + +- Setting SubstructureRedirect and SubstructureNotify on the root window, to get notifications for when new windows are being created +- Follwing (most of) the [ICCCM](https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html) and [EWMH](https://specifications.freedesktop.org/wm-spec/latest/) specs + +In addition, satellite must do some other things that a normal X11 window manager wouldn't - but a compositor integrating +Xwayland would - such as synchronize X11 and Wayland selections. This is explained further in the Wayland server section. + +The way that satellite manages windows from the X11 point of view is as follows: + +- All toplevels on a monitor are positioned at 0x0 on that monitor. So if you have one monitor at 0x0, +all the windows are located at 0x0. If you have a monitor at 300x600, all the windows on that monitor are at 300x600. + - This offset is needed because all monitors rest in the same coordinate plane in X11, so missing this offset would + would lead to incorrect cursor behavior. +- The current window that the mouse is hovering over is raised to the top of the stack. +- Any window determined to be a popup (override redirect, EWMH properties, etc) has its position respected if there is +an existing toplevel. If there is no existing toplevel, the window is treated as a toplevel. + +This approach seems to work well for most applications. The biggest issues will be applications that rely on creating windows +at specific coordinates - for example Steam's notifications that slide in from the bottom of the screen. + +### Wayland client + +Since satellite is intended to function on any Wayland compositor implementing the necessary protocols, +it functions as a Wayland client. This is straightforward to think about. Client interfacing code lives in +`src/clientside`, as well as being interspersed throughout `src/server`. + +### Wayland server + +In order to interface with Xwayland, which itself is a Wayland client, satellite must function as a Wayland server. +The code for this lives in `src/server`. Satellite will re-expose relevant Wayland interfaces from the host compositor +(the compositor that satellite itself is a client to) back to Xwayland. + +A lot of the interfaces that Xwayland is interested in can be exposed directly from the host with no further changes, +in which case satellite is just acting as an interface passthrough. However, some interfaces need to be manipulated +or otherwise intercepted for proper functionality, such as: + +- `wl_surface` - Xwayland simply exposes all X11 windows as `wl_surface`s, but for standard desktop compositors to actually show something, +these surfaces must have roles, such as `xdg_toplevel` and `xdg_popup` and friends +- `xdg_output` - Xwayland will use `xdg_output`'s logical size for sizing the X11 screen, but this leads to the wrong size +when the output is scaled, and blurry windows as you may have seen in other Xwayland integrations. +- `wl_pointer` - For handling scaled mouse output, since we are changing the reported output/surface sizes. + +Note that there may be some interfaces that are only used from satellite's client side, such as `xdg_wm_base`. These +are interfaces that Xwayland is not actually interested in, but satellite itself uses to provide some sort of functionality +- satellite is a normal Wayland client after all.