wayland/protocol, branch 1.24

protocol: drop reference to linux-explicit-synchronization

2025-05-20T20:57:52Z

This protocol has been superseded. Replace this outdated reference with a generic hint that protocol extensions may provide this functionality. Signed-off-by: Simon Ser

protocol: Clarify sending of wl_seat.capabilities

2025-05-20T20:20:13Z

It wasn't explicitly stated that wl_seat.capabilities should also be sent on bind. Everyone did because it was obviously sensible. This also clarifies that static seat name should be sent before announcing capabilities so clients can associate these devices with the right seat name. Signed-off-by: David Edmundson

protocol: Clarify wl_buffer.release description

2025-03-15T23:12:07Z

Sebastian pointed out that the existing text could be read as wl_buffer.destroy not being allowed before the wl_buffer.release event arrives, contrary to what the wl_surface.attach description says. Clarify to be consistent with the latter. This is a follow-up for https://gitlab.freedesktop.org/wayland/wayland/-/merge_requests/141 . Signed-off-by: Michel Dänzer v2: * Simplify clarification, don't talk about callbacks. (Julian Orth) * Add reference to details in the description of wl_surface.attach. (Daniel Stone) v3: * Tweak clarification again. (Sebastian Wick) v4: * Make clarification even less ambiguous. (Simon Ser, Julian Orth) v5: * Just refer to the description of wl_surface.attach instead of trying to clarify anything here. (Sebastian Wick)

protocol: add wl_fixes interface

2024-11-18T09:25:20Z

This commit describes a new wl_fixes interface that can be used to destroy wl_registry objects. Users of libwayland-client should use it as follows: - call wl_fixes_destroy_registry(registry) - call wl_registry_destroy(registry) Users of libwayland-server should, in their implementation of the request, call wl_resource_destroy(registry). It should be similar in other protocol implementations. Signed-off-by: Julian Orth

protocol: document that wl_surface.offset is role-specific

2024-10-05T14:06:51Z

This request doesn't make sense for all surface roles. For instance, for maximized/tiled/fullscreen xdg_toplevel, for xdg_popup, for layer-shell surfaces, etc. Signed-off-by: Simon Ser

Add wl_keyboard key repeat events

2024-09-23T15:23:45Z

This allows the compositor to take over the responsibility of repeating keys. Signed-off-by: Andri Yngvason

protocol: clients should not emulate key-press events on enter

2024-09-10T07:36:48Z

The previous change introducing the logical state caused some confusion. Clarify that most application should not use the list of pressed keys. Signed-off-by: Julian Orth

protocol: clarify divergence in compositor behaviour

2024-05-29T12:23:38Z

This is intended to only document the current situation. Whether further behaviour will be defined is out of scope and left for protocol v7. See: https://gitlab.freedesktop.org/wayland/wayland/-/merge_requests/363 Signed-off-by: Hugo Osvaldo Barrera

protocol: explicitly describe wl_keyboard state

2024-05-09T14:43:19Z

And the allowed state transitions. There has been some confusion regarding which state transitions are allowed. This change should clarify this. Signed-off-by: Julian Orth

protocol: define content updates and their internal queue

2024-04-24T16:32:06Z

Multiple protocols use the term content update without a fill definition. It makes sense to define it in the core protocol so that not every other protocol has to define it. This is supposed to retain the current semantics and only changes the documentation while defining new terms. Signed-off-by: Sebastian Wick

protocol: mark wl_pointer.axis_discrete as deprecated

2024-04-24T16:18:28Z

Since version 8, this event isn't sent anymore. Signed-off-by: Simon Ser

Add support for the deprecated-since XML attribute

2024-04-24T16:18:28Z

This marks a request, event or enum entry as deprecated since a given version. Note that it's not clear what it means if an entry is deprecated at some version, and the enum is used from some completely different interface than where it was defined. However, that's a more general issue with enums, see: https://gitlab.freedesktop.org/wayland/wayland/-/issues/435 Signed-off-by: Simon Ser References: https://gitlab.freedesktop.org/wayland/wayland/-/issues/89

Clarify behavior of buffer transformations

2024-04-23T09:08:09Z

The new text describes how - Mutter - Plasma - Sway 1.8 - Jay behave. Sway 1.9 flipped the behavior of 90 degree and 270 degree set_buffer_transform requests. [mpv] also changed the behavior of its vo_wayland_dmabuf backend which makes it only work correctly on sway 1.9. [mpv]: https://github.com/mpv-player/mpv/pull/12509 It seems that the previous text was open to interpretation or at least caused some amount of confusion. Signed-off-by: Julian Orth

