KWayland

surface.h
1 /*
2  SPDX-FileCopyrightText: 2014 Martin Gräßlin <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 #ifndef WAYLAND_SURFACE_H
7 #define WAYLAND_SURFACE_H
8 
9 #include "buffer.h"
10 
11 #include <QObject>
12 #include <QPoint>
13 #include <QSize>
14 #include <QWindow>
15 
16 #include <KWayland/Client/kwaylandclient_export.h>
17 
18 struct wl_buffer;
19 struct wl_surface;
20 
21 class QWindow;
22 
23 namespace KWayland
24 {
25 namespace Client
26 {
27 
28 class Output;
29 class Region;
30 
31 /**
32  * @short Wrapper for the wl_surface interface.
33  *
34  * This class is a convenient wrapper for the wl_surface interface.
35  * To create a Surface call Compositor::createSurface.
36  *
37  * The main purpose of this class is to setup the next frame which
38  * should be rendered. Therefore it provides methods to add damage
39  * and to attach a new Buffer and to finalize the frame by calling
40  * commit.
41  *
42  * @see Compositor
43  **/
44 class KWAYLANDCLIENT_EXPORT Surface : public QObject
45 {
46  Q_OBJECT
47 public:
48  explicit Surface(QObject *parent = nullptr);
49  virtual ~Surface();
50 
51  /**
52  * Creates a Surface for the given @p window.
53  * This is an integration feature for QtWayland. On non-wayland platforms this method returns
54  * @c nullptr as well as for not created QWindows.
55  *
56  * The returned Surface will be fully setup, but won't be released. It gets automatically
57  * destroyed together with the @p window.
58  * @since 5.4
59  **/
60  static Surface *fromWindow(QWindow *window);
61 
62  /**
63  * Creates a Surface for the given @p winId.
64  * This is an integration feature for QtWayland. On non-wayland platforms this method returns
65  * @c nullptr as well as for not created QWindows.
66  *
67  * The returned Surface will be fully setup, but won't be released. It gets automatically
68  * destroyed together with the QWindow corresponding
69  * the @p wid.
70  * @since 5.5
71  **/
72  static Surface *fromQtWinId(WId wid);
73 
74  /**
75  * Setup this Surface to manage the @p surface.
76  * When using Compositor::createSurface there is no need to call this
77  * method.
78  **/
79  void setup(wl_surface *surface);
80  /**
81  * Releases the wl_surface interface.
82  * After the interface has been released the Surface instance is no
83  * longer valid and can be setup with another wl_surface interface.
84  **/
85  void release();
86  /**
87  * Destroys the data held by this Surface.
88  * This method is supposed to be used when the connection to the Wayland
89  * server goes away. If the connection is not valid anymore, it's not
90  * possible to call release anymore as that calls into the Wayland
91  * connection and the call would fail. This method cleans up the data, so
92  * that the instance can be deleted or set up to a new wl_surface interface
93  * once there is a new connection available.
94  *
95  * This method is automatically invoked when the Registry which created this
96  * Surface gets destroyed.
97  *
98  * @see release
99  **/
100  void destroy();
101  /**
102  * @returns @c true if managing a wl_surface.
103  **/
104  bool isValid() const;
105  /**
106  * Registers a frame rendered callback.
107  * This registers a callback in the Wayland server to be notified once the
108  * next frame for this Surface has been rendered. The Surface will emit the
109  * signal frameRendered after receiving the callback from the server.
110  *
111  * Instead of using this method one should prefer using the CommitFlag::FrameCallback
112  * in commit. This method is intended for cases when the Surface is going to
113  * be committed on other ways, e.g. through the OpenGL/EGL stack.
114  *
115  * @see frameRendered
116  * @see commit
117  **/
118  void setupFrameCallback();
119  /**
120  * Flags to be added to commit.
121  * @li None: no flag
122  * @li FrameCallback: register a frame rendered callback
123  *
124  * Instead of setting the FrameCallback flag one can also call
125  * setupFrameCallback. If one uses setupFrameCallback one may not
126  * use the FrameCallback flag when committing the Surface.
127  *
128  * @see commit
129  * @see setupFrameCallback
130  **/
131  enum class CommitFlag {
132  None,
133  FrameCallback
134  };
135  void commit(CommitFlag flag = CommitFlag::FrameCallback);
136  /**
137  * Mark @p rect as damaged for the next frame.
138  * @see damageBuffer
139  **/
140  void damage(const QRect &rect);
141  /**
142  * Mark @p region as damaged for the next frame.
143  * @see damageBuffer
144  **/
145  void damage(const QRegion &region);
146  /**
147  * Mark @p rect in buffer coordinates as damaged for the next frame.
148  * @see damage
149  * @since 5.59
150  **/
151  void damageBuffer(const QRect &rect);
152  /**
153  * Mark @p region in buffer coordinates as damaged for the next frame.
154  * @see damage
155  * @since 5.59
156  **/
157  void damageBuffer(const QRegion &region);
158  /**
159  * Attaches the @p buffer to this Surface for the next frame.
160  * @param buffer The buffer to attach to this Surface
161  * @param offset Position of the new upper-left corner in relation to previous frame
162  **/
163  void attachBuffer(wl_buffer *buffer, const QPoint &offset = QPoint());
164  /**
165  * Overloaded method for convenience.
166  **/
167  void attachBuffer(Buffer *buffer, const QPoint &offset = QPoint());
168  /**
169  * Overloaded method for convenience.
170  **/
171  void attachBuffer(Buffer::Ptr buffer, const QPoint &offset = QPoint());
172  /**
173  * Sets the input region to @p region.
174  *
175  * This is a double buffered state and will be applied with the next Surface
176  * commit. Initially the Surface is set up to an infinite input region.
177  * By passing @c null as the input region, it gets reset to an infinite input
178  * region.
179  *
180  * Note: the Region is being copied and can be destroyed directly after passing
181  * to this method.
182  *
183  * @param region The new input region or an infinite region if @c null
184  * @see commit
185  **/
186  void setInputRegion(const Region *region = nullptr);
187  /**
188  * Sets the opaque region to @p region.
189  *
190  * This is a double buffered state and will be applied with the next Surface
191  * commit. Initially the Surface is set up to an empty opaque region.
192  * By passing @c null as the opaque region, it gets reset to an empty opaque
193  * region.
194  *
195  * Note: the Region is being copied and can be destroyed directly after passing
196  * to this method.
197  *
198  * @param region The new opaque region or an empty region if @c null
199  * @see commit
200  **/
201  void setOpaqueRegion(const Region *region = nullptr);
202  void setSize(const QSize &size);
203  QSize size() const;
204 
205  /**
206  * The purpose of this method is to allow to supply higher resolution buffer data for use
207  * on high resolution outputs. It's intended that the same buffer scale as the scale of the
208  * output that the surface is displayed on is used.
209  * This means the compositor can avoid scaling when rendering the surface on that output.
210  *
211  * Note that if @p scale is larger than 1 you have to attach a buffer that is larger
212  * (by a factor of scale in each dimension) than the desired surface size.
213  *
214  * The default scale factor is 1.
215  *
216  * The state is only applied with the next commit.
217  *
218  * @see scale
219  * @see commit
220  * @since 5.22
221  **/
222  void setScale(qint32 scale);
223  /**
224  * @returns The current scale factor, if not explicitly set it's @c 1.
225  * @see setScale
226  * @since 5.22
227  **/
228  qint32 scale() const;
229 
230  operator wl_surface*();
231  operator wl_surface*() const;
232 
233  /**
234  * @returns the id of the referenced wl_proxy.
235  * @since 5.4
236  **/
237  quint32 id() const;
238 
239  /**
240  * @returns All Outputs the Surface is on, may be none.
241  * @see outputEntered
242  * @see outputLeft
243  * @since 5.27
244  **/
245  QVector<Output *> outputs() const;
246 
247  /**
248  * All Surfaces which are currently created.
249  * TODO: KF6 return QList<Surface*> instead of const-ref
250  **/
251  static const QList<Surface*> &all(); // krazy:exclude=constref
252  /**
253  * @returns The Surface referencing the @p native wl_surface or @c null if there is no such Surface.
254  **/
255  static Surface *get(wl_surface *native);
256 
257 Q_SIGNALS:
258  /**
259  * Emitted when the server indicates that the last committed frame has been rendered.
260  * The signal will only be emitted if a callback has been registered by either calling
261  * setupFrameCallback or calling commit with the CommitFlag::FrameCallback.
262  * @see setupFrameCallback
263  * @see commit
264  **/
265  void frameRendered();
266  void sizeChanged(const QSize&);
267 
268  /**
269  * Emitted whenever a change in the Surface (e.g. creation, movement, resize) results in
270  * a part of the Surface being within the scanout region of the Output @p o.
271  *
272  * @param o The Output the Surface intersects with
273  * @see outputLeft
274  * @see outputs
275  * @since 5.27
276  **/
277  void outputEntered(KWayland::Client::Output *o);
278 
279  /**
280  * Emitted whenever a change in the Surface (e.g. creation, movement, resize, unmapping)
281  * results in the Surface no longer being within the scanout region of the Output @p o.
282  *
283  * @param o The Output the Surface no longer intersects with
284  * @see outputEntered
285  * @see outputs
286  * @since 5.27
287  **/
288  void outputLeft(KWayland::Client::Output *o);
289 
290 private:
291  class Private;
293 };
294 
295 }
296 }
297 
298 #endif
Wrapper class for wl_buffer interface.
Definition: buffer.h:31
CommitFlag
Flags to be added to commit.
Definition: surface.h:131
Wrapper for the wl_output interface.
Definition: output.h:55
Wrapper for the wl_surface interface.
Definition: surface.h:44
Wrapper for the wl_region interface.
Definition: region.h:32
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Apr 16 2021 22:50:13 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.