Documentation menu

surface_view

Place another Hera surface inside a retained composition without taking over its client state.

A shell can arrange independently produced application content with surface_view(surface_id) -> SurfaceView. The view embeds another Hera surface into the parent's retained composition while leaving the embedded application's scene and state with their original owner.

Embedded Surface Placement

use hera_kit::{SurfaceId, View, ViewExt, surface_view};

fn application_window(surface: SurfaceId) -> impl View {
    surface_view(surface)
        .frame(800.0, 480.0)
        .clipped()
}

The supplied ID must refer to a surface admitted by server policy. Constructing a view does not create that surface or grant authority over its owner.

Layout and Ownership

The parent places the embedding within its own scene using the finite space proposed by layout. That placement gives the application a visible region without granting the parent ownership of the application's internal retained state.

When composition changes the embedded region's authoritative dimensions, the server can notify its owning client. The application's toolkit then lays out its content under the new size. A host should let this geometry workflow run rather than trying to infer and rearrange the embedded application's internal nodes itself.

Input Routing

Targeting follows the same embedding relationship. The server uses confirmed scene history and the surface placement transform to resolve which surface and node were visible at an input position before delivering the event to the owning client.

Clipping or transforming the embedding changes visible geometry and targeting. Custom shell composition must preserve the server's surface and target provenance when forwarding input.

Images and Surfaces

Choose image_buffer when the content is imported pixels, and surface_view when it is another retained scene with its own input lifecycle. Hera composes both, but the surface embedding preserves an independently owned UI rather than only referencing image storage.

See scene graph and surfaces and messages and surfaces.

Component-Specific Reference

fn surface_view(surface: SurfaceId) -> SurfaceView

The admitted surface ID is a construction input, and SurfaceView exposes no additional component-specific builder methods. Use common modifiers to frame, offset, clip, or change the opacity of the embedding. Reconstructing the embedding with another ID changes the referenced surface; it does not transfer ownership of that surface’s scene to the parent.

See View Modifiers for the complete common modifier reference.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/view/primitives.rs
  • crates/protocol/src/scene/nodes.rs
  • crates/server/src/client/surfaces.rs