<html>
<body>
<div style="font-family: Verdana, Arial, Helvetica, Sans-Serif;">
<table bgcolor="#f9f3c9" width="100%" cellpadding="12" style="border: 1px #c9c399 solid; border-radius: 6px; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tr>
<td>
This is an automatically generated e-mail. To reply, visit:
<a href="https://git.reviewboard.kde.org/r/125092/">https://git.reviewboard.kde.org/r/125092/</a>
</td>
</tr>
</table>
<br />
<pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;"><h1 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">KWayland</h1>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">KWayland is a Qt-style API to interact with the wayland-client and wayland-server API.</p>
<h2 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Overview</h2>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">KWayland provides two libraries:</p>
<ul style="padding: 0;text-rendering: inherit;margin: 0 0 0 1em;line-height: inherit;white-space: normal;">
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">KWayland::Client</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">KWayland::Server</li>
</ul>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">As the names suggest they implement a Client respectively a Server API for the Wayland
protocol. The API is Qt-styled removing the needs to interact with a for a Qt developer
uncomfortable low-level C-API. For example the callback mechanism from the Wayland API
is replaced by signals; data types are adjusted to be what a Qt developer expects, e.g.
two arguments of int are represented by a QPoint or a QSize.</p>
<h2 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">KWayland Server</h2>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Head-less API</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">The server library can be used to implement a Wayland server with Qt. The API is head-less
meaning it does not perform any output and does not restrict on the way how one wants to
render. This allows to easily integrate in existing rendering code based on e.g. OpenGL or
QPainter. Applications built on top of KWayland Server integrated the graphics with the
following technologies:</p>
<ul style="padding: 0;text-rendering: inherit;margin: 0 0 0 1em;line-height: inherit;white-space: normal;">
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">OpenGL over DRM/KMS</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">OpenGL over X11</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">OpenGL over Wayland</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">OpenGL over Android's hwcomposer enabled through libhybris</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">QPainter over DRM/KMs</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">QPainter over fbdev</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">QPainter over X11</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">QPainter over Wayland</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">QWidget</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">QtQuick</li>
</ul>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Although the library does not perform any output, it makes it very easy to enable rendering.
The representation for a <code style="text-rendering: inherit;color: #4444cc;padding: 0;white-space: normal;margin: 0;line-height: inherit;">wl_buffer</code> (KWayland::Server::BufferInterface) allows easy conversion
to a (memory-shared) QImage in case the buffer represents a shared memory buffer. This QImage
can be used for rendering in a QPainter based API or to generate an OpenGL texture.</p>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Easy usage of Wayland API</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">The library hides many Wayland implementation details. For all Wayland interfaces which have
double buffered state the classes always only provide access to the committed state. The pending
state is an internal detail. On commit of the pending state Qt signals are emitted about what
changed.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Buffers are ref-counted and automatically released if it is no longer referenced allowing the
client to reuse it. This happens fully automatically when a surface no longer references a buffer.
As long as a buffer is attached surface, the surface has it referenced and the user of the API can
access the buffer without needing to care about referencing it.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">The API of KWayland is hand-crafted to make usage easier. The representation of Surface combines
multiple aspects about a Surface even if in Wayland API it is added to other elements. E.g. a Surface
contains all SubSurfaces attached to it instead of the user having to monitor for which Surface a
SubSurface got created.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Similar the representation of a Seat combines all aspects of the Seat. A user of the API only needs
to interact with the Seat, there is no need to track all the created keyboards, pointers, etc. The
representation of Seat tracks which keyboards are generated and is able to forward events to the
proper focus surface, send enter and leave notifications when needed without the user of the API
to care about it.</p>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Handling input events</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Just like with output the server API does not restrict on how to get input events. This allows to
integrate with existing input handlers and also allows to easily filter the input before it is passed
to the server and from there delegated to the client. By that one can filter out e.g. global touch
gestures or keyboard shortcuts without having to implement handlers inside KWayland. The SeatInterface
provides a very easy to use API to forward events which can be easily integrated with Qt's own
input event system, e.g. there is a mapping from Qt::MouseButton to the Linux input code.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Applications built on top of KWayland Server integrated input events with the following technologies:</p>
<ul style="padding: 0;text-rendering: inherit;margin: 0 0 0 1em;line-height: inherit;white-space: normal;">
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">libinput</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">X11</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">Wayland</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">Android's inputstack enabled through libhybris</li>
<li style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: normal;">QInputEvent</li>
</ul>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Private IPC with child processes</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">KWayland Server is well suited for having a private IPC with child processes. The Display can be
setup in a way that it doesn't create a public socket but only allows connections through socket
pairs. This allows to create a socketpair, pass one file descriptor to KWayland server and the other
to the forked process, e.g. through the WAYLAND_SOCKET environment variable. Thus a dedicated IPC
is created which can be used even for running your own custom protocol. For example KDE Plasma uses
such a dedicated parent-child Wayland server in it's screen locker architecture.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Of course private sockets can be added at any time in addition to a publicly available socket. This
can be used to recognize specific clients and to restrict access to interfaces for only some dedicated
clients.</p>
<h2 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">KWayland Client</h2>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">The idea around KWayland Client is to provide a drop-in API for the Wayland client library which at
the same time provides convenience Qt-style API. It is not intended to be used as a replacement for
the QtWayland QPA plugin, but rather as a way to interact with Wayland in case one needs Qt to use
a different QPA plugin or in combination with QtWayland to allow a more low-level interaction without
requiring to write C code.</p>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Convenience API</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">The convenience API in KWayland Client provides one class wrapping a Wayland object. Each class can
be casted into the wrapped Wayland type. The API represents events as signals and provides simple
method calls for requests.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Classes representing global Wayland resources can be created through the Registry. This class eases
the interaction with the Wayland registry and emits signals whenever a new global is announced or gets
removed. The Registry has a list of known interfaces (e.g. common Wayland protocols like <code style="text-rendering: inherit;color: #4444cc;padding: 0;white-space: normal;margin: 0;line-height: inherit;">wl_compositor</code>
or <code style="text-rendering: inherit;color: #4444cc;padding: 0;white-space: normal;margin: 0;line-height: inherit;">wl_shell</code>) which have dedicated announce/removed signals and objects can be factored by the Registry
for those globals.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Many globals function as a factory for further resources. E.g. the Compositor has a factory method for
Surfaces. All objects can also be created in a low-level way interacting directly with the Wayland API,
but provide convenience factory methods in addition. This allows both an easy usage or a more low level
control of the Wayland API if needed.</p>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Integration with QtWayland QPA</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">If the QGuiApplication uses the QtWayland QPA, KWayland allows to integrate with it. That is one does
not need to create a new connection to the Wayland server, but can reuse the one used by Qt. If there
is a way to get a Wayland object from Qt, the respective class provides a static method normally called
<code style="text-rendering: inherit;color: #4444cc;padding: 0;white-space: normal;margin: 0;line-height: inherit;">fromApplication</code>. In addition the API allows to get the Surface from a QWindow.</p>
<h2 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">Using KWayland in your application</h2>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">With CMake</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">KWayland installs a CMake Config file which allows to use KWayland as imported targets. There is
one library for Client and one for Server.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">To find the package use for example:</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;"><div class="codehilite" style="background: #f8f8f8"><pre style="line-height: 125%">find_package(KF5Wayland CONFIG)
set_package_properties(KF5Wayland PROPERTIES TYPE OPTIONAL )
add_feature_info("KF5Wayland" KF5Wayland_FOUND "Required for the awesome Wayland on Qt demo")
</pre></div>
</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Now to link against the Client library use:</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;"><div class="codehilite" style="background: #f8f8f8"><pre style="line-height: 125%">add_executable(exampleApp example.cpp)
target_link_libraries(exampleApp KF5::WaylandClient)
</pre></div>
</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">To link against the Server library use:</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;"><div class="codehilite" style="background: #f8f8f8"><pre style="line-height: 125%">add_executable(exampleServer exampleServer.cpp)
target_link_libraries(exampleServer KF5::WaylandServer)
</pre></div>
</p>
<h3 style="font-size: 100%;text-rendering: inherit;padding: 0;white-space: normal;margin: 0;line-height: inherit;">With QMake</h3>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">KWayland installs .pri files for the Client and Server library allowing easy usage in QMake based
applications.</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Just use:</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;"><div class="codehilite" style="background: #f8f8f8"><pre style="line-height: 125%">QT += KWaylandClient
</pre></div>
</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Respectively:</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;"><div class="codehilite" style="background: #f8f8f8"><pre style="line-height: 125%">QT += KWaylandServer
</pre></div>
</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;">Please make sure that your project is configured with C++11 support:</p>
<p style="padding: 0;text-rendering: inherit;margin: 0;line-height: inherit;white-space: inherit;"><div class="codehilite" style="background: #f8f8f8"><pre style="line-height: 125%">CONFIG += c++11
</pre></div>
</p></pre>
<br />
<p>- Martin Gräßlin</p>
<br />
<p>On September 7th, 2015, 5:29 p.m. CEST, Martin Gräßlin wrote:</p>
<table bgcolor="#fefadf" width="100%" cellspacing="0" cellpadding="12" style="border: 1px #888a85 solid; border-radius: 6px; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tr>
<td>
<div>Review request for Plasma, Marco Martin and Sebastian Kügler.</div>
<div>By Martin Gräßlin.</div>
<p style="color: grey;"><i>Updated Sept. 7, 2015, 5:29 p.m.</i></p>
<div style="margin-top: 1.5em;">
<b style="color: #575012; font-size: 10pt;">Repository: </b>
kwayland
</div>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Description </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: 1px solid #b8b5a0">
<tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">A start for documenting what these libraries are, how they can be
used, etc.</pre>
</td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Diffs</b> </h1>
<ul style="margin-left: 3em; padding-left: 0;">
<li>README.md <span style="color: grey">(PRE-CREATION)</span></li>
</ul>
<p><a href="https://git.reviewboard.kde.org/r/125092/diff/" style="margin-left: 3em;">View Diff</a></p>
</td>
</tr>
</table>
</div>
</body>
</html>