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

9.0 KB
Raw Blame

Host integration guide

Most apps don't need this page. The kit (kit/, BUI_kit.h) and every language binding (tkinter and Qt syntax, the components, Rust, JavaScript, Dear ImGui) open native windows themselves and draw into BUI's own raster or GPU renderer. This page is about the lower-level render-sink layer: for hosts that want BUI's primitives in their own renderer. See "High-level syntax layers" at the bottom, and "Testing the Python bindings" for the one setup step they need.

Two drawing paths

Path Who uses it What it draws into
The kit's raster path Everything in kit/ and every binding A BuiRaster: the software raster (gpu/intern/gpu_raster.c) or, on a GPU window, Direct3D 11 / OpenGL instances. A native window presents it; headless code reads its pixels.
Render sinks (this page) api/bui_c_api.h, the Qt backend, bui.svg, buipy.demo_scene Triangles, lines, points and text runs from the immediate-mode GPU seam (gpu/intern/gpu_null.c), handed to a BuiGpuSink you install

The sink layer never opens a window, creates a GL context or picks a UI framework: every immediate-mode draw call funnels through the GPU seam into the sink you install. The kit's widgets don't go through it. To show kit widgets inside your own window, render the kit into a BuiRaster (BK_render) and blit the pixels, as bui.qt.BuiCanvas does below.

This document covers the three sink paths: plain C/C++, Qt (C++), and Python (PySide6/PyQt6 or headless).

                    ┌────────────────────────┐
   your host        │   sink (BuiGpuSink)    │
 ┌────────────────┐ │  triangles()           │      renderer
 │ ui toolkit ────┼─┼─▶ lines()  ────────────┼──▶  Qt QPainter /
 │ (bui_ui)       │ │  points()              │      PySide6 QPainter /
 │ gpu seam       │ │  text()  scissor()     │      OpenGL / SVG / console
 │ (gpu_null.c)   │ │  begin/end_frame()     │      — anything
 └────────────────┘ └────────────────────────┘

1. Plain C / C++

#include "bui_c_api.h"

static void my_triangles(void *user, const float (*coords)[2],
                         const float (*colors)[4], int count) {
  /* rasterize / record / forward `count` vertices */
}

BuiGpuSink sink = {0};
sink.user = my_renderer_state;
sink.triangles = my_triangles;
/* sink.lines, sink.points, sink.text, sink.scissor,
   sink.begin_frame, sink.end_frame are optional */
bui_set_render_sink(&sink);

bui_set_viewport(1280, 720);   /* pixels */
/* ... drive BUI drawing ... */
bui_set_render_sink(NULL);     /* restore the discarding backend */

The coordinate contract: 2D positions transformed by the current model matrix (identity matrices → pixel coordinates), colors as RGBA floats 0..1.

A complete minimal example is examples/svg_demo.c — it installs an SVG recorder and draws through the immediate-mode seam. It's an example, so configure with -DBUI_BUILD_EXAMPLES=ON first:

cmake -S . -B build -DBUI_BUILD_EXAMPLES=ON
cmake --build build --target bui_svg_demo
./build/examples/bui_svg_demo out.svg

2. Qt (C++)

Enable the backend and link it:

cmake -S . -B build-qt -DBUI_BUILD_QT_BACKEND=ON   # needs Qt5/Qt6 Widgets
cmake --build build-qt
#include "BuiWidget.h"   // backends/qt

BUI::BuiWidget *canvas = new BUI::BuiWidget(window);
canvas->render_func = [&](int w, int h) {
  // BUI draw calls; primitives land on QPainter automatically.
};

BUI::BuiWidget handles paint/resize/mouse plumbing; BUI::QtSink maps BUI primitives onto QPainter (per-vertex colors reduce to the first vertex color per primitive, which matches how the toolkit draws shapes). The backend does not require moc or OpenGL.

3. Python

The buipy extension (built by default when Python development files are found) exposes the same sink protocol to Python — no third-party packages.

Headless / CI — SVG output

import buipy
from bui.svg import SvgSink

sink = SvgSink(640, 480)
buipy.set_backend(sink)
buipy.demo_scene(640, 480)   # or your own draw calls
sink.save("frame.svg")

PySide6 / PyQt6 window

