From 3d7f7e2f4aadda84e7a1289f2f19a8be9344e436 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 29 Mar 2012 10:50:10 +1000 Subject: [PATCH] doc: move documentation from the tex file to docbook And remove the .tex file Minor changes: - where the .tex file had some interface descriptions, the docbook source now links to the actual protocol. The exception here is the shared object cache which is simply a until the protocol spec exists. - "Implementation" section skipped, this seems in need of an update anyway and may be better documented elsewhere (wiki?) Signed-off-by: Peter Hutterer --- doc/Wayland/Makefile.am | 3 + doc/Wayland/en_US/Compositors.xml | 138 ++++++ doc/Wayland/en_US/Overview.xml | 119 +++++ doc/Wayland/en_US/Wayland.xml | 3 + doc/Wayland/en_US/WaylandProtocol.xml | 684 ++++++++++++++++++++++++++ spec/main.tex | 661 ------------------------- 6 files changed, 947 insertions(+), 661 deletions(-) create mode 100644 doc/Wayland/en_US/Compositors.xml create mode 100644 doc/Wayland/en_US/Overview.xml create mode 100644 doc/Wayland/en_US/WaylandProtocol.xml delete mode 100644 spec/main.tex diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am index bc50e9e..424314d 100644 --- a/doc/Wayland/Makefile.am +++ b/doc/Wayland/Makefile.am @@ -10,6 +10,9 @@ publican_sources = \ $(srcdir)/en_US/Chapter.xml \ $(srcdir)/en_US/Preface.xml \ $(srcdir)/en_US/Wayland.xml \ + $(srcdir)/en_US/WaylandProtocol.xml \ + $(srcdir)/en_US/Compositors.xml \ + $(srcdir)/en_US/Overview.xml \ $(srcdir)/en_US/Revision_History.xml \ $(srcdir)/en_US/images/icon.svg \ $(srcdir)/en_US/images/wayland-architecture.png \ diff --git a/doc/Wayland/en_US/Compositors.xml b/doc/Wayland/en_US/Compositors.xml new file mode 100644 index 0000000..d5311fa --- /dev/null +++ b/doc/Wayland/en_US/Compositors.xml @@ -0,0 +1,138 @@ + + +%BOOK_ENTITIES; +]> + + Types of Compositors +
+ System Compositor + + + + + ties in with graphical boot + + + + + hosts different types of session compositors + + + + + lets us switch between multiple sessions (fast user switching, + secure/personal desktop switching) + + + + + multiseat + + + + + linux implementation using libudev, egl, kms, evdev, cairo + + + + + for fullscreen clients, the system compositor can reprogram the + video scanout address to source from the client provided buffer. + + + + +
+
+ Session Compositor + + + + + nested under the system compositor. nesting is feasible because + protocol is async, roundtrip would break nesting + + + + + gnome-shell + + + + + moblin + + + + + compiz? + + + + + kde compositor? + + + + + text mode using vte + + + + + rdp session + + + + + fullscreen X session under wayland + + + + + can run without system compositor, on the hw where it makes + sense + + + + + root window less X server, bridging X windows into a wayland + session compositor + + + + +
+
+ Embedding Compositor + + X11 lets clients embed windows from other clients, or lets client copy + pixmap contents rendered by another client into their window. This is + often used for applets in a panel, browser plugins and similar. + Wayland doesn't directly allow this, but clients can communicate GEM + buffer names out-of-band, for example, using d-bus or as command line + arguments when the panel launches the applet. Another option is to + use a nested wayland instance. For this, the wayland server will have + to be a library that the host application links to. The host + application will then pass the wayland server socket name to the + embedded application, and will need to implement the wayland + compositor interface. The host application composites the client + surfaces as part of it's window, that is, in the web page or in the + panel. The benefit of nesting the wayland server is that it provides + the requests the embedded client needs to inform the host about buffer + updates and a mechanism for forwarding input events from the host + application. + + + + + + firefox embedding flash by being a special purpose compositor to + the plugin + + + + +
+ diff --git a/doc/Wayland/en_US/Overview.xml b/doc/Wayland/en_US/Overview.xml new file mode 100644 index 0000000..689b43f --- /dev/null +++ b/doc/Wayland/en_US/Overview.xml @@ -0,0 +1,119 @@ + + +%BOOK_ENTITIES; +]> + + Wayland Overview + + + + + Wayland is a protocol for a new display server + + + + + Weston is the open source project implementing a wayland-based + copmositor + + + + +
+ Replacing X11 + +In Linux and other Unix-like systems, the X stack has grown to +encompass functionality arguably belonging in client libraries, +helper libraries, or the host operating system kernel. Support for +things like PCI resource management, display configuration management, +direct rendering, and memory management has been integrated into the X +stack, imposing limitations like limited support for standalone +applications, duplication in other projects (e.g. the Linux fb layer +or the DirectFB project), and high levels of complexity for systems +combining multiple elements (for example radeon memory map handling +between the fb driver and X driver, or VT switching). + + +Moreover, X has grown to incorporate modern features like offscreen +rendering and scene composition, but subject to the limitations of the +X architecture. For example, the X implementation of composition adds +additional context switches and makes things like input redirection +difficult. + + + + + + + + The diagram above illustrates the central role of the X server and + compositor in operations, and the steps required to get contents on to + the screen. + + +Over time, X developers came to understand the shortcomings of this +approach and worked to split things up. Over the past several years, +a lot of functionality has moved out of the X server and into +client-side libraries or kernel drivers. One of the first components +to move out was font rendering, with freetype and fontconfig providing +an alternative to the core X fonts. Direct rendering OpenGL as a +graphics driver in a client side library went through some iterations, +ending up as DRI2, which abstracted most of the direct rendering +buffer management from client code. Then cairo came along and provided +a modern 2D rendering library independent of X, and compositing +managers took over control of the rendering of the desktop as toolkits +like GTK+ and Qt moved away from using X APIs for rendering. Recently, +memory and display management have moved to the Linux kernel, further +reducing the scope of X and its driver stack. The end result is a +highly modular graphics stack. + + +
+ +
+ Make the compositing manager the display server + + Wayland is a new display server and compositing protocol, and Weston + is the implementation of this protocol which builds on top of all the + components above. We are trying to distill out the functionality in + the X server that is still used by the modern Linux desktop. This + turns out to be not a whole lot. Applications can allocate their own + off-screen buffers and render their window contents directly, using + hardware accelerated libraries like libGL, or high quality software + implementations like those found in Cairo. In the end, what’s needed + is a way to present the resulting window surface for display, and a + way to receive and arbitrate input among multiple clients. This is + what Wayland provides, by piecing together the components already in + the eco-system in a slightly different way. + + + X will always be relevant, in the same way Fortran compilers and VRML + browsers are, but it’s time that we think about moving it out of the + critical path and provide it as an optional component for legacy + applications. + + + Overall, the philosophy of Wayland is to provide clients with a way to + manage windows and how their contents is displayed. Rendering is left + to clients, and system wide memory management interfaces are used to + pass buffer handles between clients and the compositing manager. + + + + + + + + The figure above illustrates how Wayland clients interact with a + Wayland server. Note that window management and composition are + handled entirely in the server, significantly reducing complexity + while marginally improving performance through reduced context + switching. The resulting system is easier to build and extend than a + similar X system, because often changes need only be made in one + place. Or in the case of protocol extensions, two (rather than 3 or 4 + in the X case where window management and/or composition handling may + also need to be updated). + +
+ diff --git a/doc/Wayland/en_US/Wayland.xml b/doc/Wayland/en_US/Wayland.xml index 829d362..d591a22 100644 --- a/doc/Wayland/en_US/Wayland.xml +++ b/doc/Wayland/en_US/Wayland.xml @@ -9,7 +9,10 @@ --> + + +