Skip to content

armgit / BUI

Public Imported from GitHub
0

Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI

wayland docs

Preetham Pemmasanibca7b8d62d42
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c805ae..01bcbc6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,17 @@ All notable changes to **blenderui** (BUI). The format follows
## [Unreleased]
### Added
+- **Native Wayland windows (experimental).** `kit/intern/kit_window_wayland.c` is a Wayland host with the same
+ `BK_window_*` API, modelled on Blender's `GHOST_SystemWayland`: xdg-shell toplevels with server-side
+ decorations when offered, a `wl_seat` with xkbcommon (keys, key repeat), the pointer, the clipboard through
+ `wl_data_device`, cursors, the output's buffer scale, and `wl_surface.frame` pacing into `wl_shm` buffers
+ (only damaged rectangles are copied). It uses Blender's `wayland_dynload` (`kit/extern/wayland_dynload`), so
+ libwayland loads at run time and nothing is linked; libxkbcommon is `dlopen()`ed. A Wayland session gets it;
+ `BUI_WINDOW_BACKEND=x11|wayland` picks one. It draws on the CPU, so with the GPU renderer on (`BUI_GPU=1`, or
+ `BUI_gpu_set_default(1)` before the first window) the session keeps X11 (XWayland): the X11 host and its GPU start
+ (the worker-thread device, the idle switch) are unchanged. Builds without the Wayland headers,
+ `wayland-scanner` and `wayland-protocols` (or with `-DBUI_WAYLAND=OFF`) are X11 only, as before. Not done:
+ IME, client-side decorations (no title bar on GNOME), pointer warping.
- **Input methods (IME) on Windows**, ported from Blender (`GHOST_ImeWin32`, the text button's IME handling in
`interface_handlers.cc` and its drawing in `interface_widgets.cc`). Chinese, Japanese and Korean input now
works in text fields and text areas: the composition is drawn underlined at the caret (a thicker line under
diff --git a/README.md b/README.md
index fa0b547..2342ea7 100644
--- a/README.md
+++ b/README.md
@@ -267,7 +267,7 @@ If you're starting fresh in Python, the Blender components are the friendliest.
### Native everywhere
-- **Native windows** on Windows (Win32) and Linux (X11, Wayland through XWayland), and an experimental Cocoa host for macOS ported from Blender's GHOST.
+- **Native windows** on Windows (Win32) and Linux (X11, and an experimental native Wayland host), and an experimental Cocoa host for macOS ported from Blender's GHOST.
- **HiDPI**: per-monitor DPI on Windows, `Xft.dpi` on Linux, Retina on macOS.
- **Headless mode** for tests and screenshots, with a virtual clock that steps animations exactly.
- On Linux, libX11 and libGL are loaded at run time, so BUI imports on servers without them.
@@ -1139,7 +1139,8 @@ A **window host** puts a kit context in a top-level window and feeds it input.
| Host | Where | Notes |
| -------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Win32** (`kit_window_win32.c`) | Windows | BUI's own host. Per-monitor DPI, vsync-paced animation, clipboard, cursors, window-manager features. |
-| **X11** (`kit_window_x11.c`) | Linux; Wayland through XWayland | Input mapping after Blender's GHOST. `Xft.dpi` scaling. libX11 is loaded when the first window opens. |
+| **X11** (`kit_window_x11.c`) | Linux (also Wayland, via XWayland) | Input mapping after Blender's GHOST. `Xft.dpi` scaling. libX11 is loaded when the first window opens. |
+| **Wayland** (`kit_window_wayland.c`) | Linux, **experimental** | Native Wayland windows, after Blender's `GHOST_SystemWayland`: xdg-shell, server-side decorations when offered, `wl_seat` with xkbcommon, clipboard, cursors, buffer scale, frame callbacks. CPU renderer only: with the GPU renderer on (`BUI_GPU=1`) a Wayland session keeps using X11 through XWayland. `BUI_WINDOW_BACKEND=x11\|wayland` picks one. libwayland loads at run time (Blender's `wayland_dynload`). Needs the Wayland headers to build; without them Linux windows are X11 only. |
| **Cocoa** (`kit_window_cocoa.m`) | macOS | **Experimental.** Ported from Blender's GHOST Cocoa code, with Retina scaling. It's checked by CI and has been tried by hand on two Apple Silicon Macs so far; testing notes in [docs/macos-testing.md](docs/macos-testing.md). |
| **Tk** | Python, anywhere | A stdlib `tkinter` window that shows the kit's frame buffer. `BUI_HOST=tk` forces it; it's also the fallback where no native host works. |
| **Headless** | Everywhere | No window: render into a raster for tests and screenshots, with a virtual clock that steps animations exactly. |
@@ -1665,7 +1666,7 @@ py bindings/python/bench/tk_canvas_bench.py 3000 one # move one
| | Windows | Linux | macOS |
| ---------------------------- | -------------------------------- | ------------------------------------------------------------------------ | ---------------------------- |
-| Window | Native (Win32) | Native (X11; Wayland through XWayland) | Native (Cocoa), experimental |
+| Window | Native (Win32) | Native (X11, and Wayland: experimental) | Native (Cocoa), experimental |
| Python (`pip install`) | Works: wheels | Works: wheels (native X11 host) | Works: wheels |
| Rust (`cargo add blenderui`) | Works | Works | Experimental |
| JavaScript / React | Works: prebuilt on npm | Works: build the addon from source (`npm run build`); native X11 windows | Headless (see below) |
@@ -1854,7 +1855,7 @@ ship. The tables below have the details.
optional GPU renderer is Direct3D 11 on Windows and OpenGL 3.3 on Linux.
There is none on macOS (no Metal): macOS always draws on the CPU. Direct3D
12, Vulkan, Metal and WebGPU backends don't exist yet.
-- **Platforms.** Windows and Linux (X11; Wayland through XWayland) are the
+- **Platforms.** Windows and Linux (X11; Wayland is experimental) are the
supported ones. macOS is experimental: checked by CI and tried by hand on two
Apple Silicon Macs, and JavaScript windows are headless there. The npm
packages are prebuilt for Windows x64 only.
@@ -1881,7 +1882,7 @@ ship. The tables below have the details.
| Area | What works |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C runtime (`kit/`) | Nodes, Tk-style geometry managers, input, Blender widget drawing, damage rendering, undo, animation, text area, canvas, scroll views, Blender's string search, expression evaluator, text-edit undo and float precision, Blender's Dark and Light themes |
-| Native windows | Windows (Win32) and Linux (X11; Wayland through XWayland), in C: DPI-aware, frame-paced animation, clipboard, cursors, window-manager features |
+| Native windows | Windows (Win32) and Linux (X11; native Wayland is experimental), in C: DPI-aware, frame-paced animation, clipboard, cursors, window-manager features |
| tkinter syntax | **Complete**: every public tkinter and ttk name (7,846 of 7,846) |
| Components | 45 Blender components, including the color ramp, curve and node editors |
| Rust | HTML (113/113 elements), Flexbox 12/12, Grid 23/23, CSS 2.1 90/90, math functions, `var()`, CSS Color 4/5, Selectors 4, `@layer` / `@media` / `@supports` / `@scope` / `@container` / `@font-face` / `@property`, `@keyframes` animations and transitions, filters / blend modes / masks / `clip-path` / 2D transforms / `border-image`, bidi text, background images, `object-fit`, Tailwind v4, `rsx!`, `#[component]` with optional props and `key`, hooks, Blender components, browser-look form controls, headless testing |
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 29b7dd2..289d926 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -100,7 +100,7 @@ shared (`bui.host`).
`bui.host.Window` puts a kit context in a top-level window.
- **Native (Windows and Linux).** A window written in C: BUI's own Win32 host on Windows,
- X11 on Linux (Wayland sessions run it through XWayland). Input goes
+ X11 on Linux (and an experimental native Wayland host; X11 also runs through XWayland). Input goes
straight into the kit, and frames are presented by blitting only the
changed tiles. It follows the display's DPI (per-monitor on Windows,
`Xft.dpi` on X11) and paces animations to the display's refresh rate.
diff --git a/website/src/components/landing/Platforms.astro b/website/src/components/landing/Platforms.astro
index 0c02da3..1ea6ccb 100644
--- a/website/src/components/landing/Platforms.astro
+++ b/website/src/components/landing/Platforms.astro
@@ -7,7 +7,7 @@ import { repoFile } from "../../lib/docs";
type Cell = { text?: string; status?: "done" | "experimental" | "partial" };
const cols = ["Windows", "Linux", "macOS"];
const rows: [string, Cell, Cell, Cell][] = [
- ["Window", { text: "Native (Win32)" }, { text: "Native (X11; Wayland via XWayland)" }, { text: "Native (Cocoa)", status: "experimental" }],
+ ["Window", { text: "Native (Win32)" }, { text: "Native (X11, Wayland experimental)" }, { text: "Native (Cocoa)", status: "experimental" }],
["Python (pip install)", { text: "Wheels", status: "done" }, { text: "Wheels", status: "done" }, { text: "Wheels", status: "done" }],
["Rust", { status: "done" }, { text: "Build from source", status: "done" }, { status: "experimental" }],
["JavaScript / React", { text: "Prebuilt on npm", status: "done" }, { text: "Build the addon from source", status: "done" }, { text: "Headless for now", status: "partial" }],
diff --git a/website/src/content/docs/concepts/window-hosts.mdx b/website/src/content/docs/concepts/window-hosts.mdx
index 80b32c3..3ad735a 100644
--- a/website/src/content/docs/concepts/window-hosts.mdx
+++ b/website/src/content/docs/concepts/window-hosts.mdx
@@ -15,7 +15,8 @@ This page explains each host, how to choose one yourself, and what to expect on
<StatusTable columns={["Host", "Status", "Where and what"]} rows={[
["<strong>Win32</strong>", "done", "Windows. Native, written in C"],
- ["<strong>X11</strong>", "done", "Linux (Wayland sessions through XWayland). Native, written in C"],
+ ["<strong>X11</strong>", "done", "Linux (and Wayland sessions, through XWayland). Native, written in C"],
+ ["<strong>Wayland</strong>", "experimental", "Linux. Native, written in C, after Blender's GHOST. CPU renderer"],
["<strong>Cocoa</strong>", "experimental", "macOS. Native, tried by hand on two Apple Silicon Macs so far"],
["<strong>Tk</strong>", "done", "Anywhere Python has <code>tkinter</code>. Python only; the fallback"],
["<strong>Headless</strong>", "done", "Anywhere. No window: tests and screenshots"],
@@ -43,7 +44,11 @@ A plain Win32 window. Redraw requests coalesce into one render message, and the
The same API on Xlib. Button and key mapping follow Blender's `GHOST_SystemX11`. Damaged rectangles go to the window with `XPutImage`, or through GLX with the [GPU renderer](../rendering/). Timers, cross-thread wakes and frame pacing all run in one `select()` loop.
-Wayland sessions run it through XWayland, which every mainstream desktop provides.
+Wayland sessions can run it through XWayland, which every mainstream desktop provides.
+
+### Linux (Wayland) <Badge tone="preview">Experimental</Badge>
+
+A native Wayland host with the same API, modelled on Blender's `GHOST_SystemWayland`: xdg-shell toplevels (with server-side decorations when the compositor offers them), a `wl_seat` with xkbcommon for keys and key repeat, the pointer, the clipboard through `wl_data_device`, cursors from the cursor theme, the output's buffer scale, and frame callbacks for pacing. Damaged rectangles are copied into `wl_shm` buffers. libwayland-client and libwayland-cursor load at run time through Blender's `wayland_dynload`, so nothing is linked. A session with `WAYLAND_DISPLAY` gets this host; set `BUI_WINDOW_BACKEND=x11` to use X11, or `wayland` to force this one. It draws on the CPU: with the [GPU renderer](../rendering/) on (`BUI_GPU=1`), a Wayland session keeps X11 through XWayland until Wayland has its own EGL renderer. Per-window `BK_window_set_gpu` on a Wayland window is ignored for the same reason. Not done yet: IME, client-side decorations when the compositor has no server-side ones (GNOME shows no title bar), pointer warping, window positions.
### macOS (Cocoa) <Badge tone="preview">Experimental</Badge>
diff --git a/website/src/content/docs/project/limitations.mdx b/website/src/content/docs/project/limitations.mdx
index 8ce5d2e..d4e1510 100644
--- a/website/src/content/docs/project/limitations.mdx
+++ b/website/src/content/docs/project/limitations.mdx
@@ -34,7 +34,7 @@ BUI looks like Blender. It has Blender's Dark and Light themes (other Blender th
## Platforms
-- **Windows and Linux** (X11; Wayland through XWayland) are the supported platforms.
+- **Windows and Linux** (X11; native Wayland is experimental, CPU renderer only, and has no title bar on compositors without server-side decorations, such as GNOME) are the supported platforms.
- **macOS is experimental.** CI checks it and two people have tried it by hand on Apple Silicon Macs. JavaScript windows are headless there. See the [macOS testing guide](https://github.com/ppmpreetham/BUI/blob/main/docs/macos-testing.md).
- The npm packages are prebuilt for **Windows x64 only**. On Linux, build the addon from source.
diff --git a/website/src/content/docs/project/roadmap.mdx b/website/src/content/docs/project/roadmap.mdx
index bdc39e3..91b33d0 100644
--- a/website/src/content/docs/project/roadmap.mdx
+++ b/website/src/content/docs/project/roadmap.mdx
@@ -16,7 +16,7 @@ Each row has a status: **Works** when it works and is tested, **Partial** when c
<StatusTable
rows={[
["C runtime (the kit)", "done", "Nodes, Tk-style geometry managers, input, Blender widget drawing, damage rendering, undo, animation, text areas, canvases, scroll views, Blender's string search, expression evaluator, text-edit undo and float precision"],
- ["Native windows", "done", "Windows (Win32) and Linux (X11; Wayland through XWayland): DPI-aware, frame-paced animation, clipboard, cursors"],
+ ["Native windows", "done", "Windows (Win32) and Linux (X11; native Wayland is experimental): DPI-aware, frame-paced animation, clipboard, cursors"],
["Themes", "done", "Blender's Dark (default) and Light presets, switchable at run time from every language, or with <code>BUI_THEME</code>"],
["tkinter syntax", "done", "Every public tkinter and ttk name: 7,846 of 7,846"],
["Blender components", "done", "45 components, including the color ramp, curve and node editors"],
diff --git a/website/src/content/docs/reference/glossary.mdx b/website/src/content/docs/reference/glossary.mdx
index d0eb1ae..2bdbb18 100644
--- a/website/src/content/docs/reference/glossary.mdx
+++ b/website/src/content/docs/reference/glossary.mdx
@@ -248,7 +248,7 @@ Blender's basic size: 20 pixels at scale 1. Heights, paddings and corner radii a
### X11, XWayland
-**X11** is the classic window system on Linux; BUI's Linux host uses it. **XWayland** runs X11 apps on Wayland desktops, so BUI windows work there too.
+**X11** is the classic window system on Linux; BUI's main Linux host uses it. **XWayland** runs X11 apps on Wayland desktops, so BUI windows work there too, and BUI also has an experimental native Wayland host.
### zopra
diff --git a/website/src/content/docs/reference/platforms.mdx b/website/src/content/docs/reference/platforms.mdx
index 905e691..2d71d25 100644
--- a/website/src/content/docs/reference/platforms.mdx
+++ b/website/src/content/docs/reference/platforms.mdx
@@ -12,7 +12,7 @@ BUI runs on Windows, Linux and macOS. Windows and Linux are fully supported; mac
| | Windows | Linux | macOS |
| --- | --- | --- | --- |
-| Window | Native (Win32) | Native (X11; Wayland through XWayland) | Native (Cocoa), experimental |
+| Window | Native (Win32) | Native (X11, and Wayland: experimental) | Native (Cocoa), experimental |
| Python (`pip install`) | Works: wheels | Works: wheels | Works: wheels |
| Rust | Works | Works | Experimental |
| JavaScript and React | Works: prebuilt on npm | Works: build the addon from source (`npm run build`) | Headless |
@@ -34,7 +34,7 @@ BUI runs on Windows, Linux and macOS. Windows and Linux are fully supported; mac
## Linux
-- **Window:** a native X11 host. Wayland sessions run it through XWayland.
+- **Window:** a native X11 host, and an experimental native Wayland host (CPU renderer; the GPU renderer keeps X11 through XWayland on a Wayland session).
- **No X11 needed to import.** `libX11` and `libGL` load when the first window opens, so BUI imports and renders headless on servers and in containers without them. (Rust binaries are the exception: they link `libX11` directly.)
- **GPU renderer:** OpenGL 3.3 core, through GLX for windows and EGL for offscreen rendering. Where OpenGL is missing, BUI falls back to the CPU raster.
- **Tested on:** the C, Python, window and GPU parity tests pass on Mesa's software OpenGL and on an NVIDIA GPU. The suites also run under WSLg.
diff --git a/website/src/content/docs/start/installation.mdx b/website/src/content/docs/start/installation.mdx
index 8a81be9..15582ef 100644
--- a/website/src/content/docs/start/installation.mdx
+++ b/website/src/content/docs/start/installation.mdx
@@ -149,7 +149,7 @@ Want ImGui's widgets to *be* Blender's widgets? Build with `-DBUI_IMGUI_BLENDER_
| | Windows | Linux | macOS |
| --- | --- | --- | --- |
-| Window | Native (Win32) | Native (X11; Wayland through XWayland) | Native (Cocoa), experimental |
+| Window | Native (Win32) | Native (X11, and Wayland: experimental) | Native (Cocoa), experimental |
| Python wheels | Yes | Yes | Yes |
| Rust | Yes | Yes | Yes, experimental |
| JavaScript and React | Yes, prebuilt | Yes, build the addon | Headless for now |