mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2025-10-31 22:25:25 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: rename "Wayland" to "publican"

Browse source 
This directory was called Wayland during my early tries with publican where
the source layout was different and it needed to be set to the same name as
the publican output directory. This reason doesn't exist anymore, so re-name
it to publican to make it more obvious what's hiding in here.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2013-04-03 15:43:34 -04:00 • committed by Kristian Høgsberg
parent 8ccab1ba62
commit 9d296fc73a
24 changed files with 2 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

3
doc/publican/.gitignore vendored Normal file
View file

@ -0,0 +1,3 @@
Wayland
en-US/
publican-copy.cfg

125
doc/publican/Makefile.am Normal file
View file

@ -0,0 +1,125 @@
# Documentation is built with publican
# https://fedorahosted.org/publican/
# Publican takes docbook-style input files and compiles them to various
# output formats.
#
# How this build works:
# * the main target is Wayland, documentation ends up in $(builddir)/Wayland/
# * hand-written chapters are located in sources
# Publican does not take a source path, so to support out-of-tree builds
# these are copied to $(builddir)/en-US which is the actual directory
# Publican uses.
# * ProtocolSpec.xml is generated from $(top_srcdir)/protocol/wayland.xml,
# changed into docbook via XSLT and saved in $(builddir)/en-US/
# * ProtocolInterfaces.xml, same as above, uses a different XSLT
# * WaylandClientAPI.xml is generated from the doxygen output and saved in
# $(builddir)/en-US
# * run Publican on en-US
publican_sources = \
$(srcdir)/sources/Wayland.ent \
$(srcdir)/sources/Wayland.xml \
$(srcdir)/sources/Book_Info.xml \
$(srcdir)/sources/Author_Group.xml \
$(srcdir)/sources/Foreword.xml \
$(srcdir)/sources/Preface.xml \
$(srcdir)/sources/Revision_History.xml \
$(srcdir)/sources/Introduction.xml \
$(srcdir)/sources/Architecture.xml \
$(srcdir)/sources/Protocol.xml \
$(srcdir)/sources/Library.xml \
$(srcdir)/sources/Compositors.xml \
$(srcdir)/sources/images/icon.svg \
$(srcdir)/sources/images/wayland-architecture.png \
$(srcdir)/sources/images/wayland.png \
$(srcdir)/sources/images/x-architecture.png
if HAVE_PUBLICAN
if HAVE_XSLTPROC
noinst_DATA = Wayland $(publican_targets)
pubdir = $(docdir)/Wayland/en-US
publican_targets = $(publican_sources:$(srcdir)/sources%=$(builddir)/en-US%) \
en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml \
en-US/WaylandClientAPI.xml
# The Protocol.xml is purely generated and required before running publican
en-US/ProtocolSpec.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-to-docbook.xsl
$(AM_V_GEN)$(MKDIR_P) en-US/images
$(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-to-docbook.xsl \
$(top_srcdir)/protocol/wayland.xml > en-US/ProtocolSpec.xml
en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-interfaces-to-docbook.xsl
$(AM_V_GEN)$(MKDIR_P) en-US/images
$(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-interfaces-to-docbook.xsl \
$(top_srcdir)/protocol/wayland.xml > en-US/ProtocolInterfaces.xml
# WaylandClientAPI.xml:
# * we don't want wayland-client_8h.xml to avoid duplicating output methods,
# move it out of the way first.
# * use doxygen's combine.xslt to merge the xml files into one single file
# * move wayland-client_8h.xml back to its original location
# * transform the combined XML file into docbook format
en-US/WaylandClientAPI.xml: $(top_builddir)/doc/doxygen/xml/index.xml $(srcdir)/doxygen-to-publican.xsl
$(AM_V_GEN)$(MKDIR_P) en-US/images
$(AM_V_GEN)mv $(top_builddir)/doc/doxygen/xml/wayland-client_8h.xml \
$(top_builddir)/doc/doxygen/
$(AM_V_GEN)$(XSLTPROC) $(top_builddir)/doc/doxygen/xml/combine.xslt \
$(top_builddir)/doc/doxygen/xml/index.xml > \
$(top_builddir)/doc/doxygen/xml/clientAPI.xml
$(AM_V_GEN)mv $(top_builddir)/doc/doxygen/wayland-client_8h.xml \
$(top_builddir)/doc/doxygen/xml
$(AM_V_GEN)$(XSLTPROC) $(srcdir)/doxygen-to-publican.xsl \
$(top_builddir)/doc/doxygen/xml/clientAPI.xml > en-US/WaylandClientAPI.xml
# Copy the sources source files into en-US destination
# This is required for out-of-source-tree build as publican does not allow us
# to specify the location of the source code.
$(builddir)/en-US/%: $(srcdir)/sources/% en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_sources)
$(AM_V_GEN)cp -f $< $@
$(AM_V_GEN)chmod a+w $@
# Run publican for the builddir on the generated (or copied) source
# The output formats are generated in the Wayland sub directory. Also, we need
# to use a tmp publican.cfg cause 'publican rename' modifies the original.
Wayland: $(publican_targets)
$(AM_V_GEN)cp -f $(srcdir)/publican.cfg $(builddir)/publican-copy.cfg
$(AM_V_GEN)$(PUBLICAN) rename --name Wayland \
--version "$(WAYLAND_VERSION_MAJOR).$(WAYLAND_VERSION_MINOR)" \
--config $(builddir)/publican-copy.cfg
$(AM_V_GEN)$(PUBLICAN) build --quiet --langs en-US --formats html,pdf \
--config $(builddir)/publican-copy.cfg
@touch Wayland
CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_targets)
clean-local:
$(AM_V_at)rm -fr $(builddir)/en-US
$(AM_V_at)rm -fr $(builddir)/Wayland
$(AM_V_at)rm -fr $(builddir)/publican-copy.cfg
install-data-local:
test -z "$(pubdir)/html/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/Common_Content/css"
test -z "$(pubdir)/html/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/Common_Content/images"
test -z "$(pubdir)/html/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/images"
test -z "$(pubdir)/pdf" || $(mkdir_p) "$(DESTDIR)$(pubdir)/pdf"
test -z "$(pubdir)/xml/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/Common_Content/css"
test -z "$(pubdir)/xml/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/Common_Content/images"
test -z "$(pubdir)/xml/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/images"
list=`find $(builddir)/Wayland/en-US -type f -not -path '$(builddir)/Wayland/en-US/xml_tmp*'`; \
for p in $$list; do \
echo " $(INSTALL_DATA) '$$p' '$(DESTDIR)$(docdir)/$$p'"; \
$(INSTALL_DATA) "$$p" "$(DESTDIR)$(docdir)/$$p"; \
done;
uninstall-local:
@if test -n $(DESTDIR)$(docdir); then \
if test -d $(DESTDIR)$(docdir); then \
echo " rm -fr $(DESTDIR)$(docdir)/Wayland;"; \
rm -fr $(DESTDIR)$(docdir)/Wayland; \
fi; \
fi;
endif
endif
EXTRA_DIST = $(publican_sources) publican.cfg protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-publican.xsl

164
doc/publican/doxygen-to-publican.xsl Normal file
View file

@ -0,0 +1,164 @@
<?xml version="1.0" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" encoding="UTF-8" indent="yes" />
<xsl:template match="/">
<!-- insert docbook's DOCTYPE blurb -->
<xsl:text disable-output-escaping = "yes"><![CDATA[
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
]]></xsl:text>
<section id="sect-Library-Client">
<title>Client API</title>
<para>Following is the Wayland library classes for clients
(<emphasis>libwayland-client</emphasis>). Note that most of the
procedures are related with IPC, which is the main responsibility of
the library.
</para>
<xsl:if test="/doxygen/compounddef[@kind='class']">
<para>
<variablelist>
<xsl:apply-templates select="/doxygen/compounddef" />
</variablelist>
</para>
</xsl:if>
<para>Methods for the respective classes.</para>
<para>
<variablelist>
<xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" />
</variablelist>
</para>
</section>
</xsl:template>
<xsl:template match="parameteritem">
<varlistentry>
<term>
<xsl:value-of select="parameternamelist/parametername"/>
</term>
<listitem>
<para>
<xsl:value-of select="parameterdescription/para"/>
</para>
</listitem>
</varlistentry>
</xsl:template>
<xsl:template match="parameterlist">
<xsl:if test="parameteritem">
<variablelist>
<xsl:apply-templates select="parameteritem" />
</variablelist>
</xsl:if>
</xsl:template>
<xsl:template match="ref">
<emphasis><xsl:value-of select="." /></emphasis>
</xsl:template>
<xsl:template match="simplesect[@kind='return']">
<variablelist>
<varlistentry>
<term>Returns:</term>
<listitem>
<para>
<xsl:value-of select="." />
</para>
</listitem>
</varlistentry>
</variablelist>
</xsl:template>
<xsl:template match="simplesect[@kind='see']">
<itemizedlist>
<listitem>
<para>
See also:
<xsl:for-each select="para/ref">
<emphasis><xsl:value-of select="."/><xsl:text> </xsl:text></emphasis>
</xsl:for-each>
</para>
</listitem>
</itemizedlist>
</xsl:template>
<xsl:template match="simplesect[@kind='since']">
<itemizedlist>
<listitem>
<para>
Since: <xsl:value-of select="para"/>
</para>
</listitem>
</itemizedlist>
</xsl:template>
<xsl:template match="simplesect[@kind='note']">
<emphasis>Note: <xsl:value-of select="."/></emphasis>
</xsl:template>
<xsl:template match="programlisting">
<programlisting><xsl:value-of select="."/></programlisting>
</xsl:template>
<!-- this opens a para for each detaileddescription/para. I could not find a
way to extract the right text for the description from the
source otherwise. Downside: we can't use para for return value, "see
also", etc. because they're already inside a para. So they're lists.
It also means we don't control the order of when something is added to
the output, it matches the input file
-->
<xsl:template match="detaileddescription/para">
<para><xsl:apply-templates /></para>
</xsl:template>
<xsl:template match="detaileddescription">
<xsl:apply-templates select="para" />
</xsl:template>
<!-- methods -->
<xsl:template match="memberdef" >
<xsl:if test="@kind = 'function' and @static = 'no'">
<varlistentry>
<term>
<xsl:value-of select="name"/>
- <xsl:value-of select="briefdescription" />
</term>
<listitem>
<para>
<synopsis>
<xsl:value-of select="definition"/><xsl:value-of select="argsstring"/>
</synopsis>
</para>
<xsl:apply-templates select="detaileddescription" />
</listitem>
</varlistentry>
</xsl:if>
</xsl:template>
<!-- classes -->
<xsl:template match="compounddef" >
<xsl:if test="@kind = 'class' ">
<varlistentry>
<term>
<xsl:value-of select="compoundname" />
<xsl:if test="briefdescription">
- <xsl:value-of select="briefdescription" />
</xsl:if>
</term>
<listitem>
<xsl:for-each select="detaileddescription/para">
<para><xsl:value-of select="." /></para>
</xsl:for-each>
</listitem>
</varlistentry>
</xsl:if>
</xsl:template>
</xsl:stylesheet>

56
doc/publican/protocol-interfaces-to-docbook.xsl Normal file
View file

@ -0,0 +1,56 @@
<?xml version="1.0" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes" encoding="UTF-8"/>
<xsl:output method="xml" encoding="UTF-8" indent="yes" />
<xsl:template match="/">
<!-- insert docbook's DOCTYPE blurb -->
<xsl:text disable-output-escaping = "yes"><![CDATA[
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
]]></xsl:text>
<section id="sect-Protocol-Interfaces">
<title>Interfaces</title>
<para>
The protocol includes several interfaces which are used for
interacting with the server. Each interface provides requests,
events, and errors (which are really just special events) as described
above. Specific compositor implementations may have their own
interfaces provided as extensions, but there are several which are
always expected to be present.
</para>
<para>
Core interfaces:
<variablelist>
<xsl:apply-templates select="protocol/interface" />
</variablelist>
</para>
</section>
</xsl:template>
<!-- Interfaces summary -->
<xsl:template match="interface" >
<varlistentry>
<xsl:attribute name="id">protocol-summary-<xsl:value-of select="name()"/>-<xsl:value-of select="@name" />
</xsl:attribute>
<term>
<xsl:value-of select="@name" />
<xsl:if test="description/@summary">
- <xsl:value-of select="description/@summary" />
</xsl:if>
</term>
<listitem>
<para>
<xsl:value-of select="description"/>
</para>
</listitem>
</varlistentry>
</xsl:template>
</xsl:stylesheet>
<!-- vim: set expandtab shiftwidth=2: -->

136
doc/publican/protocol-to-docbook.xsl Normal file
View file

@ -0,0 +1,136 @@
<?xml version="1.0" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes" encoding="UTF-8"/>
<xsl:output method="xml" encoding="UTF-8" indent="yes" />
<xsl:template match="/">
<!-- insert docbook's DOCTYPE blurb -->
<xsl:text disable-output-escaping = "yes"><![CDATA[
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
]]></xsl:text>
<appendix id="appe-Wayland-Protocol">
<title>Wayland Protocol Specification</title>
<xsl:apply-templates select="protocol/copyright" />
<xsl:apply-templates select="protocol/interface" />
</appendix>
</xsl:template>
<!-- Break text blocks separated by two new lines into paragraphs -->
<xsl:template name="break">
<xsl:param name="text" />
<xsl:param name="linebreak" select="'&#10;&#10;'" />
<xsl:choose>
<xsl:when test="contains($text,$linebreak)">
<para>
<xsl:value-of select="substring-before($text,$linebreak)" />
</para>
<xsl:call-template name="break">
<xsl:with-param name="text" select="substring-after($text,$linebreak)" />
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<para><xsl:value-of select="$text" /></para>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Copyright blurb -->
<xsl:template match="copyright">
<para>
<literallayout>
<xsl:value-of select="." disable-output-escaping="yes"/>
</literallayout>
</para>
</xsl:template>
<!-- Interface descriptions -->
<xsl:template match="interface" >
<section>
<xsl:attribute name="id">protocol-spec-<xsl:value-of select="name()"/>-<xsl:value-of select="@name" />
</xsl:attribute>
<title>
<xsl:value-of select="@name" />
<!-- only show summary if it exists -->
<xsl:if test="description/@summary">
- <xsl:value-of select="description/@summary" />
</xsl:if>
</title>
<xsl:call-template name="break">
<xsl:with-param name="text" select="description" />
</xsl:call-template>
<xsl:if test="request">
<section>
<title>Requests provided by <xsl:value-of select="@name" /></title>
<xsl:apply-templates select="request" />
</section>
</xsl:if>
<xsl:if test="event">
<section>
<title>Events provided by <xsl:value-of select="@name" /></title>
<xsl:apply-templates select="event" />
</section>
</xsl:if>
<xsl:if test="enum">
<section>
<title>Enums provided by <xsl:value-of select="@name" /></title>
<xsl:apply-templates select="enum" />
</section>
</xsl:if>
</section>
</xsl:template>
<!-- table contents for request/event arguments or enum values -->
<xsl:template match="arg|entry">
<varlistentry>
<term><xsl:value-of select="@name"/></term>
<listitem>
<xsl:if test="name() = 'arg'" >
<para>Type: <xsl:value-of select="@type"/></para>
</xsl:if>
<xsl:if test="name() = 'entry'" >
<para>Value: <xsl:value-of select="@value"/></para>
</xsl:if>
<xsl:if test="@summary" >
<para>
<xsl:value-of select="@summary"/>
</para>
</xsl:if>
</listitem>
</varlistentry>
</xsl:template>
<!-- Request/event list -->
<xsl:template match="request|event|enum">
<section>
<xsl:attribute name="id">protocol-spec-interface-<xsl:value-of select="../@name"/>-<xsl:value-of select="name()"/>-<xsl:value-of select="@name"/></xsl:attribute>
<title>
<xsl:value-of select="../@name"/>::<xsl:value-of select="@name" />
<xsl:if test="description/@summary">
- <xsl:value-of select="description/@summary" />
</xsl:if>
</title>
<xsl:call-template name="break">
<xsl:with-param name="text" select="description" />
</xsl:call-template>
<xsl:if test="arg">
<variablelist>
<title><xsl:value-of select="../@name"/>::<xsl:value-of select="@name" /> arguments</title>
<xsl:apply-templates select="arg"/>
</variablelist>
</xsl:if>
<xsl:if test="entry">
<variablelist>
<title><xsl:value-of select="../@name"/>::<xsl:value-of select="@name" /> values</title>
<xsl:apply-templates select="entry"/>
</variablelist>
</xsl:if>
</section>
</xsl:template>
</xsl:stylesheet>
<!-- vim: set expandtab shiftwidth=2: -->

