WPEPlatform is a GObject library that abstracts the platform layer for WPE WebKit. It is the successor to libwpe and the various out-of-tree backends written against it (notably WPEBackend-fdo), and it lives upstream in the WebKit tree under Source/WebKit/WPEPlatform/.

A platform implementation provides a connection to a native windowing system (Wayland, DRM/KMS, X11, a custom compositor, etc.) and the machinery WPE WebKit needs to render web content into a surface and deliver input events back to it. WPEPlatform defines that contract as a small set of GObject-based abstract classes that implementations subclass.

WPEPlatform ships with three built-in platform implementations — Wayland, DRM, and headless. All of them are compiled into the same shared library as the rest of WPE WebKit, but each one has its own headers and its own pkg-config module. They are built by default but each one is individually optional at build time. Integrators are expected to choose between using a built-in implementation or writing a new implementation from scratch. The built-in implementations can be extended by using their public API, which exposes the internal platform specific objects. For example the Wayland implementation exposes its underlying wl_display, wl_compositor, and wl_surface objects, which makes it possible to add support for a Wayland protocol that the built-in module does not implement. External implementations for other windowing systems already exist (notably for GTK4).

WPEPlatform is used only from WPE WebKit’s UI process. The web process never touches the native display directly — it renders into offscreen buffers shared with the UI process through a platform-specific buffer-sharing mechanism (such as DMA-BUF or AHardwareBuffer). WebKit’s IPC layer is used to notify the UI process when a buffer is created, destroyed, or updated; the UI process then hands the buffer to the platform via wpe_view_render_buffer().

Audience

WPEPlatform has three distinct kinds of consumer. The same API serves all three, but the surface each one uses is different — and recognizing this up front makes the rest of the documentation easier to navigate.

Browser-application developers. Most browser applications never need to call into WPEPlatform directly. Creating a WebKitWebView without specifying a backend will pick a platform automatically and the application can then work entirely against the existing WebKitWebView API. WPEPlatform becomes visible when the application wants to do things that the WebKit-level API does not expose — for example, attach custom keyboard shortcuts to a WPEView, change cursor appearance, or pin the application to a specific built-in platform implementation.

Platform implementers. Integrators bringing up WPE WebKit on new hardware or new window systems subclass WPEDisplay, WPEView, and WPEToplevel (and optionally WPEKeymap, WPEInputMethodContext, WPEScreen, and so on) to provide the glue between WPE WebKit and the native platform. The implementation can live in the embedder’s source tree, or be installed as a module that WPEPlatform discovers and loads at runtime via a GIO extension point.

WebKit itself. WPE WebKit’s UI process consumes the API to drive the platform: it asks the display for a view, hands the view the buffers it produces, listens for input events, and watches the toplevel’s state. As a documentation reader you usually do not need to know which APIs are used by WebKit internally, but the headers sometimes contain both a request-style function (e.g. wpe_view_lock_pointer()) and a notification-style function meant for platform implementations to call back into WebKit (e.g. wpe_view_event()).

Class hierarchy

The core of the API revolves around four base classes. WPEDisplay, WPEView, and WPEBuffer are abstract - WPEToplevel can be instantiated but is normally subclassed by platform implementations:

Class	Role
WPEDisplay	The connection to a platform — singleton-like, the root of every other object.
WPEToplevel	A native top-level window (or its conceptual equivalent on platforms that don’t have windows).
WPEView	A rendering surface for a single web view, normally hosted inside a toplevel.
WPEBuffer	A piece of pixel data produced by WebKit and handed to the view to be rendered.

Around them are helper and support classes — WPEScreen, WPESettings, WPEKeymap, WPEEvent, WPEClipboard, WPEInputMethodContext, WPEGestureController, WPEGamepadManager / WPEGamepad, WPEViewAccessible (an interface) — and concrete WPEBuffer subclasses (WPEBufferDMABuf, WPEBufferSHM, WPEBufferAndroid).

How a browser application uses WPEPlatform

The minimum viable usage looks like this:

1. Create a WebKitWebView without specifying a display or a backend. WebKit then uses the default display automatically — it is obtained by iterating the registered platform modules in priority order and connecting to the first one that succeeds.
2. Run the GLib main loop.

WebKit creates the WPEDisplay, WPEToplevel, and WPEView on the application’s behalf in this default flow, so a browser application does not need to touch the WPEPlatform API at all to get a window on screen. An application only needs a WPEDisplay of its own when it wants to use a non-default one — for example, to pin to a specific built-in implementation by instantiating it directly with wpe_display_wayland_new() — in which case it passes the connected display to the web view on construction.

The browser tutorial walks through both paths.

How a platform implementation uses WPEPlatform

A platform implementation subclasses WPEDisplay and overrides its virtual methods — at minimum WPEPlatform.DisplayClass.connect and WPEPlatform.DisplayClass.create_view — and similarly subclasses WPEView and WPEToplevel for the platform-specific behavior. It optionally subclasses WPEKeymap, WPEScreen, WPEInputMethodContext, and others depending on the features the platform supports.

The implementation can be:

• Built as a module and installed under ${LIB_INSTALL_DIR}/wpe-platform-${WPE_API_VERSION}/modules/, in which case wpe_display_get_default() will pick it up automatically via the wpe-platform-display GIO extension point.
• Linked directly by the embedder, in which case the embedder instantiates the display class explicitly.

The Writing a WPE platform implementation tutorial walks through implementing a backend.

Relationship to libwpe

libwpe and its out-of-tree backends remain available but are deprecated. WPE WebKit can still be built against them while applications and platform integrators migrate, but new code should target WPEPlatform.

• The Migration mapping table lists every libwpe and WPEBackend-fdo public symbol and points at the WPEPlatform equivalent (or marks it as gone).
• Migrating from libwpe is a hands-on guide with before/after code for the common patterns.

What is not covered by WPEPlatform

A few things that lived in libwpe / WPEBackend-fdo do not have direct WPEPlatform equivalents:

• Process management (libwpe’s wpe_process_provider_* API, added in 1.14). Child-process launch is once again handled internally by WPE WebKit. The exception is Android builds, where WPEPlatform ships a WPEProcessManager for this purpose.
• The renderer-host/renderer-backend-egl plumbing. The new rendering model is built on buffer sharing through WPEBuffer subclasses; there is no separate EGL renderer-target abstraction to wire up.
• WPEBackend-fdo’s “exportable” view backend. The “WebKit hands you rendered buffers via callbacks” pattern is replaced by subclassing WPEView and implementing WPEPlatform.ViewClass.render_buffer.
• WPEBackend-fdo’s audio and video-plane extensions. See the Migration mapping table for their status.