1/*
2 SPDX-FileCopyrightText: 2013 Martin Gräßlin <mgraesslin@kde.org>
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
15struct wl_output;
16class QPoint;
17class QRect;
18
19namespace KWayland
20{
21namespace Client
22{
23class 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 **/
54class KWAYLANDCLIENT_EXPORT Output : public QObject
55{
56 Q_OBJECT
57public:
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
215Q_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
245private:
246 class Private;
247 QScopedPointer<Private> d;
248};
249
250Q_DECLARE_OPERATORS_FOR_FLAGS(Output::Mode::Flags)
251
252}
253}
254
255Q_DECLARE_METATYPE(KWayland::Client::Output *)
256Q_DECLARE_METATYPE(KWayland::Client::Output::SubPixel)
257Q_DECLARE_METATYPE(KWayland::Client::Output::Transform)
258Q_DECLARE_METATYPE(KWayland::Client::Output::Mode)
259
260#endif
261

source code of kwayland/src/client/output.h