wlr-output-management-unstable-v1.xml RawHistoryFolder
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="wlr_output_management_unstable_v1">
3 <copyright>
4 Copyright © 2019 Purism SPC
5
6 Permission to use, copy, modify, distribute, and sell this
7 software and its documentation for any purpose is hereby granted
8 without fee, provided that the above copyright notice appear in
9 all copies and that both that copyright notice and this permission
10 notice appear in supporting documentation, and that the name of
11 the copyright holders not be used in advertising or publicity
12 pertaining to distribution of the software without specific,
13 written prior permission. The copyright holders make no
14 representations about the suitability of this software for any
15 purpose. It is provided "as is" without express or implied
16 warranty.
17
18 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
19 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
22 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
23 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
24 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
25 THIS SOFTWARE.
26 </copyright>
27
28 <description summary="protocol to configure output devices">
29 This protocol exposes interfaces to obtain and modify output device
30 configuration.
31
32 Warning! The protocol described in this file is experimental and
33 backward incompatible changes may be made. Backward compatible changes
34 may be added together with the corresponding interface version bump.
35 Backward incompatible changes are done by bumping the version number in
36 the protocol and interface names and resetting the interface version.
37 Once the protocol is to be declared stable, the 'z' prefix and the
38 version number in the protocol and interface names are removed and the
39 interface version number is reset.
40 </description>
41
42 <interface name="zwlr_output_manager_v1" version="4">
43 <description summary="output device configuration manager">
44 This interface is a manager that allows reading and writing the current
45 output device configuration.
46
47 Output devices that display pixels (e.g. a physical monitor or a virtual
48 output in a window) are represented as heads. Heads cannot be created nor
49 destroyed by the client, but they can be enabled or disabled and their
50 properties can be changed. Each head may have one or more available modes.
51
52 Whenever a head appears (e.g. a monitor is plugged in), it will be
53 advertised via the head event. Immediately after the output manager is
54 bound, all current heads are advertised.
55
56 Whenever a head's properties change, the relevant wlr_output_head events
57 will be sent. Not all head properties will be sent: only properties that
58 have changed need to.
59
60 Whenever a head disappears (e.g. a monitor is unplugged), a
61 wlr_output_head.finished event will be sent.
62
63 After one or more heads appear, change or disappear, the done event will
64 be sent. It carries a serial which can be used in a create_configuration
65 request to update heads properties.
66
67 The information obtained from this protocol should only be used for output
68 configuration purposes. This protocol is not designed to be a generic
69 output property advertisement protocol for regular clients. Instead,
70 protocols such as xdg-output should be used.
71 </description>
72
73 <event name="head">
74 <description summary="introduce a new head">
75 This event introduces a new head. This happens whenever a new head
76 appears (e.g. a monitor is plugged in) or after the output manager is
77 bound.
78 </description>
79 <arg name="head" type="new_id" interface="zwlr_output_head_v1"/>
80 </event>
81
82 <event name="done">
83 <description summary="sent all information about current configuration">
84 This event is sent after all information has been sent after binding to
85 the output manager object and after any subsequent changes. This applies
86 to child head and mode objects as well. In other words, this event is
87 sent whenever a head or mode is created or destroyed and whenever one of
88 their properties has been changed. Not all state is re-sent each time
89 the current configuration changes: only the actual changes are sent.
90
91 This allows changes to the output configuration to be seen as atomic,
92 even if they happen via multiple events.
93
94 A serial is sent to be used in a future create_configuration request.
95 </description>
96 <arg name="serial" type="uint" summary="current configuration serial"/>
97 </event>
98
99 <request name="create_configuration">
100 <description summary="create a new output configuration object">
101 Create a new output configuration object. This allows to update head
102 properties.
103 </description>
104 <arg name="id" type="new_id" interface="zwlr_output_configuration_v1"/>
105 <arg name="serial" type="uint"/>
106 </request>
107
108 <request name="stop">
109 <description summary="stop sending events">
110 Indicates the client no longer wishes to receive events for output
111 configuration changes. However the compositor may emit further events,
112 until the finished event is emitted.
113
114 The client must not send any more requests after this one.
115 </description>
116 </request>
117
118 <event name="finished" type="destructor">
119 <description summary="the compositor has finished with the manager">
120 This event indicates that the compositor is done sending manager events.
121 The compositor will destroy the object immediately after sending this
122 event, so it will become invalid and the client should release any
123 resources associated with it.
124 </description>
125 </event>
126 </interface>
127
128 <interface name="zwlr_output_head_v1" version="4">
129 <description summary="output device">
130 A head is an output device. The difference between a wl_output object and
131 a head is that heads are advertised even if they are turned off. A head
132 object only advertises properties and cannot be used directly to change
133 them.
134
135 A head has some read-only properties: modes, name, description and
136 physical_size. These cannot be changed by clients.
137
138 Other properties can be updated via a wlr_output_configuration object.
139
140 Properties sent via this interface are applied atomically via the
141 wlr_output_manager.done event. No guarantees are made regarding the order
142 in which properties are sent.
143 </description>
144
145 <event name="name">
146 <description summary="head name">
147 This event describes the head name.
148
149 The naming convention is compositor defined, but limited to alphanumeric
150 characters and dashes (-). Each name is unique among all wlr_output_head
151 objects, but if a wlr_output_head object is destroyed the same name may
152 be reused later. The names will also remain consistent across sessions
153 with the same hardware and software configuration.
154
155 Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
156 not assume that the name is a reflection of an underlying DRM
157 connector, X11 connection, etc.
158
159 If this head matches a wl_output, the wl_output.name event must report
160 the same name.
161
162 The name event is sent after a wlr_output_head object is created. This
163 event is only sent once per object, and the name does not change over
164 the lifetime of the wlr_output_head object.
165 </description>
166 <arg name="name" type="string"/>
167 </event>
168
169 <event name="description">
170 <description summary="head description">
171 This event describes a human-readable description of the head.
172
173 The description is a UTF-8 string with no convention defined for its
174 contents. Examples might include 'Foocorp 11" Display' or 'Virtual X11
175 output via :1'. However, do not assume that the name is a reflection of
176 the make, model, serial of the underlying DRM connector or the display
177 name of the underlying X11 connection, etc.
178
179 If this head matches a wl_output, the wl_output.description event must
180 report the same name.
181
182 The description event is sent after a wlr_output_head object is created.
183 This event is only sent once per object, and the description does not
184 change over the lifetime of the wlr_output_head object.
185 </description>
186 <arg name="description" type="string"/>
187 </event>
188
189 <event name="physical_size">
190 <description summary="head physical size">
191 This event describes the physical size of the head. This event is only
192 sent if the head has a physical size (e.g. is not a projector or a
193 virtual device).
194
195 The physical size event is sent after a wlr_output_head object is created. This
196 event is only sent once per object, and the physical size does not change over
197 the lifetime of the wlr_output_head object.
198 </description>
199 <arg name="width" type="int" summary="width in millimeters of the output"/>
200 <arg name="height" type="int" summary="height in millimeters of the output"/>
201 </event>
202
203 <event name="mode">
204 <description summary="introduce a mode">
205 This event introduces a mode for this head. It is sent once per
206 supported mode.
207 </description>
208 <arg name="mode" type="new_id" interface="zwlr_output_mode_v1"/>
209 </event>
210
211 <event name="enabled">
212 <description summary="head is enabled or disabled">
213 This event describes whether the head is enabled. A disabled head is not
214 mapped to a region of the global compositor space.
215
216 When a head is disabled, some properties (current_mode, position,
217 transform and scale) are irrelevant.
218 </description>
219 <arg name="enabled" type="int" summary="zero if disabled, non-zero if enabled"/>
220 </event>
221
222 <event name="current_mode">
223 <description summary="current mode">
224 This event describes the mode currently in use for this head. It is only
225 sent if the output is enabled.
226 </description>
227 <arg name="mode" type="object" interface="zwlr_output_mode_v1"/>
228 </event>
229
230 <event name="position">
231 <description summary="current position">
232 This events describes the position of the head in the global compositor
233 space. It is only sent if the output is enabled.
234 </description>
235 <arg name="x" type="int"
236 summary="x position within the global compositor space"/>
237 <arg name="y" type="int"
238 summary="y position within the global compositor space"/>
239 </event>
240
241 <event name="transform">
242 <description summary="current transformation">
243 This event describes the transformation currently applied to the head.
244 It is only sent if the output is enabled.
245 </description>
246 <arg name="transform" type="int" enum="wl_output.transform"/>
247 </event>
248
249 <event name="scale">
250 <description summary="current scale">
251 This events describes the scale of the head in the global compositor
252 space. It is only sent if the output is enabled.
253 </description>
254 <arg name="scale" type="fixed"/>
255 </event>
256
257 <event name="finished">
258 <description summary="the head has disappeared">
259 This event indicates that the head is no longer available. The head
260 object becomes inert. Clients should send a destroy request and release
261 any resources associated with it.
262 </description>
263 </event>
264
265 <!-- Version 2 additions -->
266
267 <event name="make" since="2">
268 <description summary="head manufacturer">
269 This event describes the manufacturer of the head.
270
271 Together with the model and serial_number events the purpose is to
272 allow clients to recognize heads from previous sessions and for example
273 load head-specific configurations back.
274
275 It is not guaranteed this event will be ever sent. A reason for that
276 can be that the compositor does not have information about the make of
277 the head or the definition of a make is not sensible in the current
278 setup, for example in a virtual session. Clients can still try to
279 identify the head by available information from other events but should
280 be aware that there is an increased risk of false positives.
281
282 If sent, the make event is sent after a wlr_output_head object is
283 created and only sent once per object. The make does not change over
284 the lifetime of the wlr_output_head object.
285
286 It is not recommended to display the make string in UI to users. For
287 that the string provided by the description event should be preferred.
288 </description>
289 <arg name="make" type="string"/>
290 </event>
291
292 <event name="model" since="2">
293 <description summary="head model">
294 This event describes the model of the head.
295
296 Together with the make and serial_number events the purpose is to
297 allow clients to recognize heads from previous sessions and for example
298 load head-specific configurations back.
299
300 It is not guaranteed this event will be ever sent. A reason for that
301 can be that the compositor does not have information about the model of
302 the head or the definition of a model is not sensible in the current
303 setup, for example in a virtual session. Clients can still try to
304 identify the head by available information from other events but should
305 be aware that there is an increased risk of false positives.
306
307 If sent, the model event is sent after a wlr_output_head object is
308 created and only sent once per object. The model does not change over
309 the lifetime of the wlr_output_head object.
310
311 It is not recommended to display the model string in UI to users. For
312 that the string provided by the description event should be preferred.
313 </description>
314 <arg name="model" type="string"/>
315 </event>
316
317 <event name="serial_number" since="2">
318 <description summary="head serial number">
319 This event describes the serial number of the head.
320
321 Together with the make and model events the purpose is to allow clients
322 to recognize heads from previous sessions and for example load head-
323 specific configurations back.
324
325 It is not guaranteed this event will be ever sent. A reason for that
326 can be that the compositor does not have information about the serial
327 number of the head or the definition of a serial number is not sensible
328 in the current setup. Clients can still try to identify the head by
329 available information from other events but should be aware that there
330 is an increased risk of false positives.
331
332 If sent, the serial number event is sent after a wlr_output_head object
333 is created and only sent once per object. The serial number does not
334 change over the lifetime of the wlr_output_head object.
335
336 It is not recommended to display the serial_number string in UI to
337 users. For that the string provided by the description event should be
338 preferred.
339 </description>
340 <arg name="serial_number" type="string"/>
341 </event>
342
343 <!-- Version 3 additions -->
344
345 <request name="release" type="destructor" since="3">
346 <description summary="destroy the head object">
347 This request indicates that the client will no longer use this head
348 object.
349 </description>
350 </request>
351
352 <!-- Version 4 additions -->
353
354 <enum name="adaptive_sync_state" since="4">
355 <entry name="disabled" value="0" summary="adaptive sync is disabled"/>
356 <entry name="enabled" value="1" summary="adaptive sync is enabled"/>
357 </enum>
358
359 <event name="adaptive_sync" since="4">
360 <description summary="current adaptive sync state">
361 This event describes whether adaptive sync is currently enabled for
362 the head or not. Adaptive sync is also known as Variable Refresh
363 Rate or VRR.
364 </description>
365 <arg name="state" type="uint" enum="adaptive_sync_state"/>
366 </event>
367 </interface>
368
369 <interface name="zwlr_output_mode_v1" version="3">
370 <description summary="output mode">
371 This object describes an output mode.
372
373 Some heads don't support output modes, in which case modes won't be
374 advertised.
375
376 Properties sent via this interface are applied atomically via the
377 wlr_output_manager.done event. No guarantees are made regarding the order
378 in which properties are sent.
379 </description>
380
381 <event name="size">
382 <description summary="mode size">
383 This event describes the mode size. The size is given in physical
384 hardware units of the output device. This is not necessarily the same as
385 the output size in the global compositor space. For instance, the output
386 may be scaled or transformed.
387 </description>
388 <arg name="width" type="int" summary="width of the mode in hardware units"/>
389 <arg name="height" type="int" summary="height of the mode in hardware units"/>
390 </event>
391
392 <event name="refresh">
393 <description summary="mode refresh rate">
394 This event describes the mode's fixed vertical refresh rate. It is only
395 sent if the mode has a fixed refresh rate.
396 </description>
397 <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
398 </event>
399
400 <event name="preferred">
401 <description summary="mode is preferred">
402 This event advertises this mode as preferred.
403 </description>
404 </event>
405
406 <event name="finished">
407 <description summary="the mode has disappeared">
408 This event indicates that the mode is no longer available. The mode
409 object becomes inert. Clients should send a destroy request and release
410 any resources associated with it.
411 </description>
412 </event>
413
414 <!-- Version 3 additions -->
415
416 <request name="release" type="destructor" since="3">
417 <description summary="destroy the mode object">
418 This request indicates that the client will no longer use this mode
419 object.
420 </description>
421 </request>
422 </interface>
423
424 <interface name="zwlr_output_configuration_v1" version="4">
425 <description summary="output configuration">
426 This object is used by the client to describe a full output configuration.
427
428 First, the client needs to setup the output configuration. Each head can
429 be either enabled (and configured) or disabled. It is a protocol error to
430 send two enable_head or disable_head requests with the same head. It is a
431 protocol error to omit a head in a configuration.
432
433 Then, the client can apply or test the configuration. The compositor will
434 then reply with a succeeded, failed or cancelled event. Finally the client
435 should destroy the configuration object.
436 </description>
437
438 <enum name="error">
439 <entry name="already_configured_head" value="1"
440 summary="head has been configured twice"/>
441 <entry name="unconfigured_head" value="2"
442 summary="head has not been configured"/>
443 <entry name="already_used" value="3"
444 summary="request sent after configuration has been applied or tested"/>
445 </enum>
446
447 <request name="enable_head">
448 <description summary="enable and configure a head">
449 Enable a head. This request creates a head configuration object that can
450 be used to change the head's properties.
451 </description>
452 <arg name="id" type="new_id" interface="zwlr_output_configuration_head_v1"
453 summary="a new object to configure the head"/>
454 <arg name="head" type="object" interface="zwlr_output_head_v1"
455 summary="the head to be enabled"/>
456 </request>
457
458 <request name="disable_head">
459 <description summary="disable a head">
460 Disable a head.
461 </description>
462 <arg name="head" type="object" interface="zwlr_output_head_v1"
463 summary="the head to be disabled"/>
464 </request>
465
466 <request name="apply">
467 <description summary="apply the configuration">
468 Apply the new output configuration.
469
470 In case the configuration is successfully applied, there is no guarantee
471 that the new output state matches completely the requested
472 configuration. For instance, a compositor might round the scale if it
473 doesn't support fractional scaling.
474
475 After this request has been sent, the compositor must respond with an
476 succeeded, failed or cancelled event. Sending a request that isn't the
477 destructor is a protocol error.
478 </description>
479 </request>
480
481 <request name="test">
482 <description summary="test the configuration">
483 Test the new output configuration. The configuration won't be applied,
484 but will only be validated.
485
486 Even if the compositor succeeds to test a configuration, applying it may
487 fail.
488
489 After this request has been sent, the compositor must respond with an
490 succeeded, failed or cancelled event. Sending a request that isn't the
491 destructor is a protocol error.
492 </description>
493 </request>
494
495 <event name="succeeded">
496 <description summary="configuration changes succeeded">
497 Sent after the compositor has successfully applied the changes or
498 tested them.
499
500 Upon receiving this event, the client should destroy this object.
501
502 If the current configuration has changed, events to describe the changes
503 will be sent followed by a wlr_output_manager.done event.
504 </description>
505 </event>
506
507 <event name="failed">
508 <description summary="configuration changes failed">
509 Sent if the compositor rejects the changes or failed to apply them. The
510 compositor should revert any changes made by the apply request that
511 triggered this event.
512
513 Upon receiving this event, the client should destroy this object.
514 </description>
515 </event>
516
517 <event name="cancelled">
518 <description summary="configuration has been cancelled">
519 Sent if the compositor cancels the configuration because the state of an
520 output changed and the client has outdated information (e.g. after an
521 output has been hotplugged).
522
523 The client can create a new configuration with a newer serial and try
524 again.
525
526 Upon receiving this event, the client should destroy this object.
527 </description>
528 </event>
529
530 <request name="destroy" type="destructor">
531 <description summary="destroy the output configuration">
532 Using this request a client can tell the compositor that it is not going
533 to use the configuration object anymore. Any changes to the outputs
534 that have not been applied will be discarded.
535
536 This request also destroys wlr_output_configuration_head objects created
537 via this object.
538 </description>
539 </request>
540 </interface>
541
542 <interface name="zwlr_output_configuration_head_v1" version="4">
543 <description summary="head configuration">
544 This object is used by the client to update a single head's configuration.
545
546 It is a protocol error to set the same property twice.
547 </description>
548
549 <enum name="error">
550 <entry name="already_set" value="1" summary="property has already been set"/>
551 <entry name="invalid_mode" value="2" summary="mode doesn't belong to head"/>
552 <entry name="invalid_custom_mode" value="3" summary="mode is invalid"/>
553 <entry name="invalid_transform" value="4" summary="transform value outside enum"/>
554 <entry name="invalid_scale" value="5" summary="scale negative or zero"/>
555 <entry name="invalid_adaptive_sync_state" value="6" since="4"
556 summary="invalid enum value used in the set_adaptive_sync request"/>
557 </enum>
558
559 <request name="set_mode">
560 <description summary="set the mode">
561 This request sets the head's mode.
562 </description>
563 <arg name="mode" type="object" interface="zwlr_output_mode_v1"/>
564 </request>
565
566 <request name="set_custom_mode">
567 <description summary="set a custom mode">
568 This request assigns a custom mode to the head. The size is given in
569 physical hardware units of the output device. If set to zero, the
570 refresh rate is unspecified.
571
572 It is a protocol error to set both a mode and a custom mode.
573 </description>
574 <arg name="width" type="int" summary="width of the mode in hardware units"/>
575 <arg name="height" type="int" summary="height of the mode in hardware units"/>
576 <arg name="refresh" type="int" summary="vertical refresh rate in mHz or zero"/>
577 </request>
578
579 <request name="set_position">
580 <description summary="set the position">
581 This request sets the head's position in the global compositor space.
582 </description>
583 <arg name="x" type="int" summary="x position in the global compositor space"/>
584 <arg name="y" type="int" summary="y position in the global compositor space"/>
585 </request>
586
587 <request name="set_transform">
588 <description summary="set the transform">
589 This request sets the head's transform.
590 </description>
591 <arg name="transform" type="int" enum="wl_output.transform"/>
592 </request>
593
594 <request name="set_scale">
595 <description summary="set the scale">
596 This request sets the head's scale.
597 </description>
598 <arg name="scale" type="fixed"/>
599 </request>
600
601 <!-- Version 4 additions -->
602
603 <request name="set_adaptive_sync" since="4">
604 <description summary="enable/disable adaptive sync">
605 This request enables/disables adaptive sync. Adaptive sync is also
606 known as Variable Refresh Rate or VRR.
607 </description>
608 <arg name="state" type="uint" enum="zwlr_output_head_v1.adaptive_sync_state"/>
609 </request>
610 </interface>
611</protocol>