| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<protocol name="xdg_output_unstable_v1"> |
| 3 |
|
| 4 |
<copyright> |
| 5 |
Copyright © 2017 Red Hat Inc. |
| 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 |
<description summary="Protocol to describe output regions"> |
| 28 |
This protocol aims at describing outputs in a way which is more in line |
| 29 |
with the concept of an output on desktop oriented systems. |
| 30 |
|
| 31 |
Some information are more specific to the concept of an output for |
| 32 |
a desktop oriented system and may not make sense in other applications, |
| 33 |
such as IVI systems for example. |
| 34 |
|
| 35 |
Typically, the global compositor space on a desktop system is made of |
| 36 |
a contiguous or overlapping set of rectangular regions. |
| 37 |
|
| 38 |
The logical_position and logical_size events defined in this protocol |
| 39 |
might provide information identical to their counterparts already |
| 40 |
available from wl_output, in which case the information provided by this |
| 41 |
protocol should be preferred to their equivalent in wl_output. The goal is |
| 42 |
to move the desktop specific concepts (such as output location within the |
| 43 |
global compositor space, etc.) out of the core wl_output protocol. |
| 44 |
|
| 45 |
Warning! The protocol described in this file is experimental and |
| 46 |
backward incompatible changes may be made. Backward compatible |
| 47 |
changes may be added together with the corresponding interface |
| 48 |
version bump. |
| 49 |
Backward incompatible changes are done by bumping the version |
| 50 |
number in the protocol and interface names and resetting the |
| 51 |
interface version. Once the protocol is to be declared stable, |
| 52 |
the 'z' prefix and the version number in the protocol and |
| 53 |
interface names are removed and the interface version number is |
| 54 |
reset. |
| 55 |
</description> |
| 56 |
|
| 57 |
<interface name="zxdg_output_manager_v1" version="3"> |
| 58 |
<description summary="manage xdg_output objects"> |
| 59 |
A global factory interface for xdg_output objects. |
| 60 |
</description> |
| 61 |
|
| 62 |
<request name="destroy" type="destructor"> |
| 63 |
<description summary="destroy the xdg_output_manager object"> |
| 64 |
Using this request a client can tell the server that it is not |
| 65 |
going to use the xdg_output_manager object anymore. |
| 66 |
|
| 67 |
Any objects already created through this instance are not affected. |
| 68 |
</description> |
| 69 |
</request> |
| 70 |
|
| 71 |
<request name="get_xdg_output"> |
| 72 |
<description summary="create an xdg output from a wl_output"> |
| 73 |
This creates a new xdg_output object for the given wl_output. |
| 74 |
</description> |
| 75 |
<arg name="id" type="new_id" interface="zxdg_output_v1"/> |
| 76 |
<arg name="output" type="object" interface="wl_output"/> |
| 77 |
</request> |
| 78 |
</interface> |
| 79 |
|
| 80 |
<interface name="zxdg_output_v1" version="3"> |
| 81 |
<description summary="compositor logical output region"> |
| 82 |
An xdg_output describes part of the compositor geometry. |
| 83 |
|
| 84 |
This typically corresponds to a monitor that displays part of the |
| 85 |
compositor space. |
| 86 |
|
| 87 |
For objects version 3 onwards, after all xdg_output properties have been |
| 88 |
sent (when the object is created and when properties are updated), a |
| 89 |
wl_output.done event is sent. This allows changes to the output |
| 90 |
properties to be seen as atomic, even if they happen via multiple events. |
| 91 |
</description> |
| 92 |
|
| 93 |
<request name="destroy" type="destructor"> |
| 94 |
<description summary="destroy the xdg_output object"> |
| 95 |
Using this request a client can tell the server that it is not |
| 96 |
going to use the xdg_output object anymore. |
| 97 |
</description> |
| 98 |
</request> |
| 99 |
|
| 100 |
<event name="logical_position"> |
| 101 |
<description summary="position of the output within the global compositor space"> |
| 102 |
The position event describes the location of the wl_output within |
| 103 |
the global compositor space. |
| 104 |
|
| 105 |
The logical_position event is sent after creating an xdg_output |
| 106 |
(see xdg_output_manager.get_xdg_output) and whenever the location |
| 107 |
of the output changes within the global compositor space. |
| 108 |
</description> |
| 109 |
<arg name="x" type="int" |
| 110 |
summary="x position within the global compositor space"/> |
| 111 |
<arg name="y" type="int" |
| 112 |
summary="y position within the global compositor space"/> |
| 113 |
</event> |
| 114 |
|
| 115 |
<event name="logical_size"> |
| 116 |
<description summary="size of the output in the global compositor space"> |
| 117 |
The logical_size event describes the size of the output in the |
| 118 |
global compositor space. |
| 119 |
|
| 120 |
Most regular Wayland clients should not pay attention to the |
| 121 |
logical size and would rather rely on xdg_shell interfaces. |
| 122 |
|
| 123 |
Some clients such as Xwayland, however, need this to configure |
| 124 |
their surfaces in the global compositor space as the compositor |
| 125 |
may apply a different scale from what is advertised by the output |
| 126 |
scaling property (to achieve fractional scaling, for example). |
| 127 |
|
| 128 |
For example, for a wl_output mode 3840×2160 and a scale factor 2: |
| 129 |
|
| 130 |
- A compositor not scaling the monitor viewport in its compositing space |
| 131 |
will advertise a logical size of 3840×2160, |
| 132 |
|
| 133 |
- A compositor scaling the monitor viewport with scale factor 2 will |
| 134 |
advertise a logical size of 1920×1080, |
| 135 |
|
| 136 |
- A compositor scaling the monitor viewport using a fractional scale of |
| 137 |
1.5 will advertise a logical size of 2560×1440. |
| 138 |
|
| 139 |
For example, for a wl_output mode 1920×1080 and a 90 degree rotation, |
| 140 |
the compositor will advertise a logical size of 1080x1920. |
| 141 |
|
| 142 |
The logical_size event is sent after creating an xdg_output |
| 143 |
(see xdg_output_manager.get_xdg_output) and whenever the logical |
| 144 |
size of the output changes, either as a result of a change in the |
| 145 |
applied scale or because of a change in the corresponding output |
| 146 |
mode(see wl_output.mode) or transform (see wl_output.transform). |
| 147 |
</description> |
| 148 |
<arg name="width" type="int" |
| 149 |
summary="width in global compositor space"/> |
| 150 |
<arg name="height" type="int" |
| 151 |
summary="height in global compositor space"/> |
| 152 |
</event> |
| 153 |
|
| 154 |
<event name="done" deprecated-since="3"> |
| 155 |
<description summary="all information about the output have been sent"> |
| 156 |
This event is sent after all other properties of an xdg_output |
| 157 |
have been sent. |
| 158 |
|
| 159 |
This allows changes to the xdg_output properties to be seen as |
| 160 |
atomic, even if they happen via multiple events. |
| 161 |
|
| 162 |
For objects version 3 onwards, this event is deprecated. Compositors |
| 163 |
are not required to send it anymore and must send wl_output.done |
| 164 |
instead. |
| 165 |
</description> |
| 166 |
</event> |
| 167 |
|
| 168 |
<!-- Version 2 additions --> |
| 169 |
|
| 170 |
<event name="name" since="2"> |
| 171 |
<description summary="name of this output"> |
| 172 |
Many compositors will assign names to their outputs, show them to the |
| 173 |
user, allow them to be configured by name, etc. The client may wish to |
| 174 |
know this name as well to offer the user similar behaviors. |
| 175 |
|
| 176 |
The naming convention is compositor defined, but limited to |
| 177 |
alphanumeric characters and dashes (-). Each name is unique among all |
| 178 |
wl_output globals, but if a wl_output global is destroyed the same name |
| 179 |
may be reused later. The names will also remain consistent across |
| 180 |
sessions with the same hardware and software configuration. |
| 181 |
|
| 182 |
Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do |
| 183 |
not assume that the name is a reflection of an underlying DRM |
| 184 |
connector, X11 connection, etc. |
| 185 |
|
| 186 |
The name event is sent after creating an xdg_output (see |
| 187 |
xdg_output_manager.get_xdg_output). This event is only sent once per |
| 188 |
xdg_output, and the name does not change over the lifetime of the |
| 189 |
wl_output global. |
| 190 |
|
| 191 |
This event is deprecated, instead clients should use wl_output.name. |
| 192 |
Compositors must still support this event. |
| 193 |
</description> |
| 194 |
<arg name="name" type="string" summary="output name"/> |
| 195 |
</event> |
| 196 |
|
| 197 |
<event name="description" since="2"> |
| 198 |
<description summary="human-readable description of this output"> |
| 199 |
Many compositors can produce human-readable descriptions of their |
| 200 |
outputs. The client may wish to know this description as well, to |
| 201 |
communicate the user for various purposes. |
| 202 |
|
| 203 |
The description is a UTF-8 string with no convention defined for its |
| 204 |
contents. Examples might include 'Foocorp 11" Display' or 'Virtual X11 |
| 205 |
output via :1'. |
| 206 |
|
| 207 |
The description event is sent after creating an xdg_output (see |
| 208 |
xdg_output_manager.get_xdg_output) and whenever the description |
| 209 |
changes. The description is optional, and may not be sent at all. |
| 210 |
|
| 211 |
For objects of version 2 and lower, this event is only sent once per |
| 212 |
xdg_output, and the description does not change over the lifetime of |
| 213 |
the wl_output global. |
| 214 |
|
| 215 |
This event is deprecated, instead clients should use |
| 216 |
wl_output.description. Compositors must still support this event. |
| 217 |
</description> |
| 218 |
<arg name="description" type="string" summary="output description"/> |
| 219 |
</event> |
| 220 |
|
| 221 |
</interface> |
| 222 |
</protocol> |