Documentation menu

Presentation and Synchronization

Track GPU dependencies and display ownership separately so that images are never reused while they are still visible.

Presenting a frame requires more than finishing its GPU commands. The output also becomes a consumer of the rendered storage, and that storage must remain valid for as long as the display scans it out. Hera therefore tracks GPU dependencies and display ownership separately throughout the presentation lifecycle.

Swapchain Slot Lifecycle

A frame begins with a free swapchain slot. The swapchain consumes that slot's free token when rendering starts, using typed tokens to constrain the acquisition and rendering operations. Its internal slot state then follows the GPU and display work that must complete before the image becomes free again.

When presentation succeeds, the swapchain has queued an identified frame along with its GPU dependency. Completion of that dependency establishes that rendering finished, while an identified KMS activation establishes that the queued frame became active. The previous active image can leave scanout only after its successor activates.

An unrelated page flip, a cursor-only update, a ready descriptor, or a signaled GPU fence cannot stand in for that identified scene activation.

Presentation Storage Paths

The selected presentation path determines how rendered pixels reach scanout storage. In zero-copy mode, Vulkan imports scanout-compatible storage and renders into the same backing used by the display. In CPU-copy mode, the renderer uses separate GPU storage and copies the completed pixels into scanout storage after validating both layouts and their strides.

Sharing storage does not eliminate the need to synchronize its consumers. Even in zero-copy mode, the CPU may need to wait for GPU completion if KMS cannot accept an input fence through the selected handoff path.

During startup, the renderer reads HERA_PRESENT_MODE and selects the corresponding device requirements. A forced mode must meet those requirements or initialization fails, making an unsupported path explicit rather than silently choosing another one. The configuration guide lists the accepted values.

Readiness Signals and Display Events

The asynchronous frame driver waits for display readiness through PresentationSignal, leaving the render worker as the sole reader of DRM events. Because the signal only observes readiness, cancelling a wait does not consume the activation event or discard the scene that event will confirm.

Submitted scene history and undelivered notifications share bounded admission capacity. Notifications remain owned until the receiving future acknowledges them, so cancelling an API waiter cannot lose confirmed presentation.

Recovery and Resource Reuse

Recovery must respect the same consumers as the successful path. Abandoned rendering retains its slot until GPU completion is established, and a presentation timeout does not prove that queued or active storage has left the display. Teardown must therefore quiesce GPU work and disable output before releasing scanout resources.

See frame lifecycle for the surrounding sequence and buffer ownership for client-imported images.

Source Reference

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

  • crates/renderer/src/swapchain/README.md
  • crates/renderer/src/present/README.md
  • crates/renderer/src/display/README.md
  • crates/renderer/src/sync/README.md