QtWayland: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
Line 1: Line 1:
'''English''' | [[QtWayland SimplifiedChinese|简体中文]]
'''English''' | [[:QtWayland_SimplifiedChinese|简体中文]]


=What is QtWayland?=
= What is QtWayland? =


QtWayland is a Qt 5 module that wraps the functionality of Wayland. QtWayland is separated into a client and server side. The client side is the wayland platform plugin, and provides a way to run Qt applications as Wayland clients. The server side is the QtCompositor <span class="caps">API</span>, and allows users to write their own Wayland compositors.
QtWayland is a Qt 5 module that wraps the functionality of Wayland. QtWayland is separated into a client and server side. The client side is the wayland platform plugin, and provides a way to run Qt applications as Wayland clients. The server side is the QtCompositor API, and allows users to write their own Wayland compositors.


==What is Wayland==
== What is Wayland ==


Wayland is a protocol for a compositor to talk to its clients as well as a C library implementation of that protocol. For more detailed information you should visit the [http://wayland.freedesktop.org/ Wayland project homepage] ''[wayland.freedesktop.org]''
Wayland is a protocol for a compositor to talk to its clients as well as a C library implementation of that protocol. For more detailed information you should visit the &quot;Wayland project homepage&amp;quot;:http://wayland.freedesktop.org/


=Where can I find the code for QtWayland?=
= Where can I find the code for QtWayland? =


[http://qt.gitorious.org/qt/qtwayland Gitorious Repo] ''[qt.gitorious.org]''
&quot;Gitorious Repo&amp;quot;:http://qt.gitorious.org/qt/qtwayland


=How do I build QtWayland?=
= How do I build QtWayland? =


==Desktop build instructions==
== Desktop build instructions ==


===Setup build environment===
=== Setup build environment ===


The first step is to start with a reasonably modern Linux distribution. I use Ubuntu 12.04, so anything newer is just gravy.<br /> The following instructions are based off of the tips on: http://wayland.freedesktop.org/building.html
The first step is to start with a reasonably modern Linux distribution. I use Ubuntu 12.04, so anything newer is just gravy.<br />The following instructions are based off of the tips on: http://wayland.freedesktop.org/building.html


The first thing I do is start by creating an install directory for my Wayland dependencies and create an environment file to source:
The first thing I do is start by creating an install directory for my Wayland dependencies and create an environment file to source:


So if I wanted to install my Wayland dependencies into the folder $HOME/Apps/Wayland I would create the folder, and then create the file:<br />''~/Apps/Wayland/wayland.sourceme''
So if I wanted to install my Wayland dependencies into the folder $HOME/Apps/Wayland I would create the folder, and then create the file:<br />''<sub>/Apps/Wayland/wayland.sourceme_
<br /><code>#wayland.sourceme<br />WLD=$HOME/Apps/Wayland # change this to another location if you prefer<br />LD_LIBRARY_PATH=$WLD/lib<br />PKG_CONFIG_PATH=$WLD/lib/pkgconfig/:$WLD/share/pkgconfig/<br />ACLOCAL=&quot;aclocal -I $WLD/share/aclocal&amp;quot;<br />PATH=$WLD/bin:$PATH<br />XDG_RUNTIME_DIR=/tmp
<br />export WLD LD_LIBRARY_PATH PKG_CONFIG_PATH ACLOCAL PATH XDG_RUNTIME_DIR</code>
<br />So then source that file to set up your work environment:<br />_source</sub>/Apps/Wayland/wayland.sourceme''


So then source that file to set up your work environment:<br />''source ~/Apps/Wayland/wayland.sourceme''
=== Build dependencies ===


===Build dependencies===
Most of the dependencies you need are released, but not yet available in the latest Linux distributions, so you will need to build them. Here are the instructions for each in the order that they need to be built:


Most of the dependencies you need are released, but not yet available in the latest Linux distributions, so you will need to build them. Here are the instructions for each in the order that they need to be built:
==== wayland ====


====wayland====
<code>git clone git://anongit.freedesktop.org/wayland/wayland<br />cd wayland<br />#this prevents autogen.sh to fail while testing for exiting folders<br />mkdir -p $WLD/share/aclocal<br />./autogen.sh —prefix=$WLD<br />make<br />make install</code>


====drm====
==== drm ====


====mesa====
<code>git clone git://anongit.freedesktop.org/git/mesa/drm<br />cd drm<br />./autogen.sh —prefix=$WLD<br />make &amp;&amp; make install</code>


====libxkbcommon====
==== mesa ====


====weston (optional)====
<code>git clone git://anongit.freedesktop.org/mesa/mesa<br />cd mesa<br />./autogen.sh —prefix=$WLD —enable-gles2 —disable-gallium-egl —with-egl-platforms=x11,wayland,drm —enable-gbm —enable-shared-glapi —with-gallium-drivers=r300,r600,swrast,nouveau<br />make &amp;&amp; make install</code>


===Qt dependency===
==== libxkbcommon ====


Currently, you need to build the latest Qt (stable branch) (see http://lists.qt.io/pipermail/development/2013-December/014789.html ) <span class="caps">WITHOUT</span> using the wayland.sourceme environment. The modules you need at the very least are:<br /> qtbase<br /> qtjsbackend<br /> qtdeclarative
<code>git clone git://people.freedesktop.org/xorg/lib/libxkbcommon.git<br />cd libxkbcommon/<br />./autogen.sh —prefix=$WLD —with-xkb-config-root=/usr/share/X11/xkb<br />make &amp;&amp; make install</code>


If you face linker errors related to libGL and undefined references, it may be necessary to compile Qt5 and link it with the self compiled mesa. Maybe due to the way that mesa was compiled and installed, the configure script will require to explicitly define the version of OpenGL to be used with: ./configure -opengl es2
==== weston (optional) ====


===Building the QtWayland module===
<code>git clone git://anongit.freedesktop.org/wayland/weston<br />cd weston<br />./autogen.sh —prefix=$WLD<br />make<br />make install -k</code>


Once you have a working build of Qt 5, then pull down the latest QtWayland module code and configure with “qmake” this time using the wayland.sourceme environment. Make sure that you use the version of qmake that you get with Qt 5 here. This will make sure that the Wayland platform plugin and QtCompositor <span class="caps">API</span> are build using your special versions of OpenGL and Wayland.
=== Qt dependency ===


==Raspberry Pi build instructions==
Currently, you need to build the latest Qt (stable branch) (see http://lists.qt.io/pipermail/development/2013-December/014789.html ) WITHOUT using the wayland.sourceme environment. The modules you need at the very least are:<br />qtbase<br />qtjsbackend<br />qtdeclarative


Coming soon…
If you face linker errors related to libGL and undefined references, it may be necessary to compile Qt5 and link it with the self compiled mesa. Maybe due to the way that mesa was compiled and installed, the configure script will require to explicitly define the version of OpenGL to be used with: ./configure -opengl es2


=How do I use QtWayland?=
=== Building the QtWayland module ===


==Run Qt applications as Wayland clients==
Once you have a working build of Qt 5, then pull down the latest QtWayland module code and configure with &quot;qmake&amp;quot; this time using the wayland.sourceme environment. Make sure that you use the version of qmake that you get with Qt 5 here. This will make sure that the Wayland platform plugin and QtCompositor API are build using your special versions of OpenGL and Wayland.


When you build the QtWayland module, you should get a new platform plugin for wayland. To use it you must first already have a Wayland compositor running. This could be either the Weston reference compositor provided by the Wayland project, or a Qt example compositor provided by QtWayland. Regardless the only thing you need to do as an application developer to run your <span class="caps">GUI</span> application as a wayland client is:
<code>source <sub>/Apps/Wayland/wayland.sourceme<br />git clone git://gitorious.org/qt/qtwayland.git<br />cd qtwayland<br />qmake<br />make<br />make install</code>
<br />h2. Raspberry Pi build instructions
<br />Coming soon…
<br />h1. How do I use QtWayland?
<br />h2. Run Qt applications as Wayland clients
<br />When you build the QtWayland module, you should get a new platform plugin for wayland. To use it you must first already have a Wayland compositor running. This could be either the Weston reference compositor provided by the Wayland project, or a Qt example compositor provided by QtWayland. Regardless the only thing you need to do as an application developer to run your GUI application as a wayland client is:
<br /><code>source</sub>/Apps/Wayland/wayland.sourceme<br />./application -platform wayland</code>


==Create and Run your own Wayland Compositor with Qt5==
== Create and Run your own Wayland Compositor with Qt5 ==


===Running example compositors===
=== Running example compositors ===


The QtWayland module provides a couple of example compositors that demonstrate how the QtCompositor <span class="caps">API</span> works. These are built in the examples folder of the QtWayland module if you add “wayland-compositor” to the <span class="caps">CONFIG</span> variable when starting qmake, as in :<br />
The QtWayland module provides a couple of example compositors that demonstrate how the QtCompositor API works. These are built in the examples folder of the QtWayland module if you add &quot;wayland-compositor&amp;quot; to the CONFIG variable when starting qmake, as in :<br /><code>qmake CONFIG+=wayland-compositor<code>


These examples represent the server side of Wayland, so they do not use the wayland platform plugin, but rather whatever platform you need to run on. Generally this is going to be either ''eglfs'', ''kms'', or if you want to run in X11 ''xcb''.
These examples represent the server side of Wayland, so they do not use the wayland platform plugin, but rather whatever platform you need to run on. Generally this is going to be either ''eglfs'', ''kms'', or if you want to run in X11 ''xcb''.


If you wanted to run the qml-compositor in X11 you would run the following:
If you wanted to run the qml-compositor in X11 you would run the following:
</code>source ~/Apps/Wayland/wayland.sourceme<br />cd qtwayland/examples/qml-compositor<br />./qml-compositor -platform xcb<code>


And now that you have a Wayland compositor running, you can connect and display Wayland clients.
And now that you have a Wayland compositor running, you can connect and display Wayland clients.


===Creating your own compositor===
=== Creating your own compositor ===


The <span class="caps">API</span> to create a Wayland compositor and control associated events (e.g. a new client connected) is exposed through the QtWayland class WaylandCompositor. Its constructor expects as the primary parameter a pointer to a QWindow object, which allows some flexibility when implementing your compositor.
The API to create a Wayland compositor and control associated events (e.g. a new client connected) is exposed through the QtWayland class WaylandCompositor. Its constructor expects as the primary parameter a pointer to a QWindow object, which allows some flexibility when implementing your compositor.


Thanks to this, there are 3 different approaches while implementing a compositor:
Thanks to this, there are 3 different approaches while implementing a compositor:
Line 83: Line 94:
* QWidget based: in this case, the base widget window handle will be used.
* QWidget based: in this case, the base widget window handle will be used.


* <span class="caps">QML</span> based: your C++ application will use a QQuickView object to setup the WaylandCompositor. At the time of writing, there is no way to create a compositor using only <span class="caps">QML</span>.
* QML based: your C++ application will use a QQuickView object to setup the WaylandCompositor. At the time of writing, there is no way to create a compositor using only QML.


WaylandCompositor is a pure abstract virtual class, which means that it is not possible to create instances of it. A common pattern while implementing a compositor is inherit from WaylandCompositor and implement the function method '''void surfaceCreated(WaylandSurface *surface)'''.
WaylandCompositor is a pure abstract virtual class, which means that it is not possible to create instances of it. A common pattern while implementing a compositor is inherit from WaylandCompositor and implement the function method *void surfaceCreated(WaylandSurface '''surface)'''.


This method will be executed every time a new client connects (i.e. an application was started and requests the services of the compositor), being represented as a WaylandSurface object. There are some signals that this object can generate and must be treated by the compositor, namely:
This method will be executed every time a new client connects (i.e. an application was started and requests the services of the compositor), being represented as a WaylandSurface object. There are some signals that this object can generate and must be treated by the compositor, namely:
Line 91: Line 102:
* mapped(): emitted when the client has connected to the compositor.
* mapped(): emitted when the client has connected to the compositor.


* damaged(): <span class="caps">TODO</span>
* damaged(): TODO


* destroyed(): emitted when the client quits (i.e. the application has exited)
* destroyed(): emitted when the client quits (i.e. the application has exited)


* unmapped(): <span class="caps">TODO</span>
* unmapped(): TODO
 
* extendedSurfaceReady(): <span class="caps">TODO</span>


The project file will need to use the compositor module (i.e. add in the .pro file '''QT += compositor'''). It is interesting to comment that at time of writing, there are some <span class="caps">QML</span> related <span class="caps">API</span>s only available by adding a define in the project file (i.e. '''<span class="caps">DEFINES</span> += QT_COMPOSITOR_QUICK''').
* extendedSurfaceReady(): TODO


===Starting the compositor standalone===
The project file will need to use the compositor module (i.e. add in the .pro file '''QT += compositor'''). It is interesting to comment that at time of writing, there are some QML related APIs only available by adding a define in the project file &amp;#40;i.e. '''DEFINES += QT_COMPOSITOR_QUICK'''&amp;#41;.


<span class="caps">TODO</span>
=== Starting the compositor standalone ===

Revision as of 14:19, 23 February 2015

English | 简体中文

What is QtWayland?

QtWayland is a Qt 5 module that wraps the functionality of Wayland. QtWayland is separated into a client and server side. The client side is the wayland platform plugin, and provides a way to run Qt applications as Wayland clients. The server side is the QtCompositor API, and allows users to write their own Wayland compositors.

What is Wayland

Wayland is a protocol for a compositor to talk to its clients as well as a C library implementation of that protocol. For more detailed information you should visit the "Wayland project homepage&quot;:http://wayland.freedesktop.org/

Where can I find the code for QtWayland?

"Gitorious Repo&quot;:http://qt.gitorious.org/qt/qtwayland

How do I build QtWayland?

Desktop build instructions

Setup build environment

The first step is to start with a reasonably modern Linux distribution. I use Ubuntu 12.04, so anything newer is just gravy.
The following instructions are based off of the tips on: http://wayland.freedesktop.org/building.html

The first thing I do is start by creating an install directory for my Wayland dependencies and create an environment file to source:

So if I wanted to install my Wayland dependencies into the folder $HOME/Apps/Wayland I would create the folder, and then create the file:
/Apps/Wayland/wayland.sourceme_


#wayland.sourceme<br />WLD=$HOME/Apps/Wayland # change this to another location if you prefer<br />LD_LIBRARY_PATH=$WLD/lib<br />PKG_CONFIG_PATH=$WLD/lib/pkgconfig/:$WLD/share/pkgconfig/<br />ACLOCAL=&quot;aclocal -I $WLD/share/aclocal&amp;quot;<br />PATH=$WLD/bin:$PATH<br />XDG_RUNTIME_DIR=/tmp
<br />export WLD LD_LIBRARY_PATH PKG_CONFIG_PATH ACLOCAL PATH XDG_RUNTIME_DIR


So then source that file to set up your work environment:
_source/Apps/Wayland/wayland.sourceme

Build dependencies

Most of the dependencies you need are released, but not yet available in the latest Linux distributions, so you will need to build them. Here are the instructions for each in the order that they need to be built:

wayland

git clone git://anongit.freedesktop.org/wayland/wayland<br />cd wayland<br />#this prevents autogen.sh to fail while testing for exiting folders<br />mkdir -p $WLD/share/aclocal<br />./autogen.sh —prefix=$WLD<br />make<br />make install

drm

git clone git://anongit.freedesktop.org/git/mesa/drm<br />cd drm<br />./autogen.sh —prefix=$WLD<br />make &amp;&amp; make install

mesa

git clone git://anongit.freedesktop.org/mesa/mesa<br />cd mesa<br />./autogen.sh —prefix=$WLD —enable-gles2 —disable-gallium-egl —with-egl-platforms=x11,wayland,drm —enable-gbm —enable-shared-glapi —with-gallium-drivers=r300,r600,swrast,nouveau<br />make &amp;&amp; make install

libxkbcommon

git clone git://people.freedesktop.org/xorg/lib/libxkbcommon.git<br />cd libxkbcommon/<br />./autogen.sh —prefix=$WLD —with-xkb-config-root=/usr/share/X11/xkb<br />make &amp;&amp; make install

weston (optional)

git clone git://anongit.freedesktop.org/wayland/weston<br />cd weston<br />./autogen.sh —prefix=$WLD<br />make<br />make install -k

Qt dependency

Currently, you need to build the latest Qt (stable branch) (see http://lists.qt.io/pipermail/development/2013-December/014789.html ) WITHOUT using the wayland.sourceme environment. The modules you need at the very least are:
qtbase
qtjsbackend
qtdeclarative

If you face linker errors related to libGL and undefined references, it may be necessary to compile Qt5 and link it with the self compiled mesa. Maybe due to the way that mesa was compiled and installed, the configure script will require to explicitly define the version of OpenGL to be used with: ./configure -opengl es2

Building the QtWayland module

Once you have a working build of Qt 5, then pull down the latest QtWayland module code and configure with "qmake&quot; this time using the wayland.sourceme environment. Make sure that you use the version of qmake that you get with Qt 5 here. This will make sure that the Wayland platform plugin and QtCompositor API are build using your special versions of OpenGL and Wayland.

source <sub>/Apps/Wayland/wayland.sourceme<br />git clone git://gitorious.org/qt/qtwayland.git<br />cd qtwayland<br />qmake<br />make<br />make install


h2. Raspberry Pi build instructions
Coming soon…
h1. How do I use QtWayland?
h2. Run Qt applications as Wayland clients
When you build the QtWayland module, you should get a new platform plugin for wayland. To use it you must first already have a Wayland compositor running. This could be either the Weston reference compositor provided by the Wayland project, or a Qt example compositor provided by QtWayland. Regardless the only thing you need to do as an application developer to run your GUI application as a wayland client is:


source</sub>/Apps/Wayland/wayland.sourceme<br />./application -platform wayland

Create and Run your own Wayland Compositor with Qt5

Running example compositors

The QtWayland module provides a couple of example compositors that demonstrate how the QtCompositor API works. These are built in the examples folder of the QtWayland module if you add "wayland-compositor&quot; to the CONFIG variable when starting qmake, as in :

qmake CONFIG+=wayland-compositor<code>

These examples represent the server side of Wayland, so they do not use the wayland platform plugin, but rather whatever platform you need to run on. Generally this is going to be either ''eglfs'', ''kms'', or if you want to run in X11 ''xcb''.

If you wanted to run the qml-compositor in X11 you would run the following:

source ~/Apps/Wayland/wayland.sourceme
cd qtwayland/examples/qml-compositor
./qml-compositor -platform xcb

And now that you have a Wayland compositor running, you can connect and display Wayland clients.

Creating your own compositor

The API to create a Wayland compositor and control associated events (e.g. a new client connected) is exposed through the QtWayland class WaylandCompositor. Its constructor expects as the primary parameter a pointer to a QWindow object, which allows some flexibility when implementing your compositor.

Thanks to this, there are 3 different approaches while implementing a compositor:

  • QWindow based: the instance will be used to setup the WaylandCompositor object.
  • QWidget based: in this case, the base widget window handle will be used.
  • QML based: your C++ application will use a QQuickView object to setup the WaylandCompositor. At the time of writing, there is no way to create a compositor using only QML.

WaylandCompositor is a pure abstract virtual class, which means that it is not possible to create instances of it. A common pattern while implementing a compositor is inherit from WaylandCompositor and implement the function method *void surfaceCreated(WaylandSurface surface).

This method will be executed every time a new client connects (i.e. an application was started and requests the services of the compositor), being represented as a WaylandSurface object. There are some signals that this object can generate and must be treated by the compositor, namely:

  • mapped(): emitted when the client has connected to the compositor.
  • damaged(): TODO
  • destroyed(): emitted when the client quits (i.e. the application has exited)
  • unmapped(): TODO
  • extendedSurfaceReady(): TODO

The project file will need to use the compositor module (i.e. add in the .pro file QT += compositor). It is interesting to comment that at time of writing, there are some QML related APIs only available by adding a define in the project file &#40;i.e. DEFINES += QT_COMPOSITOR_QUICK&#41;.

Starting the compositor standalone