mirror of
https://gitlab.freedesktop.org/wayland/wayland.git
synced 2025-10-28 05:40:14 -04:00
doc: start documenting Xwayland
This is a rough intro to what Xwayland is and does, with just one implementation detail so far (Window identification). I paid no attention to formatting details, those can be polished in follow-ups. I just want the prose out. I also just quickly whacked up the diagram, would be happy to see someone replace it with a nicer one. I just didn't have time to learn dot for now. v2: - typo fix - rephrase "talking to hardware" as "driving the displays" - mention circular dependency in intro - add section to explain rootless and rootful modes - remove paragraph about Xwayland protocol usage - move TBD part to the end under a new section header v3: - use "advantage" and "disadvantage" instead of "pro" and "con" - slight rewording on rootful mode and rootless mode paragraphs - removed the paragraph about the lack of shell and special Wayland protocol extensions - removed the commented out list of ideas to write v4: - typo fixes pointed out by Yong Cc: Olivier Fourdan <ofourdan@redhat.com> Cc: Jonas Ådahl <jadahl@gmail.com> Cc: Daniel Stone <daniel@fooishbar.org> Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk> Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
This commit is contained in:
Pekka Paalanen
parent
1b6521e695
commit
147617800d
4 changed files with 175 additions and 1 deletions
|
|
@ -24,9 +24,11 @@ publican_sources = \
|
|||
$(srcdir)/sources/Preface.xml \
|
||||
$(srcdir)/sources/Revision_History.xml \
|
||||
$(srcdir)/sources/Protocol.xml \
|
||||
$(srcdir)/sources/Xwayland.xml \
|
||||
$(srcdir)/sources/Compositors.xml \
|
||||
$(srcdir)/sources/images/icon.svg \
|
||||
$(srcdir)/sources/images/wayland.png \
|
||||
$(srcdir)/sources/images/xwayland-architecture.png \
|
||||
$(srcdir)/sources/Client.xml \
|
||||
$(srcdir)/sources/Server.xml
|
||||
|
||||
|
|
@ -43,7 +45,8 @@ css_sources = \
|
|||
|
||||
img_sources = \
|
||||
$(srcdir)/sources/images/icon.svg \
|
||||
$(srcdir)/sources/images/wayland.png
|
||||
$(srcdir)/sources/images/wayland.png \
|
||||
$(srcdir)/sources/images/xwayland-architecture.png
|
||||
|
||||
doxygen_img_sources := \
|
||||
$(doxydir)/xml/wayland-architecture.png \
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@
|
|||
<xi:include href="Compositors.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Protocol.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Xwayland.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="ProtocolSpec.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="Client.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
||||
<xi:include href="Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
||||
|
|
|
|||
170
doc/publican/sources/Xwayland.xml
Normal file
170
doc/publican/sources/Xwayland.xml
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
<?xml version='1.0' encoding='utf-8' ?>
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
|
||||
%BOOK_ENTITIES;
|
||||
]>
|
||||
<chapter id="chap-X11-Application-Support">
|
||||
<title>X11 Application Support</title>
|
||||
<section id="sect-X11-Application-Support-introduction">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section id="sect-X11-Application-Support-two-modes">
|
||||
<title>Two Modes for Foreign Windows</title>
|
||||
<para>
|
||||
In general, windows from a foreign window system can be presented in one
|
||||
of two ways: rootless and rootful (not rootless).
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
This chapter concentrates on the rootless mode, and ignores the rootful
|
||||
mode.
|
||||
</para>
|
||||
</section>
|
||||
<section id="sect-X11-Application-Support-architecture">
|
||||
<title>Architecture</title>
|
||||
<para>
|
||||
A Wayland compositor usually takes care of launching Xwayland.
|
||||
Xwayland works in cooperation with a Wayland compositor as follows:
|
||||
</para>
|
||||
<figure>
|
||||
<title>Xwayland architecture diagram</title>
|
||||
<mediaobjectco>
|
||||
<imageobjectco>
|
||||
<imageobject>
|
||||
<imagedata fileref="images/xwayland-architecture.png" format="PNG" />
|
||||
</imageobject>
|
||||
</imageobjectco>
|
||||
</mediaobjectco>
|
||||
</figure>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section id="sect-X11-Application-Support-xwm">
|
||||
<title>X Window Manager (XWM)</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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 asynchonous by design.
|
||||
</para>
|
||||
<section id="sect-X11-Application-Support-xwm-window-identification">
|
||||
<title>Window identification</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
BIN
doc/publican/sources/images/xwayland-architecture.png
Normal file
BIN
doc/publican/sources/images/xwayland-architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.4 KiB |
Loading…
Add table
Add a link
Reference in a new issue