From bbb5fa66a7fe53c492e4cc2e616c4ada38712542 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Tue, 28 Oct 2025 00:36:53 +0100 Subject: doc: Refactor the build system for complete build dir docs By structuring things differently, it becomes possible to have a complete build of the docs in the build dir, without having to install anything. Signed-off-by: Sebastian Wick --- doc/doxygen/dot/wayland-architecture.gv | 36 - doc/doxygen/dot/x-architecture.gv | 53 - doc/doxygen/meson.build | 12 - doc/doxygen/xml/Client/meson.build | 1 - doc/doxygen/xml/Server/meson.build | 1 - doc/doxygen/xml/meson.build | 20 - doc/publican/Architecture.xml | 344 ++++ doc/publican/Author_Group.xml | 16 + doc/publican/Book_Info.xml | 71 + doc/publican/Client.xml | 92 + doc/publican/Color.xml | 139 ++ doc/publican/Compositors.xml | 128 ++ doc/publican/Foreword.xml | 28 + doc/publican/Introduction.xml | 116 ++ doc/publican/Preface.xml | 20 + doc/publican/Protocol.xml | 592 +++++++ doc/publican/Revision_History.xml | 7 + doc/publican/Server.xml | 49 + doc/publican/Wayland.ent | 4 + doc/publican/Wayland.xml | 19 + doc/publican/Xwayland.xml | 170 ++ doc/publican/doxygen-to-publican.xsl | 147 -- doc/publican/html/css/brand.css | 14 + doc/publican/html/css/common.css | 1769 ++++++++++++++++++++ doc/publican/html/css/default.css | 3 + doc/publican/html/css/epub.css | 115 ++ doc/publican/html/css/meson.build | 14 + doc/publican/html/css/print.css | 15 + doc/publican/html/images/icon.svg | 19 + doc/publican/html/images/meson.build | 28 + doc/publican/html/images/wayland-architecture.gv | 36 + doc/publican/html/images/wayland.png | Bin 0 -> 5649 bytes doc/publican/html/images/x-architecture.gv | 53 + doc/publican/html/images/xwayland-architecture.png | Bin 0 -> 7611 bytes doc/publican/merge-mapcoords.xsl | 64 - doc/publican/meson.build | 106 +- doc/publican/protocol-interfaces-to-docbook.xsl | 51 - doc/publican/protocol-to-docbook.xsl | 223 --- doc/publican/sources/Architecture.xml | 344 ---- doc/publican/sources/Author_Group.xml | 16 - doc/publican/sources/Book_Info.xml | 71 - doc/publican/sources/Client.xml | 92 - doc/publican/sources/Color.xml | 139 -- doc/publican/sources/Compositors.xml | 128 -- doc/publican/sources/Foreword.xml | 28 - doc/publican/sources/Introduction.xml | 116 -- doc/publican/sources/Preface.xml | 20 - doc/publican/sources/Protocol.xml | 592 ------- doc/publican/sources/Revision_History.xml | 7 - doc/publican/sources/Server.xml | 49 - doc/publican/sources/Wayland.ent | 4 - doc/publican/sources/Wayland.xml | 19 - doc/publican/sources/Xwayland.xml | 170 -- doc/publican/sources/css/brand.css | 14 - doc/publican/sources/css/common.css | 1769 -------------------- doc/publican/sources/css/default.css | 3 - doc/publican/sources/css/epub.css | 115 -- doc/publican/sources/css/print.css | 15 - doc/publican/sources/images/icon.svg | 19 - doc/publican/sources/images/wayland.png | Bin 5649 -> 0 bytes .../sources/images/xwayland-architecture.png | Bin 7611 -> 0 bytes doc/publican/sources/meson.build | 114 -- doc/publican/xsl/doxygen-to-publican.xsl | 147 ++ doc/publican/xsl/merge-mapcoords.xsl | 64 + .../xsl/protocol-interfaces-to-docbook.xsl | 51 + doc/publican/xsl/protocol-to-docbook.xsl | 223 +++ meson.build | 6 +- 67 files changed, 4442 insertions(+), 4468 deletions(-) delete mode 100644 doc/doxygen/dot/wayland-architecture.gv delete mode 100644 doc/doxygen/dot/x-architecture.gv create mode 100644 doc/publican/Architecture.xml create mode 100644 doc/publican/Author_Group.xml create mode 100644 doc/publican/Book_Info.xml create mode 100644 doc/publican/Client.xml create mode 100644 doc/publican/Color.xml create mode 100644 doc/publican/Compositors.xml create mode 100644 doc/publican/Foreword.xml create mode 100644 doc/publican/Introduction.xml create mode 100644 doc/publican/Preface.xml create mode 100644 doc/publican/Protocol.xml create mode 100644 doc/publican/Revision_History.xml create mode 100644 doc/publican/Server.xml create mode 100644 doc/publican/Wayland.ent create mode 100644 doc/publican/Wayland.xml create mode 100644 doc/publican/Xwayland.xml delete mode 100644 doc/publican/doxygen-to-publican.xsl create mode 100644 doc/publican/html/css/brand.css create mode 100644 doc/publican/html/css/common.css create mode 100644 doc/publican/html/css/default.css create mode 100644 doc/publican/html/css/epub.css create mode 100644 doc/publican/html/css/meson.build create mode 100644 doc/publican/html/css/print.css create mode 100644 doc/publican/html/images/icon.svg create mode 100644 doc/publican/html/images/meson.build create mode 100644 doc/publican/html/images/wayland-architecture.gv create mode 100644 doc/publican/html/images/wayland.png create mode 100644 doc/publican/html/images/x-architecture.gv create mode 100644 doc/publican/html/images/xwayland-architecture.png delete mode 100644 doc/publican/merge-mapcoords.xsl delete mode 100644 doc/publican/protocol-interfaces-to-docbook.xsl delete mode 100644 doc/publican/protocol-to-docbook.xsl delete mode 100644 doc/publican/sources/Architecture.xml delete mode 100644 doc/publican/sources/Author_Group.xml delete mode 100644 doc/publican/sources/Book_Info.xml delete mode 100644 doc/publican/sources/Client.xml delete mode 100644 doc/publican/sources/Color.xml delete mode 100644 doc/publican/sources/Compositors.xml delete mode 100644 doc/publican/sources/Foreword.xml delete mode 100644 doc/publican/sources/Introduction.xml delete mode 100644 doc/publican/sources/Preface.xml delete mode 100644 doc/publican/sources/Protocol.xml delete mode 100644 doc/publican/sources/Revision_History.xml delete mode 100644 doc/publican/sources/Server.xml delete mode 100644 doc/publican/sources/Wayland.ent delete mode 100644 doc/publican/sources/Wayland.xml delete mode 100644 doc/publican/sources/Xwayland.xml delete mode 100644 doc/publican/sources/css/brand.css delete mode 100644 doc/publican/sources/css/common.css delete mode 100644 doc/publican/sources/css/default.css delete mode 100644 doc/publican/sources/css/epub.css delete mode 100644 doc/publican/sources/css/print.css delete mode 100644 doc/publican/sources/images/icon.svg delete mode 100644 doc/publican/sources/images/wayland.png delete mode 100644 doc/publican/sources/images/xwayland-architecture.png delete mode 100644 doc/publican/sources/meson.build create mode 100644 doc/publican/xsl/doxygen-to-publican.xsl create mode 100644 doc/publican/xsl/merge-mapcoords.xsl create mode 100644 doc/publican/xsl/protocol-interfaces-to-docbook.xsl create mode 100644 doc/publican/xsl/protocol-to-docbook.xsl diff --git a/doc/doxygen/dot/wayland-architecture.gv b/doc/doxygen/dot/wayland-architecture.gv deleted file mode 100644 index f2c3507..0000000 --- a/doc/doxygen/dot/wayland-architecture.gv +++ /dev/null @@ -1,36 +0,0 @@ -digraph arch_wayland { - edge[ - fontname="DejaVu Sans", - dir="both", - arrowtail="dot", - arrowsize=.5, - fontname="DejaVu Sans", - fontsize="18", - ] - - node[ - color=none, - margin=0, - fontname="DejaVu Sans", - fontsize="18", - ] - - c1 [label=<
Wayland Client
>, URL="#c1"] - c2 [label=<
Wayland Client
>, URL="#c2"] - - comp [tooltip="Wayland Compositor", label=<

Wayland
Compositor

>, URL="#comp"] - - impl [tooltip="KMS evdev Kernel", label=<
KMSevdev
Kernel
>, URL="#impl"] - - c1 -> comp [taillabel="③", labeldistance=2.5, URL="#step_3"]; - c2 -> comp; - - comp -> c1 [label="②", URL="#step_2"]; - comp -> c2; - - comp -> impl [xlabel = "④", URL="#step_4"]; - comp -> impl [style = invis, label=" "]; - impl -> comp [xlabel = "①", URL="#step_1"]; - - c1 -> c2 [style=invis]; -} diff --git a/doc/doxygen/dot/x-architecture.gv b/doc/doxygen/dot/x-architecture.gv deleted file mode 100644 index b223d1d..0000000 --- a/doc/doxygen/dot/x-architecture.gv +++ /dev/null @@ -1,53 +0,0 @@ -digraph arch_x { - edge[ - fontname="DejaVu Sans", - dir="both", - arrowtail="dot", - arrowsize=.5, - fontname="DejaVu Sans", - fontsize="18", - ] - - node[ - shape="none", - color=none, - margin=0, - fontname="DejaVu Sans", - fontsize="18", - ] - - { - rank=same; - c1 [label=<
X Client
>, URL="#c1"] - c3 [label=<
X Client
>, URL="#c3"] - } - c2 [label=<
X Client
>, URL="#c2"] - - { - rank=same; - xserver [tooltip="X Server", label=<

X Server

>, URL="#xserver"] - comp [tooltip="Compositor", label=<

Compositor

>, URL="#comp"] - } - - impl [tooltip="KMS evdev Kernel", label=<
KMSevdev
Kernel
>, URL="#impl"] - - c1 -> xserver [taillabel="③", labeldistance=2, URL="#step_3"]; - c2 -> xserver; - c3 -> xserver; - - xserver -> c1 [taillabel="②", labeldistance=2, URL="#step_2"]; - xserver -> c2; - xserver -> c3; - - xserver -> impl [taillabel="⑥", labeldistance=1.75, URL="#step_6"]; - xserver -> impl [style=invis, label=" "]; - impl -> xserver [taillabel="①", labeldistance=1.75, URL="#step_1"]; - - xserver -> comp [style=invis]; - xserver -> comp [taillabel="④", labeldistance=1.75, labelangle=-45, URL="#step_4"]; - comp -> xserver [taillabel="⑤", URL="#step_5"]; - comp -> xserver [style=invis] - - c1 -> c2 [style=invis]; - c3 -> c2 [style=invis]; - } diff --git a/doc/doxygen/meson.build b/doc/doxygen/meson.build index 6112620..551bd4b 100644 --- a/doc/doxygen/meson.build +++ b/doc/doxygen/meson.build @@ -1,16 +1,5 @@ # Here be dragons -dot_gv = { - 'wayland-architecture': files('dot/wayland-architecture.gv'), - 'x-architecture': files('dot/x-architecture.gv'), -} - -# This is a workaround for Meson's custom_target() directive, which -# currently does not support outputs pointing to a sub-directory -# XXX: try turning these into maps, so they can be indexed with picture name -dot_png = [] -dot_map = [] - doxygen_conf = configuration_data() doxygen_conf.set('VERSION', meson.project_version()) doxygen_conf.set('top_builddir', meson.project_build_root()) @@ -91,7 +80,6 @@ foreach f_name, sections: formats ], input: s_files, output: '@0@.stamp'.format(t_name), - depends: [dot_png, dot_map], build_by_default: true, ) endforeach diff --git a/doc/doxygen/xml/Client/meson.build b/doc/doxygen/xml/Client/meson.build index 849c30d..e51fccb 100644 --- a/doc/doxygen/xml/Client/meson.build +++ b/doc/doxygen/xml/Client/meson.build @@ -11,7 +11,6 @@ tgt = custom_target( ], input: [ shared_files, client_files ], output: [ 'combine.xslt', 'index.xml' ], - depends: [dot_png, dot_map] ) doxygen_Client_combine_xslt = tgt[0] diff --git a/doc/doxygen/xml/Server/meson.build b/doc/doxygen/xml/Server/meson.build index 4792c1b..5df9744 100644 --- a/doc/doxygen/xml/Server/meson.build +++ b/doc/doxygen/xml/Server/meson.build @@ -11,7 +11,6 @@ tgt = custom_target( ], input: [ shared_files, server_files ], output: [ 'combine.xslt', 'index.xml' ], - depends: [dot_png, dot_map] ) doxygen_Server_combine_xslt = tgt[0] diff --git a/doc/doxygen/xml/meson.build b/doc/doxygen/xml/meson.build index 6d55c53..479af8e 100644 --- a/doc/doxygen/xml/meson.build +++ b/doc/doxygen/xml/meson.build @@ -1,22 +1,2 @@ -# dot_png: list of PNG targets -# dot_map: list of MAP targets -foreach name, infile: dot_gv - dot_png += custom_target( - name + '.png', - command: [ dot, '-Tpng', '-o@OUTPUT@', '@INPUT@' ], - input: infile, - output: name + '.png', - install: true, - install_dir: join_paths(publican_install_prefix, publican_html_dir, 'images') - ) - - dot_map += custom_target( - name + '.map', - command: [ dot, '-Tcmapx_np', '-o@OUTPUT@', '@INPUT@' ], - input: infile, - output: name + '.map', - ) -endforeach - subdir('Client') subdir('Server') diff --git a/doc/publican/Architecture.xml b/doc/publican/Architecture.xml new file mode 100644 index 0000000..b8a104c --- /dev/null +++ b/doc/publican/Architecture.xml @@ -0,0 +1,344 @@ + + +%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: + +
+ X architecture diagram + + + + + + + + + + + + + + + +
+ + + + + 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: + +
+ Wayland architecture diagram + + + + + + + + + + + + + +
+ + + + + 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 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. + +
+
+ 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/publican/Author_Group.xml b/doc/publican/Author_Group.xml new file mode 100644 index 0000000..2bdde62 --- /dev/null +++ b/doc/publican/Author_Group.xml @@ -0,0 +1,16 @@ + + +%BOOK_ENTITIES; +]> + + + Kristian + Høgsberg + + Intel Corporation + + krh@bitplanet.net + + + diff --git a/doc/publican/Book_Info.xml b/doc/publican/Book_Info.xml new file mode 100644 index 0000000..897673a --- /dev/null +++ b/doc/publican/Book_Info.xml @@ -0,0 +1,71 @@ + + +%BOOK_ENTITIES; +]> + + Wayland + The Wayland Protocol + Documentation + 0.1 + 1 + 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. + + + + + + + + + + Wayland logo + + + + + + + + Copyright &YEAR; &HOLDER; + + + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + + + + + + diff --git a/doc/publican/Client.xml b/doc/publican/Client.xml new file mode 100644 index 0000000..19bf3e9 --- /dev/null +++ b/doc/publican/Client.xml @@ -0,0 +1,92 @@ + + + +%BOOK_ENTITIES; +]> + + Client API +
Introduction + + The open-source reference implementation of Wayland protocol is + split in two C libraries, libwayland-client and libwayland-server. Their main + responsibility is to handle the Inter-process communication + (IPC) with each other, therefore guaranteeing + the protocol objects marshaling and messages synchronization. + + + A client uses libwayland-client to communicate with one or more + wayland servers. A wl_display object is + created and manages each open connection to a server. At least one + wl_event_queue + object is created for each wl_display, this holds events as they + are received 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. + + + Though some convenience 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. + + + The library only provides low-level access to the wayland objects. + Each object created by the client is represented by a wl_proxy 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 wl_interface object, + which is generated from the xml and identifies the object's class + and can be used for introspection into the messages and events. + + + 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 Wayland protocols. For + instance the C header file generated from the xml defines the + following inline function to transmit the wl_surface::attach + message: + + 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); +} + + 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 wl_surface::enter + event defines this pointer in the wl_surface_listener object: + + struct wl_surface_listener { + void (*enter)(void *data, struct wl_surface *, struct wl_output *); + ... +} + + +
+ &doxygen; + diff --git a/doc/publican/Color.xml b/doc/publican/Color.xml new file mode 100644 index 0000000..ceee779 --- /dev/null +++ b/doc/publican/Color.xml @@ -0,0 +1,139 @@ + + +%BOOK_ENTITIES; +]> + + + Color management + +
+ Overview + + + Color management in Wayland considers only displays. All pictures in + Wayland are always display-referred, meaning that the pixel values are + intended as-is for some specific display where they would produce the + light emissions (stimuli) the picture's + author desired. Wayland does not support displaying "raw" camera or + scanner images as they are not display-referred, nor are they even + pictures without complex and subjective processing. + + + Stimuli — the picture itself — are only half of the picture reproduction. + The other half is the environment where a display is viewed. A striking + example is comparing a brightly lit office to a dark movie theater, the + stimuli required to produce a good reading of the picture is greatly + different. Therefore display-referred does not include only the display + but the viewing environment as well. + + + Window systems have been very well capable of operating without any + explicit consideration to color management. This is because there used to + be the implicit assumption of the standard display, the sRGB display, + which all computer monitors implemented, more or less. The viewing + environment was and still is accounted by adjusting the display and/or the + room to produce a workable experience. Pictures are authored on a computer + system by drawing, painting and adjusting the picture until it looks right + on the author's monitor. This implicitly builds the standard display and + environment assumption into the picture data. Deviations from the sRGB + specification were minor enough that they often did not matter if not in a + professional context like the printing industry. Displaying video material + required some more attention to the details, because video and television + standards differ enough from the sRGB display. What really made explicit + color management a hard requirement for entertainment is the coming of + wide color gamut (WCG) and high dynamic range (HDR) materials and + displays. + + + The color management design in Wayland follows the general Wayland design + principles: compositors tell clients what would be the optimal thing to + do, clients tell the compositors what kind of pictures they are actually + producing, and then compositors display those pictures the best they can. + +
+ +
+ Protocol Interfaces + + + Color management interfaces in Wayland and divided into two protocols: + color-management + and + color-representation. + They are designed to work together, but they can also be used + independently when the other one is not needed. + + +
+ Color-management + + + Color management protocol has two main purposes. First, it puts the + responsibility of color management on the compositor. This means that + clients do not necessarily need to care about color management at all, + and can display just fine by using the traditional standard display + assumption even when the actual display is wildly different. Clients + can also choose to target some other assumed display and let the + compositor handle it, or they can explicitly render for the actual + display at hand. Second, when the window system has multiple different + monitors, and a wl_surface happens to span more than one monitor, the + compositor can display the surface content correctly on all spanned + monitors simultaneously, as much as physically possible. + + + Color-management protocol concentrates on colorimetry: when you have a + pixel with RGB values, what stimulus do those values represent. The + stimulus definition follows the CIE 1931 two-degree observer model. Some + core concepts here are color primaries, white point, transfer function, + and dynamic range. The viewing environment is represented in an + extremely simplified way as the reference white luminance. The + connection between pixel RGB values and stimulus plus viewing + environment is recorded in an image description + object. Clients can create image description objects and tag + wl_surfaces with them, to indicate what kind of surface + content there will be. Clients can also ask what image description the + compositor would prefer to have on the wl_surface, and that + preference can change over time, e.g. when the wl_surface + is moved from one + wl_output to another. Following the compositor's preference + may provide advantages in image quality and power consumption. + + + Image description objects can come in two flavors: parametric and + ICC-based. The above was written with parametric image descriptions in + mind, and they have first-class support for HDR. ICC-based image + descriptions are wrapping an ICC profile and have no other data. ICC + profiles are the standard tool for standard dynamic range (SDR) display + color management. This means the capabilities between the two flavors + differ, and one cannot always be replaced by the other. Compositor + support for each flavor is optional. + +
+ +
+ Color-representation + + + Color-representation protocol deals with (potentially sub-sampled) + YCbCr-RGB conversion, quantization range, and the inclusion of alpha in + the RGB color channels, a.k.a. pre-multiplication. There are several + different specifications on how an YCbCr-like (including ICtCp) signal, + with chroma sub-sampling or not, is created from a full-resolution RGB + image. Again, a client can tag a wl_surface with + color-representation metadata to tell the compositor what kind of pixel + data will be displayed through the wl_surface. + + + The main purpose of color-representation is to correctly off-load the + YCbCr-RGB conversion to the compositor, which can then opportunistically + off-load it further to very power-efficient fixed-function circuitry in + a display controller. This can significantly reduce power consumption + when watching videos compared to using a GPU for the same, and on some + embedded hardware platforms it is a hard requirement for processing high + resolution video. + +
+
+ diff --git a/doc/publican/Compositors.xml b/doc/publican/Compositors.xml new file mode 100644 index 0000000..7a7bdaa --- /dev/null +++ b/doc/publican/Compositors.xml @@ -0,0 +1,128 @@ + + +%BOOK_ENTITIES; +]> + + Types of Compositors + + + Compositors come in different types, depending on which + role they play in the overall architecture of the OS. + For instance, a + system compositor + can be used for booting the system, handling multiple user switching, a + possible console terminal emulator and so forth. A different compositor, a + session compositor + would provide the actual desktop environment. There are many ways for + different types of compositors to co-exist. + + + In this section, we introduce three types of Wayland compositors relying + on libwayland-server. + + +
+ System Compositor + + 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. + + + 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). + + + A linux implementation of a system compositor will typically + use libudev, egl, kms, evdev and cairo. + + + For fullscreen clients, the system compositor can reprogram the + video scanout address to read directly from the client provided + buffer. + +
+
+ Session Compositor + + 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 hardware. + + + X applications can continue working under a session compositor + by means of a root-less X server that is activated on demand. + + + Possible examples for session compositors include + + + + gnome-shell + + + + + moblin + + + + + kwin + + + + + kmscon + + + + + rdp session + + + + + Weston with X11 or Wayland backend is a session compositor nested + in another session compositor. + + + + + fullscreen X session under Wayland + + + + +
+
+ Embedding Compositor + + 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. + + + An example for this kind of setup is firefox embedding the flash + player as a kind of special-purpose compositor. + +
+ diff --git a/doc/publican/Foreword.xml b/doc/publican/Foreword.xml new file mode 100644 index 0000000..46fda2b --- /dev/null +++ b/doc/publican/Foreword.xml @@ -0,0 +1,28 @@ + + +%BOOK_ENTITIES; +]> + + + Preface + + + This document describes the (i) Wayland architecture, (ii) Wayland model of + operation and (iii) its library API. Also, the Wayland protocol specification is shown + in the Appendix. This document is aimed primarily at Wayland developers and + those looking to program with it; it does not cover application development. + + + There have been many contributors to this document and since this is only the + first edition many errors are expected to be found. We appreciate + corrections. + + +Yours, + + the Wayland open-source community + November 2012 + + diff --git a/doc/publican/Introduction.xml b/doc/publican/Introduction.xml new file mode 100644 index 0000000..f2a8274 --- /dev/null +++ b/doc/publican/Introduction.xml @@ -0,0 +1,116 @@ + + +%BOOK_ENTITIES; +]> + + Introduction +
+ Motivation + + Most Linux and Unix-based systems rely on the X Window System (or + simply X) 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). + + + 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. + + + + + + + + X architecture diagram + + + + + 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. + + +
+ +
+ The compositing manager as the display server + + 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 are displayed. Rendering is left + to clients, and system wide memory management interfaces are used to + pass buffer handles between clients and the compositing manager. + + + + + + + + Wayland architecture diagram + + + + + 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). + +
+ diff --git a/doc/publican/Preface.xml b/doc/publican/Preface.xml new file mode 100644 index 0000000..17c6ebf --- /dev/null +++ b/doc/publican/Preface.xml @@ -0,0 +1,20 @@ + + +%BOOK_ENTITIES; +]> + + + Acknowledgments + + + TODO: Kristian has to fill up this with one or two paragraphs and a small + "thank you": http://en.wikipedia.org/wiki/Preface + + +Best, + + Kristian Høgsberg + + diff --git a/doc/publican/Protocol.xml b/doc/publican/Protocol.xml new file mode 100644 index 0000000..e4087e9 --- /dev/null +++ b/doc/publican/Protocol.xml @@ -0,0 +1,592 @@ + + +%BOOK_ENTITIES; +]> + + Wayland Protocol and Model of Operation +
+ Basic Principles + + 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. + + + 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. + A message has a number of arguments, each of which has a certain type (see + for a list of argument types). + + + Additionally, the protocol can specify enums which associate + names to specific numeric enumeration values. These are primarily just + descriptive in nature: at the wire format level enums are just integers. + But they also serve a secondary purpose to enhance type safety or + otherwise add context for use in language bindings or other such code. + This latter usage is only supported so long as code written before these + attributes were introduced still works after; in other words, adding an + enum should not break API, otherwise it puts backwards compatibility at + risk. + + + enums can be defined as just a set of integers, or as + bitfields. This is specified via the bitfield boolean + attribute in the enum definition. If this attribute is true, + the enum is intended to be accessed primarily using bitwise operations, + for example when arbitrarily many choices of the enum can be ORed + together; if it is false, or the attribute is omitted, then the enum + arguments are a just a sequence of numerical values. + + + The enum attribute can be used on either uint + or int arguments, however if the enum is + defined as a bitfield, it can only be used on + uint args. + + + 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. + + + + + + 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. + + + + + The server will broadcast the presence of a number of global objects, + which in turn will broadcast their current state. + + + + +
+
+ Code Generation + + The interfaces, requests and events are defined in + protocol/wayland.xml. + 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 + wrap the 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. + +
+
+ Wire Format + + The protocol is sent over a UNIX domain stream socket, where the endpoint + usually is named wayland-0 + (although it can be changed via WAYLAND_DISPLAY + in the environment). Beginning in Wayland 1.15, implementations can + optionally support server socket endpoints located at arbitrary + locations in the filesystem by setting WAYLAND_DISPLAY + to the absolute path at which the server endpoint listens. The socket may + also be provided through file descriptor inheritance, in which case + WAYLAND_SOCKET is set. + + + Every message is structured as 32-bit words; values are represented in the + host's byte-order. The message header has 2 words in it: + + + + The first word is the sender's object ID (32-bit). + + + + + 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. + + + + 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. + + + + The representation of argument types are as follows: + + + int + uint + + + The value is the 32-bit value of the signed/unsigned + int. + + + + + fixed + + + 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. + + + + + string + + + Starts with an unsigned 32-bit length (including null terminator), + followed by the UTF-8 encoded string contents, including + terminating null byte, then padding to a 32-bit boundary. A null + value is represented with a length of 0. Interior null bytes are + not permitted. + + + + + object + + + 32-bit object ID. A null value is represented with an ID of 0. + + + + + new_id + + + The 32-bit object ID. Generally, the interface used for the new + object is inferred from the xml, but in the case where it's not + specified, a new_id is preceded by a string specifying + the interface name, and a uint specifying the version. + + + + + array + + + Starts with 32-bit array size in bytes, followed by the array + contents verbatim, and finally padding to a 32-bit boundary. + + + + + fd + + + The file descriptor is not stored in the message buffer, but in + the ancillary data of the UNIX domain socket message (msg_control). + + + + + + + The protocol does not specify the exact position of the ancillary data + in the stream, except that the order of file descriptors is the same as + the order of messages and fd arguments within messages on + the wire. + + + In particular, it means that any byte of the stream, even the message + header, may carry the ancillary data with file descriptors. + + + Clients and compositors should queue incoming data until they have + whole messages to process, as file descriptors may arrive earlier + or later than the corresponding data bytes. + +
+ +
+ Versioning + + Every interface is versioned and every protocol object implements a + particular version of its interface. For global objects, the maximum + version supported by the server is advertised with the global and the + actual version of the created protocol object is determined by the + version argument passed to wl_registry.bind(). For objects that are + not globals, their version is inferred from the object that created + them. + + + In order to keep things sane, this has a few implications for + interface versions: + + + + The object creation hierarchy must be a tree. Otherwise, + inferring object versions from the parent object becomes a much + more difficult to properly track. + + + + + When the version of an interface increases, so does the version + of its parent (recursively until you get to a global interface) + + + + + A global interface's version number acts like a counter for all + of its child interfaces. Whenever a child interface gets + modified, the global parent's interface version number also + increases (see above). The child interface then takes on the + same version number as the new version of its parent global + interface. + + + + + + To illustrate the above, consider the wl_compositor interface. It + has two children, wl_surface and wl_region. As of wayland version + 1.2, wl_surface and wl_compositor are both at version 3. If + something is added to the wl_region interface, both wl_region and + wl_compositor will get bumpped to version 4. If, afterwards, + wl_surface is changed, both wl_compositor and wl_surface will be at + version 5. In this way the global interface version is used as a + sort of "counter" for all of its child interfaces. This makes it + very simple to know the version of the child given the version of its + parent. The child is at the highest possible interface version that + is less than or equal to its parent's version. + + + It is worth noting a particular exception to the above versioning + scheme. The wl_display (and, by extension, wl_registry) interface + cannot change because it is the core protocol object and its version + is never advertised nor is there a mechanism to request a different + version. + +
+
+ Connect Time + + 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. + +
+
+ Security and Authentication + + + + + mostly about access to underlying buffers, need new drm auth + mechanism (the grant-to ioctl idea), need to check the cmd stream? + + + + + 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. + + + + +
+
+ Creating Objects + + Each object has a unique ID. The IDs are allocated by the entity + creating the object (either client or server). IDs allocated by the + client are in the range [1, 0xfeffffff] while IDs allocated by the + server are in the range [0xff000000, 0xffffffff]. The 0 ID is + reserved to represent a null or non-existent object. + + For efficiency purposes, the IDs are densely packed in the sense that + the ID N will not be used until N-1 has been used. This ordering is + not merely a guideline, but a strict requirement, and there are + implementations of the protocol that rigorously enforce this rule, + including the ubiquitous libwayland. + +
+
+ Compositor + + The compositor is a global object, advertised at connect time. + + + See for the + protocol description. + +
+
+ Surfaces + + A surface manages a rectangular grid of pixels that clients create + for displaying their content to the screen. Clients don't know + the global position of their surfaces, and cannot access other + clients' surfaces. + + + Once the client has finished writing pixels, it 'commits' the + buffer; this permits the compositor to access the buffer and read + the pixels. When the compositor is finished, it releases the + buffer back to the client. + + + See for the protocol + description. + +
+
+ Input + + 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. + + + 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. + + + 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. + + + 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. + + + See for the + protocol description. + + + Talk about: + + + + + keyboard map, change events + + + + + xkb on Wayland + + + + + multi pointer Wayland + + + + + + 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 to 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 or 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. + + + Setting the pointer image to NULL causes the cursor to be hidden. + + + The compositor will revert the pointer image back to a default image + when no surface has the pointer focus for that device. + + + 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. If a client does not set a pointer image + when the pointer enters a surface, the pointer stays with the image set + by the last surface that changed it, possibly even hidden. Such a client + is likely just broken. + +
+
+ Output + + An output is a global object, advertised at connect time or as it + comes and goes. + + + See for the protocol + description. + + + + + + + laid out in a big (compositor) coordinate system + + + + + basically xrandr over Wayland + + + + + geometry needs position in compositor coordinate system + + + + + events to advertise available modes, requests to move and change + modes + + + +
+
+ Data sharing between clients + + 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 + wl_data_source object and the clients + obtaining the data will see it as wl_data_offer + 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. + + + The next section explains the negotiation between data source and + data offer objects. + explains how these objects are created and passed to different + clients using the wl_data_device interface + that implements copy-paste and drag-and-drop support. + + + See , + , + and + for + protocol descriptions. + + + MIME is defined in RFC's 2045-2049. A + + registry of MIME types is maintained by the Internet Assigned + Numbers Authority (IANA). + +
+ Data negotiation + + A client providing data to other clients will create a wl_data_source + object and advertise the mime types for the formats it supports for + that data through the wl_data_source.offer + request. On the receiving end, the data offer object will generate one + wl_data_offer.offer event for each supported mime + type. + + + The actual data transfer happens when the receiving client sends a + wl_data_offer.receive request. This request takes + a mime type and a file descriptor as arguments. This request will generate a + wl_data_source.send 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. + +
+
+ Data devices + + Data devices glue data sources and offers together. A data device is + associated with a wl_seat and is obtained by the clients using the + wl_data_device_manager factory object, which is also responsible for + creating data sources. + + + Clients are informed of new data offers through the + wl_data_device.data_offer 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. + +
+ Selection + + 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 + wl_data_device.selection event. This event is + also generated on a client immediately before it receives keyboard + focus. + + + The data offer is introduced with + wl_data_device.data_offer event before the + selection event. + +
+
+ Drag and Drop + + A drag-and-drop operation is started using the + wl_data_device.start_drag 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 + wl_data_device.enter event. The data offer + is introduced to the client prior to the enter event with the + wl_data_device.data_offer event. + + + Clients are expected to provide feedback to the data sending client + by calling the wl_data_offer.accept 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 wl_data_source.target event with the + chosen mime type. + + + When the drag ends, the receiving client receives a + wl_data_device.drop event at which it is expected + to transfer the data using the + wl_data_offer.receive request. + +
+
+
+ diff --git a/doc/publican/Revision_History.xml b/doc/publican/Revision_History.xml new file mode 100644 index 0000000..2c540fe --- /dev/null +++ b/doc/publican/Revision_History.xml @@ -0,0 +1,7 @@ + + + 1-0 + krh + Initial version + + diff --git a/doc/publican/Server.xml b/doc/publican/Server.xml new file mode 100644 index 0000000..2333b1a --- /dev/null +++ b/doc/publican/Server.xml @@ -0,0 +1,49 @@ + + + +%BOOK_ENTITIES; +]> + + Server API +
Introduction + + The open-source reference implementation of Wayland protocol is + split in two C libraries, libwayland-client and + libwayland-server. Their main responsibility is to handle the + Inter-process communication (IPC) with each + other, therefore guaranteeing the protocol objects marshaling and + messages synchronization. + + + 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. + + + Each open socket to a client is represented by a wl_client. The equivalent + of the wl_proxy that + libwayland-client uses to represent an object is wl_resource for + client-created objects, and wl_global for objects + created by the server. + + + 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 client wl_display and + server wl_display, + 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. + +
+ &doxygen; + diff --git a/doc/publican/Wayland.ent b/doc/publican/Wayland.ent new file mode 100644 index 0000000..da18a95 --- /dev/null +++ b/doc/publican/Wayland.ent @@ -0,0 +1,4 @@ + + + + diff --git a/doc/publican/Wayland.xml b/doc/publican/Wayland.xml new file mode 100644 index 0000000..7593097 --- /dev/null +++ b/doc/publican/Wayland.xml @@ -0,0 +1,19 @@ + + +%BOOK_ENTITIES; +]> + + + + + + + + + + + + + + diff --git a/doc/publican/Xwayland.xml b/doc/publican/Xwayland.xml new file mode 100644 index 0000000..7915559 --- /dev/null +++ b/doc/publican/Xwayland.xml @@ -0,0 +1,170 @@ + + +%BOOK_ENTITIES; +]> + + X11 Application Support +
+ Introduction + + Being able to run existing X11 applications is crucial for the adoption + of Wayland, especially on desktops, as there will always be X11 + applications that have not been or cannot be converted into Wayland + applications, and throwing them all away would be prohibitive. + Therefore a Wayland compositor often needs to support running X11 + applications. + + + X11 and Wayland are different enough that there is no "simple" way to + translate between them. Most of X11 is uninteresting to a Wayland + compositor. That, combined with the gigantic implementation effort needed + to support X11, makes it intractable to just write X11 support directly in + a Wayland compositor. The implementation would be nothing short of a + real X11 server. + + + Therefore, Wayland compositors should use Xwayland, the X11 server that + lives in the Xorg server source code repository and shares most of the + implementation with the Xorg server. Xwayland is a complete X11 server, + just like Xorg is, but instead of driving the displays and opening input + devices, it acts as a Wayland client. The rest of this chapter talks + about how Xwayland works. + + + For integration and architecture reasons, while Xwayland is a Wayland + client of the Wayland compositor, the Wayland compositor is an X11 client + of Xwayland. This circular dependency requires special care from the + Wayland compositor. + +
+
+ Two Modes for Foreign Windows + + In general, windows from a foreign window system can be presented in one + of two ways: rootless and rootful (not rootless). + + + In rootful mode, the foreign window system as a whole is represented as a + window (or more) of its own. You have a native window, inside which all + the foreign windows are. The advantage of this approach in Xwayland's + case is that you can run your favourite X11 window manager to manage your + X11 applications. The disadvantage is that the foreign windows do not + integrate with the native desktop. Therefore this mode is not usually + used. + + + In rootless mode, each foreign window is a first-class resident among the + native windows. Foreign windows are not confined inside a native window + but act as if they were native windows. The advantage is that one can + freely stack and mix native and foreign windows, which is not possible in + rootful mode. The disadvantage is that this mode is harder to implement + and fundamental differences in window systems may prevent some things + from working. With rootless Xwayland, the Wayland compositor must take + the role as the X11 window manager, and one cannot use any other X11 + window manager in its place. + + + This chapter concentrates on the rootless mode, and ignores the rootful + mode. + +
+
+ Architecture + + A Wayland compositor usually takes care of launching Xwayland. + Xwayland works in cooperation with a Wayland compositor as follows: + +
+ Xwayland architecture diagram + + + + + + + +
+ + An X11 application connects to Xwayland just like it would connect to any + X server. Xwayland processes all the X11 requests. On the other end, + Xwayland is a Wayland client that connects to the Wayland compositor. + + + The X11 window manager (XWM) is an integral part of the Wayland + compositor. XWM uses the usual X11 window management protocol to manage + all X11 windows in Xwayland. Most importantly, XWM acts as a bridge + between Xwayland window state and the Wayland compositor's window manager + (WWM). This way WWM can manage all windows, both native Wayland and X11 + (Xwayland) windows. This is very important for a coherent user + experience. + + + Since Xwayland uses Wayland for input and output, it does not have any + use for the device drivers that Xorg uses. None of the xf86-video-* or + xf86-input-* modules are used. There also is no configuration file for + the Xwayland server. For optional hardware accelerated rendering, + Xwayland uses GLAMOR. + + + A Wayland compositor usually spawns only one Xwayland instance. This is + because many X11 applications assume they can communicate with other X11 + applications through the X server, and this requires a shared X server + instance. This also means that Xwayland does not protect nor isolate X11 + clients from each other, unless the Wayland compositor specifically + chooses to break the X11 client intercommunications by spawning + application specific Xwayland instances. X11 clients are naturally + isolated from Wayland clients. + + + Xwayland compatibility compared to a native X server will probably never + reach 100%. Desktop environment (DE) components, specifically X11 window + managers, are practically never supported. An X11 window manager would + not know about native Wayland windows, so it could manage only X11 + windows. On the other hand, there must be an XWM that reserves the + exclusive window manager role so that the Wayland compositor could show + the X11 windows appropriately. For other DE components, like pagers and + panels, adding the necessary interfaces to support them in WWM through XWM + is often considered not worthwhile. + +
+
+ X Window Manager (XWM) + + From the X11 point of view, the X window manager (XWM) living inside a + Wayland compositor is just like any other window manager. The difference + is mostly in which process it resides in, and the few extra conventions + in the X11 protocol to support Wayland window management (WWM) + specifically. + + + There are two separate asynchronous communication channels between + Xwayland and a Wayland compositor: one uses the Wayland protocol, and the + other one, solely for XWM, uses X11 protocol. This setting demands great + care from the XWM implementation to avoid (random) deadlocks with + Xwayland. It is often nearly impossible to prove that synchronous or + blocking X11 calls from XWM cannot cause a deadlock, and therefore it is + strongly recommended to make all X11 communications asynchronous. All + Wayland communications are already asynchronous by design. + +
+ Window identification + + In Xwayland, an X11 window may have a corresponding wl_surface object + in Wayland. The wl_surface object is used for input and output: it is + referenced by input events and used to provide the X11 window content + to the Wayland compositor. The X11 window and the wl_surface live in + different protocol streams, and they need to be matched for XWM to do + its job. + + + When Xwayland creates a wl_surface on Wayland, it will also send an X11 + ClientMessage of type atom "WL_SURFACE_ID" to the X11 window carrying + the wl_surface Wayland object ID as the first 32-bit data element. This + is how XWM can associate a wl_surface with an X11 window. Note that + the request to create a wl_surface and the ID message may arrive in any + order in the Wayland compositor. + +
+
+ diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl deleted file mode 100644 index e13dcd7..0000000 --- a/doc/publican/doxygen-to-publican.xsl +++ /dev/null @@ -1,147 +0,0 @@ - - - - - - - - -
- Functions - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Returns: - - - - - - - - - See also: - - - - Since: - - - - Note: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - <xsl:value-of select="compoundname" /> - <xsl:if test="normalize-space(briefdescription) != ''"> - - <xsl:apply-templates select="briefdescription" /> - </xsl:if> - - - - - - - - - - - - - - -
- - diff --git a/doc/publican/html/css/brand.css b/doc/publican/html/css/brand.css new file mode 100644 index 0000000..d86cba9 --- /dev/null +++ b/doc/publican/html/css/brand.css @@ -0,0 +1,14 @@ +/*headings*/ +h1, h2, h3, h4, h5, h6, +div.producttitle, +div.subtitle, +div.author div.author, +div.translator div.translator, +div.othercredit div.othercredit, +div.editor div.editor, +div.contrib div.contrib, +.title, +.titlepage .edition, +.titlepage .releaseinfo { + color: #336699; +} diff --git a/doc/publican/html/css/common.css b/doc/publican/html/css/common.css new file mode 100644 index 0000000..a05648e --- /dev/null +++ b/doc/publican/html/css/common.css @@ -0,0 +1,1769 @@ +* { + widows: 4 !important; + orphans: 4 !important; +} + +body, h1, h2, h3, h4, h5, h6, pre, li, div { + line-height: 1.29em; +} + +body { + background-color: white; + margin:0 auto; + font-family: "liberation sans", "Myriad ", "Bitstream Vera Sans", "Lucida Grande", "Luxi Sans", "Trebuchet MS", helvetica, verdana, arial, sans-serif; + font-size: 14px; + max-width: 770px; + color: black; +} + +body.toc_embeded { + /*for web hosting system only*/ + margin-left: 300px; +} + +object.toc, iframe.toc { + /*for web hosting system only*/ + border-style: none; + position: fixed; + width: 290px; + height: 99.99%; + top: 0; + left: 0; + z-index: 100; + border-style: none; + border-right:1px solid #999; +} + +/* Hide web menu */ + +body.notoc { + margin-left: 3em; +} + +iframe.notoc { + border-style:none; + border: none; + padding: 0px; + position:fixed; + width: 21px; + height: 29px; + top: 0px; + left:0; + overflow: hidden; + margin: 0px; + margin-left: -3px; +} +/* End hide web menu */ + +/* desktop styles */ +body.desktop { + margin-left: 26em; +} + +body.desktop .book > .toc { + display:block; + width:24em; + height:99.99%; + position:fixed; + overflow:auto; + top:0px; + left:0px; +/* padding-left:1em; */ + background-color:#EEEEEE; + font-size: 12px; +} + +body.pdf { + max-width: 100%; +} + +.toc { + line-height:1.35em; +} + +.toc .glossary, +.toc .chapter, .toc .appendix { + margin-top:1em; +} + +.toc .part { + margin-top:1em; + display:block; +} + +span.glossary, +span.appendix { + display:block; + margin-top:0.5em; +} + +div { + padding-top:0px; +} + +div.section { + page-break-inside: avoid; +} + +p, div.para { + padding-top: 0px; + margin-top: 1em; + padding-bottom: 0px; + margin-bottom: 1em; +} + +div.formalpara { + padding-top: 0px; + margin-top: 1em; + padding-bottom: 0px; + margin-bottom: 1em; +} + +.varlistentry div.para { + page-break-before: avoid; + +} + +/*Links*/ +a { + outline: none; +} + +a:link { + text-decoration: none; + border-bottom: 1px dotted ; + color:#3366cc; +} + +body.pdf a:link { + word-wrap: break-word; +} + +a:visited { + text-decoration:none; + border-bottom: 1px dotted ; + color:#003366; +} + +div.longdesc-link { + float:right; + color:#999; +} + +.toc a, .qandaset a { + font-weight:normal; + border:none; +} + +.toc a:hover, .qandaset a:hover +{ + border-bottom: 1px dotted; +} + +/*headings*/ +h1, h2, h3, h4, h5, h6 { + color: #336699; + margin-top: 0px; + margin-bottom: 0px; + background-color: transparent; + margin-bottom: 0px; + margin-top: 20px; + page-break-inside: avoid; + page-break-after: avoid; + word-wrap: break-word; +} + +h1 { + font-size: 22px; +} + +.titlepage h1.title { + text-align:left; +} + +.book > .titlepage h1.title { + text-align: center; +} + +.article > .titlepage h1.title, +.article > .titlepage h2.title { + text-align: center; +} + +.set .titlepage > div > div > h1.title { + text-align: center; +} + +.part > .titlepage h1.title { + text-align: center; + font-size: 24px; +} + +div.producttitle { + margin-top: 0px; + margin-bottom: 20px; + font-size: 48px; + font-weight: bold; +/* background: #003d6e url(../images/h1-bg.png) top left repeat-x; */ + color: #336699; + text-align: center; + padding-top: 12px; +} + +.titlepage .corpauthor { + margin-top: 1em; + text-align: center; +} + +.section h1.title { + font-size: 18px; + padding: 0px; + color: #336699; + text-align: left; + background: white; +} + +h2 { + font-size: 20px; + margin-top: 30px; +} + + +.book div.subtitle, .book h2.subtitle, .book h3.subtitle { + margin-top: 1em; + margin-bottom: 1em; + font-size: 18px; + text-align: center; +} + +div.subtitle { + color: #336699; + font-weight: bold; +} + +h1.legalnotice { + font-size: 24px; +} + +.preface > div > div > div > h2.title, +.preface > div > div > div > h1.title { + margin-top: 1em; + font-size: 24px; +} + +.appendix h2 { + font-size: 24px; +} + + + +h3 { + font-size: 14px; + padding-top:0px; + padding-bottom: 0px; + margin-bottom: 0px; +} +h4 { + font-size: 14px; + padding-top:0px; + padding-bottom:0px; +} + +h5 { + font-size: 14px; +} + +h6 { + font-size: 14px; + margin-bottom: 0px; +} + +.abstract h6 { + margin-top:1em; + margin-bottom:.5em; + font-size: 24px; +} + +.index > div > div > div > h2.title { + font-size: 24px; +} + +.chapter > div > div > div > h2.title { + font-size: 24px; +} + +.section > div > div > div > h2.title { + font-size: 21px; + page-break-inside: avoid; + page-break-before: avoid; + page-break-after: avoid; +} + +.section > div > div > div > h3.title { + font-size: 17px; +} + +/*element rules*/ +hr { + border-collapse: collapse; + border-style:none; + border-top: 1px dotted #ccc; + width:100%; +} + +/* web site rules */ +ul.languages, .languages li { + display:inline; + padding:0px; +} + +.languages li a { + padding:0px .5em; + text-decoration: none; +} + +.languages li p, .languages li div.para { + display:inline; +} + +.languages li a:link, .languages li a:visited { + color:#444; +} + +.languages li a:hover, .languages li a:focus, .languages li a:active { + color:black; +} + +ul.languages { + display:block; + background-color:#eee; + padding:.5em; +} + +/*supporting stylesheets*/ + +/*unique to the webpage only*/ +.books { + position:relative; +} + +.versions li { + width:100%; + clear:both; + display:block; +} + +a.version { + font-size: 20px; + text-decoration:none; + width:100%; + display:block; + padding:1em 0px .2em 0px; + clear:both; +} + +a.version:before { + content:"Version"; + font-size: smaller; +} + +a.version:visited, a.version:link { + color:#666; +} + +a.version:focus, a.version:hover { + color:black; +} + +.books { + display:block; + position:relative; + clear:both; + width:100%; +} + +.books li { + display:block; + width:200px; + float:left; + position:relative; + clear: none ; +} + +.books .html { + width:170px; + display:block; +} + +.books .pdf { + position:absolute; + left:170px; + top:0px; + font-size: smaller; +} + +.books .pdf:link, .books .pdf:visited { + color:#555; +} + +.books .pdf:hover, .books .pdf:focus { + color:#000; +} + +.books li a { + text-decoration:none; +} + +.books li a:hover { + color:black; +} + +/*products*/ +.products li { + display: block; + width:300px; + float:left; +} + +.products li a { + width:300px; + padding:.5em 0px; +} + +.products ul { + clear:both; +} + +/*revision history*/ +.revhistory { + display:block; +} + +.revhistory table { + background-color:transparent; + border-color:#fff; + padding:0px; + margin: 0; + border-collapse:collapse; + border-style:none; +} + +.revhistory td { + text-align :left; + padding:0px; + border: none; + border-top: 1px solid #fff; + font-weight: bold; +} + +.revhistory .simplelist td { + font-weight: normal; +} + +.revhistory .simplelist { + margin-bottom: 1.5em; + margin-left: 1em; +} + +.revhistory table th { + display: none; +} + + +/*credits*/ +.authorgroup div { + clear:both; + text-align: center; +} + +div.author div.author, +div.translator div.translator, +div.othercredit div.othercredit, +div.editor div.editor, +div.contrib div.contrib { + margin: 0px; + padding: 0px; + margin-top: 12px; + font-size: 14px; + font-weight: bold; + color: #336699; +} + +div.editedby { + margin-top: 15px; + margin-bottom: -0.8em; +} + +div.authorgroup .author, +div.authorgroup.editor, +div.authorgroup.translator, +div.authorgroup.othercredit, +div.authorgroup.contrib { + display: block; + font-size: 14px; + page-break-inside: avoid; +} + +.revhistory .author { + display: inline; +} + +.othercredit h3 { + padding-top: 1em; +} + + +.othercredit { + margin:0px; + padding:0px; +} + +.releaseinfo { + clear: both; +} + +.copyright { + margin-top: 1em; +} + +/* qanda sets */ +.answer { + margin-bottom:1em; + border-bottom:1px dotted #ccc; +} + +.qandaset .toc { + border-bottom:1px dotted #ccc; +} + +.question { + font-weight:bold; +} + +.answer .data, .question .data { + padding-left: 2.6em; +} + +.answer .label, .question .label { + float:left; + font-weight:bold; +} + +/* inline syntax highlighting */ +.perl_Alert { + color: #0000ff; +} + +.perl_BaseN { + color: #007f00; +} + +.perl_BString { + color: #5C3566; +} + +.perl_Char { + color: #ff00ff; +} + +.perl_Comment { + color: #888888; +} + + +.perl_DataType { + color: #0000ff; +} + + +.perl_DecVal { + color: #00007f; +} + + +.perl_Error { + color: #ff0000; +} + + +.perl_Float { + color: #00007f; +} + + +.perl_Function { + color: #007f00; +} + + +.perl_IString { + color: #5C3566; +} + + +.perl_Keyword { + color: #002F5D; +} + + +.perl_Operator { + color: #ffa500; +} + + +.perl_Others { + color: #b03060; +} + + +.perl_RegionMarker { + color: #96b9ff; +} + + +.perl_Reserved { + color: #9b30ff; +} + + +.perl_String { + color: #5C3566; +} + + +.perl_Variable { + color: #0000ff; +} + + +.perl_Warning { + color: #0000ff; +} + +/*Lists*/ +ul { + list-style-image: url("../images/dot.png"); + list-style-type: circle; + padding-left: 1.6em; +} + +ul ul { + list-style-image: url("../images/dot2.png"); + list-style-type: circle; +} + +ol.1 { + list-style-type: decimal; +} + +ol.a, +ol ol { + list-style-type: lower-alpha; +} + +ol.i { + list-style-type: lower-roman; +} +ol.A { + list-style-type: upper-alpha; +} + +ol.I { + list-style-type: upper-roman; +} + +dt { + font-weight:bold; + margin-bottom:0px; + padding-bottom:0px; +} + +dd { + margin:0px; + margin-left:2em; + padding-top:0px; +} + +li { + padding-top: 0px; + margin-top: 0px; + padding-bottom: 0px; +/* margin-bottom: 16px; */ +} + +/*images*/ +img { + display:block; + margin: 2em 0; + max-width: 100%; +} + +.inlinemediaobject, +.inlinemediaobject img, +.inlinemediaobject object { + display:inline; + margin:0px; + overflow: hidden; +} + +.figure { + margin-top: 1em; + width: 100%; +} + +.figure img, +.mediaobject img { + display:block; + margin: 0em; + page-break-inside: avoid; +} + +.figure .title { + margin-bottom:2em; + padding:0px; +} + +/*document modes*/ +.confidential { + background-color:#900; + color:White; + padding:.5em .5em; + text-transform:uppercase; + text-align:center; +} + +.longdesc-link { + display:none; +} + +.longdesc { + display:none; +} + +.prompt { + padding:0px .3em; +} + +/*user interface styles*/ +.screen .replaceable { +} + +.guibutton, .guilabel { + font-family: "liberation mono", "bitstream vera mono", "dejavu mono", monospace; + font-weight: bold; +} + +.example { + background-color: #ffffff; + border-left: 3px solid #aaaaaa; + padding-top: 1px; + padding-bottom: 0.1em; + padding-left: 1em; +} + +.equation { + border-left: 3px solid #aaaaaa; + background-color: #ffffff; + padding-top: 1px; + padding-bottom: 0.1em; + padding-left: 1em; +} + +.equation-contents { + margin-left: 4em; +} + +div.title { + margin-bottom: 1em; + font-weight: 14px; + font-weight: bold; + color: #336699; + page-break-inside: avoid; + page-break-after: avoid; + word-wrap: break-word; +} + +.example-contents { + background-color: #ffffff; +} + +.example-contents .para { +/* padding: 10px;*/ +} + +/*terminal/console text*/ +.computeroutput, +.option { + font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; + font-weight:bold; +} + +.replaceable { + font-style: italic; +} + +.command, .filename, .keycap, .classname, .literal { + font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; + font-weight:bold; +} + +/* no bold in toc */ +.toc * { + font-weight: inherit; +} + +.toc H1 { + font-weight: bold; +} + + +div.programlisting { + white-space: pre-wrap; /* css-3 */ + white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + word-wrap: break-word; /* Internet Explorer 5.5+ */ +} + +pre { + font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; + display:block; + background-color: #f5f5f5; + color: #000000; +/* border: 1px solid #aaaaaa; */ + margin-bottom: 1em; + padding:.5em 1em; + white-space: pre-wrap; /* css-3 */ + white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + word-wrap: break-word; /* Internet Explorer 5.5+ */ + font-size: 0.9em; + border-style:none; + box-shadow: 0 2px 5px #AAAAAA inset; + -moz-box-shadow: 0 2px 5px #AAAAAA inset; + -webkit-box-shadow: 0 2px 5px #AAAAAA inset; + -o-box-shadow: 0 2px 5px #AAAAAA inset; +} + +body.pdf pre { + border: 1px solid #AAAAAA; + box-shadow: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + -o-box-shadow: none; +} + + +pre .replaceable, +pre .keycap { +} + +code { + font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; + white-space: pre-wrap; + word-wrap: break-word; + font-weight:bold; +} + +.parameter code { + display: inline; + white-space: pre-wrap; /* css-3 */ + white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + word-wrap: break-word; /* Internet Explorer 5.5+ */ +} + +code.email { + font-weight: normal; + font-family: "liberation sans", "Myriad ", "Bitstream Vera Sans", "Lucida Grande", "Luxi Sans", "Trebuchet MS", helvetica, verdana, arial, sans-serif; + +} + +/*Notifications*/ +div.warning:before { + content:url(../images/warning.png); + padding-left: 5px; +} + +div.note:before { + content:url(../images/note.png); + padding-left: 5px; +} + +div.important:before { + content:url(../images/important.png); + padding-left: 5px; +} + +div.warning, div.note, div.important { + color: black; + margin: 0px; + padding: 0px; + background: none; + background-color: white; + margin-bottom: 1em; + border-bottom: 1px solid #aaaaaa; + page-break-inside: avoid; +} + +div.admonition_header p { + margin: 0px; + padding: 0px; + color: #eeeeec; + padding-top: 0px; + padding-bottom: 0px; + height: 1.4em; + line-height: 1.4em; + font-size: 17px; + display:inline; +} + +div.admonition_header { + background-origin:content-box; + clear: both; + margin: 0px; + padding: 0px; + margin-top: -40px; + padding-left: 58px; + line-height: 1.0px; + font-size: 1.0px; +} + +div.warning div.admonition_header { + background: url(../images/red.png) top left repeat-x; + background-color: #590000; + background: -webkit-linear-gradient(#a40000,#590000); + background: linear-gradient(#a40000,#590000); +} + +div.note div.admonition_header { + background: url(../images/green.png) top right repeat-x; + background-color: #597800; + background: -webkit-linear-gradient(#769f00,#597800); + background: linear-gradient(#769f00,#597800); +} + +div.important div.admonition_header { + background: url(../images/yellow.png) top right repeat-x; + background-color: #a6710f; + background: -webkit-linear-gradient(#d08e13,#a6710f); + background: linear-gradient(#d08e13,#a6710f); +} + +div.warning p:first-child, +div.warning div.para:first-child, +div.note p:first-child, +div.note div.para:first-child, +div.important p:first-child, +div.important div.para:first-child { + padding: 0px; + margin: 0px; +} + +div.admonition { + border: none; + border-left: 1px solid #aaaaaa; + border-right: 1px solid #aaaaaa; + padding:0px; + margin:0px; + padding-top: 1.5em; + padding-bottom: 1em; + padding-left: 2em; + padding-right: 1em; + background-color: #eeeeec; + -moz-border-radius: 0px; + -webkit-border-radius: 0px; + border-radius: 0px; +} + +/*Page Title*/ +#title { + display:block; + height:45px; + padding-bottom:1em; + margin:0px; +} + +#title a.left{ + display:inline; + border:none; +} + +#title a.left img{ + border:none; + float:left; + margin:0px; + margin-top:.7em; +} + +#title a.right { + padding-bottom:1em; +} + +#title a.right img { + border:none; + float:right; + margin:0px; + margin-top:.7em; +} + +/*Table*/ +div.table { +/* page-break-inside: avoid; */ +} + +table { + border: 1px solid #444; + width:100%; + border-collapse:collapse; + table-layout: fixed; + word-wrap: break-word; +} + +table.blockquote, +table.simplelist, +.calloutlist table { + border-style: none; +} + +table th { + text-align:left; + background-color:#6699cc; + padding:.3em .5em; + color:white; +} + +table td { + padding:.15em .5em; +} + +table tr.even td { + background-color:#f5f5f5; +} + +tr:nth-child(even) { + background-color: #eeeeee; + +} + + +table th p:first-child, table td p:first-child, table li p:first-child, +table th div.para:first-child, table td div.para:first-child, table li div.para:first-child { + margin-top:0px; + padding-top:0px; + display:inline; +} + +th, td { + border-style:none; + vertical-align: top; +/* border: 1px solid #000; */ +} + +.blockquote td, +.simplelist th, +.simplelist td { + border: none; +} + +table table td { + border-bottom:1px dotted #aaa; + background-color:white; + padding:.6em 0px; +} + +table table { + border:1px solid white; +} + +td.remarkval { + color:#444; +} + +td.fieldval { + font-weight:bold; +} + +.lbname, .lbtype, .lbdescr, .lbdriver, .lbhost { + color:white; + font-weight:bold; + background-color:#999; + width:120px; +} + +td.remarkval { + width:230px; +} + +td.tname { + font-weight:bold; +} + +th.dbfield { + width:120px; +} + +th.dbtype { + width:70px; +} + +th.dbdefault { + width:70px; +} + +th.dbnul { + width:70px; +} + +th.dbkey { + width:70px; +} + +span.book { + margin-top:4em; + display:block; + font-size: 11pt; +} + +span.book a{ + font-weight:bold; +} +span.chapter { + display:block; +} + +table.simplelist td, .calloutlist table td { + border-style: none; +} + + +table.lt-4-cols.lt-7-rows td { + border: none; +} +/*to simplify layout*/ + + +table.lt-4-cols.gt-14-rows tr:nth-child(odd) { + background-color: #fafafa; +} +/* to keep simple but stripe rows */ + + +.gt-8-cols td { + border-left: 1px solid #ccc; +} + +.gt-8-cols td:first-child { + border-left: 0; +} +/* to apply vertical lines to differentiate columns*/ + +/*Breadcrumbs*/ +#breadcrumbs ul li.first:before { + content:" "; +} + +#breadcrumbs { + color:#900; + padding:3px; + margin-bottom:25px; +} + +#breadcrumbs ul { + margin-left:0; + padding-left:0; + display:inline; + border:none; +} + +#breadcrumbs ul li { + margin-left:0; + padding-left:2px; + border:none; + list-style:none; + display:inline; +} + +#breadcrumbs ul li:before { + content:"\0020 \0020 \0020 \00BB \0020"; + color:#333; +} + +dl { + margin-top: 0px; + margin-left: 28px; +} + +.toc dl { + margin-left: 10px; +} + +/*index*/ +.glossary h3, +.index h3 { + font-size: 20px; + color:#aaa; + margin:0px; +} + +.indexdiv { + margin-bottom:1em; +} + +.glossary dt, +.index dt { + color:#444; + padding-top:.5em; +} + +.glossary dl dl dt, +.index dl dl dt { + color:#777; + font-weight:normal; + padding-top:0px; +} + +.index dl dl dt:before { + content:"- "; + color:#ccc; +} + +/*changes*/ +.footnote { + font-size: 10px; + margin: 0px; + color: #222; +} + +.footnotes { + margin-bottom: 60px; +} + +table .footnote { +} + +sup { + margin:0px; + padding:0px; + font-size: 10px; + padding-left:0px; +} + +.footnote { + position:relative; +} + +.footnote sup { + color: black; + left: .4em; +} + +.footnote a:link, +.footnote a:visited { + text-decoration:none; + border: none; +} + +.footnote .para sup { +/* position:absolute; */ + vertical-align:text-bottom; +} + +a.footnote { + padding-right: 0.5em; + text-decoration:none; + border: none; +} + +.footnote sup a:link, +.footnote sup a:visited { + color:#92917d; + text-decoration:none; +} + +.footnote:hover sup a { + text-decoration:none; +} + +.footnote p,.footnote div.para { + padding-left:1em; +} + +.footnote a:link, +.footnote a:visited before{ + color:#00537c; +} + +.footnote a:hover { +} + +/**/ +.pdf-break { + page-break-before: always; +} + +div.legalnotice { + page-break-before: always; +} + +div.abstract { + page-break-before: always; +/* page-break-after: always;*/ +} + +div.chapter { + page-break-before: always; +} + + +div.titlepage, div.titlepage > div, div.titlepage > div > div { + page-break-inside: avoid; + page-break-after: avoid; +} + +div.preface, div.part { + page-break-before: always; +} + +div.appendix { + page-break-before: always; +} + +div.section { + page-break-inside: auto; + page-break-before: auto; + page-break-after: auto; +} + + +dt.varlistentry { + page-break-inside: avoid; + page-break-after: avoid; +} + +dd { + page-break-before: avoid; +} + +div.note .replaceable, +div.important .replaceable, +div.warning .replaceable, +div.note .keycap, +div.important .keycap, +div.warning .keycap +{ +} + +ul li p:last-child, ul li para:last-child { + margin-bottom:0px; + padding-bottom:0px; +} + +/*document navigation*/ +.docnav a, .docnav strong { + border:none; + text-decoration:none; + font-weight:normal; +} + +.docnav { + list-style:none; + margin:0px; + padding:0px; + position:relative; + width:100%; + padding-bottom:2em; + padding-top:1em; + height:2.5em; + line-height:2.5em; +/* + border-top:1px dotted #ccc; + background-color: rgba(240, 240, 240, 0.9); +-webkitbox-shadow: 0px .15em .5em rgba(0,0,0,0.2); + -moz-box-shadow: 0px .15em .5em rgba(0,0,0,0.2); + box-shadow: 0px .15em .5em rgba(0,0,0,0.2); +*/ +} + +.docnav li { + list-style:none; + margin:0px; + padding:0px; + display:inline; + font-size: 14px; +} + +.docnav li:before { + content:" "; +} + +.docnav li.previous, .docnav li.next { + position:absolute; + top:1.5em; +} + +.docnav li.up, .docnav li.home { + margin:0px 1.5em; +} + +.docnav.top li.home { + color: #336699; + font-size: 22pt; + font-weight: bold; +} + + +.docnav li.previous { + left:0px; + text-align:left; +} + +.docnav li.next { + right:0px; + text-align:right; +} + +.docnav li.previous strong, .docnav li.next strong { + height: 17px; + display: block; +} + +.docnav { + margin:0 auto; + text-align:center; +} + +.docnav li.next a strong { + background: url(../images/stock-go-forward.png) right 120% no-repeat; + padding-top:3px; + padding-bottom:4px; + padding-right:28px; +} + +.docnav li.previous a strong { + background: url(../images/stock-go-back.png) left 120% no-repeat; + padding-top:3px; + padding-bottom:4px; + padding-left:28px; + padding-right:0.5em; +} + +.docnav li.home a strong { + background: url(../images/stock-home.png) top left no-repeat; + padding:5px; + padding-left:28px; +} + +.docnav li.up a strong { + background: url(../images/stock-go-up.png) top left no-repeat; + padding:5px; + padding-left:28px; +} + +.docnav a:link, .docnav a:visited { + color:#666; +} + +.docnav a:hover, .docnav a:focus, .docnav a:active { + color:black; +} + +.docnav a { + max-width: 10px; + overflow:hidden; +} + +.docnav a:link strong { + text-decoration:none; +} + +.docnav { + margin:0 auto; + text-align:center; +} + +ul.docnav { + margin-bottom: 1em; +} +/* Reports */ +.reports ul { + list-style:none; + margin:0px; + padding:0px; +} + +.reports li{ + margin:0px; + padding:0px; +} + +.reports li.odd { + background-color: #eeeeee; + margin:0px; + padding:0px; +} + +.reports dl { + display:inline; + margin:0px; + padding:0px; + float:right; + margin-right: 17em; + margin-top:-1.3em; +} + +.reports dt { + display:inline; + margin:0px; + padding:0px; +} + +.reports dd { + display:inline; + margin:0px; + padding:0px; + padding-right:.5em; +} + +.reports h2, .reports h3{ + display:inline; + padding-right:.5em; + font-size: 14px; + font-weight:normal; +} + +.reports div.progress { + display:inline; + float:right; + width:16em; + background:#c00 url(../images/shine.png) top left repeat-x; + margin:0px; + margin-top:-1.3em; + padding:0px; + border:none; +} + +/*uniform*/ +body.results, body.reports { + max-width:57em ; + padding:0px; +} + +/*Progress Bar*/ +div.progress { + display:block; + float:left; + width:16em; + background:#c00 url(../images/shine.png) top left repeat-x; + height:1em; +} + +div.progress span { + height:1em; + float:left; +} + +div.progress span.translated { + background:#6c3 url(../images/shine.png) top left repeat-x; +} + +div.progress span.fuzzy { + background:#ff9f00 url(../images/shine.png) top left repeat-x; +} + + +/*Results*/ + +.results ul { + list-style:none; + margin:0px; + padding:0px; +} + +.results li{ + margin:0px; + padding:0px; +} + +.results li.odd { + background-color: #eeeeee; + margin:0px; + padding:0px; +} + +.results dl { + display:inline; + margin:0px; + padding:0px; + float:right; + margin-right: 17em; + margin-top:-1.3em; +} + +.results dt { + display:inline; + margin:0px; + padding:0px; +} + +.results dd { + display:inline; + margin:0px; + padding:0px; + padding-right:.5em; +} + +.results h2, .results h3 { + display:inline; + padding-right:.5em; + font-size: 14px; + font-weight:normal; +} + +.results div.progress { + display:inline; + float:right; + width:16em; + background:#c00 url(../images/shine.png) top left repeat-x; + margin:0px; + margin-top:-1.3em; + padding:0px; + border:none; +} + +/* Dirty EVIL Mozilla hack for round corners */ +pre { + -moz-border-radius:11px; + -webkit-border-radius:11px; + border-radius: 11px; +/* page-break-inside: avoid; */ +} + +.example { + -moz-border-radius:0px; + -webkit-border-radius:0px; + border-radius: 0px; + page-break-inside: avoid; +} + +/* move these invisible fields out of the flow */ +.example > a:first-child, +.table > a:first-child { + float: left; +} + +.package, .citetitle { + font-style: italic; +} + +.titlepage .edition, +.titlepage .releaseinfo { + color: #336699; + background-color: transparent; + margin-top: 1em; + margin-bottom: 1em; + font-size: 20px; + font-weight: bold; + text-align: center; +} + +span.remark { + background-color: #ff00ff; +} + +.draft { + background-image: url(../images/watermark-draft.png); + background-repeat: repeat-y; + background-position: center; +} + +.foreignphrase { + font-style: inherit; +} + +dt { + clear:both; + page-break-inside: avoid; + page-break-after: avoid; +} + +dt img { + border-style: none; + max-width: 112px; +} + +dt object { + max-width: 112px; +} + +dt .inlinemediaobject, dt object { + display: inline; + float: left; + margin-bottom: 1em; + padding-right: 1em; + width: 112px; +} + +dl:after { + display: block; + clear: both; + content: ""; +} + +.toc dd { + padding-bottom: 0px; + margin-bottom: 1em; + padding-left: 1.3em; + margin-left: 0px; +} + +div.toc > dl > dt { + padding-bottom: 0px; + margin-bottom: 0px; + margin-top: 1em; +} + + +.strikethrough { + text-decoration: line-through; +} + +.underline { + text-decoration: underline; +} + +.calloutlist img, .callout { + padding: 0px; + margin: 0px; + width: 12pt; + display: inline; + vertical-align: middle; +} + +li.step > a:first-child { + display: block; +} + +.stepalternatives { + list-style-image: none; + list-style-type: upper-alpha; +} +.task { +/* page-break-inside: avoid; */ +} + + +.added { + background-color: #99ff99; +} + +.changed { + background-color: #ffff77; +} + +.deleted { + background-color: #ff4455; + text-decoration: line-through; +} diff --git a/doc/publican/html/css/default.css b/doc/publican/html/css/default.css new file mode 100644 index 0000000..bf38ebb --- /dev/null +++ b/doc/publican/html/css/default.css @@ -0,0 +1,3 @@ +@import url("common.css"); +@import url("overrides.css"); +@import url("lang.css"); diff --git a/doc/publican/html/css/epub.css b/doc/publican/html/css/epub.css new file mode 100644 index 0000000..b0ffd43 --- /dev/null +++ b/doc/publican/html/css/epub.css @@ -0,0 +1,115 @@ +/*headings*/ +h1, h2, h3, h4, h5, h6, +div.producttitle, +div.subtitle, +div.author div.author, +div.translator div.translator, +div.othercredit div.othercredit, +div.editor div.editor, +div.contrib div.contrib, +.title, +.titlepage .edition { +} + +div.para { + margin-top: 1em; +} +/* inline syntax highlighting */ +.perl_Alert { + color: #0000ff; +} + +.perl_BaseN { + color: #007f00; +} + +.perl_BString { + color: #5C3566; +} + +.perl_Char { + color: #ff00ff; +} + +.perl_Comment { + color: #888888; +} + + +.perl_DataType { + color: #0000ff; +} + + +.perl_DecVal { + color: #00007f; +} + + +.perl_Error { + color: #ff0000; +} + + +.perl_Float { + color: #00007f; +} + + +.perl_Function { + color: #007f00; +} + + +.perl_IString { + color: #5C3566; +} + + +.perl_Keyword { + color: #002F5D; +} + + +.perl_Operator { + color: #ffa500; +} + + +.perl_Others { + color: #b03060; +} + + +.perl_RegionMarker { + color: #96b9ff; +} + + +.perl_Reserved { + color: #9b30ff; +} + + +.perl_String { + color: #5C3566; +} + + +.perl_Variable { + color: #0000ff; +} + + +.perl_Warning { + color: #0000ff; +} + +b, strong { + font-weight: bolder; +} + +code.command { + font-family: monospace; + font-weight: bolder; +} diff --git a/doc/publican/html/css/meson.build b/doc/publican/html/css/meson.build new file mode 100644 index 0000000..699d70e --- /dev/null +++ b/doc/publican/html/css/meson.build @@ -0,0 +1,14 @@ +foreach src : files([ + 'brand.css', + 'common.css', + 'default.css', + 'epub.css', + 'print.css', +]) + name = fs.name(src) + publican_inputs += fs.copyfile( + name, + install: true, + install_dir: publican_install_prefix + '/html/css', + ) +endforeach diff --git a/doc/publican/html/css/print.css b/doc/publican/html/css/print.css new file mode 100644 index 0000000..54088f4 --- /dev/null +++ b/doc/publican/html/css/print.css @@ -0,0 +1,15 @@ +@import url("common.css"); +@import url("overrides.css"); +@import url("lang.css"); + +#tocframe { + display: none; +} + +body.toc_embeded { + margin-left: 30px; +} + +.producttitle { + color: #336699; +} diff --git a/doc/publican/html/images/icon.svg b/doc/publican/html/images/icon.svg new file mode 100644 index 0000000..b2f16d0 --- /dev/null +++ b/doc/publican/html/images/icon.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/doc/publican/html/images/meson.build b/doc/publican/html/images/meson.build new file mode 100644 index 0000000..98e5b93 --- /dev/null +++ b/doc/publican/html/images/meson.build @@ -0,0 +1,28 @@ +foreach src : files([ + 'icon.svg', + 'wayland.png', +]) + name = fs.name(src) + publican_inputs += fs.copyfile( + name, + install: true, + install_dir: publican_install_prefix + '/html/images', + ) +endforeach + +foreach src : files([ + 'wayland-architecture.gv', + 'x-architecture.gv', +]) + input = fs.name(src) + output = fs.stem(src) + '.png' + + publican_inputs += custom_target( + input + '.png', + command: [ dot, '-Tpng', '-o@OUTPUT@', '@INPUT@' ], + input: input, + output: output, + install: true, + install_dir: publican_install_prefix + '/html/images', + ) +endforeach diff --git a/doc/publican/html/images/wayland-architecture.gv b/doc/publican/html/images/wayland-architecture.gv new file mode 100644 index 0000000..f2c3507 --- /dev/null +++ b/doc/publican/html/images/wayland-architecture.gv @@ -0,0 +1,36 @@ +digraph arch_wayland { + edge[ + fontname="DejaVu Sans", + dir="both", + arrowtail="dot", + arrowsize=.5, + fontname="DejaVu Sans", + fontsize="18", + ] + + node[ + color=none, + margin=0, + fontname="DejaVu Sans", + fontsize="18", + ] + + c1 [label=<
Wayland Client
>, URL="#c1"] + c2 [label=<
Wayland Client
>, URL="#c2"] + + comp [tooltip="Wayland Compositor", label=<

Wayland
Compositor

>, URL="#comp"] + + impl [tooltip="KMS evdev Kernel", label=<
KMSevdev
Kernel
>, URL="#impl"] + + c1 -> comp [taillabel="③", labeldistance=2.5, URL="#step_3"]; + c2 -> comp; + + comp -> c1 [label="②", URL="#step_2"]; + comp -> c2; + + comp -> impl [xlabel = "④", URL="#step_4"]; + comp -> impl [style = invis, label=" "]; + impl -> comp [xlabel = "①", URL="#step_1"]; + + c1 -> c2 [style=invis]; +} diff --git a/doc/publican/html/images/wayland.png b/doc/publican/html/images/wayland.png new file mode 100644 index 0000000..c993792 Binary files /dev/null and b/doc/publican/html/images/wayland.png differ diff --git a/doc/publican/html/images/x-architecture.gv b/doc/publican/html/images/x-architecture.gv new file mode 100644 index 0000000..b223d1d --- /dev/null +++ b/doc/publican/html/images/x-architecture.gv @@ -0,0 +1,53 @@ +digraph arch_x { + edge[ + fontname="DejaVu Sans", + dir="both", + arrowtail="dot", + arrowsize=.5, + fontname="DejaVu Sans", + fontsize="18", + ] + + node[ + shape="none", + color=none, + margin=0, + fontname="DejaVu Sans", + fontsize="18", + ] + + { + rank=same; + c1 [label=<
X Client
>, URL="#c1"] + c3 [label=<
X Client
>, URL="#c3"] + } + c2 [label=<
X Client
>, URL="#c2"] + + { + rank=same; + xserver [tooltip="X Server", label=<

X Server

>, URL="#xserver"] + comp [tooltip="Compositor", label=<

Compositor

>, URL="#comp"] + } + + impl [tooltip="KMS evdev Kernel", label=<
KMSevdev
Kernel
>, URL="#impl"] + + c1 -> xserver [taillabel="③", labeldistance=2, URL="#step_3"]; + c2 -> xserver; + c3 -> xserver; + + xserver -> c1 [taillabel="②", labeldistance=2, URL="#step_2"]; + xserver -> c2; + xserver -> c3; + + xserver -> impl [taillabel="⑥", labeldistance=1.75, URL="#step_6"]; + xserver -> impl [style=invis, label=" "]; + impl -> xserver [taillabel="①", labeldistance=1.75, URL="#step_1"]; + + xserver -> comp [style=invis]; + xserver -> comp [taillabel="④", labeldistance=1.75, labelangle=-45, URL="#step_4"]; + comp -> xserver [taillabel="⑤", URL="#step_5"]; + comp -> xserver [style=invis] + + c1 -> c2 [style=invis]; + c3 -> c2 [style=invis]; + } diff --git a/doc/publican/html/images/xwayland-architecture.png b/doc/publican/html/images/xwayland-architecture.png new file mode 100644 index 0000000..f24dc18 Binary files /dev/null and b/doc/publican/html/images/xwayland-architecture.png differ diff --git a/doc/publican/merge-mapcoords.xsl b/doc/publican/merge-mapcoords.xsl deleted file mode 100644 index 7adaca3..0000000 --- a/doc/publican/merge-mapcoords.xsl +++ /dev/null @@ -1,64 +0,0 @@ - - - - - - - -%BOOK_ENTITIES; -]> -]]> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/publican/meson.build b/doc/publican/meson.build index eac3e9b..83556f0 100644 --- a/doc/publican/meson.build +++ b/doc/publican/meson.build @@ -1,6 +1,92 @@ -merge_mapcoords_xsl = files('merge-mapcoords.xsl') +proto_to_docboox_xsl = files('xsl/protocol-to-docbook.xsl') +proto_iface_to_docboox_xsl = files('xsl/protocol-interfaces-to-docbook.xsl') +merge_mapcoords_xsl = files('xsl/merge-mapcoords.xsl') +to_publican_xsl = files('xsl/doxygen-to-publican.xsl') -subdir('sources') +publican_inputs = [] + +foreach src : files([ + 'Wayland.xml', # must be first in publican_inputs + 'Wayland.ent', + 'Book_Info.xml', + 'Author_Group.xml', + 'Foreword.xml', + 'Preface.xml', + 'Revision_History.xml', + 'Protocol.xml', + 'Xwayland.xml', + 'Compositors.xml', + 'Color.xml', + 'Client.xml', + 'Server.xml', +]) + name = fs.name(src) + publican_inputs += fs.copyfile(name) +endforeach + +publican_inputs += custom_target( + 'ProtocolSpec.xml', + command: [ xsltproc, '-o', '@OUTPUT@', proto_to_docboox_xsl, '@INPUT@' ], + input: wayland_protocol_xml, + output: 'ProtocolSpec.xml' +) + +publican_inputs += custom_target( + 'ProtocolInterfaces.xml', + command: [ xsltproc, '-o', '@OUTPUT@', proto_iface_to_docboox_xsl, '@INPUT@' ], + input: wayland_protocol_xml, + output: 'ProtocolInterfaces.xml' +) + +ClientAPI_combined = custom_target( + 'ClientAPI-combined', + command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ], + input: [ doxygen_Client_combine_xslt, doxygen_Client_index_xml ], + output: 'ClientAPI-combined.xml' +) + +publican_inputs += custom_target( + 'ClientAPI.xml', + command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Client', to_publican_xsl, '@INPUT@' ], + input: ClientAPI_combined, + output: 'ClientAPI.xml' +) + +ServerAPI_combined = custom_target( + 'ServerAPI-combined', + command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ], + input: [ doxygen_Server_combine_xslt, doxygen_Server_index_xml ], + output: 'ServerAPI-combined.xml' +) + +publican_inputs += custom_target( + 'ServerAPI.xml', + command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Server', to_publican_xsl, '@INPUT@' ], + input: ServerAPI_combined, + output: 'ServerAPI.xml' +) + +foreach src : files([ + 'Architecture.xml', + 'Introduction.xml' +]) + name = fs.name(src) + publican_inputs += custom_target( + name, + command: [ + xsltproc, + '-o', '@OUTPUT@', + '--stringparam', 'basedir', '.', + merge_mapcoords_xsl, + '@INPUT@', + ], + input: [name], + output: [name], + ) +endforeach + +subdir('html/css') +subdir('html/images') custom_target( 'Wayland-docbook-html', @@ -14,19 +100,11 @@ custom_target( '--stringparam', 'html.stylesheet=css/default.css', '-o', '@OUTPUT@', 'html', - '@INPUT@' - ], - input: publican_processed_main, - output: publican_html_dir, - depend_files: publican_copied_sources, - depends: [ - publican_processed_targets, - ClientAPI_xml, - ServerAPI_xml, - ProtocolSpec_xml, - ProtocolInterfaces_xml + '@INPUT0@' ], + input: publican_inputs, + output: 'html', build_by_default: true, install: true, - install_dir: publican_install_prefix + install_dir: publican_install_prefix, ) diff --git a/doc/publican/protocol-interfaces-to-docbook.xsl b/doc/publican/protocol-interfaces-to-docbook.xsl deleted file mode 100644 index f68216d..0000000 --- a/doc/publican/protocol-interfaces-to-docbook.xsl +++ /dev/null @@ -1,51 +0,0 @@ - - - - - - - -%BOOK_ENTITIES; -]> -]]> - -
- Interfaces - - 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. - - - - Core interfaces: - - - - -
- - - - - - - - - - - - - - - - - - - - diff --git a/doc/publican/protocol-to-docbook.xsl b/doc/publican/protocol-to-docbook.xsl deleted file mode 100644 index 79c938b..0000000 --- a/doc/publican/protocol-to-docbook.xsl +++ /dev/null @@ -1,223 +0,0 @@ - - - - - - - -%BOOK_ENTITIES; -]> -]]> - - - Wayland Protocol Specification - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - <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" /> - -
- - -
- Enums provided by <xsl:value-of select="@name" /> - -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - id for the new - - - - - - - - - - - - - - - - - - - - - - - :: - - - - - - - :: - - - - - () - - - - - - - - - - - -
- - <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" /> - <xsl:if test="@bitfield"> - - bitfield - </xsl:if> - <xsl:if test="description/@summary"> - - <xsl:value-of select="description/@summary" /> - </xsl:if> - - - - - - - -
- - - - - diff --git a/doc/publican/sources/Architecture.xml b/doc/publican/sources/Architecture.xml deleted file mode 100644 index b8a104c..0000000 --- a/doc/publican/sources/Architecture.xml +++ /dev/null @@ -1,344 +0,0 @@ - - -%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: - -
- X architecture diagram - - - - - - - - - - - - - - - -
- - - - - 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: - -
- Wayland architecture diagram - - - - - - - - - - - - - -
- - - - - 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 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. - -
-
- 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/publican/sources/Author_Group.xml b/doc/publican/sources/Author_Group.xml deleted file mode 100644 index 2bdde62..0000000 --- a/doc/publican/sources/Author_Group.xml +++ /dev/null @@ -1,16 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Kristian - Høgsberg - - Intel Corporation - - krh@bitplanet.net - - - diff --git a/doc/publican/sources/Book_Info.xml b/doc/publican/sources/Book_Info.xml deleted file mode 100644 index 897673a..0000000 --- a/doc/publican/sources/Book_Info.xml +++ /dev/null @@ -1,71 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Wayland - The Wayland Protocol - Documentation - 0.1 - 1 - 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. - - - - - - - - - - Wayland logo - - - - - - - - Copyright &YEAR; &HOLDER; - - - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the "Software"), - to deal in the Software without restriction, including without limitation - the rights to use, copy, modify, merge, publish, distribute, sublicense, - and/or sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following conditions: - - - - The above copyright notice and this permission notice (including the next - paragraph) shall be included in all copies or substantial portions of the - Software. - - - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. - - - - - - diff --git a/doc/publican/sources/Client.xml b/doc/publican/sources/Client.xml deleted file mode 100644 index 19bf3e9..0000000 --- a/doc/publican/sources/Client.xml +++ /dev/null @@ -1,92 +0,0 @@ - - - -%BOOK_ENTITIES; -]> - - Client API -
Introduction - - The open-source reference implementation of Wayland protocol is - split in two C libraries, libwayland-client and libwayland-server. Their main - responsibility is to handle the Inter-process communication - (IPC) with each other, therefore guaranteeing - the protocol objects marshaling and messages synchronization. - - - A client uses libwayland-client to communicate with one or more - wayland servers. A wl_display object is - created and manages each open connection to a server. At least one - wl_event_queue - object is created for each wl_display, this holds events as they - are received 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. - - - Though some convenience 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. - - - The library only provides low-level access to the wayland objects. - Each object created by the client is represented by a wl_proxy 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 wl_interface object, - which is generated from the xml and identifies the object's class - and can be used for introspection into the messages and events. - - - 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 Wayland protocols. For - instance the C header file generated from the xml defines the - following inline function to transmit the wl_surface::attach - message: - - 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); -} - - 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 wl_surface::enter - event defines this pointer in the wl_surface_listener object: - - struct wl_surface_listener { - void (*enter)(void *data, struct wl_surface *, struct wl_output *); - ... -} - - -
- &doxygen; - diff --git a/doc/publican/sources/Color.xml b/doc/publican/sources/Color.xml deleted file mode 100644 index ceee779..0000000 --- a/doc/publican/sources/Color.xml +++ /dev/null @@ -1,139 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Color management - -
- Overview - - - Color management in Wayland considers only displays. All pictures in - Wayland are always display-referred, meaning that the pixel values are - intended as-is for some specific display where they would produce the - light emissions (stimuli) the picture's - author desired. Wayland does not support displaying "raw" camera or - scanner images as they are not display-referred, nor are they even - pictures without complex and subjective processing. - - - Stimuli — the picture itself — are only half of the picture reproduction. - The other half is the environment where a display is viewed. A striking - example is comparing a brightly lit office to a dark movie theater, the - stimuli required to produce a good reading of the picture is greatly - different. Therefore display-referred does not include only the display - but the viewing environment as well. - - - Window systems have been very well capable of operating without any - explicit consideration to color management. This is because there used to - be the implicit assumption of the standard display, the sRGB display, - which all computer monitors implemented, more or less. The viewing - environment was and still is accounted by adjusting the display and/or the - room to produce a workable experience. Pictures are authored on a computer - system by drawing, painting and adjusting the picture until it looks right - on the author's monitor. This implicitly builds the standard display and - environment assumption into the picture data. Deviations from the sRGB - specification were minor enough that they often did not matter if not in a - professional context like the printing industry. Displaying video material - required some more attention to the details, because video and television - standards differ enough from the sRGB display. What really made explicit - color management a hard requirement for entertainment is the coming of - wide color gamut (WCG) and high dynamic range (HDR) materials and - displays. - - - The color management design in Wayland follows the general Wayland design - principles: compositors tell clients what would be the optimal thing to - do, clients tell the compositors what kind of pictures they are actually - producing, and then compositors display those pictures the best they can. - -
- -
- Protocol Interfaces - - - Color management interfaces in Wayland and divided into two protocols: - color-management - and - color-representation. - They are designed to work together, but they can also be used - independently when the other one is not needed. - - -
- Color-management - - - Color management protocol has two main purposes. First, it puts the - responsibility of color management on the compositor. This means that - clients do not necessarily need to care about color management at all, - and can display just fine by using the traditional standard display - assumption even when the actual display is wildly different. Clients - can also choose to target some other assumed display and let the - compositor handle it, or they can explicitly render for the actual - display at hand. Second, when the window system has multiple different - monitors, and a wl_surface happens to span more than one monitor, the - compositor can display the surface content correctly on all spanned - monitors simultaneously, as much as physically possible. - - - Color-management protocol concentrates on colorimetry: when you have a - pixel with RGB values, what stimulus do those values represent. The - stimulus definition follows the CIE 1931 two-degree observer model. Some - core concepts here are color primaries, white point, transfer function, - and dynamic range. The viewing environment is represented in an - extremely simplified way as the reference white luminance. The - connection between pixel RGB values and stimulus plus viewing - environment is recorded in an image description - object. Clients can create image description objects and tag - wl_surfaces with them, to indicate what kind of surface - content there will be. Clients can also ask what image description the - compositor would prefer to have on the wl_surface, and that - preference can change over time, e.g. when the wl_surface - is moved from one - wl_output to another. Following the compositor's preference - may provide advantages in image quality and power consumption. - - - Image description objects can come in two flavors: parametric and - ICC-based. The above was written with parametric image descriptions in - mind, and they have first-class support for HDR. ICC-based image - descriptions are wrapping an ICC profile and have no other data. ICC - profiles are the standard tool for standard dynamic range (SDR) display - color management. This means the capabilities between the two flavors - differ, and one cannot always be replaced by the other. Compositor - support for each flavor is optional. - -
- -
- Color-representation - - - Color-representation protocol deals with (potentially sub-sampled) - YCbCr-RGB conversion, quantization range, and the inclusion of alpha in - the RGB color channels, a.k.a. pre-multiplication. There are several - different specifications on how an YCbCr-like (including ICtCp) signal, - with chroma sub-sampling or not, is created from a full-resolution RGB - image. Again, a client can tag a wl_surface with - color-representation metadata to tell the compositor what kind of pixel - data will be displayed through the wl_surface. - - - The main purpose of color-representation is to correctly off-load the - YCbCr-RGB conversion to the compositor, which can then opportunistically - off-load it further to very power-efficient fixed-function circuitry in - a display controller. This can significantly reduce power consumption - when watching videos compared to using a GPU for the same, and on some - embedded hardware platforms it is a hard requirement for processing high - resolution video. - -
-
- diff --git a/doc/publican/sources/Compositors.xml b/doc/publican/sources/Compositors.xml deleted file mode 100644 index 7a7bdaa..0000000 --- a/doc/publican/sources/Compositors.xml +++ /dev/null @@ -1,128 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Types of Compositors - - - Compositors come in different types, depending on which - role they play in the overall architecture of the OS. - For instance, a - system compositor - can be used for booting the system, handling multiple user switching, a - possible console terminal emulator and so forth. A different compositor, a - session compositor - would provide the actual desktop environment. There are many ways for - different types of compositors to co-exist. - - - In this section, we introduce three types of Wayland compositors relying - on libwayland-server. - - -
- System Compositor - - 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. - - - 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). - - - A linux implementation of a system compositor will typically - use libudev, egl, kms, evdev and cairo. - - - For fullscreen clients, the system compositor can reprogram the - video scanout address to read directly from the client provided - buffer. - -
-
- Session Compositor - - 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 hardware. - - - X applications can continue working under a session compositor - by means of a root-less X server that is activated on demand. - - - Possible examples for session compositors include - - - - gnome-shell - - - - - moblin - - - - - kwin - - - - - kmscon - - - - - rdp session - - - - - Weston with X11 or Wayland backend is a session compositor nested - in another session compositor. - - - - - fullscreen X session under Wayland - - - - -
-
- Embedding Compositor - - 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. - - - An example for this kind of setup is firefox embedding the flash - player as a kind of special-purpose compositor. - -
- diff --git a/doc/publican/sources/Foreword.xml b/doc/publican/sources/Foreword.xml deleted file mode 100644 index 46fda2b..0000000 --- a/doc/publican/sources/Foreword.xml +++ /dev/null @@ -1,28 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Preface - - - This document describes the (i) Wayland architecture, (ii) Wayland model of - operation and (iii) its library API. Also, the Wayland protocol specification is shown - in the Appendix. This document is aimed primarily at Wayland developers and - those looking to program with it; it does not cover application development. - - - There have been many contributors to this document and since this is only the - first edition many errors are expected to be found. We appreciate - corrections. - - -Yours, - - the Wayland open-source community - November 2012 - - diff --git a/doc/publican/sources/Introduction.xml b/doc/publican/sources/Introduction.xml deleted file mode 100644 index f2a8274..0000000 --- a/doc/publican/sources/Introduction.xml +++ /dev/null @@ -1,116 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Introduction -
- Motivation - - Most Linux and Unix-based systems rely on the X Window System (or - simply X) 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). - - - 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. - - - - - - - - X architecture diagram - - - - - 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. - - -
- -
- The compositing manager as the display server - - 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 are displayed. Rendering is left - to clients, and system wide memory management interfaces are used to - pass buffer handles between clients and the compositing manager. - - - - - - - - Wayland architecture diagram - - - - - 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). - -
- diff --git a/doc/publican/sources/Preface.xml b/doc/publican/sources/Preface.xml deleted file mode 100644 index 17c6ebf..0000000 --- a/doc/publican/sources/Preface.xml +++ /dev/null @@ -1,20 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Acknowledgments - - - TODO: Kristian has to fill up this with one or two paragraphs and a small - "thank you": http://en.wikipedia.org/wiki/Preface - - -Best, - - Kristian Høgsberg - - diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml deleted file mode 100644 index e4087e9..0000000 --- a/doc/publican/sources/Protocol.xml +++ /dev/null @@ -1,592 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Wayland Protocol and Model of Operation -
- Basic Principles - - 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. - - - 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. - A message has a number of arguments, each of which has a certain type (see - for a list of argument types). - - - Additionally, the protocol can specify enums which associate - names to specific numeric enumeration values. These are primarily just - descriptive in nature: at the wire format level enums are just integers. - But they also serve a secondary purpose to enhance type safety or - otherwise add context for use in language bindings or other such code. - This latter usage is only supported so long as code written before these - attributes were introduced still works after; in other words, adding an - enum should not break API, otherwise it puts backwards compatibility at - risk. - - - enums can be defined as just a set of integers, or as - bitfields. This is specified via the bitfield boolean - attribute in the enum definition. If this attribute is true, - the enum is intended to be accessed primarily using bitwise operations, - for example when arbitrarily many choices of the enum can be ORed - together; if it is false, or the attribute is omitted, then the enum - arguments are a just a sequence of numerical values. - - - The enum attribute can be used on either uint - or int arguments, however if the enum is - defined as a bitfield, it can only be used on - uint args. - - - 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. - - - - - - 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. - - - - - The server will broadcast the presence of a number of global objects, - which in turn will broadcast their current state. - - - - -
-
- Code Generation - - The interfaces, requests and events are defined in - protocol/wayland.xml. - 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 - wrap the 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. - -
-
- Wire Format - - The protocol is sent over a UNIX domain stream socket, where the endpoint - usually is named wayland-0 - (although it can be changed via WAYLAND_DISPLAY - in the environment). Beginning in Wayland 1.15, implementations can - optionally support server socket endpoints located at arbitrary - locations in the filesystem by setting WAYLAND_DISPLAY - to the absolute path at which the server endpoint listens. The socket may - also be provided through file descriptor inheritance, in which case - WAYLAND_SOCKET is set. - - - Every message is structured as 32-bit words; values are represented in the - host's byte-order. The message header has 2 words in it: - - - - The first word is the sender's object ID (32-bit). - - - - - 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. - - - - 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. - - - - The representation of argument types are as follows: - - - int - uint - - - The value is the 32-bit value of the signed/unsigned - int. - - - - - fixed - - - 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. - - - - - string - - - Starts with an unsigned 32-bit length (including null terminator), - followed by the UTF-8 encoded string contents, including - terminating null byte, then padding to a 32-bit boundary. A null - value is represented with a length of 0. Interior null bytes are - not permitted. - - - - - object - - - 32-bit object ID. A null value is represented with an ID of 0. - - - - - new_id - - - The 32-bit object ID. Generally, the interface used for the new - object is inferred from the xml, but in the case where it's not - specified, a new_id is preceded by a string specifying - the interface name, and a uint specifying the version. - - - - - array - - - Starts with 32-bit array size in bytes, followed by the array - contents verbatim, and finally padding to a 32-bit boundary. - - - - - fd - - - The file descriptor is not stored in the message buffer, but in - the ancillary data of the UNIX domain socket message (msg_control). - - - - - - - The protocol does not specify the exact position of the ancillary data - in the stream, except that the order of file descriptors is the same as - the order of messages and fd arguments within messages on - the wire. - - - In particular, it means that any byte of the stream, even the message - header, may carry the ancillary data with file descriptors. - - - Clients and compositors should queue incoming data until they have - whole messages to process, as file descriptors may arrive earlier - or later than the corresponding data bytes. - -
- -
- Versioning - - Every interface is versioned and every protocol object implements a - particular version of its interface. For global objects, the maximum - version supported by the server is advertised with the global and the - actual version of the created protocol object is determined by the - version argument passed to wl_registry.bind(). For objects that are - not globals, their version is inferred from the object that created - them. - - - In order to keep things sane, this has a few implications for - interface versions: - - - - The object creation hierarchy must be a tree. Otherwise, - inferring object versions from the parent object becomes a much - more difficult to properly track. - - - - - When the version of an interface increases, so does the version - of its parent (recursively until you get to a global interface) - - - - - A global interface's version number acts like a counter for all - of its child interfaces. Whenever a child interface gets - modified, the global parent's interface version number also - increases (see above). The child interface then takes on the - same version number as the new version of its parent global - interface. - - - - - - To illustrate the above, consider the wl_compositor interface. It - has two children, wl_surface and wl_region. As of wayland version - 1.2, wl_surface and wl_compositor are both at version 3. If - something is added to the wl_region interface, both wl_region and - wl_compositor will get bumpped to version 4. If, afterwards, - wl_surface is changed, both wl_compositor and wl_surface will be at - version 5. In this way the global interface version is used as a - sort of "counter" for all of its child interfaces. This makes it - very simple to know the version of the child given the version of its - parent. The child is at the highest possible interface version that - is less than or equal to its parent's version. - - - It is worth noting a particular exception to the above versioning - scheme. The wl_display (and, by extension, wl_registry) interface - cannot change because it is the core protocol object and its version - is never advertised nor is there a mechanism to request a different - version. - -
-
- Connect Time - - 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. - -
-
- Security and Authentication - - - - - mostly about access to underlying buffers, need new drm auth - mechanism (the grant-to ioctl idea), need to check the cmd stream? - - - - - 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. - - - - -
-
- Creating Objects - - Each object has a unique ID. The IDs are allocated by the entity - creating the object (either client or server). IDs allocated by the - client are in the range [1, 0xfeffffff] while IDs allocated by the - server are in the range [0xff000000, 0xffffffff]. The 0 ID is - reserved to represent a null or non-existent object. - - For efficiency purposes, the IDs are densely packed in the sense that - the ID N will not be used until N-1 has been used. This ordering is - not merely a guideline, but a strict requirement, and there are - implementations of the protocol that rigorously enforce this rule, - including the ubiquitous libwayland. - -
-
- Compositor - - The compositor is a global object, advertised at connect time. - - - See for the - protocol description. - -
-
- Surfaces - - A surface manages a rectangular grid of pixels that clients create - for displaying their content to the screen. Clients don't know - the global position of their surfaces, and cannot access other - clients' surfaces. - - - Once the client has finished writing pixels, it 'commits' the - buffer; this permits the compositor to access the buffer and read - the pixels. When the compositor is finished, it releases the - buffer back to the client. - - - See for the protocol - description. - -
-
- Input - - 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. - - - 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. - - - 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. - - - 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. - - - See for the - protocol description. - - - Talk about: - - - - - keyboard map, change events - - - - - xkb on Wayland - - - - - multi pointer Wayland - - - - - - 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 to 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 or 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. - - - Setting the pointer image to NULL causes the cursor to be hidden. - - - The compositor will revert the pointer image back to a default image - when no surface has the pointer focus for that device. - - - 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. If a client does not set a pointer image - when the pointer enters a surface, the pointer stays with the image set - by the last surface that changed it, possibly even hidden. Such a client - is likely just broken. - -
-
- Output - - An output is a global object, advertised at connect time or as it - comes and goes. - - - See for the protocol - description. - - - - - - - laid out in a big (compositor) coordinate system - - - - - basically xrandr over Wayland - - - - - geometry needs position in compositor coordinate system - - - - - events to advertise available modes, requests to move and change - modes - - - -
-
- Data sharing between clients - - 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 - wl_data_source object and the clients - obtaining the data will see it as wl_data_offer - 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. - - - The next section explains the negotiation between data source and - data offer objects. - explains how these objects are created and passed to different - clients using the wl_data_device interface - that implements copy-paste and drag-and-drop support. - - - See , - , - and - for - protocol descriptions. - - - MIME is defined in RFC's 2045-2049. A - - registry of MIME types is maintained by the Internet Assigned - Numbers Authority (IANA). - -
- Data negotiation - - A client providing data to other clients will create a wl_data_source - object and advertise the mime types for the formats it supports for - that data through the wl_data_source.offer - request. On the receiving end, the data offer object will generate one - wl_data_offer.offer event for each supported mime - type. - - - The actual data transfer happens when the receiving client sends a - wl_data_offer.receive request. This request takes - a mime type and a file descriptor as arguments. This request will generate a - wl_data_source.send 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. - -
-
- Data devices - - Data devices glue data sources and offers together. A data device is - associated with a wl_seat and is obtained by the clients using the - wl_data_device_manager factory object, which is also responsible for - creating data sources. - - - Clients are informed of new data offers through the - wl_data_device.data_offer 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. - -
- Selection - - 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 - wl_data_device.selection event. This event is - also generated on a client immediately before it receives keyboard - focus. - - - The data offer is introduced with - wl_data_device.data_offer event before the - selection event. - -
-
- Drag and Drop - - A drag-and-drop operation is started using the - wl_data_device.start_drag 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 - wl_data_device.enter event. The data offer - is introduced to the client prior to the enter event with the - wl_data_device.data_offer event. - - - Clients are expected to provide feedback to the data sending client - by calling the wl_data_offer.accept 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 wl_data_source.target event with the - chosen mime type. - - - When the drag ends, the receiving client receives a - wl_data_device.drop event at which it is expected - to transfer the data using the - wl_data_offer.receive request. - -
-
-
- diff --git a/doc/publican/sources/Revision_History.xml b/doc/publican/sources/Revision_History.xml deleted file mode 100644 index 2c540fe..0000000 --- a/doc/publican/sources/Revision_History.xml +++ /dev/null @@ -1,7 +0,0 @@ - - - 1-0 - krh - Initial version - - diff --git a/doc/publican/sources/Server.xml b/doc/publican/sources/Server.xml deleted file mode 100644 index 2333b1a..0000000 --- a/doc/publican/sources/Server.xml +++ /dev/null @@ -1,49 +0,0 @@ - - - -%BOOK_ENTITIES; -]> - - Server API -
Introduction - - The open-source reference implementation of Wayland protocol is - split in two C libraries, libwayland-client and - libwayland-server. Their main responsibility is to handle the - Inter-process communication (IPC) with each - other, therefore guaranteeing the protocol objects marshaling and - messages synchronization. - - - 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. - - - Each open socket to a client is represented by a wl_client. The equivalent - of the wl_proxy that - libwayland-client uses to represent an object is wl_resource for - client-created objects, and wl_global for objects - created by the server. - - - 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 client wl_display and - server wl_display, - 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. - -
- &doxygen; - diff --git a/doc/publican/sources/Wayland.ent b/doc/publican/sources/Wayland.ent deleted file mode 100644 index da18a95..0000000 --- a/doc/publican/sources/Wayland.ent +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/doc/publican/sources/Wayland.xml b/doc/publican/sources/Wayland.xml deleted file mode 100644 index 7593097..0000000 --- a/doc/publican/sources/Wayland.xml +++ /dev/null @@ -1,19 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - - - - - - - - - - - - diff --git a/doc/publican/sources/Xwayland.xml b/doc/publican/sources/Xwayland.xml deleted file mode 100644 index 7915559..0000000 --- a/doc/publican/sources/Xwayland.xml +++ /dev/null @@ -1,170 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - X11 Application Support -
- Introduction - - Being able to run existing X11 applications is crucial for the adoption - of Wayland, especially on desktops, as there will always be X11 - applications that have not been or cannot be converted into Wayland - applications, and throwing them all away would be prohibitive. - Therefore a Wayland compositor often needs to support running X11 - applications. - - - X11 and Wayland are different enough that there is no "simple" way to - translate between them. Most of X11 is uninteresting to a Wayland - compositor. That, combined with the gigantic implementation effort needed - to support X11, makes it intractable to just write X11 support directly in - a Wayland compositor. The implementation would be nothing short of a - real X11 server. - - - Therefore, Wayland compositors should use Xwayland, the X11 server that - lives in the Xorg server source code repository and shares most of the - implementation with the Xorg server. Xwayland is a complete X11 server, - just like Xorg is, but instead of driving the displays and opening input - devices, it acts as a Wayland client. The rest of this chapter talks - about how Xwayland works. - - - For integration and architecture reasons, while Xwayland is a Wayland - client of the Wayland compositor, the Wayland compositor is an X11 client - of Xwayland. This circular dependency requires special care from the - Wayland compositor. - -
-
- Two Modes for Foreign Windows - - In general, windows from a foreign window system can be presented in one - of two ways: rootless and rootful (not rootless). - - - In rootful mode, the foreign window system as a whole is represented as a - window (or more) of its own. You have a native window, inside which all - the foreign windows are. The advantage of this approach in Xwayland's - case is that you can run your favourite X11 window manager to manage your - X11 applications. The disadvantage is that the foreign windows do not - integrate with the native desktop. Therefore this mode is not usually - used. - - - In rootless mode, each foreign window is a first-class resident among the - native windows. Foreign windows are not confined inside a native window - but act as if they were native windows. The advantage is that one can - freely stack and mix native and foreign windows, which is not possible in - rootful mode. The disadvantage is that this mode is harder to implement - and fundamental differences in window systems may prevent some things - from working. With rootless Xwayland, the Wayland compositor must take - the role as the X11 window manager, and one cannot use any other X11 - window manager in its place. - - - This chapter concentrates on the rootless mode, and ignores the rootful - mode. - -
-
- Architecture - - A Wayland compositor usually takes care of launching Xwayland. - Xwayland works in cooperation with a Wayland compositor as follows: - -
- Xwayland architecture diagram - - - - - - - -
- - An X11 application connects to Xwayland just like it would connect to any - X server. Xwayland processes all the X11 requests. On the other end, - Xwayland is a Wayland client that connects to the Wayland compositor. - - - The X11 window manager (XWM) is an integral part of the Wayland - compositor. XWM uses the usual X11 window management protocol to manage - all X11 windows in Xwayland. Most importantly, XWM acts as a bridge - between Xwayland window state and the Wayland compositor's window manager - (WWM). This way WWM can manage all windows, both native Wayland and X11 - (Xwayland) windows. This is very important for a coherent user - experience. - - - Since Xwayland uses Wayland for input and output, it does not have any - use for the device drivers that Xorg uses. None of the xf86-video-* or - xf86-input-* modules are used. There also is no configuration file for - the Xwayland server. For optional hardware accelerated rendering, - Xwayland uses GLAMOR. - - - A Wayland compositor usually spawns only one Xwayland instance. This is - because many X11 applications assume they can communicate with other X11 - applications through the X server, and this requires a shared X server - instance. This also means that Xwayland does not protect nor isolate X11 - clients from each other, unless the Wayland compositor specifically - chooses to break the X11 client intercommunications by spawning - application specific Xwayland instances. X11 clients are naturally - isolated from Wayland clients. - - - Xwayland compatibility compared to a native X server will probably never - reach 100%. Desktop environment (DE) components, specifically X11 window - managers, are practically never supported. An X11 window manager would - not know about native Wayland windows, so it could manage only X11 - windows. On the other hand, there must be an XWM that reserves the - exclusive window manager role so that the Wayland compositor could show - the X11 windows appropriately. For other DE components, like pagers and - panels, adding the necessary interfaces to support them in WWM through XWM - is often considered not worthwhile. - -
-
- X Window Manager (XWM) - - From the X11 point of view, the X window manager (XWM) living inside a - Wayland compositor is just like any other window manager. The difference - is mostly in which process it resides in, and the few extra conventions - in the X11 protocol to support Wayland window management (WWM) - specifically. - - - There are two separate asynchronous communication channels between - Xwayland and a Wayland compositor: one uses the Wayland protocol, and the - other one, solely for XWM, uses X11 protocol. This setting demands great - care from the XWM implementation to avoid (random) deadlocks with - Xwayland. It is often nearly impossible to prove that synchronous or - blocking X11 calls from XWM cannot cause a deadlock, and therefore it is - strongly recommended to make all X11 communications asynchronous. All - Wayland communications are already asynchronous by design. - -
- Window identification - - In Xwayland, an X11 window may have a corresponding wl_surface object - in Wayland. The wl_surface object is used for input and output: it is - referenced by input events and used to provide the X11 window content - to the Wayland compositor. The X11 window and the wl_surface live in - different protocol streams, and they need to be matched for XWM to do - its job. - - - When Xwayland creates a wl_surface on Wayland, it will also send an X11 - ClientMessage of type atom "WL_SURFACE_ID" to the X11 window carrying - the wl_surface Wayland object ID as the first 32-bit data element. This - is how XWM can associate a wl_surface with an X11 window. Note that - the request to create a wl_surface and the ID message may arrive in any - order in the Wayland compositor. - -
-
- diff --git a/doc/publican/sources/css/brand.css b/doc/publican/sources/css/brand.css deleted file mode 100644 index d86cba9..0000000 --- a/doc/publican/sources/css/brand.css +++ /dev/null @@ -1,14 +0,0 @@ -/*headings*/ -h1, h2, h3, h4, h5, h6, -div.producttitle, -div.subtitle, -div.author div.author, -div.translator div.translator, -div.othercredit div.othercredit, -div.editor div.editor, -div.contrib div.contrib, -.title, -.titlepage .edition, -.titlepage .releaseinfo { - color: #336699; -} diff --git a/doc/publican/sources/css/common.css b/doc/publican/sources/css/common.css deleted file mode 100644 index a05648e..0000000 --- a/doc/publican/sources/css/common.css +++ /dev/null @@ -1,1769 +0,0 @@ -* { - widows: 4 !important; - orphans: 4 !important; -} - -body, h1, h2, h3, h4, h5, h6, pre, li, div { - line-height: 1.29em; -} - -body { - background-color: white; - margin:0 auto; - font-family: "liberation sans", "Myriad ", "Bitstream Vera Sans", "Lucida Grande", "Luxi Sans", "Trebuchet MS", helvetica, verdana, arial, sans-serif; - font-size: 14px; - max-width: 770px; - color: black; -} - -body.toc_embeded { - /*for web hosting system only*/ - margin-left: 300px; -} - -object.toc, iframe.toc { - /*for web hosting system only*/ - border-style: none; - position: fixed; - width: 290px; - height: 99.99%; - top: 0; - left: 0; - z-index: 100; - border-style: none; - border-right:1px solid #999; -} - -/* Hide web menu */ - -body.notoc { - margin-left: 3em; -} - -iframe.notoc { - border-style:none; - border: none; - padding: 0px; - position:fixed; - width: 21px; - height: 29px; - top: 0px; - left:0; - overflow: hidden; - margin: 0px; - margin-left: -3px; -} -/* End hide web menu */ - -/* desktop styles */ -body.desktop { - margin-left: 26em; -} - -body.desktop .book > .toc { - display:block; - width:24em; - height:99.99%; - position:fixed; - overflow:auto; - top:0px; - left:0px; -/* padding-left:1em; */ - background-color:#EEEEEE; - font-size: 12px; -} - -body.pdf { - max-width: 100%; -} - -.toc { - line-height:1.35em; -} - -.toc .glossary, -.toc .chapter, .toc .appendix { - margin-top:1em; -} - -.toc .part { - margin-top:1em; - display:block; -} - -span.glossary, -span.appendix { - display:block; - margin-top:0.5em; -} - -div { - padding-top:0px; -} - -div.section { - page-break-inside: avoid; -} - -p, div.para { - padding-top: 0px; - margin-top: 1em; - padding-bottom: 0px; - margin-bottom: 1em; -} - -div.formalpara { - padding-top: 0px; - margin-top: 1em; - padding-bottom: 0px; - margin-bottom: 1em; -} - -.varlistentry div.para { - page-break-before: avoid; - -} - -/*Links*/ -a { - outline: none; -} - -a:link { - text-decoration: none; - border-bottom: 1px dotted ; - color:#3366cc; -} - -body.pdf a:link { - word-wrap: break-word; -} - -a:visited { - text-decoration:none; - border-bottom: 1px dotted ; - color:#003366; -} - -div.longdesc-link { - float:right; - color:#999; -} - -.toc a, .qandaset a { - font-weight:normal; - border:none; -} - -.toc a:hover, .qandaset a:hover -{ - border-bottom: 1px dotted; -} - -/*headings*/ -h1, h2, h3, h4, h5, h6 { - color: #336699; - margin-top: 0px; - margin-bottom: 0px; - background-color: transparent; - margin-bottom: 0px; - margin-top: 20px; - page-break-inside: avoid; - page-break-after: avoid; - word-wrap: break-word; -} - -h1 { - font-size: 22px; -} - -.titlepage h1.title { - text-align:left; -} - -.book > .titlepage h1.title { - text-align: center; -} - -.article > .titlepage h1.title, -.article > .titlepage h2.title { - text-align: center; -} - -.set .titlepage > div > div > h1.title { - text-align: center; -} - -.part > .titlepage h1.title { - text-align: center; - font-size: 24px; -} - -div.producttitle { - margin-top: 0px; - margin-bottom: 20px; - font-size: 48px; - font-weight: bold; -/* background: #003d6e url(../images/h1-bg.png) top left repeat-x; */ - color: #336699; - text-align: center; - padding-top: 12px; -} - -.titlepage .corpauthor { - margin-top: 1em; - text-align: center; -} - -.section h1.title { - font-size: 18px; - padding: 0px; - color: #336699; - text-align: left; - background: white; -} - -h2 { - font-size: 20px; - margin-top: 30px; -} - - -.book div.subtitle, .book h2.subtitle, .book h3.subtitle { - margin-top: 1em; - margin-bottom: 1em; - font-size: 18px; - text-align: center; -} - -div.subtitle { - color: #336699; - font-weight: bold; -} - -h1.legalnotice { - font-size: 24px; -} - -.preface > div > div > div > h2.title, -.preface > div > div > div > h1.title { - margin-top: 1em; - font-size: 24px; -} - -.appendix h2 { - font-size: 24px; -} - - - -h3 { - font-size: 14px; - padding-top:0px; - padding-bottom: 0px; - margin-bottom: 0px; -} -h4 { - font-size: 14px; - padding-top:0px; - padding-bottom:0px; -} - -h5 { - font-size: 14px; -} - -h6 { - font-size: 14px; - margin-bottom: 0px; -} - -.abstract h6 { - margin-top:1em; - margin-bottom:.5em; - font-size: 24px; -} - -.index > div > div > div > h2.title { - font-size: 24px; -} - -.chapter > div > div > div > h2.title { - font-size: 24px; -} - -.section > div > div > div > h2.title { - font-size: 21px; - page-break-inside: avoid; - page-break-before: avoid; - page-break-after: avoid; -} - -.section > div > div > div > h3.title { - font-size: 17px; -} - -/*element rules*/ -hr { - border-collapse: collapse; - border-style:none; - border-top: 1px dotted #ccc; - width:100%; -} - -/* web site rules */ -ul.languages, .languages li { - display:inline; - padding:0px; -} - -.languages li a { - padding:0px .5em; - text-decoration: none; -} - -.languages li p, .languages li div.para { - display:inline; -} - -.languages li a:link, .languages li a:visited { - color:#444; -} - -.languages li a:hover, .languages li a:focus, .languages li a:active { - color:black; -} - -ul.languages { - display:block; - background-color:#eee; - padding:.5em; -} - -/*supporting stylesheets*/ - -/*unique to the webpage only*/ -.books { - position:relative; -} - -.versions li { - width:100%; - clear:both; - display:block; -} - -a.version { - font-size: 20px; - text-decoration:none; - width:100%; - display:block; - padding:1em 0px .2em 0px; - clear:both; -} - -a.version:before { - content:"Version"; - font-size: smaller; -} - -a.version:visited, a.version:link { - color:#666; -} - -a.version:focus, a.version:hover { - color:black; -} - -.books { - display:block; - position:relative; - clear:both; - width:100%; -} - -.books li { - display:block; - width:200px; - float:left; - position:relative; - clear: none ; -} - -.books .html { - width:170px; - display:block; -} - -.books .pdf { - position:absolute; - left:170px; - top:0px; - font-size: smaller; -} - -.books .pdf:link, .books .pdf:visited { - color:#555; -} - -.books .pdf:hover, .books .pdf:focus { - color:#000; -} - -.books li a { - text-decoration:none; -} - -.books li a:hover { - color:black; -} - -/*products*/ -.products li { - display: block; - width:300px; - float:left; -} - -.products li a { - width:300px; - padding:.5em 0px; -} - -.products ul { - clear:both; -} - -/*revision history*/ -.revhistory { - display:block; -} - -.revhistory table { - background-color:transparent; - border-color:#fff; - padding:0px; - margin: 0; - border-collapse:collapse; - border-style:none; -} - -.revhistory td { - text-align :left; - padding:0px; - border: none; - border-top: 1px solid #fff; - font-weight: bold; -} - -.revhistory .simplelist td { - font-weight: normal; -} - -.revhistory .simplelist { - margin-bottom: 1.5em; - margin-left: 1em; -} - -.revhistory table th { - display: none; -} - - -/*credits*/ -.authorgroup div { - clear:both; - text-align: center; -} - -div.author div.author, -div.translator div.translator, -div.othercredit div.othercredit, -div.editor div.editor, -div.contrib div.contrib { - margin: 0px; - padding: 0px; - margin-top: 12px; - font-size: 14px; - font-weight: bold; - color: #336699; -} - -div.editedby { - margin-top: 15px; - margin-bottom: -0.8em; -} - -div.authorgroup .author, -div.authorgroup.editor, -div.authorgroup.translator, -div.authorgroup.othercredit, -div.authorgroup.contrib { - display: block; - font-size: 14px; - page-break-inside: avoid; -} - -.revhistory .author { - display: inline; -} - -.othercredit h3 { - padding-top: 1em; -} - - -.othercredit { - margin:0px; - padding:0px; -} - -.releaseinfo { - clear: both; -} - -.copyright { - margin-top: 1em; -} - -/* qanda sets */ -.answer { - margin-bottom:1em; - border-bottom:1px dotted #ccc; -} - -.qandaset .toc { - border-bottom:1px dotted #ccc; -} - -.question { - font-weight:bold; -} - -.answer .data, .question .data { - padding-left: 2.6em; -} - -.answer .label, .question .label { - float:left; - font-weight:bold; -} - -/* inline syntax highlighting */ -.perl_Alert { - color: #0000ff; -} - -.perl_BaseN { - color: #007f00; -} - -.perl_BString { - color: #5C3566; -} - -.perl_Char { - color: #ff00ff; -} - -.perl_Comment { - color: #888888; -} - - -.perl_DataType { - color: #0000ff; -} - - -.perl_DecVal { - color: #00007f; -} - - -.perl_Error { - color: #ff0000; -} - - -.perl_Float { - color: #00007f; -} - - -.perl_Function { - color: #007f00; -} - - -.perl_IString { - color: #5C3566; -} - - -.perl_Keyword { - color: #002F5D; -} - - -.perl_Operator { - color: #ffa500; -} - - -.perl_Others { - color: #b03060; -} - - -.perl_RegionMarker { - color: #96b9ff; -} - - -.perl_Reserved { - color: #9b30ff; -} - - -.perl_String { - color: #5C3566; -} - - -.perl_Variable { - color: #0000ff; -} - - -.perl_Warning { - color: #0000ff; -} - -/*Lists*/ -ul { - list-style-image: url("../images/dot.png"); - list-style-type: circle; - padding-left: 1.6em; -} - -ul ul { - list-style-image: url("../images/dot2.png"); - list-style-type: circle; -} - -ol.1 { - list-style-type: decimal; -} - -ol.a, -ol ol { - list-style-type: lower-alpha; -} - -ol.i { - list-style-type: lower-roman; -} -ol.A { - list-style-type: upper-alpha; -} - -ol.I { - list-style-type: upper-roman; -} - -dt { - font-weight:bold; - margin-bottom:0px; - padding-bottom:0px; -} - -dd { - margin:0px; - margin-left:2em; - padding-top:0px; -} - -li { - padding-top: 0px; - margin-top: 0px; - padding-bottom: 0px; -/* margin-bottom: 16px; */ -} - -/*images*/ -img { - display:block; - margin: 2em 0; - max-width: 100%; -} - -.inlinemediaobject, -.inlinemediaobject img, -.inlinemediaobject object { - display:inline; - margin:0px; - overflow: hidden; -} - -.figure { - margin-top: 1em; - width: 100%; -} - -.figure img, -.mediaobject img { - display:block; - margin: 0em; - page-break-inside: avoid; -} - -.figure .title { - margin-bottom:2em; - padding:0px; -} - -/*document modes*/ -.confidential { - background-color:#900; - color:White; - padding:.5em .5em; - text-transform:uppercase; - text-align:center; -} - -.longdesc-link { - display:none; -} - -.longdesc { - display:none; -} - -.prompt { - padding:0px .3em; -} - -/*user interface styles*/ -.screen .replaceable { -} - -.guibutton, .guilabel { - font-family: "liberation mono", "bitstream vera mono", "dejavu mono", monospace; - font-weight: bold; -} - -.example { - background-color: #ffffff; - border-left: 3px solid #aaaaaa; - padding-top: 1px; - padding-bottom: 0.1em; - padding-left: 1em; -} - -.equation { - border-left: 3px solid #aaaaaa; - background-color: #ffffff; - padding-top: 1px; - padding-bottom: 0.1em; - padding-left: 1em; -} - -.equation-contents { - margin-left: 4em; -} - -div.title { - margin-bottom: 1em; - font-weight: 14px; - font-weight: bold; - color: #336699; - page-break-inside: avoid; - page-break-after: avoid; - word-wrap: break-word; -} - -.example-contents { - background-color: #ffffff; -} - -.example-contents .para { -/* padding: 10px;*/ -} - -/*terminal/console text*/ -.computeroutput, -.option { - font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; - font-weight:bold; -} - -.replaceable { - font-style: italic; -} - -.command, .filename, .keycap, .classname, .literal { - font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; - font-weight:bold; -} - -/* no bold in toc */ -.toc * { - font-weight: inherit; -} - -.toc H1 { - font-weight: bold; -} - - -div.programlisting { - white-space: pre-wrap; /* css-3 */ - white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */ - white-space: -pre-wrap; /* Opera 4-6 */ - white-space: -o-pre-wrap; /* Opera 7 */ - word-wrap: break-word; /* Internet Explorer 5.5+ */ -} - -pre { - font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; - display:block; - background-color: #f5f5f5; - color: #000000; -/* border: 1px solid #aaaaaa; */ - margin-bottom: 1em; - padding:.5em 1em; - white-space: pre-wrap; /* css-3 */ - white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */ - white-space: -pre-wrap; /* Opera 4-6 */ - white-space: -o-pre-wrap; /* Opera 7 */ - word-wrap: break-word; /* Internet Explorer 5.5+ */ - font-size: 0.9em; - border-style:none; - box-shadow: 0 2px 5px #AAAAAA inset; - -moz-box-shadow: 0 2px 5px #AAAAAA inset; - -webkit-box-shadow: 0 2px 5px #AAAAAA inset; - -o-box-shadow: 0 2px 5px #AAAAAA inset; -} - -body.pdf pre { - border: 1px solid #AAAAAA; - box-shadow: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - -o-box-shadow: none; -} - - -pre .replaceable, -pre .keycap { -} - -code { - font-family:"liberation mono", "bitstream vera mono", "dejavu mono", monospace; - white-space: pre-wrap; - word-wrap: break-word; - font-weight:bold; -} - -.parameter code { - display: inline; - white-space: pre-wrap; /* css-3 */ - white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */ - white-space: -pre-wrap; /* Opera 4-6 */ - white-space: -o-pre-wrap; /* Opera 7 */ - word-wrap: break-word; /* Internet Explorer 5.5+ */ -} - -code.email { - font-weight: normal; - font-family: "liberation sans", "Myriad ", "Bitstream Vera Sans", "Lucida Grande", "Luxi Sans", "Trebuchet MS", helvetica, verdana, arial, sans-serif; - -} - -/*Notifications*/ -div.warning:before { - content:url(../images/warning.png); - padding-left: 5px; -} - -div.note:before { - content:url(../images/note.png); - padding-left: 5px; -} - -div.important:before { - content:url(../images/important.png); - padding-left: 5px; -} - -div.warning, div.note, div.important { - color: black; - margin: 0px; - padding: 0px; - background: none; - background-color: white; - margin-bottom: 1em; - border-bottom: 1px solid #aaaaaa; - page-break-inside: avoid; -} - -div.admonition_header p { - margin: 0px; - padding: 0px; - color: #eeeeec; - padding-top: 0px; - padding-bottom: 0px; - height: 1.4em; - line-height: 1.4em; - font-size: 17px; - display:inline; -} - -div.admonition_header { - background-origin:content-box; - clear: both; - margin: 0px; - padding: 0px; - margin-top: -40px; - padding-left: 58px; - line-height: 1.0px; - font-size: 1.0px; -} - -div.warning div.admonition_header { - background: url(../images/red.png) top left repeat-x; - background-color: #590000; - background: -webkit-linear-gradient(#a40000,#590000); - background: linear-gradient(#a40000,#590000); -} - -div.note div.admonition_header { - background: url(../images/green.png) top right repeat-x; - background-color: #597800; - background: -webkit-linear-gradient(#769f00,#597800); - background: linear-gradient(#769f00,#597800); -} - -div.important div.admonition_header { - background: url(../images/yellow.png) top right repeat-x; - background-color: #a6710f; - background: -webkit-linear-gradient(#d08e13,#a6710f); - background: linear-gradient(#d08e13,#a6710f); -} - -div.warning p:first-child, -div.warning div.para:first-child, -div.note p:first-child, -div.note div.para:first-child, -div.important p:first-child, -div.important div.para:first-child { - padding: 0px; - margin: 0px; -} - -div.admonition { - border: none; - border-left: 1px solid #aaaaaa; - border-right: 1px solid #aaaaaa; - padding:0px; - margin:0px; - padding-top: 1.5em; - padding-bottom: 1em; - padding-left: 2em; - padding-right: 1em; - background-color: #eeeeec; - -moz-border-radius: 0px; - -webkit-border-radius: 0px; - border-radius: 0px; -} - -/*Page Title*/ -#title { - display:block; - height:45px; - padding-bottom:1em; - margin:0px; -} - -#title a.left{ - display:inline; - border:none; -} - -#title a.left img{ - border:none; - float:left; - margin:0px; - margin-top:.7em; -} - -#title a.right { - padding-bottom:1em; -} - -#title a.right img { - border:none; - float:right; - margin:0px; - margin-top:.7em; -} - -/*Table*/ -div.table { -/* page-break-inside: avoid; */ -} - -table { - border: 1px solid #444; - width:100%; - border-collapse:collapse; - table-layout: fixed; - word-wrap: break-word; -} - -table.blockquote, -table.simplelist, -.calloutlist table { - border-style: none; -} - -table th { - text-align:left; - background-color:#6699cc; - padding:.3em .5em; - color:white; -} - -table td { - padding:.15em .5em; -} - -table tr.even td { - background-color:#f5f5f5; -} - -tr:nth-child(even) { - background-color: #eeeeee; - -} - - -table th p:first-child, table td p:first-child, table li p:first-child, -table th div.para:first-child, table td div.para:first-child, table li div.para:first-child { - margin-top:0px; - padding-top:0px; - display:inline; -} - -th, td { - border-style:none; - vertical-align: top; -/* border: 1px solid #000; */ -} - -.blockquote td, -.simplelist th, -.simplelist td { - border: none; -} - -table table td { - border-bottom:1px dotted #aaa; - background-color:white; - padding:.6em 0px; -} - -table table { - border:1px solid white; -} - -td.remarkval { - color:#444; -} - -td.fieldval { - font-weight:bold; -} - -.lbname, .lbtype, .lbdescr, .lbdriver, .lbhost { - color:white; - font-weight:bold; - background-color:#999; - width:120px; -} - -td.remarkval { - width:230px; -} - -td.tname { - font-weight:bold; -} - -th.dbfield { - width:120px; -} - -th.dbtype { - width:70px; -} - -th.dbdefault { - width:70px; -} - -th.dbnul { - width:70px; -} - -th.dbkey { - width:70px; -} - -span.book { - margin-top:4em; - display:block; - font-size: 11pt; -} - -span.book a{ - font-weight:bold; -} -span.chapter { - display:block; -} - -table.simplelist td, .calloutlist table td { - border-style: none; -} - - -table.lt-4-cols.lt-7-rows td { - border: none; -} -/*to simplify layout*/ - - -table.lt-4-cols.gt-14-rows tr:nth-child(odd) { - background-color: #fafafa; -} -/* to keep simple but stripe rows */ - - -.gt-8-cols td { - border-left: 1px solid #ccc; -} - -.gt-8-cols td:first-child { - border-left: 0; -} -/* to apply vertical lines to differentiate columns*/ - -/*Breadcrumbs*/ -#breadcrumbs ul li.first:before { - content:" "; -} - -#breadcrumbs { - color:#900; - padding:3px; - margin-bottom:25px; -} - -#breadcrumbs ul { - margin-left:0; - padding-left:0; - display:inline; - border:none; -} - -#breadcrumbs ul li { - margin-left:0; - padding-left:2px; - border:none; - list-style:none; - display:inline; -} - -#breadcrumbs ul li:before { - content:"\0020 \0020 \0020 \00BB \0020"; - color:#333; -} - -dl { - margin-top: 0px; - margin-left: 28px; -} - -.toc dl { - margin-left: 10px; -} - -/*index*/ -.glossary h3, -.index h3 { - font-size: 20px; - color:#aaa; - margin:0px; -} - -.indexdiv { - margin-bottom:1em; -} - -.glossary dt, -.index dt { - color:#444; - padding-top:.5em; -} - -.glossary dl dl dt, -.index dl dl dt { - color:#777; - font-weight:normal; - padding-top:0px; -} - -.index dl dl dt:before { - content:"- "; - color:#ccc; -} - -/*changes*/ -.footnote { - font-size: 10px; - margin: 0px; - color: #222; -} - -.footnotes { - margin-bottom: 60px; -} - -table .footnote { -} - -sup { - margin:0px; - padding:0px; - font-size: 10px; - padding-left:0px; -} - -.footnote { - position:relative; -} - -.footnote sup { - color: black; - left: .4em; -} - -.footnote a:link, -.footnote a:visited { - text-decoration:none; - border: none; -} - -.footnote .para sup { -/* position:absolute; */ - vertical-align:text-bottom; -} - -a.footnote { - padding-right: 0.5em; - text-decoration:none; - border: none; -} - -.footnote sup a:link, -.footnote sup a:visited { - color:#92917d; - text-decoration:none; -} - -.footnote:hover sup a { - text-decoration:none; -} - -.footnote p,.footnote div.para { - padding-left:1em; -} - -.footnote a:link, -.footnote a:visited before{ - color:#00537c; -} - -.footnote a:hover { -} - -/**/ -.pdf-break { - page-break-before: always; -} - -div.legalnotice { - page-break-before: always; -} - -div.abstract { - page-break-before: always; -/* page-break-after: always;*/ -} - -div.chapter { - page-break-before: always; -} - - -div.titlepage, div.titlepage > div, div.titlepage > div > div { - page-break-inside: avoid; - page-break-after: avoid; -} - -div.preface, div.part { - page-break-before: always; -} - -div.appendix { - page-break-before: always; -} - -div.section { - page-break-inside: auto; - page-break-before: auto; - page-break-after: auto; -} - - -dt.varlistentry { - page-break-inside: avoid; - page-break-after: avoid; -} - -dd { - page-break-before: avoid; -} - -div.note .replaceable, -div.important .replaceable, -div.warning .replaceable, -div.note .keycap, -div.important .keycap, -div.warning .keycap -{ -} - -ul li p:last-child, ul li para:last-child { - margin-bottom:0px; - padding-bottom:0px; -} - -/*document navigation*/ -.docnav a, .docnav strong { - border:none; - text-decoration:none; - font-weight:normal; -} - -.docnav { - list-style:none; - margin:0px; - padding:0px; - position:relative; - width:100%; - padding-bottom:2em; - padding-top:1em; - height:2.5em; - line-height:2.5em; -/* - border-top:1px dotted #ccc; - background-color: rgba(240, 240, 240, 0.9); --webkitbox-shadow: 0px .15em .5em rgba(0,0,0,0.2); - -moz-box-shadow: 0px .15em .5em rgba(0,0,0,0.2); - box-shadow: 0px .15em .5em rgba(0,0,0,0.2); -*/ -} - -.docnav li { - list-style:none; - margin:0px; - padding:0px; - display:inline; - font-size: 14px; -} - -.docnav li:before { - content:" "; -} - -.docnav li.previous, .docnav li.next { - position:absolute; - top:1.5em; -} - -.docnav li.up, .docnav li.home { - margin:0px 1.5em; -} - -.docnav.top li.home { - color: #336699; - font-size: 22pt; - font-weight: bold; -} - - -.docnav li.previous { - left:0px; - text-align:left; -} - -.docnav li.next { - right:0px; - text-align:right; -} - -.docnav li.previous strong, .docnav li.next strong { - height: 17px; - display: block; -} - -.docnav { - margin:0 auto; - text-align:center; -} - -.docnav li.next a strong { - background: url(../images/stock-go-forward.png) right 120% no-repeat; - padding-top:3px; - padding-bottom:4px; - padding-right:28px; -} - -.docnav li.previous a strong { - background: url(../images/stock-go-back.png) left 120% no-repeat; - padding-top:3px; - padding-bottom:4px; - padding-left:28px; - padding-right:0.5em; -} - -.docnav li.home a strong { - background: url(../images/stock-home.png) top left no-repeat; - padding:5px; - padding-left:28px; -} - -.docnav li.up a strong { - background: url(../images/stock-go-up.png) top left no-repeat; - padding:5px; - padding-left:28px; -} - -.docnav a:link, .docnav a:visited { - color:#666; -} - -.docnav a:hover, .docnav a:focus, .docnav a:active { - color:black; -} - -.docnav a { - max-width: 10px; - overflow:hidden; -} - -.docnav a:link strong { - text-decoration:none; -} - -.docnav { - margin:0 auto; - text-align:center; -} - -ul.docnav { - margin-bottom: 1em; -} -/* Reports */ -.reports ul { - list-style:none; - margin:0px; - padding:0px; -} - -.reports li{ - margin:0px; - padding:0px; -} - -.reports li.odd { - background-color: #eeeeee; - margin:0px; - padding:0px; -} - -.reports dl { - display:inline; - margin:0px; - padding:0px; - float:right; - margin-right: 17em; - margin-top:-1.3em; -} - -.reports dt { - display:inline; - margin:0px; - padding:0px; -} - -.reports dd { - display:inline; - margin:0px; - padding:0px; - padding-right:.5em; -} - -.reports h2, .reports h3{ - display:inline; - padding-right:.5em; - font-size: 14px; - font-weight:normal; -} - -.reports div.progress { - display:inline; - float:right; - width:16em; - background:#c00 url(../images/shine.png) top left repeat-x; - margin:0px; - margin-top:-1.3em; - padding:0px; - border:none; -} - -/*uniform*/ -body.results, body.reports { - max-width:57em ; - padding:0px; -} - -/*Progress Bar*/ -div.progress { - display:block; - float:left; - width:16em; - background:#c00 url(../images/shine.png) top left repeat-x; - height:1em; -} - -div.progress span { - height:1em; - float:left; -} - -div.progress span.translated { - background:#6c3 url(../images/shine.png) top left repeat-x; -} - -div.progress span.fuzzy { - background:#ff9f00 url(../images/shine.png) top left repeat-x; -} - - -/*Results*/ - -.results ul { - list-style:none; - margin:0px; - padding:0px; -} - -.results li{ - margin:0px; - padding:0px; -} - -.results li.odd { - background-color: #eeeeee; - margin:0px; - padding:0px; -} - -.results dl { - display:inline; - margin:0px; - padding:0px; - float:right; - margin-right: 17em; - margin-top:-1.3em; -} - -.results dt { - display:inline; - margin:0px; - padding:0px; -} - -.results dd { - display:inline; - margin:0px; - padding:0px; - padding-right:.5em; -} - -.results h2, .results h3 { - display:inline; - padding-right:.5em; - font-size: 14px; - font-weight:normal; -} - -.results div.progress { - display:inline; - float:right; - width:16em; - background:#c00 url(../images/shine.png) top left repeat-x; - margin:0px; - margin-top:-1.3em; - padding:0px; - border:none; -} - -/* Dirty EVIL Mozilla hack for round corners */ -pre { - -moz-border-radius:11px; - -webkit-border-radius:11px; - border-radius: 11px; -/* page-break-inside: avoid; */ -} - -.example { - -moz-border-radius:0px; - -webkit-border-radius:0px; - border-radius: 0px; - page-break-inside: avoid; -} - -/* move these invisible fields out of the flow */ -.example > a:first-child, -.table > a:first-child { - float: left; -} - -.package, .citetitle { - font-style: italic; -} - -.titlepage .edition, -.titlepage .releaseinfo { - color: #336699; - background-color: transparent; - margin-top: 1em; - margin-bottom: 1em; - font-size: 20px; - font-weight: bold; - text-align: center; -} - -span.remark { - background-color: #ff00ff; -} - -.draft { - background-image: url(../images/watermark-draft.png); - background-repeat: repeat-y; - background-position: center; -} - -.foreignphrase { - font-style: inherit; -} - -dt { - clear:both; - page-break-inside: avoid; - page-break-after: avoid; -} - -dt img { - border-style: none; - max-width: 112px; -} - -dt object { - max-width: 112px; -} - -dt .inlinemediaobject, dt object { - display: inline; - float: left; - margin-bottom: 1em; - padding-right: 1em; - width: 112px; -} - -dl:after { - display: block; - clear: both; - content: ""; -} - -.toc dd { - padding-bottom: 0px; - margin-bottom: 1em; - padding-left: 1.3em; - margin-left: 0px; -} - -div.toc > dl > dt { - padding-bottom: 0px; - margin-bottom: 0px; - margin-top: 1em; -} - - -.strikethrough { - text-decoration: line-through; -} - -.underline { - text-decoration: underline; -} - -.calloutlist img, .callout { - padding: 0px; - margin: 0px; - width: 12pt; - display: inline; - vertical-align: middle; -} - -li.step > a:first-child { - display: block; -} - -.stepalternatives { - list-style-image: none; - list-style-type: upper-alpha; -} -.task { -/* page-break-inside: avoid; */ -} - - -.added { - background-color: #99ff99; -} - -.changed { - background-color: #ffff77; -} - -.deleted { - background-color: #ff4455; - text-decoration: line-through; -} diff --git a/doc/publican/sources/css/default.css b/doc/publican/sources/css/default.css deleted file mode 100644 index bf38ebb..0000000 --- a/doc/publican/sources/css/default.css +++ /dev/null @@ -1,3 +0,0 @@ -@import url("common.css"); -@import url("overrides.css"); -@import url("lang.css"); diff --git a/doc/publican/sources/css/epub.css b/doc/publican/sources/css/epub.css deleted file mode 100644 index b0ffd43..0000000 --- a/doc/publican/sources/css/epub.css +++ /dev/null @@ -1,115 +0,0 @@ -/*headings*/ -h1, h2, h3, h4, h5, h6, -div.producttitle, -div.subtitle, -div.author div.author, -div.translator div.translator, -div.othercredit div.othercredit, -div.editor div.editor, -div.contrib div.contrib, -.title, -.titlepage .edition { -} - -div.para { - margin-top: 1em; -} -/* inline syntax highlighting */ -.perl_Alert { - color: #0000ff; -} - -.perl_BaseN { - color: #007f00; -} - -.perl_BString { - color: #5C3566; -} - -.perl_Char { - color: #ff00ff; -} - -.perl_Comment { - color: #888888; -} - - -.perl_DataType { - color: #0000ff; -} - - -.perl_DecVal { - color: #00007f; -} - - -.perl_Error { - color: #ff0000; -} - - -.perl_Float { - color: #00007f; -} - - -.perl_Function { - color: #007f00; -} - - -.perl_IString { - color: #5C3566; -} - - -.perl_Keyword { - color: #002F5D; -} - - -.perl_Operator { - color: #ffa500; -} - - -.perl_Others { - color: #b03060; -} - - -.perl_RegionMarker { - color: #96b9ff; -} - - -.perl_Reserved { - color: #9b30ff; -} - - -.perl_String { - color: #5C3566; -} - - -.perl_Variable { - color: #0000ff; -} - - -.perl_Warning { - color: #0000ff; -} - -b, strong { - font-weight: bolder; -} - -code.command { - font-family: monospace; - font-weight: bolder; -} diff --git a/doc/publican/sources/css/print.css b/doc/publican/sources/css/print.css deleted file mode 100644 index 54088f4..0000000 --- a/doc/publican/sources/css/print.css +++ /dev/null @@ -1,15 +0,0 @@ -@import url("common.css"); -@import url("overrides.css"); -@import url("lang.css"); - -#tocframe { - display: none; -} - -body.toc_embeded { - margin-left: 30px; -} - -.producttitle { - color: #336699; -} diff --git a/doc/publican/sources/images/icon.svg b/doc/publican/sources/images/icon.svg deleted file mode 100644 index b2f16d0..0000000 --- a/doc/publican/sources/images/icon.svg +++ /dev/null @@ -1,19 +0,0 @@ - - - - - - - - - - - - - - - - - - - diff --git a/doc/publican/sources/images/wayland.png b/doc/publican/sources/images/wayland.png deleted file mode 100644 index c993792..0000000 Binary files a/doc/publican/sources/images/wayland.png and /dev/null differ diff --git a/doc/publican/sources/images/xwayland-architecture.png b/doc/publican/sources/images/xwayland-architecture.png deleted file mode 100644 index f24dc18..0000000 Binary files a/doc/publican/sources/images/xwayland-architecture.png and /dev/null differ diff --git a/doc/publican/sources/meson.build b/doc/publican/sources/meson.build deleted file mode 100644 index a53b389..0000000 --- a/doc/publican/sources/meson.build +++ /dev/null @@ -1,114 +0,0 @@ -ProtocolSpec_xml = custom_target( - 'ProtocolSpec.xml', - command: [ xsltproc, '-o', '@OUTPUT@', files('../protocol-to-docbook.xsl'), '@INPUT@' ], - input: wayland_protocol_xml, - output: 'ProtocolSpec.xml' -) - -ProtocolInterfaces_xml = custom_target( - 'ProtocolInterfaces.xml', - command: [ xsltproc, '-o', '@OUTPUT@', files('../protocol-interfaces-to-docbook.xsl'), '@INPUT@' ], - input: wayland_protocol_xml, - output: 'ProtocolInterfaces.xml' -) - -ClientAPI_combined = custom_target( - 'ClientAPI-combined', - command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ], - input: [ doxygen_Client_combine_xslt, doxygen_Client_index_xml ], - output: 'ClientAPI-combined.xml' -) - -to_publican_xsl = files('../doxygen-to-publican.xsl') - -ClientAPI_xml = custom_target( - 'ClientAPI.xml', - command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Client', to_publican_xsl, '@INPUT@' ], - input: ClientAPI_combined, - output: 'ClientAPI.xml' -) - -ServerAPI_combined = custom_target( - 'ServerAPI-combined', - command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ], - input: [ doxygen_Server_combine_xslt, doxygen_Server_index_xml ], - output: 'ServerAPI-combined.xml' -) - -ServerAPI_xml = custom_target( - 'ServerAPI.xml', - command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Server', to_publican_xsl, '@INPUT@' ], - input: ServerAPI_combined, - output: 'ServerAPI.xml' -) - - -publican_sources = [ - 'Wayland.ent', - # 'Wayland.xml', # handled specially - 'Book_Info.xml', - 'Author_Group.xml', - 'Foreword.xml', - 'Preface.xml', - 'Revision_History.xml', - 'Protocol.xml', - 'Xwayland.xml', - 'Compositors.xml', - 'Color.xml', - 'Client.xml', - 'Server.xml' -] - -publican_processed_main = configure_file( - input: 'Wayland.xml', - output: 'Wayland.xml', - copy: true -) - -publican_copied_sources = [] -foreach src: publican_sources - publican_copied_sources += configure_file( - input: src, - output: src, - copy: true - ) -endforeach - -publican_processed_sources = [ - 'Architecture.xml', - 'Introduction.xml' -] - -publican_processed_targets = [] -foreach src: publican_processed_sources - publican_processed_targets += custom_target( - src, - command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'basedir', '.', merge_mapcoords_xsl, '@INPUT@' ], - input: src, - output: src - ) -endforeach - -publican_css_sources = files([ - 'css/brand.css', - 'css/common.css', - 'css/default.css', - 'css/epub.css', - 'css/print.css' -]) - -install_data( - publican_css_sources, - install_dir: join_paths(publican_install_prefix, publican_html_dir, 'css') -) - -publican_img_sources = files([ - 'images/icon.svg', - 'images/wayland.png', - 'images/xwayland-architecture.png' -]) - -install_data( - publican_img_sources, - install_dir: join_paths(publican_install_prefix, publican_html_dir, 'images') -) diff --git a/doc/publican/xsl/doxygen-to-publican.xsl b/doc/publican/xsl/doxygen-to-publican.xsl new file mode 100644 index 0000000..e13dcd7 --- /dev/null +++ b/doc/publican/xsl/doxygen-to-publican.xsl @@ -0,0 +1,147 @@ + + + + + + + + +
+ Functions + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns: + + + + + + + + + See also: + + + + Since: + + + + Note: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + +
+ + <xsl:value-of select="compoundname" /> + <xsl:if test="normalize-space(briefdescription) != ''"> + - <xsl:apply-templates select="briefdescription" /> + </xsl:if> + + + + + + + + + + + + + + +
+ + diff --git a/doc/publican/xsl/merge-mapcoords.xsl b/doc/publican/xsl/merge-mapcoords.xsl new file mode 100644 index 0000000..7adaca3 --- /dev/null +++ b/doc/publican/xsl/merge-mapcoords.xsl @@ -0,0 +1,64 @@ + + + + + + + +%BOOK_ENTITIES; +]> +]]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/publican/xsl/protocol-interfaces-to-docbook.xsl b/doc/publican/xsl/protocol-interfaces-to-docbook.xsl new file mode 100644 index 0000000..f68216d --- /dev/null +++ b/doc/publican/xsl/protocol-interfaces-to-docbook.xsl @@ -0,0 +1,51 @@ + + + + + + + +%BOOK_ENTITIES; +]> +]]> + +
+ Interfaces + + 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. + + + + Core interfaces: + + + + +
+ + + + + + + + + + + + + + + + + + + + diff --git a/doc/publican/xsl/protocol-to-docbook.xsl b/doc/publican/xsl/protocol-to-docbook.xsl new file mode 100644 index 0000000..79c938b --- /dev/null +++ b/doc/publican/xsl/protocol-to-docbook.xsl @@ -0,0 +1,223 @@ + + + + + + + +%BOOK_ENTITIES; +]> +]]> + + + Wayland Protocol Specification + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + <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" /> + +
+ + +
+ Enums provided by <xsl:value-of select="@name" /> + +
+ +
+ + + + + + + + + + + - + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + id for the new + + + + + - + + + + + + + + + + + + + + + + + :: + + + + + + + :: + + + + + () + + - + + + + + + + + +
+ + <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" /> + <xsl:if test="@bitfield"> + - bitfield + </xsl:if> + <xsl:if test="description/@summary"> + - <xsl:value-of select="description/@summary" /> + </xsl:if> + + + + + + + +
+ + + + + diff --git a/meson.build b/meson.build index c96ca29..7ad5ac0 100644 --- a/meson.build +++ b/meson.build @@ -9,6 +9,10 @@ project( 'c_std=c99', ] ) + +fs = import('fs') +pkgconfig = import('pkgconfig') + wayland_version = meson.project_version().split('.') config_h = configuration_data() @@ -106,8 +110,6 @@ configure_file( configuration: config_h, ) -pkgconfig = import('pkgconfig') - wayland_protocol_xml = files('protocol/wayland.xml') root_inc = include_directories('.') -- cgit v1.2.3-70-g09d2