Commit 6be2d9aa authored by Bill Spitzak's avatar Bill Spitzak Committed by Bryce Harrington

doc: Intro text for doxygen output in it's own file

(This patch has been modified to apply atop current master)

This makes it considerably easier to edit the text and make it different
for each library.

To address previous concerns with this patch, I wrote some more complete
introductory text. This is based on my understanding of these libraries, which
may not be correct, and is pretty rudimentary for libwayland-server!

However this intro text demonstrates how to create links to the
doxygen-generated text. It looks like you cannot link to methods easily as the
link name contains a hash number, but links to objects and classes work.
Reviewed-by: default avatarJon A. Cruz <jonc@osg.samsung.com>
Tested-by: default avatarJon A. Cruz <jonc@osg.samsung.com>
parent a4afd90f
......@@ -26,7 +26,9 @@ publican_sources = \
$(srcdir)/sources/Protocol.xml \
$(srcdir)/sources/Compositors.xml \
$(srcdir)/sources/images/icon.svg \
$(srcdir)/sources/images/wayland.png
$(srcdir)/sources/images/wayland.png \
$(srcdir)/sources/Client.xml \
$(srcdir)/sources/Server.xml
processed_sources := \
$(srcdir)/sources/Architecture.xml \
......
......@@ -4,49 +4,16 @@
<xsl:param name="which" />
<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="sect-Library-$which">
<xsl:attribute name="id">sect-Library-<xsl:value-of select="$which"/></xsl:attribute>
<title><xsl:value-of select="$which"/> API</title>
<para>
The open-source reference implementation of Wayland protocol is
split in two C libraries, <link
linkend="sect-Library-Client">libwayland-client</link> and <link
linkend="sect-Library-Server">libwayland-server</link>. Their
main responsibility is to handle the Inter-process communication
(<emphasis>IPC</emphasis>) with each other, therefore
guaranteeing the protocol objects marshaling and messages
synchronization.
</para>
<para>
Following is the Wayland library classes for the
<emphasis>libwayland-<xsl:value-of select="translate($which,
'SC', 'sc')"/></emphasis>. This appendix describes in detail
the library's methods and their helpers, aiming implementors who
are building a Wayland <xsl:value-of select="translate($which,
'SC', 'sc')"/>.
</para>
<xsl:apply-templates select="/doxygen/compounddef[@kind!='file' and @kind!='dir']" />
<section id="{$which}-Functions">
<title>Functions</title>
<para />
<variablelist>
<xsl:apply-templates select="/doxygen/compounddef[@kind='file']/sectiondef/memberdef" />
</variablelist>
</section>
<xsl:apply-templates select="/doxygen/compounddef[@kind!='file' and @kind!='dir']" />
<section id="{$which}-Functions">
<title>Functions</title>
<para />
<variablelist>
<xsl:apply-templates select="/doxygen/compounddef[@kind='file']/sectiondef/memberdef" />
</variablelist>
</section>
</appendix>
</xsl:template>
<xsl:template match="parameteritem">
......
<?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">
<!ENTITY doxygen SYSTEM "ClientAPI.xml">
%BOOK_ENTITIES;
]>
<appendix id="sect-Library-Client">
<title>Client API</title>
<section><title>Introduction</title>
<para>
The open-source reference implementation of Wayland protocol is
split in two C libraries, libwayland-client and <link
linkend="sect-Library-Server">libwayland-server</link>. Their main
responsibility is to handle the Inter-process communication
(<emphasis>IPC</emphasis>) with each other, therefore guaranteeing
the protocol objects marshaling and messages synchronization.
</para>
<para>
A client uses libwayland-client to communicate with one or more
wayland servers. A <link
linkend="Client-classwl__display">wl_display</link> object is
created and manages each open connection to a server. At least one
<link linkend="Client-classwl__event__queue">wl_event_queue</link>
object is created for each wl_display, this holds events as they
are recieved from the server until they can be
processed. Multi-threading is supported by creating an additional
wl_event_queue for each additional thread, each object can have
it's events placed in a particular queue, so potentially a
different thread could be made to handle the events for each
object created.
</para>
<para>
Though some conveinence functions are provided, libwayland-client
is designed to allow the calling code to wait for events, so that
different polling mechanisms can be used. A file descriptor is
provided, when it becomes ready for reading the calling code can
ask libwayland-client to read the available events from it into
the wl_event_queue objects.
</para>
<para>
The library only provides low-level access to the wayland objects.
Each object created by the client is represented by a <link
linkend="Client-classwl__proxy">wl_proxy</link> object that this
library creates. This includes the id that is actually
communicated over the socket to the server, a void* data pointer
that is intended to point at a client's representation of the
object, and a pointer to a static <link
linkend="Client-structwl__interface">wl_interface</link> object,
which is generated from the xml and identifies the object's class
and can be used for introspection into the messages and events.
</para>
<para>
Messages are sent by calling wl_proxy_marshal. This will write a
message to the socket, by using the message id and the
wl_interface to identify the types of each argument and convert
them into stream format. Most software will call type-safe
wrappers generated from the xml description of the <link
linkend="appe-Wayland-Protocol">Wayland protocols</link>. For
instance the C header file generated from the xml defines the
following inline function to transmit the <link
linkend="protocol-spec-wl_surface-request-attach">wl_surface::attach</link>
message:
</para>
<programlisting>static inline void
wl_surface_attach(struct wl_surface *wl_surface, struct wl_buffer *buffer, int32_t x, int32_t y)
{
wl_proxy_marshal((struct wl_proxy *) wl_surface, WL_SURFACE_ATTACH, buffer, x, y);
}</programlisting>
<para>
Events (messages from the server) are handled by calling a
"dispatcher" callback the client stores in the wl_proxy for each
event. A language binding for a string-based interpreter, such as
CPython, might have a dispatcher that uses the event name from the
wl_interface to identify the function to call. The default
dispatcher uses the message id number to index an array of
functions pointers, called a wl_listener, and the wl_interface to
convert data from the stream into arguments to the function. The
C header file generated from the xml defines a per-class structure
that forces the function pointers to be of the correct type, for
instance the <link
linkend="protocol-spec-wl_surface-event-enter">wl_surface::enter</link>
event defines this pointer in the wl_surface_listener object:
</para>
<programlisting>struct wl_surface_listener {
void (*enter)(void *data, struct wl_surface *, struct wl_output *);
...
}</programlisting>
<para>
</para>
</section>
&doxygen;
</appendix>
<?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">
<!ENTITY doxygen SYSTEM "ServerAPI.xml">
%BOOK_ENTITIES;
]>
<appendix id="sect-Library-Server">
<title>Server API</title>
<section><title>Introduction</title>
<para>
The open-source reference implementation of Wayland protocol is
split in two C libraries, <link
linkend="sect-Library-Client">libwayland-client</link> and
libwayland-server. Their main responsibility is to handle the
Inter-process communication (<emphasis>IPC</emphasis>) with each
other, therefore guaranteeing the protocol objects marshaling and
messages synchronization.
</para>
<para>
The server library is designed to work much like libwayland-client,
although it is considerably complicated due to the server needing
to support multiple versions of the protocol. It is best to learn
libwayland-client first.
</para>
<para>
Each open socket to a client is represented by a <link
linkend="Server-structwl__client">wl_client</link>. The equvalent
of the <link linkend="Client-classwl__proxy">wl_proxy</link> that
libwayland-client uses to represent an object is <link
linkend="Server-structwl__resource">wl_resource</link> for
client-created objects, and <link
linkend="Server-structwl__global">wl_global</link> for objects
created by the server.
</para>
<para>
Often a server is also a client for another Wayland server, and
thus must link with both libwayland-client and libwayland-server.
This produces some type name conflicts (such as the <link
linkend="Client-classwl__display">client wl_display</link> and
<link linkend="Server-structwl__display">server wl_display</link>,
but the duplicate-but-not-the-same types are opaque, and accessed
only inside the correct library where it came from. Naturally that
means that the program writer needs to always know if a pointer to
a wl_display is for the server or client side and use the
corresponding functions.
</para>
</section>
&doxygen;
</appendix>
......@@ -12,7 +12,6 @@
<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="ClientAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="ServerAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="Client.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</book>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment