1/*
2 SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6#ifndef WAYLAND_COMPOSITOR_H
7#define WAYLAND_COMPOSITOR_H
8
9#include <QObject>
10
11#include <memory>
12
13#include "KWayland/Client/kwaylandclient_export.h"
14
15struct wl_compositor;
16
17namespace KWayland
18{
19namespace Client
20{
21class EventQueue;
22class Region;
23class Surface;
24
25/**
26 * @short Wrapper for the wl_compositor interface.
27 *
28 * This class provides a convenient wrapper for the wl_compositor interface.
29 * It's main purpose is to create a Surface.
30 *
31 * To use this class one needs to interact with the Registry. There are two
32 * possible ways to create the Compositor interface:
33 * @code
34 * Compositor *c = registry->createCompositor(name, version);
35 * @endcode
36 *
37 * This creates the Compositor and sets it up directly. As an alternative this
38 * can also be done in a more low level way:
39 * @code
40 * Compositor *c = new Compositor;
41 * c->setup(registry->bindCompositor(name, version));
42 * @endcode
43 *
44 * The Compositor can be used as a drop-in replacement for any wl_compositor
45 * pointer as it provides matching cast operators.
46 *
47 * @see Registry
48 **/
49class KWAYLANDCLIENT_EXPORT Compositor : public QObject
50{
51 Q_OBJECT
52public:
53 /**
54 * Creates a new Compositor.
55 * Note: after constructing the Compositor it is not yet valid and one needs
56 * to call setup. In order to get a ready to use Compositor prefer using
57 * Registry::createCompositor.
58 **/
59 explicit Compositor(QObject *parent = nullptr);
60 ~Compositor() override;
61
62 /**
63 * Creates a Compositor for the used QGuiApplication.
64 * This is an integration feature for QtWayland. On non-wayland platforms this method returns
65 * @c nullptr.
66 *
67 * The returned Compositor will be fully setup, which means it manages a wl_compositor.
68 * When the created Compositor gets destroyed the managed wl_compositor won't be disconnected
69 * as that's managed by Qt.
70 * @since 5.4
71 **/
72 static Compositor *fromApplication(QObject *parent = nullptr);
73
74 /**
75 * @returns @c true if managing a wl_compositor.
76 **/
77 bool isValid() const;
78 /**
79 * Setup this Compositor to manage the @p compositor.
80 * When using Registry::createCompositor there is no need to call this
81 * method.
82 **/
83 void setup(wl_compositor *compositor);
84 /**
85 * Releases the wl_compositor interface.
86 * After the interface has been released the Compositor instance is no
87 * longer valid and can be setup with another wl_compositor interface.
88 **/
89 void release();
90 /**
91 * Destroys the data held by this Compositor.
92 * This method is supposed to be used when the connection to the Wayland
93 * server goes away. If the connection is not valid anymore, it's not
94 * possible to call release anymore as that calls into the Wayland
95 * connection and the call would fail. This method cleans up the data, so
96 * that the instance can be deleted or set up to a new wl_compositor interface
97 * once there is a new connection available.
98 *
99 * It is suggested to connect this method to ConnectionThread::connectionDied:
100 * @code
101 * connect(connection, &ConnectionThread::connectionDied, compositor, &Compositor::destroy);
102 * @endcode
103 *
104 * @see release
105 **/
106 void destroy();
107
108 /**
109 * Sets the @p queue to use for creating a Surface.
110 **/
111 void setEventQueue(EventQueue *queue);
112 /**
113 * @returns The event queue to use for creating a Surface.
114 **/
115 EventQueue *eventQueue();
116
117 /**
118 * Creates and setup a new Surface with @p parent.
119 * @param parent The parent to pass to the Surface.
120 * @returns The new created Surface
121 **/
122 Surface *createSurface(QObject *parent = nullptr);
123
124 /**
125 * Creates and setup a new Region with @p parent.
126 * @param parent The parent to pass to the Region.
127 * @returns The new created Region
128 **/
129 Region *createRegion(QObject *parent = nullptr);
130 /**
131 * Creates and setup a new Region with @p parent.
132 *
133 * The @p region is directly added to the created Region.
134 * @param parent The parent to pass to the Region.
135 * @param region The region to install on the newly created Region
136 * @returns The new created Region
137 **/
138 Region *createRegion(const QRegion &region, QObject *parent);
139 /**
140 * Creates and setup a new Region with @p region installed.
141 *
142 * This overloaded convenience method is intended to be used in the
143 * case that the Region is only needed to setup e.g. input region on
144 * a Surface and is afterwards no longer needed. Setting the input
145 * region has copy semantics and the Region can be destroyed afterwards.
146 * This allows to simplify setting the input region to:
147 *
148 * @code
149 * Surface *s = compositor->createSurface();
150 * s->setInputRegion(compositor->createRegion(QRegion(0, 0, 10, 10)).get());
151 * @endcode
152 *
153 * @param region The region to install on the newly created Region
154 * @returns The new created Region
155 **/
156 std::unique_ptr<Region> createRegion(const QRegion &region);
157
158 operator wl_compositor *();
159 operator wl_compositor *() const;
160
161Q_SIGNALS:
162 /**
163 * The corresponding global for this interface on the Registry got removed.
164 *
165 * This signal gets only emitted if the Compositor got created by
166 * Registry::createCompositor
167 *
168 * @since 5.5
169 **/
170 void removed();
171
172private:
173 class Private;
174 QScopedPointer<Private> d;
175};
176
177}
178}
179
180#endif
181

source code of kwayland/src/client/compositor.h