Documentation menu

Frame Export and Damage

Publish ready page buffers through DMA-BUF or sealed CPU storage while preserving image continuity and native ownership.

The native exporter bridges two different image lifecycles: WPE owns produced page buffers, while Hera retains imported images beyond a single application update. Export must therefore establish producer readiness and immutable backing before transferring a descriptor, then keep the WPE buffer alive until the host reports server retirement.

Producer Readiness

The custom view normally receives implicitly synchronized buffers, but the exporter also checks an explicit rendering fence when one is supplied. For a DMA-BUF without a separate fence, it can inspect readiness through the backing descriptor. If readiness is pending, it duplicates the descriptor and registers a GLib FD source instead of blocking the UI thread.

The waiting state retains the WPE buffer and bounded damage information until the source becomes ready or fails. A separate ten-second timeout records a terminal export error if readiness never arrives. Cleanup closes the retained descriptor and drops the waiting buffer reference, including during teardown.

Compatible DMA-BUF Exports

The preferred path accepts a one-plane DMA-BUF with zero plane offset and a packed RGBA/BGRA format supported by the protocol. It duplicates the plane FD with close-on-exec behavior and preserves the buffer's stride and modifier in the exported descriptor.

Retaining the original WPE buffer prevents the producer from recycling the backing while Hera may still sample it. Duplicating the FD alone is not a substitute for that producer-side lifetime, which is why callback completion and release remain separate native operations.

Immutable CPU Snapshots

When DMA-BUF sharing is unavailable or CPU mode is forced, the exporter creates a complete memory-backed snapshot. A shared-memory WPE buffer can be copied directly after checking its layout; other supported buffers are imported into an EGL image and read through GLES into packed RGBA pixels.

The copy is written into a memfd, after which the exporter seals writes, growth, shrinkage, and further seal changes. Rust receives that immutable backing under the same frame lifecycle as a DMA-BUF. If the buffer cannot be copied or exported, the bridge reports a failure instead of publishing an incomplete frame.

Export Limits

Export checks nonzero dimensions, the 8192-pixel axis limit, the 64 MiB image limit, frame-ID exhaustion, and the native held-image budget. Rust then validates the resulting descriptor and actual backing again before exposing a public Frame. Each check protects a different point in the handoff; native format selection does not eliminate the need to validate the transferred FD.

After publication, hw_take_frame transfers that FD once and records the delivered frame as the predecessor for possible future damage. The held-image map retains the WPE buffer and damage metadata independently until the host invokes the matching release operation.

Predecessor-Relative Damage

Narrow damage is usable only when the exporter has a continuous predecessor with compatible dimensions and format, and WPE supplies a nonempty valid list of at most 64 rectangles. Navigation, resize, missing continuity, or ambiguous regions discard that relationship and produce full or unknown damage.

The native metadata identifies the preceding native frame. The Rust host maps it to the successfully imported Hera buffer ID and uses that ID in FrameDamage; if the mapping does not match, it omits damage. The imported backing remains a complete image regardless of how small its damage list is.

Each server target still tracks its own image history, which may be older than the previous page frame. Producer damage supports that calculation but does not replace scene-level effect dependencies or display-target history. Use HERA_WEBKIT_FULL_DAMAGE=1 to compare full production and image repaint without changing the transport path.

Source Reference

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

  • crates/webkit/native/frames.cpp
  • crates/webkit/native/hera_wpe.cpp
  • crates/webkit/src/frame.rs
  • crates/webkit/src/ffi.rs
  • apps/browser/src/host.rs
  • crates/protocol/src/buffers.rs