Bug 1422966 - Comment Wayland rendering scheme, r=jhorak
authorMartin Stransky <stransky@redhat.com>
Tue, 05 Dec 2017 10:12:37 +0100
changeset 448295 3cf5876e6d1c63b17cc656e04468627671de7fe7
parent 448294 fe85732c14da164231e9ae3889b0f5a5ba5dc3ff
child 448296 8870736e152c95d897e691581f1d239f06729d82
push id8527
push userCallek@gmail.com
push dateThu, 11 Jan 2018 21:05:50 +0000
treeherdermozilla-beta@95342d212a7a [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjhorak
bugs1422966
milestone59.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1422966 - Comment Wayland rendering scheme, r=jhorak MozReview-Commit-ID: 7ZV97xcRskV
widget/gtk/WindowSurfaceWayland.cpp
--- a/widget/gtk/WindowSurfaceWayland.cpp
+++ b/widget/gtk/WindowSurfaceWayland.cpp
@@ -17,16 +17,125 @@
 #include "mozilla/StaticMutex.h"
 
 #include <gdk/gdkwayland.h>
 #include <sys/mman.h>
 #include <assert.h>
 #include <fcntl.h>
 #include <errno.h>
 
+/*
+  Wayland multi-thread rendering scheme
+
+  Every rendering thread (main thread, compositor thread) contains its own
+  nsWaylandDisplay object connected to Wayland compositor (Mutter, Weston, etc.)
+
+  WindowSurfaceWayland implements WindowSurface class and draws nsWindow by
+  WindowSurface interface (Lock, Commit) to screen through nsWaylandDisplay.
+
+  ----------------------
+  | Wayland compositor |
+  ----------------------
+             ^
+             |
+  ----------------------
+  |  nsWaylandDisplay  |
+  ----------------------
+        ^          ^
+        |          |
+        |          |
+        |       ---------------------------------        ------------------
+        |       | WindowSurfaceWayland          |<------>| nsWindow       |
+        |       |                               |        ------------------
+        |       |  -----------------------      |
+        |       |  | WindowBackBuffer    |      |
+        |       |  |                     |      |
+        |       |  | ------------------- |      |
+        |       |  | |  WaylandShmPool | |      |
+        |       |  | ------------------- |      |
+        |       |  -----------------------      |
+        |       |                               |
+        |       |  -----------------------      |
+        |       |  | WindowBackBuffer    |      |
+        |       |  |                     |      |
+        |       |  | ------------------- |      |
+        |       |  | |  WaylandShmPool | |      |
+        |       |  | ------------------- |      |
+        |       |  -----------------------      |
+        |       ---------------------------------
+        |
+        |
+  ---------------------------------        ------------------
+  | WindowSurfaceWayland          |<------>| nsWindow       |
+  |                               |        ------------------
+  |  -----------------------      |
+  |  | WindowBackBuffer    |      |
+  |  |                     |      |
+  |  | ------------------- |      |
+  |  | |  WaylandShmPool | |      |
+  |  | ------------------- |      |
+  |  -----------------------      |
+  |                               |
+  |  -----------------------      |
+  |  | WindowBackBuffer    |      |
+  |  |                     |      |
+  |  | ------------------- |      |
+  |  | |  WaylandShmPool | |      |
+  |  | ------------------- |      |
+  |  -----------------------      |
+  ---------------------------------
+
+nsWaylandDisplay
+
+Is our connection to Wayland display server,
+holds our display connection (wl_display) and event queue (wl_event_queue).
+
+nsWaylandDisplay is created for every thread which sends data to Wayland
+compositor. Wayland events for main thread is served by default Gtk+ loop,
+for other threads (compositor) we must create wl_event_queue and run event loop.
+
+
+WindowSurfaceWayland
+
+Is a Wayland implementation of WindowSurface class for WindowSurfaceProvider,
+we implement Lock() and Commit() interfaces from WindowSurface
+for actual drawing.
+
+One WindowSurfaceWayland draws one nsWindow so those are tied 1:1.
+At Wayland level it holds one wl_surface object.
+
+To perform visualiation of nsWindow, WindowSurfaceWayland contains one
+wl_surface and two wl_buffer objects (owned by WindowBackBuffer)
+as we use double buffering. When nsWindow drawing is finished to wl_buffer,
+the wl_buffer is attached to wl_surface and it's sent to Wayland compositor.
+
+
+WindowBackBuffer
+
+Manages one wl_buffer. It owns wl_buffer object, owns WaylandShmPool
+(which provides shared memory) and ties them together.
+
+Wl_buffer is a main Wayland object with actual graphics data.
+Wl_buffer basically represent one complete window screen.
+When double buffering is involved every window (GdkWindow for instance)
+utilises two wl_buffers which are cycled. One is filed with data by application
+and one is rendered by compositor.
+
+
+WaylandShmPool
+
+WaylandShmPool acts as a manager of shared memory for WindowBackBuffer.
+Allocates it, holds reference to it and releases it.
+
+We allocate shared memory (shm) by mmap(..., MAP_SHARED,...) as an interface
+between us and wayland compositor. We draw our graphics data to the shm and
+handle to wayland compositor by WindowBackBuffer/WindowSurfaceWayland
+(wl_buffer/wl_surface).
+*/
+
 namespace mozilla {
 namespace widget {
 
 // TODO: How many rendering threads do we actualy handle?
 static nsCOMArray<nsWaylandDisplay> gWaylandDisplays;
 static StaticMutex gWaylandDisplaysMutex;
 
 // Each thread which is using wayland connection (wl_display) has to operate