KWayland

outputdevice.h
1 /*
2  SPDX-FileCopyrightText: 2013 Martin Gräßlin <[email protected]>
3  SPDX-FileCopyrightText: 2018 Roman Gilg <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6 */
7 #ifndef WAYLAND_OUTPUTDEVICE_H
8 #define WAYLAND_OUTPUTDEVICE_H
9 
10 #include <QObject>
11 #include <QPointer>
12 #include <QSize>
13 #include <QVector>
14 
15 #include <KWayland/Client/kwaylandclient_export.h>
16 
17 struct org_kde_kwin_outputdevice;
18 class QPoint;
19 class QRect;
20 
21 namespace KWayland
22 {
23 namespace Client
24 {
25 class EventQueue;
26 
27 /**
28  * @short Wrapper for the org_kde_kwin_outputdevice interface.
29  *
30  * This class provides a convenient wrapper for the org_kde_kwin_outputdevice interface.
31  * Its main purpose is to hold the information about one OutputDevice.
32  *
33  * To use this class one needs to interact with the Registry. There are two
34  * possible ways to create an OutputDevice interface:
35  * @code
36  * OutputDevice *c = registry->createOutputDevice(name, version);
37  * @endcode
38  *
39  * This creates the OutputDevice and sets it up directly. As an alternative this
40  * can also be done in a more low level way:
41  * @code
42  * OutputDevice *c = new OutputDevice;
43  * c->setup(registry->bindOutputDevice(name, version));
44  * @endcode
45  *
46  * The OutputDevice can be used as a drop-in replacement for any org_kde_kwin_outputdevice
47  * pointer as it provides matching cast operators.
48  *
49  * Please note that all properties of OutputDevice are not valid until the
50  * changed signal has been emitted. The wayland server is pushing the
51  * information in an async way to the OutputDevice instance. By emitting changed
52  * the OutputDevice indicates that all relevant information is available.
53  *
54  * @see Registry
55  * @since 5.5
56  **/
57 class KWAYLANDCLIENT_EXPORT OutputDevice : public QObject
58 {
59  Q_OBJECT
60 public:
61  enum class SubPixel {
62  Unknown,
63  None,
64  HorizontalRGB,
65  HorizontalBGR,
66  VerticalRGB,
67  VerticalBGR,
68  };
69  Q_ENUM(SubPixel)
70  enum class Transform {
71  Normal,
72  Rotated90,
73  Rotated180,
74  Rotated270,
75  Flipped,
76  Flipped90,
77  Flipped180,
78  Flipped270,
79  };
80  Q_ENUM(Transform)
81  enum class Enablement {
82  Disabled = 0,
83  Enabled = 1,
84  };
85  Q_ENUM(Enablement)
86  struct Mode {
87  enum class Flag {
88  None = 0,
89  Current = 1 << 0,
90  Preferred = 1 << 1,
91  };
92  Q_DECLARE_FLAGS(Flags, Flag)
93  /**
94  * The size of this Mode in pixel space.
95  **/
96  QSize size;
97  /**
98  * The refresh rate in mHz of this Mode.
99  **/
100  int refreshRate = 0;
101  /**
102  * The flags of this Mode, that is whether it's the
103  * Current and/or Preferred Mode of the OutputDevice.
104  **/
105  Flags flags = Flag::None;
106  /**
107  * The OutputDevice to which this Mode belongs.
108  **/
109  QPointer<OutputDevice> output;
110  /**
111  * The id of this mode, unique per OutputDevice. This id can be used to call
112  * OutputConfiguration->setMode();
113  * @see OutputConfiguration::setMode
114  **/
115  int id;
116 
117  bool operator==(const Mode &m) const;
118  };
119  struct ColorCurves {
120  QVector<quint16> red, green, blue;
121 
122  bool operator==(const ColorCurves &cc) const;
123  bool operator!=(const ColorCurves &cc) const;
124  };
125  enum class Capability {
126  Overscan = 0x1,
127  Vrr = 0x2,
128  };
129  Q_DECLARE_FLAGS(Capabilities, Capability)
130  enum class VrrPolicy {
131  Never = 0,
132  Always = 1,
133  Automatic = 2
134  };
135 
136  explicit OutputDevice(QObject *parent = nullptr);
137  virtual ~OutputDevice();
138 
139  /**
140  * Setup this Compositor to manage the @p output.
141  * When using Registry::createOutputDevice there is no need to call this
142  * method.
143  **/
144  void setup(org_kde_kwin_outputdevice *output);
145 
146  /**
147  * @returns @c true if managing a org_kde_kwin_outputdevice.
148  **/
149  bool isValid() const;
150  operator org_kde_kwin_outputdevice *();
151  operator org_kde_kwin_outputdevice *() const;
152  org_kde_kwin_outputdevice *output();
153  /**
154  * Size in millimeters.
155  **/
156  QSize physicalSize() const;
157  /**
158  * Position within the global compositor space.
159  **/
160  QPoint globalPosition() const;
161  /**
162  * Textual description of the manufacturer.
163  **/
164  QString manufacturer() const;
165  /**
166  * Textual description of the model.
167  **/
168  QString model() const;
169  /**
170  * Textual representation of serial number.
171  */
172  QString serialNumber() const;
173  /**
174  * Textual representation of EISA identifier.
175  */
176  QString eisaId() const;
177  /**
178  * Size in the current mode.
179  **/
180  QSize pixelSize() const;
181  /**
182  * The geometry of this OutputDevice in pixels.
183  * Convenient for QRect(globalPosition(), pixelSize()).
184  * @see globalPosition
185  * @see pixelSize
186  **/
187  QRect geometry() const;
188  /**
189  * Refresh rate in mHz of the current mode.
190  **/
191  int refreshRate() const;
192 
193 #if KWAYLANDCLIENT_ENABLE_DEPRECATED_SINCE(5, 50)
194  /**
195  * Scaling factor of this output.
196  *
197  * A scale larger than 1 means that the compositor will automatically scale surface buffers
198  * by this amount when rendering. This is used for very high resolution displays where
199  * applications rendering at the native resolution would be too small to be legible.
200  * @deprecated Since 5.50, use scaleF()
201  **/
202  KWAYLANDCLIENT_DEPRECATED_VERSION(5, 50, "Use OutputDevice::scaleF()")
203  int scale() const;
204 #endif
205 
206  /**
207  * Scaling factor of this output.
208  *
209  * A scale larger than 1 means that the compositor will automatically scale surface buffers
210  * by this amount when rendering. This is used for very high resolution displays where
211  * applications rendering at the native resolution would be too small to be legible.
212  * @since 5.50
213  **/
214  qreal scaleF() const;
215  /**
216  * Subpixel orientation of this OutputDevice.
217  **/
218  SubPixel subPixel() const;
219  /**
220  * Transform that maps framebuffer to OutputDevice.
221  *
222  * The purpose is mainly to allow clients render accordingly and tell the compositor,
223  * so that for fullscreen surfaces, the compositor will still be able to scan out
224  * directly from client surfaces.
225  **/
226  Transform transform() const;
227  /**
228  * Color curves.
229  * @since 5.50
230  **/
231  ColorCurves colorCurves() const;
232 
233  /**
234  * @returns The Modes of this OutputDevice.
235  **/
236  QList<Mode> modes() const;
237 
238  KWayland::Client::OutputDevice::Mode currentMode() const;
239 
240  /**
241  * Sets the @p queue to use for bound proxies.
242  **/
243  void setEventQueue(EventQueue *queue);
244  /**
245  * @returns The event queue to use for bound proxies.
246  **/
247  EventQueue *eventQueue() const;
248 
249  /**
250  * @returns The EDID information for this output.
251  **/
252  QByteArray edid() const;
253 
254  /**
255  * @returns Whether this output is enabled or not.
256  **/
257  OutputDevice::Enablement enabled() const;
258 
259  /**
260  * @returns A unique identifier for this outputdevice, determined by the server.
261  **/
262  QByteArray uuid() const;
263 
264  /**
265  * @returns the capabilities of this outputdevice
266  * @since 5.82
267  **/
268  Capabilities capabilities() const;
269 
270  /**
271  * @returns what overscan value this outputdevice is using
272  * @since 5.82
273  **/
274  uint32_t overscan() const;
275 
276  /**
277  * @returns the compositors policy regarding vrr on this output
278  * @since 5.82
279  */
280  VrrPolicy vrrPolicy() const;
281 
282  /**
283  * Destroys the data hold by this OutputDevice.
284  * This method is supposed to be used when the connection to the Wayland
285  * server goes away. If the connection is not valid any more, it's not
286  * possible to call release any more as that calls into the Wayland
287  * connection and the call would fail.
288  *
289  * This method is automatically invoked when the Registry which created this
290  * Output gets destroyed.
291  **/
292  void destroy();
293 
294 Q_SIGNALS:
295  /**
296  * Emitted when the output is fully initialized.
297  **/
298  void done();
299  /**
300  * Emitted whenever at least one of the data changed.
301  **/
302  void changed();
303  /**
304  * Emitted whenever the enabled property changes.
305  **/
306  void enabledChanged(OutputDevice::Enablement enabled);
307  /**
308  * Emitted whenever the id property changes.
309  **/
310  void uuidChanged(const QByteArray &uuid);
311  /**
312  * Emitted whenever a new Mode is added.
313  * This normally only happens during the initial promoting of modes.
314  * Afterwards only modeChanged should be emitted.
315  * @param mode The newly added Mode.
316  * @see modeChanged
317  **/
318  void modeAdded(const KWayland::Client::OutputDevice::Mode &mode);
319  /**
320  * Emitted whenever a Mode changes.
321  * This normally means that the @c Mode::Flag::Current is added or removed.
322  * @param mode The changed Mode
323  **/
324  void modeChanged(const KWayland::Client::OutputDevice::Mode &mode);
325  /**
326  * Emitted whenever the color curves changed.
327  *
328  * @since 5.TODO
329  **/
330  void colorCurvesChanged();
331  /**
332  * Emitted whenever the capabilities change
333  * @param capabilities the new capabilities
334  * @since 5.82
335  **/
336  void capabilitiesChanged(const Capabilities &capabilities);
337  /**
338  * Emitted whenever the overscan changes
339  * @param overscan the new overscan value
340  * @since 5.82
341  **/
342  void overscanChanged(uint32_t overscan);
343  /**
344  * Emitted whenever the variable refresh rate policy for this output changes
345  *
346  * @since 5.82
347  **/
348  void vrrPolicyChanged(VrrPolicy vrrPolicy);
349  /**
350  * The corresponding global for this interface on the Registry got removed.
351  *
352  * This signal gets only emitted if the OutputDevice got created by
353  * Registry::createOutputDevice
354  *
355  * @since 5.5
356  **/
357  void removed();
358 
359 private:
360  class Private;
362 };
363 
364 Q_DECLARE_OPERATORS_FOR_FLAGS(OutputDevice::Mode::Flags)
365 
366 }
367 }
368 
369 Q_DECLARE_METATYPE(KWayland::Client::OutputDevice::SubPixel)
370 Q_DECLARE_METATYPE(KWayland::Client::OutputDevice::Transform)
371 Q_DECLARE_METATYPE(KWayland::Client::OutputDevice::Enablement)
372 Q_DECLARE_METATYPE(KWayland::Client::OutputDevice::Mode)
373 Q_DECLARE_METATYPE(KWayland::Client::OutputDevice::ColorCurves)
374 
375 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the org_kde_kwin_outputdevice interface.
Definition: outputdevice.h:57
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Sep 24 2021 22:51:11 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.