8
doc/publican/publican.cfg Normal file
View file

@ -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
toc_section_depth: 1

330
doc/publican/sources/Architecture.xml Normal file
View file

@ -0,0 +1,330 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Wayland-Architecture">
<title>Wayland Architecture</title>
<section id="sect-Wayland-Architecture-wayland_architecture">
<title>X vs. Wayland Architecture</title>
<para>
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.
</para>
<para>
This is where we are now with X:
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/x-architecture.png" format="PNG" />
</imageobject>
<textobject>
<phrase>
X architecture diagram
</phrase>
</textobject>
</mediaobject>
<para>
<orderedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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).
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</orderedlist>
</para>
<para>
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.
</para>
<para>
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:
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/wayland-architecture.png" format="PNG" />
</imageobject>
<textobject>
<phrase>
Wayland architecture diagram
</phrase>
</textobject>
</mediaobject>
<para>
<orderedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</orderedlist>
</para>
</section>
<section id="sect-Wayland-Architecture-wayland_rendering">
<title>Wayland Rendering</title>
<para>
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.
</para>
<para>
This leaves an application with two ways to update its window contents:
</para>
<para>
<orderedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</orderedlist>
</para>
<para>
In either case, the application must tell the compositor
which area of the surface holds new contents. When the
application renders directly to the 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.
</para>
</section>
<section id="sect-Wayland-Architecture-wayland_hw_enabling">
<title>Hardware Enabling for Wayland</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
</section>
</chapter>

16
doc/publican/sources/Author_Group.xml Normal file
View file

@ -0,0 +1,16 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<authorgroup>
<author>
<firstname>Kristian</firstname>
<surname>Høgsberg</surname>
<affiliation>
<orgname>Intel Corporation</orgname>
</affiliation>
<email>krh@bitplanet.net</email>
</author>
</authorgroup>

39
doc/publican/sources/Book_Info.xml Normal file
View file

@ -0,0 +1,39 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<bookinfo id="book-Wayland-Wayland">
<title>Wayland</title>
<subtitle>The Wayland display server</subtitle>
<productname>Documentation</productname>
<productnumber>0.1</productnumber>
<edition>1</edition>
<pubsnumber>0</pubsnumber>
<abstract>
<para>
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.
</para>
</abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/wayland.png" format="PNG" />
</imageobject>
<textobject>
<phrase>
Wayland logo
</phrase>
</textobject>
</inlinemediaobject>
</corpauthor>
<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

111
doc/publican/sources/Compositors.xml Normal file
View file

