spec: update high level description, add diagrams

Add diagrams from the Wayland architecture page and add some more high
level text describing X limitations and Wayland architecture.

spec/main.tex

@@ -1,11 +1,12 @@
 \documentclass{article}
 \usepackage{palatino}
+\usepackage{graphicx}
 
 \author{Kristian Høgsberg\\
 \texttt{krh@bitplanet.net}
 }
 
-\title{The Wayland Display Server}
+\title{The Wayland Compositing System}
 
 \begin{document}
 
@@ -15,39 +16,96 @@
 
 \begin{itemize}
 \item wayland is a protocol for a new display server.
-\item wayland is an implementation
+\item weston is the open source project implementing a wayland based compositor
 \end{itemize}
 
 \subsection{Replacing X11}
 
-Over time, a lot of functionality have slowly moved out of the X
+In Linux and other Unix-like systems, the X stack has grown to
-server and into client-side libraries or kernel drivers. One of the
+encompass funcationality arguably belonging in client libraries,
-first components to move out was font rendering, with freetype and
+helper libraries, or the host operating system kernel.  Support for
-fontconfig providing an alternative to the core X fonts.  Direct
+things like PCI resource management, display configuration management,
-rendering OpenGL as a graphics driver in a client side library. Then
+direct rendering, and memory management has been integrated into the X
-cairo came along and provided a modern 2D rendering library
+stack, imposing limitations like limited support for standalone
-independent of X and compositing managers took over control of the
+applications, duplication in other projects (e.g. the Linux fb layer
-rendering of the desktop. Recently with GEM and KMS in the Linux
+or the DirectFB project), and high levels of complexity for systems
-kernel, we can do modesetting outside X and schedule several direct
+combining multiple elements (for example radeon memory map handling
-rendering clients. The end result is a highly modular graphics stack.
+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.
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=70mm]{x-architecture.png}
+\caption{\small \sl X with a compositing manager.\label{fig:X architecture}}
+\end{center}
+\end{figure}
+
+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.
 
 \subsection{Make the compositing manager the display server}
 
-Wayland is a new display server building on top of all those
+Wayland is a new display server and compositing protocol, and Weston
-components. We are trying to distill out the functionality in the X
+is the implementation of this protocol which builds on top of all the
-server that is still used by the modern Linux desktop. This turns out
+components above. We are trying to distill out the functionality in
-to be not a whole lot. Applications can allocate their own off-screen
+the X server that is still used by the modern Linux desktop. This
-buffers and render their window contents by themselves. In the end,
+turns out to be not a whole lot. Applications can allocate their own
-what’s needed is a way to present the resulting window surface to a
+off-screen buffers and render their window contents directly, using
-compositor and a way to receive input. This is what Wayland provides,
+hardware accelerated libraries like libGL, or high quality software
-by piecing together the components already in the eco-system in a
+implementations like those found in Cairo. In the end, what’s needed
-slightly different way.
+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.
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=50mm]{wayland-architecture.png}
+\caption{\small \sl The Wayland system\label{fig:Wayland architecture}}
+\end{center}
+\end{figure}
+
+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).
 
 \section{Wayland protocol}
 
@@ -62,16 +120,16 @@ identifies which method in the interface to invoke.
 The server sends back events to the client, each event is emitted from
 an object.  Events can be error conditions.  The event includes the
 object id and the event opcode, from which the client can determine
-the type of event.  Events are generated both in response to a request
+the type of event.  Events are generated both in response to requests
 (in which case the request and the event constitutes a round trip) or
 spontaneously when the server state changes.
 
 \begin{itemize}
-\item state is broadcast on connect, events sent out when state
+\item state is broadcast on connect, events are sent out when state
-  change.  client must listen for these changes and cache the state.
+  changes.  clients must listen for these changes and cache the state.
-  no need (or mechanism) to query server state.
+  there is no need (or mechanism) to query server state.
 
-\item server will broadcast presence of a number of global objects,
+\item the server will broadcast the presence of a number of global objects,
   which in turn will broadcast their current state.
 \end{itemize}
 
@@ -82,7 +140,7 @@ This xml is used to generate the function prototypes that can be used by
 clients and compositors.
 
 The protocol entry points are generated as inline functions which just
-wraps the \verb:wl_proxy_*: functions.  The inline functions aren't
+wrap the \verb:wl_proxy_*: functions.  The inline functions aren't
 part of the library ABI and language bindings should generate their
 own stubs for the protocol entry points from the xml.