import sys
from PySide6.QtWidgets import QApplication   # PyQt6 works identically
import buipy
from bui.qt import BuiCanvas

app = QApplication(sys.argv)
canvas = BuiCanvas()               # default renders the demo scene
# canvas.render_func = lambda: <BUI draw calls>
canvas.resize(800, 600)
canvas.show()
sys.exit(app.exec())

BuiCanvas renders each paint pass into one buipy.Raster in C (the same software raster the kit uses) and shows it with a single QPainter.drawImage: pure Python, no shiboken build. The per-primitive QtPainterBackend (which maps each triangle, line and text run onto QPainter, like the C++ backend) is still in bui.qt for custom use.

High-level syntax layers

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 / X11 / Cocoa windows, the Cocoa one still experimental, or Tk with BUI_HOST=tk). They use the kit's raster path, not render sinks:

Qt syntax — bui.qtsyntax

from bui.qtsyntax import QApplication, QWidget, QPushButton, QLabel, QVBoxLayout

app = QApplication([])
window = QWidget()
window.setWindowTitle("BUI — Qt syntax")
layout = QVBoxLayout()
status = QLabel("Press the button.")
button = QPushButton("Click me")
button.clicked.connect(lambda: status.setText("Clicked!"))
layout.addWidget(status)
layout.addWidget(button)
window.setLayout(layout)
window.show()
app.exec()

Supported surface: see docs/qt.md and SYNTAX_COVERAGE.md for the exact, honest list (widgets, layouts, signals, QPainter, menus, timers, a setStyleSheet subset). Anything not yet implemented raises AttributeError. Neither PySide nor PyQt is needed: windows come from bui.host, as above.

tkinter syntax — bui.tksyntax

from bui.tksyntax import Tk, Label, Button, Checkbutton

root = Tk()
root.title("BUI — tkinter syntax")
root.geometry("420x260")
status = Label(root, text="")
status.pack()
Button(root, text="Click me", command=lambda: status.config(text="Clicked!")).pack(pady=4)
Checkbutton(root, text="Enable feature").pack()
root.mainloop()

Every public tkinter and ttk name is implemented (7,846 of 7,846); see docs/tkinter.md. Widgets are kit nodes drawn by the kit's raster path in a bui.host window. Existing programs run unchanged with python -m bui.tksyntax app.py (or blenderui-tk app.py after pip install blenderui).

Testing the Python bindings

buipy is a compiled extension — it lives in the CMake build tree and is built for one specific interpreter. ModuleNotFoundError: No module named 'buipy' means Python cannot find (or cannot load) that file. Three ways to fix, fastest first:

1. Nothing to install (auto-locate). import bui finds the extension in build*/bindings/python automatically. Just build and run:

cmake -S . -B build -G "MinGW Makefiles"
cmake --build build --target buipy
python examples/python_demo.py            # needs the interpreter CMake used

2. Match the interpreter. The extension only loads in the interpreter it was built for (if CMake found Python 3.14, it built buipy.cp314-win_amd64.pyd). Check which one CMake picked and run that one:

grep Python3_EXECUTABLE build/CMakeCache.txt
C:/Path/Python314/python.exe examples/python_demo.py

To target a different interpreter, point CMake at it explicitly:

cmake -S . -B build-py312 -DPython3_EXECUTABLE="C:/Path/Python312/python.exe"
cmake --build build-py312 --target buipy

3. pip install (no PYTHONPATH ever again):

cmake --build build --target buipy
python -m pip install bindings/python     # stages bui/ + the .pyd into site-packages
python -c "import bui; print(bui.version())"

Sanity check either way:

python -c "import bui; print(bui.version())"     # -> 0.1.0
python -m pytest bindings/python/tests           # or: ctest --test-dir build

Wire format reference

Callback Payload
begin_frame(w, h) Start of a frame batch; viewport in pixels
scissor(x, y, w, h) Clip rect; w/h ≤ 0 clears clipping
triangles(coords, colors, n) Non-indexed triangles, 3 vertices each
lines(coords, colors, n) Line list, endpoints in pairs
points(coords, colors, n, size) Points at size pixels
text(x, y, text, size, rgba) UTF-8 text run at baseline
end_frame() End of frame batch

All coordinates are 2D floats; colors RGBA floats 0..1. Callbacks may be invoked with or without the GIL held — the Python bindings handle this internally.