protocol: Undefine wl_display_sync callback data

2024-04-23T08:43:44Z

Signed-off-by: Colin Kinloch

wl_touch.cancel: document lack of frame event

2024-03-28T13:27:54Z

This appears to be what at least wlroots-based compositors and kwin do in practice. However, it's not abundantly clear from the protocol text what the expected behavior here is. This patch fixes that. Signed-off-by: Isaac Freund

protocol: document that color channels provide electrical values

2024-03-12T13:04:51Z

Expand the work done in [1] to document that all channels store electrical values. See the discussion in [2]. [1]: https://gitlab.freedesktop.org/wayland/wayland/-/merge_requests/316 [2]: https://gitlab.freedesktop.org/wayland/wayland/-/merge_requests/250#note_2311377 Signed-off-by: Simon Ser

protocol: mention wl_surface events from wl_output.{scale,transform}

2024-02-21T09:14:23Z

The wl_output events should not be used anymore for guessing the preferred scale and transform of a surface. We have explicit events for that now. Signed-off-by: Simon Ser

protocol: clarify pending wl_buffer destruction

2024-01-27T15:17:28Z

This matches the current behavior of KWin, Mutter, and Weston. References: https://gitlab.freedesktop.org/wayland/wayland/-/issues/387 Signed-off-by: Kirill Primak

protocol: add wl_shm.release request

2024-01-19T15:12:29Z

Allows clients to cleanly release wl_shm objects. Useful for clients using multiple wl_registry objects (e.g. via libraries). Signed-off-by: Simon Ser

protocol: clarify scale expecations

2024-01-19T14:35:06Z

Since the positivity of zero is debatable, and, in some cases scale was simply underspecified, clarify the situation. Signed-off-by: Ben Widawsky

protocol: document wl_surface.offset for sub-surfaces

2024-01-19T14:14:15Z

Document that the request is ignored, since this is the behavior of most compositors. Signed-off-by: Simon Ser

protocol: wl_subsurface will never be focused

2023-12-27T18:02:07Z

The spec does not describe which actions cause the compositor to assign keyboard focus to a surface, leaving this up to the compositor. Compositors differ in their behavior when the user clicks on a sub-surface. Some will move the keyboard focus to the subsurface whereas others will only ever assign the keyboard focus to toplevel surfaces. Some applications (e.g. firefox) seem to require the second behavior. This patch specifies that sub-surfaces never get the keyboard focus. Signed-off-by: Julian Orth

protocol: improve wl_subsurface.{set_position,place_above} description

2023-11-21T15:54:58Z

Don't mention when the parent surface state is applied; the parent surface isn't necessarily a sub-surface. Signed-off-by: Kirill Primak

protocol: clarify defaults with wl_compositor@v6

2023-11-21T15:50:11Z

This should be sufficient for clients to not decide to fallback to output based logic to determine scaling/transform when compositor doesn't send any of the v6 events. Signed-off-by: Kirill Chibisov

protocol: refer to wl_surface.offset in wl_data_device.start_drag

2023-11-21T15:36:00Z

Passing an offset to wl_surface.attach is not supported in the latest version of the interface. Signed-off-by: Simon Ser

protocol: fix whitespace

2023-07-19T11:01:17Z

This file uses tabs instead of 8 spaces. Signed-off-by: Simon Ser

protocol: refer to wl_surface.offset in set_cursor

2023-05-23T09:33:43Z

The offset in wl_surface.attach has been superseded by wl_surface.offset. Refer to the new request instead of using the deprecated one. Signed-off-by: Simon Ser

protocol: specify the exact form of premultiplication

2023-05-09T12:52:58Z

There are two ways to do pre-multiplication of the alpha channel into the color channels: on optical values or on electrical values. While pre-multiplication with optical values is arguably more correct, because operations like blending or scaling require pre-multiplied, optical color channels, wayland and compositors by default work with pre-multiplied electrical values. This is most likely a convention that Wayland took from Cairo. This commit makes sure that the expectation of pre-multiplied electrical values is properly documented. Signed-off-by: Sebastian Wick

protocol: add new shm formats

2023-05-03T19:10:32Z

This brings the format list up to date with libdrm 2.4.115. Signed-off-by: Manuel Stoeckl

protocol: improve wl_keyboard focus documentation

2023-04-12T13:37:51Z

The compositor must not send any key events while a surface is not focused, but in order to allow for common actions like ctrl+scroll for zooming to work with unfocused surfaces it may do so with modifiers. Signed-off-by: Xaver Hugl

