Documentation menu

Scene Graph and Surfaces

Represent an interface as retained nodes, and compose independently owned surfaces into the server scene.

A surface gives a client an independently owned place in the retained composition. Within that surface, nodes describe visual content and its parent-child relationships using stable identifiers and properties. A client changes this durable description through scene updates, which the server can use when composing later frames.

Visual Content

The five node kinds describe the content that can appear in a scene. Rectangular paint belongs to a View, while an Image refers to pixels imported separately as a buffer. Text is represented by a TextRun containing positioned glyphs and a font key, and a Path carries vector geometry with optional fill and stroke. A SurfaceView extends the composition by placing another surface within the hierarchy.

All of these kinds share properties for geometry, visibility, clipping, effects, and hit behavior. Clients resolve layout into those properties before submission, so the server receives explicit sizes and positions rather than Hera Kit stack rules or Yoga layout instructions.

Scene Updates

Clients send a Commit containing an ordered list of DiffOps. Operations establish a root, add or remove nodes, update properties or content, reorder children, and detach or attach subtrees. Validation runs before the new state is published, so a rejected commit does not expose a partially modified scene.

Stable identifiers allow a client to change a node's appearance or placement while preserving its descendants. The protocol also distinguishes detaching a node from removing its subtree, which lets a mounting framework move retained content without treating the move as deletion.

Surface Composition

A SurfaceView lets a parent scene place another surface without transferring ownership of that surface's client state. The shell can use this mechanism to arrange application windows. Surface placement and size changes participate in the server's composition policy and can produce SurfaceChanged notifications for the embedded application's owner.

Embedding must preserve independent inherited transforms, clips, and opacity when traversing siblings and surfaces. A renderer traversal must not let state from one branch leak into another.

Retained Scene Snapshots

When preparing a frame, the composer captures retained state in a SceneSnapshot. This snapshot gives rendering a consistent scene even if clients submit more changes while the frame is in flight. By retaining submitted snapshots until identified display activation, the renderer can later report which scene actually became visible.

See scene operations for the contract and reconciliation for how Hera Kit creates those operations.

Source Reference

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

  • crates/graph/src/lib.rs
  • crates/protocol/src/scene/nodes.rs
  • crates/protocol/src/scene/diff.rs
  • crates/renderer/src/present/history.rs