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

KDE's Doxygen guidelines are available online.