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  ~Output() override;
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  * Returns the name of the output.
179  **/
180  QString name() const;
181 
182  /**
183  * Returns the human readable description of the output.
184  **/
185  QString description() const;
186 
187  /**
188  * Sets the @p queue to use for bound proxies.
189  **/
190  void setEventQueue(EventQueue *queue);
191  /**
192  * @returns The event queue to use for bound proxies.
193  **/
194  EventQueue *eventQueue() const;
195 
196  /**
197  * @returns The Output for the @p native wl_output. @c null if there is no Output for it.
198  * @since 5.27
199  **/
200  static Output *get(wl_output *native);
201 
202  /**
203  * Destroys the data hold by this Output.
204  * This method is supposed to be used when the connection to the Wayland
205  * server goes away. If the connection is not valid any more, it's not
206  * possible to call release any more as that calls into the Wayland
207  * connection and the call would fail.
208  *
209  * This method is automatically invoked when the Registry which created this
210  * Output gets destroyed.
211  *
212  **/
213  void destroy();
214 
215 Q_SIGNALS:
216  /**
217  * Emitted whenever at least one of the data changed.
218  **/
219  void changed();
220  /**
221  * Emitted whenever a new Mode is added.
222  * This normally only happens during the initial promoting of modes.
223  * Afterwards only modeChanged should be emitted.
224  * @param mode The newly added Mode.
225  * @see modeChanged
226  **/
227  void modeAdded(const KWayland::Client::Output::Mode &mode);
228  /**
229  * Emitted whenever a Mode changes.
230  * This normally means that the @c Mode::Flag::Current is added or removed.
231  * @param mode The changed Mode
232  **/
233  void modeChanged(const KWayland::Client::Output::Mode &mode);
234 
235  /**
236  * The corresponding global for this interface on the Registry got removed.
237  *
238  * This signal gets only emitted if the Compositor got created by
239  * Registry::createOutput
240  *
241  * @since 5.5
242  **/
243  void removed();
244 
245 private:
246  class Private;
248 };
249 
250 Q_DECLARE_OPERATORS_FOR_FLAGS(Output::Mode::Flags)
251 
252 }
253 }
254 
255 Q_DECLARE_METATYPE(KWayland::Client::Output *)
256 Q_DECLARE_METATYPE(KWayland::Client::Output::SubPixel)
257 Q_DECLARE_METATYPE(KWayland::Client::Output::Transform)
258 Q_DECLARE_METATYPE(KWayland::Client::Output::Mode)
259 
260 #endif
Wrapper for the wl_output interface.
Definition: output.h:54
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
virtual QVariant get(ScriptableExtension *callerPrincipal, quint64 objId, const QString &propName)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jan 27 2023 07:38:08 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.