TestPlatform
in treeThe in-process platform the test harness draws through: deterministic dispatchers, a simulated display and window, and no display server.
gpui_authoring · test-support
Ways to extend · Serve
Use one of ours, or bring your own.
The platform is the host seam: it supplies the event loop, the windows, the displays, the clipboard and the GPU backend the scene draws through. Four ship and two harnesses exist for tests; a platform of your own is a Platform impl, not a fork.
4
Built-in platforms
macOS, Windows, Linux, Web
1
Host seam
Platform, in gpui_platform
0
Drivers linked
The leaf links nothing
1
Hook
Application::with_platform
Built in
One backend per build, selected by cfg.
A platform is never chosen by a manifest line or a runtime string. The facade's platform bundle enables the one for the target, and the application is constructed with it — which is why the same source compiles on all four. The two mobile slabs are the exception: they are a third-party platform crate, not a backend in this tree.
The wgpu renderer is the one two platforms share: Linux always draws through it, and the web reaches WebGPU through the same crate. Metal and Direct3D are native backends with their own command encoders.
What a platform owns
Everything a plain window cannot name.
The trait is the contract between the facade and a backend. It is declared in gpui_platform, the acyclic leaf that links no drivers — a backend implements it without depending on the framework.
- the event loop, and when a frame is asked for
- window creation, its raw handles, and the swapchain
- displays, their bounds and their refresh intervals
- the clipboard, drag and drop, and the input queue
- the GPU backend's devices, and the renderer a window draws through
- screen capture, thermal state and system appearance
The seam, in one line
Application::with_platform(Rc<dyn Platform>) — the constructor, not a setter. A platform is chosen with the application rather than chained onto it. The default is the host's own, compiled in by cfg.
Bring your own
The test harness is the proof it is a seam.
Two implementations in the tree are not desktop platforms at all, and they are what a new backend can be modelled on: neither has a window server, and one has no GPU.
Headless Linux
in treeA platform with no compositor surface: layout, text shaping and entity plumbing run normally, and draw discards the scene.
gpui_linux · ZED_HEADLESS
An out-of-tree platform implements the same trait, gets a WindowId space and a renderer, and is installed with with_platform. The mobile path is the third-party gpui-mobile crate, which targets iOS (Metal) and Android (wgpu/Vulkan) — it is not ported to these crates yet.
- iOS and Android are not built in. gpui_apple already compiles for iOS and shares its Metal and text code, but there is no iOS Platform or entrypoint here; Android has no backend in this tree.
- A platform is a large impl. The trait covers the event loop, window creation, displays, input, clipboard, GPU specs and screen capture. It is the widest seam in the stack, and the one where a fork is most tempting — which is why it is documented as its own way.
- The renderer follows the platform. A backend picks the SceneRenderer its windows draw through; that is why a renderer is not a swap today, and why a second one needs a door first (the open seams).
Limits
What the plate does not do.
- It links nothing. The leaf depends only on the vocabulary crates, never on a driver or a windowing library. A backend does the linking, in its own crate.
- It is not a swap at runtime. There is no request_windowing-style switch between backends; a platform is fixed when the application is built. The one thing that changes at runtime is windowing mode, not the backend.
- It is not the distribution story. Versions, crates and provenance are the comparison and the quickstart; this page is about the host.
The rest of the ways
Ways to extend has all four, and Bring your own surface is the pixels side. If what you want to change is the algorithm a seam runs, that is a swap.