KWaylandServer

surface_interface.h
1 /*
2  SPDX-FileCopyrightText: 2014 Martin Gräßlin <[email protected]>
3  SPDX-FileCopyrightText: 2020 Vlad Zahorodnii <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6 */
7 #pragma once
8 
9 #include "output_interface.h"
10 
11 #include <QMatrix4x4>
12 #include <QObject>
13 #include <QPointer>
14 #include <QRegion>
15 
16 #include <KWaylandServer/kwaylandserver_export.h>
17 
18 namespace KWaylandServer
19 {
20 class BlurInterface;
21 class ClientBuffer;
22 class ConfinedPointerV1Interface;
23 class ContrastInterface;
24 class CompositorInterface;
25 class LockedPointerV1Interface;
26 class ShadowInterface;
27 class SlideInterface;
28 class SubSurfaceInterface;
29 class SurfaceInterfacePrivate;
30 
31 /**
32  * @brief Resource representing a wl_surface.
33  *
34  * The SurfaceInterface gets created by the CompositorInterface. A SurfaceInterface normally
35  * takes up a role by being "attached" to either a ShellSurfaceInterface, a SubSurfaceInterface
36  * or a Cursor.
37  *
38  * The implementation of the SurfaceInterface does not only wrap the features exposed by wl_surface,
39  * but goes further by integrating the information added to a SurfaceInterface by other interfaces.
40  * This should make interacting from the server easier, it only needs to monitor the SurfaceInterface
41  * and does not need to track each specific interface.
42  *
43  * The SurfaceInterface takes care of reference/unreferencing the ClientBuffer attached to it.
44  * As long as a ClientBuffer is attached, the released signal won't be sent. If the ClientBuffer
45  * is no longer needed by the SurfaceInterface, it will get unreferenced and might be automatically
46  * deleted (if it's no longer referenced).
47  *
48  * @see CompositorInterface
49  * @see ClientBuffer
50  * @see SubSurfaceInterface
51  * @see BlurInterface
52  * @see ContrastInterface
53  * @see ShadowInterface
54  * @see SlideInterface
55  */
56 class KWAYLANDSERVER_EXPORT SurfaceInterface : public QObject
57 {
58  Q_OBJECT
59  /**
60  * The current damage region.
61  */
62  Q_PROPERTY(QRegion damage READ damage NOTIFY damaged)
63  /**
64  * The opaque region for a translucent buffer.
65  */
66  Q_PROPERTY(QRegion opaque READ opaque NOTIFY opaqueChanged)
67  /**
68  * The current input region.
69  */
70  Q_PROPERTY(QRegion input READ input NOTIFY inputChanged)
71  Q_PROPERTY(qint32 bufferScale READ bufferScale NOTIFY bufferScaleChanged)
72  Q_PROPERTY(KWaylandServer::OutputInterface::Transform bufferTransform READ bufferTransform NOTIFY bufferTransformChanged)
73  Q_PROPERTY(QSize size READ size NOTIFY sizeChanged)
74 public:
75  explicit SurfaceInterface(CompositorInterface *compositor, wl_resource *resource);
76  ~SurfaceInterface() override;
77 
78  /**
79  * Returns the object id for this Wayland surface.
80  */
81  uint32_t id() const;
82  /**
83  * Returns the Wayland client that owns this SurfaceInterface.
84  */
85  ClientConnection *client() const;
86  /**
87  * Returns the Wayland resource corresponding to this SurfaceInterface.
88  */
89  wl_resource *resource() const;
90  /**
91  * Returns the compositor for this SurfaceInterface.
92  */
93  CompositorInterface *compositor() const;
94 
95  /**
96  * Maps the specified @a point from the surface-local coordinates to buffer pixel coordinates.
97  *
98  * Note that there is no direct connection between points in the surface-local coordinates
99  * and points in the buffer pixel coordinates. In order to map points between the two spaces,
100  * one has to use mapToBuffer() and mapFromBuffer().
101  *
102  * The returned value will become invalid when the surfaceToBufferMatrixChanged() signal is emitted.
103  *
104  * @see surfaceToBufferMatrix(), surfaceToBufferMatrixChanged()
105  */
106  QPointF mapToBuffer(const QPointF &point) const;
107  /**
108  * Maps the specified @a point from the buffer pixel coordinates to surface-local coordinates.
109  *
110  * Note that there is no direct connection between points in the surface-local coordinates
111  * and points in the buffer pixel coordinates. In order to map points between the two spaces,
112  * one has to use mapToBuffer() and mapFromBuffer().
113  *
114  * The returned value will become invalid when the surfaceToBufferMatrixChanged() signal is emitted.
115  *
116  * @see surfaceToBufferMatrix(), surfaceToBufferMatrixChanged()
117  */
118  QPointF mapFromBuffer(const QPointF &point) const;
119  /**
120  * Maps the specified @a region from the surface-local coordinates to buffer pixel coordinates.
121  *
122  * Note that there is no direct connection between regions in the surface-local coordinates
123  * and regions in the buffer pixel coordinates. In order to map regions between the two spaces,
124  * one has to use mapToBuffer() and mapFromBuffer().
125  *
126  * The returned value will become invalid when the surfaceToBufferMatrixChanged() signal is emitted.
127  *
128  * @see surfaceToBufferMatrix(), surfaceToBufferMatrixChanged()
129  */
130  QRegion mapToBuffer(const QRegion &region) const;
131  /**
132  * Maps the specified @a region from the buffer pixel coordinates to surface-local coordinates.
133  *
134  * Note that there is no direct connection between regions in the surface-local coordinates
135  * and regions in the buffer pixel coordinates. In order to map regions between the two spaces,
136  * one has to use mapToBuffer() and mapFromBuffer().
137  *
138  * The returned value will become invalid when the surfaceToBufferMatrixChanged() signal is emitted.
139  *
140  * @see surfaceToBufferMatrix(), surfaceToBufferMatrixChanged()
141  */
142  QRegion mapFromBuffer(const QRegion &region) const;
143  /**
144  * Returns the projection matrix from the surface-local coordinates to buffer coordinates.
145  *
146  * @see surfaceToBufferMatrixChanged()
147  */
148  QMatrix4x4 surfaceToBufferMatrix() const;
149 
150  /**
151  * Maps the specified @a point in this surface's coordinate system to the equivalent point
152  * within the @a child's coordinate system, and returns the mapped point.
153  *
154  * If this surface is not an ancestor of the @a child, a null point is returned.
155  */
156  QPointF mapToChild(SurfaceInterface *child, const QPointF &point) const;
157 
158  void frameRendered(quint32 msec);
159  bool hasFrameCallbacks() const;
160 
161  QRegion damage() const;
162  QRegion opaque() const;
163  QRegion input() const;
164  qint32 bufferScale() const;
165  /**
166  * Returns the buffer transform that had been applied to the buffer to compensate for
167  * output rotation.
168  *
169  * If the surface is on an output that is rotated 90 degrees clockwise, the buffer will
170  * be rotated 90 degrees counter clockwise.
171  */
172  OutputInterface::Transform bufferTransform() const;
173  /**
174  * @returns the current ClientBuffer, might be @c nullptr.
175  */
176  ClientBuffer *buffer() const;
177  QPoint offset() const;
178  /**
179  * Returns the current size of the surface, in surface coordinates.
180  *
181  * Note that there is no direct relationship between the surface size and the buffer size.
182  * In order to determine the size of the currently attached buffer, use buffer()->size().
183  */
184  QSize size() const;
185  /**
186  * Returns the rectangle that bounds this surface and all of its sub-surfaces.
187  *
188  * QPoint(0, 0) corresponds to the upper left corner of this surface.
189  */
190  QRect boundingRect() const;
191  /**
192  * Returns the size of the attached buffer, in device pixels.
193  *
194  * If no buffer is attached to this surface, an invalid QSize will be returned.
195  */
196  QSize bufferSize() const;
197 
198  /**
199  * @returns The SubSurface for this Surface in case there is one.
200  */
201  SubSurfaceInterface *subSurface() const;
202  /**
203  * Returns the sub-surfaces that are below this surface. The sub-surfaces are sorted
204  * from bottom to top.
205  */
206  QList<SubSurfaceInterface *> below() const;
207  /**
208  * Returns the sub-surfaces that are above this surface. The sub-surfaces are sorted
209  * from bottom to top.
210  */
211  QList<SubSurfaceInterface *> above() const;
212 
213  /**
214  * @returns The Shadow for this Surface.
215  */
216  QPointer<ShadowInterface> shadow() const;
217 
218  /**
219  * @returns The Blur for this Surface.
220  */
221  QPointer<BlurInterface> blur() const;
222 
223  /**
224  * @returns The Slide for this Surface.
225  */
226  QPointer<SlideInterface> slideOnShowHide() const;
227 
228  /**
229  * @returns The Contrast for this Surface.
230  */
231  QPointer<ContrastInterface> contrast() const;
232 
233  /**
234  * Whether the SurfaceInterface is currently considered to be mapped.
235  * A SurfaceInterface is mapped if it has a non-null ClientBuffer attached.
236  * If the SurfaceInterface references a SubSurfaceInterface it is only considered
237  * mapped if it has a ClientBuffer attached and the parent SurfaceInterface is mapped.
238  *
239  * @returns Whether the SurfaceInterface is currently mapped
240  */
241  bool isMapped() const;
242 
243  /**
244  * Finds the SurfaceInterface at the given @p position in surface-local coordinates.
245  * This can be either a descendant SurfaceInterface honoring the stacking order or
246  * the SurfaceInterface itself if its geometry contains the given @p position.
247  *
248  * If no such SurfaceInterface is found, e.g. because the SurfaceInterface is unmapped,
249  * @c nullptr is returned.
250  *
251  * @param position The position in surface-local coordinates
252  * @returns Child surface at the given @p position or surface itself at the position, might be @c nullptr
253  */
254  SurfaceInterface *surfaceAt(const QPointF &position);
255 
256  /**
257  * Finds the input receiving SurfaceInterface at the given @p position in surface-local coordinates.
258  * This can be either a descendant SurfaceInterface honoring the stacking order or
259  * the SurfaceInterface itself if its geometry contains the given @p position.
260  *
261  * If no such SurfaceInterface is found, e.g. because the SurfaceInterface is unmapped or there is no
262  * input region containing the position,
263  * @c nullptr is returned.
264  *
265  * @param position The position in surface-local coordinates
266  * @returns Input receiving child surface at the given @p position or surface itself at the position, might be @c nullptr
267  */
268  SurfaceInterface *inputSurfaceAt(const QPointF &position);
269 
270  /**
271  * Sets the @p outputs this SurfaceInterface overlaps with, may be empty.
272  *
273  * The compositor should update whenever the SurfaceInterface becomes visible on
274  * an OutputInterface by e.g. getting (un)mapped, resized, moved, etc.
275  *
276  * @see outputs
277  */
278  void setOutputs(const QVector<OutputInterface *> &outputs);
279 
280  /**
281  * @returns All OutputInterfaces the SurfaceInterface is on.
282  * @see setOutputs
283  */
284  QVector<OutputInterface *> outputs() const;
285 
286  /**
287  * Pointer confinement installed on this SurfaceInterface.
288  * @see pointerConstraintsChanged
289  */
290  ConfinedPointerV1Interface *confinedPointer() const;
291 
292  /**
293  * Pointer lock installed on this SurfaceInterface.
294  * @see pointerConstraintsChanged
295  */
296  LockedPointerV1Interface *lockedPointer() const;
297 
298  /**
299  * @returns Whether this SurfaceInterface wants idle to be inhibited on the Output it is shown
300  * @see inhibitsIdleChanged
301  */
302  bool inhibitsIdle() const;
303 
304  /**
305  * @returns The SurfaceInterface for the @p native resource.
306  */
307  static SurfaceInterface *get(wl_resource *native);
308  /**
309  * @returns The SurfaceInterface with given @p id for @p client, if it exists, otherwise @c nullptr.
310  */
311  static SurfaceInterface *get(quint32 id, const ClientConnection *client);
312 
313 Q_SIGNALS:
314  /**
315  * This signal is emitted when the underlying wl_surface resource is about to be freed.
316  *
317  * The unbound() signal is emitted either when the client that owns the surface has been
318  * destroyed or if the surface has been destroyed due to a destructor request.
319  *
320  * The SurfaceInterface object and the associated wl_surface resource are valid when this
321  * signal is emitted.
322  */
323  void aboutToBeDestroyed();
324  /**
325  * This signal is emitted when the projection matrix from the surface-local coordinate space
326  * to the buffer coordinate space has been changed.
327  *
328  * Note that the compositor will most likely need to re-compute the texture coordinates after
329  * the surface-to-buffer matrix has been changed.
330  */
331  void surfaceToBufferMatrixChanged();
332  /**
333  * Emitted whenever the SurfaceInterface got damaged.
334  * The signal is only emitted during the commit of state.
335  * A damage means that a new ClientBuffer got attached.
336  *
337  * @see buffer
338  * @see damage
339  */
340  void damaged(const QRegion &);
341  void opaqueChanged(const QRegion &);
342  void inputChanged(const QRegion &);
343  /**
344  * This signal is emitted when the scale of the attached buffer has changed.
345  */
346  void bufferScaleChanged(qint32);
347  /**
348  * This signal is emitted when the buffer transform has changed.
349  */
350  void bufferTransformChanged(KWaylandServer::OutputInterface::Transform);
351  /**
352  * This signal is emitted when the size of the attached buffer has changed.
353  */
354  void bufferSizeChanged();
355  /**
356  * Emitted when the Surface becomes visible, i.e. a non-null buffer has been attached.
357  */
358  void mapped();
359  /**
360  * Emitted when the Surface removes its content
361  */
362  void unmapped();
363  /**
364  * This signal is emitted when the surface size has changed.
365  */
366  void sizeChanged();
367  void shadowChanged();
368  void blurChanged();
369  void slideOnShowHideChanged();
370  void contrastChanged();
371  /**
372  * Emitted whenever a new child sub-surface @p subSurface is added.
373  */
374  void childSubSurfaceAdded(SubSurfaceInterface *subSurface);
375  /**
376  * Emitted whenver the child sub-surface @p subSurface is removed.
377  */
378  void childSubSurfaceRemoved(SubSurfaceInterface *subSurface);
379  /**
380  * This signal is emitted when the list of child subsurfaces changes.
381  */
382  void childSubSurfacesChanged();
383 
384  /**
385  * Emitted whenever a pointer constraint get (un)installed on this SurfaceInterface.
386  *
387  * The pointer constraint does not get activated, the compositor needs to activate
388  * the lock/confinement.
389  *
390  * @see confinedPointer
391  * @see lockedPointer
392  */
393  void pointerConstraintsChanged();
394 
395  /**
396  * Emitted whenever the SurfaceInterface starts/ends to inhibit idle.
397  * @see inhibitsIdle
398  */
399  void inhibitsIdleChanged();
400 
401  /**
402  * Emitted when the Surface has been committed.
403  *
404  * This signal is emitted after all the relevant damage and xyzChanged signals
405  * for this commit are emitted.
406  */
407  void committed();
408 
409 private:
410  QScopedPointer<SurfaceInterfacePrivate> d;
411  friend class SurfaceInterfacePrivate;
412 };
413 
414 }
415 
416 Q_DECLARE_METATYPE(KWaylandServer::SurfaceInterface *)
The OutputInterface class represents a screen.
The ConfinedPointerV1Interface gets installed on a SurfaceInterface.
Represents the Resource for the org_kde_kwin_blur interface.
Represents the Resource for the org_kde_kwin_contrast interface.
The SubSurfaceInterface corresponds to the Wayland interface wl_subsurface.
Convenient Class which represents a wl_client.
Resource representing a wl_surface.
The ClientBuffer class represents a client buffer.
Definition: clientbuffer.h:29
The LockedPointerV1Interface lets the client request to disable movements of the virtual pointer (i...
The CompositorInterface global allows clients to create surfaces and region objects.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Oct 24 2021 23:08:29 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.