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