@ -0,0 +1,111 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Compositors">
<title>Types of Compositors</title>
<para>
Compositors come in different types, depending on which
role they play in the overall architecture of the OS.
</para>
<section id="sect-Compositors-System-Compositor">
<title>System Compositor</title>
<para>
A system compositor can run from early boot until shutdown.
It effectively replaces the kernel vt system, and can tie in
with the systems graphical boot setup and multiseat support.
</para>
<para>
A system compositor can host different types of session
compositors, and let us switch between multiple sessions
(fast user switching, or secure/personal desktop switching).
</para>
<para>
A linux implementation of a system compositor will typically
use libudev, egl, kms, evdev and cairo.
</para>
<para>
For fullscreen clients, the system compositor can reprogram the
video scanout address to read directly from the client provided
buffer.
</para>
</section>
<section id="sect-Compositors-Session-Compositor">
<title>Session Compositor</title>
<para>
A session compositor is responsible for a single user session.
If a system compositor is present, the session compositor will
run nested under the system compositor. Nesting is feasible because
the protocol is asynchronous; roundtrips would be too expensive
when nesting is involved. If no system compositor is present, a
session compositor can run directly on the hw.
</para>
<para>
X applications can continue working under a session compositor
by means of a root less X server that is activated on demand.
</para>
<para>
Possible examples for session compositors include
<itemizedlist>
<listitem>
<para>
gnome-shell
</para>
</listitem>
<listitem>
<para>
moblin
</para>
</listitem>
<listitem>
<para>
kwin
</para>
</listitem>
<listitem>
<para>
kmscon
</para>
</listitem>
<listitem>
<para>
rdp session
</para>
</listitem>
<listitem>
<para>
fullscreen X session under wayland
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="sect-Compositors-Embedding-Compositor">
<title>Embedding Compositor</title>
<para>
X11 lets clients embed windows from other clients, or lets clients
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 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.
</para>
<para>
An example for this kind of setup is firefox embedding the flash
player as a kind of special-purpose compositor.
</para>
</section>
</chapter>

29
doc/publican/sources/Foreword.xml Normal file
View file

@ -0,0 +1,29 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<preface>
<title>Preface</title>
<para>
This document concerns the (i) Wayland architecture, (ii) Wayland model of
operation and (iii) its library API. Wayland protocol specification is shown
also in the Appendix. The document here is aimed at Wayland developers and
who is looking for information how to program with it, but it is not meant
primarily for applications developers.
</para>
<para>
There have been many contributors to this document and, while this is the
first edition only, many errors are expected to be found. We appreciate
corrections.
</para>
<literallayout>
Yours,
the Wayland open-source community
November 2012
</literallayout>
</preface>

116
doc/publican/sources/Introduction.xml Normal file
View file

@ -0,0 +1,116 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Introduction">
<title>Introduction</title>
<section id="sect-Motivation">
<title>Motivation</title>
<para>
Most of Linux and Unix-based systems rely on the X Window System (or
simply <emphasis>X</emphasis>) as the low-level protocol for building
bitmap graphics interfaces. On these 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).
</para>
<para>
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.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/x-architecture.png" format="PNG" />
</imageobject>
<textobject>
<phrase>
X architecture diagram
</phrase>
</textobject>
</mediaobject>
<para>
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.
</para>
<para>
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.
</para>
</section>
<section id="sect-Compositing-manager-display-server">
<title>The compositing manager as the display server</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/wayland-architecture.png" format="PNG" />
</imageobject>
<textobject>
<phrase>
Wayland architecture diagram
</phrase>
</textobject>
</mediaobject>
<para>
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).
</para>
</section>
</chapter>

9
doc/publican/sources/Library.xml Normal file
View file

@ -0,0 +1,9 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Library">
<title>Wayland Library</title>
<xi:include href="WaylandClientAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</chapter>

20
doc/publican/sources/Preface.xml Normal file
View file

@ -0,0 +1,20 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<preface>
<title>Acknowledgments</title>
<para>
TODO: Kristian has to fill up this with one or two paragraphs and a small
"thank you": http://en.wikipedia.org/wiki/Preface
</para>
<literallayout>
Best,
Kristian Høgsberg
</literallayout>
</preface>

462
doc/publican/sources/Protocol.xml Normal file
View file

