KWayland

surface_interface.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_SERVER_SURFACE_INTERFACE_H
7 #define WAYLAND_SERVER_SURFACE_INTERFACE_H
8 
9 #include "output_interface.h"
10 #include "resource.h"
11 
12 #include <QObject>
13 #include <QPointer>
14 #include <QRegion>
15 
16 #include <KWayland/Server/kwaylandserver_export.h>
17 
18 namespace KWayland
19 {
20 namespace Server
21 {
22 class BlurManagerInterface;
23 class BlurInterface;
24 class BufferInterface;
25 class ConfinedPointerInterface;
26 class ContrastInterface;
27 class ContrastManagerInterface;
28 class CompositorInterface;
29 class IdleInhibitManagerUnstableV1Interface;
30 class LockedPointerInterface;
31 class PointerConstraintsUnstableV1Interface;
32 class ShadowManagerInterface;
33 class ShadowInterface;
34 class SlideInterface;
35 class SubSurfaceInterface;
36 
37 /**
38  * @brief Resource representing a wl_surface.
39  *
40  * The SurfaceInterface gets created by the CompositorInterface. A SurfaceInterface normally
41  * takes up a role by being "attached" to either a ShellSurfaceInterface, a SubSurfaceInterface
42  * or a Cursor.
43  *
44  * The implementation of the SurfaceInterface does not only wrap the features exposed by wl_surface,
45  * but goes further by integrating the information added to a SurfaceInterface by other interfaces.
46  * This should make interacting from the server easier, it only needs to monitor the SurfaceInterface
47  * and does not need to track each specific interface.
48  *
49  * The SurfaceInterface takes care of reference/unreferencing the BufferInterface attached to it.
50  * As long as a BufferInterface is attached, the released signal won't be sent. If the BufferInterface
51  * is no longer needed by the SurfaceInterface, it will get unreferenced and might be automatically
52  * deleted (if it's no longer referenced).
53  *
54  * @see CompositorInterface
55  * @see BufferInterface
56  * @see SubSurfaceInterface
57  * @see BlurInterface
58  * @see ContrastInterface
59  * @see ShadowInterface
60  * @see SlideInterface
61  **/
62 class KWAYLANDSERVER_EXPORT SurfaceInterface : public Resource
63 {
64  Q_OBJECT
65  /**
66  * The current damage region.
67  **/
68  Q_PROPERTY(QRegion damage READ damage NOTIFY damaged)
69  /**
70  * The opaque region for a translucent buffer.
71  **/
72  Q_PROPERTY(QRegion opaque READ opaque NOTIFY opaqueChanged)
73  /**
74  * The current input region.
75  **/
76  Q_PROPERTY(QRegion input READ input NOTIFY inputChanged)
77  Q_PROPERTY(qint32 scale READ scale NOTIFY scaleChanged)
78  Q_PROPERTY(KWayland::Server::OutputInterface::Transform transform READ transform NOTIFY transformChanged)
79  Q_PROPERTY(QSize size READ size NOTIFY sizeChanged)
80 public:
81  virtual ~SurfaceInterface();
82 
83  void frameRendered(quint32 msec);
84 
85  QRegion damage() const;
86  QRegion opaque() const;
87  QRegion input() const;
88 #if KWAYLANDSERVER_ENABLE_DEPRECATED_SINCE(5, 5)
89  /**
90  * Use Surface::inputIsInfinite instead.
91  * @deprecated Since 5.5, use inputIsInfinite
92  */
93  KWAYLANDSERVER_DEPRECATED_VERSION(5, 5, "Use SurfaceInterface::inputIsInfinite()")
94  bool inputIsInfitine() const;
95 #endif
96  /**
97  * Replaces Surface::inputIsInfitine instead.
98  * @since 5.5
99  */
100  bool inputIsInfinite() const;
101  qint32 scale() const;
102  OutputInterface::Transform transform() const;
103  /**
104  * @returns the current BufferInterface, might be @c nullptr.
105  **/
106  BufferInterface *buffer();
107  QPoint offset() const;
108  /**
109  * The size of the Surface in global compositor space.
110  * @see For buffer size use BufferInterface::size
111  * from SurfaceInterface::buffer
112  * @since 5.3
113  **/
114  QSize size() const;
115  /**
116  * Returns the rectangle that bounds this surface and all of its sub-surfaces.
117  *
118  * QPoint(0, 0) corresponds to the upper left corner of this surface.
119  *
120  * @since 5.69
121  */
122  QRect boundingRect() const;
123 
124  /**
125  * @returns The SubSurface for this Surface in case there is one.
126  **/
127  QPointer<SubSurfaceInterface> subSurface() const;
128  /**
129  * @returns Children in stacking order from bottom (first) to top (last).
130  **/
131  QList<QPointer<SubSurfaceInterface>> childSubSurfaces() const;
132 
133  /**
134  * @returns The Shadow for this Surface.
135  * @since 5.4
136  **/
137  QPointer<ShadowInterface> shadow() const;
138 
139  /**
140  * @returns The Blur for this Surface.
141  * @since 5.5
142  **/
143  QPointer<BlurInterface> blur() const;
144 
145  /**
146  * @returns The Slide for this Surface.
147  * @since 5.5
148  **/
149  QPointer<SlideInterface> slideOnShowHide() const;
150 
151  /**
152  * @returns The Contrast for this Surface.
153  * @since 5.5
154  **/
155  QPointer<ContrastInterface> contrast() const;
156 
157  /**
158  * Whether the SurfaceInterface is currently considered to be mapped.
159  * A SurfaceInterface is mapped if it has a non-null BufferInterface attached.
160  * If the SurfaceInterface references a SubSurfaceInterface it is only considered
161  * mapped if it has a BufferInterface attached and the parent SurfaceInterface is mapped.
162  *
163  * @returns Whether the SurfaceInterface is currently mapped
164  * @since 5.22
165  **/
166  bool isMapped() const;
167 
168  /**
169  * Returns the tracked damage since the last call to {@link resetTrackedDamage}.
170  * In contrast to {@link damage} this method does not reset the damage when
171  * a new BufferInterface gets committed. This allows a compositor to properly
172  * track the damage over multiple commits even if it didn't render each new
173  * BufferInterface.
174  *
175  * The damage gets reset whenever {@link resetTrackedDamage} is called.
176  * This allows a compositor to properly track the change in its rendering scene
177  * for this SurfaceInterface. After it updates its internal state (e.g. by creating
178  * an OpenGL texture from the BufferInterface) it can invoke {@link resetTrackedDamage}
179  * and the damage tracker will start to track further damage changes.
180  *
181  * @returns Combined damage since last call to resetTrackedDamage
182  * @see damage
183  * @see resetTrackedDamage
184  * @since 5.22
185  **/
186  QRegion trackedDamage() const;
187 
188  /**
189  * Reset the damage tracking. The compositor should invoke this method once it updated
190  * it's internal state and processed the current damage.
191  * @see trackedDamage
192  * @since 5.22
193  **/
194  void resetTrackedDamage();
195 
196  /**
197  * Finds the SurfaceInterface at the given @p position in surface-local coordinates.
198  * This can be either a descendant SurfaceInterface honoring the stacking order or
199  * the SurfaceInterface itself if its geometry contains the given @p position.
200  *
201  * If no such SurfaceInterface is found, e.g. because the SurfaceInterface is unmapped,
202  * @c nullptr is returned.
203  *
204  * @param position The position in surface-local coordinates
205  * @returns Child surface at the given @p position or surface itself at the position, might be @c nullptr
206  * @since 5.22
207  **/
208  SurfaceInterface *surfaceAt(const QPointF &position);
209 
210  /**
211  * Finds the input receiving SurfaceInterface at the given @p position in surface-local coordinates.
212  * This can be either a descendant SurfaceInterface honoring the stacking order or
213  * the SurfaceInterface itself if its geometry contains the given @p position.
214  *
215  * If no such SurfaceInterface is found, e.g. because the SurfaceInterface is unmapped or there is no
216  * input region containing the position,
217  * @c nullptr is returned.
218  *
219  * @param position The position in surface-local coordinates
220  * @returns Input receiving child surface at the given @p position or surface itself at the position, might be @c nullptr
221  * @since 5.52
222  **/
223  SurfaceInterface *inputSurfaceAt(const QPointF &position);
224 
225  /**
226  * Sets the @p outputs this SurfaceInterface overlaps with, may be empty.
227  *
228  * The compositor should update whenever the SurfaceInterface becomes visible on
229  * an OutputInterface by e.g. getting (un)mapped, resized, moved, etc.
230  *
231  * @see outputs
232  * @since 5.27
233  **/
234  void setOutputs(const QVector<OutputInterface *> &outputs);
235 
236  /**
237  * @returns All OutputInterfaces the SurfaceInterface is on.
238  * @see setOutputs
239  * @since 5.27
240  **/
241  QVector<OutputInterface *> outputs() const;
242 
243  /**
244  * Pointer confinement installed on this SurfaceInterface.
245  * @see pointerConstraintsChanged
246  * @since 5.29
247  **/
248  QPointer<ConfinedPointerInterface> confinedPointer() const;
249 
250  /**
251  * Pointer lock installed on this SurfaceInterface.
252  * @see pointerConstraintsChanged
253  * @since 5.29
254  **/
255  QPointer<LockedPointerInterface> lockedPointer() const;
256 
257  /**
258  * @returns Whether this SurfaceInterface wants idle to be inhibited on the Output it is shown
259  * @see inhibitsIdleChanged
260  * @since 5.41
261  **/
262  bool inhibitsIdle() const;
263 
264  /**
265  * @returns The SurfaceInterface for the @p native resource.
266  **/
267  static SurfaceInterface *get(wl_resource *native);
268  /**
269  * @returns The SurfaceInterface with given @p id for @p client, if it exists, otherwise @c nullptr.
270  * @since 5.3
271  **/
272  static SurfaceInterface *get(quint32 id, const ClientConnection *client);
273 
274  /**
275  * Set @p surface as a data proxy for this SurfaceInterface. This enables
276  * the proxy to conduct drags on the surface's client behalf.
277  *
278  * Setting a data proxy is only allowed when the client owning this surface
279  * has not created a data device itself.
280  * @since 5.56
281  **/
282  void setDataProxy(SurfaceInterface *surface);
283  /**
284  * Returns the data proxy of this SurfaceInterface or null if there
285  * is none set.
286  * @since 5.56
287  **/
288  SurfaceInterface *dataProxy() const;
289 
290 Q_SIGNALS:
291  /**
292  * Emitted whenever the SurfaceInterface got damaged.
293  * The signal is only emitted during the commit of state.
294  * A damage means that a new BufferInterface got attached.
295  *
296  * @see buffer
297  * @see damage
298  **/
299  void damaged(const QRegion &);
300  void opaqueChanged(const QRegion &);
301  void inputChanged(const QRegion &);
302  void scaleChanged(qint32);
303  void transformChanged(KWayland::Server::OutputInterface::Transform);
304  /**
305  * Emitted when the Surface removes its content
306  **/
307  void unmapped();
308  /**
309  * @since 5.3
310  **/
311  void sizeChanged();
312  /**
313  * @since 5.4
314  **/
315  void shadowChanged();
316  /**
317  * @since 5.5
318  **/
319  void blurChanged();
320  /**
321  * @since 5.5
322  **/
323  void slideOnShowHideChanged();
324  /**
325  * @since 5.5
326  **/
327  void contrastChanged();
328  /**
329  * Emitted whenever the tree of sub-surfaces changes in a way which requires a repaint.
330  * @since 5.22
331  **/
332  void subSurfaceTreeChanged();
333  /**
334  * Emitted whenever a new child sub-surface @p subSurface is added.
335  * @since 5.70
336  */
337  void childSubSurfaceAdded(SubSurfaceInterface *subSurface);
338  /**
339  * Emitted whenever the child sub-surface @p subSurface is removed.
340  * @since 5.70
341  */
342  void childSubSurfaceRemoved(SubSurfaceInterface *subSurface);
343 
344  /**
345  * Emitted whenever a pointer constraint get (un)installed on this SurfaceInterface.
346  *
347  * The pointer constraint does not get activated, the compositor needs to activate
348  * the lock/confinement.
349  *
350  * @see confinedPointer
351  * @see lockedPointer
352  * @since 5.29
353  **/
354  void pointerConstraintsChanged();
355 
356  /**
357  * Emitted whenever the SurfaceInterface starts/ends to inhibit idle.
358  * @see inhibitsIdle
359  * @since 5.41
360  **/
361  void inhibitsIdleChanged();
362 
363  /**
364  * Emitted when the Surface has been committed.
365  *
366  * This signal is emitted after all the relevant damage and xyzChanged signals
367  * for this commit are emitted.
368  * @since 5.54
369  **/
370  void committed();
371 
372 private:
373  friend class CompositorInterface;
374  friend class SubSurfaceInterface;
375  friend class ShadowManagerInterface;
376  friend class BlurManagerInterface;
377  friend class SlideManagerInterface;
378  friend class ContrastManagerInterface;
379  friend class IdleInhibitManagerUnstableV1Interface;
380  friend class PointerConstraintsUnstableV1Interface;
381  friend class SurfaceRole;
382  explicit SurfaceInterface(CompositorInterface *parent, wl_resource *parentResource);
383 
384  class Private;
385  Private *d_func() const;
386 };
387 
388 }
389 }
390 
391 Q_DECLARE_METATYPE(KWayland::Server::SurfaceInterface *)
392 
393 #endif
Global for the wl_output interface.
Resource representing a wl_surface.
Represents the Global for org_kde_kwin_contrast_manager interface.
Reference counted representation of a Wayland buffer on Server side.
Represents the Global for org_kde_kwin_blur_manager interface.
Represents the Global for wl_compositor interface.
Represents a bound Resource.
Definition: resource.h:31
Convenient Class which represents a wl_client.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:10 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.