Function surface 

pub fn surface(source: impl Into<SurfaceSource>) -> Surface

Composites pixels GPUI did not draw into the scene, as an ordinary element.

A surface is how an application shows content produced outside GPUI — a video decoder’s frame, a texture another graphics API rendered, or a resource that lives on another device — without copying those pixels through the CPU. The producer fills a GPU resource and hands it here as a source; the window’s renderer samples that resource directly while it composites the frame.

The element lays out and stacks like any other child: it occupies space in the layout tree, and it is painted in the frame’s own pass in child order, so ordinary elements drawn beside or over it compose with it rather than floating above it.

source is anything that converts into a SurfaceSource. On Windows that is a Direct3D texture or shader-resource view, on macOS a CoreVideo image buffer, and on Linux a dma-buf handle; SurfaceSource documents each platform’s payloads and, where a platform offers more than one, which to reach for. The Windows pair is the one that comes up most: handing over a texture is the ergonomic default, since the renderer makes the view on the device it owns, while handing over a view is the escape for a producer that is the authority on its own format and mip interpretation.

A source is produced by someone else, before this element paints. A same-device resource is made inside a gpu_canvas callback, where the window renderer’s device is reachable through GpuCanvasContext::device; a source this element takes was made off the window’s device and shared with it — a dma-buf, a CoreVideo buffer, a shared Direct3D view — the route a cross-process bridge takes.

use gpui::{div, surface};

// `source` is a `SurfaceSource` for this platform; see the type's docs.
div().size_full().child(surface(source))

For a working producer, run cargo run -p gpui --example surface: it shows this element and the gpu_canvas() callback side by side, one payload at a time, on the host renderer.