Documentation menu

The WPE Platform Adapter

Adapt WPE’s display and view contracts to offscreen page production without introducing a second display owner.

The platform adapter supplies WPE with the objects it needs to create and render a page while leaving visible composition to Hera. Its custom HeraDisplay, HeraView, and HeraToplevel objects describe an embedding target backed by headless render infrastructure rather than a separate desktop window.

Headless Rendering Infrastructure

During initialization, the bridge creates a headless WPE display as backing for the custom display. The custom object delegates EGL display access, DRM device information, keymap access, and its clipboard getter to that backing. These delegated facilities support page production; they do not establish application-level clipboard UI or give the page scanout ownership.

The bridge selects an EGL configuration with an OpenGL ES 2 context, then creates WebKitWebView against the custom display. Its owning native state retains these resources until view teardown, ensuring that exported images can be released before EGL support disappears.

Custom View Buffer Delivery

HeraView implements the platform's render_buffer callback, which receives a produced WPE buffer together with its damage rectangles. The callback retrieves the associated native owner and passes the buffer to the exporter. If that owner is unavailable, it reports a rendering error rather than publishing a buffer without a lifetime controller.

This callback is the boundary between engine production and Hera transport. It does not submit a scene directly. Export first establishes a ready, immutable image and metadata; Rust and the host then decide when it can be imported and referenced by the retained scene.

Format Negotiation

The custom display derives preferred formats from the headless device and filters them to packed alpha formats accepted by Hera's single-plane importer. It preserves the supported modifiers for those formats, allowing the exporter to share backing when the produced buffer meets the remaining layout requirements.

Negotiation reduces avoidable readback but does not replace export validation. A multi-plane buffer, nonzero plane offset, or unsupported format still needs a supported fallback or an explicit error. The export guide follows that decision.

Viewport and View State

The adapter creates a custom toplevel for its WPE view, reports the initial dimensions, and marks that toplevel active before mapping the page. Later resize calls notify both the toplevel and view, while the host remains responsible for deriving the page viewport from Hera's authoritative surface geometry.

There is no independent KMS mode or display event loop in this adapter. Offscreen WPE production responds to its platform callbacks and completion feedback, while Hera decides how the exported page is placed and when the final composition reaches the display.

Damage and Lifecycle Callbacks

View initialization looks up the engine features used for damaging information, enables propagation, and selects partial composition unless full damage was requested. If the required features are missing, initialization fails rather than running with an assumed damage contract.

The bridge also connects load state, load failure, and web-process termination signals. Load state feeds the application's status display, while process termination records a frame-production error. These signals progress when the owning host pumps the GLib context through iterate().

Source Reference

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

  • crates/webkit/native/platform.cpp
  • crates/webkit/native/hera_wpe.cpp
  • crates/webkit/native/browser.h
  • apps/browser/src/host.rs