protocol: disallow re-using wl_data_source

2023-04-04T11:39:08Z

As pointed out in [1], re-using a wl_data_source for multiple start_drag or set_selection requests has bad consequences, because this object has events that allo tracking the state of a selection/drag-and-drop operation. Tracking two operations at the same time isn't possible with this interface. [1]: https://lists.freedesktop.org/archives/wayland-devel/2019-January/039936.html Signed-off-by: Simon Ser Signed-off-by: Daniel Stone

protocol: Clarify meaning of input region for cursors, DnD icons

2023-02-27T20:51:51Z

Input region is ignored for cursors, DnD icons. Current wording implies that this state is temporary, but surfaces never lose the role once assigned, so reword to make it clearer. Signed-off-by: Mikhail Gusarov

protocol: reorder wl_data_offer.source_actions and wl_data_device.enter

2023-02-27T20:43:41Z

Most compositors send the wl_data_offer.source_actions event before the wl_data_device.enter event, i.e. after creation of the data offer. This contradicts to the wayland spec. On the other hand, it's reasonable to send all the information useful to the client before the enter event, rather than send mime types before the enter event and source actions (that don't depend on drop target) after the enter event. On the client side, toolkits such as Qt and GTK already expect to see the source actions before receiving the enter event. Given all of that, this change adjusts the spec to match the behavior observed in the compositors in the wild. Signed-off-by: Vlad Zahorodnii

protocol: do not change pending x and y when attaching a buffer

2023-02-27T20:39:41Z

Attaching a buffer with interface version 5 requires clients to pass zero to x and y but it still affects the pending surface state. Attaching a buffer after a request to offset therefore sets the pending x and y to zero. The intent of version 5 was to allow exactly this sequence of requests to work so let's just make sure the protocol actually spells it out. Signed-off-by: Sebastian Wick

protocol: add wl_pointer's axis relative physical direction

2023-02-21T15:32:03Z

This event adds the physical direction of the axis motion, relative to the axis event we get. Right now, when natural scrolling is enabled things like virtual volume sliders move the wrong way round. By adding the axis motion direction, we can have toolkits swap the scroll direction for applicable widgets, getting the right behavior on all widgets. Signed-off-by: Peter Hutterer Reviewed-by: Yong Bakos

protocol: add wl_surface.preferred_buffer_transform

2023-02-07T13:33:09Z

Same as the new wl_surface.preferred_buffer_scale event but for transform. No version bump needed since the previous commit did that. Signed-off-by: Simon Ser

protocol: add wl_surface.preferred_buffer_scale

2023-02-07T13:33:09Z

