Why maintain an engine fork? Replace the text shaper or the layout solver, decorate the frame pipeline, composite pixels GPUI did not draw, or bring the platform itself. Four ways to change the engine, and not one of them edits a div().
The distinction is not stylistic: it decides what you hand over, which boundary it plugs into, and what publishing it commits the project to. Everything below is one of the four.
Implements FramePipeline and delegates. It is handed every pass of every frame it admits, forwards the ones it does not change, and decides the ones it does — including whether the frame runs at all.
Implements one of the algorithm seams and is installed at bootstrap in place of the default. One implementation per seam, chosen when the application is built.
Replaces no seam and decorates no pipeline. It builds on the published surface and pushes foreign pixels into the frame — a 3D viewport, a decoded video frame, or a texture you computed.
Supplies the platform the application runs on: one of the four built-in backends compiled in by cfg, or a Platform implementation of your own.
Every swappable boundary is defined in a standalone layer crate, backed by a default implementation, and re-exported under use gpui::*. Two have a published second implementation; the third — the scene renderer — has no hook to install one through, and this page says so rather than implying otherwise.
Text shaping, line layout, and glyph rasterization.
Application::with_text_system(Arc<dyn TextSystem>)
Translating the reactive element tree into positioned layout boxes.
Application::with_layout_engine(impl Fn() -> Box<dyn LayoutEngine>)
Lowering the scene intermediate representation (IR) into GPU drawing commands.
none — the trait is the boundary
No Application setter installs one today: the trait is the boundary, and the platform picks the implementation. A second one needs a door before it can be a crate.
The open seams →One wrap is published from its own repository; two ship inside the facade as decorators you can stack without depending on anything. All three implement the same trait, and all three forward the passes they do not change.
The seam is FramePipeline, declared in gpui_authoring and installed with Application::with_frame_pipeline. Its default is StandardImmediatePipeline with the shipped .max_fps(n) and .instrumented(metrics) decorators — the frame governor the one-pager shows is that default configured, not a second implementation.
Reads the frame's passes and the asks that did not draw: a policy-driven rate on one side, a ledger of what each pass cost on the other. A decorator you install without changing a view.
lib: gpui_pass
Using gpui_pass →The facade's own rate cap: draw every Nth ask, decided from one number and the last frame.
lib: gpui_runtime
The facade's own accounting: an Instant around each root pass, summed into running phase totals.
lib: gpui_runtime
A wrap implements FramePipeline and delegates. Every pass has a default that calls the Window method behind it, so a decorator is only as transparent as the passes it explicitly forwards — which is the whole of the contract.
A wrap goes where any pipeline goes — the factory you hand to with_frame_pipeline — and stacks in any order and any number. Nothing in the tree is forked, so there is no patch to rebase when the engine moves. The published one is bite-gp-pass, and cargo add bite-gp-pass is the whole of its install.
A surface is content GPUI did not draw: a decoded video frame, a 3D viewport on its own device, or a texture computed off-thread. It replaces no seam and decorates no pipeline — it is an ordinary element that composites a foreign buffer with no CPU copy.
A same-device texture is sampled with no export and no fence; an exported handle costs the producer a hand-off per frame. The measured difference, the platform matrix, and the 3D and video producers are on Bring your own surface.
The platform is the seam the application does not switch at runtime: it is chosen when the app is built, and it supplies the event loop, windows, displays, clipboard and input. Four ship; a platform of your own is an impl, not a fork.
| platform | backend | selected by |
|---|---|---|
| macOS | MacPlatform over gpui_apple’s Metal renderer | cfg(target_os = "macos") |
| Windows | WindowsPlatform over Direct3D 11 | cfg(target_os = "windows") |
| Linux | LinuxPlatform over X11 or Wayland, and gpui_wgpu | cfg(any(linux, freebsd)) |
| Web | WebPlatform on wasm32, through wgpu to WebGPU | cfg(target_family = "wasm") |
| Headless | the test platform and the headless Linux platform | test-support, or ZED_HEADLESS |
| iOS · Android | the third-party gpui-mobile crate, not yet ported to these crates | its own Platform impl |
The hook is Application::with_platform, and the trait is declared in gpui_platform — the leaf that links no drivers. What a platform owns, and what bringing one takes, is on Bring your own platform.
The two published swaps are ordinary crate dependencies. Nothing in the tree is forked, so there is no patch to rebase when the engine moves — and because each published package keeps its library target name, use gpui_parley::… and use gpui_morphorm::… are what your code already says.
# both published swaps, one manifest
[dependencies]
bite-gpui = "1.25"
bite-gp-parley = "1.21"
bite-gp-morphorm = "1.21"use gpui::*;
use gpui_morphorm::MorphormLayoutEngine;
use gpui_parley::ParleyTextSystem;
fn main() {
application()
.with_text_system(ParleyTextSystem::new())
.with_layout_engine(|| Box::new(MorphormLayoutEngine::new()))
.run(|cx: &mut App| { /* the same div() tree */ });
}We explicitly document the two unbuilt seams so external contributors know exactly where the architectural boundaries lie. The frame pipeline is no longer one: bite-gp-pass is that out-of-tree wrap.
| seam | what it would take | filed as |
|---|---|---|
| Platform | A platform that needs no display, so a CI job can render. The built-in route is the facade with its platform bundle dropped — default-features = false — plus the TestPlatform the test harness already runs on. | headless-platform |
| SceneRenderer | A renderer out of tree, which is what a raw render-pass blit would actually have to be — and a door at the facade first, because there is no setter to install one through. | scene-renderer |
These are the categories the project files its own work under — a new flavour of a swappable, a decorator, a new authoring surface — and the demos page carries the whole taxonomy with what each category is for.
The wgpu renderer and the frame governor are on the one-pager's shelf,
but neither is a swap: WgpuRenderer is the scene renderer
the Linux platform installs, and the governor is
StandardImmediatePipeline.max_fps(60) with
.instrumented(…) — shipped decorators, configured rather
than installed. The seam that replaces the renderer is
SceneRenderer, and it has no hook yet.
The Combo Studio is the interactive version
of this shelf: it stacks the add-ons and the platform backend, and shows
the
main.rs they produce. Two of its four add-ons are the
published crates above; the others are shipped configuration, as the
panel itself says.
The four crates, and the repositories they are developed and released from.