@ -0,0 +1,462 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Protocol">
<title>Wayland Protocol and Model of Operation</title>
<section id="sect-Protocol-Basic-Principles">
<title>Basic Principles</title>
<para>
The wayland protocol is an asynchronous object oriented protocol. All
requests are method invocations on some object. The requests include
an object ID that uniquely identifies an object on the server. Each
object implements an interface and the requests include an opcode that
identifies which method in the interface to invoke.
</para>
<para>
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 requests
(in which case the request and the event constitutes a round trip) or
spontaneously when the server state changes.
</para>
<para>
<itemizedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
The server will broadcast the presence of a number of global objects,
which in turn will broadcast their current state.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="sect-Protocol-Code-Generation">
<title>Code Generation</title>
<para>
The interfaces, requests and events are defined in
<filename>protocol/wayland.xml</filename>.
This xml is used to generate the function prototypes that can be used by
clients and compositors.
</para>
<para>
The protocol entry points are generated as inline functions which just
wrap the <function>wl_proxy_*</function> 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.
</para>
</section>
<section id="sect-Protocol-Wire-Format">
<title>Wire Format</title>
<para>
The protocol is sent over a UNIX domain stream socket, where the endpoint
usually is named <systemitem class="service">wayland-0</systemitem>
(although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis>
in the environment). The protocol is message-based. A
message sent by a client to the server is called request. A message
from the server to a client is called event. Every message is
structured as 32-bit words, values are represented in the host's
byte-order.
</para>
<para>
The message header has 2 words in it:
<itemizedlist>
<listitem>
<para>
The first word is the sender's object ID (32-bit).
</para>
</listitem>
<listitem>
<para>
The second has 2 parts of 16-bit. The upper 16-bits are the message
size in bytes, starting at the header (i.e. it has a minimum value of 8).The lower is the request/event opcode.
</para>
</listitem>
</itemizedlist>
The payload describes the request/event arguments. Every argument is always
aligned to 32-bits. Where padding is required, the value of padding bytes is
undefined. There is no prefix that describes the type, but it is
inferred implicitly from the xml specification.
</para>
<para>
The representation of argument types are as follows:
<variablelist>
<varlistentry>
<term>int</term>
<term>uint</term>
<listitem>
<para>
The value is the 32-bit value of the signed/unsigned
int.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fixed</term>
<listitem>
<para>
Signed 24.8 decimal numbers. It is a signed decimal type which
offers a sign bit, 23 bits of integer precision and 8 bits of
decimal precision. This is exposed as an opaque struct with
conversion helpers to and from double and int on the C API side.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>string</term>
<listitem>
<para>
Starts with an unsigned 32-bit length, followed by the
string contents, including terminating null byte, then padding
to a 32-bit boundary.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>object</term>
<listitem>
<para>
32-bit object ID.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>new_id</term>
<listitem>
<para>
The 32-bit object ID. On requests, the client
decides the ID. The only events with <type>new_id</type> are
advertisements of globals, and the server will use IDs below
0x10000.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>array</term>
<listitem>
<para>
Starts with 32-bit array size in bytes, followed by the array
contents verbatim, and finally padding to a 32-bit boundary.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fd</term>
<listitem>
<para>
The file descriptor is not stored in the message buffer, but in
the ancillary data of the UNIX domain socket message (msg_control).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<xi:include href="ProtocolInterfaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<section id="sect-Protocol-Connect-Time">
<title>Connect Time</title>
<para>
There is no fixed connection setup information, the server emits
multiple events at connect time, to indicate the presence and
properties of global objects: outputs, compositor, input devices.
</para>
</section>
<section id="sect-Protocol-Security-and-Authentication">
<title>Security and Authentication</title>
<para>
<itemizedlist>
<listitem>
<para>
mostly about access to underlying buffers, need new drm auth
mechanism (the grant-to ioctl idea), need to check the cmd stream?
</para>
</listitem>
<listitem>
<para>
getting the server socket depends on the compositor type, could
be a system wide name, through fd passing on the session dbus.
or the client is forked by the compositor and the fd is
already opened.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="sect-Protocol-Creating-Objects">
<title>Creating Objects</title>
<para>
Each object has a unique ID. The IDs are allocated by the
client, from a range of IDs. The server tracks how many
IDs are left in the current range and sends a new range
when the client is about to run out.
</para>
</section>
<section id="sect-Protocol-Compositor">
<title>Compositor</title>
<para>
The compositor is a global object, advertised at connect time.
</para>
<para>
See <xref linkend="protocol-spec-interface-wl_compositor"/> for the
protocol description.
</para>
</section>
<section id="sect-Protocol-Surface">
<title>Surfaces</title>
<para>
Surfaces are created by the client.
Clients don't know the global position of their surfaces, and
cannot access other clients surfaces.
</para>
<para>
See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
description.
</para>
</section>
<section id="sect-Protocol-Input">
<title>Input</title>
<para>
A seat represents a group of input devices including mice,
keyboards and touchscreens. It has a keyboard and pointer
focus. Seats are global objects. Pointer events are delivered
in surface local coordinates.
</para>
<para>
The compositor maintains an implicit grab when a button is
pressed, to ensure that the corresponding button release
event gets delivered to the same surface. But there is no way
for clients to take an explicit grab. Instead, surfaces can
be mapped as 'popup', which combines transient window semantics
with a pointer grab.
</para>
<para>
To avoid race conditions, input events that are likely to
trigger further requests (such as button presses, key events,
pointer motions) carry serial numbers, and requests such as
wl_surface.set_popup require that the serial number of the
triggering event is specified. The server maintains a
monotonically increasing counter for these serial numbers.
</para>
<para>
Input events also carry timestamps with millisecond granularity.
Their base is undefined, so they can't be compared against
system time (as obtained with clock_gettime or gettimeofday).
They can be compared with each other though, and for instance
be used to identify sequences of button presses as double
or triple clicks.
</para>
<para>
See <xref linkend="protocol-spec-interface-wl_seat"/> for the
protocol description.
</para>
<para>
Talk about:
<itemizedlist>
<listitem>
<para>
keyboard map, change events
</para>
</listitem>
<listitem>
<para>
xkb on wayland
</para>
</listitem>
<listitem>
<para>
multi pointer wayland
</para>
</listitem>
</itemizedlist>
</para>
<para>
A surface can change the pointer image when the surface is the pointer
focus of the input device. Wayland doesn't automatically change the
pointer image when a pointer enters a surface, but expects the
application to set the cursor it wants in response the pointer
focus and motion events. The rationale is that a client has to manage
changing pointer images for UI elements within the surface in response
to motion events anyway, so we'll make that the only mechanism for
setting changing the pointer image. If the server receives a request
to set the pointer image after the surface loses pointer focus, the
request is ignored. To the client this will look like it successfully
set the pointer image.
</para>
<para>
The compositor will revert the pointer image back to a default image
when no surface has the pointer focus for that device. Clients can
revert the pointer image back to the default image by setting a NULL
image.
</para>
<para>
What if the pointer moves from one window which has set a special
pointer image to a surface that doesn't set an image in response to
the motion event? The new surface will be stuck with the special
pointer image. We can't just revert the pointer image on leaving a
surface, since if we immediately enter a surface that sets a different
image, the image will flicker. Broken app, I suppose.
</para>
</section>
<section id="sect-Protocol-Output">
<title>Output</title>
<para>
A output is a global object, advertised at connect time or as they
come and go.
</para>
<para>
See <xref linkend="protocol-spec-interface-wl_output"/> for the protocol
description.
</para>
<para>
</para>
<itemizedlist>
<listitem>
<para>
laid out in a big (compositor) coordinate system
</para>
</listitem>
<listitem>
<para>
basically xrandr over wayland
</para>
</listitem>
<listitem>
<para>
geometry needs position in compositor coordinate system
</para>
</listitem>
<listitem>
<para>
events to advertise available modes, requests to move and change
modes
</para>
</listitem>
</itemizedlist>
</section>
<section id="sect-Protocol-data-sharing">
<title>Data sharing between clients</title>
<para>
The Wayland protocol provides clients a mechanism for sharing
data that allows the implementation of copy-paste and
drag-and-drop. The client providing the data creates a
<function>wl_data_source</function> object and the clients
obtaining the data will see it as <function>wl_data_offer</function>
object. This interface allows the clients to agree on a mutually
supported mime type and transfer the data via a file descriptor
that is passed through the protocol.
</para>
<para>
The next section explains the negotiation between data source and
data offer objects. <xref linkend="sect-Protocol-data-sharing-devices"/>
explains how these objects are created and passed to different
clients using the <function>wl_data_device</function> interface
that implements copy-paste and drag-and-drop support.
</para>
<para>
See <xref linkend="protocol-spec-interface-wl_data_offer"/>,
<xref linkend="protocol-spec-interface-wl_data_source"/>,
<xref linkend="protocol-spec-interface-wl_data_device"/> and
<xref linkend="protocol-spec-interface-wl_data_device_manager"/> for
protocol descriptions.
</para>
<para>
MIME is defined in RFC's 2045-2049. A
<ulink url="ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/">
registry of MIME types</ulink> is maintained by the Internet Assigned
Numbers Authority (IANA).
</para>
<section>
<title>Data negotiation</title>
<para>
A client providing data to other clients will create a <function>wl_data_source</function>
object and advertise the mime types for the formats it supports for
that data through the <function>wl_data_source.offer</function>
request. On the receiving end, the data offer object will generate one
<function>wl_data_offer.offer</function> event for each supported mime
type.
</para>
<para>
The actual data transfer happens when the receiving client sends a
<function>wl_data_offer.receive</function> request. This request takes
a mime type and a file descriptor as arguments. This request will generate a
<function>wl_data_source.send</function> event on the sending client
with the same arguments, and the latter client is expected to write its
data to the given file descriptor using the chosen mime type.
</para>
</section>
<section id="sect-Protocol-data-sharing-devices">
<title>Data devices</title>
<para>
Data devices glue data sources and offers together. A data device is
associated with a <function>wl_seat</function> and is obtained by the clients using the
<function>wl_data_device_manager</function> factory object, which is also responsible for
creating data sources.
</para>
<para>
Clients are informed of new data offers through the
<function>wl_data_device.data_offer</function> event. After this
event is generated the data offer will advertise the available mime
types. New data offers are introduced prior to their use for
copy-paste or drag-and-drop.
</para>
<section>
<title>Selection</title>
<para>
Each data device has a selection data source. Clients create a data
source object using the device manager and may set it as the
current selection for a given data device. Whenever the current
selection changes, the client with keyboard focus receives a
<function>wl_data_device.selection</function> event. This event is
also generated on a client immediately before it receives keyboard
focus.
</para>
<para>
The data offer is introduced with
<function>wl_data_device.data_offer</function> event before the
selection event.
</para>
</section>
<section>
<title>Drag and Drop</title>
<para>
A drag-and-drop operation is started using the
<function>wl_data_device.start_drag</function> request. This
requests causes a pointer grab that will generate enter, motion and
leave events on the data device. A data source is supplied as
argument to start_drag, and data offers associated with it are
supplied to clients surfaces under the pointer in the
<function>wl_data_device.enter</function> event. The data offer
is introduced to the client prior to the enter event with the
<function>wl_data_device.data_offer</function> event.
</para>
<para>
Clients are expected to provide feedback to the data sending client
by calling the <function>wl_data_offer.accept</function> request with
a mime type it accepts. If none of the advertised mime types is
supported by the receiving client, it should supply NULL to the
accept request. The accept request causes the sending client to
receive a <function>wl_data_source.target</function> event with the
chosen mime type.
</para>
<para>
When the drag ends, the receiving client receives a
<function>wl_data_device.drop</function> event at which it is expect
to trasnfer the data using the
<function>wl_data_offer.receive</function> request.
</para>
</section>
</section>
</section>
</chapter>

