1//! Generic wayland protocols
2
3#![cfg_attr(rustfmt, rustfmt_skip)]
4
5#[cfg(feature = "staging")]
6pub mod content_type {
7 //! This protocol allows a client to describe the kind of content a surface
8 //! will display, to allow the compositor to optimize its behavior for it.
9
10 #[allow(missing_docs)]
11 pub mod v1 {
12 wayland_protocol!(
13 "./protocols/staging/content-type/content-type-v1.xml",
14 []
15 );
16 }
17}
18
19#[cfg(feature = "staging")]
20pub mod drm_lease {
21 //! This protocol is used by Wayland compositors which act as Direct
22 //! Renderering Manager (DRM) masters to lease DRM resources to Wayland
23 //! clients.
24 //!
25 //! The compositor will advertise one wp_drm_lease_device_v1 global for each
26 //! DRM node. Some time after a client binds to the wp_drm_lease_device_v1
27 //! global, the compositor will send a drm_fd event followed by zero, one or
28 //! more connector events. After all currently available connectors have been
29 //! sent, the compositor will send a wp_drm_lease_device_v1.done event.
30 //!
31 //! When the list of connectors available for lease changes the compositor
32 //! will send wp_drm_lease_device_v1.connector events for added connectors and
33 //! wp_drm_lease_connector_v1.withdrawn events for removed connectors,
34 //! followed by a wp_drm_lease_device_v1.done event.
35 //!
36 //! The compositor will indicate when a device is gone by removing the global
37 //! via a wl_registry.global_remove event. Upon receiving this event, the
38 //! client should destroy any matching wp_drm_lease_device_v1 object.
39 //!
40 //! To destroy a wp_drm_lease_device_v1 object, the client must first issue
41 //! a release request. Upon receiving this request, the compositor will
42 //! immediately send a released event and destroy the object. The client must
43 //! continue to process and discard drm_fd and connector events until it
44 //! receives the released event. Upon receiving the released event, the
45 //! client can safely cleanup any client-side resources.
46
47 #[allow(missing_docs)]
48 pub mod v1 {
49 wayland_protocol!(
50 "./protocols/staging/drm-lease/drm-lease-v1.xml",
51 []
52 );
53 }
54}
55
56#[cfg(feature = "staging")]
57pub mod tearing_control {
58 //! This protocol provides a way for clients to indicate whether
59 //! or not their content is suitable for this kind of presentation.
60 //!
61 //! For some use cases like games or drawing tablets it can make sense to reduce
62 //! latency by accepting tearing with the use of asynchronous page flips.
63
64 #[allow(missing_docs)]
65 pub mod v1 {
66 wayland_protocol!(
67 "./protocols/staging/tearing-control/tearing-control-v1.xml",
68 []
69 );
70 }
71}
72
73#[cfg(feature = "staging")]
74pub mod fractional_scale {
75 //! This protocol allows a compositor to suggest for surfaces to render at
76 //! fractional scales.
77 //!
78 //! A client can submit scaled content by utilizing wp_viewport. This is done by
79 //! creating a wp_viewport object for the surface and setting the destination
80 //! rectangle to the surface size before the scale factor is applied.
81 //!
82 //! The buffer size is calculated by multiplying the surface size by the
83 //! intended scale.
84 //!
85 //! The wl_surface buffer scale should remain set to 1.
86 //!
87 //! If a surface has a surface-local size of 100 px by 50 px and wishes to
88 //! submit buffers with a scale of 1.5, then a buffer of 150px by 75 px should
89 //! be used and the wp_viewport destination rectangle should be 100 px by 50 px.
90 //!
91 //! For toplevel surfaces, the size is rounded halfway away from zero. The
92 //! rounding algorithm for subsurface position and size is not defined.
93
94 #[allow(missing_docs)]
95 pub mod v1 {
96 wayland_protocol!(
97 "./protocols/staging/fractional-scale/fractional-scale-v1.xml",
98 []
99 );
100 }
101}
102
103#[cfg(feature = "unstable")]
104pub mod fullscreen_shell {
105 //! Fullscreen shell protocol
106
107 /// Unstable version 1
108 pub mod zv1 {
109 wayland_protocol!(
110 "./protocols/unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml",
111 []
112 );
113 }
114}
115
116#[cfg(feature = "unstable")]
117pub mod idle_inhibit {
118 //! Screensaver inhibition protocol
119
120 /// Unstable version 1
121 pub mod zv1 {
122 wayland_protocol!(
123 "./protocols/unstable/idle-inhibit/idle-inhibit-unstable-v1.xml",
124 []
125 );
126 }
127}
128
129#[cfg(feature = "unstable")]
130pub mod input_method {
131 //! Input method protocol
132
133 /// Unstable version 1
134 pub mod zv1 {
135 wayland_protocol!(
136 "./protocols/unstable/input-method/input-method-unstable-v1.xml",
137 []
138 );
139 }
140}
141
142#[cfg(feature = "unstable")]
143pub mod input_timestamps {
144 //! Input timestamps protocol
145
146 /// Unstable version 1
147 pub mod zv1 {
148 wayland_protocol!(
149 "./protocols/unstable/input-timestamps/input-timestamps-unstable-v1.xml",
150 []
151 );
152 }
153}
154
155#[cfg(feature = "unstable")]
156pub mod keyboard_shortcuts_inhibit {
157 //! Protocol for inhibiting the compositor keyboard shortcuts
158 //!
159 //! This protocol specifies a way for a client to request the compositor
160 //! to ignore its own keyboard shortcuts for a given seat, so that all
161 //! key events from that seat get forwarded to a surface.
162
163 /// Unstable version 1
164 pub mod zv1 {
165 wayland_protocol!(
166 "./protocols/unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml",
167 []
168 );
169 }
170}
171
172pub mod linux_dmabuf {
173 //! Linux DMA-BUF protocol
174
175 /// Unstable version 1
176 pub mod zv1 {
177 wayland_protocol!(
178 "./protocols/stable/linux-dmabuf/linux-dmabuf-v1.xml",
179 []
180 );
181 }
182}
183
184#[cfg(feature = "unstable")]
185pub mod linux_explicit_synchronization {
186 //! Linux explicit synchronization protocol
187
188 /// Unstable version 1
189 pub mod zv1 {
190 wayland_protocol!(
191 "./protocols/unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml",
192 []
193 );
194 }
195}
196
197#[cfg(feature = "staging")]
198pub mod linux_drm_syncobj {
199 //! This protocol allows clients to request explicit synchronization for
200 //! buffers. It is tied to the Linux DRM synchronization object framework.
201 //!
202 //! Synchronization refers to co-ordination of pipelined operations performed
203 //! on buffers. Most GPU clients will schedule an asynchronous operation to
204 //! render to the buffer, then immediately send the buffer to the compositor
205 //! to be attached to a surface.
206 //!
207 //! With implicit synchronization, ensuring that the rendering operation is
208 //! complete before the compositor displays the buffer is an implementation
209 //! detail handled by either the kernel or userspace graphics driver.
210 //!
211 //! By contrast, with explicit synchronization, DRM synchronization object
212 //! timeline points mark when the asynchronous operations are complete. When
213 //! submitting a buffer, the client provides a timeline point which will be
214 //! waited on before the compositor accesses the buffer, and another timeline
215 //! point that the compositor will signal when it no longer needs to access the
216 //! buffer contents for the purposes of the surface commit.
217 //!
218 //! Linux DRM synchronization objects are documented at:
219 //! <https://dri.freedesktop.org/docs/drm/gpu/drm-mm.html#drm-sync-objects>
220
221 /// Version 1
222 pub mod v1 {
223 wayland_protocol!(
224 "./protocols/staging/linux-drm-syncobj/linux-drm-syncobj-v1.xml",
225 []
226 );
227 }
228}
229
230#[cfg(feature = "unstable")]
231pub mod pointer_constraints {
232 //! protocol for constraining pointer motions
233 //!
234 //! This protocol specifies a set of interfaces used for adding constraints to
235 //! the motion of a pointer. Possible constraints include confining pointer
236 //! motions to a given region, or locking it to its current position.
237 //!
238 //! In order to constrain the pointer, a client must first bind the global
239 //! interface "wp_pointer_constraints" which, if a compositor supports pointer
240 //! constraints, is exposed by the registry. Using the bound global object, the
241 //! client uses the request that corresponds to the type of constraint it wants
242 //! to make. See wp_pointer_constraints for more details.
243
244 /// Unstable version 1
245 pub mod zv1 {
246 wayland_protocol!(
247 "./protocols/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml",
248 []
249 );
250 }
251}
252
253#[cfg(feature = "unstable")]
254pub mod pointer_gestures {
255 //! Pointer gestures protocol
256
257 /// Unstable version 1
258 pub mod zv1 {
259 wayland_protocol!(
260 "./protocols/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml",
261 []
262 );
263 }
264}
265
266pub mod presentation_time {
267 //! Presentation time protocol
268 //!
269 //! Allows precise feedback on presentation timing, for example for smooth video playback.
270
271 wayland_protocol!(
272 "./protocols/stable/presentation-time/presentation-time.xml",
273 []
274 );
275}
276
277#[cfg(feature = "unstable")]
278pub mod primary_selection {
279 //! Primary selection protocol
280
281 /// Unstable version 1
282 pub mod zv1 {
283 wayland_protocol!(
284 "./protocols/unstable/primary-selection/primary-selection-unstable-v1.xml",
285 []
286 );
287 }
288}
289
290#[cfg(feature = "unstable")]
291pub mod relative_pointer {
292 //! protocol for relative pointer motion events
293 //!
294 //! This protocol specifies a set of interfaces used for making clients able to
295 //! receive relative pointer events not obstructed by barriers (such as the
296 //! monitor edge or other pointer barriers).
297 //!
298 //! To start receiving relative pointer events, a client must first bind the
299 //! global interface "wp_relative_pointer_manager" which, if a compositor
300 //! supports relative pointer motion events, is exposed by the registry. After
301 //! having created the relative pointer manager proxy object, the client uses
302 //! it to create the actual relative pointer object using the
303 //! "get_relative_pointer" request given a wl_pointer. The relative pointer
304 //! motion events will then, when applicable, be transmitted via the proxy of
305 //! the newly created relative pointer object. See the documentation of the
306 //! relative pointer interface for more details.
307
308 /// Unstable version 1
309 pub mod zv1 {
310 wayland_protocol!(
311 "./protocols/unstable/relative-pointer/relative-pointer-unstable-v1.xml",
312 []
313 );
314 }
315}
316
317#[cfg(feature = "staging")]
318pub mod single_pixel_buffer {
319 //! This protocol extension allows clients to create single-pixel buffers.
320 //!
321 //! Compositors supporting this protocol extension should also support the
322 //! viewporter protocol extension. Clients may use viewporter to scale a
323 //! single-pixel buffer to a desired size.
324
325 /// Version 1
326 pub mod v1 {
327 wayland_protocol!(
328 "./protocols/staging/single-pixel-buffer/single-pixel-buffer-v1.xml",
329 []
330 );
331 }
332}
333
334#[cfg(all(feature = "staging", feature = "unstable"))]
335pub mod cursor_shape {
336 //! This protocol extension offers a simpler way for clients to set a cursor.
337
338 /// Version 1
339 pub mod v1 {
340 wayland_protocol!(
341 "./protocols/staging/cursor-shape/cursor-shape-v1.xml",
342 [crate::wp::tablet::zv2]
343 );
344 }
345}
346
347pub mod tablet {
348 //! Wayland protocol for graphics tablets
349 //!
350 //! This description provides a high-level overview of the interplay between
351 //! the interfaces defined this protocol. For details, see the protocol
352 //! specification.
353 //!
354 //! More than one tablet may exist, and device-specifics matter. Tablets are
355 //! not represented by a single virtual device like wl_pointer. A client
356 //! binds to the tablet manager object which is just a proxy object. From
357 //! that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat)
358 //! and that returns the actual interface that has all the tablets. With
359 //! this indirection, we can avoid merging wp_tablet into the actual Wayland
360 //! protocol, a long-term benefit.
361 //!
362 //! The wp_tablet_seat sends a "tablet added" event for each tablet
363 //! connected. That event is followed by descriptive events about the
364 //! hardware; currently that includes events for name, vid/pid and
365 //! a wp_tablet.path event that describes a local path. This path can be
366 //! used to uniquely identify a tablet or get more information through
367 //! libwacom. Emulated or nested tablets can skip any of those, e.g. a
368 //! virtual tablet may not have a vid/pid. The sequence of descriptive
369 //! events is terminated by a wp_tablet.done event to signal that a client
370 //! may now finalize any initialization for that tablet.
371 //!
372 //! Events from tablets require a tool in proximity. Tools are also managed
373 //! by the tablet seat; a "tool added" event is sent whenever a tool is new
374 //! to the compositor. That event is followed by a number of descriptive
375 //! events about the hardware; currently that includes capabilities,
376 //! hardware id and serial number, and tool type. Similar to the tablet
377 //! interface, a wp_tablet_tool.done event is sent to terminate that initial
378 //! sequence.
379 //!
380 //! Any event from a tool happens on the wp_tablet_tool interface. When the
381 //! tool gets into proximity of the tablet, a proximity_in event is sent on
382 //! the wp_tablet_tool interface, listing the tablet and the surface. That
383 //! event is followed by a motion event with the coordinates. After that,
384 //! it's the usual motion, axis, button, etc. events. The protocol's
385 //! serialisation means events are grouped by wp_tablet_tool.frame events.
386 //!
387 //! Two special events (that don't exist in X) are down and up. They signal
388 //! "tip touching the surface". For tablets without real proximity
389 //! detection, the sequence is: proximity_in, motion, down, frame.
390 //!
391 //! When the tool leaves proximity, a proximity_out event is sent. If any
392 //! button is still down, a button release event is sent before this
393 //! proximity event. These button events are sent in the same frame as the
394 //! proximity event to signal to the client that the buttons were held when
395 //! the tool left proximity.
396 //!
397 //! If the tool moves out of the surface but stays in proximity (i.e.
398 //! between windows), compositor-specific grab policies apply. This usually
399 //! means that the proximity-out is delayed until all buttons are released.
400 //!
401 //! Moving a tool physically from one tablet to the other has no real effect
402 //! on the protocol, since we already have the tool object from the "tool
403 //! added" event. All the information is already there and the proximity
404 //! events on both tablets are all a client needs to reconstruct what
405 //! happened.
406 //!
407 //! Some extra axes are normalized, i.e. the client knows the range as
408 //! specified in the protocol (e.g. [0, 65535]), the granularity however is
409 //! unknown. The current normalized axes are pressure, distance, and slider.
410 //!
411 //! Other extra axes are in physical units as specified in the protocol.
412 //! The current extra axes with physical units are tilt, rotation and
413 //! wheel rotation.
414 //!
415 //! Since tablets work independently of the pointer controlled by the mouse,
416 //! the focus handling is independent too and controlled by proximity.
417 //! The wp_tablet_tool.set_cursor request sets a tool-specific cursor.
418 //! This cursor surface may be the same as the mouse cursor, and it may be
419 //! the same across tools but it is possible to be more fine-grained. For
420 //! example, a client may set different cursors for the pen and eraser.
421 //!
422 //! Tools are generally independent of tablets and it is
423 //! compositor-specific policy when a tool can be removed. Common approaches
424 //! will likely include some form of removing a tool when all tablets the
425 //! tool was used on are removed.
426
427 /// Unstable version 1
428 pub mod zv1 {
429 wayland_protocol!(
430 "./protocols/unstable/tablet/tablet-unstable-v1.xml",
431 []
432 );
433 }
434
435 /// Unstable version 2
436 pub mod zv2 {
437 wayland_protocol!(
438 "./protocols/unstable/tablet/tablet-unstable-v2.xml",
439 []
440 );
441 }
442}
443
444#[cfg(feature = "unstable")]
445pub mod text_input {
446 //! Text input protocol
447
448 /// Unstable version 1
449 pub mod zv1 {
450 wayland_protocol!(
451 "./protocols/unstable/text-input/text-input-unstable-v1.xml",
452 []
453 );
454 }
455
456 /// Unstable version 3
457 pub mod zv3 {
458 wayland_protocol!(
459 "./protocols/unstable/text-input/text-input-unstable-v3.xml",
460 []
461 );
462 }
463}
464
465pub mod viewporter {
466 //! Viewporter protocol
467 //!
468 //! Provides the capability of scaling and cropping surfaces, decorrelating the surface
469 //! dimensions from the size of the buffer.
470
471 wayland_protocol!("./protocols/stable/viewporter/viewporter.xml", []);
472}
473
474#[cfg(feature = "staging")]
475pub mod security_context {
476 //! This interface allows a client to register a new Wayland connection to
477 //! the compositor and attach a security context to it.
478 //!
479 //! This is intended to be used by sandboxes. Sandbox engines attach a
480 //! security context to all connections coming from inside the sandbox. The
481 //! compositor can then restrict the features that the sandboxed connections
482 //! can use.
483 //!
484 //! Compositors should forbid nesting multiple security contexts by not
485 //! exposing wp_security_context_manager_v1 global to clients with a security
486 //! context attached, or by sending the nested protocol error. Nested
487 //! security contexts are dangerous because they can potentially allow
488 //! privilege escalation of a sandboxed client.
489
490 #[allow(missing_docs)]
491 pub mod v1 {
492 wayland_protocol!(
493 "./protocols/staging/security-context/security-context-v1.xml",
494 []
495 );
496 }
497}
498
499#[cfg(feature = "staging")]
500pub mod alpha_modifier {
501 //! This interface allows a client to set a factor for the alpha values on a
502 //! surface, which can be used to offload such operations to the compositor,
503 //! which can in turn for example offload them to KMS.
504
505 #[allow(missing_docs)]
506 pub mod v1 {
507 wayland_protocol!(
508 "./protocols/staging/alpha-modifier/alpha-modifier-v1.xml",
509 []
510 );
511 }
512}
513
514#[cfg(feature = "staging")]
515pub mod fifo {
516 //! When a Wayland compositor considers applying a content update,
517 //! it must ensure all the update's readiness constraints (fences, etc)
518 //! are met.
519 //!
520 //! This protocol provides a way to use the completion of a display refresh
521 //! cycle as an additional readiness constraint.
522
523 #[allow(missing_docs)]
524 pub mod v1 {
525 wayland_protocol!(
526 "./protocols/staging/fifo/fifo-v1.xml",
527 []
528 );
529 }
530}
531
532#[cfg(feature = "staging")]
533pub mod commit_timing {
534 //! When a compositor latches on to new content updates it will check for
535 //! any number of requirements of the available content updates (such as
536 //! fences of all buffers being signalled) to consider the update ready.
537 //!
538 //! This protocol provides a method for adding a time constraint to surface
539 //! content. This constraint indicates to the compositor that a content
540 //! update should be presented as closely as possible to, but not before,
541 //! a specified time.
542 //!
543 //! This protocol does not change the Wayland property that content
544 //! updates are applied in the order they are received, even when some
545 //! content updates contain timestamps and others do not.
546 //!
547 //! To provide timestamps, this global factory interface must be used to
548 //! acquire a `wp_commit_timing_v1` object for a surface, which may then be
549 //! used to provide timestamp information for commits.
550
551 #[allow(missing_docs)]
552 pub mod v1 {
553 wayland_protocol!(
554 "./protocols/staging/commit-timing/commit-timing-v1.xml",
555 []
556 );
557 }
558}
559