diff --git a/Makefile.am b/Makefile.am
index 016bb760..332f9b46 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,4 +1,4 @@
-SUBDIRS = src protocol
+SUBDIRS = src protocol doc
ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
diff --git a/configure.ac b/configure.ac
index fc623e82..b709e3c1 100644
--- a/configure.ac
+++ b/configure.ac
@@ -51,8 +51,13 @@ fi
AC_PATH_PROG(XSLTPROC, xsltproc)
AM_CONDITIONAL([HAVE_XSLTPROC], [test $XSLTPROC != ""])
+AC_PATH_PROG(PUBLICAN, publican)
+AM_CONDITIONAL([HAVE_PUBLICAN], [test $PUBLICAN != ""])
+
AC_CONFIG_FILES([Makefile
wayland-scanner.m4
+ doc/Makefile
+ doc/Wayland/Makefile
src/Makefile
src/wayland-server.pc
src/wayland-client.pc
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 00000000..f8046e78
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = Wayland
diff --git a/doc/Wayland/.gitignore b/doc/Wayland/.gitignore
new file mode 100644
index 00000000..cf787546
--- /dev/null
+++ b/doc/Wayland/.gitignore
@@ -0,0 +1,2 @@
+Wayland
+en-US/Protocol.xml
diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
new file mode 100644
index 00000000..0ac9fff9
--- /dev/null
+++ b/doc/Wayland/Makefile.am
@@ -0,0 +1,54 @@
+if HAVE_PUBLICAN
+noinst_DATA = Wayland
+
+publican_sources = \
+ $(srcdir)/en-US/Wayland.ent \
+ $(srcdir)/en-US/Architecture.xml \
+ $(srcdir)/en-US/Author_Group.xml \
+ $(srcdir)/en-US/Book_Info.xml \
+ $(srcdir)/en-US/Chapter.xml \
+ $(srcdir)/en-US/Preface.xml \
+ $(srcdir)/en-US/Wayland.xml \
+ $(srcdir)/en-US/Revision_History.xml \
+ $(srcdir)/en-US/images/icon.svg \
+ $(srcdir)/en-US/images/wayland-architecture.png \
+ $(srcdir)/en-US/images/wayland.png \
+ $(srcdir)/en-US/images/x-architecture.png
+
+# publican does not support out-of-tree builds and during make distcheck the
+# source tree is read-only so we can't chdir and/or dump the protocol there
+# copy the tree into _build, leaving a marker file to clean up after
+# distclean
+# See https://bugzilla.redhat.com/show_bug.cgi?id=798484 for the chmod
+copy-sources:
+ if ! test -e "en-US/"; then \
+ mkdir en-US/; \
+ touch en-US/need-distclean; \
+ cp -r $(srcdir)/en-US/* en-US; \
+ chmod u+w en-US/images; \
+ fi
+
+Wayland: docbook-xsl publican.cfg $(publican_sources)
+ publican build --config=$(srcdir)/publican.cfg --lang en-US --format html,pdf
+
+# This must be run befor the publican run
+docbook-xsl: copy-sources $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-to-docbook.xsl
+ $(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-to-docbook.xsl $(top_srcdir)/protocol/wayland.xml > $(builddir)/en-US/Protocol.xml
+
+clean-local:
+ -rm -rf Wayland
+ if test -e "en-US/need-distclean"; then \
+ rm -rf en-US; \
+ fi
+
+install-data-local:
+ $(MKDIR_P) $(DESTDIR)$(docdir)
+ cp -R $(builddir)/Wayland $(DESTDIR)$(docdir)
+
+uninstall-local:
+ -rm -rf $(DESTDIR)$(docdir)/Wayland/*
+ -rmdir $(DESTDIR)$(docdir)/Wayland
+
+EXTRA_DIST = $(publican_sources) publican.cfg protocol-to-docbook.xsl
+
+endif
diff --git a/doc/Wayland/en-US/Architecture.xml b/doc/Wayland/en-US/Architecture.xml
new file mode 100644
index 00000000..d10260a8
--- /dev/null
+++ b/doc/Wayland/en-US/Architecture.xml
@@ -0,0 +1,318 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+ Wayland Architecture
+
+ X vs. Wayland Architecture
+
+ A good way to understand the wayland architecture
+ and how it is different from X is to follow an event
+ from the input device to the point where the change
+ it affects appears on screen.
+
+
+ This is where we are now with X:
+
+
+
+
+
+
+
+
+
+
+ The kernel gets an event from an input
+ device and sends it to X through the evdev
+ input driver. The kernel does all the hard
+ work here by driving the device and
+ translating the different device specific
+ event protocols to the linux evdev input
+ event standard.
+
+
+
+
+ The X server determines which window the
+ event affects and sends it to the clients
+ that have selected for the event in question
+ on that window. The X server doesn't
+ actually know how to do this right, since
+ the window location on screen is controlled
+ by the compositor and may be transformed in
+ a number of ways that the X server doesn't
+ understand (scaled down, rotated, wobbling,
+ etc).
+
+
+
+
+ The client looks at the event and decides
+ what to do. Often the UI will have to change
+ in response to the event - perhaps a check
+ box was clicked or the pointer entered a
+ button that must be highlighted. Thus the
+ client sends a rendering request back to the
+ X server.
+
+
+
+
+ When the X server receives the rendering
+ request, it sends it to the driver to let it
+ program the hardware to do the rendering.
+ The X server also calculates the bounding
+ region of the rendering, and sends that to
+ the compositor as a damage event.
+
+
+
+
+ The damage event tells the compositor that
+ something changed in the window and that it
+ has to recomposite the part of the screen
+ where that window is visible. The compositor
+ is responsible for rendering the entire
+ screen contents based on its scenegraph and
+ the contents of the X windows. Yet, it has
+ to go through the X server to render this.
+
+
+
+
+ The X server receives the rendering requests
+ from the compositor and either copies the
+ compositor back buffer to the front buffer
+ or does a pageflip. In the general case, the
+ X server has to do this step so it can
+ account for overlapping windows, which may
+ require clipping and determine whether or
+ not it can page flip. However, for a
+ compositor, which is always fullscreen, this
+ is another unnecessary context switch.
+
+
+
+
+
+ As suggested above, there are a few problems with this
+ approach. The X server doesn't have the information to
+ decide which window should receive the event, nor can it
+ transform the screen coordinates to window local
+ coordinates. And even though X has handed responsibility for
+ the final painting of the screen to the compositing manager,
+ X still controls the front buffer and modesetting. Most of
+ the complexity that the X server used to handle is now
+ available in the kernel or self contained libraries (KMS,
+ evdev, mesa, fontconfig, freetype, cairo, Qt etc). In
+ general, the X server is now just a middle man that
+ introduces an extra step between applications and the
+ compositor and an extra step between the compositor and the
+ hardware.
+
+
+ In wayland the compositor is the display server. We transfer
+ the control of KMS and evdev to the compositor. The wayland
+ protocol lets the compositor send the input events directly
+ to the clients and lets the client send the damage event
+ directly to the compositor:
+
+
+
+
+
+
+
+
+
+
+ The kernel gets an event and sends
+ it to the compositor. This
+ is similar to the X case, which is
+ great, since we get to reuse all the
+ input drivers in the kernel.
+
+
+
+
+ The compositor looks through its
+ scenegraph to determine which window
+ should receive the event. The
+ scenegraph corresponds to what's on
+ screen and the compositor
+ understands the transformations that
+ it may have applied to the elements
+ in the scenegraph. Thus, the
+ compositor can pick the right window
+ and transform the screen coordinates
+ to window local coordinates, by
+ applying the inverse
+ transformations. The types of
+ transformation that can be applied
+ to a window is only restricted to
+ what the compositor can do, as long
+ as it can compute the inverse
+ transformation for the input events.
+
+
+
+
+ As in the X case, when the client
+ receives the event, it updates the
+ UI in response. But in the wayland
+ case, the rendering happens in the
+ client, and the client just sends a
+ request to the compositor to
+ indicate the region that was
+ updated.
+
+
+
+
+ The compositor collects damage
+ requests from its clients and then
+ recomposites the screen. The
+ compositor can then directly issue
+ an ioctl to schedule a pageflip with
+ KMS.
+
+
+
+
+
+
+
+
+ Wayland Rendering
+
+ One of the details I left out in the above overview
+ is how clients actually render under wayland. By
+ removing the X server from the picture we also
+ removed the mechanism by which X clients typically
+ render. But there's another mechanism that we're
+ already using with DRI2 under X: direct rendering.
+ With direct rendering, the client and the server
+ share a video memory buffer. The client links to a
+ rendering library such as OpenGL that knows how to
+ program the hardware and renders directly into the
+ buffer. The compositor in turn can take the buffer
+ and use it as a texture when it composites the
+ desktop. After the initial setup, the client only
+ needs to tell the compositor which buffer to use and
+ when and where it has rendered new content into it.
+
+
+
+ This leaves an application with two ways to update its window contents:
+
+
+
+
+
+ Render the new content into a new buffer and tell the compositor
+ to use that instead of the old buffer. The application can
+ allocate a new buffer every time it needs to update the window
+ contents or it can keep two (or more) buffers around and cycle
+ between them. The buffer management is entirely under
+ application control.
+
+
+
+
+ Render the new content into the buffer that it previously
+ told the compositor to to use. While it's possible to just
+ render directly into the buffer shared with the compositor,
+ this might race with the compositor. What can happen is that
+ repainting the window contents could be interrupted by the
+ compositor repainting the desktop. If the application gets
+ interrupted just after clearing the window but before
+ rendering the contents, the compositor will texture from a
+ blank buffer. The result is that the application window will
+ flicker between a blank window or half-rendered content. The
+ traditional way to avoid this is to render the new content
+ into a back buffer and then copy from there into the
+ compositor surface. The back buffer can be allocated on the
+ fly and just big enough to hold the new content, or the
+ application can keep a buffer around. Again, this is under
+ application control.
+
+
+
+
+
+ In either case, the application must tell the compositor
+ which area of the surface holds new contents. When the
+ application renders directly the to shared buffer, the
+ compositor needs to be noticed that there is new content.
+ But also when exchanging buffers, the compositor doesn't
+ assume anything changed, and needs a request from the
+ application before it will repaint the desktop. The idea
+ that even if an application passes a new buffer to the
+ compositor, only a small part of the buffer may be
+ different, like a blinking cursor or a spinner.
+ Hardware Enabling for Wayland
+
+
+ Typically, hardware enabling includes modesetting/display
+ and EGL/GLES2. On top of that Wayland needs a way to share
+ buffers efficiently between processes. There are two sides
+ to that, the client side and the server side.
+
+
+ On the client side we've defined a Wayland EGL platform. In
+ the EGL model, that consists of the native types
+ (EGLNativeDisplayType, EGLNativeWindowType and
+ EGLNativePixmapType) and a way to create those types. In
+ other words, it's the glue code that binds the EGL stack and
+ its buffer sharing mechanism to the generic Wayland API. The
+ EGL stack is expected to provide an implementation of the
+ Wayland EGL platform. The full API is in the wayland-egl.h
+ header. The open source implementation in the mesa EGL stack
+ is in wayland-egl.c and platform_wayland.c.
+
+
+ Under the hood, the EGL stack is expected to define a
+ vendor-specific protocol extension that lets the client side
+ EGL stack communicate buffer details with the compositor in
+ order to share buffers. The point of the wayland-egl.h API
+ is to abstract that away and just let the client create an
+ EGLSurface for a Wayland surface and start rendering. The
+ open source stack uses the drm Wayland extension, which lets
+ the client discover the drm device to use and authenticate
+ and then share drm (GEM) buffers with the compositor.
+
+
+ The server side of Wayland is the compositor and core UX for
+ the vertical, typically integrating task switcher, app
+ launcher, lock screen in one monolithic application. The
+ server runs on top of a modesetting API (kernel modesetting,
+ OpenWF Display or similar) and composites the final UI using
+ a mix of EGL/GLES2 compositor and hardware overlays if
+ available. Enabling modesetting, EGL/GLES2 and overlays is
+ something that should be part of standard hardware bringup.
+ The extra requirement for Wayland enabling is the
+ EGL_WL_bind_wayland_display extension that lets the
+ compositor create an EGLImage from a generic Wayland shared
+ buffer. It's similar to the EGL_KHR_image_pixmap extension
+ to create an EGLImage from an X pixmap.
+
+
+ The extension has a setup step where you have to bind the
+ EGL display to a Wayland display. Then as the compositor
+ receives generic Wayland buffers from the clients (typically
+ when the client calls eglSwapBuffers), it will be able to
+ pass the struct wl_buffer pointer to eglCreateImageKHR as
+ the EGLClientBuffer argument and with EGL_WAYLAND_BUFFER_WL
+ as the target. This will create an EGLImage, which can then
+ be used by the compositor as a texture or passed to the
+ modesetting code to use as an overlay plane. Again, this is
+ implemented by the vendor specific protocol extension, which
+ on the server side will receive the driver specific details
+ about the shared buffer and turn that into an EGL image when
+ the user calls eglCreateImageKHR.
+
+
+
diff --git a/doc/Wayland/en-US/Author_Group.xml b/doc/Wayland/en-US/Author_Group.xml
new file mode 100644
index 00000000..7a707604
--- /dev/null
+++ b/doc/Wayland/en-US/Author_Group.xml
@@ -0,0 +1,16 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+
+ Kristian
+ Høgsberg
+
+ Intel Corporation
+
+ krh@bitplanet.net
+
+
+
diff --git a/doc/Wayland/en-US/Book_Info.xml b/doc/Wayland/en-US/Book_Info.xml
new file mode 100644
index 00000000..4b134eb0
--- /dev/null
+++ b/doc/Wayland/en-US/Book_Info.xml
@@ -0,0 +1,34 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+ Wayland
+ The Wayland display server
+ Documentation
+ 0.1
+ 0
+ 0
+
+
+ Wayland is a protocol for a compositor to talk to
+ its clients as well as a C library implementation of
+ that protocol. The compositor can be a standalone
+ display server running on Linux kernel modesetting
+ and evdev input devices, an X application, or a
+ wayland client itself. The clients can be
+ traditional applications, X servers (rootless or
+ fullscreen) or other display servers.
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/Wayland/en-US/Chapter.xml b/doc/Wayland/en-US/Chapter.xml
new file mode 100644
index 00000000..f89f28b2
--- /dev/null
+++ b/doc/Wayland/en-US/Chapter.xml
@@ -0,0 +1,32 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+ Test Chapter
+
+ This is a test paragraph
+
+
+ Test Section 1
+
+ This is a test paragraph in a section
+
+
+
+
+ Test Section 2
+
+ This is a test paragraph in Section 2
+
+
+
+ listitem text
+
+
+
+
+
+
+
diff --git a/doc/Wayland/en-US/Preface.xml b/doc/Wayland/en-US/Preface.xml
new file mode 100644
index 00000000..610170af
--- /dev/null
+++ b/doc/Wayland/en-US/Preface.xml
@@ -0,0 +1,12 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+ Preface
+
+
+
+
+
diff --git a/doc/Wayland/en-US/Revision_History.xml b/doc/Wayland/en-US/Revision_History.xml
new file mode 100644
index 00000000..ef0907a5
--- /dev/null
+++ b/doc/Wayland/en-US/Revision_History.xml
@@ -0,0 +1,26 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+ Revision History
+
+
+
+ 0-0
+ Thu Feb 23 2012
+
+ Dude
+ McPants
+ Dude.McPants@example.com
+
+
+
+ Initial creation of book by publican
+
+
+
+
+
+
diff --git a/doc/Wayland/en-US/Wayland.ent b/doc/Wayland/en-US/Wayland.ent
new file mode 100644
index 00000000..da18a952
--- /dev/null
+++ b/doc/Wayland/en-US/Wayland.ent
@@ -0,0 +1,4 @@
+
+
+
+
diff --git a/doc/Wayland/en-US/Wayland.xml b/doc/Wayland/en-US/Wayland.xml
new file mode 100644
index 00000000..829d362d
--- /dev/null
+++ b/doc/Wayland/en-US/Wayland.xml
@@ -0,0 +1,19 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+
+
+
+
+
+
+
+
diff --git a/doc/Wayland/en-US/images/icon.svg b/doc/Wayland/en-US/images/icon.svg
new file mode 100644
index 00000000..b2f16d0f
--- /dev/null
+++ b/doc/Wayland/en-US/images/icon.svg
@@ -0,0 +1,19 @@
+
+
diff --git a/doc/Wayland/en-US/images/wayland-architecture.png b/doc/Wayland/en-US/images/wayland-architecture.png
new file mode 100644
index 00000000..4f92e0fb
Binary files /dev/null and b/doc/Wayland/en-US/images/wayland-architecture.png differ
diff --git a/doc/Wayland/en-US/images/wayland.png b/doc/Wayland/en-US/images/wayland.png
new file mode 100644
index 00000000..c9937928
Binary files /dev/null and b/doc/Wayland/en-US/images/wayland.png differ
diff --git a/doc/Wayland/en-US/images/x-architecture.png b/doc/Wayland/en-US/images/x-architecture.png
new file mode 100644
index 00000000..098205b5
Binary files /dev/null and b/doc/Wayland/en-US/images/x-architecture.png differ
diff --git a/doc/Wayland/protocol-to-docbook.xsl b/doc/Wayland/protocol-to-docbook.xsl
new file mode 100644
index 00000000..e50d80d9
--- /dev/null
+++ b/doc/Wayland/protocol-to-docbook.xsl
@@ -0,0 +1,113 @@
+
+
+
+
+
+
+
+
+%BOOK_ENTITIES;
+]>
+]]>
+
+
+ Wayland Protocol Specification
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ protocol--
+
+
+ <xsl:value-of select="@name" />
+ <!-- only show summary if it exists -->
+ <xsl:if test="description/@summary">
+ - <xsl:value-of select="description/@summary" />
+ </xsl:if>
+
+
+
+
+
+
+ Requests provided by <xsl:value-of select="@name" />
+
+
+
+
+
+ Events provided by <xsl:value-of select="@name" /> events
+
+
+
+
+
+ Enums provided by <xsl:value-of select="@name" /> enums
+
+
+
+
+
+
+
+
+
+
+
+
+ Type:
+
+
+ Value:
+
+
+
+
+
+
+
+
+
+
+
+ protocol-interface---
+
+ <xsl:value-of select="../@name"/>::<xsl:value-of select="@name" />
+ <xsl:if test="description/@summary">
+ - <xsl:value-of select="description/@summary" />
+ </xsl:if>
+
+
+
+
+ <xsl:value-of select="../@name"/>::<xsl:value-of select="@name" /> arguments
+
+
+
+
+
+ <xsl:value-of select="../@name"/>::<xsl:value-of select="@name" /> values
+
+
+
+
+
+
+
+
diff --git a/doc/Wayland/publican.cfg b/doc/Wayland/publican.cfg
new file mode 100644
index 00000000..810c7358
--- /dev/null
+++ b/doc/Wayland/publican.cfg
@@ -0,0 +1,8 @@
+# Config::Simple 4.59
+# Fri Feb 24 09:36:50 2012
+
+xml_lang: "en-US"
+type: Book
+brand: common
+tmp_dir: Wayland
+
diff --git a/protocol/Makefile.am b/protocol/Makefile.am
index 9c6cc49e..49395576 100644
--- a/protocol/Makefile.am
+++ b/protocol/Makefile.am
@@ -1,7 +1,8 @@
if HAVE_XSLTPROC
-doc_DATA = wayland.html wayland-protocol.css
+dist_doc_DATA = wayland.html wayland-protocol.css wayland.xml
-wayland.html: wayland.xml protocol.xsl
- $(AM_V_GEN)$(XSLTPROC) protocol.xsl wayland.xml > $@
+wayland.html: $(srcdir)/wayland.xml $(srcdir)/protocol.xsl
+ $(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol.xsl $(srcdir)/wayland.xml > $@
+CLEANFILES = wayland.html
endif