7
doc/publican/sources/Revision_History.xml Normal file
View file

@ -0,0 +1,7 @@
<revhistory>
<revision>
<revnumber>1-0</revnumber>
<authorinitials>krh</authorinitials>
<revremark>Initial version</revremark>
</revision>
</revhistory>

4
doc/publican/sources/Wayland.ent Normal file
View file

@ -0,0 +1,4 @@
<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "Wayland">
<!ENTITY YEAR "2012">
<!ENTITY HOLDER "Kristian Høgsberg, Intel Corporation">

17
doc/publican/sources/Wayland.xml Normal file
View file

@ -0,0 +1,17 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
%BOOK_ENTITIES;
]>
<book>
<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Foreword.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Compositors.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Protocol.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="ProtocolSpec.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Library.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>

19
doc/publican/sources/images/icon.svg Normal file
View file

@ -0,0 +1,19 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0" width="32" height="32" id="svg3017">
<defs id="defs3019">
<linearGradient id="linearGradient2381">
<stop id="stop2383" style="stop-color:#ffffff;stop-opacity:1" offset="0"/>
<stop id="stop2385" style="stop-color:#ffffff;stop-opacity:0" offset="1"/>
</linearGradient>
<linearGradient x1="296.4996" y1="188.81061" x2="317.32471" y2="209.69398" id="linearGradient2371" xlink:href="#linearGradient2381" gradientUnits="userSpaceOnUse" gradientTransform="matrix(0.90776,0,0,0.90776,24.35648,49.24131)"/>
</defs>
<g transform="matrix(0.437808,-0.437808,0.437808,0.437808,-220.8237,43.55311)" id="g5089">
<path d="m 8.4382985,-6.28125 c -0.6073916,0 -4.3132985,5.94886271 -4.3132985,8.25 l 0,26.71875 c 0,0.846384 0.5818159,1.125 1.15625,1.125 l 25.5625,0 c 0.632342,0 1.125001,-0.492658 1.125,-1.125 l 0,-5.21875 0.28125,0 c 0.49684,0 0.906249,-0.409411 0.90625,-0.90625 l 0,-27.9375 c 0,-0.4968398 -0.40941,-0.90625 -0.90625,-0.90625 l -23.8117015,0 z" transform="translate(282.8327,227.1903)" id="path5091" style="fill:#5c5c4f;stroke:#000000;stroke-width:3.23021388;stroke-miterlimit:4;stroke-dasharray:none"/>
<rect width="27.85074" height="29.369793" rx="1.1414107" ry="1.1414107" x="286.96509" y="227.63805" id="rect5093" style="fill:#032c87"/>
<path d="m 288.43262,225.43675 25.2418,0 0,29.3698 -26.37615,0.0241 1.13435,-29.39394 z" id="rect5095" style="fill:#ffffff"/>
<path d="m 302.44536,251.73726 c 1.38691,7.85917 -0.69311,11.28365 -0.69311,11.28365 2.24384,-1.60762 3.96426,-3.47694 4.90522,-5.736 0.96708,2.19264 1.83294,4.42866 4.27443,5.98941 0,0 -1.59504,-7.2004 -1.71143,-11.53706 l -6.77511,0 z" id="path5097" style="fill:#a70000;fill-opacity:1;stroke-width:2"/>
<rect width="25.241802" height="29.736675" rx="0.89682275" ry="0.89682275" x="290.73544" y="220.92249" id="rect5099" style="fill:#809cc9"/>
<path d="m 576.47347,725.93939 6.37084,0.41502 0.4069,29.51809 c -1.89202,-1.31785 -6.85427,-3.7608 -8.26232,-1.68101 l 0,-26.76752 c 0,-0.82246 0.66212,-1.48458 1.48458,-1.48458 z" transform="matrix(0.499065,-0.866565,0,1,0,0)" id="rect5101" style="fill:#4573b3;fill-opacity:1"/>
<path d="m 293.2599,221.89363 20.73918,0 c 0.45101,0 0.8141,0.3631 0.8141,0.81411 0.21547,6.32836 -19.36824,21.7635 -22.36739,17.59717 l 0,-17.59717 c 0,-0.45101 0.3631,-0.81411 0.81411,-0.81411 z" id="path5103" style="opacity:0.65536726;fill:url(#linearGradient2371);fill-opacity:1"/>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
doc/publican/sources/images/wayland-architecture.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
doc/publican/sources/images/wayland.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.5 KiB

BIN
doc/publican/sources/images/x-architecture.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 36 KiB