aboutsummaryrefslogtreecommitdiff
path: root/raylib/src/external/glfw/deps/wayland
diff options
context:
space:
mode:
Diffstat (limited to 'raylib/src/external/glfw/deps/wayland')
-rw-r--r--raylib/src/external/glfw/deps/wayland/fractional-scale-v1.xml102
-rw-r--r--raylib/src/external/glfw/deps/wayland/idle-inhibit-unstable-v1.xml83
-rw-r--r--raylib/src/external/glfw/deps/wayland/pointer-constraints-unstable-v1.xml339
-rw-r--r--raylib/src/external/glfw/deps/wayland/relative-pointer-unstable-v1.xml136
-rw-r--r--raylib/src/external/glfw/deps/wayland/viewporter.xml180
-rw-r--r--raylib/src/external/glfw/deps/wayland/wayland.xml3151
-rw-r--r--raylib/src/external/glfw/deps/wayland/xdg-activation-v1.xml200
-rw-r--r--raylib/src/external/glfw/deps/wayland/xdg-decoration-unstable-v1.xml156
-rw-r--r--raylib/src/external/glfw/deps/wayland/xdg-shell.xml1370
9 files changed, 5717 insertions, 0 deletions
diff --git a/raylib/src/external/glfw/deps/wayland/fractional-scale-v1.xml b/raylib/src/external/glfw/deps/wayland/fractional-scale-v1.xml
new file mode 100644
index 0000000..350bfc0
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/fractional-scale-v1.xml
@@ -0,0 +1,102 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="fractional_scale_v1">
3 <copyright>
4 Copyright © 2022 Kenny Levinsen
5
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice (including the next
14 paragraph) shall be included in all copies or substantial portions of the
15 Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23 DEALINGS IN THE SOFTWARE.
24 </copyright>
25
26 <description summary="Protocol for requesting fractional surface scales">
27 This protocol allows a compositor to suggest for surfaces to render at
28 fractional scales.
29
30 A client can submit scaled content by utilizing wp_viewport. This is done by
31 creating a wp_viewport object for the surface and setting the destination
32 rectangle to the surface size before the scale factor is applied.
33
34 The buffer size is calculated by multiplying the surface size by the
35 intended scale.
36
37 The wl_surface buffer scale should remain set to 1.
38
39 If a surface has a surface-local size of 100 px by 50 px and wishes to
40 submit buffers with a scale of 1.5, then a buffer of 150px by 75 px should
41 be used and the wp_viewport destination rectangle should be 100 px by 50 px.
42
43 For toplevel surfaces, the size is rounded halfway away from zero. The
44 rounding algorithm for subsurface position and size is not defined.
45 </description>
46
47 <interface name="wp_fractional_scale_manager_v1" version="1">
48 <description summary="fractional surface scale information">
49 A global interface for requesting surfaces to use fractional scales.
50 </description>
51
52 <request name="destroy" type="destructor">
53 <description summary="unbind the fractional surface scale interface">
54 Informs the server that the client will not be using this protocol
55 object anymore. This does not affect any other objects,
56 wp_fractional_scale_v1 objects included.
57 </description>
58 </request>
59
60 <enum name="error">
61 <entry name="fractional_scale_exists" value="0"
62 summary="the surface already has a fractional_scale object associated"/>
63 </enum>
64
65 <request name="get_fractional_scale">
66 <description summary="extend surface interface for scale information">
67 Create an add-on object for the the wl_surface to let the compositor
68 request fractional scales. If the given wl_surface already has a
69 wp_fractional_scale_v1 object associated, the fractional_scale_exists
70 protocol error is raised.
71 </description>
72 <arg name="id" type="new_id" interface="wp_fractional_scale_v1"
73 summary="the new surface scale info interface id"/>
74 <arg name="surface" type="object" interface="wl_surface"
75 summary="the surface"/>
76 </request>
77 </interface>
78
79 <interface name="wp_fractional_scale_v1" version="1">
80 <description summary="fractional scale interface to a wl_surface">
81 An additional interface to a wl_surface object which allows the compositor
82 to inform the client of the preferred scale.
83 </description>
84
85 <request name="destroy" type="destructor">
86 <description summary="remove surface scale information for surface">
87 Destroy the fractional scale object. When this object is destroyed,
88 preferred_scale events will no longer be sent.
89 </description>
90 </request>
91
92 <event name="preferred_scale">
93 <description summary="notify of new preferred scale">
94 Notification of a new preferred scale for this surface that the
95 compositor suggests that the client should use.
96
97 The sent scale is the numerator of a fraction with a denominator of 120.
98 </description>
99 <arg name="scale" type="uint" summary="the new preferred scale"/>
100 </event>
101 </interface>
102</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/idle-inhibit-unstable-v1.xml b/raylib/src/external/glfw/deps/wayland/idle-inhibit-unstable-v1.xml
new file mode 100644
index 0000000..9c06cdc
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/idle-inhibit-unstable-v1.xml
@@ -0,0 +1,83 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="idle_inhibit_unstable_v1">
3
4 <copyright>
5 Copyright © 2015 Samsung Electronics Co., Ltd
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="zwp_idle_inhibit_manager_v1" version="1">
28 <description summary="control behavior when display idles">
29 This interface permits inhibiting the idle behavior such as screen
30 blanking, locking, and screensaving. The client binds the idle manager
31 globally, then creates idle-inhibitor objects for each surface.
32
33 Warning! The protocol described in this file is experimental and
34 backward incompatible changes may be made. Backward compatible changes
35 may be added together with the corresponding interface version bump.
36 Backward incompatible changes are done by bumping the version number in
37 the protocol and interface names and resetting the interface version.
38 Once the protocol is to be declared stable, the 'z' prefix and the
39 version number in the protocol and interface names are removed and the
40 interface version number is reset.
41 </description>
42
43 <request name="destroy" type="destructor">
44 <description summary="destroy the idle inhibitor object">
45 Destroy the inhibit manager.
46 </description>
47 </request>
48
49 <request name="create_inhibitor">
50 <description summary="create a new inhibitor object">
51 Create a new inhibitor object associated with the given surface.
52 </description>
53 <arg name="id" type="new_id" interface="zwp_idle_inhibitor_v1"/>
54 <arg name="surface" type="object" interface="wl_surface"
55 summary="the surface that inhibits the idle behavior"/>
56 </request>
57
58 </interface>
59
60 <interface name="zwp_idle_inhibitor_v1" version="1">
61 <description summary="context object for inhibiting idle behavior">
62 An idle inhibitor prevents the output that the associated surface is
63 visible on from being set to a state where it is not visually usable due
64 to lack of user interaction (e.g. blanked, dimmed, locked, set to power
65 save, etc.) Any screensaver processes are also blocked from displaying.
66
67 If the surface is destroyed, unmapped, becomes occluded, loses
68 visibility, or otherwise becomes not visually relevant for the user, the
69 idle inhibitor will not be honored by the compositor; if the surface
70 subsequently regains visibility the inhibitor takes effect once again.
71 Likewise, the inhibitor isn't honored if the system was already idled at
72 the time the inhibitor was established, although if the system later
73 de-idles and re-idles the inhibitor will take effect.
74 </description>
75
76 <request name="destroy" type="destructor">
77 <description summary="destroy the idle inhibitor object">
78 Remove the inhibitor effect from the associated wl_surface.
79 </description>
80 </request>
81
82 </interface>
83</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/pointer-constraints-unstable-v1.xml b/raylib/src/external/glfw/deps/wayland/pointer-constraints-unstable-v1.xml
new file mode 100644
index 0000000..efd64b6
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/pointer-constraints-unstable-v1.xml
@@ -0,0 +1,339 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="pointer_constraints_unstable_v1">
3
4 <copyright>
5 Copyright © 2014 Jonas Ådahl
6 Copyright © 2015 Red Hat Inc.
7
8 Permission is hereby granted, free of charge, to any person obtaining a
9 copy of this software and associated documentation files (the "Software"),
10 to deal in the Software without restriction, including without limitation
11 the rights to use, copy, modify, merge, publish, distribute, sublicense,
12 and/or sell copies of the Software, and to permit persons to whom the
13 Software is furnished to do so, subject to the following conditions:
14
15 The above copyright notice and this permission notice (including the next
16 paragraph) shall be included in all copies or substantial portions of the
17 Software.
18
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25 DEALINGS IN THE SOFTWARE.
26 </copyright>
27
28 <description summary="protocol for constraining pointer motions">
29 This protocol specifies a set of interfaces used for adding constraints to
30 the motion of a pointer. Possible constraints include confining pointer
31 motions to a given region, or locking it to its current position.
32
33 In order to constrain the pointer, a client must first bind the global
34 interface "wp_pointer_constraints" which, if a compositor supports pointer
35 constraints, is exposed by the registry. Using the bound global object, the
36 client uses the request that corresponds to the type of constraint it wants
37 to make. See wp_pointer_constraints for more details.
38
39 Warning! The protocol described in this file is experimental and backward
40 incompatible changes may be made. Backward compatible changes may be added
41 together with the corresponding interface version bump. Backward
42 incompatible changes are done by bumping the version number in the protocol
43 and interface names and resetting the interface version. Once the protocol
44 is to be declared stable, the 'z' prefix and the version number in the
45 protocol and interface names are removed and the interface version number is
46 reset.
47 </description>
48
49 <interface name="zwp_pointer_constraints_v1" version="1">
50 <description summary="constrain the movement of a pointer">
51 The global interface exposing pointer constraining functionality. It
52 exposes two requests: lock_pointer for locking the pointer to its
53 position, and confine_pointer for locking the pointer to a region.
54
55 The lock_pointer and confine_pointer requests create the objects
56 wp_locked_pointer and wp_confined_pointer respectively, and the client can
57 use these objects to interact with the lock.
58
59 For any surface, only one lock or confinement may be active across all
60 wl_pointer objects of the same seat. If a lock or confinement is requested
61 when another lock or confinement is active or requested on the same surface
62 and with any of the wl_pointer objects of the same seat, an
63 'already_constrained' error will be raised.
64 </description>
65
66 <enum name="error">
67 <description summary="wp_pointer_constraints error values">
68 These errors can be emitted in response to wp_pointer_constraints
69 requests.
70 </description>
71 <entry name="already_constrained" value="1"
72 summary="pointer constraint already requested on that surface"/>
73 </enum>
74
75 <enum name="lifetime">
76 <description summary="constraint lifetime">
77 These values represent different lifetime semantics. They are passed
78 as arguments to the factory requests to specify how the constraint
79 lifetimes should be managed.
80 </description>
81 <entry name="oneshot" value="1">
82 <description summary="the pointer constraint is defunct once deactivated">
83 A oneshot pointer constraint will never reactivate once it has been
84 deactivated. See the corresponding deactivation event
85 (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for
86 details.
87 </description>
88 </entry>
89 <entry name="persistent" value="2">
90 <description summary="the pointer constraint may reactivate">
91 A persistent pointer constraint may again reactivate once it has
92 been deactivated. See the corresponding deactivation event
93 (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for
94 details.
95 </description>
96 </entry>
97 </enum>
98
99 <request name="destroy" type="destructor">
100 <description summary="destroy the pointer constraints manager object">
101 Used by the client to notify the server that it will no longer use this
102 pointer constraints object.
103 </description>
104 </request>
105
106 <request name="lock_pointer">
107 <description summary="lock pointer to a position">
108 The lock_pointer request lets the client request to disable movements of
109 the virtual pointer (i.e. the cursor), effectively locking the pointer
110 to a position. This request may not take effect immediately; in the
111 future, when the compositor deems implementation-specific constraints
112 are satisfied, the pointer lock will be activated and the compositor
113 sends a locked event.
114
115 The protocol provides no guarantee that the constraints are ever
116 satisfied, and does not require the compositor to send an error if the
117 constraints cannot ever be satisfied. It is thus possible to request a
118 lock that will never activate.
119
120 There may not be another pointer constraint of any kind requested or
121 active on the surface for any of the wl_pointer objects of the seat of
122 the passed pointer when requesting a lock. If there is, an error will be
123 raised. See general pointer lock documentation for more details.
124
125 The intersection of the region passed with this request and the input
126 region of the surface is used to determine where the pointer must be
127 in order for the lock to activate. It is up to the compositor whether to
128 warp the pointer or require some kind of user interaction for the lock
129 to activate. If the region is null the surface input region is used.
130
131 A surface may receive pointer focus without the lock being activated.
132
133 The request creates a new object wp_locked_pointer which is used to
134 interact with the lock as well as receive updates about its state. See
135 the the description of wp_locked_pointer for further information.
136
137 Note that while a pointer is locked, the wl_pointer objects of the
138 corresponding seat will not emit any wl_pointer.motion events, but
139 relative motion events will still be emitted via wp_relative_pointer
140 objects of the same seat. wl_pointer.axis and wl_pointer.button events
141 are unaffected.
142 </description>
143 <arg name="id" type="new_id" interface="zwp_locked_pointer_v1"/>
144 <arg name="surface" type="object" interface="wl_surface"
145 summary="surface to lock pointer to"/>
146 <arg name="pointer" type="object" interface="wl_pointer"
147 summary="the pointer that should be locked"/>
148 <arg name="region" type="object" interface="wl_region" allow-null="true"
149 summary="region of surface"/>
150 <arg name="lifetime" type="uint" enum="lifetime" summary="lock lifetime"/>
151 </request>
152
153 <request name="confine_pointer">
154 <description summary="confine pointer to a region">
155 The confine_pointer request lets the client request to confine the
156 pointer cursor to a given region. This request may not take effect
157 immediately; in the future, when the compositor deems implementation-
158 specific constraints are satisfied, the pointer confinement will be
159 activated and the compositor sends a confined event.
160
161 The intersection of the region passed with this request and the input
162 region of the surface is used to determine where the pointer must be
163 in order for the confinement to activate. It is up to the compositor
164 whether to warp the pointer or require some kind of user interaction for
165 the confinement to activate. If the region is null the surface input
166 region is used.
167
168 The request will create a new object wp_confined_pointer which is used
169 to interact with the confinement as well as receive updates about its
170 state. See the the description of wp_confined_pointer for further
171 information.
172 </description>
173 <arg name="id" type="new_id" interface="zwp_confined_pointer_v1"/>
174 <arg name="surface" type="object" interface="wl_surface"
175 summary="surface to lock pointer to"/>
176 <arg name="pointer" type="object" interface="wl_pointer"
177 summary="the pointer that should be confined"/>
178 <arg name="region" type="object" interface="wl_region" allow-null="true"
179 summary="region of surface"/>
180 <arg name="lifetime" type="uint" enum="lifetime" summary="confinement lifetime"/>
181 </request>
182 </interface>
183
184 <interface name="zwp_locked_pointer_v1" version="1">
185 <description summary="receive relative pointer motion events">
186 The wp_locked_pointer interface represents a locked pointer state.
187
188 While the lock of this object is active, the wl_pointer objects of the
189 associated seat will not emit any wl_pointer.motion events.
190
191 This object will send the event 'locked' when the lock is activated.
192 Whenever the lock is activated, it is guaranteed that the locked surface
193 will already have received pointer focus and that the pointer will be
194 within the region passed to the request creating this object.
195
196 To unlock the pointer, send the destroy request. This will also destroy
197 the wp_locked_pointer object.
198
199 If the compositor decides to unlock the pointer the unlocked event is
200 sent. See wp_locked_pointer.unlock for details.
201
202 When unlocking, the compositor may warp the cursor position to the set
203 cursor position hint. If it does, it will not result in any relative
204 motion events emitted via wp_relative_pointer.
205
206 If the surface the lock was requested on is destroyed and the lock is not
207 yet activated, the wp_locked_pointer object is now defunct and must be
208 destroyed.
209 </description>
210
211 <request name="destroy" type="destructor">
212 <description summary="destroy the locked pointer object">
213 Destroy the locked pointer object. If applicable, the compositor will
214 unlock the pointer.
215 </description>
216 </request>
217
218 <request name="set_cursor_position_hint">
219 <description summary="set the pointer cursor position hint">
220 Set the cursor position hint relative to the top left corner of the
221 surface.
222
223 If the client is drawing its own cursor, it should update the position
224 hint to the position of its own cursor. A compositor may use this
225 information to warp the pointer upon unlock in order to avoid pointer
226 jumps.
227
228 The cursor position hint is double buffered. The new hint will only take
229 effect when the associated surface gets it pending state applied. See
230 wl_surface.commit for details.
231 </description>
232 <arg name="surface_x" type="fixed"
233 summary="surface-local x coordinate"/>
234 <arg name="surface_y" type="fixed"
235 summary="surface-local y coordinate"/>
236 </request>
237
238 <request name="set_region">
239 <description summary="set a new lock region">
240 Set a new region used to lock the pointer.
241
242 The new lock region is double-buffered. The new lock region will
243 only take effect when the associated surface gets its pending state
244 applied. See wl_surface.commit for details.
245
246 For details about the lock region, see wp_locked_pointer.
247 </description>
248 <arg name="region" type="object" interface="wl_region" allow-null="true"
249 summary="region of surface"/>
250 </request>
251
252 <event name="locked">
253 <description summary="lock activation event">
254 Notification that the pointer lock of the seat's pointer is activated.
255 </description>
256 </event>
257
258 <event name="unlocked">
259 <description summary="lock deactivation event">
260 Notification that the pointer lock of the seat's pointer is no longer
261 active. If this is a oneshot pointer lock (see
262 wp_pointer_constraints.lifetime) this object is now defunct and should
263 be destroyed. If this is a persistent pointer lock (see
264 wp_pointer_constraints.lifetime) this pointer lock may again
265 reactivate in the future.
266 </description>
267 </event>
268 </interface>
269
270 <interface name="zwp_confined_pointer_v1" version="1">
271 <description summary="confined pointer object">
272 The wp_confined_pointer interface represents a confined pointer state.
273
274 This object will send the event 'confined' when the confinement is
275 activated. Whenever the confinement is activated, it is guaranteed that
276 the surface the pointer is confined to will already have received pointer
277 focus and that the pointer will be within the region passed to the request
278 creating this object. It is up to the compositor to decide whether this
279 requires some user interaction and if the pointer will warp to within the
280 passed region if outside.
281
282 To unconfine the pointer, send the destroy request. This will also destroy
283 the wp_confined_pointer object.
284
285 If the compositor decides to unconfine the pointer the unconfined event is
286 sent. The wp_confined_pointer object is at this point defunct and should
287 be destroyed.
288 </description>
289
290 <request name="destroy" type="destructor">
291 <description summary="destroy the confined pointer object">
292 Destroy the confined pointer object. If applicable, the compositor will
293 unconfine the pointer.
294 </description>
295 </request>
296
297 <request name="set_region">
298 <description summary="set a new confine region">
299 Set a new region used to confine the pointer.
300
301 The new confine region is double-buffered. The new confine region will
302 only take effect when the associated surface gets its pending state
303 applied. See wl_surface.commit for details.
304
305 If the confinement is active when the new confinement region is applied
306 and the pointer ends up outside of newly applied region, the pointer may
307 warped to a position within the new confinement region. If warped, a
308 wl_pointer.motion event will be emitted, but no
309 wp_relative_pointer.relative_motion event.
310
311 The compositor may also, instead of using the new region, unconfine the
312 pointer.
313
314 For details about the confine region, see wp_confined_pointer.
315 </description>
316 <arg name="region" type="object" interface="wl_region" allow-null="true"
317 summary="region of surface"/>
318 </request>
319
320 <event name="confined">
321 <description summary="pointer confined">
322 Notification that the pointer confinement of the seat's pointer is
323 activated.
324 </description>
325 </event>
326
327 <event name="unconfined">
328 <description summary="pointer unconfined">
329 Notification that the pointer confinement of the seat's pointer is no
330 longer active. If this is a oneshot pointer confinement (see
331 wp_pointer_constraints.lifetime) this object is now defunct and should
332 be destroyed. If this is a persistent pointer confinement (see
333 wp_pointer_constraints.lifetime) this pointer confinement may again
334 reactivate in the future.
335 </description>
336 </event>
337 </interface>
338
339</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/relative-pointer-unstable-v1.xml b/raylib/src/external/glfw/deps/wayland/relative-pointer-unstable-v1.xml
new file mode 100644
index 0000000..ca6f81d
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/relative-pointer-unstable-v1.xml
@@ -0,0 +1,136 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="relative_pointer_unstable_v1">
3
4 <copyright>
5 Copyright © 2014 Jonas Ådahl
6 Copyright © 2015 Red Hat Inc.
7
8 Permission is hereby granted, free of charge, to any person obtaining a
9 copy of this software and associated documentation files (the "Software"),
10 to deal in the Software without restriction, including without limitation
11 the rights to use, copy, modify, merge, publish, distribute, sublicense,
12 and/or sell copies of the Software, and to permit persons to whom the
13 Software is furnished to do so, subject to the following conditions:
14
15 The above copyright notice and this permission notice (including the next
16 paragraph) shall be included in all copies or substantial portions of the
17 Software.
18
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25 DEALINGS IN THE SOFTWARE.
26 </copyright>
27
28 <description summary="protocol for relative pointer motion events">
29 This protocol specifies a set of interfaces used for making clients able to
30 receive relative pointer events not obstructed by barriers (such as the
31 monitor edge or other pointer barriers).
32
33 To start receiving relative pointer events, a client must first bind the
34 global interface "wp_relative_pointer_manager" which, if a compositor
35 supports relative pointer motion events, is exposed by the registry. After
36 having created the relative pointer manager proxy object, the client uses
37 it to create the actual relative pointer object using the
38 "get_relative_pointer" request given a wl_pointer. The relative pointer
39 motion events will then, when applicable, be transmitted via the proxy of
40 the newly created relative pointer object. See the documentation of the
41 relative pointer interface for more details.
42
43 Warning! The protocol described in this file is experimental and backward
44 incompatible changes may be made. Backward compatible changes may be added
45 together with the corresponding interface version bump. Backward
46 incompatible changes are done by bumping the version number in the protocol
47 and interface names and resetting the interface version. Once the protocol
48 is to be declared stable, the 'z' prefix and the version number in the
49 protocol and interface names are removed and the interface version number is
50 reset.
51 </description>
52
53 <interface name="zwp_relative_pointer_manager_v1" version="1">
54 <description summary="get relative pointer objects">
55 A global interface used for getting the relative pointer object for a
56 given pointer.
57 </description>
58
59 <request name="destroy" type="destructor">
60 <description summary="destroy the relative pointer manager object">
61 Used by the client to notify the server that it will no longer use this
62 relative pointer manager object.
63 </description>
64 </request>
65
66 <request name="get_relative_pointer">
67 <description summary="get a relative pointer object">
68 Create a relative pointer interface given a wl_pointer object. See the
69 wp_relative_pointer interface for more details.
70 </description>
71 <arg name="id" type="new_id" interface="zwp_relative_pointer_v1"/>
72 <arg name="pointer" type="object" interface="wl_pointer"/>
73 </request>
74 </interface>
75
76 <interface name="zwp_relative_pointer_v1" version="1">
77 <description summary="relative pointer object">
78 A wp_relative_pointer object is an extension to the wl_pointer interface
79 used for emitting relative pointer events. It shares the same focus as
80 wl_pointer objects of the same seat and will only emit events when it has
81 focus.
82 </description>
83
84 <request name="destroy" type="destructor">
85 <description summary="release the relative pointer object"/>
86 </request>
87
88 <event name="relative_motion">
89 <description summary="relative pointer motion">
90 Relative x/y pointer motion from the pointer of the seat associated with
91 this object.
92
93 A relative motion is in the same dimension as regular wl_pointer motion
94 events, except they do not represent an absolute position. For example,
95 moving a pointer from (x, y) to (x', y') would have the equivalent
96 relative motion (x' - x, y' - y). If a pointer motion caused the
97 absolute pointer position to be clipped by for example the edge of the
98 monitor, the relative motion is unaffected by the clipping and will
99 represent the unclipped motion.
100
101 This event also contains non-accelerated motion deltas. The
102 non-accelerated delta is, when applicable, the regular pointer motion
103 delta as it was before having applied motion acceleration and other
104 transformations such as normalization.
105
106 Note that the non-accelerated delta does not represent 'raw' events as
107 they were read from some device. Pointer motion acceleration is device-
108 and configuration-specific and non-accelerated deltas and accelerated
109 deltas may have the same value on some devices.
110
111 Relative motions are not coupled to wl_pointer.motion events, and can be
112 sent in combination with such events, but also independently. There may
113 also be scenarios where wl_pointer.motion is sent, but there is no
114 relative motion. The order of an absolute and relative motion event
115 originating from the same physical motion is not guaranteed.
116
117 If the client needs button events or focus state, it can receive them
118 from a wl_pointer object of the same seat that the wp_relative_pointer
119 object is associated with.
120 </description>
121 <arg name="utime_hi" type="uint"
122 summary="high 32 bits of a 64 bit timestamp with microsecond granularity"/>
123 <arg name="utime_lo" type="uint"
124 summary="low 32 bits of a 64 bit timestamp with microsecond granularity"/>
125 <arg name="dx" type="fixed"
126 summary="the x component of the motion vector"/>
127 <arg name="dy" type="fixed"
128 summary="the y component of the motion vector"/>
129 <arg name="dx_unaccel" type="fixed"
130 summary="the x component of the unaccelerated motion vector"/>
131 <arg name="dy_unaccel" type="fixed"
132 summary="the y component of the unaccelerated motion vector"/>
133 </event>
134 </interface>
135
136</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/viewporter.xml b/raylib/src/external/glfw/deps/wayland/viewporter.xml
new file mode 100644
index 0000000..d1048d1
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/viewporter.xml
@@ -0,0 +1,180 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="viewporter">
3
4 <copyright>
5 Copyright © 2013-2016 Collabora, Ltd.
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="wp_viewporter" version="1">
28 <description summary="surface cropping and scaling">
29 The global interface exposing surface cropping and scaling
30 capabilities is used to instantiate an interface extension for a
31 wl_surface object. This extended interface will then allow
32 cropping and scaling the surface contents, effectively
33 disconnecting the direct relationship between the buffer and the
34 surface size.
35 </description>
36
37 <request name="destroy" type="destructor">
38 <description summary="unbind from the cropping and scaling interface">
39 Informs the server that the client will not be using this
40 protocol object anymore. This does not affect any other objects,
41 wp_viewport objects included.
42 </description>
43 </request>
44
45 <enum name="error">
46 <entry name="viewport_exists" value="0"
47 summary="the surface already has a viewport object associated"/>
48 </enum>
49
50 <request name="get_viewport">
51 <description summary="extend surface interface for crop and scale">
52 Instantiate an interface extension for the given wl_surface to
53 crop and scale its content. If the given wl_surface already has
54 a wp_viewport object associated, the viewport_exists
55 protocol error is raised.
56 </description>
57 <arg name="id" type="new_id" interface="wp_viewport"
58 summary="the new viewport interface id"/>
59 <arg name="surface" type="object" interface="wl_surface"
60 summary="the surface"/>
61 </request>
62 </interface>
63
64 <interface name="wp_viewport" version="1">
65 <description summary="crop and scale interface to a wl_surface">
66 An additional interface to a wl_surface object, which allows the
67 client to specify the cropping and scaling of the surface
68 contents.
69
70 This interface works with two concepts: the source rectangle (src_x,
71 src_y, src_width, src_height), and the destination size (dst_width,
72 dst_height). The contents of the source rectangle are scaled to the
73 destination size, and content outside the source rectangle is ignored.
74 This state is double-buffered, and is applied on the next
75 wl_surface.commit.
76
77 The two parts of crop and scale state are independent: the source
78 rectangle, and the destination size. Initially both are unset, that
79 is, no scaling is applied. The whole of the current wl_buffer is
80 used as the source, and the surface size is as defined in
81 wl_surface.attach.
82
83 If the destination size is set, it causes the surface size to become
84 dst_width, dst_height. The source (rectangle) is scaled to exactly
85 this size. This overrides whatever the attached wl_buffer size is,
86 unless the wl_buffer is NULL. If the wl_buffer is NULL, the surface
87 has no content and therefore no size. Otherwise, the size is always
88 at least 1x1 in surface local coordinates.
89
90 If the source rectangle is set, it defines what area of the wl_buffer is
91 taken as the source. If the source rectangle is set and the destination
92 size is not set, then src_width and src_height must be integers, and the
93 surface size becomes the source rectangle size. This results in cropping
94 without scaling. If src_width or src_height are not integers and
95 destination size is not set, the bad_size protocol error is raised when
96 the surface state is applied.
97
98 The coordinate transformations from buffer pixel coordinates up to
99 the surface-local coordinates happen in the following order:
100 1. buffer_transform (wl_surface.set_buffer_transform)
101 2. buffer_scale (wl_surface.set_buffer_scale)
102 3. crop and scale (wp_viewport.set*)
103 This means, that the source rectangle coordinates of crop and scale
104 are given in the coordinates after the buffer transform and scale,
105 i.e. in the coordinates that would be the surface-local coordinates
106 if the crop and scale was not applied.
107
108 If src_x or src_y are negative, the bad_value protocol error is raised.
109 Otherwise, if the source rectangle is partially or completely outside of
110 the non-NULL wl_buffer, then the out_of_buffer protocol error is raised
111 when the surface state is applied. A NULL wl_buffer does not raise the
112 out_of_buffer error.
113
114 If the wl_surface associated with the wp_viewport is destroyed,
115 all wp_viewport requests except 'destroy' raise the protocol error
116 no_surface.
117
118 If the wp_viewport object is destroyed, the crop and scale
119 state is removed from the wl_surface. The change will be applied
120 on the next wl_surface.commit.
121 </description>
122
123 <request name="destroy" type="destructor">
124 <description summary="remove scaling and cropping from the surface">
125 The associated wl_surface's crop and scale state is removed.
126 The change is applied on the next wl_surface.commit.
127 </description>
128 </request>
129
130 <enum name="error">
131 <entry name="bad_value" value="0"
132 summary="negative or zero values in width or height"/>
133 <entry name="bad_size" value="1"
134 summary="destination size is not integer"/>
135 <entry name="out_of_buffer" value="2"
136 summary="source rectangle extends outside of the content area"/>
137 <entry name="no_surface" value="3"
138 summary="the wl_surface was destroyed"/>
139 </enum>
140
141 <request name="set_source">
142 <description summary="set the source rectangle for cropping">
143 Set the source rectangle of the associated wl_surface. See
144 wp_viewport for the description, and relation to the wl_buffer
145 size.
146
147 If all of x, y, width and height are -1.0, the source rectangle is
148 unset instead. Any other set of values where width or height are zero
149 or negative, or x or y are negative, raise the bad_value protocol
150 error.
151
152 The crop and scale state is double-buffered state, and will be
153 applied on the next wl_surface.commit.
154 </description>
155 <arg name="x" type="fixed" summary="source rectangle x"/>
156 <arg name="y" type="fixed" summary="source rectangle y"/>
157 <arg name="width" type="fixed" summary="source rectangle width"/>
158 <arg name="height" type="fixed" summary="source rectangle height"/>
159 </request>
160
161 <request name="set_destination">
162 <description summary="set the surface size for scaling">
163 Set the destination size of the associated wl_surface. See
164 wp_viewport for the description, and relation to the wl_buffer
165 size.
166
167 If width is -1 and height is -1, the destination size is unset
168 instead. Any other pair of values for width and height that
169 contains zero or negative values raises the bad_value protocol
170 error.
171
172 The crop and scale state is double-buffered state, and will be
173 applied on the next wl_surface.commit.
174 </description>
175 <arg name="width" type="int" summary="surface width"/>
176 <arg name="height" type="int" summary="surface height"/>
177 </request>
178 </interface>
179
180</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/wayland.xml b/raylib/src/external/glfw/deps/wayland/wayland.xml
new file mode 100644
index 0000000..10e039d
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/wayland.xml
@@ -0,0 +1,3151 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="wayland">
3
4 <copyright>
5 Copyright © 2008-2011 Kristian Høgsberg
6 Copyright © 2010-2011 Intel Corporation
7 Copyright © 2012-2013 Collabora, Ltd.
8
9 Permission is hereby granted, free of charge, to any person
10 obtaining a copy of this software and associated documentation files
11 (the "Software"), to deal in the Software without restriction,
12 including without limitation the rights to use, copy, modify, merge,
13 publish, distribute, sublicense, and/or sell copies of the Software,
14 and to permit persons to whom the Software is furnished to do so,
15 subject to the following conditions:
16
17 The above copyright notice and this permission notice (including the
18 next paragraph) shall be included in all copies or substantial
19 portions of the Software.
20
21 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
25 BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
26 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
27 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28 SOFTWARE.
29 </copyright>
30
31 <interface name="wl_display" version="1">
32 <description summary="core global object">
33 The core global object. This is a special singleton object. It
34 is used for internal Wayland protocol features.
35 </description>
36
37 <request name="sync">
38 <description summary="asynchronous roundtrip">
39 The sync request asks the server to emit the 'done' event
40 on the returned wl_callback object. Since requests are
41 handled in-order and events are delivered in-order, this can
42 be used as a barrier to ensure all previous requests and the
43 resulting events have been handled.
44
45 The object returned by this request will be destroyed by the
46 compositor after the callback is fired and as such the client must not
47 attempt to use it after that point.
48
49 The callback_data passed in the callback is the event serial.
50 </description>
51 <arg name="callback" type="new_id" interface="wl_callback"
52 summary="callback object for the sync request"/>
53 </request>
54
55 <request name="get_registry">
56 <description summary="get global registry object">
57 This request creates a registry object that allows the client
58 to list and bind the global objects available from the
59 compositor.
60
61 It should be noted that the server side resources consumed in
62 response to a get_registry request can only be released when the
63 client disconnects, not when the client side proxy is destroyed.
64 Therefore, clients should invoke get_registry as infrequently as
65 possible to avoid wasting memory.
66 </description>
67 <arg name="registry" type="new_id" interface="wl_registry"
68 summary="global registry object"/>
69 </request>
70
71 <event name="error">
72 <description summary="fatal error event">
73 The error event is sent out when a fatal (non-recoverable)
74 error has occurred. The object_id argument is the object
75 where the error occurred, most often in response to a request
76 to that object. The code identifies the error and is defined
77 by the object interface. As such, each interface defines its
78 own set of error codes. The message is a brief description
79 of the error, for (debugging) convenience.
80 </description>
81 <arg name="object_id" type="object" summary="object where the error occurred"/>
82 <arg name="code" type="uint" summary="error code"/>
83 <arg name="message" type="string" summary="error description"/>
84 </event>
85
86 <enum name="error">
87 <description summary="global error values">
88 These errors are global and can be emitted in response to any
89 server request.
90 </description>
91 <entry name="invalid_object" value="0"
92 summary="server couldn't find object"/>
93 <entry name="invalid_method" value="1"
94 summary="method doesn't exist on the specified interface or malformed request"/>
95 <entry name="no_memory" value="2"
96 summary="server is out of memory"/>
97 <entry name="implementation" value="3"
98 summary="implementation error in compositor"/>
99 </enum>
100
101 <event name="delete_id">
102 <description summary="acknowledge object ID deletion">
103 This event is used internally by the object ID management
104 logic. When a client deletes an object that it had created,
105 the server will send this event to acknowledge that it has
106 seen the delete request. When the client receives this event,
107 it will know that it can safely reuse the object ID.
108 </description>
109 <arg name="id" type="uint" summary="deleted object ID"/>
110 </event>
111 </interface>
112
113 <interface name="wl_registry" version="1">
114 <description summary="global registry object">
115 The singleton global registry object. The server has a number of
116 global objects that are available to all clients. These objects
117 typically represent an actual object in the server (for example,
118 an input device) or they are singleton objects that provide
119 extension functionality.
120
121 When a client creates a registry object, the registry object
122 will emit a global event for each global currently in the
123 registry. Globals come and go as a result of device or
124 monitor hotplugs, reconfiguration or other events, and the
125 registry will send out global and global_remove events to
126 keep the client up to date with the changes. To mark the end
127 of the initial burst of events, the client can use the
128 wl_display.sync request immediately after calling
129 wl_display.get_registry.
130
131 A client can bind to a global object by using the bind
132 request. This creates a client-side handle that lets the object
133 emit events to the client and lets the client invoke requests on
134 the object.
135 </description>
136
137 <request name="bind">
138 <description summary="bind an object to the display">
139 Binds a new, client-created object to the server using the
140 specified name as the identifier.
141 </description>
142 <arg name="name" type="uint" summary="unique numeric name of the object"/>
143 <arg name="id" type="new_id" summary="bounded object"/>
144 </request>
145
146 <event name="global">
147 <description summary="announce global object">
148 Notify the client of global objects.
149
150 The event notifies the client that a global object with
151 the given name is now available, and it implements the
152 given version of the given interface.
153 </description>
154 <arg name="name" type="uint" summary="numeric name of the global object"/>
155 <arg name="interface" type="string" summary="interface implemented by the object"/>
156 <arg name="version" type="uint" summary="interface version"/>
157 </event>
158
159 <event name="global_remove">
160 <description summary="announce removal of global object">
161 Notify the client of removed global objects.
162
163 This event notifies the client that the global identified
164 by name is no longer available. If the client bound to
165 the global using the bind request, the client should now
166 destroy that object.
167
168 The object remains valid and requests to the object will be
169 ignored until the client destroys it, to avoid races between
170 the global going away and a client sending a request to it.
171 </description>
172 <arg name="name" type="uint" summary="numeric name of the global object"/>
173 </event>
174 </interface>
175
176 <interface name="wl_callback" version="1">
177 <description summary="callback object">
178 Clients can handle the 'done' event to get notified when
179 the related request is done.
180
181 Note, because wl_callback objects are created from multiple independent
182 factory interfaces, the wl_callback interface is frozen at version 1.
183 </description>
184
185 <event name="done" type="destructor">
186 <description summary="done event">
187 Notify the client when the related request is done.
188 </description>
189 <arg name="callback_data" type="uint" summary="request-specific data for the callback"/>
190 </event>
191 </interface>
192
193 <interface name="wl_compositor" version="6">
194 <description summary="the compositor singleton">
195 A compositor. This object is a singleton global. The
196 compositor is in charge of combining the contents of multiple
197 surfaces into one displayable output.
198 </description>
199
200 <request name="create_surface">
201 <description summary="create new surface">
202 Ask the compositor to create a new surface.
203 </description>
204 <arg name="id" type="new_id" interface="wl_surface" summary="the new surface"/>
205 </request>
206
207 <request name="create_region">
208 <description summary="create new region">
209 Ask the compositor to create a new region.
210 </description>
211 <arg name="id" type="new_id" interface="wl_region" summary="the new region"/>
212 </request>
213 </interface>
214
215 <interface name="wl_shm_pool" version="1">
216 <description summary="a shared memory pool">
217 The wl_shm_pool object encapsulates a piece of memory shared
218 between the compositor and client. Through the wl_shm_pool
219 object, the client can allocate shared memory wl_buffer objects.
220 All objects created through the same pool share the same
221 underlying mapped memory. Reusing the mapped memory avoids the
222 setup/teardown overhead and is useful when interactively resizing
223 a surface or for many small buffers.
224 </description>
225
226 <request name="create_buffer">
227 <description summary="create a buffer from the pool">
228 Create a wl_buffer object from the pool.
229
230 The buffer is created offset bytes into the pool and has
231 width and height as specified. The stride argument specifies
232 the number of bytes from the beginning of one row to the beginning
233 of the next. The format is the pixel format of the buffer and
234 must be one of those advertised through the wl_shm.format event.
235
236 A buffer will keep a reference to the pool it was created from
237 so it is valid to destroy the pool immediately after creating
238 a buffer from it.
239 </description>
240 <arg name="id" type="new_id" interface="wl_buffer" summary="buffer to create"/>
241 <arg name="offset" type="int" summary="buffer byte offset within the pool"/>
242 <arg name="width" type="int" summary="buffer width, in pixels"/>
243 <arg name="height" type="int" summary="buffer height, in pixels"/>
244 <arg name="stride" type="int" summary="number of bytes from the beginning of one row to the beginning of the next row"/>
245 <arg name="format" type="uint" enum="wl_shm.format" summary="buffer pixel format"/>
246 </request>
247
248 <request name="destroy" type="destructor">
249 <description summary="destroy the pool">
250 Destroy the shared memory pool.
251
252 The mmapped memory will be released when all
253 buffers that have been created from this pool
254 are gone.
255 </description>
256 </request>
257
258 <request name="resize">
259 <description summary="change the size of the pool mapping">
260 This request will cause the server to remap the backing memory
261 for the pool from the file descriptor passed when the pool was
262 created, but using the new size. This request can only be
263 used to make the pool bigger.
264
265 This request only changes the amount of bytes that are mmapped
266 by the server and does not touch the file corresponding to the
267 file descriptor passed at creation time. It is the client's
268 responsibility to ensure that the file is at least as big as
269 the new pool size.
270 </description>
271 <arg name="size" type="int" summary="new size of the pool, in bytes"/>
272 </request>
273 </interface>
274
275 <interface name="wl_shm" version="1">
276 <description summary="shared memory support">
277 A singleton global object that provides support for shared
278 memory.
279
280 Clients can create wl_shm_pool objects using the create_pool
281 request.
282
283 On binding the wl_shm object one or more format events
284 are emitted to inform clients about the valid pixel formats
285 that can be used for buffers.
286 </description>
287
288 <enum name="error">
289 <description summary="wl_shm error values">
290 These errors can be emitted in response to wl_shm requests.
291 </description>
292 <entry name="invalid_format" value="0" summary="buffer format is not known"/>
293 <entry name="invalid_stride" value="1" summary="invalid size or stride during pool or buffer creation"/>
294 <entry name="invalid_fd" value="2" summary="mmapping the file descriptor failed"/>
295 </enum>
296
297 <enum name="format">
298 <description summary="pixel formats">
299 This describes the memory layout of an individual pixel.
300
301 All renderers should support argb8888 and xrgb8888 but any other
302 formats are optional and may not be supported by the particular
303 renderer in use.
304
305 The drm format codes match the macros defined in drm_fourcc.h, except
306 argb8888 and xrgb8888. The formats actually supported by the compositor
307 will be reported by the format event.
308
309 For all wl_shm formats and unless specified in another protocol
310 extension, pre-multiplied alpha is used for pixel values.
311 </description>
312 <!-- Note to protocol writers: don't update this list manually, instead
313 run the automated script that keeps it in sync with drm_fourcc.h. -->
314 <entry name="argb8888" value="0" summary="32-bit ARGB format, [31:0] A:R:G:B 8:8:8:8 little endian"/>
315 <entry name="xrgb8888" value="1" summary="32-bit RGB format, [31:0] x:R:G:B 8:8:8:8 little endian"/>
316 <entry name="c8" value="0x20203843" summary="8-bit color index format, [7:0] C"/>
317 <entry name="rgb332" value="0x38424752" summary="8-bit RGB format, [7:0] R:G:B 3:3:2"/>
318 <entry name="bgr233" value="0x38524742" summary="8-bit BGR format, [7:0] B:G:R 2:3:3"/>
319 <entry name="xrgb4444" value="0x32315258" summary="16-bit xRGB format, [15:0] x:R:G:B 4:4:4:4 little endian"/>
320 <entry name="xbgr4444" value="0x32314258" summary="16-bit xBGR format, [15:0] x:B:G:R 4:4:4:4 little endian"/>
321 <entry name="rgbx4444" value="0x32315852" summary="16-bit RGBx format, [15:0] R:G:B:x 4:4:4:4 little endian"/>
322 <entry name="bgrx4444" value="0x32315842" summary="16-bit BGRx format, [15:0] B:G:R:x 4:4:4:4 little endian"/>
323 <entry name="argb4444" value="0x32315241" summary="16-bit ARGB format, [15:0] A:R:G:B 4:4:4:4 little endian"/>
324 <entry name="abgr4444" value="0x32314241" summary="16-bit ABGR format, [15:0] A:B:G:R 4:4:4:4 little endian"/>
325 <entry name="rgba4444" value="0x32314152" summary="16-bit RBGA format, [15:0] R:G:B:A 4:4:4:4 little endian"/>
326 <entry name="bgra4444" value="0x32314142" summary="16-bit BGRA format, [15:0] B:G:R:A 4:4:4:4 little endian"/>
327 <entry name="xrgb1555" value="0x35315258" summary="16-bit xRGB format, [15:0] x:R:G:B 1:5:5:5 little endian"/>
328 <entry name="xbgr1555" value="0x35314258" summary="16-bit xBGR 1555 format, [15:0] x:B:G:R 1:5:5:5 little endian"/>
329 <entry name="rgbx5551" value="0x35315852" summary="16-bit RGBx 5551 format, [15:0] R:G:B:x 5:5:5:1 little endian"/>
330 <entry name="bgrx5551" value="0x35315842" summary="16-bit BGRx 5551 format, [15:0] B:G:R:x 5:5:5:1 little endian"/>
331 <entry name="argb1555" value="0x35315241" summary="16-bit ARGB 1555 format, [15:0] A:R:G:B 1:5:5:5 little endian"/>
332 <entry name="abgr1555" value="0x35314241" summary="16-bit ABGR 1555 format, [15:0] A:B:G:R 1:5:5:5 little endian"/>
333 <entry name="rgba5551" value="0x35314152" summary="16-bit RGBA 5551 format, [15:0] R:G:B:A 5:5:5:1 little endian"/>
334 <entry name="bgra5551" value="0x35314142" summary="16-bit BGRA 5551 format, [15:0] B:G:R:A 5:5:5:1 little endian"/>
335 <entry name="rgb565" value="0x36314752" summary="16-bit RGB 565 format, [15:0] R:G:B 5:6:5 little endian"/>
336 <entry name="bgr565" value="0x36314742" summary="16-bit BGR 565 format, [15:0] B:G:R 5:6:5 little endian"/>
337 <entry name="rgb888" value="0x34324752" summary="24-bit RGB format, [23:0] R:G:B little endian"/>
338 <entry name="bgr888" value="0x34324742" summary="24-bit BGR format, [23:0] B:G:R little endian"/>
339 <entry name="xbgr8888" value="0x34324258" summary="32-bit xBGR format, [31:0] x:B:G:R 8:8:8:8 little endian"/>
340 <entry name="rgbx8888" value="0x34325852" summary="32-bit RGBx format, [31:0] R:G:B:x 8:8:8:8 little endian"/>
341 <entry name="bgrx8888" value="0x34325842" summary="32-bit BGRx format, [31:0] B:G:R:x 8:8:8:8 little endian"/>
342 <entry name="abgr8888" value="0x34324241" summary="32-bit ABGR format, [31:0] A:B:G:R 8:8:8:8 little endian"/>
343 <entry name="rgba8888" value="0x34324152" summary="32-bit RGBA format, [31:0] R:G:B:A 8:8:8:8 little endian"/>
344 <entry name="bgra8888" value="0x34324142" summary="32-bit BGRA format, [31:0] B:G:R:A 8:8:8:8 little endian"/>
345 <entry name="xrgb2101010" value="0x30335258" summary="32-bit xRGB format, [31:0] x:R:G:B 2:10:10:10 little endian"/>
346 <entry name="xbgr2101010" value="0x30334258" summary="32-bit xBGR format, [31:0] x:B:G:R 2:10:10:10 little endian"/>
347 <entry name="rgbx1010102" value="0x30335852" summary="32-bit RGBx format, [31:0] R:G:B:x 10:10:10:2 little endian"/>
348 <entry name="bgrx1010102" value="0x30335842" summary="32-bit BGRx format, [31:0] B:G:R:x 10:10:10:2 little endian"/>
349 <entry name="argb2101010" value="0x30335241" summary="32-bit ARGB format, [31:0] A:R:G:B 2:10:10:10 little endian"/>
350 <entry name="abgr2101010" value="0x30334241" summary="32-bit ABGR format, [31:0] A:B:G:R 2:10:10:10 little endian"/>
351 <entry name="rgba1010102" value="0x30334152" summary="32-bit RGBA format, [31:0] R:G:B:A 10:10:10:2 little endian"/>
352 <entry name="bgra1010102" value="0x30334142" summary="32-bit BGRA format, [31:0] B:G:R:A 10:10:10:2 little endian"/>
353 <entry name="yuyv" value="0x56595559" summary="packed YCbCr format, [31:0] Cr0:Y1:Cb0:Y0 8:8:8:8 little endian"/>
354 <entry name="yvyu" value="0x55595659" summary="packed YCbCr format, [31:0] Cb0:Y1:Cr0:Y0 8:8:8:8 little endian"/>
355 <entry name="uyvy" value="0x59565955" summary="packed YCbCr format, [31:0] Y1:Cr0:Y0:Cb0 8:8:8:8 little endian"/>
356 <entry name="vyuy" value="0x59555956" summary="packed YCbCr format, [31:0] Y1:Cb0:Y0:Cr0 8:8:8:8 little endian"/>
357 <entry name="ayuv" value="0x56555941" summary="packed AYCbCr format, [31:0] A:Y:Cb:Cr 8:8:8:8 little endian"/>
358 <entry name="nv12" value="0x3231564e" summary="2 plane YCbCr Cr:Cb format, 2x2 subsampled Cr:Cb plane"/>
359 <entry name="nv21" value="0x3132564e" summary="2 plane YCbCr Cb:Cr format, 2x2 subsampled Cb:Cr plane"/>
360 <entry name="nv16" value="0x3631564e" summary="2 plane YCbCr Cr:Cb format, 2x1 subsampled Cr:Cb plane"/>
361 <entry name="nv61" value="0x3136564e" summary="2 plane YCbCr Cb:Cr format, 2x1 subsampled Cb:Cr plane"/>
362 <entry name="yuv410" value="0x39565559" summary="3 plane YCbCr format, 4x4 subsampled Cb (1) and Cr (2) planes"/>
363 <entry name="yvu410" value="0x39555659" summary="3 plane YCbCr format, 4x4 subsampled Cr (1) and Cb (2) planes"/>
364 <entry name="yuv411" value="0x31315559" summary="3 plane YCbCr format, 4x1 subsampled Cb (1) and Cr (2) planes"/>
365 <entry name="yvu411" value="0x31315659" summary="3 plane YCbCr format, 4x1 subsampled Cr (1) and Cb (2) planes"/>
366 <entry name="yuv420" value="0x32315559" summary="3 plane YCbCr format, 2x2 subsampled Cb (1) and Cr (2) planes"/>
367 <entry name="yvu420" value="0x32315659" summary="3 plane YCbCr format, 2x2 subsampled Cr (1) and Cb (2) planes"/>
368 <entry name="yuv422" value="0x36315559" summary="3 plane YCbCr format, 2x1 subsampled Cb (1) and Cr (2) planes"/>
369 <entry name="yvu422" value="0x36315659" summary="3 plane YCbCr format, 2x1 subsampled Cr (1) and Cb (2) planes"/>
370 <entry name="yuv444" value="0x34325559" summary="3 plane YCbCr format, non-subsampled Cb (1) and Cr (2) planes"/>
371 <entry name="yvu444" value="0x34325659" summary="3 plane YCbCr format, non-subsampled Cr (1) and Cb (2) planes"/>
372 <entry name="r8" value="0x20203852" summary="[7:0] R"/>
373 <entry name="r16" value="0x20363152" summary="[15:0] R little endian"/>
374 <entry name="rg88" value="0x38384752" summary="[15:0] R:G 8:8 little endian"/>
375 <entry name="gr88" value="0x38385247" summary="[15:0] G:R 8:8 little endian"/>
376 <entry name="rg1616" value="0x32334752" summary="[31:0] R:G 16:16 little endian"/>
377 <entry name="gr1616" value="0x32335247" summary="[31:0] G:R 16:16 little endian"/>
378 <entry name="xrgb16161616f" value="0x48345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
379 <entry name="xbgr16161616f" value="0x48344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
380 <entry name="argb16161616f" value="0x48345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
381 <entry name="abgr16161616f" value="0x48344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
382 <entry name="xyuv8888" value="0x56555958" summary="[31:0] X:Y:Cb:Cr 8:8:8:8 little endian"/>
383 <entry name="vuy888" value="0x34325556" summary="[23:0] Cr:Cb:Y 8:8:8 little endian"/>
384 <entry name="vuy101010" value="0x30335556" summary="Y followed by U then V, 10:10:10. Non-linear modifier only"/>
385 <entry name="y210" value="0x30313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 10:6:10:6:10:6:10:6 little endian per 2 Y pixels"/>
386 <entry name="y212" value="0x32313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 12:4:12:4:12:4:12:4 little endian per 2 Y pixels"/>
387 <entry name="y216" value="0x36313259" summary="[63:0] Cr0:Y1:Cb0:Y0 16:16:16:16 little endian per 2 Y pixels"/>
388 <entry name="y410" value="0x30313459" summary="[31:0] A:Cr:Y:Cb 2:10:10:10 little endian"/>
389 <entry name="y412" value="0x32313459" summary="[63:0] A:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
390 <entry name="y416" value="0x36313459" summary="[63:0] A:Cr:Y:Cb 16:16:16:16 little endian"/>
391 <entry name="xvyu2101010" value="0x30335658" summary="[31:0] X:Cr:Y:Cb 2:10:10:10 little endian"/>
392 <entry name="xvyu12_16161616" value="0x36335658" summary="[63:0] X:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
393 <entry name="xvyu16161616" value="0x38345658" summary="[63:0] X:Cr:Y:Cb 16:16:16:16 little endian"/>
394 <entry name="y0l0" value="0x304c3059" summary="[63:0] A3:A2:Y3:0:Cr0:0:Y2:0:A1:A0:Y1:0:Cb0:0:Y0:0 1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
395 <entry name="x0l0" value="0x304c3058" summary="[63:0] X3:X2:Y3:0:Cr0:0:Y2:0:X1:X0:Y1:0:Cb0:0:Y0:0 1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
396 <entry name="y0l2" value="0x324c3059" summary="[63:0] A3:A2:Y3:Cr0:Y2:A1:A0:Y1:Cb0:Y0 1:1:10:10:10:1:1:10:10:10 little endian"/>
397 <entry name="x0l2" value="0x324c3058" summary="[63:0] X3:X2:Y3:Cr0:Y2:X1:X0:Y1:Cb0:Y0 1:1:10:10:10:1:1:10:10:10 little endian"/>
398 <entry name="yuv420_8bit" value="0x38305559"/>
399 <entry name="yuv420_10bit" value="0x30315559"/>
400 <entry name="xrgb8888_a8" value="0x38415258"/>
401 <entry name="xbgr8888_a8" value="0x38414258"/>
402 <entry name="rgbx8888_a8" value="0x38415852"/>
403 <entry name="bgrx8888_a8" value="0x38415842"/>
404 <entry name="rgb888_a8" value="0x38413852"/>
405 <entry name="bgr888_a8" value="0x38413842"/>
406 <entry name="rgb565_a8" value="0x38413552"/>
407 <entry name="bgr565_a8" value="0x38413542"/>
408 <entry name="nv24" value="0x3432564e" summary="non-subsampled Cr:Cb plane"/>
409 <entry name="nv42" value="0x3234564e" summary="non-subsampled Cb:Cr plane"/>
410 <entry name="p210" value="0x30313250" summary="2x1 subsampled Cr:Cb plane, 10 bit per channel"/>
411 <entry name="p010" value="0x30313050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel"/>
412 <entry name="p012" value="0x32313050" summary="2x2 subsampled Cr:Cb plane 12 bits per channel"/>
413 <entry name="p016" value="0x36313050" summary="2x2 subsampled Cr:Cb plane 16 bits per channel"/>
414 <entry name="axbxgxrx106106106106" value="0x30314241" summary="[63:0] A:x:B:x:G:x:R:x 10:6:10:6:10:6:10:6 little endian"/>
415 <entry name="nv15" value="0x3531564e" summary="2x2 subsampled Cr:Cb plane"/>
416 <entry name="q410" value="0x30313451"/>
417 <entry name="q401" value="0x31303451"/>
418 <entry name="xrgb16161616" value="0x38345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
419 <entry name="xbgr16161616" value="0x38344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
420 <entry name="argb16161616" value="0x38345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
421 <entry name="abgr16161616" value="0x38344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
422 </enum>
423
424 <request name="create_pool">
425 <description summary="create a shm pool">
426 Create a new wl_shm_pool object.
427
428 The pool can be used to create shared memory based buffer
429 objects. The server will mmap size bytes of the passed file
430 descriptor, to use as backing memory for the pool.
431 </description>
432 <arg name="id" type="new_id" interface="wl_shm_pool" summary="pool to create"/>
433 <arg name="fd" type="fd" summary="file descriptor for the pool"/>
434 <arg name="size" type="int" summary="pool size, in bytes"/>
435 </request>
436
437 <event name="format">
438 <description summary="pixel format description">
439 Informs the client about a valid pixel format that
440 can be used for buffers. Known formats include
441 argb8888 and xrgb8888.
442 </description>
443 <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
444 </event>
445 </interface>
446
447 <interface name="wl_buffer" version="1">
448 <description summary="content for a wl_surface">
449 A buffer provides the content for a wl_surface. Buffers are
450 created through factory interfaces such as wl_shm, wp_linux_buffer_params
451 (from the linux-dmabuf protocol extension) or similar. It has a width and
452 a height and can be attached to a wl_surface, but the mechanism by which a
453 client provides and updates the contents is defined by the buffer factory
454 interface.
455
456 If the buffer uses a format that has an alpha channel, the alpha channel
457 is assumed to be premultiplied in the color channels unless otherwise
458 specified.
459
460 Note, because wl_buffer objects are created from multiple independent
461 factory interfaces, the wl_buffer interface is frozen at version 1.
462 </description>
463
464 <request name="destroy" type="destructor">
465 <description summary="destroy a buffer">
466 Destroy a buffer. If and how you need to release the backing
467 storage is defined by the buffer factory interface.
468
469 For possible side-effects to a surface, see wl_surface.attach.
470 </description>
471 </request>
472
473 <event name="release">
474 <description summary="compositor releases buffer">
475 Sent when this wl_buffer is no longer used by the compositor.
476 The client is now free to reuse or destroy this buffer and its
477 backing storage.
478
479 If a client receives a release event before the frame callback
480 requested in the same wl_surface.commit that attaches this
481 wl_buffer to a surface, then the client is immediately free to
482 reuse the buffer and its backing storage, and does not need a
483 second buffer for the next surface content update. Typically
484 this is possible, when the compositor maintains a copy of the
485 wl_surface contents, e.g. as a GL texture. This is an important
486 optimization for GL(ES) compositors with wl_shm clients.
487 </description>
488 </event>
489 </interface>
490
491 <interface name="wl_data_offer" version="3">
492 <description summary="offer to transfer data">
493 A wl_data_offer represents a piece of data offered for transfer
494 by another client (the source client). It is used by the
495 copy-and-paste and drag-and-drop mechanisms. The offer
496 describes the different mime types that the data can be
497 converted to and provides the mechanism for transferring the
498 data directly from the source client.
499 </description>
500
501 <enum name="error">
502 <entry name="invalid_finish" value="0"
503 summary="finish request was called untimely"/>
504 <entry name="invalid_action_mask" value="1"
505 summary="action mask contains invalid values"/>
506 <entry name="invalid_action" value="2"
507 summary="action argument has an invalid value"/>
508 <entry name="invalid_offer" value="3"
509 summary="offer doesn't accept this request"/>
510 </enum>
511
512 <request name="accept">
513 <description summary="accept one of the offered mime types">
514 Indicate that the client can accept the given mime type, or
515 NULL for not accepted.
516
517 For objects of version 2 or older, this request is used by the
518 client to give feedback whether the client can receive the given
519 mime type, or NULL if none is accepted; the feedback does not
520 determine whether the drag-and-drop operation succeeds or not.
521
522 For objects of version 3 or newer, this request determines the
523 final result of the drag-and-drop operation. If the end result
524 is that no mime types were accepted, the drag-and-drop operation
525 will be cancelled and the corresponding drag source will receive
526 wl_data_source.cancelled. Clients may still use this event in
527 conjunction with wl_data_source.action for feedback.
528 </description>
529 <arg name="serial" type="uint" summary="serial number of the accept request"/>
530 <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the client"/>
531 </request>
532
533 <request name="receive">
534 <description summary="request that the data is transferred">
535 To transfer the offered data, the client issues this request
536 and indicates the mime type it wants to receive. The transfer
537 happens through the passed file descriptor (typically created
538 with the pipe system call). The source client writes the data
539 in the mime type representation requested and then closes the
540 file descriptor.
541
542 The receiving client reads from the read end of the pipe until
543 EOF and then closes its end, at which point the transfer is
544 complete.
545
546 This request may happen multiple times for different mime types,
547 both before and after wl_data_device.drop. Drag-and-drop destination
548 clients may preemptively fetch data or examine it more closely to
549 determine acceptance.
550 </description>
551 <arg name="mime_type" type="string" summary="mime type desired by receiver"/>
552 <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
553 </request>
554
555 <request name="destroy" type="destructor">
556 <description summary="destroy data offer">
557 Destroy the data offer.
558 </description>
559 </request>
560
561 <event name="offer">
562 <description summary="advertise offered mime type">
563 Sent immediately after creating the wl_data_offer object. One
564 event per offered mime type.
565 </description>
566 <arg name="mime_type" type="string" summary="offered mime type"/>
567 </event>
568
569 <!-- Version 3 additions -->
570
571 <request name="finish" since="3">
572 <description summary="the offer will no longer be used">
573 Notifies the compositor that the drag destination successfully
574 finished the drag-and-drop operation.
575
576 Upon receiving this request, the compositor will emit
577 wl_data_source.dnd_finished on the drag source client.
578
579 It is a client error to perform other requests than
580 wl_data_offer.destroy after this one. It is also an error to perform
581 this request after a NULL mime type has been set in
582 wl_data_offer.accept or no action was received through
583 wl_data_offer.action.
584
585 If wl_data_offer.finish request is received for a non drag and drop
586 operation, the invalid_finish protocol error is raised.
587 </description>
588 </request>
589
590 <request name="set_actions" since="3">
591 <description summary="set the available/preferred drag-and-drop actions">
592 Sets the actions that the destination side client supports for
593 this operation. This request may trigger the emission of
594 wl_data_source.action and wl_data_offer.action events if the compositor
595 needs to change the selected action.
596
597 This request can be called multiple times throughout the
598 drag-and-drop operation, typically in response to wl_data_device.enter
599 or wl_data_device.motion events.
600
601 This request determines the final result of the drag-and-drop
602 operation. If the end result is that no action is accepted,
603 the drag source will receive wl_data_source.cancelled.
604
605 The dnd_actions argument must contain only values expressed in the
606 wl_data_device_manager.dnd_actions enum, and the preferred_action
607 argument must only contain one of those values set, otherwise it
608 will result in a protocol error.
609
610 While managing an "ask" action, the destination drag-and-drop client
611 may perform further wl_data_offer.receive requests, and is expected
612 to perform one last wl_data_offer.set_actions request with a preferred
613 action other than "ask" (and optionally wl_data_offer.accept) before
614 requesting wl_data_offer.finish, in order to convey the action selected
615 by the user. If the preferred action is not in the
616 wl_data_offer.source_actions mask, an error will be raised.
617
618 If the "ask" action is dismissed (e.g. user cancellation), the client
619 is expected to perform wl_data_offer.destroy right away.
620
621 This request can only be made on drag-and-drop offers, a protocol error
622 will be raised otherwise.
623 </description>
624 <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"
625 enum="wl_data_device_manager.dnd_action"/>
626 <arg name="preferred_action" type="uint" summary="action preferred by the destination client"
627 enum="wl_data_device_manager.dnd_action"/>
628 </request>
629
630 <event name="source_actions" since="3">
631 <description summary="notify the source-side available actions">
632 This event indicates the actions offered by the data source. It
633 will be sent immediately after creating the wl_data_offer object,
634 or anytime the source side changes its offered actions through
635 wl_data_source.set_actions.
636 </description>
637 <arg name="source_actions" type="uint" summary="actions offered by the data source"
638 enum="wl_data_device_manager.dnd_action"/>
639 </event>
640
641 <event name="action" since="3">
642 <description summary="notify the selected action">
643 This event indicates the action selected by the compositor after
644 matching the source/destination side actions. Only one action (or
645 none) will be offered here.
646
647 This event can be emitted multiple times during the drag-and-drop
648 operation in response to destination side action changes through
649 wl_data_offer.set_actions.
650
651 This event will no longer be emitted after wl_data_device.drop
652 happened on the drag-and-drop destination, the client must
653 honor the last action received, or the last preferred one set
654 through wl_data_offer.set_actions when handling an "ask" action.
655
656 Compositors may also change the selected action on the fly, mainly
657 in response to keyboard modifier changes during the drag-and-drop
658 operation.
659
660 The most recent action received is always the valid one. Prior to
661 receiving wl_data_device.drop, the chosen action may change (e.g.
662 due to keyboard modifiers being pressed). At the time of receiving
663 wl_data_device.drop the drag-and-drop destination must honor the
664 last action received.
665
666 Action changes may still happen after wl_data_device.drop,
667 especially on "ask" actions, where the drag-and-drop destination
668 may choose another action afterwards. Action changes happening
669 at this stage are always the result of inter-client negotiation, the
670 compositor shall no longer be able to induce a different action.
671
672 Upon "ask" actions, it is expected that the drag-and-drop destination
673 may potentially choose a different action and/or mime type,
674 based on wl_data_offer.source_actions and finally chosen by the
675 user (e.g. popping up a menu with the available options). The
676 final wl_data_offer.set_actions and wl_data_offer.accept requests
677 must happen before the call to wl_data_offer.finish.
678 </description>
679 <arg name="dnd_action" type="uint" summary="action selected by the compositor"
680 enum="wl_data_device_manager.dnd_action"/>
681 </event>
682 </interface>
683
684 <interface name="wl_data_source" version="3">
685 <description summary="offer to transfer data">
686 The wl_data_source object is the source side of a wl_data_offer.
687 It is created by the source client in a data transfer and
688 provides a way to describe the offered data and a way to respond
689 to requests to transfer the data.
690 </description>
691
692 <enum name="error">
693 <entry name="invalid_action_mask" value="0"
694 summary="action mask contains invalid values"/>
695 <entry name="invalid_source" value="1"
696 summary="source doesn't accept this request"/>
697 </enum>
698
699 <request name="offer">
700 <description summary="add an offered mime type">
701 This request adds a mime type to the set of mime types
702 advertised to targets. Can be called several times to offer
703 multiple types.
704 </description>
705 <arg name="mime_type" type="string" summary="mime type offered by the data source"/>
706 </request>
707
708 <request name="destroy" type="destructor">
709 <description summary="destroy the data source">
710 Destroy the data source.
711 </description>
712 </request>
713
714 <event name="target">
715 <description summary="a target accepts an offered mime type">
716 Sent when a target accepts pointer_focus or motion events. If
717 a target does not accept any of the offered types, type is NULL.
718
719 Used for feedback during drag-and-drop.
720 </description>
721 <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the target"/>
722 </event>
723
724 <event name="send">
725 <description summary="send the data">
726 Request for data from the client. Send the data as the
727 specified mime type over the passed file descriptor, then
728 close it.
729 </description>
730 <arg name="mime_type" type="string" summary="mime type for the data"/>
731 <arg name="fd" type="fd" summary="file descriptor for the data"/>
732 </event>
733
734 <event name="cancelled">
735 <description summary="selection was cancelled">
736 This data source is no longer valid. There are several reasons why
737 this could happen:
738
739 - The data source has been replaced by another data source.
740 - The drag-and-drop operation was performed, but the drop destination
741 did not accept any of the mime types offered through
742 wl_data_source.target.
743 - The drag-and-drop operation was performed, but the drop destination
744 did not select any of the actions present in the mask offered through
745 wl_data_source.action.
746 - The drag-and-drop operation was performed but didn't happen over a
747 surface.
748 - The compositor cancelled the drag-and-drop operation (e.g. compositor
749 dependent timeouts to avoid stale drag-and-drop transfers).
750
751 The client should clean up and destroy this data source.
752
753 For objects of version 2 or older, wl_data_source.cancelled will
754 only be emitted if the data source was replaced by another data
755 source.
756 </description>
757 </event>
758
759 <!-- Version 3 additions -->
760
761 <request name="set_actions" since="3">
762 <description summary="set the available drag-and-drop actions">
763 Sets the actions that the source side client supports for this
764 operation. This request may trigger wl_data_source.action and
765 wl_data_offer.action events if the compositor needs to change the
766 selected action.
767
768 The dnd_actions argument must contain only values expressed in the
769 wl_data_device_manager.dnd_actions enum, otherwise it will result
770 in a protocol error.
771
772 This request must be made once only, and can only be made on sources
773 used in drag-and-drop, so it must be performed before
774 wl_data_device.start_drag. Attempting to use the source other than
775 for drag-and-drop will raise a protocol error.
776 </description>
777 <arg name="dnd_actions" type="uint" summary="actions supported by the data source"
778 enum="wl_data_device_manager.dnd_action"/>
779 </request>
780
781 <event name="dnd_drop_performed" since="3">
782 <description summary="the drag-and-drop operation physically finished">
783 The user performed the drop action. This event does not indicate
784 acceptance, wl_data_source.cancelled may still be emitted afterwards
785 if the drop destination does not accept any mime type.
786
787 However, this event might however not be received if the compositor
788 cancelled the drag-and-drop operation before this event could happen.
789
790 Note that the data_source may still be used in the future and should
791 not be destroyed here.
792 </description>
793 </event>
794
795 <event name="dnd_finished" since="3">
796 <description summary="the drag-and-drop operation concluded">
797 The drop destination finished interoperating with this data
798 source, so the client is now free to destroy this data source and
799 free all associated data.
800
801 If the action used to perform the operation was "move", the
802 source can now delete the transferred data.
803 </description>
804 </event>
805
806 <event name="action" since="3">
807 <description summary="notify the selected action">
808 This event indicates the action selected by the compositor after
809 matching the source/destination side actions. Only one action (or
810 none) will be offered here.
811
812 This event can be emitted multiple times during the drag-and-drop
813 operation, mainly in response to destination side changes through
814 wl_data_offer.set_actions, and as the data device enters/leaves
815 surfaces.
816
817 It is only possible to receive this event after
818 wl_data_source.dnd_drop_performed if the drag-and-drop operation
819 ended in an "ask" action, in which case the final wl_data_source.action
820 event will happen immediately before wl_data_source.dnd_finished.
821
822 Compositors may also change the selected action on the fly, mainly
823 in response to keyboard modifier changes during the drag-and-drop
824 operation.
825
826 The most recent action received is always the valid one. The chosen
827 action may change alongside negotiation (e.g. an "ask" action can turn
828 into a "move" operation), so the effects of the final action must
829 always be applied in wl_data_offer.dnd_finished.
830
831 Clients can trigger cursor surface changes from this point, so
832 they reflect the current action.
833 </description>
834 <arg name="dnd_action" type="uint" summary="action selected by the compositor"
835 enum="wl_data_device_manager.dnd_action"/>
836 </event>
837 </interface>
838
839 <interface name="wl_data_device" version="3">
840 <description summary="data transfer device">
841 There is one wl_data_device per seat which can be obtained
842 from the global wl_data_device_manager singleton.
843
844 A wl_data_device provides access to inter-client data transfer
845 mechanisms such as copy-and-paste and drag-and-drop.
846 </description>
847
848 <enum name="error">
849 <entry name="role" value="0" summary="given wl_surface has another role"/>
850 </enum>
851
852 <request name="start_drag">
853 <description summary="start drag-and-drop operation">
854 This request asks the compositor to start a drag-and-drop
855 operation on behalf of the client.
856
857 The source argument is the data source that provides the data
858 for the eventual data transfer. If source is NULL, enter, leave
859 and motion events are sent only to the client that initiated the
860 drag and the client is expected to handle the data passing
861 internally. If source is destroyed, the drag-and-drop session will be
862 cancelled.
863
864 The origin surface is the surface where the drag originates and
865 the client must have an active implicit grab that matches the
866 serial.
867
868 The icon surface is an optional (can be NULL) surface that
869 provides an icon to be moved around with the cursor. Initially,
870 the top-left corner of the icon surface is placed at the cursor
871 hotspot, but subsequent wl_surface.attach request can move the
872 relative position. Attach requests must be confirmed with
873 wl_surface.commit as usual. The icon surface is given the role of
874 a drag-and-drop icon. If the icon surface already has another role,
875 it raises a protocol error.
876
877 The input region is ignored for wl_surfaces with the role of a
878 drag-and-drop icon.
879 </description>
880 <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the eventual transfer"/>
881 <arg name="origin" type="object" interface="wl_surface" summary="surface where the drag originates"/>
882 <arg name="icon" type="object" interface="wl_surface" allow-null="true" summary="drag-and-drop icon surface"/>
883 <arg name="serial" type="uint" summary="serial number of the implicit grab on the origin"/>
884 </request>
885
886 <request name="set_selection">
887 <description summary="copy data to the selection">
888 This request asks the compositor to set the selection
889 to the data from the source on behalf of the client.
890
891 To unset the selection, set the source to NULL.
892 </description>
893 <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the selection"/>
894 <arg name="serial" type="uint" summary="serial number of the event that triggered this request"/>
895 </request>
896
897 <event name="data_offer">
898 <description summary="introduce a new wl_data_offer">
899 The data_offer event introduces a new wl_data_offer object,
900 which will subsequently be used in either the
901 data_device.enter event (for drag-and-drop) or the
902 data_device.selection event (for selections). Immediately
903 following the data_device.data_offer event, the new data_offer
904 object will send out data_offer.offer events to describe the
905 mime types it offers.
906 </description>
907 <arg name="id" type="new_id" interface="wl_data_offer" summary="the new data_offer object"/>
908 </event>
909
910 <event name="enter">
911 <description summary="initiate drag-and-drop session">
912 This event is sent when an active drag-and-drop pointer enters
913 a surface owned by the client. The position of the pointer at
914 enter time is provided by the x and y arguments, in surface-local
915 coordinates.
916 </description>
917 <arg name="serial" type="uint" summary="serial number of the enter event"/>
918 <arg name="surface" type="object" interface="wl_surface" summary="client surface entered"/>
919 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
920 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
921 <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
922 summary="source data_offer object"/>
923 </event>
924
925 <event name="leave">
926 <description summary="end drag-and-drop session">
927 This event is sent when the drag-and-drop pointer leaves the
928 surface and the session ends. The client must destroy the
929 wl_data_offer introduced at enter time at this point.
930 </description>
931 </event>
932
933 <event name="motion">
934 <description summary="drag-and-drop session motion">
935 This event is sent when the drag-and-drop pointer moves within
936 the currently focused surface. The new position of the pointer
937 is provided by the x and y arguments, in surface-local
938 coordinates.
939 </description>
940 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
941 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
942 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
943 </event>
944
945 <event name="drop">
946 <description summary="end drag-and-drop session successfully">
947 The event is sent when a drag-and-drop operation is ended
948 because the implicit grab is removed.
949
950 The drag-and-drop destination is expected to honor the last action
951 received through wl_data_offer.action, if the resulting action is
952 "copy" or "move", the destination can still perform
953 wl_data_offer.receive requests, and is expected to end all
954 transfers with a wl_data_offer.finish request.
955
956 If the resulting action is "ask", the action will not be considered
957 final. The drag-and-drop destination is expected to perform one last
958 wl_data_offer.set_actions request, or wl_data_offer.destroy in order
959 to cancel the operation.
960 </description>
961 </event>
962
963 <event name="selection">
964 <description summary="advertise new selection">
965 The selection event is sent out to notify the client of a new
966 wl_data_offer for the selection for this device. The
967 data_device.data_offer and the data_offer.offer events are
968 sent out immediately before this event to introduce the data
969 offer object. The selection event is sent to a client
970 immediately before receiving keyboard focus and when a new
971 selection is set while the client has keyboard focus. The
972 data_offer is valid until a new data_offer or NULL is received
973 or until the client loses keyboard focus. Switching surface with
974 keyboard focus within the same client doesn't mean a new selection
975 will be sent. The client must destroy the previous selection
976 data_offer, if any, upon receiving this event.
977 </description>
978 <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
979 summary="selection data_offer object"/>
980 </event>
981
982 <!-- Version 2 additions -->
983
984 <request name="release" type="destructor" since="2">
985 <description summary="destroy data device">
986 This request destroys the data device.
987 </description>
988 </request>
989 </interface>
990
991 <interface name="wl_data_device_manager" version="3">
992 <description summary="data transfer interface">
993 The wl_data_device_manager is a singleton global object that
994 provides access to inter-client data transfer mechanisms such as
995 copy-and-paste and drag-and-drop. These mechanisms are tied to
996 a wl_seat and this interface lets a client get a wl_data_device
997 corresponding to a wl_seat.
998
999 Depending on the version bound, the objects created from the bound
1000 wl_data_device_manager object will have different requirements for
1001 functioning properly. See wl_data_source.set_actions,
1002 wl_data_offer.accept and wl_data_offer.finish for details.
1003 </description>
1004
1005 <request name="create_data_source">
1006 <description summary="create a new data source">
1007 Create a new data source.
1008 </description>
1009 <arg name="id" type="new_id" interface="wl_data_source" summary="data source to create"/>
1010 </request>
1011
1012 <request name="get_data_device">
1013 <description summary="create a new data device">
1014 Create a new data device for a given seat.
1015 </description>
1016 <arg name="id" type="new_id" interface="wl_data_device" summary="data device to create"/>
1017 <arg name="seat" type="object" interface="wl_seat" summary="seat associated with the data device"/>
1018 </request>
1019
1020 <!-- Version 3 additions -->
1021
1022 <enum name="dnd_action" bitfield="true" since="3">
1023 <description summary="drag and drop actions">
1024 This is a bitmask of the available/preferred actions in a
1025 drag-and-drop operation.
1026
1027 In the compositor, the selected action is a result of matching the
1028 actions offered by the source and destination sides. "action" events
1029 with a "none" action will be sent to both source and destination if
1030 there is no match. All further checks will effectively happen on
1031 (source actions ∩ destination actions).
1032
1033 In addition, compositors may also pick different actions in
1034 reaction to key modifiers being pressed. One common design that
1035 is used in major toolkits (and the behavior recommended for
1036 compositors) is:
1037
1038 - If no modifiers are pressed, the first match (in bit order)
1039 will be used.
1040 - Pressing Shift selects "move", if enabled in the mask.
1041 - Pressing Control selects "copy", if enabled in the mask.
1042
1043 Behavior beyond that is considered implementation-dependent.
1044 Compositors may for example bind other modifiers (like Alt/Meta)
1045 or drags initiated with other buttons than BTN_LEFT to specific
1046 actions (e.g. "ask").
1047 </description>
1048 <entry name="none" value="0" summary="no action"/>
1049 <entry name="copy" value="1" summary="copy action"/>
1050 <entry name="move" value="2" summary="move action"/>
1051 <entry name="ask" value="4" summary="ask action"/>
1052 </enum>
1053 </interface>
1054
1055 <interface name="wl_shell" version="1">
1056 <description summary="create desktop-style surfaces">
1057 This interface is implemented by servers that provide
1058 desktop-style user interfaces.
1059
1060 It allows clients to associate a wl_shell_surface with
1061 a basic surface.
1062
1063 Note! This protocol is deprecated and not intended for production use.
1064 For desktop-style user interfaces, use xdg_shell. Compositors and clients
1065 should not implement this interface.
1066 </description>
1067
1068 <enum name="error">
1069 <entry name="role" value="0" summary="given wl_surface has another role"/>
1070 </enum>
1071
1072 <request name="get_shell_surface">
1073 <description summary="create a shell surface from a surface">
1074 Create a shell surface for an existing surface. This gives
1075 the wl_surface the role of a shell surface. If the wl_surface
1076 already has another role, it raises a protocol error.
1077
1078 Only one shell surface can be associated with a given surface.
1079 </description>
1080 <arg name="id" type="new_id" interface="wl_shell_surface" summary="shell surface to create"/>
1081 <arg name="surface" type="object" interface="wl_surface" summary="surface to be given the shell surface role"/>
1082 </request>
1083 </interface>
1084
1085 <interface name="wl_shell_surface" version="1">
1086 <description summary="desktop-style metadata interface">
1087 An interface that may be implemented by a wl_surface, for
1088 implementations that provide a desktop-style user interface.
1089
1090 It provides requests to treat surfaces like toplevel, fullscreen
1091 or popup windows, move, resize or maximize them, associate
1092 metadata like title and class, etc.
1093
1094 On the server side the object is automatically destroyed when
1095 the related wl_surface is destroyed. On the client side,
1096 wl_shell_surface_destroy() must be called before destroying
1097 the wl_surface object.
1098 </description>
1099
1100 <request name="pong">
1101 <description summary="respond to a ping event">
1102 A client must respond to a ping event with a pong request or
1103 the client may be deemed unresponsive.
1104 </description>
1105 <arg name="serial" type="uint" summary="serial number of the ping event"/>
1106 </request>
1107
1108 <request name="move">
1109 <description summary="start an interactive move">
1110 Start a pointer-driven move of the surface.
1111
1112 This request must be used in response to a button press event.
1113 The server may ignore move requests depending on the state of
1114 the surface (e.g. fullscreen or maximized).
1115 </description>
1116 <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1117 <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1118 </request>
1119
1120 <enum name="resize" bitfield="true">
1121 <description summary="edge values for resizing">
1122 These values are used to indicate which edge of a surface
1123 is being dragged in a resize operation. The server may
1124 use this information to adapt its behavior, e.g. choose
1125 an appropriate cursor image.
1126 </description>
1127 <entry name="none" value="0" summary="no edge"/>
1128 <entry name="top" value="1" summary="top edge"/>
1129 <entry name="bottom" value="2" summary="bottom edge"/>
1130 <entry name="left" value="4" summary="left edge"/>
1131 <entry name="top_left" value="5" summary="top and left edges"/>
1132 <entry name="bottom_left" value="6" summary="bottom and left edges"/>
1133 <entry name="right" value="8" summary="right edge"/>
1134 <entry name="top_right" value="9" summary="top and right edges"/>
1135 <entry name="bottom_right" value="10" summary="bottom and right edges"/>
1136 </enum>
1137
1138 <request name="resize">
1139 <description summary="start an interactive resize">
1140 Start a pointer-driven resizing of the surface.
1141
1142 This request must be used in response to a button press event.
1143 The server may ignore resize requests depending on the state of
1144 the surface (e.g. fullscreen or maximized).
1145 </description>
1146 <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1147 <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1148 <arg name="edges" type="uint" enum="resize" summary="which edge or corner is being dragged"/>
1149 </request>
1150
1151 <request name="set_toplevel">
1152 <description summary="make the surface a toplevel surface">
1153 Map the surface as a toplevel surface.
1154
1155 A toplevel surface is not fullscreen, maximized or transient.
1156 </description>
1157 </request>
1158
1159 <enum name="transient" bitfield="true">
1160 <description summary="details of transient behaviour">
1161 These flags specify details of the expected behaviour
1162 of transient surfaces. Used in the set_transient request.
1163 </description>
1164 <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
1165 </enum>
1166
1167 <request name="set_transient">
1168 <description summary="make the surface a transient surface">
1169 Map the surface relative to an existing surface.
1170
1171 The x and y arguments specify the location of the upper left
1172 corner of the surface relative to the upper left corner of the
1173 parent surface, in surface-local coordinates.
1174
1175 The flags argument controls details of the transient behaviour.
1176 </description>
1177 <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1178 <arg name="x" type="int" summary="surface-local x coordinate"/>
1179 <arg name="y" type="int" summary="surface-local y coordinate"/>
1180 <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1181 </request>
1182
1183 <enum name="fullscreen_method">
1184 <description summary="different method to set the surface fullscreen">
1185 Hints to indicate to the compositor how to deal with a conflict
1186 between the dimensions of the surface and the dimensions of the
1187 output. The compositor is free to ignore this parameter.
1188 </description>
1189 <entry name="default" value="0" summary="no preference, apply default policy"/>
1190 <entry name="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/>
1191 <entry name="driver" value="2" summary="switch output mode to the smallest mode that can fit the surface, add black borders to compensate size mismatch"/>
1192 <entry name="fill" value="3" summary="no upscaling, center on output and add black borders to compensate size mismatch"/>
1193 </enum>
1194
1195 <request name="set_fullscreen">
1196 <description summary="make the surface a fullscreen surface">
1197 Map the surface as a fullscreen surface.
1198
1199 If an output parameter is given then the surface will be made
1200 fullscreen on that output. If the client does not specify the
1201 output then the compositor will apply its policy - usually
1202 choosing the output on which the surface has the biggest surface
1203 area.
1204
1205 The client may specify a method to resolve a size conflict
1206 between the output size and the surface size - this is provided
1207 through the method parameter.
1208
1209 The framerate parameter is used only when the method is set
1210 to "driver", to indicate the preferred framerate. A value of 0
1211 indicates that the client does not care about framerate. The
1212 framerate is specified in mHz, that is framerate of 60000 is 60Hz.
1213
1214 A method of "scale" or "driver" implies a scaling operation of
1215 the surface, either via a direct scaling operation or a change of
1216 the output mode. This will override any kind of output scaling, so
1217 that mapping a surface with a buffer size equal to the mode can
1218 fill the screen independent of buffer_scale.
1219
1220 A method of "fill" means we don't scale up the buffer, however
1221 any output scale is applied. This means that you may run into
1222 an edge case where the application maps a buffer with the same
1223 size of the output mode but buffer_scale 1 (thus making a
1224 surface larger than the output). In this case it is allowed to
1225 downscale the results to fit the screen.
1226
1227 The compositor must reply to this request with a configure event
1228 with the dimensions for the output on which the surface will
1229 be made fullscreen.
1230 </description>
1231 <arg name="method" type="uint" enum="fullscreen_method" summary="method for resolving size conflict"/>
1232 <arg name="framerate" type="uint" summary="framerate in mHz"/>
1233 <arg name="output" type="object" interface="wl_output" allow-null="true"
1234 summary="output on which the surface is to be fullscreen"/>
1235 </request>
1236
1237 <request name="set_popup">
1238 <description summary="make the surface a popup surface">
1239 Map the surface as a popup.
1240
1241 A popup surface is a transient surface with an added pointer
1242 grab.
1243
1244 An existing implicit grab will be changed to owner-events mode,
1245 and the popup grab will continue after the implicit grab ends
1246 (i.e. releasing the mouse button does not cause the popup to
1247 be unmapped).
1248
1249 The popup grab continues until the window is destroyed or a
1250 mouse button is pressed in any other client's window. A click
1251 in any of the client's surfaces is reported as normal, however,
1252 clicks in other clients' surfaces will be discarded and trigger
1253 the callback.
1254
1255 The x and y arguments specify the location of the upper left
1256 corner of the surface relative to the upper left corner of the
1257 parent surface, in surface-local coordinates.
1258 </description>
1259 <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1260 <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1261 <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1262 <arg name="x" type="int" summary="surface-local x coordinate"/>
1263 <arg name="y" type="int" summary="surface-local y coordinate"/>
1264 <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1265 </request>
1266
1267 <request name="set_maximized">
1268 <description summary="make the surface a maximized surface">
1269 Map the surface as a maximized surface.
1270
1271 If an output parameter is given then the surface will be
1272 maximized on that output. If the client does not specify the
1273 output then the compositor will apply its policy - usually
1274 choosing the output on which the surface has the biggest surface
1275 area.
1276
1277 The compositor will reply with a configure event telling
1278 the expected new surface size. The operation is completed
1279 on the next buffer attach to this surface.
1280
1281 A maximized surface typically fills the entire output it is
1282 bound to, except for desktop elements such as panels. This is
1283 the main difference between a maximized shell surface and a
1284 fullscreen shell surface.
1285
1286 The details depend on the compositor implementation.
1287 </description>
1288 <arg name="output" type="object" interface="wl_output" allow-null="true"
1289 summary="output on which the surface is to be maximized"/>
1290 </request>
1291
1292 <request name="set_title">
1293 <description summary="set surface title">
1294 Set a short title for the surface.
1295
1296 This string may be used to identify the surface in a task bar,
1297 window list, or other user interface elements provided by the
1298 compositor.
1299
1300 The string must be encoded in UTF-8.
1301 </description>
1302 <arg name="title" type="string" summary="surface title"/>
1303 </request>
1304
1305 <request name="set_class">
1306 <description summary="set surface class">
1307 Set a class for the surface.
1308
1309 The surface class identifies the general class of applications
1310 to which the surface belongs. A common convention is to use the
1311 file name (or the full path if it is a non-standard location) of
1312 the application's .desktop file as the class.
1313 </description>
1314 <arg name="class_" type="string" summary="surface class"/>
1315 </request>
1316
1317 <event name="ping">
1318 <description summary="ping client">
1319 Ping a client to check if it is receiving events and sending
1320 requests. A client is expected to reply with a pong request.
1321 </description>
1322 <arg name="serial" type="uint" summary="serial number of the ping"/>
1323 </event>
1324
1325 <event name="configure">
1326 <description summary="suggest resize">
1327 The configure event asks the client to resize its surface.
1328
1329 The size is a hint, in the sense that the client is free to
1330 ignore it if it doesn't resize, pick a smaller size (to
1331 satisfy aspect ratio or resize in steps of NxM pixels).
1332
1333 The edges parameter provides a hint about how the surface
1334 was resized. The client may use this information to decide
1335 how to adjust its content to the new size (e.g. a scrolling
1336 area might adjust its content position to leave the viewable
1337 content unmoved).
1338
1339 The client is free to dismiss all but the last configure
1340 event it received.
1341
1342 The width and height arguments specify the size of the window
1343 in surface-local coordinates.
1344 </description>
1345 <arg name="edges" type="uint" enum="resize" summary="how the surface was resized"/>
1346 <arg name="width" type="int" summary="new width of the surface"/>
1347 <arg name="height" type="int" summary="new height of the surface"/>
1348 </event>
1349
1350 <event name="popup_done">
1351 <description summary="popup interaction is done">
1352 The popup_done event is sent out when a popup grab is broken,
1353 that is, when the user clicks a surface that doesn't belong
1354 to the client owning the popup surface.
1355 </description>
1356 </event>
1357 </interface>
1358
1359 <interface name="wl_surface" version="6">
1360 <description summary="an onscreen surface">
1361 A surface is a rectangular area that may be displayed on zero
1362 or more outputs, and shown any number of times at the compositor's
1363 discretion. They can present wl_buffers, receive user input, and
1364 define a local coordinate system.
1365
1366 The size of a surface (and relative positions on it) is described
1367 in surface-local coordinates, which may differ from the buffer
1368 coordinates of the pixel content, in case a buffer_transform
1369 or a buffer_scale is used.
1370
1371 A surface without a "role" is fairly useless: a compositor does
1372 not know where, when or how to present it. The role is the
1373 purpose of a wl_surface. Examples of roles are a cursor for a
1374 pointer (as set by wl_pointer.set_cursor), a drag icon
1375 (wl_data_device.start_drag), a sub-surface
1376 (wl_subcompositor.get_subsurface), and a window as defined by a
1377 shell protocol (e.g. wl_shell.get_shell_surface).
1378
1379 A surface can have only one role at a time. Initially a
1380 wl_surface does not have a role. Once a wl_surface is given a
1381 role, it is set permanently for the whole lifetime of the
1382 wl_surface object. Giving the current role again is allowed,
1383 unless explicitly forbidden by the relevant interface
1384 specification.
1385
1386 Surface roles are given by requests in other interfaces such as
1387 wl_pointer.set_cursor. The request should explicitly mention
1388 that this request gives a role to a wl_surface. Often, this
1389 request also creates a new protocol object that represents the
1390 role and adds additional functionality to wl_surface. When a
1391 client wants to destroy a wl_surface, they must destroy this role
1392 object before the wl_surface, otherwise a defunct_role_object error is
1393 sent.
1394
1395 Destroying the role object does not remove the role from the
1396 wl_surface, but it may stop the wl_surface from "playing the role".
1397 For instance, if a wl_subsurface object is destroyed, the wl_surface
1398 it was created for will be unmapped and forget its position and
1399 z-order. It is allowed to create a wl_subsurface for the same
1400 wl_surface again, but it is not allowed to use the wl_surface as
1401 a cursor (cursor is a different role than sub-surface, and role
1402 switching is not allowed).
1403 </description>
1404
1405 <enum name="error">
1406 <description summary="wl_surface error values">
1407 These errors can be emitted in response to wl_surface requests.
1408 </description>
1409 <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
1410 <entry name="invalid_transform" value="1" summary="buffer transform value is invalid"/>
1411 <entry name="invalid_size" value="2" summary="buffer size is invalid"/>
1412 <entry name="invalid_offset" value="3" summary="buffer offset is invalid"/>
1413 <entry name="defunct_role_object" value="4"
1414 summary="surface was destroyed before its role object"/>
1415 </enum>
1416
1417 <request name="destroy" type="destructor">
1418 <description summary="delete surface">
1419 Deletes the surface and invalidates its object ID.
1420 </description>
1421 </request>
1422
1423 <request name="attach">
1424 <description summary="set the surface contents">
1425 Set a buffer as the content of this surface.
1426
1427 The new size of the surface is calculated based on the buffer
1428 size transformed by the inverse buffer_transform and the
1429 inverse buffer_scale. This means that at commit time the supplied
1430 buffer size must be an integer multiple of the buffer_scale. If
1431 that's not the case, an invalid_size error is sent.
1432
1433 The x and y arguments specify the location of the new pending
1434 buffer's upper left corner, relative to the current buffer's upper
1435 left corner, in surface-local coordinates. In other words, the
1436 x and y, combined with the new surface size define in which
1437 directions the surface's size changes. Setting anything other than 0
1438 as x and y arguments is discouraged, and should instead be replaced
1439 with using the separate wl_surface.offset request.
1440
1441 When the bound wl_surface version is 5 or higher, passing any
1442 non-zero x or y is a protocol violation, and will result in an
1443 'invalid_offset' error being raised. The x and y arguments are ignored
1444 and do not change the pending state. To achieve equivalent semantics,
1445 use wl_surface.offset.
1446
1447 Surface contents are double-buffered state, see wl_surface.commit.
1448
1449 The initial surface contents are void; there is no content.
1450 wl_surface.attach assigns the given wl_buffer as the pending
1451 wl_buffer. wl_surface.commit makes the pending wl_buffer the new
1452 surface contents, and the size of the surface becomes the size
1453 calculated from the wl_buffer, as described above. After commit,
1454 there is no pending buffer until the next attach.
1455
1456 Committing a pending wl_buffer allows the compositor to read the
1457 pixels in the wl_buffer. The compositor may access the pixels at
1458 any time after the wl_surface.commit request. When the compositor
1459 will not access the pixels anymore, it will send the
1460 wl_buffer.release event. Only after receiving wl_buffer.release,
1461 the client may reuse the wl_buffer. A wl_buffer that has been
1462 attached and then replaced by another attach instead of committed
1463 will not receive a release event, and is not used by the
1464 compositor.
1465
1466 If a pending wl_buffer has been committed to more than one wl_surface,
1467 the delivery of wl_buffer.release events becomes undefined. A well
1468 behaved client should not rely on wl_buffer.release events in this
1469 case. Alternatively, a client could create multiple wl_buffer objects
1470 from the same backing storage or use wp_linux_buffer_release.
1471
1472 Destroying the wl_buffer after wl_buffer.release does not change
1473 the surface contents. Destroying the wl_buffer before wl_buffer.release
1474 is allowed as long as the underlying buffer storage isn't re-used (this
1475 can happen e.g. on client process termination). However, if the client
1476 destroys the wl_buffer before receiving the wl_buffer.release event and
1477 mutates the underlying buffer storage, the surface contents become
1478 undefined immediately.
1479
1480 If wl_surface.attach is sent with a NULL wl_buffer, the
1481 following wl_surface.commit will remove the surface content.
1482 </description>
1483 <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
1484 summary="buffer of surface contents"/>
1485 <arg name="x" type="int" summary="surface-local x coordinate"/>
1486 <arg name="y" type="int" summary="surface-local y coordinate"/>
1487 </request>
1488
1489 <request name="damage">
1490 <description summary="mark part of the surface damaged">
1491 This request is used to describe the regions where the pending
1492 buffer is different from the current surface contents, and where
1493 the surface therefore needs to be repainted. The compositor
1494 ignores the parts of the damage that fall outside of the surface.
1495
1496 Damage is double-buffered state, see wl_surface.commit.
1497
1498 The damage rectangle is specified in surface-local coordinates,
1499 where x and y specify the upper left corner of the damage rectangle.
1500
1501 The initial value for pending damage is empty: no damage.
1502 wl_surface.damage adds pending damage: the new pending damage
1503 is the union of old pending damage and the given rectangle.
1504
1505 wl_surface.commit assigns pending damage as the current damage,
1506 and clears pending damage. The server will clear the current
1507 damage as it repaints the surface.
1508
1509 Note! New clients should not use this request. Instead damage can be
1510 posted with wl_surface.damage_buffer which uses buffer coordinates
1511 instead of surface coordinates.
1512 </description>
1513 <arg name="x" type="int" summary="surface-local x coordinate"/>
1514 <arg name="y" type="int" summary="surface-local y coordinate"/>
1515 <arg name="width" type="int" summary="width of damage rectangle"/>
1516 <arg name="height" type="int" summary="height of damage rectangle"/>
1517 </request>
1518
1519 <request name="frame">
1520 <description summary="request a frame throttling hint">
1521 Request a notification when it is a good time to start drawing a new
1522 frame, by creating a frame callback. This is useful for throttling
1523 redrawing operations, and driving animations.
1524
1525 When a client is animating on a wl_surface, it can use the 'frame'
1526 request to get notified when it is a good time to draw and commit the
1527 next frame of animation. If the client commits an update earlier than
1528 that, it is likely that some updates will not make it to the display,
1529 and the client is wasting resources by drawing too often.
1530
1531 The frame request will take effect on the next wl_surface.commit.
1532 The notification will only be posted for one frame unless
1533 requested again. For a wl_surface, the notifications are posted in
1534 the order the frame requests were committed.
1535
1536 The server must send the notifications so that a client
1537 will not send excessive updates, while still allowing
1538 the highest possible update rate for clients that wait for the reply
1539 before drawing again. The server should give some time for the client
1540 to draw and commit after sending the frame callback events to let it
1541 hit the next output refresh.
1542
1543 A server should avoid signaling the frame callbacks if the
1544 surface is not visible in any way, e.g. the surface is off-screen,
1545 or completely obscured by other opaque surfaces.
1546
1547 The object returned by this request will be destroyed by the
1548 compositor after the callback is fired and as such the client must not
1549 attempt to use it after that point.
1550
1551 The callback_data passed in the callback is the current time, in
1552 milliseconds, with an undefined base.
1553 </description>
1554 <arg name="callback" type="new_id" interface="wl_callback" summary="callback object for the frame request"/>
1555 </request>
1556
1557 <request name="set_opaque_region">
1558 <description summary="set opaque region">
1559 This request sets the region of the surface that contains
1560 opaque content.
1561
1562 The opaque region is an optimization hint for the compositor
1563 that lets it optimize the redrawing of content behind opaque
1564 regions. Setting an opaque region is not required for correct
1565 behaviour, but marking transparent content as opaque will result
1566 in repaint artifacts.
1567
1568 The opaque region is specified in surface-local coordinates.
1569
1570 The compositor ignores the parts of the opaque region that fall
1571 outside of the surface.
1572
1573 Opaque region is double-buffered state, see wl_surface.commit.
1574
1575 wl_surface.set_opaque_region changes the pending opaque region.
1576 wl_surface.commit copies the pending region to the current region.
1577 Otherwise, the pending and current regions are never changed.
1578
1579 The initial value for an opaque region is empty. Setting the pending
1580 opaque region has copy semantics, and the wl_region object can be
1581 destroyed immediately. A NULL wl_region causes the pending opaque
1582 region to be set to empty.
1583 </description>
1584 <arg name="region" type="object" interface="wl_region" allow-null="true"
1585 summary="opaque region of the surface"/>
1586 </request>
1587
1588 <request name="set_input_region">
1589 <description summary="set input region">
1590 This request sets the region of the surface that can receive
1591 pointer and touch events.
1592
1593 Input events happening outside of this region will try the next
1594 surface in the server surface stack. The compositor ignores the
1595 parts of the input region that fall outside of the surface.
1596
1597 The input region is specified in surface-local coordinates.
1598
1599 Input region is double-buffered state, see wl_surface.commit.
1600
1601 wl_surface.set_input_region changes the pending input region.
1602 wl_surface.commit copies the pending region to the current region.
1603 Otherwise the pending and current regions are never changed,
1604 except cursor and icon surfaces are special cases, see
1605 wl_pointer.set_cursor and wl_data_device.start_drag.
1606
1607 The initial value for an input region is infinite. That means the
1608 whole surface will accept input. Setting the pending input region
1609 has copy semantics, and the wl_region object can be destroyed
1610 immediately. A NULL wl_region causes the input region to be set
1611 to infinite.
1612 </description>
1613 <arg name="region" type="object" interface="wl_region" allow-null="true"
1614 summary="input region of the surface"/>
1615 </request>
1616
1617 <request name="commit">
1618 <description summary="commit pending surface state">
1619 Surface state (input, opaque, and damage regions, attached buffers,
1620 etc.) is double-buffered. Protocol requests modify the pending state,
1621 as opposed to the current state in use by the compositor. A commit
1622 request atomically applies all pending state, replacing the current
1623 state. After commit, the new pending state is as documented for each
1624 related request.
1625
1626 On commit, a pending wl_buffer is applied first, and all other state
1627 second. This means that all coordinates in double-buffered state are
1628 relative to the new wl_buffer coming into use, except for
1629 wl_surface.attach itself. If there is no pending wl_buffer, the
1630 coordinates are relative to the current surface contents.
1631
1632 All requests that need a commit to become effective are documented
1633 to affect double-buffered state.
1634
1635 Other interfaces may add further double-buffered surface state.
1636 </description>
1637 </request>
1638
1639 <event name="enter">
1640 <description summary="surface enters an output">
1641 This is emitted whenever a surface's creation, movement, or resizing
1642 results in some part of it being within the scanout region of an
1643 output.
1644
1645 Note that a surface may be overlapping with zero or more outputs.
1646 </description>
1647 <arg name="output" type="object" interface="wl_output" summary="output entered by the surface"/>
1648 </event>
1649
1650 <event name="leave">
1651 <description summary="surface leaves an output">
1652 This is emitted whenever a surface's creation, movement, or resizing
1653 results in it no longer having any part of it within the scanout region
1654 of an output.
1655
1656 Clients should not use the number of outputs the surface is on for frame
1657 throttling purposes. The surface might be hidden even if no leave event
1658 has been sent, and the compositor might expect new surface content
1659 updates even if no enter event has been sent. The frame event should be
1660 used instead.
1661 </description>
1662 <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
1663 </event>
1664
1665 <!-- Version 2 additions -->
1666
1667 <request name="set_buffer_transform" since="2">
1668 <description summary="sets the buffer transformation">
1669 This request sets an optional transformation on how the compositor
1670 interprets the contents of the buffer attached to the surface. The
1671 accepted values for the transform parameter are the values for
1672 wl_output.transform.
1673
1674 Buffer transform is double-buffered state, see wl_surface.commit.
1675
1676 A newly created surface has its buffer transformation set to normal.
1677
1678 wl_surface.set_buffer_transform changes the pending buffer
1679 transformation. wl_surface.commit copies the pending buffer
1680 transformation to the current one. Otherwise, the pending and current
1681 values are never changed.
1682
1683 The purpose of this request is to allow clients to render content
1684 according to the output transform, thus permitting the compositor to
1685 use certain optimizations even if the display is rotated. Using
1686 hardware overlays and scanning out a client buffer for fullscreen
1687 surfaces are examples of such optimizations. Those optimizations are
1688 highly dependent on the compositor implementation, so the use of this
1689 request should be considered on a case-by-case basis.
1690
1691 Note that if the transform value includes 90 or 270 degree rotation,
1692 the width of the buffer will become the surface height and the height
1693 of the buffer will become the surface width.
1694
1695 If transform is not one of the values from the
1696 wl_output.transform enum the invalid_transform protocol error
1697 is raised.
1698 </description>
1699 <arg name="transform" type="int" enum="wl_output.transform"
1700 summary="transform for interpreting buffer contents"/>
1701 </request>
1702
1703 <!-- Version 3 additions -->
1704
1705 <request name="set_buffer_scale" since="3">
1706 <description summary="sets the buffer scaling factor">
1707 This request sets an optional scaling factor on how the compositor
1708 interprets the contents of the buffer attached to the window.
1709
1710 Buffer scale is double-buffered state, see wl_surface.commit.
1711
1712 A newly created surface has its buffer scale set to 1.
1713
1714 wl_surface.set_buffer_scale changes the pending buffer scale.
1715 wl_surface.commit copies the pending buffer scale to the current one.
1716 Otherwise, the pending and current values are never changed.
1717
1718 The purpose of this request is to allow clients to supply higher
1719 resolution buffer data for use on high resolution outputs. It is
1720 intended that you pick the same buffer scale as the scale of the
1721 output that the surface is displayed on. This means the compositor
1722 can avoid scaling when rendering the surface on that output.
1723
1724 Note that if the scale is larger than 1, then you have to attach
1725 a buffer that is larger (by a factor of scale in each dimension)
1726 than the desired surface size.
1727
1728 If scale is not positive the invalid_scale protocol error is
1729 raised.
1730 </description>
1731 <arg name="scale" type="int"
1732 summary="positive scale for interpreting buffer contents"/>
1733 </request>
1734
1735 <!-- Version 4 additions -->
1736 <request name="damage_buffer" since="4">
1737 <description summary="mark part of the surface damaged using buffer coordinates">
1738 This request is used to describe the regions where the pending
1739 buffer is different from the current surface contents, and where
1740 the surface therefore needs to be repainted. The compositor
1741 ignores the parts of the damage that fall outside of the surface.
1742
1743 Damage is double-buffered state, see wl_surface.commit.
1744
1745 The damage rectangle is specified in buffer coordinates,
1746 where x and y specify the upper left corner of the damage rectangle.
1747
1748 The initial value for pending damage is empty: no damage.
1749 wl_surface.damage_buffer adds pending damage: the new pending
1750 damage is the union of old pending damage and the given rectangle.
1751
1752 wl_surface.commit assigns pending damage as the current damage,
1753 and clears pending damage. The server will clear the current
1754 damage as it repaints the surface.
1755
1756 This request differs from wl_surface.damage in only one way - it
1757 takes damage in buffer coordinates instead of surface-local
1758 coordinates. While this generally is more intuitive than surface
1759 coordinates, it is especially desirable when using wp_viewport
1760 or when a drawing library (like EGL) is unaware of buffer scale
1761 and buffer transform.
1762
1763 Note: Because buffer transformation changes and damage requests may
1764 be interleaved in the protocol stream, it is impossible to determine
1765 the actual mapping between surface and buffer damage until
1766 wl_surface.commit time. Therefore, compositors wishing to take both
1767 kinds of damage into account will have to accumulate damage from the
1768 two requests separately and only transform from one to the other
1769 after receiving the wl_surface.commit.
1770 </description>
1771 <arg name="x" type="int" summary="buffer-local x coordinate"/>
1772 <arg name="y" type="int" summary="buffer-local y coordinate"/>
1773 <arg name="width" type="int" summary="width of damage rectangle"/>
1774 <arg name="height" type="int" summary="height of damage rectangle"/>
1775 </request>
1776
1777 <!-- Version 5 additions -->
1778
1779 <request name="offset" since="5">
1780 <description summary="set the surface contents offset">
1781 The x and y arguments specify the location of the new pending
1782 buffer's upper left corner, relative to the current buffer's upper
1783 left corner, in surface-local coordinates. In other words, the
1784 x and y, combined with the new surface size define in which
1785 directions the surface's size changes.
1786
1787 Surface location offset is double-buffered state, see
1788 wl_surface.commit.
1789
1790 This request is semantically equivalent to and the replaces the x and y
1791 arguments in the wl_surface.attach request in wl_surface versions prior
1792 to 5. See wl_surface.attach for details.
1793 </description>
1794 <arg name="x" type="int" summary="surface-local x coordinate"/>
1795 <arg name="y" type="int" summary="surface-local y coordinate"/>
1796 </request>
1797
1798 <!-- Version 6 additions -->
1799
1800 <event name="preferred_buffer_scale" since="6">
1801 <description summary="preferred buffer scale for the surface">
1802 This event indicates the preferred buffer scale for this surface. It is
1803 sent whenever the compositor's preference changes.
1804
1805 It is intended that scaling aware clients use this event to scale their
1806 content and use wl_surface.set_buffer_scale to indicate the scale they
1807 have rendered with. This allows clients to supply a higher detail
1808 buffer.
1809 </description>
1810 <arg name="factor" type="int" summary="preferred scaling factor"/>
1811 </event>
1812
1813 <event name="preferred_buffer_transform" since="6">
1814 <description summary="preferred buffer transform for the surface">
1815 This event indicates the preferred buffer transform for this surface.
1816 It is sent whenever the compositor's preference changes.
1817
1818 It is intended that transform aware clients use this event to apply the
1819 transform to their content and use wl_surface.set_buffer_transform to
1820 indicate the transform they have rendered with.
1821 </description>
1822 <arg name="transform" type="uint" enum="wl_output.transform"
1823 summary="preferred transform"/>
1824 </event>
1825 </interface>
1826
1827 <interface name="wl_seat" version="9">
1828 <description summary="group of input devices">
1829 A seat is a group of keyboards, pointer and touch devices. This
1830 object is published as a global during start up, or when such a
1831 device is hot plugged. A seat typically has a pointer and
1832 maintains a keyboard focus and a pointer focus.
1833 </description>
1834
1835 <enum name="capability" bitfield="true">
1836 <description summary="seat capability bitmask">
1837 This is a bitmask of capabilities this seat has; if a member is
1838 set, then it is present on the seat.
1839 </description>
1840 <entry name="pointer" value="1" summary="the seat has pointer devices"/>
1841 <entry name="keyboard" value="2" summary="the seat has one or more keyboards"/>
1842 <entry name="touch" value="4" summary="the seat has touch devices"/>
1843 </enum>
1844
1845 <enum name="error">
1846 <description summary="wl_seat error values">
1847 These errors can be emitted in response to wl_seat requests.
1848 </description>
1849 <entry name="missing_capability" value="0"
1850 summary="get_pointer, get_keyboard or get_touch called on seat without the matching capability"/>
1851 </enum>
1852
1853 <event name="capabilities">
1854 <description summary="seat capabilities changed">
1855 This is emitted whenever a seat gains or loses the pointer,
1856 keyboard or touch capabilities. The argument is a capability
1857 enum containing the complete set of capabilities this seat has.
1858
1859 When the pointer capability is added, a client may create a
1860 wl_pointer object using the wl_seat.get_pointer request. This object
1861 will receive pointer events until the capability is removed in the
1862 future.
1863
1864 When the pointer capability is removed, a client should destroy the
1865 wl_pointer objects associated with the seat where the capability was
1866 removed, using the wl_pointer.release request. No further pointer
1867 events will be received on these objects.
1868
1869 In some compositors, if a seat regains the pointer capability and a
1870 client has a previously obtained wl_pointer object of version 4 or
1871 less, that object may start sending pointer events again. This
1872 behavior is considered a misinterpretation of the intended behavior
1873 and must not be relied upon by the client. wl_pointer objects of
1874 version 5 or later must not send events if created before the most
1875 recent event notifying the client of an added pointer capability.
1876
1877 The above behavior also applies to wl_keyboard and wl_touch with the
1878 keyboard and touch capabilities, respectively.
1879 </description>
1880 <arg name="capabilities" type="uint" enum="capability" summary="capabilities of the seat"/>
1881 </event>
1882
1883 <request name="get_pointer">
1884 <description summary="return pointer object">
1885 The ID provided will be initialized to the wl_pointer interface
1886 for this seat.
1887
1888 This request only takes effect if the seat has the pointer
1889 capability, or has had the pointer capability in the past.
1890 It is a protocol violation to issue this request on a seat that has
1891 never had the pointer capability. The missing_capability error will
1892 be sent in this case.
1893 </description>
1894 <arg name="id" type="new_id" interface="wl_pointer" summary="seat pointer"/>
1895 </request>
1896
1897 <request name="get_keyboard">
1898 <description summary="return keyboard object">
1899 The ID provided will be initialized to the wl_keyboard interface
1900 for this seat.
1901
1902 This request only takes effect if the seat has the keyboard
1903 capability, or has had the keyboard capability in the past.
1904 It is a protocol violation to issue this request on a seat that has
1905 never had the keyboard capability. The missing_capability error will
1906 be sent in this case.
1907 </description>
1908 <arg name="id" type="new_id" interface="wl_keyboard" summary="seat keyboard"/>
1909 </request>
1910
1911 <request name="get_touch">
1912 <description summary="return touch object">
1913 The ID provided will be initialized to the wl_touch interface
1914 for this seat.
1915
1916 This request only takes effect if the seat has the touch
1917 capability, or has had the touch capability in the past.
1918 It is a protocol violation to issue this request on a seat that has
1919 never had the touch capability. The missing_capability error will
1920 be sent in this case.
1921 </description>
1922 <arg name="id" type="new_id" interface="wl_touch" summary="seat touch interface"/>
1923 </request>
1924
1925 <!-- Version 2 additions -->
1926
1927 <event name="name" since="2">
1928 <description summary="unique identifier for this seat">
1929 In a multi-seat configuration the seat name can be used by clients to
1930 help identify which physical devices the seat represents.
1931
1932 The seat name is a UTF-8 string with no convention defined for its
1933 contents. Each name is unique among all wl_seat globals. The name is
1934 only guaranteed to be unique for the current compositor instance.
1935
1936 The same seat names are used for all clients. Thus, the name can be
1937 shared across processes to refer to a specific wl_seat global.
1938
1939 The name event is sent after binding to the seat global. This event is
1940 only sent once per seat object, and the name does not change over the
1941 lifetime of the wl_seat global.
1942
1943 Compositors may re-use the same seat name if the wl_seat global is
1944 destroyed and re-created later.
1945 </description>
1946 <arg name="name" type="string" summary="seat identifier"/>
1947 </event>
1948
1949 <!-- Version 5 additions -->
1950
1951 <request name="release" type="destructor" since="5">
1952 <description summary="release the seat object">
1953 Using this request a client can tell the server that it is not going to
1954 use the seat object anymore.
1955 </description>
1956 </request>
1957
1958 </interface>
1959
1960 <interface name="wl_pointer" version="9">
1961 <description summary="pointer input device">
1962 The wl_pointer interface represents one or more input devices,
1963 such as mice, which control the pointer location and pointer_focus
1964 of a seat.
1965
1966 The wl_pointer interface generates motion, enter and leave
1967 events for the surfaces that the pointer is located over,
1968 and button and axis events for button presses, button releases
1969 and scrolling.
1970 </description>
1971
1972 <enum name="error">
1973 <entry name="role" value="0" summary="given wl_surface has another role"/>
1974 </enum>
1975
1976 <request name="set_cursor">
1977 <description summary="set the pointer surface">
1978 Set the pointer surface, i.e., the surface that contains the
1979 pointer image (cursor). This request gives the surface the role
1980 of a cursor. If the surface already has another role, it raises
1981 a protocol error.
1982
1983 The cursor actually changes only if the pointer
1984 focus for this device is one of the requesting client's surfaces
1985 or the surface parameter is the current pointer surface. If
1986 there was a previous surface set with this request it is
1987 replaced. If surface is NULL, the pointer image is hidden.
1988
1989 The parameters hotspot_x and hotspot_y define the position of
1990 the pointer surface relative to the pointer location. Its
1991 top-left corner is always at (x, y) - (hotspot_x, hotspot_y),
1992 where (x, y) are the coordinates of the pointer location, in
1993 surface-local coordinates.
1994
1995 On surface.attach requests to the pointer surface, hotspot_x
1996 and hotspot_y are decremented by the x and y parameters
1997 passed to the request. Attach must be confirmed by
1998 wl_surface.commit as usual.
1999
2000 The hotspot can also be updated by passing the currently set
2001 pointer surface to this request with new values for hotspot_x
2002 and hotspot_y.
2003
2004 The input region is ignored for wl_surfaces with the role of
2005 a cursor. When the use as a cursor ends, the wl_surface is
2006 unmapped.
2007
2008 The serial parameter must match the latest wl_pointer.enter
2009 serial number sent to the client. Otherwise the request will be
2010 ignored.
2011 </description>
2012 <arg name="serial" type="uint" summary="serial number of the enter event"/>
2013 <arg name="surface" type="object" interface="wl_surface" allow-null="true"
2014 summary="pointer surface"/>
2015 <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/>
2016 <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/>
2017 </request>
2018
2019 <event name="enter">
2020 <description summary="enter event">
2021 Notification that this seat's pointer is focused on a certain
2022 surface.
2023
2024 When a seat's focus enters a surface, the pointer image
2025 is undefined and a client should respond to this event by setting
2026 an appropriate pointer image with the set_cursor request.
2027 </description>
2028 <arg name="serial" type="uint" summary="serial number of the enter event"/>
2029 <arg name="surface" type="object" interface="wl_surface" summary="surface entered by the pointer"/>
2030 <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2031 <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2032 </event>
2033
2034 <event name="leave">
2035 <description summary="leave event">
2036 Notification that this seat's pointer is no longer focused on
2037 a certain surface.
2038
2039 The leave notification is sent before the enter notification
2040 for the new focus.
2041 </description>
2042 <arg name="serial" type="uint" summary="serial number of the leave event"/>
2043 <arg name="surface" type="object" interface="wl_surface" summary="surface left by the pointer"/>
2044 </event>
2045
2046 <event name="motion">
2047 <description summary="pointer motion event">
2048 Notification of pointer location change. The arguments
2049 surface_x and surface_y are the location relative to the
2050 focused surface.
2051 </description>
2052 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2053 <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2054 <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2055 </event>
2056
2057 <enum name="button_state">
2058 <description summary="physical button state">
2059 Describes the physical state of a button that produced the button
2060 event.
2061 </description>
2062 <entry name="released" value="0" summary="the button is not pressed"/>
2063 <entry name="pressed" value="1" summary="the button is pressed"/>
2064 </enum>
2065
2066 <event name="button">
2067 <description summary="pointer button event">
2068 Mouse button click and release notifications.
2069
2070 The location of the click is given by the last motion or
2071 enter event.
2072 The time argument is a timestamp with millisecond
2073 granularity, with an undefined base.
2074
2075 The button is a button code as defined in the Linux kernel's
2076 linux/input-event-codes.h header file, e.g. BTN_LEFT.
2077
2078 Any 16-bit button code value is reserved for future additions to the
2079 kernel's event code list. All other button codes above 0xFFFF are
2080 currently undefined but may be used in future versions of this
2081 protocol.
2082 </description>
2083 <arg name="serial" type="uint" summary="serial number of the button event"/>
2084 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2085 <arg name="button" type="uint" summary="button that produced the event"/>
2086 <arg name="state" type="uint" enum="button_state" summary="physical state of the button"/>
2087 </event>
2088
2089 <enum name="axis">
2090 <description summary="axis types">
2091 Describes the axis types of scroll events.
2092 </description>
2093 <entry name="vertical_scroll" value="0" summary="vertical axis"/>
2094 <entry name="horizontal_scroll" value="1" summary="horizontal axis"/>
2095 </enum>
2096
2097 <event name="axis">
2098 <description summary="axis event">
2099 Scroll and other axis notifications.
2100
2101 For scroll events (vertical and horizontal scroll axes), the
2102 value parameter is the length of a vector along the specified
2103 axis in a coordinate space identical to those of motion events,
2104 representing a relative movement along the specified axis.
2105
2106 For devices that support movements non-parallel to axes multiple
2107 axis events will be emitted.
2108
2109 When applicable, for example for touch pads, the server can
2110 choose to emit scroll events where the motion vector is
2111 equivalent to a motion event vector.
2112
2113 When applicable, a client can transform its content relative to the
2114 scroll distance.
2115 </description>
2116 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2117 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2118 <arg name="value" type="fixed" summary="length of vector in surface-local coordinate space"/>
2119 </event>
2120
2121 <!-- Version 3 additions -->
2122
2123 <request name="release" type="destructor" since="3">
2124 <description summary="release the pointer object">
2125 Using this request a client can tell the server that it is not going to
2126 use the pointer object anymore.
2127
2128 This request destroys the pointer proxy object, so clients must not call
2129 wl_pointer_destroy() after using this request.
2130 </description>
2131 </request>
2132
2133 <!-- Version 5 additions -->
2134
2135 <event name="frame" since="5">
2136 <description summary="end of a pointer event sequence">
2137 Indicates the end of a set of events that logically belong together.
2138 A client is expected to accumulate the data in all events within the
2139 frame before proceeding.
2140
2141 All wl_pointer events before a wl_pointer.frame event belong
2142 logically together. For example, in a diagonal scroll motion the
2143 compositor will send an optional wl_pointer.axis_source event, two
2144 wl_pointer.axis events (horizontal and vertical) and finally a
2145 wl_pointer.frame event. The client may use this information to
2146 calculate a diagonal vector for scrolling.
2147
2148 When multiple wl_pointer.axis events occur within the same frame,
2149 the motion vector is the combined motion of all events.
2150 When a wl_pointer.axis and a wl_pointer.axis_stop event occur within
2151 the same frame, this indicates that axis movement in one axis has
2152 stopped but continues in the other axis.
2153 When multiple wl_pointer.axis_stop events occur within the same
2154 frame, this indicates that these axes stopped in the same instance.
2155
2156 A wl_pointer.frame event is sent for every logical event group,
2157 even if the group only contains a single wl_pointer event.
2158 Specifically, a client may get a sequence: motion, frame, button,
2159 frame, axis, frame, axis_stop, frame.
2160
2161 The wl_pointer.enter and wl_pointer.leave events are logical events
2162 generated by the compositor and not the hardware. These events are
2163 also grouped by a wl_pointer.frame. When a pointer moves from one
2164 surface to another, a compositor should group the
2165 wl_pointer.leave event within the same wl_pointer.frame.
2166 However, a client must not rely on wl_pointer.leave and
2167 wl_pointer.enter being in the same wl_pointer.frame.
2168 Compositor-specific policies may require the wl_pointer.leave and
2169 wl_pointer.enter event being split across multiple wl_pointer.frame
2170 groups.
2171 </description>
2172 </event>
2173
2174 <enum name="axis_source">
2175 <description summary="axis source types">
2176 Describes the source types for axis events. This indicates to the
2177 client how an axis event was physically generated; a client may
2178 adjust the user interface accordingly. For example, scroll events
2179 from a "finger" source may be in a smooth coordinate space with
2180 kinetic scrolling whereas a "wheel" source may be in discrete steps
2181 of a number of lines.
2182
2183 The "continuous" axis source is a device generating events in a
2184 continuous coordinate space, but using something other than a
2185 finger. One example for this source is button-based scrolling where
2186 the vertical motion of a device is converted to scroll events while
2187 a button is held down.
2188
2189 The "wheel tilt" axis source indicates that the actual device is a
2190 wheel but the scroll event is not caused by a rotation but a
2191 (usually sideways) tilt of the wheel.
2192 </description>
2193 <entry name="wheel" value="0" summary="a physical wheel rotation" />
2194 <entry name="finger" value="1" summary="finger on a touch surface" />
2195 <entry name="continuous" value="2" summary="continuous coordinate space"/>
2196 <entry name="wheel_tilt" value="3" summary="a physical wheel tilt" since="6"/>
2197 </enum>
2198
2199 <event name="axis_source" since="5">
2200 <description summary="axis source event">
2201 Source information for scroll and other axes.
2202
2203 This event does not occur on its own. It is sent before a
2204 wl_pointer.frame event and carries the source information for
2205 all events within that frame.
2206
2207 The source specifies how this event was generated. If the source is
2208 wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be
2209 sent when the user lifts the finger off the device.
2210
2211 If the source is wl_pointer.axis_source.wheel,
2212 wl_pointer.axis_source.wheel_tilt or
2213 wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
2214 or may not be sent. Whether a compositor sends an axis_stop event
2215 for these sources is hardware-specific and implementation-dependent;
2216 clients must not rely on receiving an axis_stop event for these
2217 scroll sources and should treat scroll sequences from these scroll
2218 sources as unterminated by default.
2219
2220 This event is optional. If the source is unknown for a particular
2221 axis event sequence, no event is sent.
2222 Only one wl_pointer.axis_source event is permitted per frame.
2223
2224 The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2225 not guaranteed.
2226 </description>
2227 <arg name="axis_source" type="uint" enum="axis_source" summary="source of the axis event"/>
2228 </event>
2229
2230 <event name="axis_stop" since="5">
2231 <description summary="axis stop event">
2232 Stop notification for scroll and other axes.
2233
2234 For some wl_pointer.axis_source types, a wl_pointer.axis_stop event
2235 is sent to notify a client that the axis sequence has terminated.
2236 This enables the client to implement kinetic scrolling.
2237 See the wl_pointer.axis_source documentation for information on when
2238 this event may be generated.
2239
2240 Any wl_pointer.axis events with the same axis_source after this
2241 event should be considered as the start of a new axis motion.
2242
2243 The timestamp is to be interpreted identical to the timestamp in the
2244 wl_pointer.axis event. The timestamp value may be the same as a
2245 preceding wl_pointer.axis event.
2246 </description>
2247 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2248 <arg name="axis" type="uint" enum="axis" summary="the axis stopped with this event"/>
2249 </event>
2250
2251 <event name="axis_discrete" since="5">
2252 <description summary="axis click event">
2253 Discrete step information for scroll and other axes.
2254
2255 This event carries the axis value of the wl_pointer.axis event in
2256 discrete steps (e.g. mouse wheel clicks).
2257
2258 This event is deprecated with wl_pointer version 8 - this event is not
2259 sent to clients supporting version 8 or later.
2260
2261 This event does not occur on its own, it is coupled with a
2262 wl_pointer.axis event that represents this axis value on a
2263 continuous scale. The protocol guarantees that each axis_discrete
2264 event is always followed by exactly one axis event with the same
2265 axis number within the same wl_pointer.frame. Note that the protocol
2266 allows for other events to occur between the axis_discrete and
2267 its coupled axis event, including other axis_discrete or axis
2268 events. A wl_pointer.frame must not contain more than one axis_discrete
2269 event per axis type.
2270
2271 This event is optional; continuous scrolling devices
2272 like two-finger scrolling on touchpads do not have discrete
2273 steps and do not generate this event.
2274
2275 The discrete value carries the directional information. e.g. a value
2276 of -2 is two steps towards the negative direction of this axis.
2277
2278 The axis number is identical to the axis number in the associated
2279 axis event.
2280
2281 The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2282 not guaranteed.
2283 </description>
2284 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2285 <arg name="discrete" type="int" summary="number of steps"/>
2286 </event>
2287
2288 <event name="axis_value120" since="8">
2289 <description summary="axis high-resolution scroll event">
2290 Discrete high-resolution scroll information.
2291
2292 This event carries high-resolution wheel scroll information,
2293 with each multiple of 120 representing one logical scroll step
2294 (a wheel detent). For example, an axis_value120 of 30 is one quarter of
2295 a logical scroll step in the positive direction, a value120 of
2296 -240 are two logical scroll steps in the negative direction within the
2297 same hardware event.
2298 Clients that rely on discrete scrolling should accumulate the
2299 value120 to multiples of 120 before processing the event.
2300
2301 The value120 must not be zero.
2302
2303 This event replaces the wl_pointer.axis_discrete event in clients
2304 supporting wl_pointer version 8 or later.
2305
2306 Where a wl_pointer.axis_source event occurs in the same
2307 wl_pointer.frame, the axis source applies to this event.
2308
2309 The order of wl_pointer.axis_value120 and wl_pointer.axis_source is
2310 not guaranteed.
2311 </description>
2312 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2313 <arg name="value120" type="int" summary="scroll distance as fraction of 120"/>
2314 </event>
2315
2316 <!-- Version 9 additions -->
2317
2318 <enum name="axis_relative_direction">
2319 <description summary="axis relative direction">
2320 This specifies the direction of the physical motion that caused a
2321 wl_pointer.axis event, relative to the wl_pointer.axis direction.
2322 </description>
2323 <entry name="identical" value="0"
2324 summary="physical motion matches axis direction"/>
2325 <entry name="inverted" value="1"
2326 summary="physical motion is the inverse of the axis direction"/>
2327 </enum>
2328
2329 <event name="axis_relative_direction" since="9">
2330 <description summary="axis relative physical direction event">
2331 Relative directional information of the entity causing the axis
2332 motion.
2333
2334 For a wl_pointer.axis event, the wl_pointer.axis_relative_direction
2335 event specifies the movement direction of the entity causing the
2336 wl_pointer.axis event. For example:
2337 - if a user's fingers on a touchpad move down and this
2338 causes a wl_pointer.axis vertical_scroll down event, the physical
2339 direction is 'identical'
2340 - if a user's fingers on a touchpad move down and this causes a
2341 wl_pointer.axis vertical_scroll up scroll up event ('natural
2342 scrolling'), the physical direction is 'inverted'.
2343
2344 A client may use this information to adjust scroll motion of
2345 components. Specifically, enabling natural scrolling causes the
2346 content to change direction compared to traditional scrolling.
2347 Some widgets like volume control sliders should usually match the
2348 physical direction regardless of whether natural scrolling is
2349 active. This event enables clients to match the scroll direction of
2350 a widget to the physical direction.
2351
2352 This event does not occur on its own, it is coupled with a
2353 wl_pointer.axis event that represents this axis value.
2354 The protocol guarantees that each axis_relative_direction event is
2355 always followed by exactly one axis event with the same
2356 axis number within the same wl_pointer.frame. Note that the protocol
2357 allows for other events to occur between the axis_relative_direction
2358 and its coupled axis event.
2359
2360 The axis number is identical to the axis number in the associated
2361 axis event.
2362
2363 The order of wl_pointer.axis_relative_direction,
2364 wl_pointer.axis_discrete and wl_pointer.axis_source is not
2365 guaranteed.
2366 </description>
2367 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2368 <arg name="direction" type="uint" enum="axis_relative_direction"
2369 summary="physical direction relative to axis motion"/>
2370 </event>
2371 </interface>
2372
2373 <interface name="wl_keyboard" version="9">
2374 <description summary="keyboard input device">
2375 The wl_keyboard interface represents one or more keyboards
2376 associated with a seat.
2377 </description>
2378
2379 <enum name="keymap_format">
2380 <description summary="keyboard mapping format">
2381 This specifies the format of the keymap provided to the
2382 client with the wl_keyboard.keymap event.
2383 </description>
2384 <entry name="no_keymap" value="0"
2385 summary="no keymap; client must understand how to interpret the raw keycode"/>
2386 <entry name="xkb_v1" value="1"
2387 summary="libxkbcommon compatible, null-terminated string; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
2388 </enum>
2389
2390 <event name="keymap">
2391 <description summary="keyboard mapping">
2392 This event provides a file descriptor to the client which can be
2393 memory-mapped in read-only mode to provide a keyboard mapping
2394 description.
2395
2396 From version 7 onwards, the fd must be mapped with MAP_PRIVATE by
2397 the recipient, as MAP_SHARED may fail.
2398 </description>
2399 <arg name="format" type="uint" enum="keymap_format" summary="keymap format"/>
2400 <arg name="fd" type="fd" summary="keymap file descriptor"/>
2401 <arg name="size" type="uint" summary="keymap size, in bytes"/>
2402 </event>
2403
2404 <event name="enter">
2405 <description summary="enter event">
2406 Notification that this seat's keyboard focus is on a certain
2407 surface.
2408
2409 The compositor must send the wl_keyboard.modifiers event after this
2410 event.
2411 </description>
2412 <arg name="serial" type="uint" summary="serial number of the enter event"/>
2413 <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
2414 <arg name="keys" type="array" summary="the currently pressed keys"/>
2415 </event>
2416
2417 <event name="leave">
2418 <description summary="leave event">
2419 Notification that this seat's keyboard focus is no longer on
2420 a certain surface.
2421
2422 The leave notification is sent before the enter notification
2423 for the new focus.
2424
2425 After this event client must assume that all keys, including modifiers,
2426 are lifted and also it must stop key repeating if there's some going on.
2427 </description>
2428 <arg name="serial" type="uint" summary="serial number of the leave event"/>
2429 <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
2430 </event>
2431
2432 <enum name="key_state">
2433 <description summary="physical key state">
2434 Describes the physical state of a key that produced the key event.
2435 </description>
2436 <entry name="released" value="0" summary="key is not pressed"/>
2437 <entry name="pressed" value="1" summary="key is pressed"/>
2438 </enum>
2439
2440 <event name="key">
2441 <description summary="key event">
2442 A key was pressed or released.
2443 The time argument is a timestamp with millisecond
2444 granularity, with an undefined base.
2445
2446 The key is a platform-specific key code that can be interpreted
2447 by feeding it to the keyboard mapping (see the keymap event).
2448
2449 If this event produces a change in modifiers, then the resulting
2450 wl_keyboard.modifiers event must be sent after this event.
2451 </description>
2452 <arg name="serial" type="uint" summary="serial number of the key event"/>
2453 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2454 <arg name="key" type="uint" summary="key that produced the event"/>
2455 <arg name="state" type="uint" enum="key_state" summary="physical state of the key"/>
2456 </event>
2457
2458 <event name="modifiers">
2459 <description summary="modifier and group state">
2460 Notifies clients that the modifier and/or group state has
2461 changed, and it should update its local state.
2462 </description>
2463 <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
2464 <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
2465 <arg name="mods_latched" type="uint" summary="latched modifiers"/>
2466 <arg name="mods_locked" type="uint" summary="locked modifiers"/>
2467 <arg name="group" type="uint" summary="keyboard layout"/>
2468 </event>
2469
2470 <!-- Version 3 additions -->
2471
2472 <request name="release" type="destructor" since="3">
2473 <description summary="release the keyboard object"/>
2474 </request>
2475
2476 <!-- Version 4 additions -->
2477
2478 <event name="repeat_info" since="4">
2479 <description summary="repeat rate and delay">
2480 Informs the client about the keyboard's repeat rate and delay.
2481
2482 This event is sent as soon as the wl_keyboard object has been created,
2483 and is guaranteed to be received by the client before any key press
2484 event.
2485
2486 Negative values for either rate or delay are illegal. A rate of zero
2487 will disable any repeating (regardless of the value of delay).
2488
2489 This event can be sent later on as well with a new value if necessary,
2490 so clients should continue listening for the event past the creation
2491 of wl_keyboard.
2492 </description>
2493 <arg name="rate" type="int"
2494 summary="the rate of repeating keys in characters per second"/>
2495 <arg name="delay" type="int"
2496 summary="delay in milliseconds since key down until repeating starts"/>
2497 </event>
2498 </interface>
2499
2500 <interface name="wl_touch" version="9">
2501 <description summary="touchscreen input device">
2502 The wl_touch interface represents a touchscreen
2503 associated with a seat.
2504
2505 Touch interactions can consist of one or more contacts.
2506 For each contact, a series of events is generated, starting
2507 with a down event, followed by zero or more motion events,
2508 and ending with an up event. Events relating to the same
2509 contact point can be identified by the ID of the sequence.
2510 </description>
2511
2512 <event name="down">
2513 <description summary="touch down event and beginning of a touch sequence">
2514 A new touch point has appeared on the surface. This touch point is
2515 assigned a unique ID. Future events from this touch point reference
2516 this ID. The ID ceases to be valid after a touch up event and may be
2517 reused in the future.
2518 </description>
2519 <arg name="serial" type="uint" summary="serial number of the touch down event"/>
2520 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2521 <arg name="surface" type="object" interface="wl_surface" summary="surface touched"/>
2522 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2523 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2524 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2525 </event>
2526
2527 <event name="up">
2528 <description summary="end of a touch event sequence">
2529 The touch point has disappeared. No further events will be sent for
2530 this touch point and the touch point's ID is released and may be
2531 reused in a future touch down event.
2532 </description>
2533 <arg name="serial" type="uint" summary="serial number of the touch up event"/>
2534 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2535 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2536 </event>
2537
2538 <event name="motion">
2539 <description summary="update of touch point coordinates">
2540 A touch point has changed coordinates.
2541 </description>
2542 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2543 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2544 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2545 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2546 </event>
2547
2548 <event name="frame">
2549 <description summary="end of touch frame event">
2550 Indicates the end of a set of events that logically belong together.
2551 A client is expected to accumulate the data in all events within the
2552 frame before proceeding.
2553
2554 A wl_touch.frame terminates at least one event but otherwise no
2555 guarantee is provided about the set of events within a frame. A client
2556 must assume that any state not updated in a frame is unchanged from the
2557 previously known state.
2558 </description>
2559 </event>
2560
2561 <event name="cancel">
2562 <description summary="touch session cancelled">
2563 Sent if the compositor decides the touch stream is a global
2564 gesture. No further events are sent to the clients from that
2565 particular gesture. Touch cancellation applies to all touch points
2566 currently active on this client's surface. The client is
2567 responsible for finalizing the touch points, future touch points on
2568 this surface may reuse the touch point ID.
2569 </description>
2570 </event>
2571
2572 <!-- Version 3 additions -->
2573
2574 <request name="release" type="destructor" since="3">
2575 <description summary="release the touch object"/>
2576 </request>
2577
2578 <!-- Version 6 additions -->
2579
2580 <event name="shape" since="6">
2581 <description summary="update shape of touch point">
2582 Sent when a touchpoint has changed its shape.
2583
2584 This event does not occur on its own. It is sent before a
2585 wl_touch.frame event and carries the new shape information for
2586 any previously reported, or new touch points of that frame.
2587
2588 Other events describing the touch point such as wl_touch.down,
2589 wl_touch.motion or wl_touch.orientation may be sent within the
2590 same wl_touch.frame. A client should treat these events as a single
2591 logical touch point update. The order of wl_touch.shape,
2592 wl_touch.orientation and wl_touch.motion is not guaranteed.
2593 A wl_touch.down event is guaranteed to occur before the first
2594 wl_touch.shape event for this touch ID but both events may occur within
2595 the same wl_touch.frame.
2596
2597 A touchpoint shape is approximated by an ellipse through the major and
2598 minor axis length. The major axis length describes the longer diameter
2599 of the ellipse, while the minor axis length describes the shorter
2600 diameter. Major and minor are orthogonal and both are specified in
2601 surface-local coordinates. The center of the ellipse is always at the
2602 touchpoint location as reported by wl_touch.down or wl_touch.move.
2603
2604 This event is only sent by the compositor if the touch device supports
2605 shape reports. The client has to make reasonable assumptions about the
2606 shape if it did not receive this event.
2607 </description>
2608 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2609 <arg name="major" type="fixed" summary="length of the major axis in surface-local coordinates"/>
2610 <arg name="minor" type="fixed" summary="length of the minor axis in surface-local coordinates"/>
2611 </event>
2612
2613 <event name="orientation" since="6">
2614 <description summary="update orientation of touch point">
2615 Sent when a touchpoint has changed its orientation.
2616
2617 This event does not occur on its own. It is sent before a
2618 wl_touch.frame event and carries the new shape information for
2619 any previously reported, or new touch points of that frame.
2620
2621 Other events describing the touch point such as wl_touch.down,
2622 wl_touch.motion or wl_touch.shape may be sent within the
2623 same wl_touch.frame. A client should treat these events as a single
2624 logical touch point update. The order of wl_touch.shape,
2625 wl_touch.orientation and wl_touch.motion is not guaranteed.
2626 A wl_touch.down event is guaranteed to occur before the first
2627 wl_touch.orientation event for this touch ID but both events may occur
2628 within the same wl_touch.frame.
2629
2630 The orientation describes the clockwise angle of a touchpoint's major
2631 axis to the positive surface y-axis and is normalized to the -180 to
2632 +180 degree range. The granularity of orientation depends on the touch
2633 device, some devices only support binary rotation values between 0 and
2634 90 degrees.
2635
2636 This event is only sent by the compositor if the touch device supports
2637 orientation reports.
2638 </description>
2639 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2640 <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
2641 </event>
2642 </interface>
2643
2644 <interface name="wl_output" version="4">
2645 <description summary="compositor output region">
2646 An output describes part of the compositor geometry. The
2647 compositor works in the 'compositor coordinate system' and an
2648 output corresponds to a rectangular area in that space that is
2649 actually visible. This typically corresponds to a monitor that
2650 displays part of the compositor space. This object is published
2651 as global during start up, or when a monitor is hotplugged.
2652 </description>
2653
2654 <enum name="subpixel">
2655 <description summary="subpixel geometry information">
2656 This enumeration describes how the physical
2657 pixels on an output are laid out.
2658 </description>
2659 <entry name="unknown" value="0" summary="unknown geometry"/>
2660 <entry name="none" value="1" summary="no geometry"/>
2661 <entry name="horizontal_rgb" value="2" summary="horizontal RGB"/>
2662 <entry name="horizontal_bgr" value="3" summary="horizontal BGR"/>
2663 <entry name="vertical_rgb" value="4" summary="vertical RGB"/>
2664 <entry name="vertical_bgr" value="5" summary="vertical BGR"/>
2665 </enum>
2666
2667 <enum name="transform">
2668 <description summary="transform from framebuffer to output">
2669 This describes the transform that a compositor will apply to a
2670 surface to compensate for the rotation or mirroring of an
2671 output device.
2672
2673 The flipped values correspond to an initial flip around a
2674 vertical axis followed by rotation.
2675
2676 The purpose is mainly to allow clients to render accordingly and
2677 tell the compositor, so that for fullscreen surfaces, the
2678 compositor will still be able to scan out directly from client
2679 surfaces.
2680 </description>
2681 <entry name="normal" value="0" summary="no transform"/>
2682 <entry name="90" value="1" summary="90 degrees counter-clockwise"/>
2683 <entry name="180" value="2" summary="180 degrees counter-clockwise"/>
2684 <entry name="270" value="3" summary="270 degrees counter-clockwise"/>
2685 <entry name="flipped" value="4" summary="180 degree flip around a vertical axis"/>
2686 <entry name="flipped_90" value="5" summary="flip and rotate 90 degrees counter-clockwise"/>
2687 <entry name="flipped_180" value="6" summary="flip and rotate 180 degrees counter-clockwise"/>
2688 <entry name="flipped_270" value="7" summary="flip and rotate 270 degrees counter-clockwise"/>
2689 </enum>
2690
2691 <event name="geometry">
2692 <description summary="properties of the output">
2693 The geometry event describes geometric properties of the output.
2694 The event is sent when binding to the output object and whenever
2695 any of the properties change.
2696
2697 The physical size can be set to zero if it doesn't make sense for this
2698 output (e.g. for projectors or virtual outputs).
2699
2700 The geometry event will be followed by a done event (starting from
2701 version 2).
2702
2703 Note: wl_output only advertises partial information about the output
2704 position and identification. Some compositors, for instance those not
2705 implementing a desktop-style output layout or those exposing virtual
2706 outputs, might fake this information. Instead of using x and y, clients
2707 should use xdg_output.logical_position. Instead of using make and model,
2708 clients should use name and description.
2709 </description>
2710 <arg name="x" type="int"
2711 summary="x position within the global compositor space"/>
2712 <arg name="y" type="int"
2713 summary="y position within the global compositor space"/>
2714 <arg name="physical_width" type="int"
2715 summary="width in millimeters of the output"/>
2716 <arg name="physical_height" type="int"
2717 summary="height in millimeters of the output"/>
2718 <arg name="subpixel" type="int" enum="subpixel"
2719 summary="subpixel orientation of the output"/>
2720 <arg name="make" type="string"
2721 summary="textual description of the manufacturer"/>
2722 <arg name="model" type="string"
2723 summary="textual description of the model"/>
2724 <arg name="transform" type="int" enum="transform"
2725 summary="transform that maps framebuffer to output"/>
2726 </event>
2727
2728 <enum name="mode" bitfield="true">
2729 <description summary="mode information">
2730 These flags describe properties of an output mode.
2731 They are used in the flags bitfield of the mode event.
2732 </description>
2733 <entry name="current" value="0x1"
2734 summary="indicates this is the current mode"/>
2735 <entry name="preferred" value="0x2"
2736 summary="indicates this is the preferred mode"/>
2737 </enum>
2738
2739 <event name="mode">
2740 <description summary="advertise available modes for the output">
2741 The mode event describes an available mode for the output.
2742
2743 The event is sent when binding to the output object and there
2744 will always be one mode, the current mode. The event is sent
2745 again if an output changes mode, for the mode that is now
2746 current. In other words, the current mode is always the last
2747 mode that was received with the current flag set.
2748
2749 Non-current modes are deprecated. A compositor can decide to only
2750 advertise the current mode and never send other modes. Clients
2751 should not rely on non-current modes.
2752
2753 The size of a mode is given in physical hardware units of
2754 the output device. This is not necessarily the same as
2755 the output size in the global compositor space. For instance,
2756 the output may be scaled, as described in wl_output.scale,
2757 or transformed, as described in wl_output.transform. Clients
2758 willing to retrieve the output size in the global compositor
2759 space should use xdg_output.logical_size instead.
2760
2761 The vertical refresh rate can be set to zero if it doesn't make
2762 sense for this output (e.g. for virtual outputs).
2763
2764 The mode event will be followed by a done event (starting from
2765 version 2).
2766
2767 Clients should not use the refresh rate to schedule frames. Instead,
2768 they should use the wl_surface.frame event or the presentation-time
2769 protocol.
2770
2771 Note: this information is not always meaningful for all outputs. Some
2772 compositors, such as those exposing virtual outputs, might fake the
2773 refresh rate or the size.
2774 </description>
2775 <arg name="flags" type="uint" enum="mode" summary="bitfield of mode flags"/>
2776 <arg name="width" type="int" summary="width of the mode in hardware units"/>
2777 <arg name="height" type="int" summary="height of the mode in hardware units"/>
2778 <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
2779 </event>
2780
2781 <!-- Version 2 additions -->
2782
2783 <event name="done" since="2">
2784 <description summary="sent all information about output">
2785 This event is sent after all other properties have been
2786 sent after binding to the output object and after any
2787 other property changes done after that. This allows
2788 changes to the output properties to be seen as
2789 atomic, even if they happen via multiple events.
2790 </description>
2791 </event>
2792
2793 <event name="scale" since="2">
2794 <description summary="output scaling properties">
2795 This event contains scaling geometry information
2796 that is not in the geometry event. It may be sent after
2797 binding the output object or if the output scale changes
2798 later. If it is not sent, the client should assume a
2799 scale of 1.
2800
2801 A scale larger than 1 means that the compositor will
2802 automatically scale surface buffers by this amount
2803 when rendering. This is used for very high resolution
2804 displays where applications rendering at the native
2805 resolution would be too small to be legible.
2806
2807 It is intended that scaling aware clients track the
2808 current output of a surface, and if it is on a scaled
2809 output it should use wl_surface.set_buffer_scale with
2810 the scale of the output. That way the compositor can
2811 avoid scaling the surface, and the client can supply
2812 a higher detail image.
2813
2814 The scale event will be followed by a done event.
2815 </description>
2816 <arg name="factor" type="int" summary="scaling factor of output"/>
2817 </event>
2818
2819 <!-- Version 3 additions -->
2820
2821 <request name="release" type="destructor" since="3">
2822 <description summary="release the output object">
2823 Using this request a client can tell the server that it is not going to
2824 use the output object anymore.
2825 </description>
2826 </request>
2827
2828 <!-- Version 4 additions -->
2829
2830 <event name="name" since="4">
2831 <description summary="name of this output">
2832 Many compositors will assign user-friendly names to their outputs, show
2833 them to the user, allow the user to refer to an output, etc. The client
2834 may wish to know this name as well to offer the user similar behaviors.
2835
2836 The name is a UTF-8 string with no convention defined for its contents.
2837 Each name is unique among all wl_output globals. The name is only
2838 guaranteed to be unique for the compositor instance.
2839
2840 The same output name is used for all clients for a given wl_output
2841 global. Thus, the name can be shared across processes to refer to a
2842 specific wl_output global.
2843
2844 The name is not guaranteed to be persistent across sessions, thus cannot
2845 be used to reliably identify an output in e.g. configuration files.
2846
2847 Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
2848 not assume that the name is a reflection of an underlying DRM connector,
2849 X11 connection, etc.
2850
2851 The name event is sent after binding the output object. This event is
2852 only sent once per output object, and the name does not change over the
2853 lifetime of the wl_output global.
2854
2855 Compositors may re-use the same output name if the wl_output global is
2856 destroyed and re-created later. Compositors should avoid re-using the
2857 same name if possible.
2858
2859 The name event will be followed by a done event.
2860 </description>
2861 <arg name="name" type="string" summary="output name"/>
2862 </event>
2863
2864 <event name="description" since="4">
2865 <description summary="human-readable description of this output">
2866 Many compositors can produce human-readable descriptions of their
2867 outputs. The client may wish to know this description as well, e.g. for
2868 output selection purposes.
2869
2870 The description is a UTF-8 string with no convention defined for its
2871 contents. The description is not guaranteed to be unique among all
2872 wl_output globals. Examples might include 'Foocorp 11" Display' or
2873 'Virtual X11 output via :1'.
2874
2875 The description event is sent after binding the output object and
2876 whenever the description changes. The description is optional, and may
2877 not be sent at all.
2878
2879 The description event will be followed by a done event.
2880 </description>
2881 <arg name="description" type="string" summary="output description"/>
2882 </event>
2883 </interface>
2884
2885 <interface name="wl_region" version="1">
2886 <description summary="region interface">
2887 A region object describes an area.
2888
2889 Region objects are used to describe the opaque and input
2890 regions of a surface.
2891 </description>
2892
2893 <request name="destroy" type="destructor">
2894 <description summary="destroy region">
2895 Destroy the region. This will invalidate the object ID.
2896 </description>
2897 </request>
2898
2899 <request name="add">
2900 <description summary="add rectangle to region">
2901 Add the specified rectangle to the region.
2902 </description>
2903 <arg name="x" type="int" summary="region-local x coordinate"/>
2904 <arg name="y" type="int" summary="region-local y coordinate"/>
2905 <arg name="width" type="int" summary="rectangle width"/>
2906 <arg name="height" type="int" summary="rectangle height"/>
2907 </request>
2908
2909 <request name="subtract">
2910 <description summary="subtract rectangle from region">
2911 Subtract the specified rectangle from the region.
2912 </description>
2913 <arg name="x" type="int" summary="region-local x coordinate"/>
2914 <arg name="y" type="int" summary="region-local y coordinate"/>
2915 <arg name="width" type="int" summary="rectangle width"/>
2916 <arg name="height" type="int" summary="rectangle height"/>
2917 </request>
2918 </interface>
2919
2920 <interface name="wl_subcompositor" version="1">
2921 <description summary="sub-surface compositing">
2922 The global interface exposing sub-surface compositing capabilities.
2923 A wl_surface, that has sub-surfaces associated, is called the
2924 parent surface. Sub-surfaces can be arbitrarily nested and create
2925 a tree of sub-surfaces.
2926
2927 The root surface in a tree of sub-surfaces is the main
2928 surface. The main surface cannot be a sub-surface, because
2929 sub-surfaces must always have a parent.
2930
2931 A main surface with its sub-surfaces forms a (compound) window.
2932 For window management purposes, this set of wl_surface objects is
2933 to be considered as a single window, and it should also behave as
2934 such.
2935
2936 The aim of sub-surfaces is to offload some of the compositing work
2937 within a window from clients to the compositor. A prime example is
2938 a video player with decorations and video in separate wl_surface
2939 objects. This should allow the compositor to pass YUV video buffer
2940 processing to dedicated overlay hardware when possible.
2941 </description>
2942
2943 <request name="destroy" type="destructor">
2944 <description summary="unbind from the subcompositor interface">
2945 Informs the server that the client will not be using this
2946 protocol object anymore. This does not affect any other
2947 objects, wl_subsurface objects included.
2948 </description>
2949 </request>
2950
2951 <enum name="error">
2952 <entry name="bad_surface" value="0"
2953 summary="the to-be sub-surface is invalid"/>
2954 <entry name="bad_parent" value="1"
2955 summary="the to-be sub-surface parent is invalid"/>
2956 </enum>
2957
2958 <request name="get_subsurface">
2959 <description summary="give a surface the role sub-surface">
2960 Create a sub-surface interface for the given surface, and
2961 associate it with the given parent surface. This turns a
2962 plain wl_surface into a sub-surface.
2963
2964 The to-be sub-surface must not already have another role, and it
2965 must not have an existing wl_subsurface object. Otherwise the
2966 bad_surface protocol error is raised.
2967
2968 Adding sub-surfaces to a parent is a double-buffered operation on the
2969 parent (see wl_surface.commit). The effect of adding a sub-surface
2970 becomes visible on the next time the state of the parent surface is
2971 applied.
2972
2973 The parent surface must not be one of the child surface's descendants,
2974 and the parent must be different from the child surface, otherwise the
2975 bad_parent protocol error is raised.
2976
2977 This request modifies the behaviour of wl_surface.commit request on
2978 the sub-surface, see the documentation on wl_subsurface interface.
2979 </description>
2980 <arg name="id" type="new_id" interface="wl_subsurface"
2981 summary="the new sub-surface object ID"/>
2982 <arg name="surface" type="object" interface="wl_surface"
2983 summary="the surface to be turned into a sub-surface"/>
2984 <arg name="parent" type="object" interface="wl_surface"
2985 summary="the parent surface"/>
2986 </request>
2987 </interface>
2988
2989 <interface name="wl_subsurface" version="1">
2990 <description summary="sub-surface interface to a wl_surface">
2991 An additional interface to a wl_surface object, which has been
2992 made a sub-surface. A sub-surface has one parent surface. A
2993 sub-surface's size and position are not limited to that of the parent.
2994 Particularly, a sub-surface is not automatically clipped to its
2995 parent's area.
2996
2997 A sub-surface becomes mapped, when a non-NULL wl_buffer is applied
2998 and the parent surface is mapped. The order of which one happens
2999 first is irrelevant. A sub-surface is hidden if the parent becomes
3000 hidden, or if a NULL wl_buffer is applied. These rules apply
3001 recursively through the tree of surfaces.
3002
3003 The behaviour of a wl_surface.commit request on a sub-surface
3004 depends on the sub-surface's mode. The possible modes are
3005 synchronized and desynchronized, see methods
3006 wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized
3007 mode caches the wl_surface state to be applied when the parent's
3008 state gets applied, and desynchronized mode applies the pending
3009 wl_surface state directly. A sub-surface is initially in the
3010 synchronized mode.
3011
3012 Sub-surfaces also have another kind of state, which is managed by
3013 wl_subsurface requests, as opposed to wl_surface requests. This
3014 state includes the sub-surface position relative to the parent
3015 surface (wl_subsurface.set_position), and the stacking order of
3016 the parent and its sub-surfaces (wl_subsurface.place_above and
3017 .place_below). This state is applied when the parent surface's
3018 wl_surface state is applied, regardless of the sub-surface's mode.
3019 As the exception, set_sync and set_desync are effective immediately.
3020
3021 The main surface can be thought to be always in desynchronized mode,
3022 since it does not have a parent in the sub-surfaces sense.
3023
3024 Even if a sub-surface is in desynchronized mode, it will behave as
3025 in synchronized mode, if its parent surface behaves as in
3026 synchronized mode. This rule is applied recursively throughout the
3027 tree of surfaces. This means, that one can set a sub-surface into
3028 synchronized mode, and then assume that all its child and grand-child
3029 sub-surfaces are synchronized, too, without explicitly setting them.
3030
3031 Destroying a sub-surface takes effect immediately. If you need to
3032 synchronize the removal of a sub-surface to the parent surface update,
3033 unmap the sub-surface first by attaching a NULL wl_buffer, update parent,
3034 and then destroy the sub-surface.
3035
3036 If the parent wl_surface object is destroyed, the sub-surface is
3037 unmapped.
3038 </description>
3039
3040 <request name="destroy" type="destructor">
3041 <description summary="remove sub-surface interface">
3042 The sub-surface interface is removed from the wl_surface object
3043 that was turned into a sub-surface with a
3044 wl_subcompositor.get_subsurface request. The wl_surface's association
3045 to the parent is deleted. The wl_surface is unmapped immediately.
3046 </description>
3047 </request>
3048
3049 <enum name="error">
3050 <entry name="bad_surface" value="0"
3051 summary="wl_surface is not a sibling or the parent"/>
3052 </enum>
3053
3054 <request name="set_position">
3055 <description summary="reposition the sub-surface">
3056 This schedules a sub-surface position change.
3057 The sub-surface will be moved so that its origin (top left
3058 corner pixel) will be at the location x, y of the parent surface
3059 coordinate system. The coordinates are not restricted to the parent
3060 surface area. Negative values are allowed.
3061
3062 The scheduled coordinates will take effect whenever the state of the
3063 parent surface is applied. When this happens depends on whether the
3064 parent surface is in synchronized mode or not. See
3065 wl_subsurface.set_sync and wl_subsurface.set_desync for details.
3066
3067 If more than one set_position request is invoked by the client before
3068 the commit of the parent surface, the position of a new request always
3069 replaces the scheduled position from any previous request.
3070
3071 The initial position is 0, 0.
3072 </description>
3073 <arg name="x" type="int" summary="x coordinate in the parent surface"/>
3074 <arg name="y" type="int" summary="y coordinate in the parent surface"/>
3075 </request>
3076
3077 <request name="place_above">
3078 <description summary="restack the sub-surface">
3079 This sub-surface is taken from the stack, and put back just
3080 above the reference surface, changing the z-order of the sub-surfaces.
3081 The reference surface must be one of the sibling surfaces, or the
3082 parent surface. Using any other surface, including this sub-surface,
3083 will cause a protocol error.
3084
3085 The z-order is double-buffered. Requests are handled in order and
3086 applied immediately to a pending state. The final pending state is
3087 copied to the active state the next time the state of the parent
3088 surface is applied. When this happens depends on whether the parent
3089 surface is in synchronized mode or not. See wl_subsurface.set_sync and
3090 wl_subsurface.set_desync for details.
3091
3092 A new sub-surface is initially added as the top-most in the stack
3093 of its siblings and parent.
3094 </description>
3095 <arg name="sibling" type="object" interface="wl_surface"
3096 summary="the reference surface"/>
3097 </request>
3098
3099 <request name="place_below">
3100 <description summary="restack the sub-surface">
3101 The sub-surface is placed just below the reference surface.
3102 See wl_subsurface.place_above.
3103 </description>
3104 <arg name="sibling" type="object" interface="wl_surface"
3105 summary="the reference surface"/>
3106 </request>
3107
3108 <request name="set_sync">
3109 <description summary="set sub-surface to synchronized mode">
3110 Change the commit behaviour of the sub-surface to synchronized
3111 mode, also described as the parent dependent mode.
3112
3113 In synchronized mode, wl_surface.commit on a sub-surface will
3114 accumulate the committed state in a cache, but the state will
3115 not be applied and hence will not change the compositor output.
3116 The cached state is applied to the sub-surface immediately after
3117 the parent surface's state is applied. This ensures atomic
3118 updates of the parent and all its synchronized sub-surfaces.
3119 Applying the cached state will invalidate the cache, so further
3120 parent surface commits do not (re-)apply old state.
3121
3122 See wl_subsurface for the recursive effect of this mode.
3123 </description>
3124 </request>
3125
3126 <request name="set_desync">
3127 <description summary="set sub-surface to desynchronized mode">
3128 Change the commit behaviour of the sub-surface to desynchronized
3129 mode, also described as independent or freely running mode.
3130
3131 In desynchronized mode, wl_surface.commit on a sub-surface will
3132 apply the pending state directly, without caching, as happens
3133 normally with a wl_surface. Calling wl_surface.commit on the
3134 parent surface has no effect on the sub-surface's wl_surface
3135 state. This mode allows a sub-surface to be updated on its own.
3136
3137 If cached state exists when wl_surface.commit is called in
3138 desynchronized mode, the pending state is added to the cached
3139 state, and applied as a whole. This invalidates the cache.
3140
3141 Note: even if a sub-surface is set to desynchronized, a parent
3142 sub-surface may override it to behave as synchronized. For details,
3143 see wl_subsurface.
3144
3145 If a surface's parent surface behaves as desynchronized, then
3146 the cached state is applied on set_desync.
3147 </description>
3148 </request>
3149 </interface>
3150
3151</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/xdg-activation-v1.xml b/raylib/src/external/glfw/deps/wayland/xdg-activation-v1.xml
new file mode 100644
index 0000000..9adcc27
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/xdg-activation-v1.xml
@@ -0,0 +1,200 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="xdg_activation_v1">
3
4 <copyright>
5 Copyright © 2020 Aleix Pol Gonzalez &lt;aleixpol@kde.org&gt;
6 Copyright © 2020 Carlos Garnacho &lt;carlosg@gnome.org&gt;
7
8 Permission is hereby granted, free of charge, to any person obtaining a
9 copy of this software and associated documentation files (the "Software"),
10 to deal in the Software without restriction, including without limitation
11 the rights to use, copy, modify, merge, publish, distribute, sublicense,
12 and/or sell copies of the Software, and to permit persons to whom the
13 Software is furnished to do so, subject to the following conditions:
14
15 The above copyright notice and this permission notice (including the next
16 paragraph) shall be included in all copies or substantial portions of the
17 Software.
18
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25 DEALINGS IN THE SOFTWARE.
26 </copyright>
27
28 <description summary="Protocol for requesting activation of surfaces">
29 The way for a client to pass focus to another toplevel is as follows.
30
31 The client that intends to activate another toplevel uses the
32 xdg_activation_v1.get_activation_token request to get an activation token.
33 This token is then forwarded to the client, which is supposed to activate
34 one of its surfaces, through a separate band of communication.
35
36 One established way of doing this is through the XDG_ACTIVATION_TOKEN
37 environment variable of a newly launched child process. The child process
38 should unset the environment variable again right after reading it out in
39 order to avoid propagating it to other child processes.
40
41 Another established way exists for Applications implementing the D-Bus
42 interface org.freedesktop.Application, which should get their token under
43 activation-token on their platform_data.
44
45 In general activation tokens may be transferred across clients through
46 means not described in this protocol.
47
48 The client to be activated will then pass the token
49 it received to the xdg_activation_v1.activate request. The compositor can
50 then use this token to decide how to react to the activation request.
51
52 The token the activating client gets may be ineffective either already at
53 the time it receives it, for example if it was not focused, for focus
54 stealing prevention. The activating client will have no way to discover
55 the validity of the token, and may still forward it to the to be activated
56 client.
57
58 The created activation token may optionally get information attached to it
59 that can be used by the compositor to identify the application that we
60 intend to activate. This can for example be used to display a visual hint
61 about what application is being started.
62
63 Warning! The protocol described in this file is currently in the testing
64 phase. Backward compatible changes may be added together with the
65 corresponding interface version bump. Backward incompatible changes can
66 only be done by creating a new major version of the extension.
67 </description>
68
69 <interface name="xdg_activation_v1" version="1">
70 <description summary="interface for activating surfaces">
71 A global interface used for informing the compositor about applications
72 being activated or started, or for applications to request to be
73 activated.
74 </description>
75
76 <request name="destroy" type="destructor">
77 <description summary="destroy the xdg_activation object">
78 Notify the compositor that the xdg_activation object will no longer be
79 used.
80
81 The child objects created via this interface are unaffected and should
82 be destroyed separately.
83 </description>
84 </request>
85
86 <request name="get_activation_token">
87 <description summary="requests a token">
88 Creates an xdg_activation_token_v1 object that will provide
89 the initiating client with a unique token for this activation. This
90 token should be offered to the clients to be activated.
91 </description>
92
93 <arg name="id" type="new_id" interface="xdg_activation_token_v1"/>
94 </request>
95
96 <request name="activate">
97 <description summary="notify new interaction being available">
98 Requests surface activation. It's up to the compositor to display
99 this information as desired, for example by placing the surface above
100 the rest.
101
102 The compositor may know who requested this by checking the activation
103 token and might decide not to follow through with the activation if it's
104 considered unwanted.
105
106 Compositors can ignore unknown activation tokens when an invalid
107 token is passed.
108 </description>
109 <arg name="token" type="string" summary="the activation token of the initiating client"/>
110 <arg name="surface" type="object" interface="wl_surface"
111 summary="the wl_surface to activate"/>
112 </request>
113 </interface>
114
115 <interface name="xdg_activation_token_v1" version="1">
116 <description summary="an exported activation handle">
117 An object for setting up a token and receiving a token handle that can
118 be passed as an activation token to another client.
119
120 The object is created using the xdg_activation_v1.get_activation_token
121 request. This object should then be populated with the app_id, surface
122 and serial information and committed. The compositor shall then issue a
123 done event with the token. In case the request's parameters are invalid,
124 the compositor will provide an invalid token.
125 </description>
126
127 <enum name="error">
128 <entry name="already_used" value="0"
129 summary="The token has already been used previously"/>
130 </enum>
131
132 <request name="set_serial">
133 <description summary="specifies the seat and serial of the activating event">
134 Provides information about the seat and serial event that requested the
135 token.
136
137 The serial can come from an input or focus event. For instance, if a
138 click triggers the launch of a third-party client, the launcher client
139 should send a set_serial request with the serial and seat from the
140 wl_pointer.button event.
141
142 Some compositors might refuse to activate toplevels when the token
143 doesn't have a valid and recent enough event serial.
144
145 Must be sent before commit. This information is optional.
146 </description>
147 <arg name="serial" type="uint"
148 summary="the serial of the event that triggered the activation"/>
149 <arg name="seat" type="object" interface="wl_seat"
150 summary="the wl_seat of the event"/>
151 </request>
152
153 <request name="set_app_id">
154 <description summary="specifies the application being activated">
155 The requesting client can specify an app_id to associate the token
156 being created with it.
157
158 Must be sent before commit. This information is optional.
159 </description>
160 <arg name="app_id" type="string"
161 summary="the application id of the client being activated."/>
162 </request>
163
164 <request name="set_surface">
165 <description summary="specifies the surface requesting activation">
166 This request sets the surface requesting the activation. Note, this is
167 different from the surface that will be activated.
168
169 Some compositors might refuse to activate toplevels when the token
170 doesn't have a requesting surface.
171
172 Must be sent before commit. This information is optional.
173 </description>
174 <arg name="surface" type="object" interface="wl_surface"
175 summary="the requesting surface"/>
176 </request>
177
178 <request name="commit">
179 <description summary="issues the token request">
180 Requests an activation token based on the different parameters that
181 have been offered through set_serial, set_surface and set_app_id.
182 </description>
183 </request>
184
185 <event name="done">
186 <description summary="the exported activation token">
187 The 'done' event contains the unique token of this activation request
188 and notifies that the provider is done.
189 </description>
190 <arg name="token" type="string" summary="the exported activation token"/>
191 </event>
192
193 <request name="destroy" type="destructor">
194 <description summary="destroy the xdg_activation_token_v1 object">
195 Notify the compositor that the xdg_activation_token_v1 object will no
196 longer be used. The received token stays valid.
197 </description>
198 </request>
199 </interface>
200</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/xdg-decoration-unstable-v1.xml b/raylib/src/external/glfw/deps/wayland/xdg-decoration-unstable-v1.xml
new file mode 100644
index 0000000..e596775
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/xdg-decoration-unstable-v1.xml
@@ -0,0 +1,156 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="xdg_decoration_unstable_v1">
3 <copyright>
4 Copyright © 2018 Simon Ser
5
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice (including the next
14 paragraph) shall be included in all copies or substantial portions of the
15 Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23 DEALINGS IN THE SOFTWARE.
24 </copyright>
25
26 <interface name="zxdg_decoration_manager_v1" version="1">
27 <description summary="window decoration manager">
28 This interface allows a compositor to announce support for server-side
29 decorations.
30
31 A window decoration is a set of window controls as deemed appropriate by
32 the party managing them, such as user interface components used to move,
33 resize and change a window's state.
34
35 A client can use this protocol to request being decorated by a supporting
36 compositor.
37
38 If compositor and client do not negotiate the use of a server-side
39 decoration using this protocol, clients continue to self-decorate as they
40 see fit.
41
42 Warning! The protocol described in this file is experimental and
43 backward incompatible changes may be made. Backward compatible changes
44 may be added together with the corresponding interface version bump.
45 Backward incompatible changes are done by bumping the version number in
46 the protocol and interface names and resetting the interface version.
47 Once the protocol is to be declared stable, the 'z' prefix and the
48 version number in the protocol and interface names are removed and the
49 interface version number is reset.
50 </description>
51
52 <request name="destroy" type="destructor">
53 <description summary="destroy the decoration manager object">
54 Destroy the decoration manager. This doesn't destroy objects created
55 with the manager.
56 </description>
57 </request>
58
59 <request name="get_toplevel_decoration">
60 <description summary="create a new toplevel decoration object">
61 Create a new decoration object associated with the given toplevel.
62
63 Creating an xdg_toplevel_decoration from an xdg_toplevel which has a
64 buffer attached or committed is a client error, and any attempts by a
65 client to attach or manipulate a buffer prior to the first
66 xdg_toplevel_decoration.configure event must also be treated as
67 errors.
68 </description>
69 <arg name="id" type="new_id" interface="zxdg_toplevel_decoration_v1"/>
70 <arg name="toplevel" type="object" interface="xdg_toplevel"/>
71 </request>
72 </interface>
73
74 <interface name="zxdg_toplevel_decoration_v1" version="1">
75 <description summary="decoration object for a toplevel surface">
76 The decoration object allows the compositor to toggle server-side window
77 decorations for a toplevel surface. The client can request to switch to
78 another mode.
79
80 The xdg_toplevel_decoration object must be destroyed before its
81 xdg_toplevel.
82 </description>
83
84 <enum name="error">
85 <entry name="unconfigured_buffer" value="0"
86 summary="xdg_toplevel has a buffer attached before configure"/>
87 <entry name="already_constructed" value="1"
88 summary="xdg_toplevel already has a decoration object"/>
89 <entry name="orphaned" value="2"
90 summary="xdg_toplevel destroyed before the decoration object"/>
91 </enum>
92
93 <request name="destroy" type="destructor">
94 <description summary="destroy the decoration object">
95 Switch back to a mode without any server-side decorations at the next
96 commit.
97 </description>
98 </request>
99
100 <enum name="mode">
101 <description summary="window decoration modes">
102 These values describe window decoration modes.
103 </description>
104 <entry name="client_side" value="1"
105 summary="no server-side window decoration"/>
106 <entry name="server_side" value="2"
107 summary="server-side window decoration"/>
108 </enum>
109
110 <request name="set_mode">
111 <description summary="set the decoration mode">
112 Set the toplevel surface decoration mode. This informs the compositor
113 that the client prefers the provided decoration mode.
114
115 After requesting a decoration mode, the compositor will respond by
116 emitting an xdg_surface.configure event. The client should then update
117 its content, drawing it without decorations if the received mode is
118 server-side decorations. The client must also acknowledge the configure
119 when committing the new content (see xdg_surface.ack_configure).
120
121 The compositor can decide not to use the client's mode and enforce a
122 different mode instead.
123
124 Clients whose decoration mode depend on the xdg_toplevel state may send
125 a set_mode request in response to an xdg_surface.configure event and wait
126 for the next xdg_surface.configure event to prevent unwanted state.
127 Such clients are responsible for preventing configure loops and must
128 make sure not to send multiple successive set_mode requests with the
129 same decoration mode.
130 </description>
131 <arg name="mode" type="uint" enum="mode" summary="the decoration mode"/>
132 </request>
133
134 <request name="unset_mode">
135 <description summary="unset the decoration mode">
136 Unset the toplevel surface decoration mode. This informs the compositor
137 that the client doesn't prefer a particular decoration mode.
138
139 This request has the same semantics as set_mode.
140 </description>
141 </request>
142
143 <event name="configure">
144 <description summary="suggest a surface change">
145 The configure event asks the client to change its decoration mode. The
146 configured state should not be applied immediately. Clients must send an
147 ack_configure in response to this event. See xdg_surface.configure and
148 xdg_surface.ack_configure for details.
149
150 A configure event can be sent at any time. The specified mode must be
151 obeyed by the client.
152 </description>
153 <arg name="mode" type="uint" enum="mode" summary="the decoration mode"/>
154 </event>
155 </interface>
156</protocol>
diff --git a/raylib/src/external/glfw/deps/wayland/xdg-shell.xml b/raylib/src/external/glfw/deps/wayland/xdg-shell.xml
new file mode 100644
index 0000000..777eaa7
--- /dev/null
+++ b/raylib/src/external/glfw/deps/wayland/xdg-shell.xml
@@ -0,0 +1,1370 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="xdg_shell">
3
4 <copyright>
5 Copyright © 2008-2013 Kristian Høgsberg
6 Copyright © 2013 Rafael Antognolli
7 Copyright © 2013 Jasper St. Pierre
8 Copyright © 2010-2013 Intel Corporation
9 Copyright © 2015-2017 Samsung Electronics Co., Ltd
10 Copyright © 2015-2017 Red Hat Inc.
11
12 Permission is hereby granted, free of charge, to any person obtaining a
13 copy of this software and associated documentation files (the "Software"),
14 to deal in the Software without restriction, including without limitation
15 the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 and/or sell copies of the Software, and to permit persons to whom the
17 Software is furnished to do so, subject to the following conditions:
18
19 The above copyright notice and this permission notice (including the next
20 paragraph) shall be included in all copies or substantial portions of the
21 Software.
22
23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
26 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29 DEALINGS IN THE SOFTWARE.
30 </copyright>
31
32 <interface name="xdg_wm_base" version="6">
33 <description summary="create desktop-style surfaces">
34 The xdg_wm_base interface is exposed as a global object enabling clients
35 to turn their wl_surfaces into windows in a desktop environment. It
36 defines the basic functionality needed for clients and the compositor to
37 create windows that can be dragged, resized, maximized, etc, as well as
38 creating transient windows such as popup menus.
39 </description>
40
41 <enum name="error">
42 <entry name="role" value="0" summary="given wl_surface has another role"/>
43 <entry name="defunct_surfaces" value="1"
44 summary="xdg_wm_base was destroyed before children"/>
45 <entry name="not_the_topmost_popup" value="2"
46 summary="the client tried to map or destroy a non-topmost popup"/>
47 <entry name="invalid_popup_parent" value="3"
48 summary="the client specified an invalid popup parent surface"/>
49 <entry name="invalid_surface_state" value="4"
50 summary="the client provided an invalid surface state"/>
51 <entry name="invalid_positioner" value="5"
52 summary="the client provided an invalid positioner"/>
53 <entry name="unresponsive" value="6"
54 summary="the client didn’t respond to a ping event in time"/>
55 </enum>
56
57 <request name="destroy" type="destructor">
58 <description summary="destroy xdg_wm_base">
59 Destroy this xdg_wm_base object.
60
61 Destroying a bound xdg_wm_base object while there are surfaces
62 still alive created by this xdg_wm_base object instance is illegal
63 and will result in a defunct_surfaces error.
64 </description>
65 </request>
66
67 <request name="create_positioner">
68 <description summary="create a positioner object">
69 Create a positioner object. A positioner object is used to position
70 surfaces relative to some parent surface. See the interface description
71 and xdg_surface.get_popup for details.
72 </description>
73 <arg name="id" type="new_id" interface="xdg_positioner"/>
74 </request>
75
76 <request name="get_xdg_surface">
77 <description summary="create a shell surface from a surface">
78 This creates an xdg_surface for the given surface. While xdg_surface
79 itself is not a role, the corresponding surface may only be assigned
80 a role extending xdg_surface, such as xdg_toplevel or xdg_popup. It is
81 illegal to create an xdg_surface for a wl_surface which already has an
82 assigned role and this will result in a role error.
83
84 This creates an xdg_surface for the given surface. An xdg_surface is
85 used as basis to define a role to a given surface, such as xdg_toplevel
86 or xdg_popup. It also manages functionality shared between xdg_surface
87 based surface roles.
88
89 See the documentation of xdg_surface for more details about what an
90 xdg_surface is and how it is used.
91 </description>
92 <arg name="id" type="new_id" interface="xdg_surface"/>
93 <arg name="surface" type="object" interface="wl_surface"/>
94 </request>
95
96 <request name="pong">
97 <description summary="respond to a ping event">
98 A client must respond to a ping event with a pong request or
99 the client may be deemed unresponsive. See xdg_wm_base.ping
100 and xdg_wm_base.error.unresponsive.
101 </description>
102 <arg name="serial" type="uint" summary="serial of the ping event"/>
103 </request>
104
105 <event name="ping">
106 <description summary="check if the client is alive">
107 The ping event asks the client if it's still alive. Pass the
108 serial specified in the event back to the compositor by sending
109 a "pong" request back with the specified serial. See xdg_wm_base.pong.
110
111 Compositors can use this to determine if the client is still
112 alive. It's unspecified what will happen if the client doesn't
113 respond to the ping request, or in what timeframe. Clients should
114 try to respond in a reasonable amount of time. The “unresponsive”
115 error is provided for compositors that wish to disconnect unresponsive
116 clients.
117
118 A compositor is free to ping in any way it wants, but a client must
119 always respond to any xdg_wm_base object it created.
120 </description>
121 <arg name="serial" type="uint" summary="pass this to the pong request"/>
122 </event>
123 </interface>
124
125 <interface name="xdg_positioner" version="6">
126 <description summary="child surface positioner">
127 The xdg_positioner provides a collection of rules for the placement of a
128 child surface relative to a parent surface. Rules can be defined to ensure
129 the child surface remains within the visible area's borders, and to
130 specify how the child surface changes its position, such as sliding along
131 an axis, or flipping around a rectangle. These positioner-created rules are
132 constrained by the requirement that a child surface must intersect with or
133 be at least partially adjacent to its parent surface.
134
135 See the various requests for details about possible rules.
136
137 At the time of the request, the compositor makes a copy of the rules
138 specified by the xdg_positioner. Thus, after the request is complete the
139 xdg_positioner object can be destroyed or reused; further changes to the
140 object will have no effect on previous usages.
141
142 For an xdg_positioner object to be considered complete, it must have a
143 non-zero size set by set_size, and a non-zero anchor rectangle set by
144 set_anchor_rect. Passing an incomplete xdg_positioner object when
145 positioning a surface raises an invalid_positioner error.
146 </description>
147
148 <enum name="error">
149 <entry name="invalid_input" value="0" summary="invalid input provided"/>
150 </enum>
151
152 <request name="destroy" type="destructor">
153 <description summary="destroy the xdg_positioner object">
154 Notify the compositor that the xdg_positioner will no longer be used.
155 </description>
156 </request>
157
158 <request name="set_size">
159 <description summary="set the size of the to-be positioned rectangle">
160 Set the size of the surface that is to be positioned with the positioner
161 object. The size is in surface-local coordinates and corresponds to the
162 window geometry. See xdg_surface.set_window_geometry.
163
164 If a zero or negative size is set the invalid_input error is raised.
165 </description>
166 <arg name="width" type="int" summary="width of positioned rectangle"/>
167 <arg name="height" type="int" summary="height of positioned rectangle"/>
168 </request>
169
170 <request name="set_anchor_rect">
171 <description summary="set the anchor rectangle within the parent surface">
172 Specify the anchor rectangle within the parent surface that the child
173 surface will be placed relative to. The rectangle is relative to the
174 window geometry as defined by xdg_surface.set_window_geometry of the
175 parent surface.
176
177 When the xdg_positioner object is used to position a child surface, the
178 anchor rectangle may not extend outside the window geometry of the
179 positioned child's parent surface.
180
181 If a negative size is set the invalid_input error is raised.
182 </description>
183 <arg name="x" type="int" summary="x position of anchor rectangle"/>
184 <arg name="y" type="int" summary="y position of anchor rectangle"/>
185 <arg name="width" type="int" summary="width of anchor rectangle"/>
186 <arg name="height" type="int" summary="height of anchor rectangle"/>
187 </request>
188
189 <enum name="anchor">
190 <entry name="none" value="0"/>
191 <entry name="top" value="1"/>
192 <entry name="bottom" value="2"/>
193 <entry name="left" value="3"/>
194 <entry name="right" value="4"/>
195 <entry name="top_left" value="5"/>
196 <entry name="bottom_left" value="6"/>
197 <entry name="top_right" value="7"/>
198 <entry name="bottom_right" value="8"/>
199 </enum>
200
201 <request name="set_anchor">
202 <description summary="set anchor rectangle anchor">
203 Defines the anchor point for the anchor rectangle. The specified anchor
204 is used derive an anchor point that the child surface will be
205 positioned relative to. If a corner anchor is set (e.g. 'top_left' or
206 'bottom_right'), the anchor point will be at the specified corner;
207 otherwise, the derived anchor point will be centered on the specified
208 edge, or in the center of the anchor rectangle if no edge is specified.
209 </description>
210 <arg name="anchor" type="uint" enum="anchor"
211 summary="anchor"/>
212 </request>
213
214 <enum name="gravity">
215 <entry name="none" value="0"/>
216 <entry name="top" value="1"/>
217 <entry name="bottom" value="2"/>
218 <entry name="left" value="3"/>
219 <entry name="right" value="4"/>
220 <entry name="top_left" value="5"/>
221 <entry name="bottom_left" value="6"/>
222 <entry name="top_right" value="7"/>
223 <entry name="bottom_right" value="8"/>
224 </enum>
225
226 <request name="set_gravity">
227 <description summary="set child surface gravity">
228 Defines in what direction a surface should be positioned, relative to
229 the anchor point of the parent surface. If a corner gravity is
230 specified (e.g. 'bottom_right' or 'top_left'), then the child surface
231 will be placed towards the specified gravity; otherwise, the child
232 surface will be centered over the anchor point on any axis that had no
233 gravity specified. If the gravity is not in the ‘gravity’ enum, an
234 invalid_input error is raised.
235 </description>
236 <arg name="gravity" type="uint" enum="gravity"
237 summary="gravity direction"/>
238 </request>
239
240 <enum name="constraint_adjustment" bitfield="true">
241 <description summary="constraint adjustments">
242 The constraint adjustment value define ways the compositor will adjust
243 the position of the surface, if the unadjusted position would result
244 in the surface being partly constrained.
245
246 Whether a surface is considered 'constrained' is left to the compositor
247 to determine. For example, the surface may be partly outside the
248 compositor's defined 'work area', thus necessitating the child surface's
249 position be adjusted until it is entirely inside the work area.
250
251 The adjustments can be combined, according to a defined precedence: 1)
252 Flip, 2) Slide, 3) Resize.
253 </description>
254 <entry name="none" value="0">
255 <description summary="don't move the child surface when constrained">
256 Don't alter the surface position even if it is constrained on some
257 axis, for example partially outside the edge of an output.
258 </description>
259 </entry>
260 <entry name="slide_x" value="1">
261 <description summary="move along the x axis until unconstrained">
262 Slide the surface along the x axis until it is no longer constrained.
263
264 First try to slide towards the direction of the gravity on the x axis
265 until either the edge in the opposite direction of the gravity is
266 unconstrained or the edge in the direction of the gravity is
267 constrained.
268
269 Then try to slide towards the opposite direction of the gravity on the
270 x axis until either the edge in the direction of the gravity is
271 unconstrained or the edge in the opposite direction of the gravity is
272 constrained.
273 </description>
274 </entry>
275 <entry name="slide_y" value="2">
276 <description summary="move along the y axis until unconstrained">
277 Slide the surface along the y axis until it is no longer constrained.
278
279 First try to slide towards the direction of the gravity on the y axis
280 until either the edge in the opposite direction of the gravity is
281 unconstrained or the edge in the direction of the gravity is
282 constrained.
283
284 Then try to slide towards the opposite direction of the gravity on the
285 y axis until either the edge in the direction of the gravity is
286 unconstrained or the edge in the opposite direction of the gravity is
287 constrained.
288 </description>
289 </entry>
290 <entry name="flip_x" value="4">
291 <description summary="invert the anchor and gravity on the x axis">
292 Invert the anchor and gravity on the x axis if the surface is
293 constrained on the x axis. For example, if the left edge of the
294 surface is constrained, the gravity is 'left' and the anchor is
295 'left', change the gravity to 'right' and the anchor to 'right'.
296
297 If the adjusted position also ends up being constrained, the resulting
298 position of the flip_x adjustment will be the one before the
299 adjustment.
300 </description>
301 </entry>
302 <entry name="flip_y" value="8">
303 <description summary="invert the anchor and gravity on the y axis">
304 Invert the anchor and gravity on the y axis if the surface is
305 constrained on the y axis. For example, if the bottom edge of the
306 surface is constrained, the gravity is 'bottom' and the anchor is
307 'bottom', change the gravity to 'top' and the anchor to 'top'.
308
309 The adjusted position is calculated given the original anchor
310 rectangle and offset, but with the new flipped anchor and gravity
311 values.
312
313 If the adjusted position also ends up being constrained, the resulting
314 position of the flip_y adjustment will be the one before the
315 adjustment.
316 </description>
317 </entry>
318 <entry name="resize_x" value="16">
319 <description summary="horizontally resize the surface">
320 Resize the surface horizontally so that it is completely
321 unconstrained.
322 </description>
323 </entry>
324 <entry name="resize_y" value="32">
325 <description summary="vertically resize the surface">
326 Resize the surface vertically so that it is completely unconstrained.
327 </description>
328 </entry>
329 </enum>
330
331 <request name="set_constraint_adjustment">
332 <description summary="set the adjustment to be done when constrained">
333 Specify how the window should be positioned if the originally intended
334 position caused the surface to be constrained, meaning at least
335 partially outside positioning boundaries set by the compositor. The
336 adjustment is set by constructing a bitmask describing the adjustment to
337 be made when the surface is constrained on that axis.
338
339 If no bit for one axis is set, the compositor will assume that the child
340 surface should not change its position on that axis when constrained.
341
342 If more than one bit for one axis is set, the order of how adjustments
343 are applied is specified in the corresponding adjustment descriptions.
344
345 The default adjustment is none.
346 </description>
347 <arg name="constraint_adjustment" type="uint"
348 summary="bit mask of constraint adjustments"/>
349 </request>
350
351 <request name="set_offset">
352 <description summary="set surface position offset">
353 Specify the surface position offset relative to the position of the
354 anchor on the anchor rectangle and the anchor on the surface. For
355 example if the anchor of the anchor rectangle is at (x, y), the surface
356 has the gravity bottom|right, and the offset is (ox, oy), the calculated
357 surface position will be (x + ox, y + oy). The offset position of the
358 surface is the one used for constraint testing. See
359 set_constraint_adjustment.
360
361 An example use case is placing a popup menu on top of a user interface
362 element, while aligning the user interface element of the parent surface
363 with some user interface element placed somewhere in the popup surface.
364 </description>
365 <arg name="x" type="int" summary="surface position x offset"/>
366 <arg name="y" type="int" summary="surface position y offset"/>
367 </request>
368
369 <!-- Version 3 additions -->
370
371 <request name="set_reactive" since="3">
372 <description summary="continuously reconstrain the surface">
373 When set reactive, the surface is reconstrained if the conditions used
374 for constraining changed, e.g. the parent window moved.
375
376 If the conditions changed and the popup was reconstrained, an
377 xdg_popup.configure event is sent with updated geometry, followed by an
378 xdg_surface.configure event.
379 </description>
380 </request>
381
382 <request name="set_parent_size" since="3">
383 <description summary="">
384 Set the parent window geometry the compositor should use when
385 positioning the popup. The compositor may use this information to
386 determine the future state the popup should be constrained using. If
387 this doesn't match the dimension of the parent the popup is eventually
388 positioned against, the behavior is undefined.
389
390 The arguments are given in the surface-local coordinate space.
391 </description>
392 <arg name="parent_width" type="int"
393 summary="future window geometry width of parent"/>
394 <arg name="parent_height" type="int"
395 summary="future window geometry height of parent"/>
396 </request>
397
398 <request name="set_parent_configure" since="3">
399 <description summary="set parent configure this is a response to">
400 Set the serial of an xdg_surface.configure event this positioner will be
401 used in response to. The compositor may use this information together
402 with set_parent_size to determine what future state the popup should be
403 constrained using.
404 </description>
405 <arg name="serial" type="uint"
406 summary="serial of parent configure event"/>
407 </request>
408 </interface>
409
410 <interface name="xdg_surface" version="6">
411 <description summary="desktop user interface surface base interface">
412 An interface that may be implemented by a wl_surface, for
413 implementations that provide a desktop-style user interface.
414
415 It provides a base set of functionality required to construct user
416 interface elements requiring management by the compositor, such as
417 toplevel windows, menus, etc. The types of functionality are split into
418 xdg_surface roles.
419
420 Creating an xdg_surface does not set the role for a wl_surface. In order
421 to map an xdg_surface, the client must create a role-specific object
422 using, e.g., get_toplevel, get_popup. The wl_surface for any given
423 xdg_surface can have at most one role, and may not be assigned any role
424 not based on xdg_surface.
425
426 A role must be assigned before any other requests are made to the
427 xdg_surface object.
428
429 The client must call wl_surface.commit on the corresponding wl_surface
430 for the xdg_surface state to take effect.
431
432 Creating an xdg_surface from a wl_surface which has a buffer attached or
433 committed is a client error, and any attempts by a client to attach or
434 manipulate a buffer prior to the first xdg_surface.configure call must
435 also be treated as errors.
436
437 After creating a role-specific object and setting it up, the client must
438 perform an initial commit without any buffer attached. The compositor
439 will reply with initial wl_surface state such as
440 wl_surface.preferred_buffer_scale followed by an xdg_surface.configure
441 event. The client must acknowledge it and is then allowed to attach a
442 buffer to map the surface.
443
444 Mapping an xdg_surface-based role surface is defined as making it
445 possible for the surface to be shown by the compositor. Note that
446 a mapped surface is not guaranteed to be visible once it is mapped.
447
448 For an xdg_surface to be mapped by the compositor, the following
449 conditions must be met:
450 (1) the client has assigned an xdg_surface-based role to the surface
451 (2) the client has set and committed the xdg_surface state and the
452 role-dependent state to the surface
453 (3) the client has committed a buffer to the surface
454
455 A newly-unmapped surface is considered to have met condition (1) out
456 of the 3 required conditions for mapping a surface if its role surface
457 has not been destroyed, i.e. the client must perform the initial commit
458 again before attaching a buffer.
459 </description>
460
461 <enum name="error">
462 <entry name="not_constructed" value="1"
463 summary="Surface was not fully constructed"/>
464 <entry name="already_constructed" value="2"
465 summary="Surface was already constructed"/>
466 <entry name="unconfigured_buffer" value="3"
467 summary="Attaching a buffer to an unconfigured surface"/>
468 <entry name="invalid_serial" value="4"
469 summary="Invalid serial number when acking a configure event"/>
470 <entry name="invalid_size" value="5"
471 summary="Width or height was zero or negative"/>
472 <entry name="defunct_role_object" value="6"
473 summary="Surface was destroyed before its role object"/>
474 </enum>
475
476 <request name="destroy" type="destructor">
477 <description summary="destroy the xdg_surface">
478 Destroy the xdg_surface object. An xdg_surface must only be destroyed
479 after its role object has been destroyed, otherwise
480 a defunct_role_object error is raised.
481 </description>
482 </request>
483
484 <request name="get_toplevel">
485 <description summary="assign the xdg_toplevel surface role">
486 This creates an xdg_toplevel object for the given xdg_surface and gives
487 the associated wl_surface the xdg_toplevel role.
488
489 See the documentation of xdg_toplevel for more details about what an
490 xdg_toplevel is and how it is used.
491 </description>
492 <arg name="id" type="new_id" interface="xdg_toplevel"/>
493 </request>
494
495 <request name="get_popup">
496 <description summary="assign the xdg_popup surface role">
497 This creates an xdg_popup object for the given xdg_surface and gives
498 the associated wl_surface the xdg_popup role.
499
500 If null is passed as a parent, a parent surface must be specified using
501 some other protocol, before committing the initial state.
502
503 See the documentation of xdg_popup for more details about what an
504 xdg_popup is and how it is used.
505 </description>
506 <arg name="id" type="new_id" interface="xdg_popup"/>
507 <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
508 <arg name="positioner" type="object" interface="xdg_positioner"/>
509 </request>
510
511 <request name="set_window_geometry">
512 <description summary="set the new window geometry">
513 The window geometry of a surface is its "visible bounds" from the
514 user's perspective. Client-side decorations often have invisible
515 portions like drop-shadows which should be ignored for the
516 purposes of aligning, placing and constraining windows.
517
518 The window geometry is double buffered, and will be applied at the
519 time wl_surface.commit of the corresponding wl_surface is called.
520
521 When maintaining a position, the compositor should treat the (x, y)
522 coordinate of the window geometry as the top left corner of the window.
523 A client changing the (x, y) window geometry coordinate should in
524 general not alter the position of the window.
525
526 Once the window geometry of the surface is set, it is not possible to
527 unset it, and it will remain the same until set_window_geometry is
528 called again, even if a new subsurface or buffer is attached.
529
530 If never set, the value is the full bounds of the surface,
531 including any subsurfaces. This updates dynamically on every
532 commit. This unset is meant for extremely simple clients.
533
534 The arguments are given in the surface-local coordinate space of
535 the wl_surface associated with this xdg_surface, and may extend outside
536 of the wl_surface itself to mark parts of the subsurface tree as part of
537 the window geometry.
538
539 When applied, the effective window geometry will be the set window
540 geometry clamped to the bounding rectangle of the combined
541 geometry of the surface of the xdg_surface and the associated
542 subsurfaces.
543
544 The effective geometry will not be recalculated unless a new call to
545 set_window_geometry is done and the new pending surface state is
546 subsequently applied.
547
548 The width and height of the effective window geometry must be
549 greater than zero. Setting an invalid size will raise an
550 invalid_size error.
551 </description>
552 <arg name="x" type="int"/>
553 <arg name="y" type="int"/>
554 <arg name="width" type="int"/>
555 <arg name="height" type="int"/>
556 </request>
557
558 <request name="ack_configure">
559 <description summary="ack a configure event">
560 When a configure event is received, if a client commits the
561 surface in response to the configure event, then the client
562 must make an ack_configure request sometime before the commit
563 request, passing along the serial of the configure event.
564
565 For instance, for toplevel surfaces the compositor might use this
566 information to move a surface to the top left only when the client has
567 drawn itself for the maximized or fullscreen state.
568
569 If the client receives multiple configure events before it
570 can respond to one, it only has to ack the last configure event.
571 Acking a configure event that was never sent raises an invalid_serial
572 error.
573
574 A client is not required to commit immediately after sending
575 an ack_configure request - it may even ack_configure several times
576 before its next surface commit.
577
578 A client may send multiple ack_configure requests before committing, but
579 only the last request sent before a commit indicates which configure
580 event the client really is responding to.
581
582 Sending an ack_configure request consumes the serial number sent with
583 the request, as well as serial numbers sent by all configure events
584 sent on this xdg_surface prior to the configure event referenced by
585 the committed serial.
586
587 It is an error to issue multiple ack_configure requests referencing a
588 serial from the same configure event, or to issue an ack_configure
589 request referencing a serial from a configure event issued before the
590 event identified by the last ack_configure request for the same
591 xdg_surface. Doing so will raise an invalid_serial error.
592 </description>
593 <arg name="serial" type="uint" summary="the serial from the configure event"/>
594 </request>
595
596 <event name="configure">
597 <description summary="suggest a surface change">
598 The configure event marks the end of a configure sequence. A configure
599 sequence is a set of one or more events configuring the state of the
600 xdg_surface, including the final xdg_surface.configure event.
601
602 Where applicable, xdg_surface surface roles will during a configure
603 sequence extend this event as a latched state sent as events before the
604 xdg_surface.configure event. Such events should be considered to make up
605 a set of atomically applied configuration states, where the
606 xdg_surface.configure commits the accumulated state.
607
608 Clients should arrange their surface for the new states, and then send
609 an ack_configure request with the serial sent in this configure event at
610 some point before committing the new surface.
611
612 If the client receives multiple configure events before it can respond
613 to one, it is free to discard all but the last event it received.
614 </description>
615 <arg name="serial" type="uint" summary="serial of the configure event"/>
616 </event>
617
618 </interface>
619
620 <interface name="xdg_toplevel" version="6">
621 <description summary="toplevel surface">
622 This interface defines an xdg_surface role which allows a surface to,
623 among other things, set window-like properties such as maximize,
624 fullscreen, and minimize, set application-specific metadata like title and
625 id, and well as trigger user interactive operations such as interactive
626 resize and move.
627
628 Unmapping an xdg_toplevel means that the surface cannot be shown
629 by the compositor until it is explicitly mapped again.
630 All active operations (e.g., move, resize) are canceled and all
631 attributes (e.g. title, state, stacking, ...) are discarded for
632 an xdg_toplevel surface when it is unmapped. The xdg_toplevel returns to
633 the state it had right after xdg_surface.get_toplevel. The client
634 can re-map the toplevel by perfoming a commit without any buffer
635 attached, waiting for a configure event and handling it as usual (see
636 xdg_surface description).
637
638 Attaching a null buffer to a toplevel unmaps the surface.
639 </description>
640
641 <request name="destroy" type="destructor">
642 <description summary="destroy the xdg_toplevel">
643 This request destroys the role surface and unmaps the surface;
644 see "Unmapping" behavior in interface section for details.
645 </description>
646 </request>
647
648 <enum name="error">
649 <entry name="invalid_resize_edge" value="0" summary="provided value is
650 not a valid variant of the resize_edge enum"/>
651 <entry name="invalid_parent" value="1"
652 summary="invalid parent toplevel"/>
653 <entry name="invalid_size" value="2"
654 summary="client provided an invalid min or max size"/>
655 </enum>
656
657 <request name="set_parent">
658 <description summary="set the parent of this surface">
659 Set the "parent" of this surface. This surface should be stacked
660 above the parent surface and all other ancestor surfaces.
661
662 Parent surfaces should be set on dialogs, toolboxes, or other
663 "auxiliary" surfaces, so that the parent is raised when the dialog
664 is raised.
665
666 Setting a null parent for a child surface unsets its parent. Setting
667 a null parent for a surface which currently has no parent is a no-op.
668
669 Only mapped surfaces can have child surfaces. Setting a parent which
670 is not mapped is equivalent to setting a null parent. If a surface
671 becomes unmapped, its children's parent is set to the parent of
672 the now-unmapped surface. If the now-unmapped surface has no parent,
673 its children's parent is unset. If the now-unmapped surface becomes
674 mapped again, its parent-child relationship is not restored.
675
676 The parent toplevel must not be one of the child toplevel's
677 descendants, and the parent must be different from the child toplevel,
678 otherwise the invalid_parent protocol error is raised.
679 </description>
680 <arg name="parent" type="object" interface="xdg_toplevel" allow-null="true"/>
681 </request>
682
683 <request name="set_title">
684 <description summary="set surface title">
685 Set a short title for the surface.
686
687 This string may be used to identify the surface in a task bar,
688 window list, or other user interface elements provided by the
689 compositor.
690
691 The string must be encoded in UTF-8.
692 </description>
693 <arg name="title" type="string"/>
694 </request>
695
696 <request name="set_app_id">
697 <description summary="set application ID">
698 Set an application identifier for the surface.
699
700 The app ID identifies the general class of applications to which
701 the surface belongs. The compositor can use this to group multiple
702 surfaces together, or to determine how to launch a new application.
703
704 For D-Bus activatable applications, the app ID is used as the D-Bus
705 service name.
706
707 The compositor shell will try to group application surfaces together
708 by their app ID. As a best practice, it is suggested to select app
709 ID's that match the basename of the application's .desktop file.
710 For example, "org.freedesktop.FooViewer" where the .desktop file is
711 "org.freedesktop.FooViewer.desktop".
712
713 Like other properties, a set_app_id request can be sent after the
714 xdg_toplevel has been mapped to update the property.
715
716 See the desktop-entry specification [0] for more details on
717 application identifiers and how they relate to well-known D-Bus
718 names and .desktop files.
719
720 [0] https://standards.freedesktop.org/desktop-entry-spec/
721 </description>
722 <arg name="app_id" type="string"/>
723 </request>
724
725 <request name="show_window_menu">
726 <description summary="show the window menu">
727 Clients implementing client-side decorations might want to show
728 a context menu when right-clicking on the decorations, giving the
729 user a menu that they can use to maximize or minimize the window.
730
731 This request asks the compositor to pop up such a window menu at
732 the given position, relative to the local surface coordinates of
733 the parent surface. There are no guarantees as to what menu items
734 the window menu contains, or even if a window menu will be drawn
735 at all.
736
737 This request must be used in response to some sort of user action
738 like a button press, key press, or touch down event.
739 </description>
740 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
741 <arg name="serial" type="uint" summary="the serial of the user event"/>
742 <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
743 <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
744 </request>
745
746 <request name="move">
747 <description summary="start an interactive move">
748 Start an interactive, user-driven move of the surface.
749
750 This request must be used in response to some sort of user action
751 like a button press, key press, or touch down event. The passed
752 serial is used to determine the type of interactive move (touch,
753 pointer, etc).
754
755 The server may ignore move requests depending on the state of
756 the surface (e.g. fullscreen or maximized), or if the passed serial
757 is no longer valid.
758
759 If triggered, the surface will lose the focus of the device
760 (wl_pointer, wl_touch, etc) used for the move. It is up to the
761 compositor to visually indicate that the move is taking place, such as
762 updating a pointer cursor, during the move. There is no guarantee
763 that the device focus will return when the move is completed.
764 </description>
765 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
766 <arg name="serial" type="uint" summary="the serial of the user event"/>
767 </request>
768
769 <enum name="resize_edge">
770 <description summary="edge values for resizing">
771 These values are used to indicate which edge of a surface
772 is being dragged in a resize operation.
773 </description>
774 <entry name="none" value="0"/>
775 <entry name="top" value="1"/>
776 <entry name="bottom" value="2"/>
777 <entry name="left" value="4"/>
778 <entry name="top_left" value="5"/>
779 <entry name="bottom_left" value="6"/>
780 <entry name="right" value="8"/>
781 <entry name="top_right" value="9"/>
782 <entry name="bottom_right" value="10"/>
783 </enum>
784
785 <request name="resize">
786 <description summary="start an interactive resize">
787 Start a user-driven, interactive resize of the surface.
788
789 This request must be used in response to some sort of user action
790 like a button press, key press, or touch down event. The passed
791 serial is used to determine the type of interactive resize (touch,
792 pointer, etc).
793
794 The server may ignore resize requests depending on the state of
795 the surface (e.g. fullscreen or maximized).
796
797 If triggered, the client will receive configure events with the
798 "resize" state enum value and the expected sizes. See the "resize"
799 enum value for more details about what is required. The client
800 must also acknowledge configure events using "ack_configure". After
801 the resize is completed, the client will receive another "configure"
802 event without the resize state.
803
804 If triggered, the surface also will lose the focus of the device
805 (wl_pointer, wl_touch, etc) used for the resize. It is up to the
806 compositor to visually indicate that the resize is taking place,
807 such as updating a pointer cursor, during the resize. There is no
808 guarantee that the device focus will return when the resize is
809 completed.
810
811 The edges parameter specifies how the surface should be resized, and
812 is one of the values of the resize_edge enum. Values not matching
813 a variant of the enum will cause the invalid_resize_edge protocol error.
814 The compositor may use this information to update the surface position
815 for example when dragging the top left corner. The compositor may also
816 use this information to adapt its behavior, e.g. choose an appropriate
817 cursor image.
818 </description>
819 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
820 <arg name="serial" type="uint" summary="the serial of the user event"/>
821 <arg name="edges" type="uint" enum="resize_edge" summary="which edge or corner is being dragged"/>
822 </request>
823
824 <enum name="state">
825 <description summary="types of state on the surface">
826 The different state values used on the surface. This is designed for
827 state values like maximized, fullscreen. It is paired with the
828 configure event to ensure that both the client and the compositor
829 setting the state can be synchronized.
830
831 States set in this way are double-buffered. They will get applied on
832 the next commit.
833 </description>
834 <entry name="maximized" value="1" summary="the surface is maximized">
835 <description summary="the surface is maximized">
836 The surface is maximized. The window geometry specified in the configure
837 event must be obeyed by the client, or the xdg_wm_base.invalid_surface_state
838 error is raised.
839
840 The client should draw without shadow or other
841 decoration outside of the window geometry.
842 </description>
843 </entry>
844 <entry name="fullscreen" value="2" summary="the surface is fullscreen">
845 <description summary="the surface is fullscreen">
846 The surface is fullscreen. The window geometry specified in the
847 configure event is a maximum; the client cannot resize beyond it. For
848 a surface to cover the whole fullscreened area, the geometry
849 dimensions must be obeyed by the client. For more details, see
850 xdg_toplevel.set_fullscreen.
851 </description>
852 </entry>
853 <entry name="resizing" value="3" summary="the surface is being resized">
854 <description summary="the surface is being resized">
855 The surface is being resized. The window geometry specified in the
856 configure event is a maximum; the client cannot resize beyond it.
857 Clients that have aspect ratio or cell sizing configuration can use
858 a smaller size, however.
859 </description>
860 </entry>
861 <entry name="activated" value="4" summary="the surface is now activated">
862 <description summary="the surface is now activated">
863 Client window decorations should be painted as if the window is
864 active. Do not assume this means that the window actually has
865 keyboard or pointer focus.
866 </description>
867 </entry>
868 <entry name="tiled_left" value="5" since="2">
869 <description summary="the surface’s left edge is tiled">
870 The window is currently in a tiled layout and the left edge is
871 considered to be adjacent to another part of the tiling grid.
872 </description>
873 </entry>
874 <entry name="tiled_right" value="6" since="2">
875 <description summary="the surface’s right edge is tiled">
876 The window is currently in a tiled layout and the right edge is
877 considered to be adjacent to another part of the tiling grid.
878 </description>
879 </entry>
880 <entry name="tiled_top" value="7" since="2">
881 <description summary="the surface’s top edge is tiled">
882 The window is currently in a tiled layout and the top edge is
883 considered to be adjacent to another part of the tiling grid.
884 </description>
885 </entry>
886 <entry name="tiled_bottom" value="8" since="2">
887 <description summary="the surface’s bottom edge is tiled">
888 The window is currently in a tiled layout and the bottom edge is
889 considered to be adjacent to another part of the tiling grid.
890 </description>
891 </entry>
892 <entry name="suspended" value="9" since="6">
893 <description summary="surface repaint is suspended">
894 The surface is currently not ordinarily being repainted; for
895 example because its content is occluded by another window, or its
896 outputs are switched off due to screen locking.
897 </description>
898 </entry>
899 </enum>
900
901 <request name="set_max_size">
902 <description summary="set the maximum size">
903 Set a maximum size for the window.
904
905 The client can specify a maximum size so that the compositor does
906 not try to configure the window beyond this size.
907
908 The width and height arguments are in window geometry coordinates.
909 See xdg_surface.set_window_geometry.
910
911 Values set in this way are double-buffered. They will get applied
912 on the next commit.
913
914 The compositor can use this information to allow or disallow
915 different states like maximize or fullscreen and draw accurate
916 animations.
917
918 Similarly, a tiling window manager may use this information to
919 place and resize client windows in a more effective way.
920
921 The client should not rely on the compositor to obey the maximum
922 size. The compositor may decide to ignore the values set by the
923 client and request a larger size.
924
925 If never set, or a value of zero in the request, means that the
926 client has no expected maximum size in the given dimension.
927 As a result, a client wishing to reset the maximum size
928 to an unspecified state can use zero for width and height in the
929 request.
930
931 Requesting a maximum size to be smaller than the minimum size of
932 a surface is illegal and will result in an invalid_size error.
933
934 The width and height must be greater than or equal to zero. Using
935 strictly negative values for width or height will result in a
936 invalid_size error.
937 </description>
938 <arg name="width" type="int"/>
939 <arg name="height" type="int"/>
940 </request>
941
942 <request name="set_min_size">
943 <description summary="set the minimum size">
944 Set a minimum size for the window.
945
946 The client can specify a minimum size so that the compositor does
947 not try to configure the window below this size.
948
949 The width and height arguments are in window geometry coordinates.
950 See xdg_surface.set_window_geometry.
951
952 Values set in this way are double-buffered. They will get applied
953 on the next commit.
954
955 The compositor can use this information to allow or disallow
956 different states like maximize or fullscreen and draw accurate
957 animations.
958
959 Similarly, a tiling window manager may use this information to
960 place and resize client windows in a more effective way.
961
962 The client should not rely on the compositor to obey the minimum
963 size. The compositor may decide to ignore the values set by the
964 client and request a smaller size.
965
966 If never set, or a value of zero in the request, means that the
967 client has no expected minimum size in the given dimension.
968 As a result, a client wishing to reset the minimum size
969 to an unspecified state can use zero for width and height in the
970 request.
971
972 Requesting a minimum size to be larger than the maximum size of
973 a surface is illegal and will result in an invalid_size error.
974
975 The width and height must be greater than or equal to zero. Using
976 strictly negative values for width and height will result in a
977 invalid_size error.
978 </description>
979 <arg name="width" type="int"/>
980 <arg name="height" type="int"/>
981 </request>
982
983 <request name="set_maximized">
984 <description summary="maximize the window">
985 Maximize the surface.
986
987 After requesting that the surface should be maximized, the compositor
988 will respond by emitting a configure event. Whether this configure
989 actually sets the window maximized is subject to compositor policies.
990 The client must then update its content, drawing in the configured
991 state. The client must also acknowledge the configure when committing
992 the new content (see ack_configure).
993
994 It is up to the compositor to decide how and where to maximize the
995 surface, for example which output and what region of the screen should
996 be used.
997
998 If the surface was already maximized, the compositor will still emit
999 a configure event with the "maximized" state.
1000
1001 If the surface is in a fullscreen state, this request has no direct
1002 effect. It may alter the state the surface is returned to when
1003 unmaximized unless overridden by the compositor.
1004 </description>
1005 </request>
1006
1007 <request name="unset_maximized">
1008 <description summary="unmaximize the window">
1009 Unmaximize the surface.
1010
1011 After requesting that the surface should be unmaximized, the compositor
1012 will respond by emitting a configure event. Whether this actually
1013 un-maximizes the window is subject to compositor policies.
1014 If available and applicable, the compositor will include the window
1015 geometry dimensions the window had prior to being maximized in the
1016 configure event. The client must then update its content, drawing it in
1017 the configured state. The client must also acknowledge the configure
1018 when committing the new content (see ack_configure).
1019
1020 It is up to the compositor to position the surface after it was
1021 unmaximized; usually the position the surface had before maximizing, if
1022 applicable.
1023
1024 If the surface was already not maximized, the compositor will still
1025 emit a configure event without the "maximized" state.
1026
1027 If the surface is in a fullscreen state, this request has no direct
1028 effect. It may alter the state the surface is returned to when
1029 unmaximized unless overridden by the compositor.
1030 </description>
1031 </request>
1032
1033 <request name="set_fullscreen">
1034 <description summary="set the window as fullscreen on an output">
1035 Make the surface fullscreen.
1036
1037 After requesting that the surface should be fullscreened, the
1038 compositor will respond by emitting a configure event. Whether the
1039 client is actually put into a fullscreen state is subject to compositor
1040 policies. The client must also acknowledge the configure when
1041 committing the new content (see ack_configure).
1042
1043 The output passed by the request indicates the client's preference as
1044 to which display it should be set fullscreen on. If this value is NULL,
1045 it's up to the compositor to choose which display will be used to map
1046 this surface.
1047
1048 If the surface doesn't cover the whole output, the compositor will
1049 position the surface in the center of the output and compensate with
1050 with border fill covering the rest of the output. The content of the
1051 border fill is undefined, but should be assumed to be in some way that
1052 attempts to blend into the surrounding area (e.g. solid black).
1053
1054 If the fullscreened surface is not opaque, the compositor must make
1055 sure that other screen content not part of the same surface tree (made
1056 up of subsurfaces, popups or similarly coupled surfaces) are not
1057 visible below the fullscreened surface.
1058 </description>
1059 <arg name="output" type="object" interface="wl_output" allow-null="true"/>
1060 </request>
1061
1062 <request name="unset_fullscreen">
1063 <description summary="unset the window as fullscreen">
1064 Make the surface no longer fullscreen.
1065
1066 After requesting that the surface should be unfullscreened, the
1067 compositor will respond by emitting a configure event.
1068 Whether this actually removes the fullscreen state of the client is
1069 subject to compositor policies.
1070
1071 Making a surface unfullscreen sets states for the surface based on the following:
1072 * the state(s) it may have had before becoming fullscreen
1073 * any state(s) decided by the compositor
1074 * any state(s) requested by the client while the surface was fullscreen
1075
1076 The compositor may include the previous window geometry dimensions in
1077 the configure event, if applicable.
1078
1079 The client must also acknowledge the configure when committing the new
1080 content (see ack_configure).
1081 </description>
1082 </request>
1083
1084 <request name="set_minimized">
1085 <description summary="set the window as minimized">
1086 Request that the compositor minimize your surface. There is no
1087 way to know if the surface is currently minimized, nor is there
1088 any way to unset minimization on this surface.
1089
1090 If you are looking to throttle redrawing when minimized, please
1091 instead use the wl_surface.frame event for this, as this will
1092 also work with live previews on windows in Alt-Tab, Expose or
1093 similar compositor features.
1094 </description>
1095 </request>
1096
1097 <event name="configure">
1098 <description summary="suggest a surface change">
1099 This configure event asks the client to resize its toplevel surface or
1100 to change its state. The configured state should not be applied
1101 immediately. See xdg_surface.configure for details.
1102
1103 The width and height arguments specify a hint to the window
1104 about how its surface should be resized in window geometry
1105 coordinates. See set_window_geometry.
1106
1107 If the width or height arguments are zero, it means the client
1108 should decide its own window dimension. This may happen when the
1109 compositor needs to configure the state of the surface but doesn't
1110 have any information about any previous or expected dimension.
1111
1112 The states listed in the event specify how the width/height
1113 arguments should be interpreted, and possibly how it should be
1114 drawn.
1115
1116 Clients must send an ack_configure in response to this event. See
1117 xdg_surface.configure and xdg_surface.ack_configure for details.
1118 </description>
1119 <arg name="width" type="int"/>
1120 <arg name="height" type="int"/>
1121 <arg name="states" type="array"/>
1122 </event>
1123
1124 <event name="close">
1125 <description summary="surface wants to be closed">
1126 The close event is sent by the compositor when the user
1127 wants the surface to be closed. This should be equivalent to
1128 the user clicking the close button in client-side decorations,
1129 if your application has any.
1130
1131 This is only a request that the user intends to close the
1132 window. The client may choose to ignore this request, or show
1133 a dialog to ask the user to save their data, etc.
1134 </description>
1135 </event>
1136
1137 <!-- Version 4 additions -->
1138
1139 <event name="configure_bounds" since="4">
1140 <description summary="recommended window geometry bounds">
1141 The configure_bounds event may be sent prior to a xdg_toplevel.configure
1142 event to communicate the bounds a window geometry size is recommended
1143 to constrain to.
1144
1145 The passed width and height are in surface coordinate space. If width
1146 and height are 0, it means bounds is unknown and equivalent to as if no
1147 configure_bounds event was ever sent for this surface.
1148
1149 The bounds can for example correspond to the size of a monitor excluding
1150 any panels or other shell components, so that a surface isn't created in
1151 a way that it cannot fit.
1152
1153 The bounds may change at any point, and in such a case, a new
1154 xdg_toplevel.configure_bounds will be sent, followed by
1155 xdg_toplevel.configure and xdg_surface.configure.
1156 </description>
1157 <arg name="width" type="int"/>
1158 <arg name="height" type="int"/>
1159 </event>
1160
1161 <!-- Version 5 additions -->
1162
1163 <enum name="wm_capabilities" since="5">
1164 <entry name="window_menu" value="1" summary="show_window_menu is available"/>
1165 <entry name="maximize" value="2" summary="set_maximized and unset_maximized are available"/>
1166 <entry name="fullscreen" value="3" summary="set_fullscreen and unset_fullscreen are available"/>
1167 <entry name="minimize" value="4" summary="set_minimized is available"/>
1168 </enum>
1169
1170 <event name="wm_capabilities" since="5">
1171 <description summary="compositor capabilities">
1172 This event advertises the capabilities supported by the compositor. If
1173 a capability isn't supported, clients should hide or disable the UI
1174 elements that expose this functionality. For instance, if the
1175 compositor doesn't advertise support for minimized toplevels, a button
1176 triggering the set_minimized request should not be displayed.
1177
1178 The compositor will ignore requests it doesn't support. For instance,
1179 a compositor which doesn't advertise support for minimized will ignore
1180 set_minimized requests.
1181
1182 Compositors must send this event once before the first
1183 xdg_surface.configure event. When the capabilities change, compositors
1184 must send this event again and then send an xdg_surface.configure
1185 event.
1186
1187 The configured state should not be applied immediately. See
1188 xdg_surface.configure for details.
1189
1190 The capabilities are sent as an array of 32-bit unsigned integers in
1191 native endianness.
1192 </description>
1193 <arg name="capabilities" type="array" summary="array of 32-bit capabilities"/>
1194 </event>
1195 </interface>
1196
1197 <interface name="xdg_popup" version="6">
1198 <description summary="short-lived, popup surfaces for menus">
1199 A popup surface is a short-lived, temporary surface. It can be used to
1200 implement for example menus, popovers, tooltips and other similar user
1201 interface concepts.
1202
1203 A popup can be made to take an explicit grab. See xdg_popup.grab for
1204 details.
1205
1206 When the popup is dismissed, a popup_done event will be sent out, and at
1207 the same time the surface will be unmapped. See the xdg_popup.popup_done
1208 event for details.
1209
1210 Explicitly destroying the xdg_popup object will also dismiss the popup and
1211 unmap the surface. Clients that want to dismiss the popup when another
1212 surface of their own is clicked should dismiss the popup using the destroy
1213 request.
1214
1215 A newly created xdg_popup will be stacked on top of all previously created
1216 xdg_popup surfaces associated with the same xdg_toplevel.
1217
1218 The parent of an xdg_popup must be mapped (see the xdg_surface
1219 description) before the xdg_popup itself.
1220
1221 The client must call wl_surface.commit on the corresponding wl_surface
1222 for the xdg_popup state to take effect.
1223 </description>
1224
1225 <enum name="error">
1226 <entry name="invalid_grab" value="0"
1227 summary="tried to grab after being mapped"/>
1228 </enum>
1229
1230 <request name="destroy" type="destructor">
1231 <description summary="remove xdg_popup interface">
1232 This destroys the popup. Explicitly destroying the xdg_popup
1233 object will also dismiss the popup, and unmap the surface.
1234
1235 If this xdg_popup is not the "topmost" popup, the
1236 xdg_wm_base.not_the_topmost_popup protocol error will be sent.
1237 </description>
1238 </request>
1239
1240 <request name="grab">
1241 <description summary="make the popup take an explicit grab">
1242 This request makes the created popup take an explicit grab. An explicit
1243 grab will be dismissed when the user dismisses the popup, or when the
1244 client destroys the xdg_popup. This can be done by the user clicking
1245 outside the surface, using the keyboard, or even locking the screen
1246 through closing the lid or a timeout.
1247
1248 If the compositor denies the grab, the popup will be immediately
1249 dismissed.
1250
1251 This request must be used in response to some sort of user action like a
1252 button press, key press, or touch down event. The serial number of the
1253 event should be passed as 'serial'.
1254
1255 The parent of a grabbing popup must either be an xdg_toplevel surface or
1256 another xdg_popup with an explicit grab. If the parent is another
1257 xdg_popup it means that the popups are nested, with this popup now being
1258 the topmost popup.
1259
1260 Nested popups must be destroyed in the reverse order they were created
1261 in, e.g. the only popup you are allowed to destroy at all times is the
1262 topmost one.
1263
1264 When compositors choose to dismiss a popup, they may dismiss every
1265 nested grabbing popup as well. When a compositor dismisses popups, it
1266 will follow the same dismissing order as required from the client.
1267
1268 If the topmost grabbing popup is destroyed, the grab will be returned to
1269 the parent of the popup, if that parent previously had an explicit grab.
1270
1271 If the parent is a grabbing popup which has already been dismissed, this
1272 popup will be immediately dismissed. If the parent is a popup that did
1273 not take an explicit grab, an error will be raised.
1274
1275 During a popup grab, the client owning the grab will receive pointer
1276 and touch events for all their surfaces as normal (similar to an
1277 "owner-events" grab in X11 parlance), while the top most grabbing popup
1278 will always have keyboard focus.
1279 </description>
1280 <arg name="seat" type="object" interface="wl_seat"
1281 summary="the wl_seat of the user event"/>
1282 <arg name="serial" type="uint" summary="the serial of the user event"/>
1283 </request>
1284
1285 <event name="configure">
1286 <description summary="configure the popup surface">
1287 This event asks the popup surface to configure itself given the
1288 configuration. The configured state should not be applied immediately.
1289 See xdg_surface.configure for details.
1290
1291 The x and y arguments represent the position the popup was placed at
1292 given the xdg_positioner rule, relative to the upper left corner of the
1293 window geometry of the parent surface.
1294
1295 For version 2 or older, the configure event for an xdg_popup is only
1296 ever sent once for the initial configuration. Starting with version 3,
1297 it may be sent again if the popup is setup with an xdg_positioner with
1298 set_reactive requested, or in response to xdg_popup.reposition requests.
1299 </description>
1300 <arg name="x" type="int"
1301 summary="x position relative to parent surface window geometry"/>
1302 <arg name="y" type="int"
1303 summary="y position relative to parent surface window geometry"/>
1304 <arg name="width" type="int" summary="window geometry width"/>
1305 <arg name="height" type="int" summary="window geometry height"/>
1306 </event>
1307
1308 <event name="popup_done">
1309 <description summary="popup interaction is done">
1310 The popup_done event is sent out when a popup is dismissed by the
1311 compositor. The client should destroy the xdg_popup object at this
1312 point.
1313 </description>
1314 </event>
1315
1316 <!-- Version 3 additions -->
1317
1318 <request name="reposition" since="3">
1319 <description summary="recalculate the popup's location">
1320 Reposition an already-mapped popup. The popup will be placed given the
1321 details in the passed xdg_positioner object, and a
1322 xdg_popup.repositioned followed by xdg_popup.configure and
1323 xdg_surface.configure will be emitted in response. Any parameters set
1324 by the previous positioner will be discarded.
1325
1326 The passed token will be sent in the corresponding
1327 xdg_popup.repositioned event. The new popup position will not take
1328 effect until the corresponding configure event is acknowledged by the
1329 client. See xdg_popup.repositioned for details. The token itself is
1330 opaque, and has no other special meaning.
1331
1332 If multiple reposition requests are sent, the compositor may skip all
1333 but the last one.
1334
1335 If the popup is repositioned in response to a configure event for its
1336 parent, the client should send an xdg_positioner.set_parent_configure
1337 and possibly an xdg_positioner.set_parent_size request to allow the
1338 compositor to properly constrain the popup.
1339
1340 If the popup is repositioned together with a parent that is being
1341 resized, but not in response to a configure event, the client should
1342 send an xdg_positioner.set_parent_size request.
1343 </description>
1344 <arg name="positioner" type="object" interface="xdg_positioner"/>
1345 <arg name="token" type="uint" summary="reposition request token"/>
1346 </request>
1347
1348 <event name="repositioned" since="3">
1349 <description summary="signal the completion of a repositioned request">
1350 The repositioned event is sent as part of a popup configuration
1351 sequence, together with xdg_popup.configure and lastly
1352 xdg_surface.configure to notify the completion of a reposition request.
1353
1354 The repositioned event is to notify about the completion of a
1355 xdg_popup.reposition request. The token argument is the token passed
1356 in the xdg_popup.reposition request.
1357
1358 Immediately after this event is emitted, xdg_popup.configure and
1359 xdg_surface.configure will be sent with the updated size and position,
1360 as well as a new configure serial.
1361
1362 The client should optionally update the content of the popup, but must
1363 acknowledge the new popup configuration for the new position to take
1364 effect. See xdg_surface.ack_configure for details.
1365 </description>
1366 <arg name="token" type="uint" summary="reposition request token"/>
1367 </event>
1368
1369 </interface>
1370</protocol>

Generated with cgit - Back to sebastiano.tronto.net