KWayland

outputconfiguration.h
1 /*
2  SPDX-FileCopyrightText: 2015 Sebastian K├╝gler <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 #ifndef KWAYLAND_CLIENT_OUTPUTCONFIGURATION_H
7 #define KWAYLAND_CLIENT_OUTPUTCONFIGURATION_H
8 
9 #include <QObject>
10 #include <QPoint>
11 #include <QVector>
12 
13 #include "outputdevice.h"
14 #include <KWayland/Client/kwaylandclient_export.h>
15 
16 struct org_kde_kwin_outputmanagement;
17 struct org_kde_kwin_outputconfiguration;
18 
19 namespace KWayland
20 {
21 namespace Client
22 {
23 class EventQueue;
24 
25 /** @class OutputConfiguration
26  *
27  * OutputConfiguration provides access to changing OutputDevices. The interface is async
28  * and atomic. An OutputConfiguration is created through OutputManagement::createConfiguration().
29  *
30  * The overall mechanism is to get a new OutputConfiguration from the OutputManagement global and
31  * apply changes through the OutputConfiguration::set* calls. When all changes are set, the client
32  * calls apply, which asks the server to look at the changes and apply them. The server will then
33  * signal back whether the changes have been applied successfully (@c applied()) or were rejected
34  * or failed to apply (@c failed()).
35  *
36  * The current settings for outputdevices can be gotten from @c Registry::outputDevices(), these
37  * are used in the set* calls to identify the output the setting applies to.
38  *
39  * These KWayland classes will not apply changes to the OutputDevices, this is the compositor's
40  * task. As such, the configuration set through this interface can be seen as a hint what the
41  * compositor should set up, but whether or not the compositor does it (based on hardware or
42  * rendering policies, for example), is up to the compositor. The mode setting is passed on to
43  * the DRM subsystem through the compositor. The compositor also saves this configuration and reads
44  * it on startup, this interface is not involved in that process.
45  *
46  * @c apply() should only be called after changes to all output devices have been made, not after
47  * each change. This allows to test the new configuration as a whole, and is a lot faster since
48  * hardware changes can be tested in their new combination, they done in parallel.and rolled back
49  * as a whole.
50  *
51  * \verbatim
52  // We're just picking the first of our outputdevices
53  KWayland::Client::OutputDevice *output = m_clientOutputs.first();
54 
55  // Create a new configuration object
56  auto config = m_outputManagement.createConfiguration();
57 
58  // handle applied and failed signals
59  connect(config, &OutputConfiguration::applied, []() {
60  qDebug() << "Configuration applied!";
61  });
62  connect(config, &OutputConfiguration::failed, []() {
63  qDebug() << "Configuration failed!";
64  });
65 
66  // Change settings
67  config->setMode(output, m_clientOutputs.first()->modes().last().id);
68  config->setTransform(output, OutputDevice::Transform::Normal);
69  config->setPosition(output, QPoint(0, 1920));
70  config->setScale(output, 2);
71 
72  // Now ask the compositor to apply the changes
73  config->apply();
74  // You may wait for the applied() or failed() signal here
75  \endverbatim
76 
77  * @see OutputDevice
78  * @see OutputManagement
79  * @see OutputManagement::createConfiguration()
80  * @since 5.5
81  */
82 class KWAYLANDCLIENT_EXPORT OutputConfiguration : public QObject
83 {
84  Q_OBJECT
85 public:
86  virtual ~OutputConfiguration();
87 
88  /**
89  * Setup this OutputConfiguration to manage the @p outputconfiguration.
90  * When using OutputManagement::createOutputConfiguration there is no need to call this
91  * method.
92  * @param outputconfiguration the outputconfiguration object to set up.
93  **/
94  void setup(org_kde_kwin_outputconfiguration *outputconfiguration);
95  /**
96  * @returns @c true if managing a org_kde_kwin_outputconfiguration.
97  **/
98  bool isValid() const;
99  /**
100  * Releases the org_kde_kwin_outputconfiguration interface.
101  * After the interface has been released the OutputConfiguration instance is no
102  * longer valid and can be setup with another org_kde_kwin_outputconfiguration interface.
103  **/
104  void release();
105  /**
106  * Destroys the data held by this OutputConfiguration.
107  * This method is supposed to be used when the connection to the Wayland
108  * server goes away. If the connection is not valid any more, it's not
109  * possible to call release any more as that calls into the Wayland
110  * connection and the call would fail. This method cleans up the data, so
111  * that the instance can be deleted or setup to a new org_kde_kwin_outputconfiguration interface
112  * once there is a new connection available.
113  *
114  * This method is automatically invoked when the Registry which created this
115  * OutputConfiguration gets destroyed.
116  *
117  *
118  * @see release
119  **/
120  void destroy();
121  /**
122  * Sets the @p queue to use for creating a OutputConfiguration.
123  **/
124  void setEventQueue(EventQueue *queue);
125  /**
126  * @returns The event queue to use for creating a OutputConfiguration
127  **/
128  EventQueue *eventQueue();
129 
130  /**
131  * Enable or disable an output. Enabled means it's used by the
132  * compositor for rendering, Disabled means, that no wl_output
133  * is connected to this, and the device is sitting there unused
134  * by this compositor.
135  * The changes done in this call will be recorded in the
136  * OutputDevice and only applied after apply() has been called.
137  *
138  * @param outputdevice the OutputDevice this change applies to.
139  * @param enable new Enablement state of this output device.
140  */
141  void setEnabled(OutputDevice *outputdevice, OutputDevice::Enablement enable);
142 
143  /**
144  * Set the mode of this output, identified by its mode id.
145  * The changes done in this call will be recorded in the
146  * OutputDevice and only applied after apply() has been called.
147  *
148  * @param outputdevice the OutputDevice this change applies to.
149  * @param modeId the id of the mode.
150  */
151  void setMode(OutputDevice *outputdevice, const int modeId);
152  /**
153  * Set transformation for this output, for example rotated or flipped.
154  * The changes done in this call will be recorded in the
155  * OutputDevice and only applied after apply() has been called.
156  *
157  * @param outputdevice the OutputDevice this change applies to.
158  * @param scale the scaling factor for this output device.
159  */
160  void setTransform(OutputDevice *outputdevice, KWayland::Client::OutputDevice::Transform transform);
161 
162  /**
163  * Position this output in the global space, relative to other outputs.
164  * QPoint(0, 0) for top-left. The position is the top-left corner of this output.
165  * There may not be gaps between outputs, they have to be positioned adjacent to
166  * each other.
167  * The changes done in this call will be recorded in the
168  * OutputDevice and only applied after apply() has been called.
169  *
170  * @param outputdevice the OutputDevice this change applies to.
171  * @param pos the OutputDevice global position relative to other outputs,
172  *
173  */
174  void setPosition(OutputDevice *outputdevice, const QPoint &pos);
175 
176 #if KWAYLANDCLIENT_ENABLE_DEPRECATED_SINCE(5, 50)
177  /**
178  * Scale rendering of this output.
179  * The changes done in this call will be recorded in the
180  * OutputDevice and only applied after apply() has been called.
181  *
182  * @param scale the scaling factor for this output device.
183  * @param outputdevice the OutputDevice this change applies to.
184  * @deprecated Since 5.50, use setScaleF(OutputDevice *, qreal)
185  */
186  KWAYLANDCLIENT_DEPRECATED_VERSION(5, 50, "Use OutputConfiguration::setScaleF(OutputDevice *, qreal)")
187  void setScale(OutputDevice *outputdevice, qint32 scale);
188 #endif
189 
190  /**
191  * Scale rendering of this output.
192  * The changes done in this call will be recorded in the
193  * OutputDevice and only applied after apply() has been called.
194  *
195  * @param scale the scaling factor for this output device.
196  * @param outputdevice the OutputDevice this change applies to.
197  * @since 5.50
198  */
199  void setScaleF(OutputDevice *outputdevice, qreal scale);
200 
201  /* Set color curves for this output. The respective color curve vector
202  * lengths must equal the current ones in the OutputDevice. The codomain
203  * of the curves is always the full uint16 value range, such that any vector
204  * is accepted as long as it has the right size.
205  * The changes done in this call will be recorded in the
206  * OutputDevice and only applied after apply() has been called.
207  *
208  * @param red color curve of red channel.
209  * @param green color curve of green channel.
210  * @param blue color curve of blue channel.
211  * @param outputdevice the OutputDevice this change applies to.
212  * @since 5.50
213  */
214  void setColorCurves(OutputDevice *outputdevice, QVector<quint16> red, QVector<quint16> green, QVector<quint16> blue);
215 
216  /**
217  * Set overscan in % for this output.
218  *
219  * @since 5.82
220  */
221  void setOverscan(OutputDevice *outputdevice, uint32_t overscan);
222 
223  /**
224  * Set the VRR policy for this output
225  *
226  * @since 5.82
227  */
228  void setVrrPolicy(OutputDevice *outputdevice, OutputDevice::VrrPolicy policy);
229 
230  /**
231  * Ask the compositor to apply the changes.
232  * This results in the compositor looking at all outputdevices and if they have
233  * pending changes from the set* calls, these changes will be tested with the
234  * hardware and applied if possible. The compositor will react to these changes
235  * with the applied() or failed() signals. Note that mode setting may take a
236  * while, so the interval between calling apply() and receiving the applied()
237  * signal may be considerable, depending on the hardware.
238  *
239  * @see applied()
240  * @see failed()
241  */
242  void apply();
243 
244  operator org_kde_kwin_outputconfiguration *();
245  operator org_kde_kwin_outputconfiguration *() const;
246 
247 Q_SIGNALS:
248  /**
249  * The server has applied all settings successfully. Pending changes in the
250  * OutputDevices have been cleared, changed signals from the OutputDevice have
251  * been emitted.
252  */
253  void applied();
254  /**
255  * The server has failed to apply the settings or rejected them. Pending changes
256  * in the * OutputDevices have been cleared. No changes have been applied to the
257  * OutputDevices.
258  */
259  void failed();
260 
261 private:
262  friend class OutputManagement;
263  explicit OutputConfiguration(QObject *parent = nullptr);
264  class Private;
266 };
267 
268 }
269 }
270 
271 Q_DECLARE_METATYPE(KWayland::Client::OutputConfiguration *)
272 
273 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
OutputConfiguration provides access to changing OutputDevices.
Wrapper for the org_kde_kwin_outputmanagement interface.
Wrapper for the org_kde_kwin_outputdevice interface.
Definition: outputdevice.h:57
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Sep 25 2021 22:51:29 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.