1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="aura_output_management">
3
4  <copyright>
5    Copyright 2024 The Chromium Authors
6
7    Permission is hereby granted, free of charge, to any person obtaining a
8    copy of this software and associated documentation files (the "Software"),
9    to deal in the Software without restriction, including without limitation
10    the rights to use, copy, modify, merge, publish, distribute, sublicense,
11    and/or sell copies of the Software, and to permit persons to whom the
12    Software is furnished to do so, subject to the following conditions:
13
14    The above copyright notice and this permission notice (including the next
15    paragraph) shall be included in all copies or substantial portions of the
16    Software.
17
18    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
21    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24    DEALINGS IN THE SOFTWARE.
25  </copyright>
26
27  <interface name="zaura_output_manager_v2" version="1">
28    <description summary="aura output manager singleton">
29      A global responsible for propagating atomic output configuration changes
30      to clients. An output configuration is a union of added / removed outputs
31      and updated output metrics.
32
33      Added outputs arrive at the client as wl_registry.global events, removed
34      outputs as wl_registry.global_remove events and updated output metrics as
35      a sequence of events defined on the zaura_output_manager_v2 interface.
36      This is followed by the manager's done event which signals the end of the
37      transaction.
38
39      The change should be processed by clients in a way that transitions from
40      one output configuration state to another without exposing the
41      intermediate output state to the rest of the application.
42
43      Participating servers should emit the zaura_output_manager_v2 global
44      before any wl_output globals in the sequence of wl_registry.global events.
45
46      Participating clients should bind the zaura_output_manager_v2 before any
47      wl_output globals. This ordering is required to ensure clients receive all
48      necessary output configuration information before receiving any further
49      server events that may reference bound wl_outputs.
50
51      Clients can expect that all events comprising a configuration change are
52      sent synchronously, one after the other, before any other server events
53      that leverage the output as an event param.
54    </description>
55
56    <event name="done" since="1">
57      <description
58          summary="sent all information about the output configuration change">
59        This event is sent after all added, changed and removed output events
60        for a given wl_output have been dispatched to the client.
61      </description>
62    </event>
63
64    <event name="display_id" since="1">
65      <description summary="advertise the output's display id">
66        This event describes the 64bit display id assigned to each display by
67        ChromeOS. The value is opaque and should not be interpreted.
68
69        The event is sent immediately after the wl_registry.global event for the
70        output and subsequently in latter display configuration changes.
71      </description>
72      <arg name="output_name" type="uint" />
73      <arg name="display_id_hi" type="uint" />
74      <arg name="display_id_lo" type="uint" />
75    </event>
76
77    <event name="logical_position" since="1">
78      <description
79          summary="position of the output within the global compositor space">
80        The position event describes the location of the wl_output within the
81        global compositor space.
82
83        The event is sent immediately after the wl_registry.global event for the
84        output and subsequently in latter display configuration changes.
85      </description>
86      <arg name="output_name" type="uint" />
87      <arg name="x" type="int"
88          summary="x position within the global compositor space" />
89      <arg name="y" type="int"
90          summary="y position within the global compositor space" />
91    </event>
92
93    <event name="logical_size" since="1">
94      <description summary="size of the output in the global compositor space">
95        The logical_size event describes the logical size of the output in the
96        global compositor space.
97
98        The event is sent immediately after the wl_registry.global event for the
99        output and subsequently in latter display configuration changes.
100      </description>
101      <arg name="output_name" type="uint" />
102      <arg name="width" type="int" summary="width in global compositor space" />
103      <arg name="height" type="int"
104          summary="height in global compositor space" />
105    </event>
106
107    <event name="physical_size" since="1">
108      <description summary="size of the output in pixels">
109        The physical resolution of the display in pixels. The value should not
110        include any overscan insets or display rotation, except for any panel
111        orientation adjustment.
112
113        The event is sent immediately after the wl_registry.global event for the
114        output and subsequently in latter display configuration changes.
115      </description>
116      <arg name="output_name" type="uint" />
117      <arg name="width" type="int"
118          summary="width in global compositor space" />
119      <arg name="height" type="int"
120          summary="height in global compositor space" />
121    </event>
122
123    <event name="work_area_insets" since="1">
124      <description summary="advertise the work area insets for the output">
125        This event describes the work area insets for the output in logical
126        screen coordinates, from which the work area can be calculated.
127
128        The event is sent when binding to the output object and subsequently as
129        output state changes.
130      </description>
131      <arg name="output_name" type="uint" />
132      <arg name="top" type="int" />
133      <arg name="left" type="int" />
134      <arg name="bottom" type="int" />
135      <arg name="right" type="int" />
136    </event>
137
138    <event name="device_scale_factor" since="1">
139      <description summary="advertise device scale factor for the output">
140        The scale factor of the output device. We reinterpret_cast the float
141        scale factor into a 32-bit uint and later cast back into a float. This
142        is because wayland does not support native transport of floats. As
143        different CPU architectures may use different endian representations for
144        IEEE 754 floats, this protocol implicitly assumes that the caller and
145        receiver are the same machine.
146
147        The event is sent immediately after the wl_registry.global event for the
148        output and subsequently in latter display configuration changes.
149      </description>
150      <arg name="output_name" type="uint" />
151      <arg name="device_scale_factor" type="uint"
152          summary="display scale factor, in float format" />
153    </event>
154
155    <event name="logical_transform" since="1">
156      <description summary="logical transform of the output">
157        This event describes the logical transform for the output. Whereas
158        panel transform corresponds to the display's panel rotation, the logical
159        transform corresponds to the display's logical rotation.
160
161        The event is sent immediately after the wl_registry.global event for the
162        output and subsequently in latter display configuration changes.
163      </description>
164      <arg name="output_name" type="uint" />
165      <arg name="transform" type="int" enum="wl_output.transform"
166        summary="transform that maps framebuffer to output" />
167    </event>
168
169    <event name="panel_transform" since="1">
170      <description summary="panel transform of the output">
171        This event describes the panel transform for the output, which is the
172        associated display's panel rotation.
173
174        The event is sent immediately after the wl_registry.global event for the
175        output and subsequently in latter display configuration changes.
176      </description>
177      <arg name="output_name" type="uint" />
178      <arg name="transform" type="int" enum="wl_output.transform"
179        summary="transform that maps framebuffer to output" />
180    </event>
181
182    <event name="name" since="1">
183      <description summary="human-readable name of this output">
184        The name is a UTF-8 string with no convention defined for its contents.
185
186        The event is sent immediately after the wl_registry.global event for the
187        output and subsequently in latter display configuration changes.
188      </description>
189      <arg name="output_name" type="uint" />
190      <arg name="name" type="string" summary="output name" />
191    </event>
192
193    <event name="description" since="1">
194      <description summary="human-readable description of this output">
195        The description is a UTF-8 string with no convention defined for its
196        contents.
197
198        The event is sent immediately after the wl_registry.global event for the
199        output and subsequently in latter display configuration changes.
200      </description>
201      <arg name="output_name" type="uint" />
202      <arg name="description" type="string" summary="output description" />
203    </event>
204
205    <event name="overscan_insets" since="1">
206      <description summary="advertise the overscan insets for the output">
207        This event describes the overscan insets for the output in physical
208        pixels.
209
210        The event is sent immediately after the wl_registry.global event for the
211        output and subsequently in latter display configuration changes.
212      </description>
213      <arg name="output_name" type="uint" />
214      <arg name="top" type="int" />
215      <arg name="left" type="int" />
216      <arg name="bottom" type="int" />
217      <arg name="right" type="int" />
218    </event>
219
220    <event name="activated" since="1">
221      <description summary="target display for new windows">
222        Notifies that this output is now active output. It is typically used as
223        a target when a new window is created without specific bounds.
224      </description>
225      <arg name="output_name" type="uint" />
226    </event>
227  </interface>
228</protocol>
229