WPE platform rewrite

about/architecture.md

@@ -39,30 +39,35 @@ such as the traditional Cocoa, GTK, etc toolkits.
 
 ## Web page rendering
 
-<p class="leadin">WPE is considered a hybrid port because it defers the final web page delivery for display to a rendering backend. A traditional port would provide a widget for a given toolkit, but WPE opted for a different and more flexible approach.</p>
-
-The common interface between WPEWebKit and its rendering backends is provided by
-[libwpe](https://github.com/WebPlatformForEmbedded/libwpe). On one side, once
-WPEWebKit has a graphical representation of the final composited Web page ready
-for rendering, it invokes a callback function on `libwpe`. On the other side,
-the WPE application has to register a view backend on the WPE WebView. This view
-backend is provided by the rendering backend. The view backend receives the Web
-page representation from `libwpe`, usually as an EGLImage, and is in charge of
-presenting it in the application, on-screen.
-
-The decoupling between generating the WebPage representation on WebKit side and
-the actual rendering on the application side provides a very flexible design.
-For instance, WPE integrators can easily develop a new rendering backend for
-specific embedded platforms that might have a graphics driver with special API
-requirements.
-
-WPE provides a rendering backend aiming to target the most common platforms and
-leverage the existing graphics stack available in the
-[Freedesktop](https://freedesktop.org) umbrella eco-system.
-[WPEBackend-FDO](https://github.com/Igalia/WPEBackend-FDO) is the reference
-implementation of the base rendering backend design. WPEBackend-FDO provides an API
-for WPE applications that aims to ease the handling of rendering either
-on-screen using EGL, or off-screen using SHM.
+<p class="leadin">WPE integrates with the target platform through the WPEPlatform
+API, which ships as part of WPE WebKit itself. Because WPE provides no user-interface
+toolkit widget, this layer is what turns the rendered web page into pixels on screen
+and feeds input back to the engine.</p>
+
+Since 2.54, WPEPlatform is the default integration layer, and the only one needed
+for the common targets. A `WPEDisplay` represents the connection to the underlying
+windowing system or output, and manages one or more `WPEView`s, each hosted in a
+`WPEToplevel` (a top-level surface such as a window or a full-screen output). The
+composited web page is handed over through `WPEBuffer`, using a system GPU buffer
+(e.g. `WPEBufferDMABuf`, `WPEBufferAndroid`), or shared memory (i.e. `WPEBufferSHM`)
+as a fallback.
+
+WPE WebKit includes several built-in platform implementations:
+
+- **Wayland** (`WPEDisplayWayland`): renders as a client of a Wayland compositor.
+- **DRM/KMS** (`WPEDisplayDRM`): renders directly through the display controller,
+  with no compositor, for dedicated embedded outputs.
+- **Headless** (`WPEDisplayHeadless`): renders off-screen, for testing and CI.
+
+The implementation can be selected at runtime through the `WPE_DISPLAY` environment
+variable (`wpe-display-wayland`, `wpe-display-drm`, `wpe-display-headless`), or
+chosen automatically with `wpe_display_get_default()`. None of these targets
+require libwpe or a separate rendering backend.
+
+This design keeps WPE flexible without giving up that convenience: for special
+environments not covered by the built-in implementations, an integrator can provide
+a custom WPEPlatform implementation by subclassing `WPEDisplay` (and the related
+view and toplevel types).
 
 </section>
 
@@ -72,16 +77,57 @@ on-screen using EGL, or off-screen using SHM.
 
 <p class="leadin">In a traditional WebKit port, the provided widget usually also handles input
 (keyboard, mouse, touch) events and is in charge of relaying them to the
-internal WebKit input-methods components.</p>
+internal WebKit input handling components.</p>
+
+As WPE doesn't provide a widget, input is handled by the active WPEPlatform
+implementation. Each implementation gathers events from its environment (for
+example, from the Wayland compositor, or directly from the input devices under
+DRM/KMS) and delivers them to the target `WPEView`, which relays them to WebKit's
+internal input handling components. This flexible design enables applications to
+ provide input events in any way that better suits them.
+
+</section>
+
+<section class="dotsep">
+
+## Legacy architecture (libwpe and WPE backends)
+
+<p class="leadin">Before 2.54, WPE integrated with the platform through libwpe and a
+separate, external rendering backend. This model is legacy as of 2.54: it is kept for
+existing deployments and still built as needed, but new projects should use the
+WPEPlatform API described above.</p>
+
+<details>
+<summary>How the legacy libwpe and WPE backend model works</summary>
+
+The common interface between WPE WebKit and its rendering backends was provided by
+[libwpe](https://github.com/WebPlatformForEmbedded/libwpe). On one side, once WPE
+WebKit had a graphical representation of the final composited web page ready for
+rendering, it invoked a callback function on `libwpe`. On the other side, the WPE
+application had to register a view backend on the WPE web view. This view backend
+was provided by the rendering backend, received the web page representation from
+`libwpe` (usually as an EGLImage), and was in charge of presenting it in the
+application, on-screen.
+
+This decoupling between generating the web page representation on the WebKit side
+and the actual rendering on the application side provided a flexible design. WPE
+integrators could develop a new rendering backend for specific embedded platforms
+whose graphics driver had special API requirements.
+
+WPE provided a rendering backend aiming to target the most common platforms and
+leverage the existing graphics stack available in the
+[Freedesktop](https://freedesktop.org) umbrella ecosystem.
+[WPEBackend-FDO](https://github.com/Igalia/WPEBackend-FDO) is the reference
+implementation of that base rendering backend design. WPEBackend-FDO provides an
+API for WPE applications that eases the handling of rendering either on-screen
+using EGL, or off-screen using SHM.
 
-As WPE doesn't provide a widget, it relies on `libwpe` APIs to relay input
-events from the WPE application to the internal WebKit input-methods components.
-This design again adds flexibility to the overall WPE architecture, enabling
-applications to support new input devices without having to go through a UI
-toolkit first.
+For input, because WPE provides no widget, this model relied on `libwpe` APIs to
+relay input events from the WPE application to the internal WebKit input-method
+components. In the example of the [Cog launcher](https://github.com/Igalia/cog),
+the application relied on Wayland protocols to communicate input events coming from
+the Wayland compositor to WPE.
 
-In the example of the [Cog WPE browser](https://github.com/Igalia/cog), the
-application relies on Wayland protocols for user input to communicate events
-coming from the Wayland compositor to WPE.
+</details>
 
 </section>

about/builds.md

@@ -8,6 +8,6 @@ sitemapChangeFrequency: yearly
 skipHtmlSitemap: true
 ---
 
-While there are several [simple ways for developers to experiment with and explore WPE](/about/exploring.html), none are tuned for performance. Generally, shipping products for embedded systems are performance-tuned custom builds.  To make this easier, there is also [meta-webkit](https://github.com/Igalia/meta-webkit), which provides build recipes, WebKit based runtimes, and browsers for use with OpenEmbedded and/or Yocto.
+While there are several [simple ways for developers to experiment with and explore WPE](/about/get-wpe.html), none are tuned for performance. Generally, shipping products for embedded systems are performance-tuned custom builds.  To make this easier, there is also [meta-webkit](https://github.com/Igalia/meta-webkit), which provides build recipes, WebKit based runtimes, and browsers for use with OpenEmbedded and/or Yocto.
 
 We also have some [performance tips](https://github.com/Igalia/meta-webkit/wiki/PerformanceTips) that might be helpful.