Right now, clients need to bind to wl_output globals, listen to wl_output.scale, listen to wl_surface.enter/leave, pick the highest scale factor. This is an issue because it breaks Wayland's "policy, not mechanism" motto. Clients take the decision of which scale to use depending on the outputs they're on, compositors have no say in this (apart from faking output events, which isn't great). This commit introduces a new wl_surface.preferred_buffer_scale event to allow compositors to directly indicate the preferred scale factor for each surface. This unlocks features which require dynamically changing the scale such as: - Accessibility features such as screen magnifier - In a VR environment, render surfaces close to the eye at a higher scale - HiDPI screenshots on LoDPI screens Signed-off-by: Simon Ser Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/271

protocol: wl_subsurface::destroy does not remove the role

2023-01-16T10:09:32Z

Role assigned to wl_surface cannot be removed. Delete contradicting text from wl_subsurface::destroy documentation. Signed-off-by: Mikhail Gusarov

protocol: add note about wl_buffer/wl_callback version

2022-12-07T09:04:49Z

This is an exception which can be confusing. Add an explicit note about it in the protocol text. Signed-off-by: Simon Ser

protocol: add defunct_role_object error

2022-11-29T13:46:54Z

This commit adds wl_surface.defunct_role_object error, which has semantics similar to xdg_wm_base.defunct_surfaces error, and is sent when a client destroys a surface while the corresponding role object still exists. Signed-off-by: Kirill Primak

protocol: remove wl_subsurface lifetime contradiction

2022-11-29T13:46:54Z

This statement assumes that a wl_surface can be destroyed before the corresponding wl_subsurface, which is not true, as wl_surface description explicitly states that the role object must be destroyed before the wl_surface itself. Signed-off-by: Kirill Primak

protocol: add wl_compositor.error.bad_parent

2022-09-21T10:17:57Z

This forbids loops in sub-surface trees. Signed-off-by: Simon Ser

protocol: mention protocol error name in wl_subcompositor.get_subsurface

2022-09-21T10:17:57Z

Let's be explicit here. Signed-off-by: Simon Ser

protocol: minor clarification for axis_discrete events

2022-06-30T09:12:08Z

Explicitly spell out that multiple axis_discrete events *for the same axis* within the same wl_pointer.frame are not permitted. References: https://gitlab.freedesktop.org/xorg/xserver/-/merge_requests/911#note_1438099 Signed-off-by: Peter Hutterer

wl_shell is not mandatory

2022-04-11T23:04:26Z

Even though it is part of wayland.xml, wl_shell is not mandatory for compositors to implement, and may be removed in a future version. Signed-off-by: Demi Marie Obenour

protocol: add the wl_pointer.axis_value120 events

2022-03-28T17:31:27Z

These events are for high-resolution wheels. Each logical wheel click represents an axis value120 value of 120, fractions of a wheel click an integer fraction thereof. The new event replaces wl_pointer.axis_discrete for wl_pointer versions 8 and above. Signed-off-by: Peter Hutterer

protocol: wl_shm.format events are actually sent after bind

2022-02-21T10:13:45Z

Protocol documentation mistakenly specified that wl_shm.format events are sent at connection setup time, but that's impossible (clients do not yet know ID of wl_shm object at the time) and contradicts implementation in libwayland. Signed-off-by: Mikhail Gusarov

protocol: xkb_v1 is null-terminated

2022-01-31T21:31:07Z

Closes #270 Signed-off-by: Julian Orth

doc: fix typo in wl_data_device.data_offer

2022-01-10T10:07:22Z

Signed-off-by: Taishi Eguchi

protocol: clarify wl_shm_pool.resize

2022-01-07T13:30:29Z

Add a note that the request only changes the size of the memory mapping and does not touch the mapped file. Signed-off-by: Max Ihlenfeldt

protocol: clarify wl_data_offer::selection

2021-11-15T13:20:41Z

Clearly specify that switching focus within the same client doesn't mean a new selection will be send. Signed-off-by: Jan Grulich

protocol: sync wl_shm.format with libdrm 2.4.108

2021-11-12T01:15:22Z

The four new formats added (all 16 bpc, RGB colorspace) are very useful for applications providing high bit depth content and rendering their buffers on CPU, as computations with 16 bit unsigned integers are often more efficient than with the (half float, 10 bit) alternative formats. Signed-off-by: Manuel Stoeckl

protocol: wl_shm uses pre-multiplied alpha

2021-11-04T08:53:47Z

Add a note about pre-multiplied alpha for all wl_shm formats. Include an escape hatch in the spec to allow other protocol extensions to override this. Signed-off-by: Simon Ser Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/61

protocol: add wl_output.{name,description}

2021-10-28T14:03:04Z

This is inspired from xdg-output-unstable-v1. This allows clients to get the name and description without having to use xdg_output. This should eventually allow us to restrict xdg_output to clients like Xwayland. The name is a unique non-persistent user-friendly string that can be used to refer to an output. This can be used by Wayland clients to refer to a specific wl_output (e.g. across processes or in CLI arguments). The description is a non-unique user-friendly string that can be displayed to the user. Signed-off-by: Simon Ser References: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/issues/7

protocol: add note about wl_output.done in events

2021-10-28T14:03:04Z

Mention that geometry, mode and scale wl_output events are followed by a done event. Signed-off-by: Simon Ser

protocol: Add wl_surface.offset

2021-10-28T12:39:39Z

This is meant to address the issue where the call to 'wl_surface.attach' is done by e.g. Vulkan, meaning applications cannot affect the values of the offset passed as the x and y arguments. The lack of ability to pass these is problematic when using the Vulkan for e.g. drawing DND surfaces, as the buffer offset is used to implement the drag icon hotspots. Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/148 Signed-off-by: Jonas Ådahl Reviewed-by: Simon Ser

protocol: mention that buffers with alpha are assumed premultiplied

2021-09-29T14:43:21Z

This turns out to be the default assumption by compositors, OpenGL, and the DRM framework. Let's say it explicitly to avoid misinterpretation. See https://lists.freedesktop.org/archives/wayland-devel/2021-September/041990.html. Signed-off-by: Matt Hoosier

protocol: mention that keymap mapping must be read-only

2021-09-16T08:25:05Z

It may be obvious that the mapping must be established in read-only mode, but it wasn't specified in the specification text. Signed-off-by: Simon Ser

protocol: clarify wl_seat.name description

2021-07-06T11:57:39Z

Define the expected properties of the seat name. Signed-off-by: Simon Ser

protocol: allow immediate wl_buffer.destroy if not re-used

2021-06-11T14:05:27Z

Allow wl_buffer objects to be destroyed without having to wait for wl_buffer.release if the underlying storage isn't going to be re-used. The main motivation for this is to avoid glitches when a client is torn down. When a client disconnects, all of its objects are destroyed in arbitrary order. However some compositors will still need to access the destroyed buffer's underlying storage afterwards, e.g. for visual effects (fade-out) or for atomic layout updates (wait for other clients to commit a new buffer before hiding the buffer). It's still incorrect for clients to destroy a wl_buffer and mutate the underlying storage without waiting for wl_buffer.release. Signed-off-by: Simon Ser Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/185

protocol: drop reference to wl_drm

2021-05-27T08:48:40Z

Change the wl_drm reference to linux-dmabuf. wl_drm is a legacy, private Mesa protocol that shouldn't be used by regular clients. Signed-off-by: Simon Ser

Document serial param usage in wl_pointer.set_cursor

2021-05-04T15:26:48Z

Serial is supposed to contain the latest wl_pointer.enter value received by clients but it was not even mentioned in the docs, so add it to avoid misinterpretations. Signed-off-by: Nick Diego Yamane

protocol: Specify wl_callback::done to be a destructor event

2021-01-27T17:49:10Z

It's the only destructor event in the core protocol, and destructor events were previously unannotated. Signed-off-by: Tadeo Kondrak

protocol: Add type attribute to events

2021-01-27T17:49:10Z

This allows specifying events to be destructors, which is useful for non-C language bindings. It is unused in wayland-scanner. Signed-off-by: Tadeo Kondrak

protocol: sync wl_shm.format with libdrm 2.4.104

2021-01-19T16:16:54Z

This adds 4 new formats. Signed-off-by: Simon Ser Reviewed-by: Jonas Ådahl Acked-by: Daniel Stone

protocol: deprecate non-current wl_output.mode

2020-10-29T13:07:20Z

The current wl_output.mode event has several issues when used to advertise modes that aren't current: - It's not possible to remove some modes. This is an issue for virtual outputs and when the kernel prunes some modes because of link limitations. - wl_output.mode fails to carry metadata such as aspect ratio, which results in duplicated or missing modes. - It's not clear, given the current set of protocols, how non-current modes are useful to clients. Xwayland ignores non-current modes. GNOME and wlroots already only advertise the current mode because of these issues. If a protocol needs the clients to know about all available modes, it should advertise these modes itself instead of relying on wl_output.mode. Signed-off-by: Simon Ser Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/92

protocol: make it clear wl_surface.enter/leave are not for frame throttling

2020-10-29T13:02:50Z

Some clients rely on wl_surface.enter/leave to start/stop their rendering loop. There are cases where this doesn't work: - Some compositors don't send wl_surface.leave when a toplevel is hidden. For instance Sway doesn't send this event when a toplevel is on an inactive workspace (but doesn't send wl_surface.frame events). - Some compositors might still want applications to continue to render even if away from outputs. For instance a compositor that allows to screen record individual toplevels might not send a wl_surface.enter event for hidden toplevels. Signed-off-by: Simon Ser

