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

KDE's Doxygen guidelines are available online.