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

KDE's Doxygen guidelines are available online.