protocol: Clarify how clients can cancel a drag operation

2020-10-29T12:17:28Z

Explicitly say that destroying a wl_data_source previously used in a wl_data_device::start_drag request will cancel the DND session. This is currently the only way to do it from client side (besides those "indirect" ones already documented) and all compositors work like that but it is not clear spec-wise it is the expected behaviour. Signed-off-by: Nick Diego Yamane

protocol: Minor gramatical fix.

2020-08-14T00:30:22Z

Signed-off-by: Christopher James Halse Rogers

protocol: disambiguate key codes in wl_keyboard.key

2020-06-16T09:35:14Z

Explain that wl_keyboard.key yields platform-specific key codes. Some compositors use Linux key codes (defined in the linux/input-event-codes.h header file, e.g. KEY_ESC), however clients should not assume that this is always the case. The only reliable way for clients to interpret key codes is to feed them into a keyboard mapping. Signed-off-by: Simon Ser

Clarify clients behavior on wl_keyboard.leave

2020-06-12T21:15:11Z

Clients must assume that every key, including modifiers, are lifted after getting wl_keyboard.leave event, not doing so could lead to key repeat keep going after the user changes focus, or stuck modifiers, when the user interacts with client without keyboard focus. Signed-off-by: Kirill Chibisov

Clarify the order of wl_keyboard.modifiers

2020-06-12T21:15:11Z

