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.

3 files changed, 86 insertions, 28 deletions

diff --git a/spec/main.tex b/spec/main.tex
index f32e999..741c4e0 100644
--- a/spec/main.tex
+++ b/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}
 
@@ -14,40 +15,97 @@
 \section{Wayland Overview}
 
 \begin{itemize}
-\item wayland is a protocol for a new display server.  
-\item wayland is an implementation
+\item wayland is a protocol for a new display server.
+\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
-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. 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. Recently with GEM and KMS in the Linux
-kernel, we can do modesetting outside X and schedule several direct
-rendering clients. The end result is a highly modular graphics stack.
+In Linux and other Unix-like systems, the X stack has grown to
+encompass funcationality 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.
+
+\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
-components. 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 by themselves. In the end,
-what’s needed is a way to present the resulting window surface to a
-compositor and a way to receive input. This is what Wayland provides,
-by piecing together the components already in the eco-system in a
-slightly different way.
+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.
+
+\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
-  change.  client must listen for these changes and cache the state.
-  no need (or mechanism) to query server state.
+\item state is broadcast on connect, events are sent out when state
+  changes.  clients must listen for these changes and cache the 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.
 
diff --git a/spec/wayland-architecture.png b/spec/wayland-architecture.png
new file mode 100644
index 0000000..4f92e0f
--- /dev/null
+++ b/spec/wayland-architecture.png
diff --git a/spec/x-architecture.png b/spec/x-architecture.png
new file mode 100644
index 0000000..098205b
--- /dev/null
+++ b/spec/x-architecture.png