| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<protocol name="fullscreen_shell_unstable_v1"> |
| 3 |
|
| 4 |
<copyright> |
| 5 |
Copyright © 2016 Yong Bakos |
| 6 |
Copyright © 2015 Jason Ekstrand |
| 7 |
Copyright © 2015 Jonas Ådahl |
| 8 |
|
| 9 |
Permission is hereby granted, free of charge, to any person obtaining a |
| 10 |
copy of this software and associated documentation files (the "Software"), |
| 11 |
to deal in the Software without restriction, including without limitation |
| 12 |
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
| 13 |
and/or sell copies of the Software, and to permit persons to whom the |
| 14 |
Software is furnished to do so, subject to the following conditions: |
| 15 |
|
| 16 |
The above copyright notice and this permission notice (including the next |
| 17 |
paragraph) shall be included in all copies or substantial portions of the |
| 18 |
Software. |
| 19 |
|
| 20 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 21 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 22 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
| 23 |
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 24 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| 25 |
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 26 |
DEALINGS IN THE SOFTWARE. |
| 27 |
</copyright> |
| 28 |
|
| 29 |
<interface name="zwp_fullscreen_shell_v1" version="1"> |
| 30 |
<description summary="displays a single surface per output"> |
| 31 |
Displays a single surface per output. |
| 32 |
|
| 33 |
This interface provides a mechanism for a single client to display |
| 34 |
simple full-screen surfaces. While there technically may be multiple |
| 35 |
clients bound to this interface, only one of those clients should be |
| 36 |
shown at a time. |
| 37 |
|
| 38 |
To present a surface, the client uses either the present_surface or |
| 39 |
present_surface_for_mode requests. Presenting a surface takes effect |
| 40 |
on the next wl_surface.commit. See the individual requests for |
| 41 |
details about scaling and mode switches. |
| 42 |
|
| 43 |
The client can have at most one surface per output at any time. |
| 44 |
Requesting a surface to be presented on an output that already has a |
| 45 |
surface replaces the previously presented surface. Presenting a null |
| 46 |
surface removes its content and effectively disables the output. |
| 47 |
Exactly what happens when an output is "disabled" is |
| 48 |
compositor-specific. The same surface may be presented on multiple |
| 49 |
outputs simultaneously. |
| 50 |
|
| 51 |
Once a surface is presented on an output, it stays on that output |
| 52 |
until either the client removes it or the compositor destroys the |
| 53 |
output. This way, the client can update the output's contents by |
| 54 |
simply attaching a new buffer. |
| 55 |
|
| 56 |
Warning! The protocol described in this file is experimental and |
| 57 |
backward incompatible changes may be made. Backward compatible changes |
| 58 |
may be added together with the corresponding interface version bump. |
| 59 |
Backward incompatible changes are done by bumping the version number in |
| 60 |
the protocol and interface names and resetting the interface version. |
| 61 |
Once the protocol is to be declared stable, the 'z' prefix and the |
| 62 |
version number in the protocol and interface names are removed and the |
| 63 |
interface version number is reset. |
| 64 |
</description> |
| 65 |
|
| 66 |
<request name="release" type="destructor"> |
| 67 |
<description summary="release the wl_fullscreen_shell interface"> |
| 68 |
Release the binding from the wl_fullscreen_shell interface. |
| 69 |
|
| 70 |
This destroys the server-side object and frees this binding. If |
| 71 |
the client binds to wl_fullscreen_shell multiple times, it may wish |
| 72 |
to free some of those bindings. |
| 73 |
</description> |
| 74 |
</request> |
| 75 |
|
| 76 |
<enum name="capability"> |
| 77 |
<description summary="capabilities advertised by the compositor"> |
| 78 |
Various capabilities that can be advertised by the compositor. They |
| 79 |
are advertised one-at-a-time when the wl_fullscreen_shell interface is |
| 80 |
bound. See the wl_fullscreen_shell.capability event for more details. |
| 81 |
|
| 82 |
ARBITRARY_MODES: |
| 83 |
This is a hint to the client that indicates that the compositor is |
| 84 |
capable of setting practically any mode on its outputs. If this |
| 85 |
capability is provided, wl_fullscreen_shell.present_surface_for_mode |
| 86 |
will almost never fail and clients should feel free to set whatever |
| 87 |
mode they like. If the compositor does not advertise this, it may |
| 88 |
still support some modes that are not advertised through wl_global.mode |
| 89 |
but it is less likely. |
| 90 |
|
| 91 |
CURSOR_PLANE: |
| 92 |
This is a hint to the client that indicates that the compositor can |
| 93 |
handle a cursor surface from the client without actually compositing. |
| 94 |
This may be because of a hardware cursor plane or some other mechanism. |
| 95 |
If the compositor does not advertise this capability then setting |
| 96 |
wl_pointer.cursor may degrade performance or be ignored entirely. If |
| 97 |
CURSOR_PLANE is not advertised, it is recommended that the client draw |
| 98 |
its own cursor and set wl_pointer.cursor(NULL). |
| 99 |
</description> |
| 100 |
<entry name="arbitrary_modes" value="1" summary="compositor is capable of almost any output mode"/> |
| 101 |
<entry name="cursor_plane" value="2" summary="compositor has a separate cursor plane"/> |
| 102 |
</enum> |
| 103 |
|
| 104 |
<event name="capability"> |
| 105 |
<description summary="advertises a capability of the compositor"> |
| 106 |
Advertises a single capability of the compositor. |
| 107 |
|
| 108 |
When the wl_fullscreen_shell interface is bound, this event is emitted |
| 109 |
once for each capability advertised. Valid capabilities are given by |
| 110 |
the wl_fullscreen_shell.capability enum. If clients want to take |
| 111 |
advantage of any of these capabilities, they should use a |
| 112 |
wl_display.sync request immediately after binding to ensure that they |
| 113 |
receive all the capability events. |
| 114 |
</description> |
| 115 |
<arg name="capability" type="uint" enum="capability" /> |
| 116 |
</event> |
| 117 |
|
| 118 |
<enum name="present_method"> |
| 119 |
<description summary="different method to set the surface fullscreen"> |
| 120 |
Hints to indicate to the compositor how to deal with a conflict |
| 121 |
between the dimensions of the surface and the dimensions of the |
| 122 |
output. The compositor is free to ignore this parameter. |
| 123 |
</description> |
| 124 |
<entry name="default" value="0" summary="no preference, apply default policy"/> |
| 125 |
<entry name="center" value="1" summary="center the surface on the output"/> |
| 126 |
<entry name="zoom" value="2" summary="scale the surface, preserving aspect ratio, to the largest size that will fit on the output" /> |
| 127 |
<entry name="zoom_crop" value="3" summary="scale the surface, preserving aspect ratio, to fully fill the output cropping if needed" /> |
| 128 |
<entry name="stretch" value="4" summary="scale the surface to the size of the output ignoring aspect ratio" /> |
| 129 |
</enum> |
| 130 |
|
| 131 |
<request name="present_surface"> |
| 132 |
<description summary="present surface for display"> |
| 133 |
Present a surface on the given output. |
| 134 |
|
| 135 |
If the output is null, the compositor will present the surface on |
| 136 |
whatever display (or displays) it thinks best. In particular, this |
| 137 |
may replace any or all surfaces currently presented so it should |
| 138 |
not be used in combination with placing surfaces on specific |
| 139 |
outputs. |
| 140 |
|
| 141 |
The method parameter is a hint to the compositor for how the surface |
| 142 |
is to be presented. In particular, it tells the compositor how to |
| 143 |
handle a size mismatch between the presented surface and the |
| 144 |
output. The compositor is free to ignore this parameter. |
| 145 |
|
| 146 |
The "zoom", "zoom_crop", and "stretch" methods imply a scaling |
| 147 |
operation on the surface. This will override any kind of output |
| 148 |
scaling, so the buffer_scale property of the surface is effectively |
| 149 |
ignored. |
| 150 |
|
| 151 |
This request gives the surface the role of a fullscreen shell surface. |
| 152 |
If the surface already has another role, it raises a role protocol |
| 153 |
error. |
| 154 |
</description> |
| 155 |
<arg name="surface" type="object" interface="wl_surface" allow-null="true"/> |
| 156 |
<arg name="method" type="uint" enum="present_method" /> |
| 157 |
<arg name="output" type="object" interface="wl_output" allow-null="true"/> |
| 158 |
</request> |
| 159 |
|
| 160 |
<request name="present_surface_for_mode"> |
| 161 |
<description summary="present surface for display at a particular mode"> |
| 162 |
Presents a surface on the given output for a particular mode. |
| 163 |
|
| 164 |
If the current size of the output differs from that of the surface, |
| 165 |
the compositor will attempt to change the size of the output to |
| 166 |
match the surface. The result of the mode-switch operation will be |
| 167 |
returned via the provided wl_fullscreen_shell_mode_feedback object. |
| 168 |
|
| 169 |
If the current output mode matches the one requested or if the |
| 170 |
compositor successfully switches the mode to match the surface, |
| 171 |
then the mode_successful event will be sent and the output will |
| 172 |
contain the contents of the given surface. If the compositor |
| 173 |
cannot match the output size to the surface size, the mode_failed |
| 174 |
will be sent and the output will contain the contents of the |
| 175 |
previously presented surface (if any). If another surface is |
| 176 |
presented on the given output before either of these has a chance |
| 177 |
to happen, the present_cancelled event will be sent. |
| 178 |
|
| 179 |
Due to race conditions and other issues unknown to the client, no |
| 180 |
mode-switch operation is guaranteed to succeed. However, if the |
| 181 |
mode is one advertised by wl_output.mode or if the compositor |
| 182 |
advertises the ARBITRARY_MODES capability, then the client should |
| 183 |
expect that the mode-switch operation will usually succeed. |
| 184 |
|
| 185 |
If the size of the presented surface changes, the resulting output |
| 186 |
is undefined. The compositor may attempt to change the output mode |
| 187 |
to compensate. However, there is no guarantee that a suitable mode |
| 188 |
will be found and the client has no way to be notified of success |
| 189 |
or failure. |
| 190 |
|
| 191 |
The framerate parameter specifies the desired framerate for the |
| 192 |
output in mHz. The compositor is free to ignore this parameter. A |
| 193 |
value of 0 indicates that the client has no preference. |
| 194 |
|
| 195 |
If the value of wl_output.scale differs from wl_surface.buffer_scale, |
| 196 |
then the compositor may choose a mode that matches either the buffer |
| 197 |
size or the surface size. In either case, the surface will fill the |
| 198 |
output. |
| 199 |
|
| 200 |
This request gives the surface the role of a fullscreen shell surface. |
| 201 |
If the surface already has another role, it raises a role protocol |
| 202 |
error. |
| 203 |
</description> |
| 204 |
<arg name="surface" type="object" interface="wl_surface"/> |
| 205 |
<arg name="output" type="object" interface="wl_output"/> |
| 206 |
<arg name="framerate" type="int"/> |
| 207 |
<arg name="feedback" type="new_id" interface="zwp_fullscreen_shell_mode_feedback_v1"/> |
| 208 |
</request> |
| 209 |
|
| 210 |
<enum name="error"> |
| 211 |
<description summary="wl_fullscreen_shell error values"> |
| 212 |
These errors can be emitted in response to wl_fullscreen_shell requests. |
| 213 |
</description> |
| 214 |
<entry name="invalid_method" value="0" summary="present_method is not known"/> |
| 215 |
<entry name="role" value="1" summary="given wl_surface has another role"/> |
| 216 |
</enum> |
| 217 |
</interface> |
| 218 |
|
| 219 |
<interface name="zwp_fullscreen_shell_mode_feedback_v1" version="1"> |
| 220 |
<event name="mode_successful" type="destructor"> |
| 221 |
<description summary="mode switch succeeded"> |
| 222 |
This event indicates that the attempted mode switch operation was |
| 223 |
successful. A surface of the size requested in the mode switch |
| 224 |
will fill the output without scaling. |
| 225 |
|
| 226 |
Upon receiving this event, the client should destroy the |
| 227 |
wl_fullscreen_shell_mode_feedback object. |
| 228 |
</description> |
| 229 |
</event> |
| 230 |
|
| 231 |
<event name="mode_failed" type="destructor"> |
| 232 |
<description summary="mode switch failed"> |
| 233 |
This event indicates that the attempted mode switch operation |
| 234 |
failed. This may be because the requested output mode is not |
| 235 |
possible or it may mean that the compositor does not want to allow it. |
| 236 |
|
| 237 |
Upon receiving this event, the client should destroy the |
| 238 |
wl_fullscreen_shell_mode_feedback object. |
| 239 |
</description> |
| 240 |
</event> |
| 241 |
|
| 242 |
<event name="present_cancelled" type="destructor"> |
| 243 |
<description summary="mode switch cancelled"> |
| 244 |
This event indicates that the attempted mode switch operation was |
| 245 |
cancelled. Most likely this is because the client requested a |
| 246 |
second mode switch before the first one completed. |
| 247 |
|
| 248 |
Upon receiving this event, the client should destroy the |
| 249 |
wl_fullscreen_shell_mode_feedback object. |
| 250 |
</description> |
| 251 |
</event> |
| 252 |
</interface> |
| 253 |
|
| 254 |
</protocol> |