Consider that we set the modifier for the modifier key as well, and that you have the option to change your layout when both shifts pressed. This realized by making the shift keys produce 'Group_switch' when you press the shift key and the shift modifier is already active. So sending modifier before the key event will result in 'Group_switch' each time you press shift. That being said, the order of modifiers should be updated after the key/enter event, so it'll only affect future keypresses, not the current one. See: https://lists.x.org/archives/xorg-devel/2014-July/043110.html Signed-off-by: Kirill Chibisov

protocol: add seat missing_capability error

2020-06-05T09:36:39Z

The protocol says: > It is a protocol violation to issue this request on a seat that > has never had the pointer capability. But never defines an error code. Signed-off-by: Simon Ser Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/165

Replace initial 8 spaces with a tab for all xml files

2020-04-29T12:21:33Z

This is the style used in wayland.xml which is the only file we really care about for git blame information. So let's adjust all others to that style for consistency and fix editorconfig to avoid messing this up in the future. Signed-off-by: Peter Hutterer

protocol: add invalid_size error to wl_surface

2020-03-05T14:48:36Z

This allows the compositor to send an error when the client submits a buffer whose size is not divisible by the buffer scale. Previously, the protocol said it was a client error but didn't specify any error code. Signed-off-by: Simon Ser Closes: https://gitlab.freedesktop.org/wayland/wayland/issues/145

protocol: add missing enums for wl_data_device_manager.dnd_action

2020-01-21T11:40:09Z

Signed-off-by: Simon Ser

protocol: fix typo in wl_data_offer.set_actions description

2020-01-03T05:13:49Z

Signed-off-by: Michael Forney

protocol: invalid_method is sent on malformed request

2019-09-10T09:47:19Z

Currently libwayland sends a wl_display.invalid_method when arguments provided with a request are invalid (e.g. too short, see wl_client_connection_data). Clarify the protocol by adding that invalid_method can be sent on malformed request. Signed-off-by: Simon Ser

protocol: sync wl_shm.format with libdrm 2.4.99

2019-09-06T12:09:22Z

This adds 42 new formats. Signed-off-by: Simon Ser

protocol: add a comment about the wl_shm.format script

2019-09-06T12:09:22Z

Add a comment to wl_shm.format to advise contributors to use the automated script (generate-shm-formats.py) instead of updating the list manually. Signed-off-by: Simon Ser

Add an automated script to update wl_shm.format

2019-09-06T12:09:22Z

This prevents mismatches and missing formats between wl_shm.formats and drm_fourcc.h. The script collects DRM_FORMAT_* constants from drm_fourcc.h, compares the list with the current wayland.xml entries (checking for any mismatch) and then appends missing entries to wayland.xml. Enum values are obtained by executing a generated C file which prints the constants. There is no other reliable way to get these values as they are defined via various macros. There is no widespread Python library able to parse an XML file and format it with all whitespace preserved. For this reason, we don't use an XML library to create the new XML elements. Instead, we keep track of the line number of the last wl_shm.format enum entry and add new entries right after. To be able to read the line number of an element, we use lxml (the standard library doesn't retain line number information). Signed-off-by: Simon Ser

Improve description of wl_surface

2019-08-17T11:12:54Z

The original text makes some assumptions about surfaces which may not be true and fails to capture some details which are important to the essential traits of a wl_surface.

wayland.xml: Make releases for multiple 'wl_surface.attach' undefined

2019-07-09T17:26:11Z

Fixes #46 The way wl_buffer is specified makes this situation inherently racy, meaning there is no way this can be done unambiguously. Current real compositor implementations already have differing behaviour for this, so any client relying on it was already broken, if any such client exists. This specifically only singles out wl_buffer.release as being undefined; every other aspect of it should still be valid. This is so existing and correct uses of multiple attaches are still valid, where a "static"/immutable wl_buffer is being used (i.e. they don't care about the release event). Signed-off-by: Scott Anderson

protocol: clarify wl_display.delete_id description

2019-07-05T23:42:24Z

libwayland-server only sends wl_display.delete_id events when it responds to a client's destruction of a client-allocated object. server-allocated objects are silently removed, as per `wl_resource_destroy`. Signed-off-by: Manuel Stoeckl

protocol: allow to send a zero output refresh rate

2019-04-27T21:44:04Z

Fixed refresh rate doesn't always make sense for all outputs. In case it's not available or not relevant, allow compositors to send zero. For instance the can be the case for virtual outputs. Signed-off-by: Simon Ser

wayland.xml: document invalid_finish error in wl_data_offer.finish

2019-04-19T16:32:08Z

