A surface is content GPUI did not draw: a video frame from a hardware decoder, a 3D viewport on its own device, or a texture computed off-thread. surface() and gpu_canvas() composite it as an ordinary element — no seam to implement, no install hook, no CPU round-trip.
If your producer already has a handle GPUI can import, hand it to surface(). If it needs the window's own device to make one, open a gpu_canvas() and paint through the context it gives you.
use gpui::{ObjectFit, surface};
// a decoded frame, a shared texture, or a dma-buf you already hold
let picture = surface(source)
.object_fit(ObjectFit::Contain);use gpui::{GpuCanvasContext, gpu_canvas};
let viewport = gpu_canvas(|gpu: &mut GpuCanvasContext| {
// `frame` is a SurfaceSource from your producer
gpu.paint_surface(frame);
});Both return ordinary elements. surface() takes a SurfaceSource and fits it into the element's bounds with the same ObjectFit modes an image uses. gpu_canvas() is a Div in every respect — styling, layout and interactivity are forwarded to the box — whose paint phase adds one primitive after the box. There is no with_surface and nothing to install.
SurfaceSource names only the transport this build is compiled against, so the engine stays free of every graphics API but one. Each variant reaches the renderer as a view it samples; the renderer cannot tell how the view was made.
| platform | source | payload | what it is |
|---|---|---|---|
| macOS · iOS | CoreVideo | CFRetained<CVPixelBuffer> | an IOSurface-backed image buffer |
| Windows | DirectX | DirectXSource | a Direct3D 11 texture, or a view a producer already made |
| Linux | DmaBuf | DmaBufHandle | an fd plus a DRM fourcc, modifier, stride and offset |
A PaintSurface carries the source with its bounds, content mask and draw order. Its to_quad_record is the same quad record a styled element builds, which is why a surface clips and stacks like any other layer.
A producer that renders on the window renderer's own device never leaves it: paint_texture samples the texture view and queue ordering is the only synchronization. A producer with its own device exports an OS handle and a fence, and paint_surface imports it.
use gpui::{Corners, gpu_canvas};
use gpui_wgpu::WgpuRenderer;
let viewport = gpu_canvas(|gpu| {
// the device and queue this window already draws with
let (device, queue) = gpu.device::<WgpuRenderer>();
// draw into a texture on `device`, then composite it
gpu.paint_texture(handle, Corners::default(), 1.0, false);
});gpui_wgpu is the published bite-gp-wgpu. On Apple the renderer type is MetalRenderer and on Windows DirectXRenderer; the device each lends is that backend's own handle.
Nothing about a surface names a video decoder or a 3D engine. The crates that do are public and sit above the facade, exactly where the architecture puts them.
Bridges a producer's own device: dma-buf on Linux, a shared texture and fence on Windows, IOSurface planned on macOS. It is the crate that makes an external renderer or decoder a surface source.
A hardware-decoded video player on the same path: a VA-API decoder renders into driver-tiled NV12 surfaces, exports them as dma-bufs, and the element paces playback with HTML5-shaped controls.
A Bevy scene inside a GPUI window, with Bevy built headless: no winit, no window, no event loop of its own. GPUI owns the cadence and Bevy renders into the window renderer's own device.
The same primitive carries four kinds of work: hardware video (a decoder exports NV12 buffers), embedded 3D viewports (a renderer on its own device), emulators and capture pipelines (frames leave another process), and computed textures (a simulation or a chart rendered off-thread). None of them is a seam in this engine; all of them are a source the renderer samples.
Ways to extend has all four, and Bring your own platform is the host side. If what you want to change is the algorithm a seam runs, that is a swap.