KWayland

output.h
1 /*
2  SPDX-FileCopyrightText: 2013 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_OUTPUT_H
7 #define WAYLAND_OUTPUT_H
8 
9 #include <QObject>
10 #include <QPointer>
11 #include <QSize>
12 
13 #include <KWayland/Client/kwaylandclient_export.h>
14 
15 struct wl_output;
16 class QPoint;
17 class QRect;
18 
19 namespace KWayland
20 {
21 namespace Client
22 {
23 
24 class EventQueue;
25 
26 /**
27  * @short Wrapper for the wl_output interface.
28  *
29  * This class provides a convenient wrapper for the wl_output interface.
30  * Its main purpose is to hold the information about one Output.
31  *
32  * To use this class one needs to interact with the Registry. There are two
33  * possible ways to create an Output interface:
34  * @code
35  * Output *c = registry->createOutput(name, version);
36  * @endcode
37  *
38  * This creates the Output and sets it up directly. As an alternative this
39  * can also be done in a more low level way:
40  * @code
41  * Output *c = new Output;
42  * c->setup(registry->bindOutput(name, version));
43  * @endcode
44  *
45  * The Output can be used as a drop-in replacement for any wl_output
46  * pointer as it provides matching cast operators.
47  *
48  * Please note that all properties of Output are not valid until the
49  * changed signal has been emitted. The wayland server is pushing the
50  * information in an async way to the Output instance. By emitting changed
51  * the Output indicates that all relevant information is available.
52  *
53  * @see Registry
54  **/
55 class KWAYLANDCLIENT_EXPORT Output : public QObject
56 {
57  Q_OBJECT
58 public:
59  enum class SubPixel {
60  Unknown,
61  None,
62  HorizontalRGB,
63  HorizontalBGR,
64  VerticalRGB,
65  VerticalBGR
66  };
67  enum class Transform {
68  Normal,
69  Rotated90,
70  Rotated180,
71  Rotated270,
72  Flipped,
73  Flipped90,
74  Flipped180,
75  Flipped270
76  };
77  struct Mode {
78  enum class Flag {
79  None = 0,
80  Current = 1 << 0,
81  Preferred = 1 << 1
82  };
83  Q_DECLARE_FLAGS(Flags, Flag)
84  /**
85  * The size of this Mode in pixel space.
86  **/
87  QSize size;
88  /**
89  * The refresh rate in mHz of this Mode.
90  **/
91  int refreshRate = 0;
92  /**
93  * The flags of this Mode, that is whether it's the
94  * Current and/or Preferred Mode of the Output.
95  **/
96  Flags flags = Flag::None;
97  /**
98  * The Output to which this Mode belongs.
99  **/
100  QPointer<Output> output;
101 
102  bool operator==(const Mode &m) const;
103  };
104  explicit Output(QObject *parent = nullptr);
105  virtual ~Output();
106 
107  /**
108  * Setup this Compositor to manage the @p output.
109  * When using Registry::createOutput there is no need to call this
110  * method.
111  **/
112  void setup(wl_output *output);
113 
114  /**
115  * @returns @c true if managing a wl_output.
116  **/
117  bool isValid() const;
118  operator wl_output*();
119  operator wl_output*() const;
120  wl_output *output();
121  /**
122  * Size in millimeters.
123  **/
124  QSize physicalSize() const;
125  /**
126  * Position within the global compositor space.
127  **/
128  QPoint globalPosition() const;
129  /**
130  * Textual description of the manufacturer.
131  **/
132  QString manufacturer() const;
133  /**
134  * Textual description of the model.
135  **/
136  QString model() const;
137  /**
138  * Size in the current mode.
139  **/
140  QSize pixelSize() const;
141  /**
142  * The geometry of this Output in pixels.
143  * Convenient for QRect(globalPosition(), pixelSize()).
144  * @see globalPosition
145  * @see pixelSize
146  **/
147  QRect geometry() const;
148  /**
149  * Refresh rate in mHz of the current mode.
150  **/
151  int refreshRate() const;
152  /**
153  * Scaling factor of this output.
154  *
155  * A scale larger than 1 means that the compositor will automatically scale surface buffers
156  * by this amount when rendering. This is used for very high resolution displays where
157  * applications rendering at the native resolution would be too small to be legible.
158  **/
159  int scale() const;
160  /**
161  * Subpixel orientation of this Output.
162  **/
163  SubPixel subPixel() const;
164  /**
165  * Transform that maps framebuffer to Output.
166  *
167  * The purpose is mainly to allow clients render accordingly and tell the compositor,
168  * so that for fullscreen surfaces, the compositor will still be able to scan out
169  * directly from client surfaces.
170  **/
171  Transform transform() const;
172 
173  /**
174  * @returns The Modes of this Output.
175  **/
176  QList<Mode> modes() const;
177 
178  /**
179  * Sets the @p queue to use for bound proxies.
180  **/
181  void setEventQueue(EventQueue *queue);
182  /**
183  * @returns The event queue to use for bound proxies.
184  **/
185  EventQueue *eventQueue() const;
186 
187  /**
188  * @returns The Output for the @p native wl_output. @c null if there is no Output for it.
189  * @since 5.27
190  **/
191  static Output *get(wl_output *native);
192 
193  /**
194  * Destroys the data hold by this Output.
195  * This method is supposed to be used when the connection to the Wayland
196  * server goes away. If the connection is not valid any more, it's not
197  * possible to call release any more as that calls into the Wayland
198  * connection and the call would fail.
199  *
200  * This method is automatically invoked when the Registry which created this
201  * Output gets destroyed.
202  *
203  **/
204  void destroy();
205 
206 Q_SIGNALS:
207  /**
208  * Emitted whenever at least one of the data changed.
209  **/
210  void changed();
211  /**
212  * Emitted whenever a new Mode is added.
213  * This normally only happens during the initial promoting of modes.
214  * Afterwards only modeChanged should be emitted.
215  * @param mode The newly added Mode.
216  * @see modeChanged
217  **/
218  void modeAdded(const KWayland::Client::Output::Mode &mode);
219  /**
220  * Emitted whenever a Mode changes.
221  * This normally means that the @c Mode::Flag::Current is added or removed.
222  * @param mode The changed Mode
223  **/
224  void modeChanged(const KWayland::Client::Output::Mode &mode);
225 
226  /**
227  * The corresponding global for this interface on the Registry got removed.
228  *
229  * This signal gets only emitted if the Compositor got created by
230  * Registry::createOutput
231  *
232  * @since 5.5
233  **/
234  void removed();
235 
236 private:
237  class Private;
239 };
240 
241 Q_DECLARE_OPERATORS_FOR_FLAGS(Output::Mode::Flags)
242 
243 }
244 }
245 
246 Q_DECLARE_METATYPE(KWayland::Client::Output*)
247 Q_DECLARE_METATYPE(KWayland::Client::Output::SubPixel)
248 Q_DECLARE_METATYPE(KWayland::Client::Output::Transform)
249 Q_DECLARE_METATYPE(KWayland::Client::Output::Mode)
250 
251 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:55
Wrapper for the wl_output interface.
Definition: output.h:55
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Mar 4 2021 22:51:22 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.