Explicitly state that the invalid_finish protocol error would be raised when wl_data_offer.finish request is sent for non drag-and-drop operations. Signed-off-by: Harish Krupo

protocol: warn clients about some wl_output properties

2019-02-20T16:07:05Z

All wl_output properties don't always make sense for all compositors. Some compositors might not implement a "global compositor space", (e.g. 3D compositors) in which case properties like x and y don't make sense. Some compositors might expose virtual outputs, in which case modes, make and model are not relevant. In a lot of these situations, information from xdg_output is better suited. Compositors also expose output refresh rate, which shouldn't be used for synchronization purposes. Signed-off-by: Simon Ser Reviewed-by: Daniel Stone Reviewed-by: Jonas Ådahl Reviewed-by: Derek Foreman

proto, server: Add internal server error message. (v2)

2019-01-29T13:58:19Z

Many languages such as C++ or Rust have an unwinding error-reporting mechanism. Code in these languages can (and must!) wrap request handling callbacks in unwind guards to avoid undefined behaviour. As a consequence such code will detect internal server errors, but have no way to communicate such failures to the client. This adds a WL_DISPLAY_ERROR_IMPLEMENTATION error to wl_display so that such code can notify (and disconnect) clients which hit internal bugs. While servers can currently abuse other wl_display errors for the same effect, adding an explicit error code allows clients to tell the difference between errors which are their fault and errors which are the server's fault. This is particularly interesting for automated bug reporting. v2: Rename error from "internal" to "implementation", in sympathy with X11's BadImplementation error. Add more justification in the commit message. Signed-off-by: Christopher James Halse Rogers Acked-by: Pekka Paalanen Reviewed-by: Pekka Paalanen

protocol: prefer wl_surface.damage_buffer

2018-11-30T15:25:14Z

This commit makes wl_surface.damage_buffer preferred over wl_surface.damage. wl_surface.damage can be implemented in a non-optimal way by the compositor (e.g. by always damaging the whole buffer). Having two requests makes it complicated for the compositor to handle damage, making it necessary to transform one into the other's coordinates. Moreover, integration with wp_viewporter is tricky. Signed-off-by: Simon Ser Acked-by: Pekka Paalanen Reviewed-by: Derek Foreman

protocol: Bump seat to version 7 and require keymaps be private

2018-11-30T15:17:57Z

Weston commit 76829fc4eaea329d2a525c3978271e13bd76c078 (and similar commits for other compositors) protects the compositor's keyboard mapping from client damage by duplicating the keymap for every client. On some systems there are other potential fixes for this - such as using sealed memfds on linux - but we can't use them since essentially all client code anywhere has mapped the keyboard map with a MAP_SHARED mmap() call. While we can't break years worth of code, we can require any future clients to use MAP_PRIVATE if they use a seat version above 6. If a compositor can't use sealing or a similar facility, it should still protect itself with copied keymaps, but clients must always assume shared mapping of a keymap will fail. Signed-off-by: Derek Foreman Reviewed-by: Simon Ser Reviewed-by: Daniel Stone Reviewed-by: Philipp Kerling Acked-by: Pekka Paalanen

protocol: allow to send a zero physical output size

2018-07-24T10:26:17Z

Physical size doesn't always make sense for all outputs. In case it's not available or not relevant, allow compositors to send zero. Acked-by: Daniel Stone Acked-by: Jonas Ådahl Acked-by: Olivier Fourdan

tests: Check for wrong fd delivery with zombie objects

2018-01-09T15:20:00Z

Until recently, if an event attempting to deliver an fd to a zombie object was demarshalled after the object was made into a zombie, we leaked the fd and left it in the buffer. If another event attempting to deliver an fd to a live object was in that same buffer, the zombie's fd would be delivered instead. This test recreates that situation. While this is a ridiculously contrived way to force this race - delivering an event from a destruction handler - I do have reports of this race being hit in real world code. Signed-off-by: Derek Foreman Acked-by: Daniel Stone

tests: Add a test for fd leaks on zombie objects

2018-01-09T15:20:00Z

Until recently, if a client destroying a resource raced with the server generating an event on that resource that delivered a file descriptor, we would leak the fd. This tests for a leaked fd from that race condition. Reviewed-by: Daniel Stone Signed-off-by: Derek Foreman

protocol: make get_subsurface double-buffered

2017-12-05T10:43:17Z

