Documentation menu

Building and Presenting a Frame

Trace a scene update through validation, composition, GPU submission, and identified display activation.

The server builds a frame by sampling retained state for a planned presentation time. That sample can combine updates from several applications with server-driven animation or a composition change, such as moving an embedded surface. As a result, an individual client commit contributes to the frame lifecycle without necessarily producing its own separately displayed image.

  1. Accept

    Validate and publish retained state.

    CommitAccepted
  2. Prepare

    Sample animation and snapshot the scene.

    SceneSnapshot
  3. Submit

    Plan, record, and queue GPU work.

    CommitAck
  4. Present

    Observe the identified display activation.

    FramePresented
Retained acceptance, GPU submission, and display activation are separate milestones. Several commits can contribute to one frame.

1. Client Update Publication

The lifecycle begins when a client evaluates its UI and sends the resulting scene changes in a Commit. After verifying surface ownership, the server waits for composer admission capacity and validates the complete operation list. Only a valid, complete update is published to retained state.

The server reports publication with CommitAccepted, allowing the client to use that scene as its next reconciliation baseline. This response closes the retained-state part of the update; the accepted scene still has to pass through frame preparation and GPU submission before it can reach the display.

2. Presentation Scheduling

The scheduler uses the display clock and measured frame work to select a target presentation instant and the render start time needed to reach it. The server can announce that plan through FrameScheduled, giving clients an estimate of the upcoming presentation time and render deadline.

Hints are advisory and may be coalesced or skipped under output pressure. A client must keep making progress without receiving one hint for every submitted or presented frame.

3. Snapshot Preparation

When the render deadline arrives, the composer samples animation for the predicted presentation time and captures the resulting scene. It pairs the snapshot with submission bookkeeping that identifies the commits a successful render can acknowledge. Client changes arriving afterward affect a future preparation rather than altering the snapshot already in flight.

This separation allows clients to continue updating retained state while the renderer works on a consistent frame. It also makes a failed render retryable without claiming that its commits reached the GPU.

4. GPU Recording and Submission

The render worker acquires an available target, evaluates draw items, computes target-specific damage, admits the render graph, prepares resources, records commands, and submits GPU work.

When all target images are still in use, the renderer returns WouldBlock and the frame driver schedules a fresh attempt. Since no successful submission occurred, the pending commit records remain available for a later frame to claim and acknowledge.

After successful submission, the server claims the prepared submission and sends CommitAck for the covered commits. This acknowledgment describes GPU submission, not GPU completion or physical display visibility.

5. Display Handoff

The presentation path then queues the framebuffer through DRM/KMS, carrying its GPU dependency to the display with a fence where that handoff is supported. If the path cannot hand off the dependency directly, a fallback can wait for GPU completion on the CPU before queuing the image.

The active scanout image remains display-owned until a successor is activated. Finishing GPU work does not make an active image reusable.

6. Display Activation Confirmation

The worker resolves DRM events to an identified frame activation, then uses the retained snapshot to establish which scene became visible. That confirmation updates presentation history, produces FramePresented, and allows storage no longer used by the display to become eligible for retirement.

The server uses the activation timestamp to refine subsequent frame schedules. It also supplies the confirmed snapshot to input handling, so hit testing follows the geometry the user can see even when a newer scene has already been submitted.

Frame Stall Diagnosis

Use the last completed milestone to narrow a stalled frame investigation. If retained acceptance never arrived, inspect admission and connection handling. Once acceptance is confirmed, missing submission points toward frame preparation or renderer progress; after submission, missing identified activation points toward GPU dependencies, KMS, or presentation observation.

Use troubleshooting for a practical sequence and commit outcomes for client bookkeeping.

Source Reference

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

  • crates/server/src/client/commits.rs
  • crates/server/src/frame/driver.rs
  • crates/server/src/frame/mod.rs
  • crates/renderer/src/swapchain/core.rs
  • crates/renderer/src/present/history.rs