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

fix: readme

Preetham Pemmasani4bec4f26a2e8
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 1e22aff..d4e46e7 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -42,7 +42,7 @@ application code; everything it needs arrives through `types/`, `gpu/`, or
| `gpu/` | The draw surface used by the toolkit (`GPU_*`, `imm*`) behind seam headers + a null backend that *records and forwards*: with a sink installed it emits screen-space primitives (`GPU_backend_sink.h`); without one it discards them. Theme colors reach the GPU layer through function-pointer hooks. | **Builds + tested** |
| `compat/` | Seam headers carrying upstream API names (`RNA_access.hh`, `BLF_api.hh`, …) with BUI-owned opaque types and stub implementations (`intern/bui_stubs.cc`). | **Builds** |
| `ui/` | The toolkit sources from `editors/interface`: interface.cc family, widgets, handlers, regions, view2d, views, textbox. Option-gated (`-DBUI_BUILD_UI=ON`). | **Compiles + links** |
-| `kit/` | Blender's UI as a retained-mode C runtime: node tree, uiLayout-style layout, `interface_handlers.cc` interaction rules, widget drawing ported from `interface_widgets.cc` (widget-base shader parameters rendered by `gpu/` raster), menus, color picker, views, editors; Tk-style pack/grid/place geometry managers, canvas display list, multi-line text area; UI undo/redo, Tab field traversal, vertical multi-drag, panel animation; damage-driven rendering; native Win32 window host (`kit_window.c`). C API: `kit/include/BUI_kit.h`. | **Builds + tested** |
+| `kit/` | Blender's UI as a retained-mode C runtime: node tree, uiLayout-style layout, `interface_handlers.cc` interaction rules, widget drawing ported from `interface_widgets.cc` (widget-base shader parameters rendered by `gpu/` raster), menus, color picker, views, editors; Tk-style pack/grid/place geometry managers, canvas display list, multi-line text area; UI undo/redo, Tab field traversal, vertical multi-drag, panel animation; damage-driven rendering; native window hosts for Win32 and X11 (`kit_window_win32.c`, `kit_window_x11.c`; `kit_window_null.c` elsewhere). C API: `kit/include/BUI_kit.h`. | **Builds + tested** |
| `api/` | `bui_c_api.h` — small stable C ABI: version info + sink/viewport plumbing for hosts and bindings. | **Builds + tested** |
| `bindings/python/` | `buipy` CPython extension (no third-party deps) + `bui` package: `bui.components` (Blender component library), `bui.qtsyntax` / `bui.tksyntax` (Qt / tkinter APIs as thin facades over the kit), `bui.host` (native or Tk windows), `SvgSink` headless renderer, `bui.qt.BuiCanvas` PySide6/PyQt6 widget. | **Builds + tested** |
| `backends/qt/` | C++ Qt backend: `BUI::QtSink` (BuiGpuSink → QPainter) + `BUI::BuiWidget` (QWidget host, no moc needed). Gate: `-DBUI_BUILD_QT_BACKEND=ON`. | **Shipped** (builds where Qt exists) |
diff --git a/INTEGRATION.md b/INTEGRATION.md
index 5ca7334..8623854 100644
--- a/INTEGRATION.md
+++ b/INTEGRATION.md
@@ -121,7 +121,7 @@ shiboken build.
Two facades speak the syntax of established toolkits on top of the C kit
(`kit/`, exposed to Python as `buipy.KitNode` / `buipy.KitContext`): widgets
are kit nodes, layouts are the kit's C geometry managers, and windows come
-from `bui.host` (native Win32 on Windows, Tk elsewhere or with
+from `bui.host` (native Win32 / X11 on Windows and Linux, Tk on macOS or with
`BUI_HOST=tk`):
### Qt syntax — `bui.qtsyntax`
diff --git a/README.md b/README.md
index 84dc180..f35ba87 100644
--- a/README.md
+++ b/README.md
@@ -177,7 +177,8 @@ npx bui build app.jsx # or ship it: app.exe, one 5 MB file
is a DOM-like API (`createElement`, `appendChild`, `addEventListener`) with
the same signals.
-Node.js 18+ or Bun, Windows x64 for now. Guide:
+Node.js 18+ or Bun. Prebuilt for Windows x64; on Linux, build the addon from
+source (`npm run build` in `bindings/node`) and windows are native. Guide:
[docs/javascript.md](docs/javascript.md).
### Rust
@@ -348,7 +349,7 @@ error: rsx!: `bg-sky-50O` is not a Tailwind utility; did you mean `bg-sky-500` o
| Area | What works |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C runtime (`kit/`) | Nodes, Tk-style geometry managers, input, Blender widget drawing, damage rendering, undo, animation, text area, canvas, scroll views |
-| Windows | A native Win32 window in C: DPI-aware, vsync-paced animation, clipboard, cursors, window-manager features |
+| Native windows | Windows (Win32) and Linux (X11; Wayland through XWayland), 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 and curve 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, background images, `object-fit`, Tailwind v4, `rsx!`, `#[component]` with optional props and `key`, hooks, Blender components, browser-look form controls, filters / blend modes / masks / 2D transforms, headless testing |
@@ -362,10 +363,11 @@ error: rsx!: `bg-sky-50O` is not a Tailwind utility; did you mean `bg-sky-500` o
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Qt syntax (~25%) | Model/view classes, docks, toolbars, splitters, Qt stylesheets ([details](docs/qt.md#coverage)) |
| CSS (261 of 745 W3C properties render, 129 more parse) | 3D transforms, OpenType font features, multi-column layout. Most of the remaining W3C list is drafts, speech, print and SVG ([breakdown](docs/rust.md#coverage)) |
-| Text | No text wrapping around floats; no right-to-left shaping |
+| Text | No text wrapping around floats; right-to-left text is reordered (bidi) but not shaped (Arabic joining), and no OpenType features |
| Rust components | No async resources (`use_resource`); no generic components |
-| JavaScript / React on Linux / macOS | Prebuilt for Windows x64 only (elsewhere: build from source, headless); events reach JavaScript after BUI handled them (no native `preventDefault`), and `event.target` is the deepest _listening_ element |
-| Linux / macOS | They work through a fallback window (the stdlib Tk window shows BUI's frame), but they're less tested. No native window host and no GPU renderer yet |
+| JavaScript / React packages | npm packages are prebuilt for Windows x64 only (on Linux, build the addon from source); events reach JavaScript after BUI handled them (no native `preventDefault`), and `event.target` is the deepest _listening_ element |
+| macOS | No native window host yet: Python apps run in the stdlib Tk window (which shows BUI's frame); Rust and JavaScript apps can only run headless there |
+| GPU renderer on Linux / macOS | The GPU renderer is Direct3D 11, so Windows only; Linux and macOS draw with the software raster |
| crates.io | The crates are ready to publish but not published yet; use the git dependency for now |
### 🗺️ Planned
@@ -374,7 +376,7 @@ error: rsx!: `bg-sky-50O` is not a Tailwind utility; did you mean `bg-sky-500` o
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **WebAssembly** | The kit in the browser: the raster blits to `<canvas>`, DOM events feed the kit; `@blender-ui/react` and the DOM-like API on top, unchanged |
| **egui** | BUI panels inside egui, plus a Blender-styled theme |
-| **Native Linux / macOS windows** | Wayland / X11 and Cocoa hosts in C, like the Win32 one |
+| **Native macOS windows** | A Cocoa host in C, like the Win32 and X11 ones (and a native Wayland host for Linux) |
| **More GPU backends** | Vulkan / Metal / WebGPU drawing the same instance stream as Direct3D 11 |
| **More languages** | C#, Go, Zig, Swift, Kotlin and Lua over the same C header; Dear ImGui; Godot, Unity and Bevy; Flutter |
@@ -389,7 +391,7 @@ error: rsx!: `bg-sky-50O` is not a Tailwind utility; did you mean `bg-sky-500` o
│
renderer: damage-driven software raster (parallel) or GPU (Direct3D 11, instanced, opt-in)
│
- window: native Win32 window · stdlib Tk window (elsewhere) · headless (tests, screenshots)
+ window: native Win32 / X11 window · stdlib Tk window (macOS) · headless (tests, screenshots)
```
- **Blender's real UI code.** Widget drawing is a C port of Blender's
@@ -611,7 +613,7 @@ cd bindings/rust && cargo test # Rust: CSS, Tailwind, rsx!, hooks,
| Path | Contents |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `kit/` | The C runtime: nodes, input, widget drawing (the `interface_widgets.cc` port), menus, geometry managers, canvas, the Win32 host. API: `kit/include/BUI_kit.h` |
+| `kit/` | The C runtime: nodes, input, widget drawing (the `interface_widgets.cc` port), menus, geometry managers, canvas, the Win32 and X11 window hosts. API: `kit/include/BUI_kit.h` |
| `gpu/` | Software raster, Direct3D 11 renderer (`gpu_d3d11.c`, `shaders/`, Slug text), text engine (stb_truetype + embedded Inter, or GDI) |
| `core/`, `types/` | Blender's `blenlib` subset and data types |
| `ui/`, `compat/` | Blender's original interface sources and the seams replacing Blender's application APIs |
diff --git a/bindings/rust/blenderui/README.md b/bindings/rust/blenderui/README.md
index e16c70e..863acdb 100644
--- a/bindings/rust/blenderui/README.md
+++ b/bindings/rust/blenderui/README.md
@@ -1,7 +1,9 @@
# blenderui
Blender's UI for Rust, with [gpui](https://www.gpui.rs)'s syntax, every HTML
-element and CSS. Form controls are Blender's own widgets; layout is
+element and CSS. Form controls look like a browser's, or are Blender's own
+widgets inside `styled` and as the capitalized Blender components (`<NumberSlider>`,
+`<Button>` ...); layout is
[taffy](https://github.com/DioxusLabs/taffy); drawing and input come from the
[BUI](https://github.com/ppmpreetham/BUI) C kit (built from source, so CMake
and a C compiler are needed).
diff --git a/docs/c-api.md b/docs/c-api.md
index 782c9b2..7ad7c18 100644
--- a/docs/c-api.md
+++ b/docs/c-api.md
@@ -53,7 +53,7 @@ int main(void)
host.emit = on_event; /* the window fills in the rest */
BK_context_set_host(ctx, &host);
- if (BK_window_supported()) { /* Windows: native window */
+ if (BK_window_supported()) { /* Windows, Linux: native window */
BKWindow *win = BK_window_new(ctx, "BUI from C", 320, 120);
BK_window_show(win);
BK_window_run();
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 5ab25a0..2f3d2f7 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -79,7 +79,7 @@ shared (`bui.host`).
| Variable | Effect |
|---|---|
| `BUIPY_BUILD_DIR` | Directory containing the built `buipy` extension |
-| `BUI_HOST=tk` | Force the stdlib-Tk window host even where the native host exists (Windows) |
+| `BUI_HOST=tk` | Force the stdlib-Tk window host even where the native host exists (Windows, Linux) |
| `BUI_UI_SCALE` | Fix the UI scale (for example `1.5`) instead of following the monitor's DPI |
| `BUI_GPU=1` | Draw native windows on the GPU (Direct3D 11). `BUI_GPU=0` forces the software raster. Overrides `bui.set_gpu()` / `.gpu(true)` |
| `BUI_GPU_DEBUG=1` | Print why the GPU renderer could not start |
@@ -91,12 +91,14 @@ shared (`bui.host`).
`bui.host.Window` puts a kit context in a top-level window.
-- **Native (Windows).** A Win32 window written in C. Input goes straight
- into the kit, and frames are presented by blitting only the changed tiles.
- It follows per-monitor DPI and syncs animations to vsync.
-- **Tk (everywhere else, or with `BUI_HOST=tk`).** A stdlib `tkinter`
- window that shows the kit's frame buffer and forwards input to it.
- The UI and the API are identical, but presenting is a little slower.
+- **Native (Windows and Linux).** A window written in C: Win32 on Windows,
+ X11 on Linux (Wayland sessions run it 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.
+- **Tk (macOS, or with `BUI_HOST=tk`).** A stdlib `tkinter` window that
+ shows the kit's frame buffer and forwards input to it. The UI and the API
+ are identical, but presenting is a little slower.
### GPU rendering
@@ -126,8 +128,8 @@ Both renderers draw the same pixels. The GPU uses far less CPU per frame
[benchmark](../bindings/rust/bench/README.md)), but the process needs about
10 MB more RAM plus GPU memory. The device starts in the background, so the
first frames are drawn on the CPU and the switch happens a few frames in.
-Without a GPU, or on Linux/macOS for now, windows stay on the software
-raster.
+The GPU renderer is Direct3D 11: without a GPU, and on Linux and macOS,
+windows stay on the software raster.
`bui.host.run()` runs one loop for all windows, `bui.host.update()` processes
pending events once, and `bui.host.quit()` stops the loop.
diff --git a/docs/javascript.md b/docs/javascript.md
index a018384..68f8b63 100644
--- a/docs/javascript.md
+++ b/docs/javascript.md
@@ -13,9 +13,10 @@ engine ([Standalone apps](#standalone-apps)).
| [`@blender-ui/native`](https://www.npmjs.com/package/@blender-ui/native) (`bindings/node`) | A DOM-like API (`createElement`, `setAttribute`, `appendChild`, `addEventListener`, `requestAnimationFrame`) and signals |
| [`@blender-ui/react`](https://www.npmjs.com/package/@blender-ui/react) (`bindings/react`) | A React 19.3 renderer; React's hooks by React's names, backed by signals |
-**Platforms:** prebuilt for Windows x64. On other platforms, build the addon
-from source (see [Building](#building)) and use `headless: true` for now. A
-browser (WebAssembly) build is planned.
+**Platforms:** prebuilt for Windows x64. On Linux, build the addon from
+source (see [Building](#building)); windows are native X11 windows. macOS has
+no native window host yet, so there use `headless: true`. A browser
+(WebAssembly) build is planned.
## Plain JavaScript
diff --git a/docs/publishing.md b/docs/publishing.md
index 03c6b18..d2ffbd2 100644
--- a/docs/publishing.md
+++ b/docs/publishing.md
@@ -85,11 +85,17 @@ No API tokens are stored anywhere.
## Known gaps before 1.0
-- Linux and macOS wheels build in CI but haven't been exercised
- interactively. Their window host is the stdlib Tk window, so the system
- Python needs `tkinter` (for example `python3-tk`).
-- MSVC builds: the forced-include shim has an MSVC (`/FI`) path, but MSVC
- isn't tested, which is why CI uses MinGW on Windows.
+- Linux wheels: the native X11 window host is compiled only when CMake finds
+ the X11 headers, and the cibuildwheel build doesn't install them, so wheels
+ from PyPI use the stdlib Tk window on Linux (built from source with
+ `libx11-dev` / `libX11-devel`, BUI uses its native X11 window). Installing
+ `libX11-devel` in `[tool.cibuildwheel.linux] before-all` would give the
+ wheels the native host.
+- macOS has no native window host yet: its wheels use the stdlib Tk window,
+ so the Python needs `tkinter` (for example from python.org or
+ `brew install python-tk`).
+- MSVC builds work (the Rust crate and the CMake build use Visual Studio's
+ toolchain), but the published Windows wheels are built with MinGW.
- No `musllinux` or 32-bit wheels yet (skipped in `[tool.cibuildwheel]`).
- The README's images use relative paths. PyPI shows them once
`[project.urls]` points to the public repository and the paths are made
diff --git a/docs/qt.md b/docs/qt.md
index df88121..a4cf3eb 100644
--- a/docs/qt.md
+++ b/docs/qt.md
@@ -76,7 +76,7 @@ is much lower. See [getting-started.md](getting-started.md#gpu-rendering).
| `QVBoxLayout` / `QHBoxLayout` | Tk's packer in C, with Qt semantics: stretch factors, expanding size policies, spacing between items only, margins on top-level layouts only |
| `QGridLayout` / `QFormLayout` | Tk's gridder in C (`setColumnStretch` maps to column weights) |
| Signals | Plain Python (`Signal` / `pyqtSignal`). Slots that take fewer arguments than the signal sends get fewer. |
-| `QApplication.exec()` | `bui.host.run()`: a native window on Windows, a Tk-hosted window elsewhere |
+| `QApplication.exec()` | `bui.host.run()`: a native window on Windows and Linux, a Tk-hosted window on macOS |
| `QTimer`, `QPropertyAnimation` | Window timers; animations step at 120 Hz with easing curves |
## Supported classes
diff --git a/docs/rust.md b/docs/rust.md
index d815448..088f21c 100644
--- a/docs/rust.md
+++ b/docs/rust.md
@@ -5,8 +5,9 @@ the syntax of [gpui](https://www.gpui.rs): views implement `Render`, elements
are built with `div().flex().gap_2().child(...)`, and listeners come from
`cx.listener(...)`. On top of gpui's model it supports **every HTML element**
and **CSS**: `<style>` sheets, selectors, the cascade, flexbox, grid, tables,
-inline text that wraps, lists, `<details>`, and form controls that are real
-Blender widgets.
+inline text that wraps, lists, `<details>`, and form controls that look like a
+browser's, or like Blender's real widgets inside `styled` and as the
+capitalized Blender components.
<p align="center"><img src="images/rust-showcase.png" width="640" alt="The Rust showcase example"></p>
@@ -615,23 +616,25 @@ The `gdi-text` feature uses Windows' GDI engine and system fonts.
## Limitations
-- **Floats** place block boxes, but text does not wrap around them; `direction: rtl`
- lays boxes out right to left, but text itself is not shaped right to left.
+- **Floats** place block boxes, but text does not wrap around them. Right-to-left
+ text is reordered (bidi) but not shaped (no Arabic joining).
- **Fonts**: `font-family` picks a face per element (registered, `@font-face`,
installed or generic `monospace` / `serif`); there is no per-glyph fallback
between faces of a list.
- **Effects and animation**: see "Not done yet" under [Coverage](#coverage).
-- **Transforms**: `translate` only; `scale()` and `rotate()` are ignored.
+- **Transforms**: every 2D transform draws, but hit testing uses the
+ untransformed box; 3D transforms have no effect.
- **Inline boxes** paint their background per word; borders and padding on
inline elements (`<kbd>`, `<code>`) are not drawn.
- **Widgets draw above page content**, so a `z-index`ed box (a `<dialog>`)
over a form field does not cover the field.
- **Images**: PNG only, nearest-neighbour scaling. `video`, `audio`,
`iframe` show a placeholder.
-- **Windows** are native on Windows; elsewhere use `Application::headless()`
- until the Linux and macOS window hosts exist.
-- `text-align: justify` aligns left; `<table>` columns are equal-width
- (weighted by `colspan`) rather than sized to their content.
+- **Windows** are native on Windows (Win32) and Linux (X11); macOS has no
+ window host yet, so there use `Application::headless()`. The GPU renderer
+ is Windows only.
+- `text-align: justify` aligns left. Table columns are sized from their
+ widest single-line content, a simpler version of browsers' auto layout.
## How it works
@@ -647,7 +650,7 @@ The `gdi-text` feature uses Windows' GDI engine and system fonts.
paint ─► one display list on a kit canvas form controls ─► kit widget nodes,
│ (rects, rounded rects, text, images) placed at their boxes
▼
- C kit: input, hit testing, Blender widget drawing, damage rendering, Win32 window
+ C kit: input, hit testing, Blender widget drawing, damage rendering, Win32 / X11 window
```
- `blenderui-sys` is the raw FFI over `kit/include/BUI_kit.h`; its build script