The existing specification was not explicitly clear on when wl_subcompositor.get_subsurface request actually adds the sub-surface to the parent in the compositor's scenegraph. The implicit assumption was that this happens immediately, but it was not written anywhere. If it happens immediately, the client doing things in a wrong order may cause a glitch on screen. Particularly, if the wl_surface B that is going to be a sub-surface for wl_surface A (the parent) already has a buffer committed, and the parent surface is mapped, then get_subsurface will (may?) cause wl_surface B to become mapped immediately. That leaves no time to set up the sub-surface z-order or position before mapping, hence there can be a visible glitch. The way to avoid that, given that the parent surface is mapped, is to not commit a buffer to wl_surface B until all the sub-surface setup is done. However, doing the sub-surface setup always requires a wl_surface.commit on the parent surface unless the defaults happen to be correct. To make setting up a subsurface slightly easier by removing one possibility for a glitch, this patch amends the specification to require a wl_surface.commit on the parent surface for get_subsurface to complete. The sub-surface cannot become mapped before a parent commit. This change may break existing clients that relied on the glitchy sequence to not need a parent surface commit to map the sub-surface. However, presumably all uses would at least issue a wl_subsurface.set_position, which requires a parent surface commit to apply. That would guarantee that there is a parent surface commit after get_subsurface, and so reduces the chances of breaking anything. In other cases, this change may simply remove a possibility for the glitch. This patch also adds a note about changing wl_surface.commit behaviour on wl_subcompositor.get_subsurface. (That could be a separate patch.) The behaviour of wl_subsurface.destroy remains as specified, even though it is now slightly asymmetrical to get_subsurface. This is emphasized by adding the word "immediately". The effects of destruction were already explicitly documented, as is the way to achieve synchronized unmapping, so changing destruction behaviour would likely be more disruptive, and also open up more corner cases (what would happen between destroy and unmapping?). Bug: https://phabricator.freedesktop.org/T7358 Signed-off-by: Pekka Paalanen Reviewed-by: Daniel Stone Reviewed-by: Derek Foreman Reviewed-by: Jonas Ådahl Reviewed-by: Martin Gräßlin

protocol: Add deprecation note about wl_shell

2017-12-04T19:45:38Z

Now that xdg_shell is stable and much better defined than wl_shell we can finally deprecate wl_shell and guide users towards xdg_shell instead. Signed-off-by: Jonas Ådahl Acked-by: Pekka Paalanen Reviewed-by: Daniel Stone

protocol: Suggest get_registry not be called frequently

2017-10-02T08:45:56Z

I've heard some complaints that wl_display.get_registry "leaks" server memory because wl_registry has no destructor. While this isn't strictly true - all those resources are freed when the client disconnects - it's a bit of a gotcha for neophytes. Since wl_registry's version is not requested in any way through wl_display.get_registry, we can't add a destructor request without breaking ABI. So let's be a little more clear about the result of getting too many wl_registry objects. Signed-off-by: Derek Foreman Reviewed-by: Daniel Stone Reviewed-by: Pekka Paalanen

protocol: add axis_source.wheel_tilt

2017-01-24T10:00:19Z

Unlike a wheel rotation, a wheel tilt is a discrete-only axis. Wheel rotations are mapped to degrees in libinput but that that does not apply to wheel tilt axes where there is no physical equivalent. Signed-off-by: Peter Hutterer Reviewed-by: Jonas Ådahl Acked-by: Daniel Stone Reviewed-by: Daniel Stone Reviewed-by: Yong Bakos

protocol: indentation fixes

2016-11-21T11:43:22Z

8 spaces changed to one tab Signed-off-by: Peter Hutterer Reviewed-by: Daniel Stone Acked-by: Bryce Harrington

protocol: spell out that we're using linux/input-event-codes.h button codes

2016-11-21T11:07:12Z

Because we already rely on it in the callers anyway. This is a retrofit, which is not ideal but I'm not sure any compositor out there uses anything else. Might as well define it. Signed-off-by: Peter Hutterer Reviewed-by: Jonas Ådahl Reviewed-by: Daniel Stone

protocol: Extend wl_touch with touchpoint shape and orientation

2016-11-16T16:35:19Z

This CL updates the wl_touch interface with a shape and orientation event. The shape/orientation of a touch point is not relevant for most UI applications, but allows a better experience in some cases such as drawing apps. The events are used by the compositor to inform the client about changes in the shape and orientation of a touchpoint, which is approximated by an ellipse and it's angle to the y-axis. The event is optional and only sent when compositor and the touch device support this type of information. The client is responsible for making a reasonable assumption about the touch shape if no shape is reported. Signed-off-by: Dennis Kempin Reviewed-by: Peter Hutterer Reviewed-by: Yong Bakos Reviewed-by: Daniel Stone