staging/color-management: add Windows BT.2100 image description request

Just like with scRGB, Windows does (generally) not adjust BT.2100 images to
the viewing conditions of the user; this is instead expected to be handled by
the application or the display.
Adding this image description allows compositors to implement special handling
for all Windows HDR content, instead of being limited to scRGB in that regard.

Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>

.editorconfig

@@ -0,0 +1,6 @@
+root = true
+
+[*.xml]
+indent_style = space
+indent_size = 2
+tab_width = 8

.gitignore

@@ -1,11 +0,0 @@
-Makefile
-Makefile.in
-configure
-config.log
-config.status
-compile
-install-sh
-missing
-*.pc
-autom4te.cache
-aclocal.m4

.gitlab-ci.yml

@@ -0,0 +1,71 @@
+.templates_sha: &template_sha d11c0dd4c1c9a69c14b4af9b50cdd12b89d24672
+
+include:
+  - project: 'freedesktop/ci-templates'
+    ref: *template_sha
+    file: '/templates/debian.yml'
+  - project: 'freedesktop/ci-templates'
+    ref: *template_sha
+    file: '/templates/ci-fairy.yml'
+
+stages:
+  - review
+  - containers-build
+  - test
+
+variables:
+  FDO_UPSTREAM_REPO: wayland/wayland-protocols
+
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
+      when: never
+    - if: $CI_COMMIT_BRANCH
+
+.debian:
+  variables:
+    FDO_DISTRIBUTION_VERSION: trixie
+    FDO_DISTRIBUTION_PACKAGES: 'build-essential pkg-config meson git ca-certificates libffi-dev libexpat1-dev libxml2-dev'
+    FDO_DISTRIBUTION_TAG: '2026-04-05.0'
+    FDO_DISTRIBUTION_EXEC: 'env FDO_CI_CONCURRENT=${FDO_CI_CONCURRENT} ./.gitlab-ci/debian-install.sh'
+
+check-commit:
+  extends:
+    - .fdo.ci-fairy
+  stage: review
+  script:
+    - ci-fairy check-commits --signed-off-by --junit-xml=results.xml
+  variables:
+    GIT_DEPTH: 100
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: always
+    - when: never
+  artifacts:
+    reports:
+      junit: results.xml
+
+container_build:
+  extends:
+    - .debian
+    - .fdo.container-build@debian
+  stage: containers-build
+  variables:
+    GIT_STRATEGY: none
+
+test-meson:
+  stage: test
+  extends:
+    - .debian
+    - .fdo.distribution-image@debian
+  script:
+    - meson build
+    - ninja -C build
+    - meson test -C build
+    - ninja -C build install
+  artifacts:
+    name: wayland-protocols-$CI_COMMIT_SHA
+    when: always
+    paths:
+    - $CI_PROJECT_DIR/build/meson-logs

.gitlab-ci/debian-install.sh

@@ -0,0 +1,14 @@
+#!/bin/sh -eux
+
+# Note: don't forget to bump FDO_DISTRIBUTION_TAG when editing this file!
+
+git clone --branch 1.25.0 --depth=1 https://gitlab.freedesktop.org/wayland/wayland
+cd wayland/
+git show -s HEAD
+meson build/ -Dtests=false -Ddocumentation=false
+ninja -j${FDO_CI_CONCURRENT:-4} -C build/ install
+cd ..
+rm -rf wayland/
+
+echo "/usr/local/lib" >/etc/ld.so.conf.d/local.conf
+ldconfig

.gitlab/merge_request_templates/New protocol.md

@@ -0,0 +1,9 @@
+
+
+#### Requirements for merging
+
+- [ ] Review
+- [ ] Implementations
+- [ ] ACKs from members
+
+/label ~"New Protocol" ~"In 30 day discussion period" ~"Needs acks" ~"Needs implementations" ~"Needs review"

.mailmap

@@ -0,0 +1,3 @@
+Faith Ekstrand <faith@gfxstrand.net> <jason@jlekstrand.net>
+Faith Ekstrand <faith@gfxstrand.net> <jason.ekstrand@intel.com>
+Faith Ekstrand <faith@gfxstrand.net> <jason.ekstrand@collabora.com>

GOVERNANCE.md

@@ -0,0 +1,217 @@
+# wayland-protocols governance
+
+This document governs the maintenance of wayland-protocols and serves to outline
+the broader process for standardization of protocol extensions in the Wayland
+ecosystem.
+
+## 1. Membership
+
+Membership in wayland-protocols is offered to stakeholders in the Wayland
+ecosystem who have an interest in participating in protocol extension
+standardization.
+
+### 1.1. Membership requirements
+
+1. Membership is extended to projects, rather than individuals.
+2. Member projects represent general-purpose projects with a stake in multiple
+   Wayland protocols (e.g. compositors, GUI toolkits, etc), rather than
+   special-purpose applications with a stake in only one or two.
+3. Each member project must provide named individuals as point of contact
+   for that project who can be reached to discuss protocol-related matters.
+4. During a vote, if any points-of-contact for the same member project
+   disagree, the member project's vote is considered blank.
+
+### 1.2. Becoming a member
+
+1. New member projects who meet the criteria outlined in 1.1 are established by
+   invitation from an existing member. Projects hoping to join should reach out
+   to an existing member project or point of contact, asking for this
+   invitation.
+2. Prospective new member projects shall file a merge request tagged
+   `governance` adding themselves to the list in `MEMBERS.md`, noting their
+   sponsor member.
+3. A point of contact for the sponsor member shall respond acknowledging their
+   sponsorship of the membership.
+4. A 14 day discussion period for comments from wayland-protocols members will
+   be held.
+5. At the conclusion of the discussion period, the new membership is
+   established unless their application was NACKed by a 1/2 majority of all
+   existing member projects.
+6. Member projects may vary their point(s) of contact by proposing the addition
+   and/or removal of points of contact in a merge request tagged `governance`,
+   subject to approval as in points 4 and 5 above.
+
+### 1.3. Ceasing membership
+
+1. A member project, or point of contact, may step down by submitting a merge
+   request tagged `governance` removing themselves from `MEMBERS.md`.
+2. A removal vote may be called for by an existing member project or point of
+   contact, by filing a merge request tagged `governance`, removing the
+   specific member project or point of contact from `MEMBERS.md`. This begins a
+   14 day voting & discussion period.
+3. At the conclusion of the voting period, the member is removed if the votes
+   total 2/3rds of all current member projects.
+4. Removed members are not eligible to apply for membership again for a period
+   of 1 year.
+5. Following a failed vote, the member project who called for the vote cannot
+   call for a re-vote or propose any other removal for 90 days.
+
+## 2. Protocols
+
+### 2.1. Protocol namespaces
+
+1. Namespaces are implemented in practice by prefixing each interface name in a
+   protocol definition (XML) with the namespace name, and an underscore (e.g.
+   "xdg_wm_base").
+2. Protocols in a namespace may optionally use the namespace followed by a dash
+   in the name (e.g. "xdg-shell").
+3. The "xdg" namespace is established for protocols letting clients
+   configure their surfaces as "windows", allowing clients to affect how they
+   are managed.
+4. The "wp" namespace is established for protocols generally useful to Wayland
+   implementations (i.e. "plumbing" protocols).
+5. The "ext" namespace is established as a general catch-all for protocols that
+   fit into no other namespace.
+
+#### 2.1.1 Experimental protocol namespacing
+
+1. Experimental protocols begin with the "xx" namespace and do not include any relation
+   to namespaces specified in section 2.1.
+2. Namespacing of experimental protocols is determined upon promotion.
+
+### 2.2. Protocol inclusion requirements
+
+1. All protocols found in the "xdg" and "wp" namespaces at the time of writing
+   are grandfathered into their respective namespace without further discussion.
+2. Protocols in the "xdg" and "wp" namespace are eligible for inclusion only if
+   ACKed by at least 3 members.
+3. Protocols in the "xdg" and "wp" namespace are ineligible for inclusion if
+   NACKed by any member.
+4. Protocols in the "xdg" and "wp" namespaces must have at least 3 open-source
+   implementations (either 1 client + 2 servers, or 2 clients + 1 server) to be
+   eligible for inclusion.
+5. Protocols in the "ext" namespace are eligible for inclusion only if ACKed by
+   at least 2 member projects.
+6. Protocols in the "ext" namespace must have at least one open-source client &
+   one open-source server implementation to be eligible for inclusion.
+7. "Open-source" is defined as distributed with an Open Source Initiative
+   approved license.
+8. All protocols are eligible for inclusion only if formally reviewed in-depth
+   by at least one member project. For the purposes of this clause, reviews from
+   the individual protocol author(s) are disregarded.
+
+#### 2.2.1 Experimental protocol inclusion requirements
+
+1. Experimental protocols must be valid XML which can be consumed by wayland-scanner.
+2. All such protocols must be created with a proposal merge request outlining the
+   need for and purpose of the protocol.
+3. All such protocols must be clearly tagged as experimental.
+
+### 2.3. Introducing new protocols
+
+1. A new protocol may be proposed by submitting a merge request to the
+   wayland-protocols Gitlab repository.
+2. Protocol proposal posts must include justification for their inclusion in
+   their namespace per the requirements outlined in section 2.2.
+3. An indefinite discussion period for comments from wayland-protocols members
+   will be held, with a minimum duration of 30 days beginning from the time when
+   the MR was opened. Protocols which require a certain level of implementation
+   status, ACKs from members, and so on, should use this time to acquire them.
+4. When the proposed protocol meets all requirements for inclusion per section
+   2.2, and the minimum discussion period has elapsed, the sponsoring member may
+   merge their changes into the wayland-protocol repository.
+5. Amendments to existing protocols may be proposed by the same process, with
+   no minimum discussion period.
+6. Declaring a protocol stable may be proposed by the same process, with the
+   regular 30 day minimum discussion period.
+7. A member project has the option to invoke the 30 day discussion period for any
+   staging protocol proposal which has been in use without substantive changes
+   for a period of one year.
+
+### 2.4. Development stalemate resolution
+
+1. In the event that a discussion thread reaches a stalemate which cannot be
+   resolved, a tie-breaking vote can be requested by the protocol author or
+   any member project.
+2. All member projects are eligible to vote in stalemate tie-breakers. Each project
+   may cast a single vote.
+3. Tie-breaker voting periods last no fewer than seven days.
+4. Tie-breaker votes must be between two choices.
+5. Any member project may elect to extend the voting period by an additional seven days.
+   This option may only be invoked once per member project per tie-breaker and shall
+   not be used without cause.
+6. At the end of the voting period, the choice with the most votes is declared
+   the winner, and development proceeds using that idea.
+7. In the event of a tie, the protocol author casts the deciding vote.
+
+### 2.5. Representation of non-members
+
+1. A protocol proposed by a non-member inherently begins at a
+   responsibility deficit as compared to one initiated by a member project.
+2. To address this, any protocol proposed by a non-member intended for `staging/` or
+   `stable/` may have a sponsor designated from a member project
+3. The sponsor should have a strong understanding of the protocol they
+   represent as well as the time required to drive it.
+4. The sponsor shall be responsible for representing the protocol and its
+   author in all cases which require membership, e.g., stalemate voting.
+5. The member projects shall provide a sponsor for a non-member project upon request.
+6. An author may make a one-time request for a different sponsor at any point.
+
+### 2.3.1 Introducing new experimental protocols
+
+1. Experimental protocols are merged into wayland-protocols after a two
+   week review period upon the author's request unless a NACK has been given or
+   a WAIT is in progress.
+2. If all NACKs are removed from an experimental protocol, the two week review period is
+   started anew.
+
+### 2.3.2 Experimental protocol removal policy
+
+1. Unmaintained experimental protocols are removed after a three month period of
+   inactivity by its author, as determined by all of the following being true:
+   * No changes have been made to the protocol by the author
+   * No comments have been made to the protocol merge request by the author
+   * No mails have been sent to the mailing list persuant to the protocol by the author
+2. A notification of intent to remove shall be given to the author in the protocol
+   merge request, and the protocol shall only be removed following a one week grace period
+   of continued inactivity.
+
+### 2.3.3 Experimental protocol promotion
+
+1. A merged experimental protocol may be promoted to `staging/`
+   upon request if it meets the requirements for landing as a
+   `staging/` protocol.
+2. Upon promotion, an experimental protocol is removed from `experimental/`.
+
+## 3. NACKs
+
+1. Expressing a NACK is the sole purview of listed points-of-contact from member projects,
+   as specified in MEMBERS.md.
+   A NACK must be grounded in technical reasoning, and it constitutes the final resort
+   to block protocols which would harm the ecosystem or the project.
+2. Any non-point-of-contact mentioning a NACK on a non-governance protocol issue, merge request,
+   or mailing list thread, for any purpose, shall be banned from the project for a
+   period of no fewer than three months. Additional penalties for repeat infractions
+   may be imposed at the discretion of a membership majority. A warning, delivered in private
+   if at all possible, shall be issued instead of a ban for first-time violations of this rule.
+   Any comments violating this rule shall be explicitly marked by member projects to indicate that
+   the NACK is invalid and has no bearing.
+3. Any member project mentioning a NACK on a non-governance protocol issue, merge request,
+   or mailing list thread, for any reason that may be considered non-technical,
+   may undergo trial by eligible member projects upon receiving a written accusation of
+   impropriety. This accusation may be public or private, and it may occur by any method
+   of written communication.
+   If this NACK is determined by 2/3 majority of eligible member projects to be used improperly,
+   the offending point-of-contact shall be removed.
+4. Eligible member projects during such review periods are those who have opted not to recuse themselves.
+
+## 4. Amending this document
+
+1. An amendment to this document may be proposed by any member project by
+   submitting a merge request on Gitlab.
+2. A 30 day discussion period for comments from wayland-protocols members will
+   be held.
+3. At the conclusion of the discussion period, an amendment will become
+   effective if it's ACKed by at least 2/3rds of all wayland-protocols member
+   projects, and NACKed by none. The sponsoring member may merge their change
+   to the wayland-protocols repository at this point.

MEMBERS.md

@@ -0,0 +1,21 @@
+# wayland-protocols members
+
+- GTK/Mutter: Jonas Ådahl <jadahl@gmail.com> (@jadahl),
+  Carlos Garnacho <carlosg@gnome.org> (@carlosg)
+- KWin: Vlad Zahorodnii <vlad.zahorodnii@kde.org> (@zzag),
+  David Edmundson <david@davidedmundson.co.uk> (@davidedmundson),
+  Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)
+- mesa: Daniel Stone <daniel@fooishbar.org> (@daniels),
+  Mike Blumenkrantz <michael.blumenkrantz@gmail.com> (@zmike)
+- Mir: Christopher James Halse Rogers <raof@ubuntu.com> (@RAOF),
+  Alan Griffiths <alan.griffiths@canonical.com>
+- Qt: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>
+  (@eskilblomfeldt)
+- Smithay/Cosmic: Victoria Brekenfeld <wayland@drakulix.de> (@drakulix)
+- Weston: Pekka Paalanen <pekka.paalanen@collabora.com> (@pq),
+  Derek Foreman <derek.foreman@collabora.com> (@derekf)
+- wlroots/Sway: Simon Ser <contact@emersion.fr> (@emersion),
+  Simon Zeni <simon@bl4ckb0ne.ca> (@bl4ckb0ne)
+- Chromium: Fangzhou Ge <fangzhoug@chromium.org> (@fangzhoug),
+  Nick Yamane <nickdiego@igalia.com> (@nickdiego),
+  Max Ihlenfeldt <max@igalia.com> (@mihlenfeldt)

Makefile.am

@@ -1,18 +0,0 @@
-unstable_protocols =								\
-	unstable/pointer-gestures/pointer-gestures-unstable-v1.xml		\
-	unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml		\
-	unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml			\
-	unstable/text-input/text-input-unstable-v1.xml				\
-	unstable/input-method/input-method-unstable-v1.xml			\
-	unstable/xdg-shell/xdg-shell-unstable-v5.xml				\
-	$(NULL)
-
-nobase_dist_pkgdata_DATA =							\
-	$(unstable_protocols)							\
-	$(NULL)
-
-dist_noinst_DATA =								\
-	$(sort $(foreach p,$(unstable_protocols),$(dir $p)README))		\
-	$(NULL)
-
-noarch_pkgconfig_DATA = wayland-protocols.pc

README

@@ -1,141 +0,0 @@
-Wayland protocols
------------------
-
-wayland-protocols contains Wayland protocols that adds functionality not
-available in the Wayland core protocol. Such protocols either adds
-completely new functionality, or extends the functionality of some other
-protocol either in Wayland core, or some other protocol in
-wayland-protocols.
-
-A protocol in wayland-protocols consists of a directory containing a set
-of XML files containing the protocol specification, and a README file
-containing detailed state and a list of maintainers.
-
-Protocol directory tree structure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Protocols may be 'stable', 'unstable' or 'deprecated', and the interface
-and protocol names as well as place in the directory tree will reflect
-this.
-
-A stable protocol is a protocol which has been declared stable by
-the maintainers. Changes to such protocols will always be backward
-compatible.
-
-An unstable protocol is a protocol currently under development and this
-will be reflected in the protocol and interface names. See <<Unstable
-naming convention>>.
-
-A deprecated protocol is a protocol that has either been replaced by some
-other protocol, or declared undesirable for some other reason. No more
-changes will be made to a deprecated protocol.
-
-Depending on which of the above state the protocol is in, the protocol
-is placed within the toplevel directory containing the protocols with the
-same state. Stable protocols are placed in the +stable/+ directory,
-unstable protocols are placed in the +unstable/+ directory, and
-deprecated protocols are placed in the +deprecated/+ directory.
-
-Protocol development procedure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To propose a new protocol, create a patch adding the relevant files and
-Makefile.am entry to the wayland-protocols git repository with the
-explanation and motivation in the commit message. Then send the patch to
-the wayland-devel@lists.freedesktop.org mailing list using
-'git send-email' with the subject prefix 'RFC wayland-protocols' or
-'PATCH wayland-protocols' depending on what state the protocol is in.
-
-To propose changes to existing protocols, create a patch with the
-changes and send it to the list mentioned above while also CC:ing the
-maintainers mentioned in the README file. Use the same rule for adding a
-subject prefix as above and method for sending the patch.
-
-If the changes are backward incompatible changes to an unstable protocol,
-see <<Unstable protocol changes>>.
-
-Interface naming convention
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All protocols should avoid using generic namespaces or no namespaces in
-the protocol interface names in order to minimize risk that the generated
-C API collides with other C API. Interface names that may collide with
-interface names from other protocols should also be avoided.
-
-For generic protocols not limited to certain configurations (such as
-specific desktop environment or operating system) the +wp_+ prefix
-should be used on all interfaces in the protocol.
-
-For operating system specific protocols, the interfaces should be
-prefixed with both +wp_+ and the operating system, for example
-+wp_linux_+, or +wp_freebsd_+, etc.
-
-Unstable naming convention
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-Unstable protocols have a special naming convention in order to make it
-possible to make discoverable backward incompatible changes.
-
-An unstable protocol has at least two versions; the major version which
-represents backward incompatible changes, and the minor versions which
-represents backward compatible changes to the interfaces in the protocol.
-
-The major version is part of the XML file name, the protocol name in the
-XML, and interface names in the protocol.
-
-Minor versions are the version attributes of the interfaces in the XML.
-There may be more than one minor version per protocol, if there are more
-than one global.
-
-The XML file and protocol name also has the word 'unstable' in them, and
-all of the interfaces in the protocol are prefixed with +z+ and
-suffixed with the major version number.
-
-For example, an unstable protocol called foo-bar with major version 2
-containing the two interfaces wp_foo and wp_bar both minor version 1 will
-be placed in the directory +unstable/foo-bar/+ consisting of one file
-called +README+ and one called +foo-bar-unstable-v2.xml+. The XML file
-will consist of two interfaces called +zwp_foo_v2+ and +zwp_bar_v2+ with
-the +version+ attribute set to +1+.
-
-Unstable protocol changes
-~~~~~~~~~~~~~~~~~~~~~~~~~
-During the development of a new protocol it is possible that backward
-incompatible changes are needed. Such a change needs to be represented
-in the major and minor versions of the protocol.
-
-Assuming a backward incompatible change is needed, the procedure how to
-do so is the following:
-
-  . Make a copy of the XML file with the major version increased by +1+.
-  . Increase the major version number in the protocol XML by +1+.
-  . Increase the major version number in all of the interfaces in the
-    XML by +1+.
-  . Reset the minor version number (interface version attribute) of all
-    the interfaces to +1+.
-
-Backward compatible changes within a major unstable version can be done
-in the regular way as done in core Wayland or in stable protocols.
-
-Declaring a protocol stable
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once it is decided that a protocol should be declared stable, meaning no
-more backward incompatible changes will ever be allowed, one last
-breakage is needed.
-
-The procedure of doing this is the following:
-
-  . Create a new directory in the +stable/+ toplevel directory with the
-    same name as the protocol directory in the +unstable/+ directory.
-  . Copy the final version of the XML that is the version that was
-    decided to be declared stable into the new directory. The target name
-    should be the same name as the protocol directory but with the +.xml+
-    suffix.
-  . Rename the name of the protocol in the XML by removing the
-    'unstable' part and the major version number.
-  . Remove the +z+ prefix and the major version number suffix from all
-    of the interfaces in the protocol.
-  . Reset all of the interface version attributes to +1+.
-  . Update the +README+ file in the unstable directory and create a new
-    +README+ file in the new directory.
-
-Releases
-~~~~~~~~
-Each release of wayland-protocols finalizes the version of the protocols
-to their state they had at that time.

README.md

@@ -0,0 +1,304 @@
+# Wayland protocols
+
+wayland-protocols contains Wayland protocols that add functionality not
+available in the Wayland core protocol. Such protocols either add
+completely new functionality, or extend the functionality of some other
+protocol either in Wayland core, or some other protocol in
+wayland-protocols.
+
+A protocol in wayland-protocols consists of a directory containing a set
+of XML files containing the protocol specification, and a README file
+containing detailed state and a list of maintainers.
+
+wayland-protocols is a standardization body formed of various Wayland
+compositor and client developers. The governance rules are described in
+[GOVERNANCE.md] and the current members are listed in [MEMBERS.md].
+
+## Protocol phases
+
+Protocols have three currently used phases: the experimental phase, the staging
+phase, and the stable phase. Anything that is merged upstream is in one of
+those phases, with the exception of deprecated protocols and protocols in
+the legacy protocol phases.
+
+Backward-incompatible changes can only be introduced in a new major version of
+a protocol. In the experimental phase, a protocol is actively being
+developed and iterated upon, not trying to avoid incompatible changes.
+Protocols in the staging phase should try to minimize backward-incompatible
+changes, and protocols in the stable phase should avoid backward-incompatible
+changes.
+
+Anything that is not merged upstream can be iterated and broken freely, but
+care should be taken to ensure that there are no two protocols with the same
+name and version but a different API.
+
+During the experimental phase, patches for clients and compositors are written
+as a test vehicle. Such patches should be merged with caution in clients and
+compositors, because the protocol can still change.
+
+When a protocol has reached a stage where it is ready for wider adoption,
+it enters the "staging" phase. What this means is that implementation is
+encouraged in clients and compositors where the functionality it specifies is
+wanted.
+
+After a staging protocol has been sufficiently tested in the wild and
+proven adequate, its maintainers and the community at large may declare it
+"stable", meaning it is unexpected to become superseded by a new major
+version.
+
+## Deprecation
+
+A protocol may be deprecated, if it has been replaced by some other
+protocol, or declared undesirable for some other reason. No more changes
+will be made to a deprecated protocol.
+
+## Legacy protocol phases
+
+An "unstable" protocol refers to a protocol categorization policy
+previously used by wayland-protocols, where certain naming conventions were
+applied, requiring a backward incompatible change to be declared "stable".
+
+During this phase, protocol interface names were, in addition to
+the major version postfix, also prefixed with `z` to distinguish them from
+stable protocols.
+
+## Protocol directory tree structure
+
+Depending on which stage a protocol is in, the protocol is placed within
+the toplevel directory containing the protocols with the same stage.
+Stable protocols are placed in the `stable/` directory, staging protocols
+are placed in the `staging/` directory, experimental protocols are placed
+in the `experimental/` directory, and deprecated protocols are placed in
+the `deprecated/` directory.
+
+Unstable protocols (see [Legacy protocol phases]) can be found in the
+`unstable/` directory, but new ones should never be placed here.
+
+## Protocol development procedure
+
+To propose a new protocol, create a GitLab merge request adding the
+relevant files and `meson.build` entry to the repository with the
+explanation and motivation in the commit message. Protocols are
+organized in namespaces describing their scope ("wp", "xdg" and "ext").
+There are different requirements for each namespace, see [GOVERNANCE
+section 2] for more information.
+
+If the new protocol is just an idea, open an issue on the GitLab issue
+tracker. If the protocol isn't ready for complete review yet and is an
+RFC, create a merge request and add the "Draft:" prefix in the title.
+
+To propose changes to existing protocols, create a GitLab merge request.
+Please make sure you CC the authors and maintainers of the protocol, who
+are named in the protocol's README.
+
+Please include a `Signed-off-by` line at the end of the commit to certify
+that you wrote it or otherwise have the right to pass it on as an
+open-source patch. See the [Developer Certificate of Origin] for a formal
+definition.
+
+## Protocol development recommendations
+
+It is recommended that protocols be small and specific in scope in order to
+minimize sites of friction.
+
+Development discussion should be approached with a fresh, productive mindset
+and an openness to explore contrary ideas.
+
+Development discussions must remain civil and technical in nature at all times.
+
+## Interface naming convention
+
+All protocols should avoid using generic namespaces or no namespaces in
+the protocol interface names in order to minimize risk that the generated
+C API collides with other C API. Interface names that may collide with
+interface names from other protocols should also be avoided.
+
+For generic protocols not limited to certain configurations (such as
+specific desktop environment or operating system) the `wp_` prefix
+should be used on all interfaces in the protocol.
+
+For protocols allowing clients to configure how their windows are
+managed, the `xdg_` prefix should be used.
+
+For operating system specific protocols, the interfaces should be
+prefixed with both `wp_` and the operating system, for example
+`wp_linux_`, or `wp_freebsd_`, etc.
+
+For more information about namespaces, see [GOVERNANCE section 2.1].
+
+Each new non-experimental protocol XML file must include a major version
+postfix, starting with `-v1`. The purpose of this postfix is to make it
+possible to distinguish between backward incompatible major versions of
+the same protocol.
+
+The interfaces in the protocol XML file should as well have the same
+major version postfix in their names.
+
+For example, the protocol `foo-bar` may have a XML file
+`foo-bar/foo-bar-v1.xml`, consisting of the interface `wp_foo_bar_v1`,
+corresponding to the major version 1, as well as the newer version
+`foo-bar/foo-bar-v2.xml` consisting of the interface `wp_foo_bar_v2`,
+corresponding to the major version 2.
+
+## Use of RFC 2119 keywords
+
+Descriptions of all new protocols must use (in lowercase) and adhere to the
+proper meaning of the keywords described in [RFC 2119].
+
+All protocol descriptions that follow the guidelines in RFC 2119 must
+incorporate the following text in their toplevel protocol description section:
+
+```
+The key words "must", "must not", "required", "shall", "shall not", "should",
+"should not", "recommended",  "may", and "optional" in this document are to
+be interpreted as described in IETF RFC 2119.
+```
+
+Note that not all existing protocol descriptions conform to RFC 2119. Protocol
+maintainers are encouraged to audit their descriptions, update them as needed
+to follow RFC 2119 guidelines, and mark them as conformant in the way described
+in the previous paragraph.
+
+## Backward compatible protocol changes
+
+A protocol may receive backward compatible additions and changes. This
+is to be done in the general Wayland way, using `version` and `since` XML
+element attributes.
+
+## Backward incompatible protocol changes
+
+Protocols shall try to avoid backwards incompatible protocol changes during
+the staging and stable phases.
+
+Assuming a backward incompatible change is needed, the procedure for how to
+do so is the following:
+
+- Make a copy of the XML file with the major version increased by 1.
+- Increase the major version number in the protocol XML by 1.
+- Increase the major version number in all of the interfaces in the
+  XML by 1.
+- Reset the interface version number (interface version attribute) of all
+  the interfaces to 1.
+- Remove all of the `since` attributes.
+
+## The experimental phase
+
+Implementations choosing to support experimental protocols must work to
+support the latest version of the protocol at all times. It is therefore
+recommended that developers only opt-in to supporting protocols they
+have time and resources to actively develop.
+
+A runtime option to enable features may also be useful to ensure users
+do not opt-in to potentially broken behavior.
+
+There is no expectation or requirement to avoid backwards incompatible changes
+in this phase. It is therefore strongly advised that such consumer projects add
+build-time compile options to enable such protocols in order to avoid compile
+errors from protocol version mismatches.
+
+## The staging phase
+
+Protocols can enter the wayland-protocols repository in this stage, without
+traversing the experimental phase. The author of an experimental protocol can
+request that it be promoted at any point.
+
+In both cases, the protocol must meet the requirements of
+[GOVERNANCE section 2.3] for the staging phase.
+
+Protocols in the staging phase must carry the following disclaimer:
+
+```
+Warning! The protocol described in this file is currently in the staging
+phase. Backward compatible changes may be added together with the
+corresponding interface version bump. Backward incompatible changes can
+only be done by creating a new major version of the protocol.
+```
+
+When a protocol gets promoted from the experimental phase, the namespace prefix
+should be determined, and then the protocol should be renamed and merged into
+the appropriate directory, deleting the `experimental/` entry.
+
+## The stable phase
+
+Once it has been concluded that a protocol been proven adequate in
+production, and that it is deemed unlikely to receive any backward
+incompatible changes, it may be declared stable.
+
+There are other requirements for declaring a protocol stable, see
+[GOVERNANCE section 2.3].
+
+Note that the major version of the stable protocol, as well as all the
+interface versions and names, must remain unchanged.
+
+The procedure of promoting a protocol to the stable phase is the following:
+
+- Create a new directory in the `stable/` toplevel directory with the
+  same name as the protocol directory in the `staging/` directory.
+- Copy the final version of the XML that is the version that was
+  decided to be declared stable into the new directory. The target name
+  should be the same name as the protocol directory plus the version and
+  the `.xml` suffix.
+- Remove the disclaimer about the protocol being in the staging phase.
+- Update the `README` file in the staging directory and create a new
+  `README` file in the new directory.
+- Replace the disclaimer in the protocol files left in the staging/
+  directory with the following:
+
+```
+Disclaimer: This protocol has been marked stable. This copy is
+no longer used and only retained for backwards compatibility. The
+canonical version can be found in the stable/ directory.
+```
+
+## Releases
+
+Each release of wayland-protocols finalizes the version of the protocols
+to their state they had at that time.
+
+## Gitlab conventions
+
+### Triaging merge requests
+
+New merge requests should be triaged. Doing so requires the one doing the
+triage to add a set of initial labels:
+
+~"New Protocol" - For a new protocol being added. If it's an amendment to
+an existing protocol, apply the label of the corresponding protocol
+instead. If none exist, create it.
+
+~"Needs acks" - If the protocol needs one or more acknowledgements.
+
+~"Needs implementations" - If there are not enough implementations of the
+protocol.
+
+~"Needs review" - If the protocol is in need of review.
+
+~"In 30 day discussion period" - If the protocol needs a 30 day discussion
+period.
+
+For the meaning and requirement of acknowledgments and available
+implementations, see the [GOVERNANCE.md] document.
+
+### Managing merge requests
+
+When merge requests get their needed feedback and items, remove the
+corresponding label that marks it as needing something. For example, if a
+merge request receives all the required acknowledgments, remove the
+~"Needs acks" label, or if 30 days passed since opening, remove any
+~"In 30 day discussion period" label.
+
+### Nacking a merge request
+
+If the inclusion of a merge request is denied due to one or more Nacks, add
+the ~Nacked label.
+
+[GOVERNANCE.md]: GOVERNANCE.md
+[MEMBERS.md]: MEMBERS.md
+[merge request]: https://gitlab.freedesktop.org/wayland/wayland-protocols/merge_requests
+[issue]: https://gitlab.freedesktop.org/wayland/wayland-protocols/issues
+[GOVERNANCE section 2.3]: GOVERNANCE.md#2.3-introducing-new-protocols
+[Legacy protocol phases]: #legacy-protocol-phases
+[GOVERNANCE section 2]: GOVERNANCE.md#2-protocols
+[Developer Certificate of Origin]: https://developercertificate.org/
+[GOVERNANCE section 2.1]: GOVERNANCE.md#21-protocol-namespaces
+[RFC 2119]: https://www.rfc-editor.org/info/rfc2119

autogen.sh

@@ -1,9 +0,0 @@
-#!/bin/sh
-
-test -n "$srcdir" || srcdir=`dirname "$0"`
-test -n "$srcdir" || srcdir=.
-(
-  cd "$srcdir" &&
-  autoreconf --force -v --install
-) || exit
-test -n "$NOCONFIGURE" || "$srcdir/configure" "$@"

configure.ac

@@ -1,31 +0,0 @@
-AC_PREREQ([2.64])
-
-m4_define([wayland_protocols_major_version], [1])
-m4_define([wayland_protocols_minor_version], [0])
-m4_define([wayland_protocols_version],
-          [wayland_protocols_major_version.wayland_protocols_minor_version])
-
-AC_INIT([wayland-protocols],
-        [wayland_protocols_version],
-        [https://bugs.freedesktop.org/enter_bug.cgi?product=Wayland&component=wayland&version=unspecified],
-        [wayland-protocols],
-        [http://wayland.freedesktop.org/])
-
-AC_SUBST([WAYLAND_PROTOCOLS_VERSION], [wayland_protocols_version])
-
-AM_INIT_AUTOMAKE([1.11 foreign no-dist-gzip dist-xz])
-
-AM_SILENT_RULES([yes])
-
-PKG_NOARCH_INSTALLDIR
-
-AC_CONFIG_FILES([
-	Makefile
-	wayland-protocols.pc
-	])
-AC_OUTPUT
-
-AC_MSG_RESULT([
-	Version			${WAYLAND_PROTOCOLS_VERSION}
-	Prefix			${prefix}
-	])

experimental/xx-cutouts/README

@@ -0,0 +1,4 @@
+xx cutouts protocol
+
+Maintainers:
+Guido Günther <agx@sigxcpu.org>

experimental/xx-cutouts/xx-cutouts-v1.xml

@@ -0,0 +1,232 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xx_cutouts_unstable_v1">
+
+  <copyright>
+    Copyright © 2026 Phosh.mobi e.V.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+
+    Warning! The protocol described in this file is currently in the
+    experimental phase. Backwards incompatible major versions of the protocol
+    are to be expected. Exposing this protocol without an opt-in mechanism is
+    discouraged.
+  </copyright>
+
+  <description summary="Protocol to describe cut out surface regions">
+    This protocol describes the areas of a toplevel that are cut out
+    of the available surface area by hardware elements present in the
+    physical display. This allows clients to avoid placing user interface
+    elements in those areas.
+
+    Typical cutout areas are notches (i.e. embedding a camera) or
+    "waterfall" display edges. In the case of a notch the compositor
+    would usually supply the bounding box of the notch or an
+    approximation by multiple rectangles. Thus a single physical
+    element in the display can correspond to multiple cutout events in
+    the protocol.
+
+    The protocol currently supports xdg_toplevel surfaces but is meant
+    to be extended to other surfaces (like layer surfaces) in the
+    future.
+
+    Warning! The protocol described in this file is experimental and
+    backward incompatible changes may be made. Backward compatible
+    changes may be added together with the corresponding interface
+    version bump. Backward incompatible changes can only be done by
+    creating a new major version of the extension.
+  </description>
+
+  <interface name="xx_cutouts_manager_v1" version="1">
+    <description summary="Display cutouts area manager">
+      This interface allows a compositor to announce support for
+      supplying cutout information to the client.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_role" value="0" summary="given wl_surface has incorrect role"/>
+      <entry name="defunct_cutouts_object" value="1"
+             summary="wl_surface or surface role was destroyed before the cutouts object"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the xx_cutouts_manager object">
+        Using this request a client can tell the server that it is not
+        going to use the xx_cutouts_manger object anymore.
+
+        Any objects already created through this instance are not affected.
+      </description>
+    </request>
+
+    <request name="get_cutouts">
+      <description summary="create a cutout notifier from a xdg toplevel">
+        This creates a new xx_cutouts object for the given
+        surface. The role of the surface must be xdg_toplevel
+        otherwise an invalid_role protocol error will be raised. Later
+        versions of this protocol might allow for other surface roles.
+      </description>
+      <arg name="id" type="new_id" interface="xx_cutouts_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+
+  </interface>
+
+  <interface name="xx_cutouts_v1" version="1">
+    <description summary="cutout regions information">
+      An xx_cutouts describes the areas currently "cut out" of a
+      toplevel.
+
+      Each cutout event carries an id that identifies the
+      physical element. If the compositor describes an element by
+      multiple cutout events these should use the same element
+      id. A typical example is a curved notch that is approximated
+      by several cutout_box elements. Using the same element
+      id allows the client to identify that these belong to the
+      same physical object. Ids are only valid during one configure
+      sequence. No guarantee is given that the same id identifies
+      the same element in different configure sequences.
+
+      Typically compositors would only send cutout information when
+      the toplevel enters fullscreen or maxmized state (as specified
+      in the xdg_shell protocol).
+
+      The xx_cutouts_v1 object must be destroyed before its
+      underlying xdg_toplevel and wl_surface. Otherwise the
+      defunct_cutouts_object protocol error will be send.
+    </description>
+
+    <enum name="type">
+      <description summary="Cutout type">
+        These values indicate the type of cutout. The information is
+        meant to help clients to decide whether they can possibly
+        ignore the element.
+      </description>
+
+      <entry name="cutout" value="0">
+        <description summary="A generic cutout">
+          This element type can be used by the compositor if it
+          doesn't want to provide a more specific type.
+        </description>
+      </entry>
+      <entry name="notch" value="1">
+        <description summary="Small functional cutout area">
+          A functional, irregular shape on one of the device's
+          edges. It often contains a camera.
+        </description>
+      </entry>
+      <entry name="waterfall" value="2">
+        <description summary="A curved display edge">
+          A curved display edge intended to make the device appear
+          like not having any bezel.
+        </description>
+      </entry>
+    </enum>
+
+    <enum name="corner_position">
+      <description summary="Corner position">
+        The position of a corner on a surface
+      </description>
+
+      <entry name="top_left" value="0"/>
+      <entry name="top_right" value="1"/>
+      <entry name="bottom_right" value="2"/>
+      <entry name="bottom_left" value="3"/>
+    </enum>
+
+    <enum name="error">
+      <entry name="invalid_element_id" value="0"
+             summary="Invalid element id in a set_unhandled request"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the xx_cutouts object">
+        Using this request a client can tell the server that it is not
+        going to use the xx_cutouts object anymore.
+      </description>
+    </request>
+
+    <event name="cutout_box">
+      <description summary="A rectangular cutout region">
+        The cutout_box event describes a rectangular cutout area in
+        surface-local coordinates.
+
+        This can be an approximation of e.g. a circular camera notch.
+      </description>
+      <arg name="x" type="int"
+           summary="x coordinate of the box's top left corner"/>
+      <arg name="y" type="int"
+           summary="y coordinate of the box's top left corner"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+      <arg name="type" type="uint" enum="type" summary="The type of cutout"/>
+      <arg name="id" type="uint" summary="An identifier identifying the physical element"/>
+    </event>
+
+    <event name="cutout_corner">
+      <description summary="A cutout corner">
+        The cutout_corner event describes a rounded corner in
+        surface-local coordinates. The area towards the screen edge is
+        the cutout corner part.
+      </description>
+      <arg name="position" type="uint" enum="corner_position" summary="The position of the described corner"/>
+      <arg name="radius" type="uint" summary="The corner's radius"/>
+      <arg name="id" type="uint" summary="An identifier identifying the physical element"/>
+    </event>
+
+    <event name="configure">
+      <description summary="notify cutout changes">
+        The configure event marks the end of a configure sequence. A
+        configure sequence is a set of zero or more cutout events and
+        the final xx_cutout.configure event.
+
+        In the case of a xdg_toplevel clients should arrange their
+        surface for the new cutouts, and then send an
+        xdg_surface.ack_configure request at some point before
+        committing the new surface. See xdg_surface.configure and
+        xdg_surface.ack_configure in the xdg_shell protocol for
+        details.
+
+        If the cutout sequence consists of only a configure event and
+        contains no cutout or corner events this indicates that the
+        surface isn't overlapping with any cutouts or corners.
+
+        If the client receives multiple configure events before it can
+        respond to one, it is free to discard all but the last event
+        it received.
+      </description>
+    </event>
+
+    <request name="set_unhandled">
+      <description summary="Notify about unhandled cutouts">
+        If a client doesn't handle one or more cutouts in the to be
+        acked sequence, it can add their element's id to the
+        unhandled array. The compositor might then try to reposition
+        the surface in a way that avoids these elements in a future
+        configure sequence.
+
+        The request (if used) must be sent before acking the configure
+        sequence. State set with this request is double-buffered. It
+        will get applied on the next ack_configure and stay valid
+        until the next configure event.
+      </description>
+      <arg name="unhandled" type="array" summary="array of unhandled element ids"/>
+    </request>
+
+  </interface>
+</protocol>

experimental/xx-fractional-scale/README

@@ -0,0 +1,4 @@
+xx fractional scale v2 protocol
+
+Maintainers:
+Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)

experimental/xx-fractional-scale/xx-fractional-scale-v2.xml

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xx_fractional_scale_v2">
+  <copyright>
+    Copyright © 2022 Xaver Hugl
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for fractional scaling">
+    This protocol allows compositors and clients to communicate the
+    coordinate space their surfaces act in.
+  </description>
+
+  <interface name="xx_fractional_scale_manager_v2" version="1">
+    <description summary="creates surface scale interfaces">
+      A global interface to create xx_fractional_scale_v2 interfaces.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="release the global">
+        Informs the server that the client will not be using this protocol
+        object anymore. This does not affect any other objects.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="fractional_scale_exists" value="0"
+        summary="xx_fractional_scale_v2 for the surface already exists"/>
+    </enum>
+
+    <request name="get_fractional_scale">
+      <description summary="create an interface to enable fractional scaling">
+        Create an interface object for a wl_surface to communicate scale.
+        If the given wl_surface already has a xx_fractional_scale_v2 object
+        associated, the fractional_scale_exists protocol error is raised.
+      </description>
+      <arg name="id" type="new_id" interface="xx_fractional_scale_v2"
+           summary="the new scale interface"/>
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="the surface"/>
+    </request>
+  </interface>
+
+  <interface name="xx_fractional_scale_v2" version="1">
+    <description summary="interface for fractional scaling">
+      An additional interface for a wl_surface object that allows compositor and
+      client to communicate in a different coordinate space, in order to enable
+      them to accurately describe coordinates and sizes in pixels.
+      The two coordinate spaces in consideration are logical and pixels, where
+      logical coordinates describe the size content should have and pixels
+      describe the size of buffers.
+
+      A scale of one equals a lack of scaling, where the communicated values
+      define both logical coordinates and pixels.
+      A scale greater than one describes that for every logical coordinate,
+      more than one pixel is used, and a scale less than one describes that
+      multiple logical coordinates make up one pixel.
+      In mathematical terms, logical coordinates can be obtained by dividing
+      the provided values by the currently active scale.
+
+      The initial compositor and client coordinate scale factors are 1.
+    </description>
+
+    <event name="scale_factor">
+      <description summary="set the compositor coordinate space scale factor">
+        This event sets a scale factor for the associated wl_surface that
+        describes the coordinate system the compositor will use for events
+        following xx_fractional_scale_v2.scale_factor.
+
+        The scale factor is encoded in a 8.24 fixed point format.
+
+        The compositor must not send a scale of zero.
+
+        The client should re-render and commit a new buffer with the new scale
+        as soon as possible, in order to avoid artifacts caused by the mismatch
+        in compositor and client scales.
+      </description>
+      <arg name="scale_8_24" type="uint" summary="surface scale factor"/>
+    </event>
+
+    <request name="set_scale_factor">
+      <description summary="set the client coordinate space scale factor">
+        This request sets a scale factor for the associated wl_surface that
+        describes the coordinate system the client uses for requests following
+        xx_fractional_scale_v2.set_scale_factor.
+
+        The scale factor is encoded in a 8.24 fixed point format.
+
+        If this scale factor does not match the scale factor provided by the
+        compositor with xx_fractional_scale_v2.scale_factor, the compositor may
+        apply transformations to the wl_surface that can result in blurriness
+        or other artifacts.
+
+        If scale_8_24 is zero, the error invalid_scale will be raised.
+      </description>
+      <arg name="scale_8_24" type="uint" summary="surface scale factor"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="remove the scale interface from the surface">
+        The wl_surface's xx_fractional_scale_v2 object is destroyed, and the
+        associated scale is reset to 1.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="invalid_scale" value="0"
+        summary="scale value is not valid"/>
+    </enum>
+  </interface>
+</protocol>

experimental/xx-input-method/README

@@ -0,0 +1,4 @@
+Input method protocol
+
+Maintainers:
+Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>

experimental/xx-input-method/xx-input-method-v2.xml

@@ -0,0 +1,948 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="input_method_experimental_v2">
+
+  <copyright>
+    Copyright © 2008-2011 Kristian Høgsberg
+    Copyright © 2010-2011 Intel Corporation
+    Copyright © 2012-2013 Collabora, Ltd.
+    Copyright © 2012, 2013 Intel Corporation
+    Copyright © 2015, 2016 Jan Arne Petersen
+    Copyright © 2017, 2018 Red Hat, Inc.
+    Copyright © 2018       Purism SPC
+    Copyright © 2025       DorotaC
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for creating input methods">
+    This protocol allows applications to act as input methods for compositors.
+
+    An input method context is used to manage the state of the input method.
+
+    Text strings are UTF-8 encoded, their indices and lengths are in bytes.
+
+    This document adheres to the RFC 2119 when using words like "must",
+    "should", "may", etc.
+
+    Warning! The protocol described in this file is currently in the
+    experimental phase. Backwards incompatible major versions of the
+    protocol are to be expected. Exposing this protocol without an opt-in
+    mechanism is discouraged.
+  </description>
+
+  <interface name="xx_input_method_v1" version="4">
+    <description summary="input method">
+      An input method object allows for clients to compose text.
+
+      The objects connects the client to a text input in an application, and
+      lets the client to serve as an input method for a seat.
+
+      The xx_input_method_v1 object can occupy two distinct states: active and
+      inactive. In the active state, the object is associated to and
+      communicates with a text input. In the inactive state, there is no
+      associated text input, and the only communication is with the compositor.
+      Initially, the input method is in the inactive state.
+
+      Requests issued in the inactive state must be accepted by the compositor.
+      Because of the serial mechanism, and the state reset on activate event,
+      they will not have any effect on the state of the next text input.
+
+      There must be no more than one input method object per seat.
+    </description>
+
+    <enum name="error">
+      <entry name="surface_has_role" value="0x0" summary="surface already has a role"/>
+      <entry name="inactive" value="0x1" summary="operation requires the input method to be active"/>
+    </enum>
+
+    <event name="activate">
+      <description summary="input method has been requested">
+        Notification that a text input focused on this seat requested the input
+        method to be activated.
+
+        This event serves the purpose of providing the compositor with an
+        active input method.
+
+        This event resets all state associated with previous
+        surrounding_text, text_change_cause, and content_type events, as well
+        as the state associated with set_preedit_string, commit_string, and
+        delete_surrounding_text requests, and destroys any existing input_popup_surface objects.
+        In addition, it marks the xx_input_method_v1 object as active.
+
+        The surrounding_text, and content_type events must follow before the
+        next done event if the text input supports the respective
+        functionality.
+
+        State set with this event is double-buffered. It will get applied on
+        the next xx_input_method_v1.done event, and stay valid until changed.
+      </description>
+    </event>
+
+    <event name="deactivate">
+      <description summary="deactivate event">
+        Notification that no focused text input currently needs an active 
+        input method on this seat.
+
+        This event marks the xx_input_method_v1 object as inactive.
+        compositor must destroy all existing xx_input_popup_surface_v2 objects.
+
+        This event resets all state associated with previous
+        surrounding_text, text_change_cause, and content_type events, as well
+        as the state associated with set_preedit_string, commit_string, and
+        delete_surrounding_text requests.
+
+        State set with this event is double-buffered. It will get applied on
+        the next xx_input_method_v1.done event, and stay valid until changed.
+      </description>
+    </event>
+
+    <event name="surrounding_text">
+      <description summary="surrounding text event">
+        Updates the surrounding plain text around the cursor, excluding the
+        preedit text.
+
+        If any preedit text is present, it is replaced with the cursor for the
+        purpose of this event.
+
+        The argument text is a buffer containing the preedit string, and must
+        include the cursor position, and the complete selection. It should
+        contain additional characters before and after these. There is a
+        maximum length of wayland messages, so text can not be longer than 4000
+        bytes.
+
+        cursor is the byte offset of the cursor within the text buffer.
+
+        anchor is the byte offset of the selection anchor within the text
+        buffer. If there is no selected text, anchor must be the same as
+        cursor.
+
+        If this event does not arrive before the first done event, the input
+        method may assume that the text input does not support this
+        functionality and ignore following surrounding_text events.
+
+        Values set with this event are double-buffered. They will get applied
+        and set to initial values on the next xx_input_method_v1.done
+        event.
+
+        The initial state for affected fields is empty, meaning that the text
+        input does not support sending surrounding text. If the empty values
+        get applied, subsequent attempts to change them may have no effect.
+      </description>
+      <arg name="text" type="string"/>
+      <arg name="cursor" type="uint"/>
+      <arg name="anchor" type="uint"/>
+    </event>
+
+    <event name="text_change_cause">
+      <description summary="indicates the cause of surrounding text change">
+        Tells the input method why the text surrounding the cursor changed.
+
+        Whenever the client detects an external change in text, cursor, or
+        anchor position, it must issue this request to the compositor. This
+        request is intended to give the input method a chance to update the
+        preedit text in an appropriate way, e.g. by removing it when the user
+        starts typing with a keyboard.
+
+        cause describes the source of the change.
+
+        The value set with this event is double-buffered. It will get applied
+        and set to its initial value on the next xx_input_method_v1.done
+        event.
+
+        The initial value of cause is input_method.
+      </description>
+      <arg name="cause" type="uint" enum="xx_text_input_v3.change_cause"/>
+    </event>
+
+    <event name="content_type">
+      <description summary="content purpose and hint">
+        Indicates the content type and hint for the current
+        xx_input_method_v1 instance.
+
+        Values set with this event are double-buffered. They will get applied
+        on the next xx_input_method_v1.done event.
+        They get reset to initial on the next committed deactivate event.
+
+        The initial value for hint is none, and the initial value for purpose
+        is normal.
+      </description>
+      <arg name="hint" type="uint" enum="xx_text_input_v3.content_hint"/>
+      <arg name="purpose" type="uint" enum="xx_text_input_v3.content_purpose"/>
+    </event>
+    
+    <event name="set_available_actions" since="3">
+      <description summary="announce the available actions">
+        Announces the actions available for the currently active text input.
+
+        Values set with this event are double-buffered. They will get applied
+        on the next .done event.
+        They get reset to the initial value on the next committed deactivate event.
+
+        The initial value is an empty set: no actions are available.
+
+        Values in the available_actions array come from text-input-v3.action.
+      </description>
+      <arg name="available_actions" type="array" summary="available actions"/>
+    </event>
+
+    <event name="announce_supported_features" since="3">
+      <description summary="announce extra supported features">
+        Notifies the input method what the currently active text input client is able to do.
+
+        This event should come within the same .done sequence as .activate. Otherwise, the input method may ignore it.
+        
+        Values set with this event are double-buffered. They will get applied
+        on the next .done event.
+        They get reset to initial on the next committed deactivate event.
+
+        The initial value for features is none.
+      </description>
+      <arg name="features" type="uint" enum="xx_text_input_v3.supported_features"/>
+    </event>
+
+    <enum name="protocol_compat" since="4">
+      <description summary="protocol compatibility value">
+        Tells the input method client what kinds of events the text input client supports.
+      </description>
+      <entry name="text_input_v3" value="0x0" summary="zwp-text-input-v3 semantics"/>
+      <entry name="xx_text_input" value="0x1">
+        <description summary="xx-text-input semantics">
+          Changes the meaning of serial compared to v3.
+          The text input client now applies requested updates on a "best-effort" basis.
+        </description>
+      </entry>
+      <!-- This doesn't need disambiguating. Both protocols are pdated in lockstep, and the compositor should implement both protocols to the current version. By the experimental protocols contract, every version bump is breaking compatibility. -->
+    </enum>
+    
+    <event name="announce_protocol_compat" since="3">
+      <description summary="set text input's compatibility level">
+        Tells the input method client what kinds of events the text input client supports.
+
+        <!-- While text input protocols and input method protocols are updated in lockstep, nobody knows what versions of either will end up on a user's computer. Old input method with new apps? New input method with old apps?
+        To limit the scope for now, let's assume the user always keeps the input method up to date, and uses old apps. -->
+        
+        Values set with this event are double-buffered. They will get applied
+        on the next .done event.
+        They get reset to initial on the next committed deactivate event.
+        
+        The compositor may send this event as part of a .done chain that switches the active state from inactive to active. It must not send this event otherwise.
+
+        The initial value for version is text_input_v3.
+      </description>
+      <arg name="compat_level" type="uint" enum="protocol_compat"/>
+    </event>
+    
+    <event name="done">
+      <description summary="apply state">
+        Atomically applies state changes recently sent to the client.
+
+        The done event establishes and updates the state of the client, and
+        must be issued after any changes to apply them.
+
+        Text input state (content purpose, content hint, surrounding text, and
+        change cause) is conceptually double-buffered within an input method
+        context.
+
+        Events modify the pending state, as opposed to the current state in use
+        by the input method. A done event atomically applies all pending state,
+        replacing the current state. After done, the new pending state is as
+        documented for each related request.
+
+        Events must be applied in the order of arrival.
+
+        Neither current nor pending state are modified unless noted otherwise.
+      </description>
+    </event>
+
+    <request name="perform_action" since="3">
+      <description summary="perform action">
+        Perform an action on this text input.
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next commit request.
+
+        The initial value of action is none.
+      </description>
+      <arg name="action" type="uint" enum="xx_text_input_v3.action" summary="action to perform"/>
+    </request>
+
+    <request name="commit_string">
+      <description summary="commit string">
+        Send the commit string text for insertion to the application.
+
+        Inserts a string at current cursor position (see commit event
+        sequence). The string to commit could be either just a single character
+        after a key press or the result of some composing.
+
+        The argument text is a buffer containing the string to insert. There is
+        a maximum length of wayland messages, so text can not be longer than
+        4000 bytes.
+
+        Values set with this request are double-buffered. They must be applied
+        and reset to initial on the next .commit request.
+
+        The initial value of text is an empty string.
+      </description>
+      <arg name="text" type="string"/>
+    </request>
+
+    <request name="set_preedit_string">
+      <description summary="pre-edit string">
+        Send the pre-edit string text to the application text input.
+
+        Place a new composing text (pre-edit) at the current cursor position.
+        Any previously set composing text must be removed. Any previously
+        existing selected text must be removed. The cursor is moved to a new
+        position within the preedit string.
+
+        The argument text is a buffer containing the preedit string. There is
+        a maximum length of wayland messages, so text can not be longer than
+        4000 bytes.
+
+        The arguments cursor_begin and cursor_end are counted in bytes relative
+        to the beginning of the submitted string buffer. Cursor should be
+        hidden by the text input when both are equal to -1.
+
+        cursor_begin indicates the beginning of the cursor. cursor_end
+        indicates the end of the cursor. It may be equal or different than
+        cursor_begin.
+
+        Values set with this request are double-buffered. They must be applied on
+        the next xx_input_method_v1.commit request.
+        They must be reset to initial on the next committed .deactivate event.
+
+        The initial value of text is an empty string. The initial value of
+        cursor_begin, and cursor_end are both 0.
+      </description>
+      <arg name="text" type="string"/>
+      <arg name="cursor_begin" type="int"/>
+      <arg name="cursor_end" type="int"/>
+    </request>
+
+    <request name="delete_surrounding_text">
+      <description summary="delete text">
+        Remove the surrounding text.
+
+        before_length and after_length are the number of bytes before and after
+        the current cursor index (excluding the preedit text) to delete.
+
+        If text is selected, it must be deleted.
+        
+        If indices exceed the available text boundaries, they should be adjusted to fit in boundaries and deletion reattempted.
+        If indices do not lie on byte boundaries, then the text input client should delete at least that many bytes. In this case, the client decides the end point, but a character boundary same as when deleting using the keyboard is recommended.
+        
+        If any preedit text is present, it is replaced with the cursor for the
+        purpose of this event. In effect before_length is counted from the
+        beginning of preedit text, and after_length from its end (see commit
+        event sequence).
+
+        Values set with this request are double-buffered. They must be applied
+        and reset to initial on the next xx_input_method_v1.commit request.
+
+        The initial values of both before_length and after_length are 0.
+      </description>
+      <arg name="before_length" type="uint"/>
+      <arg name="after_length" type="uint"/>
+    </request>
+
+    <request name="move_cursor" since="3">
+      <description summary="move cursor and change selection">
+        Unselects text, moves the cursor and selects text.
+
+        This is equivalent to dragging the mouse over some text: it deselects whatever might be currently selected and selects a new range of text.
+        
+        The offsets used in arguments are in bytes relative to the current cursor position. Cursor is the new position of the cursor, and anchor is the opposite end of selection. If there's no selection, anchor should be equal to cursor.
+        
+        The offsets do not take preedit contents into account, nor is preedit changed in any way with this request.
+        
+        Both cursor and anchor must fall on code point boundaries, otherwise text input client may ignore the request. It is therefore not recommended for an input method to move any of them beyond the text received in surrounding_text.
+        
+        When surrounding_text is not supported, the offsets must not be interpreted as bytes, but as some human-readable unit at least as big as a code point, for example a grapheme.
+
+        The cursor and anchor arguments can also take the following special values:
+        BEGINNING := 0x8000_0000 = i32::MIN
+        END := 0x7fff_ffff = i32::MAX
+        meaning, respectively, the beginning and the end of of all text in the input field.
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next commit request.
+
+        The initial values of both cursor and anchor are 0.
+      </description>
+      <arg name="cursor" type="int"/>
+      <arg name="anchor" type="int"/>
+    </request>
+    
+    <request name="commit">
+      <description summary="apply state">
+        Apply state changes from commit_string, set_preedit_string and
+        delete_surrounding_text requests.
+
+        The state relating to these events is double-buffered, and each one
+        modifies the pending state. This request replaces the current state
+        with the pending state.
+
+        The connected text input is expected to proceed by evaluating the
+        changes in the following order:
+
+        1. Replace existing preedit string with the cursor.
+        2. Delete requested surrounding text.
+        3. Insert commit string with the cursor at its end.
+        4. Move the cursor and selection.
+        5. Calculate surrounding text to send.
+        6. Insert new preedit text in cursor position.
+        7. Place cursor inside preedit text.
+        8. Perform the requested action.
+
+        Note that the input method can not receive more than 4000 bytes of selection text, which might be the case for example when the entire document is selected. Nevertheless, the text input must delete the entire selected range before inserting the commit string.
+        
+        Serial handling with protocol_compat == xx_text_input
+        
+        The serial number should be set to 0.
+        
+        Serial handling with protocol_compat == text_input_v3
+
+        The serial number reflects the last state of the xx_input_method_v1
+        object known to the client. The value of the serial argument must be
+        equal to the number of done events already issued by that object. When
+        the compositor receives a commit request with a serial different than
+        the number of past done events, it must proceed as normal, except it
+        should not change the current state of the xx_input_method_v1 object.
+      </description>
+      <arg name="serial" type="uint"/>
+    </request>
+
+    <request name="get_input_popup_surface" since="2">
+      <description summary="create popup surface">
+        Creates a new xx_input_popup_surface_v2 object wrapping a given
+        surface.
+
+        The surface gets assigned the "input_popup" role. If the surface
+        already has an assigned role, the compositor must issue a protocol
+        error.
+
+        Issuing this request before receiving a committed .activate causes the "inactive" error.
+      </description>
+      <arg name="id" type="new_id" interface="xx_input_popup_surface_v2"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="positioner" type="object" interface="xx_input_popup_positioner_v1"/>
+    </request>
+    
+    <event name="unavailable">
+      <description summary="input method unavailable">
+        The input method ceased to be available.
+
+        The compositor must issue this event as the only event on the object if
+        there was another input_method object associated with the same seat at
+        the time of its creation.
+
+        The compositor must issue this request when the object is no longer
+        usable, e.g. due to seat removal.
+
+        The input method context becomes inert and should be destroyed after
+        deactivation is handled. Any further requests and events except for the
+        destroy request must be ignored.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the input method">
+        Destroys the xx_input_method_v1 object and any associated child
+        objects.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="xx_input_popup_surface_v2" version="1">
+    <description summary="popup surface">
+      An input method popup surface is a short-lived, temporary surface.
+      It is meant as an area to show suggestions, candidates, or for other input-related uses.
+
+      The compositor should anchor it at the active text input cursor area.
+      
+      The client must call wl_surface.commit on the corresponding wl_surface
+      for input_popup_surface state updates to take effect, unless otherwise noted.
+      
+      After the initial wl_surface.commit, the compositor must reply with a configure sequence (see .start_configure) initializing all the compositor-provided state of the popup. That means providing values for:
+
+      - width
+      - height
+      - anchor_x
+      - anchor_y
+      - anchor_width
+      - anchor_height
+      - serial
+      
+      using the appropriate events.
+
+      The popup will only be presented to the user after the client receives the configure sequence and replies with .ack_configure.
+      
+      An example init sequence could look like this:
+
+      1. client (Cl): popup = input_method.get_popup(wl_surface, positioner)
+      2. Cl: wl_surface.commit()
+      3. compositor (Co): popup.start_configure(150, 150, 10, -2, 5, 30)
+      5. Co: input_method.done()
+      6. Cl: ack_configure()
+      7. Cl: wl_surface.commit()
+
+      A newly created input_popup_surface will be stacked on top of all previously created
+      input_popup_surfaces associated with the same text input.
+
+      A typical sequence resulting from the user selecting a new text field and typing some text:
+      
+      1. compositor (Co): input_method.activate()
+      2. Co: input_method.done()
+      3. [init sequence]
+      4. Co: input_method.set_surrounding_text("new text")
+      5. Co: popup.start_configure(150, 150, -60, -2, 55, 30)
+      6. Co: input_method.done()
+      7. client (Cl): ack_configure()
+      8. Cl: wl_surface.commit()
+      
+      When the corresponding input_method receives a committed .deactivate event, the popup gets destroyed and becomes invalid and its surface gets unmapped.
+
+      The client must not destroy the underlying wl_surface while the
+      xx_input_popup_surface_v2 object exists.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_serial" value="0" summary="received acknowledgement for a serial which has already been acknowledged or has never been issued"/>
+    </enum>
+    
+    <event name="start_configure">
+      <description summary="configure the popup surface">
+        The start_configure event updates the popup geometry and marks the start of a configure sequence.
+
+        The anchor_* arguments represent the geometry of the anchor to which the popup was attached, relative to the upper left corner of the
+        popup's surface. Note that this makes anchor_x, anchor_y the reverse of the what they represent in xdg_popup.
+
+        A configure sequence is a set of one or more events configuring the state of the
+        input_popup_surface, starting with this event and ending with input_method.done. After the input_method.done event, the configure sequence is considered submitted.
+        
+        State set by event in a configure sequence is conceptually double-buffered.
+        Every argument overwrites its previous value. The state change should get applied atomically with the input_method.done ending the sequence, and the value of serial should return to the undefined value.
+        
+        Events on the input_popup_surface object received outside a configure sequence (while serial is undefined) must be ignored by the client.
+
+        A configure sequence shall be sent every time the compositor (re)positions the popup, or the shape of the anchor changes, for example after popup creation, or in response to text being typed and the text cursor moving.
+        
+        The client may update the surface in response to input_method.done. Unless the popup is destroyed by the input_method.done, the client must reply with
+        an .ack_configure request with the serial sent in the start_configure event at
+        some point after the sequence ends and before committing the new surface.
+
+        If the client receives multiple configure sequences before it can respond
+        to one, it is free to discard all but the last event it received.
+        
+        <!--
+        This sounds complicated because it is.
+        There are two semi-dependent states: that of the text input and that of the popup surface(s).
+        
+        Alternatives:
+        
+        1. Don't synchronize the state of the popup and the state of the text.
+        
+        Rejected because every¹ time the pre-edit changes shape there are two events: the .configure for the surface and the .done from the input method.
+        
+        ¹Actually only when the pre-edit is committed. In the current design, changing the pre-edit doesn't get reported to input-method and doesn't cause a .done. A .done gets emitted for the cursor shape change (so on every stroke), so the compositor would be able to filter it out by paying attention to state changes. That would leave double-rendering only in the case of committing the text (surrounding-text changes) or text changing without input causing reposition (collaborative editing). Worth it maybe?
+        On the other hand, it's not impossible in the future that some other property gets updated on nearly every text change.
+        
+        2. Complicate some and mandate .done after some .configures
+        
+        Rejected because the different path for syncing (on .configure or on .done) are difficult to explain and sound like a source of bugs. Also, this ended up needing additional events.
+        
+        3. Simplify a lot and remove .configure in favor of relying on .done entirely
+        
+        Rejected because it pulls in .ack_configure after every .done regardless of surface status. Also underspecifed regarding which popup needs to be configured.
+        -->
+      </description>
+      <arg name="width" type="uint" summary="popup width"/>
+      <arg name="height" type="uint" summary="popup height"/>
+      <arg name="anchor_x" type="int"
+	   summary="x position relative to anchor geometry"/>
+      <arg name="anchor_y" type="int"
+	   summary="y position relative to anchor geometry"/>
+      <arg name="anchor_width" type="uint"
+	   summary="width of the anchor area"/>
+      <arg name="anchor_height" type="uint"
+	   summary="height of the anchor area"/>
+      <arg name="serial" type="uint" summary="serial of the configure sequence"/>
+    </event>
+
+    <request name="ack_configure">
+      <description summary="acknowledge a configure sequence">
+        This request notifies the compositor that the client updated its surface in response to a configure sequence.
+
+        The purpose of this request is to synchronize the updates of the surface geometry with the surface contents.
+        For example, when the compositor assigns a size larger than previously, the client must fill the additional space before the popup gets displayed to the user with the new size. When the compositor receives .ack_configure, it can proceed to draw the new size.
+
+        .ack_configure should be sent after every submitted configure sequence, passing along the serial received in it.
+        
+        An .ack_configure request is conceptually double-buffered.
+        Every request overrides the previous one. The request takes effect once the .commit request is sent on the corresponding surface.
+
+        If the client receives multiple configure sequences before it
+        can respond to one, it may acknowledge only the last configure sequence by using its serial in the .ack_configure request.
+
+        Committing an .ack_configure request consumes the serial number sent with
+        the request, as well as serial numbers sent by all configure sequences
+        submitted on this input_popup_surface prior to the configure sequence referenced by
+        the committed serial.
+        
+        Committing this request with a serial that, for this surface, never appeared in a submitted configure sequence, or one that was already committed before, raises an invalid_serial
+        error.
+      </description>
+      <arg name="serial" type="uint" summary="the serial from the configure sequence"/>
+    </request>
+    
+    <request name="reposition">
+      <description summary="recalculate the popup's location">
+        Reposition an already-mapped popup. The popup will be placed given the
+        details in the passed input_popup_positioner object.
+
+        The request is processed immediately, without the need to issue wl_surface.commit, but the actual repositioning takes place later, after .ack_configure.
+
+        The compositor should reply with a configure sequence including:
+        - input_popup_surface.start_configure,
+        - input_popup_surface.repositioned, including the token passed in this request.
+        
+        This will discard any parameters set by the previous positioner.
+
+        If multiple .reposition requests are sent before the .repositioned event is submitted as part of a configure sequence, the compositor may ignore all
+        but the last one.
+        
+        The new popup position will not take
+        effect until the corresponding configure sequence is acknowledged by the
+        client. See input_popup_surface.repositioned for details. 
+        
+        The token itself is opaque, and has no other special meaning.
+      </description>
+      <arg name="positioner" type="object" interface="xx_input_popup_positioner_v1"/>
+      <arg name="token" type="uint" summary="reposition request token"/>
+    </request>
+
+    <event name="repositioned">
+      <description summary="signal the completion of a reposition request">
+        The compositor sends the .repositioned event in response to the .reposition request to notify about its completion.
+
+        The new geometry of the popup can be communicated using additional events within a configure sequence including:
+        - input_popup_surface.start_configure, and
+        - the .anchor_position event to update the relative position to the anchor.
+        
+        When responding to a .reposition request, the token argument is the token passed in the that request.
+
+        This event is sent as part of a configure sequence.
+        State set by this event is conceptually double-buffered.
+        Every argument overwrites its previous value. The state change should get applied atomically with the next input_method.done event.
+        
+        The client should optionally update the content of the popup, but must
+        acknowledge the new popup configuration for the new position to take
+        effect. See input_popup_surface.ack_configure for details.
+      </description>
+      <arg name="token" type="uint" summary="reposition request token"/>
+    </event>
+    
+    <request name="destroy" type="destructor">
+      <description summary="remove the popup">
+        This destroys the popup. Explicitly destroying the input_popup_surface
+        object will also dismiss the popup, and unmap the surface.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="xx_input_popup_positioner_v1" version="1">
+    <description summary="input method popup positioner">
+      The input_popup_positioner provides a collection of rules for the placement of an input method popup surface relative to the cursor.
+      Rules can be defined to ensure
+      the text input area remains within the visible area's borders, and to
+      specify how the popup changes its position, such as sliding along
+      an axis, or flipping around a rectangle. These positioner-created rules are
+      constrained by the requirement that a popup must intersect with or
+      be at least partially adjacent to the surface containing the text input.
+
+      See the various requests for details about possible rules.
+      
+      A newly created positioner has the following state:
+      - 0 surface width
+      - 0 surface height
+      - anchor at the center ("none")
+      - gravity towards the center ("none")
+      - constraints adjustment set to none
+      - offset at x = 0, y = 0
+      - not reactive
+
+      Upon receiving a request taking the positioner as an argument, the compositor makes a copy of the rules
+      specified by the input_popup_positioner. Thus, after the request is complete the
+      input_popup_positioner object can be destroyed or reused; further changes to the
+      object will have no effect on previous usages.
+
+      For an input_popup_positioner object to be considered complete, its state must contain a non-zero width and height. Passing an incomplete input_popup_positioner object when
+      positioning a surface raises an invalid_positioner error.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_input" value="0" summary="invalid input provided"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the input_popup_positioner object">
+        Notify the compositor that the positioner will no longer be used.
+      </description>
+    </request>
+
+    <request name="set_size">
+      <description summary="set the size of the to-be positioned rectangle">
+        Set the size of the surface that is to be positioned with the positioner
+        object. The size is in surface-local coordinates and corresponds to the
+        window geometry. See xdg_surface.set_window_geometry.
+
+        If any dimension is set to zero, the invalid_input error is raised.
+      </description>
+      <arg name="width" type="uint" summary="width of positioned rectangle"/>
+      <arg name="height" type="uint" summary="height of positioned rectangle"/>
+    </request>
+
+    <enum name="anchor">
+      <entry name="none" value="0" summary="no edge, specifies center"/>
+      <entry name="top" value="1"/>
+      <entry name="bottom" value="2"/>
+      <entry name="left" value="3"/>
+      <entry name="right" value="4"/>
+      <entry name="top_left" value="5"/>
+      <entry name="bottom_left" value="6"/>
+      <entry name="top_right" value="7"/>
+      <entry name="bottom_right" value="8"/>
+    </enum>
+
+    <request name="set_anchor">
+      <description summary="set anchor rectangle anchor">
+        Defines the anchor point for the anchor rectangle. The specified anchor
+        is used to derive an anchor point that the popup surface will be
+        positioned relative to. If a corner anchor is set (e.g. 'top_left' or
+        'bottom_right'), the anchor point will be at the specified corner;
+        otherwise, the derived anchor point will be centered on the specified
+        edge, or in the center of the anchor rectangle if no edge is specified.
+      </description>
+      <arg name="anchor" type="uint" enum="anchor"
+	   summary="anchor"/>
+    </request>
+
+    <enum name="gravity">
+      <entry name="none" value="0" summary="center to center"/>
+      <entry name="top" value="1"/>
+      <entry name="bottom" value="2"/>
+      <entry name="left" value="3"/>
+      <entry name="right" value="4"/>
+      <entry name="top_left" value="5"/>
+      <entry name="bottom_left" value="6"/>
+      <entry name="top_right" value="7"/>
+      <entry name="bottom_right" value="8"/>
+    </enum>
+
+    <request name="set_gravity">
+      <description summary="set surface gravity">
+        Defines in what direction the surface should be positioned, relative to
+        the anchor point of the anchor rectangle. If a corner gravity is
+        specified (e.g. 'bottom_right' or 'top_left'), then the surface
+        will be placed towards the specified gravity; otherwise, the child
+        surface will be centered over the anchor point on any axis that had no
+        gravity specified. If the gravity is not in the ‘gravity’ enum, an
+        invalid_input error is raised.
+      </description>
+      <arg name="gravity" type="uint" enum="gravity"
+	   summary="gravity direction"/>
+    </request>
+
+    <enum name="constraint_adjustment" bitfield="true">
+      <description summary="constraint adjustments">
+        The constraint adjustment value define ways the compositor will adjust
+        the position of the surface, if the unadjusted position would result
+        in the surface being partly constrained.
+
+        Whether a surface is considered 'constrained' is left to the compositor
+        to determine. For example, the surface may be partly outside the
+        compositor's defined 'work area', thus necessitating the child surface's
+        position be adjusted until it is entirely inside the work area.
+
+        The adjustments can be combined, according to a defined precedence: 1)
+        Flip, 2) Slide, 3) Resize.
+      </description>
+      <entry name="none" value="0">
+        <description summary="don't move the surface when constrained">
+          Don't alter the surface position even if it is constrained on some
+          axis, for example partially outside the edge of an output.
+        </description>
+      </entry>
+      <entry name="slide_x" value="1">
+        <description summary="move along the x axis until unconstrained">
+          Slide the surface along the x axis until it is no longer constrained.
+
+          First try to slide towards the direction of the gravity on the x axis
+          until either the edge in the opposite direction of the gravity is
+          unconstrained or the edge in the direction of the gravity is
+          constrained.
+
+          Then try to slide towards the opposite direction of the gravity on the
+          x axis until either the edge in the direction of the gravity is
+          unconstrained or the edge in the opposite direction of the gravity is
+          constrained.
+        </description>
+      </entry>
+      <entry name="slide_y" value="2">
+        <description summary="move along the y axis until unconstrained">
+          Slide the surface along the y axis until it is no longer constrained.
+
+          First try to slide towards the direction of the gravity on the y axis
+          until either the edge in the opposite direction of the gravity is
+          unconstrained or the edge in the direction of the gravity is
+          constrained.
+
+          Then try to slide towards the opposite direction of the gravity on the
+          y axis until either the edge in the direction of the gravity is
+          unconstrained or the edge in the opposite direction of the gravity is
+          constrained.
+        </description>
+      </entry>
+      <entry name="flip_x" value="4">
+        <description summary="invert the anchor and gravity on the x axis">
+          Invert the anchor and gravity on the x axis if the surface is
+          constrained on the x axis. For example, if the left edge of the
+          surface is constrained, the gravity is 'left' and the anchor is
+          'left', change the gravity to 'right' and the anchor to 'right'.
+
+          If the adjusted position also ends up being constrained, the resulting
+          position of the flip_x adjustment will be the one before the
+          adjustment.
+        </description>
+      </entry>
+      <entry name="flip_y" value="8">
+        <description summary="invert the anchor and gravity on the y axis">
+          Invert the anchor and gravity on the y axis if the surface is
+          constrained on the y axis. For example, if the bottom edge of the
+          surface is constrained, the gravity is 'bottom' and the anchor is
+          'bottom', change the gravity to 'top' and the anchor to 'top'.
+
+          The adjusted position is calculated given the original anchor
+          rectangle and offset, but with the new flipped anchor and gravity
+          values.
+
+          If the adjusted position also ends up being constrained, the resulting
+          position of the flip_y adjustment will be the one before the
+          adjustment.
+        </description>
+      </entry>
+      <entry name="resize_x" value="16">
+        <description summary="horizontally resize the surface">
+          Resize the surface horizontally so that it is completely
+          unconstrained.
+        </description>
+          </entry>
+          <entry name="resize_y" value="32">
+        <description summary="vertically resize the surface">
+          Resize the surface vertically so that it is completely unconstrained.
+        </description>
+      </entry>
+    </enum>
+
+    <request name="set_constraint_adjustment">
+      <description summary="set the adjustment to be done when constrained">
+        Specify how the popup should be positioned if the originally intended
+        position caused the surface to be constrained, meaning at least
+        partially outside positioning boundaries set by the compositor. The
+        adjustment is set by constructing a bitmask describing the adjustment to
+        be made when the surface is constrained on that axis.
+
+        If no bit for one axis is set, the compositor will assume that the child
+        surface should not change its position on that axis when constrained.
+
+        If more than one bit for one axis is set, the order of how adjustments
+        are applied is specified in the corresponding adjustment descriptions.
+
+        The default adjustment is none.
+      </description>
+      <arg name="constraint_adjustment" type="uint" enum="constraint_adjustment"
+	   summary="bit mask of constraint adjustments"/>
+    </request>
+
+    <request name="set_offset">
+      <description summary="set surface position offset">
+        Specify the surface position offset relative to the position of the
+        anchor on the anchor rectangle and the anchor on the surface. For
+        example if the anchor of the anchor rectangle is at (x, y), the surface
+        has the gravity bottom|right, and the offset is (ox, oy), the calculated
+        surface position will be (x + ox, y + oy). The offset position of the
+        surface is the one used for constraint testing. See
+        set_constraint_adjustment.
+
+        An example use case is placing a popup menu on top of a user interface
+        element, while aligning the user interface element of the parent surface
+        with some user interface element placed somewhere in the popup surface.
+      </description>
+      <arg name="x" type="int" summary="surface position x offset"/>
+      <arg name="y" type="int" summary="surface position y offset"/>
+    </request>
+
+    <request name="set_reactive">
+      <description summary="continuously reconstrain the surface">
+        When set reactive, the surface is reconstrained if the conditions used
+        for constraining changed, e.g. the window containing the text input moved.
+
+        Whenever the conditions change and the popup gets reconstrained, a
+        configure sequence is sent with updated geometry.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="xx_input_method_manager_v2" version="4">
+    <description summary="input method manager">
+      The input method manager allows the client to become the input method on
+      a chosen seat.
+
+      No more than one input method must be associated with any seat at any
+      given time.
+    </description>
+
+    <request name="get_input_method">
+      <description summary="request an input method object">
+        Request a new input xx_input_method_v1 object associated with a given
+        seat.
+      </description>
+      <arg name="seat" type="object" interface="wl_seat"/>
+      <arg name="input_method" type="new_id" interface="xx_input_method_v1"/>
+    </request>
+
+    <request name="get_positioner">
+      <description summary="create a positioner object">
+        Create a positioner object. A positioner object is used to position
+        surfaces relative to some parent surface. See the interface description
+        and xdg_surface.get_popup for details.
+      </description>
+      <arg name="id" type="new_id" interface="xx_input_popup_positioner_v1"/>
+    </request>
+    
+    <request name="destroy" type="destructor">
+      <description summary="destroy the input method manager">
+        Destroys the xx_input_method_manager_v2 object.
+
+        The xx_input_method_v1 objects originating from it remain valid.
+      </description>
+    </request>
+  </interface>
+</protocol>

experimental/xx-keyboard-filter/README

@@ -0,0 +1,4 @@
+Keyboard filter protocol
+
+Maintainers:
+Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>

experimental/xx-keyboard-filter/xx-keyboard-filter-v1.xml

@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="keyboard_filter_experimental_v1">
+
+  <copyright>
+    Copyright 2018 Mike Blumenkrantz
+    Copyright 2018 Samsung Electronics Co., Ltd
+    Copyright 2018 Red Hat Inc.
+    Copyright 2025 DorotaC
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+  
+  <description summary="filter and intercept keyboard events">
+    The keyboard_filter protocol allows a client to intercept selected keyboard events and prevent them from reaching the focused surface.
+    
+    This protocol offers a way to alter events reaching an application without the need to allow generating arbitrary keyboard events.
+    
+    High-level overview of the interfaces:
+    
+    The keyboard_filter_manager exposes the bind_to_input_method request which binds a wl_keyboard to an xx_input_method.
+    The resulting keyboard_filter object has the can be then used for intercepting keyboard events in accordance to input method needs.
+    
+    This document adheres to the RFC 2119 when using words like "must",
+    "should", "may", etc.
+
+    Warning! The protocol described in this file is currently in the
+    experimental phase. Backwards incompatible major versions of the
+    protocol are to be expected. Exposing this protocol without an opt-in
+    mechanism is discouraged.
+  </description>
+
+  <interface name="xx_keyboard_filter_v1" version="1">
+    <description summary="keyboard event filtering functionality">
+      Manages the filtering of key presses.
+    </description>
+    
+    <enum name="error">
+      <entry name="invalid_serial" value="0x1" summary="compositor received serial not adhering to requirements"/>
+    </enum>
+
+    <request name="unbind">
+      <description summary="Stop intercepting">
+        Unbind the keyboard and stop intercepting events.
+
+        Unbinds the bound keyboard and the input method. the compositor must stop redirecting keyboard events. Events that the keyboard_filter client has not yet responded to are treated as if they received the "passthrough" action.
+
+        This request takes effect immediately.
+      </description>
+    </request>
+
+    <enum name="filter_action">
+      <entry name="consume" value="0" summary="consume the key event"/>
+      <entry name="passthrough" value="1" summary="pass the key event to the text input client"/>
+    </enum>
+    
+    <request name="filter">
+      <description summary="decide the processing of a keyboard event">
+        This request controls the filtering of keyboard input events before reaching the focused surface.
+        
+        Usage:
+
+        While keyboard_filter is intercepting, the compositor must send every intercepted event to its bound wl_keyboard, and hold a copy of it in an internal queue.
+        When the client responds with the .filter request, the compositor either removes the event from the queue (filter_action.consume), or sends the copy to the original wl_keyboard objects (filter_action.passthrough).
+
+        The compositor must process .filter the oldest event in the queue before processing more recent ones.
+        For this reason, the client sets the argument "serial" to the serial of the corresponding event it received.
+        
+        Exceptions:
+
+        If the event is other than wl_keyboard.key or contains no serial, it cannot be filtered. The keyboard_filter client must not respond to it with .filter request. When such an event is oldest in the queue, the compositor must proceed as if the event had received a "passthrough" reply.
+
+        As of wl_keyboard v10 and keyboard_filter_v1, the only event that can be filtered is the wl_keyboard.key event.
+        
+        Sequence:
+
+        The wl_keyboard begins to receive events after input_method.activate is committed.
+        The valid serial is the serial of the oldest wl_keyboard event which has been sent after input_method.activate but which hasn't yet received a .filter confirmation.
+        The compositor may raise the invalid_serial error in response to events with serials it had not issued.
+        The compositor must ignore events with all other serials. (Particularly, this means events with repeating serials are accepted normally and are not ignored).
+        Events must be filtered in order of arrival.
+      </description>
+      <arg name="serial" type="uint"/>
+      <arg name="action" type="uint" enum="filter_action"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the keyboard">
+        Destroys the keyboard_filter object, stops event interception, and unbinds the wl_keyboard and input_method objects bound to it.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="xx_keyboard_filter_manager_v1" version="1">    
+    <enum name="error">
+      <entry name="already_bound" value="0x1" summary="an argument is already bound"/>
+      <entry name="wrong_seat" value="0x2" summary="the keyboard i attached to the wrong seat for this operation"/>
+    </enum>
+
+    <request name="bind_to_input_method">
+      <description summary="Bind a keyboard to an input method">
+        Bind a keyboard to an input method for the purpose of capturing key presses before they reach the text input client.
+
+        When a wl_keyboard is bound, the compositor must redirect to it the input events intended for the focused surface with text input enabled. The wl_keyboard instance receives no other events from then on.
+        See keyboard_filter.filter.
+        
+        For the bound wl_keyboard instance to intercept events, the following conditions must be fulfilled:
+        - there's a focused surface,
+        - the surface has an enabled text input object,
+        - the bound input method is active (for the meaning of "active", see input_method.activate, input_method.deactivate).
+        
+        When those conditions are fulfilled, the compositor must start redirecting input events intended for the text input surface to the wl_keyboard bound with this request. Otherwise, the text input surface receives events without intercepting them.
+
+        Be aware that the text input client might use a wl_keyboard object(s) of different version(s) than the one used by the input method. The compositor should issue events as it would normally do for the versions in question. This protocol assumes that events to multiple keyboards of different protocol versions are equivalent.
+
+        Background:
+
+        Whenever the input method is activated, the compositor must start sending it keyboard events intended for the text-input client, so that the input method can be controlled using a keyboard.
+        Traditionally, from the user perspective, input methods receive keys as if they were an overlay: keys which are interesting to the input method gain a special input method meaning, all others work as usual.
+        The binding and the keyboard_filter.filter request together make this possible by letting the input method indicate which events it is interested in.
+
+        Conceptually, when a wl_keyboard is bound to an input_method, the compositor prevents all keyboard events directed to the text input client from reaching it. They are delayed until the input method decides how to filter them using the keyboard_filter.filter request.
+
+        Arguments:
+
+        The wl_keyboard must not be already bound to another interface.
+        The wl_keyboard must only receive events between committed .activate and .deactivate.
+
+        The surface argument represents an arbitrary wl_surface. When issuing wl_keyboard.enter and wl_keyboard.leave on the bound wl_keyboard, the compositor must replace the original surface argument with the one provided by the input method in this request.
+
+        Because the wl_keyboard.enter and wl_keyboard.leave events require a surface as the target, one must be provided even if the input method doesn't display one. A dummy one is sufficient. The provided wl_surface will not be used for any other purpose than explained above.
+        
+        The surface must outlive the input method.
+
+        NOTE: This feature works much better with compositor-side key repeat introduced in wl_seat version 10. This protocol doesn't provide controls for filtering repeat key events generated client-side.
+        A compositor implementing this protocol should implement compositor-side key repeat.
+
+        This request takes effect immediately.
+
+        Attempting to bind a keyboard to an input method which is already bound must cause the already_bound error.
+        Attempting to bind a keyboard object which was already bound must cause the already_bound error.
+        Attempting to bind a keyboard object to an input method acting on a different seat must cause the wrong_seat error.
+        
+        Once any of the bound objects are destroyed, the xx_keyboard_filter_v1 instance becomes disabled and it must ignore all following requests.
+
+        When the input method gets destroyed, the compositor must stop issuing events to the keyboard and ignore any further requests to keyboard_filter, except keyboard_filter.destroy.
+      </description>
+      <arg name="keyboard" type="object" interface="wl_keyboard" />
+      <arg name="input_method" type="object" interface="xx_input_method_v1" />
+      <arg name="surface" type="object" interface="wl_surface" />
+      <arg name="extensions" type="new_id" interface="xx_keyboard_filter_v1"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the input method manager">
+        Destroys the xx_keyboard_filter_manager_v1 object.
+
+        The xx_keyboard_filter_v1 objects originating from it remain unaffected.
+      </description>
+    </request>
+  </interface>
+</protocol>

experimental/xx-session-management/README

@@ -0,0 +1,4 @@
+Session management protocol
+
+Maintainers:
+Carlos Garnacho <carlosg@gnome.org>

experimental/xx-session-management/xx-session-management-v1.xml

@@ -0,0 +1,264 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xx_session_management_v1">
+  <copyright>
+    Copyright 2018 Mike Blumenkrantz
+    Copyright 2018 Samsung Electronics Co., Ltd
+    Copyright 2018 Red Hat Inc.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for managing application sessions">
+    This description provides a high-level overview of the interplay between
+    the interfaces defined this protocol. For details, see the protocol
+    specification.
+
+    The xx_session_manager protocol declares interfaces necessary to
+    allow clients to restore toplevel state from previous executions. The
+    xx_session_manager_v1.get_session request can be used to obtain a
+    xx_session_v1 resource representing the state of a set of toplevels.
+
+    Clients may obtain the session string to use in future calls through
+    the xx_session_v1.created event. Compositors will use this string
+    as an identifiable token for future runs, possibly storing data about
+    the related toplevels in persistent storage.
+
+    Toplevels are managed through the xx_session_v1.add_toplevel and
+    xx_session_toplevel_v1.remove pair of requests. Clients will explicitly
+    request a toplevel to be restored according to prior state through the
+    xx_session_v1.restore_toplevel request before the toplevel is mapped.
+
+    Warning! The protocol described in this file is currently in the
+    experimental phase. Backwards incompatible major versions of the
+    protocol are to be expected. Exposing this protocol without an opt-in
+    mechanism is discouraged.
+  </description>
+
+  <interface name="xx_session_manager_v1" version="1">
+    <description summary="manage sessions for applications">
+      The xx_session_manager interface defines base requests for creating and
+      managing a session for an application. Sessions persist across application
+      and compositor restarts unless explicitly destroyed. A session is created
+      for the purpose of maintaining an application's xdg_toplevel surfaces
+      across compositor or application restarts. The compositor should remember
+      as many states as possible for surfaces in a given session, but there is
+      no requirement for which states must be remembered.
+    </description>
+
+    <enum name="error">
+      <entry name="in_use" summary="a requested session is already in use"
+             value="1"/>
+    </enum>
+
+    <enum name="reason">
+      <description summary="reason for getting a session">
+        The reason may determine in what way a session restores the window
+        management state of associated toplevels.
+
+        For example newly launched applications might be launched on the active
+        workspace with restored size and position, while a recovered
+        applications might restore additional state such as active workspace and
+        stacking order.
+      </description>
+      <entry name="launch" value="1">
+        <description summary="an app is newly launched">
+          A new app instance is launched, for example from an app launcher.
+        </description>
+      </entry>
+      <entry name="recover" value="2">
+        <description summary="an app recovered">
+          An app instance is recovering from for example a compositor or app crash.
+        </description>
+      </entry>
+      <entry name="session_restore" value="3">
+        <description summary="an app restored">
+          An app instance is restored, for example part of a restored session, or
+          restored from having been temporarily terminated due to resource
+          constraints.
+        </description>
+      </entry>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy this object">
+        This has no effect other than to destroy the xx_session_manager object.
+      </description>
+    </request>
+
+    <request name="get_session">
+      <description summary="create or restore a session">
+        Create a session object corresponding to either an existing session
+        identified by the given session identifier string or a new session.
+        While the session object exists, the session is considered to be "in
+        use".
+
+        If a identifier string represents a session that is currently actively
+        in use by the the same client, an 'in_use' error is raised. If some
+        other client is currently using the same session, the new session will
+        replace managing the associated state.
+
+        NULL is passed to initiate a new session. If an id is passed which does
+        not represent a valid session, the compositor treats it as if NULL had
+        been passed.
+
+        A client is allowed to have any number of in use sessions at the same
+        time.
+      </description>
+      <arg name="id" type="new_id" interface="xx_session_v1"/>
+      <arg name="reason" type="uint" enum="reason"
+           summary="reason for session"/>
+      <arg name="session" type="string"
+           summary="the session to restore"
+           allow-null="true"/>
+    </request>
+  </interface>
+
+  <interface name="xx_session_v1" version="1">
+    <description summary="A session for an application">
+      A xx_session_v1 object represents a session for an application. While the
+      object exists, all surfaces which have been added to the session will
+      have states stored by the compositor which can be reapplied at a later
+      time. Two sessions cannot exist for the same identifier string.
+
+      States for surfaces added to a session are automatically updated by the
+      compositor when they are changed.
+
+      Surfaces which have been added to a session are automatically removed from
+      the session if xdg_toplevel.destroy is called for the surface.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_restore"
+             summary="restore cannot be performed after initial toplevel commit"
+             value="1"/>
+      <entry name="name_in_use"
+             summary="toplevel name is already in used"
+             value="2"/>
+      <entry name="already_mapped"
+             summary="toplevel was already mapped when restored"
+             value="3"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the session">
+        Destroy a session object, preserving the current state but not continuing
+        to make further updates if state changes occur. This makes the associated
+        xx_toplevel_session_v1 objects inert.
+      </description>
+    </request>
+
+    <request name="remove" type="destructor">
+      <description summary="Remove the session">
+        Remove the session, making it no longer available for restoration. A
+        compositor should in response to this request remove the data related to
+        this session from its storage.
+      </description>
+    </request>
+
+    <request name="add_toplevel">
+      <description summary="add a new surface to the session">
+        Attempt to add a given surface to the session. The passed name is used
+        to identify what window is being restored, and may be used store window
+        specific state within the session.
+
+        Calling this with a toplevel that is already managed by the session with
+        the same associated will raise an in_use error.
+      </description>
+      <arg name="id" type="new_id" interface="xx_toplevel_session_v1"/>
+      <arg name="toplevel" type="object" interface="xdg_toplevel"/>
+      <arg name="name" type="string"/>
+    </request>
+
+    <request name="restore_toplevel">
+      <description summary="restore a surface state">
+        Inform the compositor that the toplevel associated with the passed name
+        should have its window management state restored.
+
+        Calling this with a toplevel that is already managed by the session with
+        the same associated will raise an in_use error.
+
+        This request must be called prior to the first commit on the associated
+        wl_surface, otherwise an already_mapped error is raised.
+
+        As part of the initial configure sequence, if the toplevel was
+        successfully restored, a xx_toplevel_session_v1.restored event is
+        emitted. See the xx_toplevel_session_v1.restored event for further
+        details.
+      </description>
+      <arg name="id" type="new_id" interface="xx_toplevel_session_v1"/>
+      <arg name="toplevel" type="object" interface="xdg_toplevel"/>
+      <arg name="name" type="string"/>
+    </request>
+
+    <event name="created">
+      <description summary="newly-created session id">
+        Emitted at most once some time after getting a new session object. It
+        means that no previous state was restored, and a new session was created.
+        The passed id can be used to restore previous sessions.
+      </description>
+      <arg name="id" type="string"/>
+    </event>
+
+    <event name="restored">
+      <description summary="the session has been restored">
+        Emitted at most once some time after getting a new session object. It
+        means that previous state was at least partially restored. The same id
+        can again be used to restore previous sessions.
+      </description>
+    </event>
+
+    <event name="replaced">
+      <description summary="the session has been restored">
+        Emitted at most once, if the session was taken over by some other
+        client. When this happens, the session and all its toplevel session
+        objects become inert, and should be destroyed.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="xx_toplevel_session_v1" version="1">
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the object">
+        Destroy the object. This has no effect window management of the
+        associated toplevel.
+      </description>
+    </request>
+
+    <request name="remove" type="destructor">
+      <description summary="remove a surface from the session">
+        Remove a specified surface from the session and render any corresponding
+        xx_toplevel_session_v1 object inert. The compositor should remove any
+        data related to the toplevel in the corresponding session from its internal
+        storage.
+      </description>
+    </request>
+
+    <event name="restored">
+      <description summary="a toplevel's session has been restored">
+        The "restored" event is emitted prior to the first
+        xdg_toplevel.configure for the toplevel. It will only be emitted after
+        xx_session_v1.restore_toplevel, and the initial empty surface state has
+        been applied, and it indicates that the surface's session is being
+        restored with this configure event.
+      </description>
+      <arg name="surface" type="object" interface="xdg_toplevel"/>
+    </event>
+  </interface>
+</protocol>

experimental/xx-text-input/README

@@ -0,0 +1,6 @@
+Text input protocol
+
+Maintainers:
+Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>
+
+

experimental/xx-text-input/xx-text-input-v3.xml

@@ -0,0 +1,592 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="xx_text_input_unstable_v3">
+  <copyright>
+    Copyright © 2012, 2013 Intel Corporation
+    Copyright © 2015, 2016 Jan Arne Petersen
+    Copyright © 2017, 2018 Red Hat, Inc.
+    Copyright © 2018       Purism SPC
+    Copyright © 2025       DorotaC
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+    THIS SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for composing text">
+    This protocol allows compositors to act as input methods and to send text
+    to applications. A text input object is used to manage state of what are
+    typically text entry fields in the application.
+
+    This document adheres to the RFC 2119 when using words like "must",
+    "should", "may", etc.
+
+    Warning! The protocol described in this file is experimental and
+    backward incompatible changes may be made. Backward compatible changes
+    may be added together with the corresponding interface version bump.
+    Backward incompatible changes are done by bumping the version number in
+    the protocol and interface names and resetting the interface version.
+    Once the protocol is to be declared stable, the 'xx' prefix and the
+    version number in the protocol and interface names are removed and the
+    interface version number is reset.
+  </description>
+
+  <interface name="xx_text_input_v3" version="3">
+    <description summary="text input">
+      The xx_text_input_v3 interface represents text input and input methods
+      associated with a seat. It provides enter/leave events to follow the
+      text input focus for a seat.
+
+      Requests are used to enable/disable the text-input object and set
+      state information like surrounding and selected text or the content type.
+      The information about the entered text is sent to the text-input object
+      via the preedit_string and commit_string events.
+
+      Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices
+      must not point to middle bytes inside a code point: they must either
+      point to the first byte of a code point or to the end of the buffer.
+      Lengths must be measured between two valid indices.
+
+      Focus moving throughout surfaces will result in the emission of
+      xx_text_input_v3.enter and xx_text_input_v3.leave events. The focused
+      surface must commit xx_text_input_v3.enable and
+      xx_text_input_v3.disable requests as the keyboard focus moves across
+      editable and non-editable elements of the UI. Those two requests are not
+      expected to be paired with each other, the compositor must be able to
+      handle consecutive series of the same request.
+
+      State is sent by the state requests (set_surrounding_text,
+      set_content_type and set_cursor_rectangle) and a commit request. After an
+      enter event or disable request all state information is invalidated and
+      needs to be resent by the client.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the xx_text_input">
+        Destroy the xx_text_input object. Also disables all surfaces enabled
+        through this xx_text_input object.
+      </description>
+    </request>
+
+    <request name="enable">
+      <description summary="Request text input to be enabled">
+        Requests text input on the surface previously obtained from the enter
+        event.
+
+        This request must be issued every time the active text input changes
+        to a new one, including within the current surface. Use
+        xx_text_input_v3.disable when there is no longer any input focus on
+        the current surface.
+
+        Clients must not enable more than one text input on the single seat
+        and should disable the current text input before enabling the new one.
+        At most one instance of text input may be in enabled state per instance,
+        Requests to enable the another text input when some text input is active
+        must be ignored by compositor.
+
+        This request resets all state associated with previous enable, disable,
+        set_surrounding_text, set_text_change_cause, set_content_type, and
+        set_cursor_rectangle requests, as well as the state associated with
+        preedit_string, commit_string, delete_surrounding_text, and action
+        events.
+
+        The set_surrounding_text, set_content_type and set_cursor_rectangle
+        requests must follow if the text input supports the necessary
+        functionality.
+
+        State set with this request is double-buffered. It will get applied on
+        the next xx_text_input_v3.commit request, and stay valid until the
+        next committed enable or disable request.
+
+        The changes must be applied by the compositor after issuing a
+        xx_text_input_v3.commit request.
+      </description>
+    </request>
+
+    <request name="disable">
+      <description summary="Disable text input on a surface">
+        Explicitly disable text input on the current surface (typically when
+        there is no focus on any text entry inside the surface).
+
+        State set with this request is double-buffered. It will get applied on
+        the next xx_text_input_v3.commit request.
+      </description>
+    </request>
+
+    <request name="set_surrounding_text">
+      <description summary="sets the surrounding text">
+        Sets the surrounding plain text around the input, excluding the preedit
+        text.
+
+        The client should notify the compositor of any changes in any of the
+        values carried with this request, including changes caused by handling
+        incoming text-input events as well as changes caused by other
+        mechanisms like keyboard typing.
+
+        If the client is unaware of the text around the cursor, it should not
+        issue this request, to signify lack of support to the compositor.
+
+        Text is UTF-8 encoded, and should include the cursor position, the
+        complete selection and additional characters before and after them.
+        There is a maximum length of wayland messages, so text can not be
+        longer than 4000 bytes.
+
+        Cursor is the byte offset of the cursor within text buffer.
+
+        Anchor is the byte offset of the selection anchor within text buffer.
+        If there is no selected text, anchor is the same as cursor.
+
+        If any preedit text is present, it is replaced with a cursor for the
+        purpose of this event.
+
+        Values set with this request are double-buffered. They will get applied
+        on the next xx_text_input_v3.commit request, and stay valid until the
+        next committed enable or disable request.
+
+        The initial state for affected fields is empty, meaning that the text
+        input does not support sending surrounding text. If the empty values
+        get applied, subsequent attempts to change them may have no effect.
+      </description>
+      <arg name="text" type="string"/>
+      <arg name="cursor" type="int"/>
+      <arg name="anchor" type="int"/>
+    </request>
+
+    <enum name="change_cause">
+      <description summary="text change reason">
+        Reason for the change of surrounding text or cursor posision.
+      </description>
+      <entry name="input_method" value="0" summary="input method caused the change"/>
+      <entry name="other" value="1" summary="something else than the input method caused the change"/>
+    </enum>
+
+    <request name="set_text_change_cause">
+      <description summary="indicates the cause of surrounding text change">
+        Tells the compositor why the text surrounding the cursor changed.
+
+        Whenever the client detects an external change in text, cursor, or
+        anchor posision, it must issue this request to the compositor. This
+        request is intended to give the input method a chance to update the
+        preedit text in an appropriate way, e.g. by removing it when the user
+        starts typing with a keyboard.
+
+        cause describes the source of the change.
+
+        The value set with this request is double-buffered. It must be applied
+        and reset to initial at the next xx_text_input_v3.commit request.
+
+        The initial value of cause is input_method.
+      </description>
+      <arg name="cause" type="uint" enum="change_cause"/>
+    </request>
+
+    <enum name="content_hint" bitfield="true">
+      <description summary="content hint">
+        Content hint is a bitmask to allow to modify the behavior of the text
+        input.
+      </description>
+      <entry name="none" value="0x0" summary="no special behavior"/>
+      <entry name="completion" value="0x1" summary="suggest word completions"/>
+      <entry name="spellcheck" value="0x2" summary="suggest word corrections"/>
+      <entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/>
+      <entry name="lowercase" value="0x8" summary="prefer lowercase letters"/>
+      <entry name="uppercase" value="0x10" summary="prefer uppercase letters"/>
+      <entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/>
+      <entry name="hidden_text" value="0x40" summary="characters should be hidden"/>
+      <entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
+      <entry name="latin" value="0x100" summary="just Latin characters should be entered"/>
+      <entry name="multiline" value="0x200" summary="the text input is multiline"/>
+    </enum>
+
+    <enum name="content_purpose">
+      <description summary="content purpose">
+        The content purpose allows to specify the primary purpose of a text
+        input.
+
+        This allows an input method to show special purpose input panels with
+        extra characters or to disallow some characters.
+      </description>
+      <entry name="normal" value="0" summary="default input, allowing all characters"/>
+      <entry name="alpha" value="1" summary="allow only alphabetic characters"/>
+      <entry name="digits" value="2" summary="allow only digits"/>
+      <entry name="number" value="3" summary="input a number (including decimal separator and sign)"/>
+      <entry name="phone" value="4" summary="input a phone number"/>
+      <entry name="url" value="5" summary="input an URL"/>
+      <entry name="email" value="6" summary="input an email address"/>
+      <entry name="name" value="7" summary="input a name of a person"/>
+      <entry name="password" value="8" summary="input a password (combine with sensitive_data hint)"/>
+      <entry name="pin" value="9" summary="input is a numeric password (combine with sensitive_data hint)"/>
+      <entry name="date" value="10" summary="input a date"/>
+      <entry name="time" value="11" summary="input a time"/>
+      <entry name="datetime" value="12" summary="input a date and time"/>
+      <entry name="terminal" value="13" summary="input for a terminal"/>
+    </enum>
+
+    <request name="set_content_type">
+      <description summary="set content purpose and hint">
+        Sets the content purpose and content hint. While the purpose is the
+        basic purpose of an input field, the hint flags allow to modify some of
+        the behavior.
+
+        Values set with this request are double-buffered. They will get applied
+        on the next xx_text_input_v3.commit request.
+        Subsequent attempts to update them may have no effect. The values
+        remain valid until the next committed enable or disable request.
+
+        The initial value for hint is none, and the initial value for purpose
+        is normal.
+      </description>
+      <arg name="hint" type="uint" enum="content_hint"/>
+      <arg name="purpose" type="uint" enum="content_purpose"/>
+    </request>
+
+    <request name="set_cursor_rectangle">
+      <description summary="set cursor position">
+        Marks an area around the cursor as a x, y, width, height rectangle in
+        surface local coordinates.
+
+        Allows the compositor to put a window with word suggestions near the
+        cursor, without obstructing the text being input.
+
+        If the client is unaware of the position of edited text, it should not
+        issue this request, to signify lack of support to the compositor.
+
+        Values set with this request are double-buffered. They will get applied
+        on the next xx_text_input_v3.commit request, and stay valid until the
+        next committed enable or disable request.
+
+        The initial values describing a cursor rectangle are empty. That means
+        the text input does not support describing the cursor area. If the
+        empty values get applied, subsequent attempts to change them may have
+        no effect.
+      </description>
+      <arg name="x" type="int"/>
+      <arg name="y" type="int"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+    </request>
+
+    <request name="commit">
+      <description summary="commit state">
+        Atomically applies state changes recently sent to the compositor.
+
+        The commit request establishes and updates the state of the client, and
+        must be issued after any changes to apply them.
+
+        Text input state (enabled status, content purpose, content hint,
+        surrounding text and change cause, cursor rectangle) is conceptually
+        double-buffered within the context of a text input, i.e. between a
+        committed enable request and the following committed enable or disable
+        request.
+
+        Protocol requests modify the pending state, as opposed to the current
+        state in use by the input method. A commit request atomically applies
+        all pending state, replacing the current state. After commit, the new
+        pending state is as documented for each related request.
+
+        Requests are applied in the order of arrival.
+
+        Neither current nor pending state are modified unless noted otherwise.
+
+        The compositor must count the number of commit requests coming from
+        each xx_text_input_v3 object and use the count as the serial in done
+        events.
+      </description>
+    </request>
+
+    <event name="enter">
+      <description summary="enter event">
+        Notification that this seat's text-input focus is on a certain surface.
+
+        If client has created multiple text input objects, compositor must send
+        this event to all of them.
+
+        When the seat has the keyboard capability the text-input focus follows
+        the keyboard focus. This event sets the current surface for the
+        text-input object.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </event>
+
+    <event name="leave">
+      <description summary="leave event">
+        Notification that this seat's text-input focus is no longer on a
+        certain surface. The client should reset any preedit string previously
+        set.
+
+        The leave notification clears the current surface. It is sent before
+        the enter notification for the new focus. After leave event, compositor
+        must ignore requests from any text input instances until next enter
+        event.
+
+        When the seat has the keyboard capability the text-input focus follows
+        the keyboard focus.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </event>
+
+    <event name="preedit_string">
+      <description summary="pre-edit">
+        Notify when a new composing text (pre-edit) should be set at the
+        current cursor position. Any previously set composing text must be
+        removed. Any previously existing selected text must be removed.
+
+        The argument text contains the pre-edit string buffer.
+
+        The parameters cursor_begin and cursor_end are counted in bytes
+        relative to the beginning of the submitted text buffer. Cursor should
+        be hidden when both are equal to -1.
+
+        They could be represented by the client as a line if both values are
+        the same, or as a text highlight otherwise.
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next xx_text_input_v3.done event.
+
+        The initial value of text is an empty string, and cursor_begin,
+        cursor_end and cursor_hidden are all 0.
+      </description>
+      <arg name="text" type="string" allow-null="true"/>
+      <arg name="cursor_begin" type="int"/>
+      <arg name="cursor_end" type="int"/>
+    </event>
+
+    <event name="commit_string">
+      <description summary="text commit">
+        Notify when text should be inserted into the editor widget. The text to
+        commit could be either just a single character after a key press or the
+        result of some composing (pre-edit).
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next xx_text_input_v3.done event.
+
+        The initial value of text is an empty string.
+      </description>
+      <arg name="text" type="string" allow-null="true"/>
+    </event>
+
+    <event name="delete_surrounding_text">
+      <description summary="delete surrounding text">
+        Notify when the text around the current cursor position should be
+        deleted.
+
+        Before_length and after_length are the number of bytes before and after
+        the current cursor index (excluding the selection) to delete.
+        
+        If text is selected, it must be deleted.
+
+        If indices exceed the available text boundaries, they should be adjusted to fit in boundaries and deletion reattempted.
+        If indices do not lie on byte boundaries, then the text input client should delete at least that many bytes. In this case, the client decides the end point, but a character boundary same as when deleting using the keyboard is recommended.
+
+        If a preedit text is present, in effect before_length is counted from
+        the beginning of it, and after_length from its end (see done event
+        sequence).
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next xx_text_input_v3.done event.
+
+        The initial values of both before_length and after_length are 0.
+      </description>
+      <arg name="before_length" type="uint" summary="length of text before current cursor position"/>
+      <arg name="after_length" type="uint" summary="length of text after current cursor position"/>
+    </event>
+
+    <event name="move_cursor" since="2">
+      <description summary="move cursor and change selection">
+        Unselects text, moves the cursor and selects text.
+
+        This is equivalent to dragging the mouse over some text: it deselects whatever might be currently selected and selects a new range of text.
+
+        The offsets used in arguments are in bytes relative to the current cursor position. Cursor is the new position of the cursor, and anchor is the opposite end of selection. If there's no selection, anchor should be equal to cursor.
+        In terms of dragging the mouse, the anchor is the start, and cursor the end.
+        
+        The offsets do not take preedit contents into account, nor is preedit changed in any way with this request.
+        
+        Both cursor and anchor must fall on code point boundaries, otherwise text input client may ignore the request. It is therefore not recommended for an input method to move any of them beyond the text received in surrounding_text.
+        <!-- Code point boundary checking must happen in the application because no one else is obliged to track the contents.
+        There are two ways to handle it:
+        
+        1. add a request from the application informing the compositor of the mistake, so that the compositor can send an error and crash the input method, giving it the chance to reset and go back to normal
+        2. just ignore the request and hope the input method can resynchronize through surrounding_text
+        
+        Choosing 2. because it's easier to implement.
+        -->
+
+        When surrounding_text is not supported, the offsets must not be interpreted as bytes, but as some human-readable unit at least as big as a code point, for example a grapheme.
+        
+        The cursor and anchor arguments can also take the following special values:
+        BEGINNING := 0x8000_0000 = i32::MIN
+        END := 0x7fff_ffff = i32::MAX
+        meaning, respectively, the beginning and the end of of all text in the input field.
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next commit request.
+
+        The initial values of both cursor and anchor are 0.
+      </description>
+      <arg name="cursor" type="int"/>
+      <arg name="anchor" type="int"/>
+    </event>
+    
+    <event name="done">
+      <description summary="apply changes">
+        Instruct the application to apply changes to state requested by the
+        preedit_string, commit_string delete_surrounding_text, and action
+        events.
+        The state relating to these events is double-buffered, and each one
+        modifies the pending state. This event replaces the current state with
+        the pending state.
+
+        The application must proceed by evaluating the changes in the following
+        order:
+
+        1. Replace existing preedit string with the cursor.
+        2. Delete requested surrounding text.
+        3. Insert commit string with the cursor at its end.
+        4. Move the cursor and selection.
+        5. Calculate surrounding text to send.
+        6. Insert new preedit text in cursor position.
+        7. Place cursor inside preedit text.
+        8. Perform the requested action.
+
+        Serial handling starting version 2:
+        
+        The argument "serial" is ignored.
+
+        Serial handling version 1:
+        
+        The serial number reflects the last state of the xx_text_input_v3
+        object known to the compositor. The value of the serial argument must
+        be equal to the number of commit requests already issued on that object.
+
+        When the client receives a done event with a serial different than the
+        number of past commit requests, it must proceed with evaluating and
+        applying the changes as normal, except it should not change the current
+        state of the xx_text_input_v3 object. All pending state requests
+        (set_surrounding_text, set_content_type and set_cursor_rectangle) on
+        the xx_text_input_v3 object should be sent and committed after
+        receiving a xx_text_input_v3.done event with a matching serial.
+      </description>
+      <arg name="serial" type="uint"/>
+    </event>
+
+    <enum name="action" since="2">
+      <description summary="action">
+        A possible action to perform on a text input.
+      </description>
+      <entry name="none" value="1">
+        <description summary="no action">
+          This enum value exists only to provide a default to make double-buffering implementation easier. It should not be used explicitly.
+        </description>
+      </entry>
+      <!-- Notably missing: moving cursor, deleting and setting a selection. They are nicer to use as part of the text manipulation interface: ranges can be selected there.
+      Exceptions: the IME doesn't know where lines start or end. The IME will not get to see the entire 4MB document so it can't select all through the text interface. But this doesn't seem urgent. -->
+
+      <!-- types of finish actions are better communicated as a hint: this triggers a URL navigation, this sends a search query, this sends a message, etc. The input method can then choose the appropriate buttons to display -->
+      <entry name="finish" value="0">
+        <description summary="trigger appropriate action for the completion of editing">
+          This should be triggered when the user is done with editing the field and wants to move on. For example, the query was typed and the user wants the search result. Or the name was entered and the address needs to be typed next.
+
+          The action to perform depends on the application, and should match the value of the current content_purpose.
+
+          All clients SHOULD implement this action. Without it, on-screen keyboards don't work as expected.
+        </description>
+      </entry>
+    </enum>
+    
+    <event name="perform_action" since="2">
+      <description summary="action performed">
+        The input method issued an action to perform on this text input.
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next .done event.
+
+        The initial value of action is none.
+      </description>
+      <arg name="action" type="uint" enum="action" summary="action performed"/>
+    </event>
+
+    <request name="set_available_actions" since="2">
+      <description summary="announce the available actions">
+        Announces the actions available for the currently active text input.
+
+        Values set with this event are double-buffered. They will get applied
+        on the next .done event.
+        They get reset to the initial value on the next committed deactivate event.
+
+        The initial value is an empty set: no actions are available.
+        
+        Values in the available_actions array come from text-input-v3.action.
+      </description>
+      <!-- Removed the protocol error on none and duplicates because a client has no interest in crashing for slight compositor misbehaviour. Ignoring extraneous values should not be a problem for any half-competent library. -->
+      <arg name="available_actions" type="array" summary="available actions"/>
+      <!-- Should this be a bitmap instead of an array? 32 generic actions should be enough, and client-specific actions would need a new protocol anyway -->
+    </request>
+    
+    <enum name="supported_features" bitfield="true" since="2">
+      <description summary="possible supported features">
+        Client functionality over the baseline that isn't indicated implicitly.
+
+        This does not include events coming with .enable: when the input method receives such an event, it is clear the text input supports it, e.g. content_type, available_actions.
+
+        Baseline functionality like commit_string, set_preedit_string must always be supported for the protocol to be useful.
+        
+        The flags match text-input protocol versions, but should be kept general enough to support other protocols.
+      </description>
+      <entry name="none" value="0x0" summary="no extra functionality supported"/>
+      <entry name="move_cursor" value="0x1" summary="the move_cursor request"/>
+    </enum>
+    
+    <request name="announce_supported_features" since="2">
+      <description summary="announce extra supported features">
+        Notifies the input method what the currently active text input client is able to do.
+
+        This event should come within the same .done sequence as .activate. Otherwise, the input method may ignore it.
+        
+        Values set with this event are double-buffered. They will get applied
+        on the next .done event.
+        They get reset to initial on the next committed deactivate event.
+
+        The initial value for features is none.
+      </description>
+      <arg name="features" type="uint" enum="xx_text_input_v3.supported_features"/>
+    </request>
+  </interface>
+
+  <interface name="xx_text_input_manager_v3" version="3">
+    <description summary="text input manager">
+      A factory for text-input objects. This object is a global singleton.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the xx_text_input_manager">
+        Destroy the xx_text_input_manager object.
+      </description>
+    </request>
+
+    <request name="get_text_input">
+      <description summary="create a new text input object">
+        Creates a new text-input object for a given seat.
+      </description>
+      <arg name="id" type="new_id" interface="xx_text_input_v3"/>
+      <arg name="seat" type="object" interface="wl_seat"/>
+    </request>
+  </interface>
+</protocol>

experimental/xx-zones/README

@@ -0,0 +1,4 @@
+Zones protocol
+
+Maintainers:
+Matthias Klumpp <matthias@tenstral.net> (@mak)

experimental/xx-zones/xx-zones-v1.xml

@@ -0,0 +1,493 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xx_zones_v1">
+
+  <copyright>
+    Copyright © 2023-2026 Matthias Klumpp
+    Copyright © 2024-2025 Frank Praznik
+    Copyright ©      2024 Victoria Brekenfeld
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="protocol to manage client-specific zones for explicit window placement">
+    This protocol provides a way for clients to create and add toplevel windows
+    to "zones".
+
+    A zone is an environment with its own coordinate space where clients can
+    add and arrange windows that logically belong and relate to each other.
+    It provides means for, among other things, requesting that windows are
+    placed at specific coordinates within the zone coordinate space.
+    See the description of "xx_zone_v1" for more details.
+
+    This document adheres to RFC 2119 when using words like "must",
+    "should", "may", etc.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="xx_zone_manager_v1" version="1">
+    <description summary="manage zones for clients">
+      The 'xx_zone_manager' interface defines base requests for obtaining and
+      managing zones for a client.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy this object">
+       This has no effect other than to destroy the xx_zone_manager object.
+      </description>
+    </request>
+
+    <request name="get_zone_item">
+      <description summary="create a positionable item representing a toplevel">
+        Create a new positionable zone item from an 'xdg_toplevel'.
+        The resulting wrapper object can then be used to position the
+        toplevel window in a zone.
+      </description>
+      <arg name="id" type="new_id" interface="xx_zone_item_v1"/>
+      <arg name="toplevel" type="object" interface="xdg_toplevel" summary="the toplevel window"/>
+    </request>
+
+    <request name="get_zone">
+      <description summary="join a zone or request a new one">
+        Create a new zone. While the zone object exists, the compositor
+        must consider it "used" and keep track of it.
+
+        A zone is represented by a string 'handle'.
+
+        The compositor must keep zone handles valid while any client is
+        referencing the corresponding zone.
+        The compositor may always give a client the same zone for a given
+        output, and remember its position and size for the client, but
+        clients should not rely on this behavior.
+
+        A client can request a zone to be placed on a specific
+        output by passing a wl_output as 'output'. If a valid output
+        is set, the compositor should place the zone on that output.
+        If NULL is passed, the compositor decides the output.
+
+        The compositor should provide the biggest reasonable zone space
+        for the client, governed by its own policy.
+
+        If the compositor wants to deny zone creation (e.g. on a specific
+        output), the returned zone must be "invalid". A zone is invalid
+        if it has a negative size, in which case the client is forbidden
+        to place items in it.
+      </description>
+      <arg name="id" type="new_id" interface="xx_zone_v1"/>
+      <arg name="output" type="object" interface="wl_output"
+           summary="the preferred output to place the zone on, or NULL"
+           allow-null="true"/>
+    </request>
+
+    <request name="get_zone_from_handle">
+      <description summary="join a zone via its handle">
+        Create a new zone object using the zone's handle.
+        For the returned zone, the same rules as described in
+        'get_zone' apply.
+
+        This request returns a reference to an existing or remembered zone
+        that is represented by 'handle'.
+        The zone may potentially have been created by a different client.
+
+        This allows cooperating clients to share the same coordinate space.
+
+        If the zone handle was invalid or unknown, a new zone must
+        be created and returned instead, following the rules outlined
+        in 'get_zone' and assuming no output preference.
+
+        Every new zone object created by this request emits its initial event
+        sequence, including the 'handle' event, which must return a different
+        handle from the one passed to this request in case the existing zone
+        could not be joined.
+      </description>
+      <arg name="id" type="new_id" interface="xx_zone_v1"/>
+      <arg name="handle" type="string" summary="the handle of a zone"/>
+    </request>
+  </interface>
+
+  <interface name="xx_zone_item_v1" version="1">
+    <description summary="opaque surface object that can be positioned in a zone">
+      The zone item object is an opaque descriptor for a positionable
+      element, such as a toplevel window.
+      It currently can only be created from an 'xdg_toplevel' via the
+      'get_zone_item' request on a 'xx_zone_manager'.
+
+      The lifetime of a zone item is tied to its referenced item (usually
+      a toplevel).
+      When the reference is destroyed, the compositor must send a 'closed'
+      event and the zone item becomes inert.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object">
+        Destroys the zone item. This request may be sent at any time by the
+        client.
+        By destroying the object, the respective item surface remains at its
+        last position, but its association with its zone is lost.
+        This will also cause it to lose any other attached state described by
+        this protocol.
+
+        If the item was associated with a zone when this request is sent,
+        the compositor must emit 'item_left' on the respective zone, unless
+        it had already been emitted before a 'closed' event.
+      </description>
+    </request>
+
+    <event name="frame_extents">
+      <description summary="the extents of the frame bordering the item">
+        The 'frame_extents' event describes the current extents of the frame
+        bordering the item's content area.
+
+        This event is sent immediately after the item joins a zone, or if
+        the item frame extents have been changed by other means (e.g. toggled
+        by a client request, or compositor involvement). The dimensions are in
+        the same coordinate space as the item's zone (the surface coordinate
+        space).
+
+        This event must be followed by a 'position' event, even if the item's
+        coordinates did not change as a result of the frame extents changing.
+
+        If the item has no associated frame, the event should still be sent,
+        but extents must be set to zero.
+
+        This event can only be emitted if the item is currently associated
+        with a zone.
+      </description>
+      <arg name="top" type="int" summary="current height of the frame bordering the top of the item"/>
+      <arg name="bottom" type="int" summary="current height of the frame bordering the bottom of the item"/>
+      <arg name="left" type="int" summary="current width of the frame bordering the left of the item"/>
+      <arg name="right" type="int" summary="current width of the frame bordering the right of the item"/>
+    </event>
+
+    <request name="set_position">
+      <description summary="set a preferred item surface position">
+        Request a preferred position (x, y) for the specified item
+        surface to be placed at, relative to its associated zone.
+        This state is double-buffered and is applied on the next
+        wl_surface.commit of the surface represented by 'item'.
+
+        X and Y coordinates are relative to the zone this item is associated
+        with, and must not be larger than the dimensions set by the zone size.
+        They may be smaller than zero, if the item's top-left edge is to be
+        placed beyond the zone's top-left sides, but clients should expect the
+        compositor to more aggressively sanitize the coordinate values in that
+        case.
+        If a coordinate exceeds the zone's maximum bounds, the compositor must
+        sanitize it to more appropriate values (e.g. by clamping the values to
+        the maximum size).
+        For infinite zones, the client may pick any coordinate.
+
+        Compositors implementing this protocol should try to place an item
+        at the requested coordinates relative to the item's zone, unless doing
+        so is not allowed by compositor policy (because e.g. the user has set
+        custom rules for the surface represented by the respective item, the
+        surface overlaps with a protected shell component, session management
+        has loaded previous surface positions or the placement request would
+        send the item out of bounds).
+
+        Clients should be aware that their placement preferences might not
+        always be followed and must be prepared to handle the case where the
+        item is placed at a different position by the compositor.
+
+        Once an item has been mapped, a change to its preferred placement can
+        still be requested and should be applied, but must not be followed
+        by the compositor while the user is interacting with the affected item
+        surface (e.g. clicking &amp; dragging within the window, or resizing it).
+
+        After a call to this request, a 'position' event must be emitted with the
+        item's new actual position.
+        If the current item has no zone associated with it, a 'position_failed'
+        event must be emitted.
+        If the compositor did not move the item at all, not even with sanitized
+        values, a 'position_failed' event must be emitted as well.
+      </description>
+      <arg name="x" type="int" summary="x position relative to zone"/>
+      <arg name="y" type="int" summary="y position relative to zone"/>
+    </request>
+
+    <event name="position">
+      <description summary="notify about the position of an item">
+        This event notifies the client of the current position (x, y) of
+        the item relative to its zone.
+        Coordinates are relative to the zone this item belongs to, and only
+        valid within it.
+        Negative coordinates are possible, if the user has moved an item
+        surface beyond the zone's top-left boundary.
+
+        This event is sent in response to a 'set_position' request,
+        or if the item position has been changed by other means
+        (e.g. user interaction or compositor involvement).
+
+        This event can only be emitted if the item is currently associated
+        with a zone.
+      </description>
+      <arg name="x" type="int" summary="current x position relative to zone"/>
+      <arg name="y" type="int" summary="current y position relative to zone"/>
+    </event>
+
+    <event name="position_failed">
+      <description summary="a set_position request has failed">
+        The compositor was unable to set the position of this item entirely,
+        and could not even find sanitized coordinates to place the item at
+        instead.
+
+        This event will also be emitted if 'set_position' was called while the
+        item had no zone associated with it.
+      </description>
+    </event>
+
+    <event name="closed">
+      <description summary="the underlying surface has been destroyed">
+        This event indicates that the surface wrapped by this
+        zone item has been destroyed.
+
+        The 'xx_zone_item_v1' object becomes inert and the client should
+        destroy it. Any requests made on an inert zone item must be silently
+        ignored by the compositor, and no further events will be sent for this
+        item.
+
+        If the item was associated with a zone when this event is sent,
+        the compositor must also emit 'item_left' on the respective zone
+        before sending this event.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="xx_zone_v1" version="1">
+    <description summary="area for a client in which it can set window positioning preferences">
+      An 'xx_zone' describes a display area provided by the compositor in
+      which a client can place windows and move them around.
+
+      A zone's area could, for example, correspond to the space usable for
+      placing windows on a specific output (space without panels or other
+      restricted elements) or it could be an area of the output the compositor
+      has specifically chosen for a client to place its surfaces in.
+
+      Clients should make no assumptions about how a zone is presented to the
+      user (e.g. compositors may visually distinguish what makes up a zone).
+
+      Items are added to a zone as 'xx_zone_item' objects.
+
+      All item surface position coordinates (x, y) are relative to the selected
+      zone.
+      They are using the 'size' of the respective zone as coordinate system,
+      with (0, 0) being in the top left corner.
+
+      If a zone item is moved out of the top/left boundaries of the zone by
+      user interaction, its coordinates must become negative, relative to the
+      zone's top-left coordinate origin. A client may position an item at negative
+      coordinates.
+
+      The compositor must ensure that any item positioned by the client is
+      visible and accessible to the user, and is not moved into invisible space
+      outside of a zone.
+      Positioning requests may be rejected or altered by the compositor, depending
+      on its policy.
+
+      The absolute position of the zone within the compositor's coordinate space
+      is opaque to the client and the compositor may move the entire zone without
+      the client noticing it. A zone may also be arbitrarily resized, in which
+      case the respective 'size' event must be emitted again to notify the client.
+
+      A zone is always tied to an output and does not extend beyond it.
+
+      A zone may be "invalid". An invalid zone is created with a negative
+      'size' and must not be used for item arrangement.
+
+      Upon creation the compositor must emit 'size' and 'handle' events for the
+      newly created 'xx_zone', followed by 'done'.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the xx_zone object">
+        Using this request a client can tell the compositor that it is not
+        going to use the 'xx_zone' object anymore.
+        The zone itself must only be destroyed if no other client
+        is currently referencing it, so this request may only destroy the
+        object reference owned by the client.
+      </description>
+    </request>
+
+    <event name="size">
+      <description summary="size of the zone">
+        The 'size' event describes the size of this zone.
+
+        It is a rectangle with its origin in the top-left corner, using
+        the surface coordinate space (device pixels divided by the scaling
+        factor of the output this zone is attached to).
+
+        If a width or height value is zero, the zone is infinite
+        in that direction.
+
+        If the width and height values are negative, the zone is considered
+        "invalid" and must not be used.
+        A size event declaring the zone invalid may only be emitted immediately
+        after the zone was created.
+        A zone must not become invalid at a later time by sending a negative
+        'size' after the zone has been established.
+
+        The 'size' event is sent immediately after creating an 'xx_zone_v1',
+        and whenever the size of the zone changes. A zone size can change at
+        any time, for any reason, for example due to output size or scaling
+        changes, or by compositor policy.
+
+        Upon subsequent emissions of 'size' after 'xx_zone' has already
+        been created, the 'done' event does not have to be sent again.
+      </description>
+      <arg name="width" type="int"
+           summary="zone width in logical pixels"/>
+      <arg name="height" type="int"
+           summary="zone height in logical pixels"/>
+    </event>
+
+    <event name="handle">
+      <description summary="the zone handle">
+        The handle event provides the unique handle of this zone.
+        The handle may be shared with any client, which then can use it to
+        join this client's zone by calling
+        'xx_zone_manager.get_zone_from_handle'.
+
+        This event must only be emitted once after the zone was created.
+        If this zone is invalid, the handle must be an empty string.
+      </description>
+      <arg name="handle" type="string" summary="the exported zone handle"/>
+    </event>
+
+    <event name="done">
+      <description summary="all information about the zone has been sent">
+        This event is sent after all other properties (size, handle) of an
+        'xx_zone' have been sent.
+
+        This allows changes to the xx_zone properties to be seen as
+        atomic, even if they happen via multiple events.
+      </description>
+    </event>
+
+    <enum name="error">
+      <entry name="invalid" summary="an invalid value has been submitted"
+             value="0"/>
+    </enum>
+
+    <request name="add_item">
+      <description summary="associate an item with this zone">
+        Make 'item' a member of this zone.
+        This state is double-buffered and is applied on the next
+        'wl_surface.commit' of the surface represented by 'item'.
+
+        This request associates an item with this zone.
+        If this request is called on an item that already has a zone
+        association with a different zone, the item must leave its old zone
+        (with 'item_left' being emitted on its old zone) and will instead
+        be associated with this zone.
+
+        Upon receiving this request and if the target zone is allowed for 'item',
+        a compositor must emit 'item_entered' to confirm the zone association.
+        It must even emit this event if the item was already associated with this
+        zone before.
+
+        The compositor must move the surface represented by 'item' into the
+        boundary of this zone upon receiving this request and accepting it
+        (either by extending the zone size, or by moving the item surface).
+
+        If the compositor does not allow the item to switch zone associations,
+        and wants it to remain in its previous zone, it must emit
+        'item_blocked' instead.
+        Compositors might want to prevent zone associations if they
+        perform specialized window management (e.g. autotiling) that would
+        make clients moving items between certain zones undesirable.
+
+        Once the 'item' is added to its zone, the compositor must first send
+        a 'frame_extents' event on the item, followed by an initial 'position'
+        event with the item's current position.
+        The compositor must then send 'position' events when the position
+        of the item in its zone is changed, for as long as the item is
+        associated with a zone.
+
+        If the zone is invalid, an 'invalid' error must be raised and the item
+        must not be associated with the invalid zone.
+        If the referenced item is inert (its underlying surface has been
+        destroyed), the request must be silently ignored.
+      </description>
+      <arg name="item" type="object" interface="xx_zone_item_v1" summary="the zone item"/>
+    </request>
+
+    <request name="remove_item">
+      <description summary="disassociate an item from this zone">
+        Remove 'item' as a member of this zone.
+        This state is double-buffered and is applied on the next
+        'wl_surface.commit' of the surface represented by 'item'.
+
+        This request removes the item from this zone explicitly,
+        making the client unable to retrieve coordinates again.
+
+        Upon receiving this request, the compositor should not change the
+        item surface position on screen, and must emit 'item_left' to confirm
+        the item's removal. It must even emit this event if the
+        item was never associated with this zone.
+
+        If the referenced item is inert (its underlying surface has been
+        destroyed), the request must be silently ignored.
+      </description>
+      <arg name="item" type="object" interface="xx_zone_item_v1" summary="the zone item"/>
+    </request>
+
+    <event name="item_blocked">
+      <description summary="an item could not be associated with this zone">
+        This event notifies the client that an item was prevented from
+        joining this zone.
+
+        It is emitted as a response to 'add_item' if the compositor did not
+        allow the item to join this particular zone.
+      </description>
+      <arg name="item" type="object" interface="xx_zone_item_v1" summary="the item that was prevented from joining this zone"/>
+    </event>
+
+    <event name="item_entered">
+      <description summary="notify about an item having joined this zone">
+        This event notifies the client of an item joining this zone.
+
+        It is emitted as a response to 'add_item' or if the compositor
+        automatically had the item surface (re)join an existing zone.
+      </description>
+      <arg name="item" type="object" interface="xx_zone_item_v1" summary="the item that has joined the zone"/>
+    </event>
+
+    <event name="item_left">
+      <description summary="notify about an item having left this zone">
+        This event notifies the client of an item leaving this zone, and
+        therefore the client will no longer receive updated coordinates
+        or frame extents for this item.
+        If the client still wishes to adjust the item surface coordinates, it
+        may associate the item with a zone again by calling 'add_item'.
+
+        This event is emitted for example if the user moved an item surface out
+        of a smaller zone's boundaries, or onto a different screen where the
+        previous zone can not expand to. It is also emitted in response to
+        explicitly removing an item via 'remove_item'.
+      </description>
+      <arg name="item" type="object" interface="xx_zone_item_v1" summary="the item that has left the zone"/>
+    </event>
+
+  </interface>
+
+</protocol>

include/wayland-protocols/meson.build

@@ -0,0 +1,18 @@
+header_install_dir = get_option('includedir') / 'wayland-protocols'
+foreach protocol_file : protocol_files
+	header_name = fs.name(protocol_file).replace('.xml', '-enum.h')
+	headers += custom_target(
+		header_name,
+		output: header_name,
+		input: '../..' / protocol_file,
+		command: [
+			prog_scanner,
+			'--strict',
+			'enum-header',
+			'@INPUT@',
+			'@OUTPUT@',
+		],
+		install: true,
+		install_dir: header_install_dir,
+	)
+endforeach

meson.build

@@ -0,0 +1,218 @@
+project('wayland-protocols',
+	version: '1.48',
+	meson_version: '>= 0.58.0',
+	license: 'MIT/Expat',
+)
+
+wayland_protocols_version = meson.project_version()
+
+fs = import('fs')
+
+dep_scanner = dependency('wayland-scanner',
+    version: get_option('tests') ? '>=1.25.0' : '>=1.20.0',
+    native: true,
+    fallback: 'wayland'
+)
+prog_scanner = find_program(dep_scanner.get_variable(pkgconfig: 'wayland_scanner', internal: 'wayland_scanner'))
+
+stable_protocols = {
+	'linux-dmabuf': {'v1': []},
+	'presentation-time': {'': []},
+	'tablet': {'v2': []},
+	'viewporter': {'': []},
+	'xdg-shell': {'': []},
+}
+
+unstable_protocols = {
+	'fullscreen-shell': {'v1': []},
+	'idle-inhibit': {'v1': []},
+	'input-method': {'v1': []},
+	'input-timestamps': {'v1': []},
+	'keyboard-shortcuts-inhibit': {'v1': []},
+	'linux-dmabuf': {'v1': []},
+	'linux-explicit-synchronization': {'v1': []},
+	'pointer-constraints': {'v1': []},
+	'pointer-gestures': {'v1': []},
+	'primary-selection': {'v1': []},
+	'relative-pointer': {'v1': []},
+	'tablet': {'v1': [], 'v2': []},
+	'text-input': {'v1': [], 'v3': []},
+	'xdg-decoration': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+	'xdg-foreign': {'v1': [], 'v2': []},
+	'xdg-output': {'v1': []},
+	'xdg-shell': {'v5': [], 'v6': []},
+	'xwayland-keyboard-grab': {'v1': []},
+}
+
+staging_protocols = {
+	'alpha-modifier': {'v1': []},
+	'color-management': {'v1': []},
+	'color-representation': {'v1': []},
+	'commit-timing': {'v1': []},
+	'content-type': {'v1': []},
+	'cursor-shape': {'v1': ['stable/tablet/tablet-v2.xml']},
+	'drm-lease': {'v1': []},
+	'ext-background-effect': {'v1': []},
+	'ext-data-control': {'v1': []},
+	'ext-foreign-toplevel-list': {'v1': []},
+	'ext-idle-notify': {'v1': []},
+	'ext-image-capture-source': {'v1': [
+		'staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml',
+	]},
+	'ext-image-copy-capture': {'v1': [
+		'staging/ext-image-capture-source/ext-image-capture-source-v1.xml',
+		'staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml',
+	]},
+	'ext-session-lock': {'v1': []},
+	'ext-transient-seat': {'v1': []},
+	'ext-workspace': {'v1': []},
+	'fifo': {'v1': []},
+	'fractional-scale': {'v1': []},
+	'linux-drm-syncobj': {'v1': []},
+	'pointer-warp': {'v1': []},
+	'security-context': {'v1': []},
+	'single-pixel-buffer': {'v1': []},
+	'tearing-control': {'v1': []},
+	'xdg-activation': {'v1': []},
+	'xdg-dialog': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+	'xdg-session-management': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+	'xdg-system-bell': {'v1': []},
+	'xdg-toplevel-drag': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+	'xdg-toplevel-icon': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+	'xdg-toplevel-tag': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+	'xwayland-shell': {'v1': []},
+}
+
+experimental_protocols = {
+	'xx-cutouts': {'v1': []},
+	'xx-input-method': {'v2': []},
+	'xx-keyboard-filter': {'v1': [
+		'experimental/xx-input-method/xx-input-method-v2.xml',
+	]},
+	'xx-session-management': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+	'xx-text-input': {'v3': []},
+	'xx-zones': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
+}
+
+protocol_files = []
+installed_protocol_files = []
+protocol_deps = {}
+
+stable_protocol_files = []
+foreach name, versions : stable_protocols
+	foreach version, deps : versions
+		if version == ''
+			protocol_file = 'stable/@0@/@0@.xml'.format(name)
+		else
+			protocol_file = 'stable/@0@/@0@-@1@.xml'.format(name, version)
+		endif
+		stable_protocol_files += [protocol_file]
+		if deps.length() > 0
+			protocol_deps += {protocol_file: deps}
+		endif
+	endforeach
+endforeach
+installed_protocol_files += stable_protocol_files
+protocol_files += stable_protocol_files
+
+staging_protocol_files = []
+foreach name, versions : staging_protocols
+	foreach version, deps : versions
+		protocol_file = 'staging/@0@/@0@-@1@.xml'.format(name, version)
+		staging_protocol_files += [protocol_file]
+		if deps.length() > 0
+			protocol_deps += {protocol_file: deps}
+		endif
+	endforeach
+endforeach
+installed_protocol_files += staging_protocol_files
+protocol_files += staging_protocol_files
+
+unstable_protocol_files = []
+foreach name, versions : unstable_protocols
+	foreach version, deps : versions
+		protocol_file = 'unstable/@0@/@0@-unstable-@1@.xml'.format(name, version)
+		unstable_protocol_files += [protocol_file]
+		if deps.length() > 0
+			protocol_deps += {protocol_file: deps}
+		endif
+	endforeach
+endforeach
+installed_protocol_files += unstable_protocol_files
+protocol_files += unstable_protocol_files
+
+experimental_protocol_files = []
+foreach name, versions : experimental_protocols
+	foreach version, deps : versions
+		protocol_file = 'experimental/@0@/@0@-@1@.xml'.format(name, version)
+		experimental_protocol_files += [protocol_file]
+		if deps.length() > 0
+			protocol_deps += {protocol_file: deps}
+		endif
+	endforeach
+endforeach
+protocol_files += experimental_protocol_files
+
+# Check that each protocol has a README
+foreach protocol_file : protocol_files
+	dir = fs.parent(protocol_file)
+	if not fs.is_file(dir + '/README')
+		error('Missing README in @0@'.format(protocol_file))
+	endif
+endforeach
+
+foreach protocol_file : installed_protocol_files
+	protocol_install_dir = fs.parent(join_paths(
+		get_option('datadir'),
+		'wayland-protocols',
+		protocol_file,
+	))
+	install_data(
+		protocol_file,
+		install_dir: protocol_install_dir,
+	)
+endforeach
+
+include_dirs = []
+headers = []
+if dep_scanner.version().version_compare('>=1.22.90')
+	subdir('include/wayland-protocols')
+	include_dirs = ['include']
+endif
+
+pkgconfig = import('pkgconfig')
+
+pkgconfig.generate(
+	filebase: 'wayland-protocols',
+	name: 'Wayland Protocols',
+	description: 'Wayland protocol files',
+	dataonly: true,
+	variables: {
+		'prefix': get_option('prefix'),
+		'includedir': '${prefix}/@0@'.format(get_option('includedir')),
+		'datarootdir': '${prefix}/@0@'.format(get_option('datadir')),
+		'pkgdatadir': '${pc_sysrootdir}${datarootdir}/wayland-protocols'
+	},
+	uninstalled_variables: {
+		'includedir': meson.current_build_dir() / 'include',
+		'pkgdatadir': meson.project_source_root(),
+	},
+)
+
+wayland_protocols = declare_dependency(
+	include_directories: include_dirs,
+	variables: {
+		'pkgdatadir': meson.project_source_root(),
+	},
+	sources: headers,
+)
+
+meson.override_dependency('wayland-protocols', wayland_protocols)
+
+if get_option('tests')
+	subdir('tests')
+endif
+
+summary({
+	'Headers': include_dirs.length() > 0,
+}, bool_yn: true)

meson_options.txt

@@ -0,0 +1,4 @@
+option('tests',
+       type: 'boolean',
+       value: true,
+       description: 'Build the tests')

stable/linux-dmabuf/README

@@ -0,0 +1,5 @@
+Linux DMA-BUF protocol
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen@collabora.co.uk> (@pq)
+Daniel Stone <daniels@collabora.com> (@daniels)

stable/linux-dmabuf/feedback.rst

@@ -0,0 +1,218 @@
+.. Copyright 2021 Simon Ser
+
+.. contents::
+
+
+linux-dmabuf feedback introduction
+==================================
+
+linux-dmabuf feedback allows compositors and clients to negotiate optimal buffer
+allocation parameters. This document will assume that the compositor is using a
+rendering API such as OpenGL or Vulkan and KMS as the presentation API: even if
+linux-dmabuf feedback isn't restricted to this use-case, it's the most common.
+
+linux-dmabuf feedback introduces the following concepts:
+
+1. A main device. This is the render device that the compositor is using to
+   perform composition. Compositors should always be able to display a buffer
+   submitted by a client, so this device can be used as a fallback in case none
+   of the more optimized code-paths work. Clients should allocate buffers such
+   that they can be imported and textured from the main device.
+
+2. One or more tranches. Each tranche consists of a target device, allocation
+   flags and a set of format/modifier pairs. A tranche can be seen as a set of
+   formats/modifier pairs that are compatible with the target device.
+
+   A tranche can have the ``scanout`` flag. It means that the target device is
+   a KMS device, and that buffers allocated with one of the format/modifier
+   pairs in the tranche are eligible for direct scanout.
+
+   Clients should use the tranches in order to allocate buffers with the most
+   appropriate format/modifier and also to avoid allocating in private device
+   memory when cross-device operations are going to happen.
+
+linux-dmabuf feedback implementation notes
+==========================================
+
+This section contains recommendations for client and compositor implementations.
+
+For clients
+-----------
+
+Clients are expected to either pick a fixed DRM format beforehand, or
+perform the following steps repeatedly until they find a suitable format.
+
+Basic clients may only support static buffer allocation on startup. These
+clients should do the following:
+
+1. Send a ``get_default_feedback`` request to get global feedback.
+2. Select the device indicated by ``main_device`` for allocation.
+3. For each tranche:
+
+   1. If ``tranche_target_device`` doesn't match the allocation device, ignore
+      the tranche.
+   2. Accumulate allocation flags from ``tranche_flags``.
+   3. Accumulate format/modifier pairs received via ``tranche_formats`` in a
+      list.
+   4. When the ``tranche_done`` event is received, try to allocate the buffer
+      with the accumulated list of modifiers and allocation flags. If that
+      fails, proceed with the next tranche. If that succeeds, stop the loop.
+
+4. Destroy the feedback object.
+
+Tranches are ordered by preference: the more optimized tranches come first. As
+such, clients should use the first tranche that happens to work.
+
+Some clients may have already selected the device they want to use beforehand.
+These clients can ignore the ``main_device`` event, and ignore tranches whose
+``tranche_target_device`` doesn't match the selected device. Such clients need
+to be prepared for the ``wp_linux_buffer_params.create`` request to potentially
+fail.
+
+If the client allocates a buffer without specifying explicit modifiers on a
+device different from the one indicated by ``main_device``, then the client
+must force a linear layout.
+
+Some clients might support re-negotiating the buffer format/modifier on the
+fly. These clients should send a ``get_surface_feedback`` request and keep the
+feedback object alive after the initial allocation. Each time a new set of
+feedback parameters is received (ended by the ``done`` event), they should
+perform the same steps as basic clients described above. They should detect
+when the optimal allocation parameters didn't change (same
+format/modifier/flags) to avoid needlessly re-allocating their buffers.
+
+Some clients might additionally support switching the device used for
+allocations on the fly. Such clients should send a ``get_surface_feedback``
+request. For each tranche, select the device indicated by
+``tranche_target_device`` for allocation. Accumulate allocation flags (received
+via ``tranche_flags``) and format/modifier pairs (received via
+``tranche_formats``) as usual. When the ``tranche_done`` event is received, try
+to allocate the buffer with the accumulated list of modifiers and the
+allocation flags. Try to import the resulting buffer by sending a
+``wp_linux_buffer_params.create`` request (this might fail). Repeat with each
+tranche until an allocation and import succeeds. Each time a new set of
+feedback parameters is received, they should perform these steps again. They
+should detect when the optimal allocation parameters didn't change (same
+device/format/modifier/flags) to avoid needlessly re-allocating their buffers.
+
+For compositors
+---------------
+
+Basic compositors may only support texturing the DMA-BUFs via a rendering API
+such as OpenGL or Vulkan. Such compositors can send a single tranche as a reply
+to both ``get_default_feedback`` and ``get_surface_feedback``. Set the
+``main_device`` to the rendering device. Send the tranche with
+``tranche_target_device`` set to the rendering device and all of the DRM
+format/modifier pairs supported by the rendering API. Do not set the
+``scanout`` flag in the ``tranche_flags`` event.
+
+Some compositors may support direct scan-out for full-screen surfaces. These
+compositors can re-send the feedback parameters when a surface becomes
+full-screen or leaves full-screen mode if the client has used the
+``get_surface_feedback`` request. The non-full-screen feedback parameters are
+the same as basic compositors described above. The full-screen feedback
+parameters have two tranches: one with the format/modifier pairs supported by
+the KMS plane, with the ``scanout`` flag set in the ``tranche_flags`` event and
+with ``tranche_target_device`` set to the KMS scan-out device; the other with
+the rest of the format/modifier pairs (supported for texturing, but not for
+scan-out), without the ``scanout`` flag set in the ``tranche_flags`` event, and
+with the ``tranche_target_device`` set to the rendering device.
+
+Some compositors may support direct scan-out for all surfaces. These
+compositors can send two tranches for surfaces that become candidates for
+direct scan-out, similarly to compositors supporting direct scan-out for
+fullscreen surfaces. When a surface stops being a candidate for direct
+scan-out, compositors should re-send the feedback parameters optimized for
+texturing only.  The way candidates for direct scan-out are selected is
+compositor policy, a possible implementation is to select as many surfaces as
+there are available hardware planes, starting from surfaces closer to the eye.
+
+Some compositors may support multiple devices at the same time. If the
+compositor supports rendering with a fixed device and direct scan-out on a
+secondary device, it may send a separate tranche for surfaces displayed on
+the secondary device that are candidates for direct scan-out. The
+``tranche_target_device`` for this tranche will be the secondary device and
+will not match the ``main_device``.
+
+Some compositors may support switching their rendering device at runtime or
+changing their rendering device depending on the surface. When the rendering
+device changes for a surface, such compositors may re-send the feedback
+parameters with a different ``main_device``. However there is a risk that
+clients don't support switching their device at runtime and continue using the
+previous device. For this reason, compositors should always have a fallback
+rendering device that they initially send as ``main_device``, such that these
+clients use said fallback device.
+
+Compositors should not change the ``main_device`` on-the-fly when explicit
+modifiers are not supported, because there's a risk of importing buffers
+with an implicit non-linear modifier as a linear buffer, resulting in
+misinterpreted buffer contents.
+
+Compositors should not send feedback parameters if they don't have a fallback
+path. For instance, compositors shouldn't send a format/modifier supported for
+direct scan-out but not supported by the rendering API for texturing.
+
+Compositors can decide to use multiple tranches to describe the allocation
+parameters optimized for texturing. For example, if there are formats which
+have a fast texturing path and formats which have a slower texturing path, the
+compositor can decide to expose two separate tranches.
+
+Compositors can decide to use intermediate tranches to describe code-paths
+slower than direct scan-out but faster than texturing. For instance, a
+compositor could insert an intermediate tranche if it's possible to use a
+mem2mem device to convert buffers to be able to use scan-out.
+
+``dev_t`` encoding
+==================
+
+The protocol carries ``dev_t`` values on the wire using arrays. A compositor
+written in C can encode the values as follows:
+
+.. code-block:: c
+
+    struct stat drm_node_stat;
+    struct wl_array dev_array = {
+        .size = sizeof(drm_node_stat.st_rdev),
+        .data = &drm_node_stat.st_rdev,
+    };
+
+A client can decode the values as follows:
+
+.. code-block:: c
+
+    dev_t dev;
+    assert(dev_array->size == sizeof(dev));
+    memcpy(&dev, dev_array->data, sizeof(dev));
+
+Because two DRM nodes can refer to the same DRM device while having different
+``dev_t`` values, clients should use ``drmDevicesEqual`` to compare two
+devices.
+
+``format_table`` encoding
+=========================
+
+The ``format_table`` event carries a file descriptor containing a list of
+format + modifier pairs. The list is an array of pairs which can be accessed
+with this C structure definition:
+
+.. code-block:: c
+
+    struct dmabuf_format_modifier {
+        uint32_t format;
+        uint32_t pad; /* unused */
+        uint64_t modifier;
+    };
+
+Integration with other APIs
+===========================
+
+- libdrm: ``drmGetDeviceFromDevId`` returns a ``drmDevice`` from a device ID.
+- EGL: the `EGL_EXT_device_drm_render_node`_ extension may be used to query the
+  DRM device render node used by a given EGL display. When unavailable, the
+  older `EGL_EXT_device_drm`_ extension may be used as a fallback.
+- Vulkan: the `VK_EXT_physical_device_drm`_ extension may be used to query the
+  DRM device used by a given ``VkPhysicalDevice``.
+
+.. _EGL_EXT_device_drm: https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm.txt
+.. _EGL_EXT_device_drm_render_node: https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm_render_node.txt
+.. _VK_EXT_physical_device_drm: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_physical_device_drm.html

stable/linux-dmabuf/linux-dmabuf-v1.xml

@@ -0,0 +1,585 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="linux_dmabuf_v1">
+
+  <copyright>
+    Copyright © 2014, 2015 Collabora, Ltd.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="zwp_linux_dmabuf_v1" version="5">
+    <description summary="factory for creating dmabuf-based wl_buffers">
+      This interface offers ways to create generic dmabuf-based wl_buffers.
+
+      For more information about dmabuf, see:
+      https://www.kernel.org/doc/html/next/userspace-api/dma-buf-alloc-exchange.html
+
+      Clients can use the get_surface_feedback request to get dmabuf feedback
+      for a particular surface. If the client wants to retrieve feedback not
+      tied to a surface, they can use the get_default_feedback request.
+
+      The following are required from clients:
+
+      - Clients must ensure that either all data in the dma-buf is
+        coherent for all subsequent read access or that coherency is
+        correctly handled by the underlying kernel-side dma-buf
+        implementation.
+
+      - Don't make any more attachments after sending the buffer to the
+        compositor. Making more attachments later increases the risk of
+        the compositor not being able to use (re-import) an existing
+        dmabuf-based wl_buffer.
+
+      The underlying graphics stack must ensure the following:
+
+      - The dmabuf file descriptors relayed to the server will stay valid
+        for the whole lifetime of the wl_buffer. This means the server may
+        at any time use those fds to import the dmabuf into any kernel
+        sub-system that might accept it.
+
+      However, when the underlying graphics stack fails to deliver the
+      promise, because of e.g. a device hot-unplug which raises internal
+      errors, after the wl_buffer has been successfully created the
+      compositor must not raise protocol errors to the client when dmabuf
+      import later fails.
+
+      To create a wl_buffer from one or more dmabufs, a client creates a
+      zwp_linux_buffer_params_v1 object with a zwp_linux_dmabuf_v1.create_params
+      request. All planes required by the intended format are added with
+      the 'add' request. Finally, a 'create' or 'create_immed' request is
+      issued, which has the following outcome depending on the import success.
+
+      The 'create' request,
+      - on success, triggers a 'created' event which provides the final
+        wl_buffer to the client.
+      - on failure, triggers a 'failed' event to convey that the server
+        cannot use the dmabufs received from the client.
+
+      For the 'create_immed' request,
+      - on success, the server immediately imports the added dmabufs to
+        create a wl_buffer. No event is sent from the server in this case.
+      - on failure, the server can choose to either:
+        - terminate the client by raising a fatal error.
+        - mark the wl_buffer as failed, and send a 'failed' event to the
+          client. If the client uses a failed wl_buffer as an argument to any
+          request, the behaviour is compositor implementation-defined.
+
+      For all DRM formats and unless specified in another protocol extension,
+      pre-multiplied alpha is used for pixel values.
+
+      Unless specified otherwise in another protocol extension, implicit
+      synchronization is used. In other words, compositors and clients must
+      wait and signal fences implicitly passed via the DMA-BUF's reservation
+      mechanism.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="unbind the factory">
+        Objects created through this interface, especially wl_buffers, will
+        remain valid.
+      </description>
+    </request>
+
+    <request name="create_params">
+      <description summary="create a temporary object for buffer parameters">
+        This temporary object is used to collect multiple dmabuf handles into
+        a single batch to create a wl_buffer. It can only be used once and
+        should be destroyed after a 'created' or 'failed' event has been
+        received.
+      </description>
+      <arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1"
+           summary="id for the newly created zwp_linux_buffer_params_v1"/>
+    </request>
+
+    <event name="format" deprecated-since="4">
+      <description summary="supported buffer format">
+        This event advertises one buffer format that the server supports.
+        All the supported formats are advertised once when the client
+        binds to this interface. A roundtrip after binding guarantees
+        that the client has received all supported formats.
+
+        For the definition of the format codes, see the
+        zwp_linux_buffer_params_v1::create request.
+
+        Starting version 4, the format event is deprecated and must not be
+        sent by compositors. Instead, use get_default_feedback or
+        get_surface_feedback.
+      </description>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+    </event>
+
+    <event name="modifier" since="3" deprecated-since="4">
+      <description summary="supported buffer format modifier">
+        This event advertises the formats that the server supports, along with
+        the modifiers supported for each format. All the supported modifiers
+        for all the supported formats are advertised once when the client
+        binds to this interface. A roundtrip after binding guarantees that
+        the client has received all supported format-modifier pairs.
+
+        For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi ==
+        0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event.
+        It indicates that the server can support the format with an implicit
+        modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it
+        is as if no explicit modifier is specified. The effective modifier
+        will be derived from the dmabuf.
+
+        A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for
+        a given format supports both explicit modifiers and implicit modifiers.
+
+        For the definition of the format and modifier codes, see the
+        zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add
+        requests.
+
+        Starting version 4, the modifier event is deprecated and must not be
+        sent by compositors. Instead, use get_default_feedback or
+        get_surface_feedback.
+      </description>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+      <arg name="modifier_hi" type="uint"
+           summary="high 32 bits of layout modifier"/>
+      <arg name="modifier_lo" type="uint"
+           summary="low 32 bits of layout modifier"/>
+    </event>
+
+    <!-- Version 4 additions -->
+
+    <request name="get_default_feedback" since="4">
+      <description summary="get default feedback">
+        This request creates a new zwp_linux_dmabuf_feedback_v1 object not bound
+        to a particular surface. This object will deliver feedback about dmabuf
+        parameters to use if the client doesn't support per-surface feedback
+        (see get_surface_feedback).
+      </description>
+      <arg name="id" type="new_id" interface="zwp_linux_dmabuf_feedback_v1"/>
+    </request>
+
+    <request name="get_surface_feedback" since="4">
+      <description summary="get feedback for a surface">
+        This request creates a new zwp_linux_dmabuf_feedback_v1 object for the
+        specified wl_surface. This object will deliver feedback about dmabuf
+        parameters to use for buffers attached to this surface.
+
+        If the surface is destroyed before the zwp_linux_dmabuf_feedback_v1 object,
+        the feedback object becomes inert.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_linux_dmabuf_feedback_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+  </interface>
+
+  <interface name="zwp_linux_buffer_params_v1" version="5">
+    <description summary="parameters for creating a dmabuf-based wl_buffer">
+      This temporary object is a collection of dmabufs and other
+      parameters that together form a single logical buffer. The temporary
+      object may eventually create one wl_buffer unless cancelled by
+      destroying it before requesting 'create'.
+
+      Single-planar formats only require one dmabuf, however
+      multi-planar formats may require more than one dmabuf. For all
+      formats, an 'add' request must be called once per plane (even if the
+      underlying dmabuf fd is identical).
+
+      You must use consecutive plane indices ('plane_idx' argument for 'add')
+      from zero to the number of planes used by the drm_fourcc format code.
+      All planes required by the format must be given exactly once, but can
+      be given in any order. Each plane index can only be set once; subsequent
+      calls with a plane index which has already been set will result in a
+      plane_set error being generated.
+    </description>
+
+    <enum name="error">
+      <entry name="already_used" value="0"
+             summary="the zwp_linux_buffer_params_v1 object has already been used to create a wl_buffer"/>
+      <entry name="plane_idx" value="1"
+             summary="plane index out of bounds"/>
+      <entry name="plane_set" value="2"
+             summary="the plane index was already set"/>
+      <entry name="incomplete" value="3"
+             summary="missing or too many planes to create a buffer"/>
+      <entry name="invalid_format" value="4"
+             summary="format not supported"/>
+      <entry name="invalid_dimensions" value="5"
+             summary="invalid width or height"/>
+      <entry name="out_of_bounds" value="6"
+             summary="offset + stride * height goes out of dmabuf bounds"/>
+      <entry name="invalid_wl_buffer" value="7"
+             summary="invalid wl_buffer resulted from importing dmabufs via
+               the create_immed request on given buffer_params"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object, used or not">
+        Cleans up the temporary data sent to the server for dmabuf-based
+        wl_buffer creation.
+      </description>
+    </request>
+
+    <request name="add">
+      <description summary="add a dmabuf to the temporary set">
+        This request adds one dmabuf to the set in this
+        zwp_linux_buffer_params_v1.
+
+        The 64-bit unsigned value combined from modifier_hi and modifier_lo
+        is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the
+        fb modifier, which is defined in drm_mode.h of Linux UAPI.
+        This is an opaque token. Drivers use this token to express tiling,
+        compression, etc. driver-specific modifications to the base format
+        defined by the DRM fourcc code.
+
+        Starting from version 4, the invalid_format protocol error is sent if
+        the format + modifier pair was not advertised as supported.
+
+        Starting from version 5, the invalid_format protocol error is sent if
+        all planes don't use the same modifier.
+
+        This request raises the PLANE_IDX error if plane_idx is too large.
+        The error PLANE_SET is raised if attempting to set a plane that
+        was already set.
+      </description>
+      <arg name="fd" type="fd" summary="dmabuf fd"/>
+      <arg name="plane_idx" type="uint" summary="plane index"/>
+      <arg name="offset" type="uint" summary="offset in bytes"/>
+      <arg name="stride" type="uint" summary="stride in bytes"/>
+      <arg name="modifier_hi" type="uint"
+           summary="high 32 bits of layout modifier"/>
+      <arg name="modifier_lo" type="uint"
+           summary="low 32 bits of layout modifier"/>
+    </request>
+
+    <enum name="flags" bitfield="true">
+      <entry name="y_invert" value="1" summary="contents are y-inverted"/>
+      <entry name="interlaced" value="2" summary="content is interlaced"/>
+      <entry name="bottom_first" value="4" summary="bottom field first"/>
+    </enum>
+
+    <request name="create">
+      <description summary="create a wl_buffer from the given dmabufs">
+        This asks for creation of a wl_buffer from the added dmabuf
+        buffers. The wl_buffer is not created immediately but returned via
+        the 'created' event if the dmabuf sharing succeeds. The sharing
+        may fail at runtime for reasons a client cannot predict, in
+        which case the 'failed' event is triggered.
+
+        The 'format' argument is a DRM_FORMAT code, as defined by the
+        libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the
+        authoritative source on how the format codes should work.
+
+        The 'flags' is a bitfield of the flags defined in enum "flags".
+        'y_invert' means that the image needs to be y-flipped.
+
+        Flag 'interlaced' means that the frame in the buffer is not
+        progressive as usual, but interlaced. An interlaced buffer as
+        supported here must always contain both top and bottom fields.
+        The top field always begins on the first pixel row. The temporal
+        ordering between the two fields is top field first, unless
+        'bottom_first' is specified. It is undefined whether 'bottom_first'
+        is ignored if 'interlaced' is not set.
+
+        This protocol does not convey any information about field rate,
+        duration, or timing, other than the relative ordering between the
+        two fields in one buffer. A compositor may have to estimate the
+        intended field rate from the incoming buffer rate. It is undefined
+        whether the time of receiving wl_surface.commit with a new buffer
+        attached, applying the wl_surface state, wl_surface.frame callback
+        trigger, presentation, or any other point in the compositor cycle
+        is used to measure the frame or field times. There is no support
+        for detecting missed or late frames/fields/buffers either, and
+        there is no support whatsoever for cooperating with interlaced
+        compositor output.
+
+        The composited image quality resulting from the use of interlaced
+        buffers is explicitly undefined. A compositor may use elaborate
+        hardware features or software to deinterlace and create progressive
+        output frames from a sequence of interlaced input buffers, or it
+        may produce substandard image quality. However, compositors that
+        cannot guarantee reasonable image quality in all cases are recommended
+        to just reject all interlaced buffers.
+
+        Any argument errors, including non-positive width or height,
+        mismatch between the number of planes and the format, bad
+        format, bad offset or stride, may be indicated by fatal protocol
+        errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS,
+        OUT_OF_BOUNDS.
+
+        Dmabuf import errors in the server that are not obvious client
+        bugs are returned via the 'failed' event as non-fatal. This
+        allows attempting dmabuf sharing and falling back in the client
+        if it fails.
+
+        This request can be sent only once in the object's lifetime, after
+        which the only legal request is destroy. This object should be
+        destroyed after issuing a 'create' request. Attempting to use this
+        object after issuing 'create' raises the ALREADY_USED protocol error.
+
+        It is not mandatory to issue 'create'. If a client wants to
+        cancel the buffer creation, it can just destroy this object.
+      </description>
+      <arg name="width" type="int" summary="base plane width in pixels"/>
+      <arg name="height" type="int" summary="base plane height in pixels"/>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+      <arg name="flags" type="uint" enum="flags" summary="see enum flags"/>
+    </request>
+
+    <event name="created">
+      <description summary="buffer creation succeeded">
+        This event indicates that the attempted buffer creation was
+        successful. It provides the new wl_buffer referencing the dmabuf(s).
+
+        Upon receiving this event, the client should destroy the
+        zwp_linux_buffer_params_v1 object.
+      </description>
+      <arg name="buffer" type="new_id" interface="wl_buffer"
+           summary="id for the the newly created wl_buffer"/>
+    </event>
+
+    <event name="failed">
+      <description summary="buffer creation failed">
+        This event indicates that the attempted buffer creation has
+        failed. It usually means that one of the dmabuf constraints
+        has not been fulfilled.
+
+        Upon receiving this event, the client should destroy the
+        zwp_linux_buffer_params_v1 object.
+      </description>
+    </event>
+
+    <request name="create_immed" since="2">
+      <description summary="immediately create a wl_buffer from the given
+                     dmabufs">
+        This asks for immediate creation of a wl_buffer by importing the
+        added dmabufs.
+
+        In case of import success, no event is sent from the server, and the
+        wl_buffer is ready to be used by the client.
+
+        Upon import failure, either of the following may happen, as seen fit
+        by the implementation:
+        - the client is terminated with one of the following fatal protocol
+          errors:
+          - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS,
+            in case of argument errors such as mismatch between the number
+            of planes and the format, bad format, non-positive width or
+            height, or bad offset or stride.
+          - INVALID_WL_BUFFER, in case the cause for failure is unknown or
+            platform specific.
+        - the server creates an invalid wl_buffer, marks it as failed and
+          sends a 'failed' event to the client. The result of using this
+          invalid wl_buffer as an argument in any request by the client is
+          defined by the compositor implementation.
+
+        This takes the same arguments as a 'create' request, and obeys the
+        same restrictions.
+      </description>
+      <arg name="buffer_id" type="new_id" interface="wl_buffer"
+           summary="id for the newly created wl_buffer"/>
+      <arg name="width" type="int" summary="base plane width in pixels"/>
+      <arg name="height" type="int" summary="base plane height in pixels"/>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+      <arg name="flags" type="uint" enum="flags" summary="see enum flags"/>
+    </request>
+  </interface>
+
+  <interface name="zwp_linux_dmabuf_feedback_v1" version="5">
+    <description summary="dmabuf feedback">
+      This object advertises dmabuf parameters feedback. This includes the
+      preferred devices and the supported formats/modifiers.
+
+      The parameters are sent once when this object is created and whenever they
+      change. The done event is always sent once after all parameters have been
+      sent. When a single parameter changes, all parameters are re-sent by the
+      compositor.
+
+      Compositors can re-send the parameters when the current client buffer
+      allocations are sub-optimal. Compositors should not re-send the
+      parameters if re-allocating the buffers would not result in a more optimal
+      configuration. In particular, compositors should avoid sending the exact
+      same parameters multiple times in a row.
+
+      The tranche_target_device and tranche_formats events are grouped by
+      tranches of preference. For each tranche, a tranche_target_device, one
+      tranche_flags and one or more tranche_formats events are sent, followed
+      by a tranche_done event finishing the list. The tranches are sent in
+      descending order of preference. All formats and modifiers in the same
+      tranche have the same preference.
+
+      To send parameters, the compositor sends one main_device event, tranches
+      (each consisting of one tranche_target_device event, one tranche_flags
+      event, tranche_formats events and then a tranche_done event), then one
+      done event.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the feedback object">
+        Using this request a client can tell the server that it is not going to
+        use the zwp_linux_dmabuf_feedback_v1 object anymore.
+      </description>
+    </request>
+
+    <event name="done">
+      <description summary="all feedback has been sent">
+        This event is sent after all parameters of a zwp_linux_dmabuf_feedback_v1
+        object have been sent.
+
+        This allows changes to the zwp_linux_dmabuf_feedback_v1 parameters to be
+        seen as atomic, even if they happen via multiple events.
+      </description>
+    </event>
+
+    <event name="format_table">
+      <description summary="format and modifier table">
+        This event provides a file descriptor which can be memory-mapped to
+        access the format and modifier table.
+
+        The table contains a tightly packed array of consecutive format +
+        modifier pairs. Each pair is 16 bytes wide. It contains a format as a
+        32-bit unsigned integer, followed by 4 bytes of unused padding, and a
+        modifier as a 64-bit unsigned integer. The native endianness is used.
+
+        The client must map the file descriptor in read-only private mode.
+
+        Compositors are not allowed to mutate the table file contents once this
+        event has been sent. Instead, compositors must create a new, separate
+        table file and re-send feedback parameters. Compositors are allowed to
+        store duplicate format + modifier pairs in the table.
+      </description>
+      <arg name="fd" type="fd" summary="table file descriptor"/>
+      <arg name="size" type="uint" summary="table size, in bytes"/>
+    </event>
+
+    <event name="main_device">
+      <description summary="preferred main device">
+        This event advertises the main device that the server prefers to use
+        when direct scan-out to the target device isn't possible. The
+        advertised main device may be different for each
+        zwp_linux_dmabuf_feedback_v1 object, and may change over time.
+
+        There is exactly one main device. The compositor must send at least
+        one preference tranche with tranche_target_device equal to main_device.
+
+        Clients need to create buffers that the main device can import and
+        read from, otherwise creating the dmabuf wl_buffer will fail (see the
+        zwp_linux_buffer_params_v1.create and create_immed requests for details).
+        The main device will also likely be kept active by the compositor,
+        so clients can use it instead of waking up another device for power
+        savings.
+
+        In general the device is a DRM node. The DRM node type (primary vs.
+        render) is unspecified. Clients must not rely on the compositor sending
+        a particular node type. Clients cannot check two devices for equality
+        by comparing the dev_t value.
+
+        If explicit modifiers are not supported and the client performs buffer
+        allocations on a different device than the main device, then the client
+        must force the buffer to have a linear layout.
+      </description>
+      <arg name="device" type="array" summary="device dev_t value"/>
+    </event>
+
+    <event name="tranche_done">
+      <description summary="a preference tranche has been sent">
+        This event splits tranche_target_device and tranche_formats events into
+        preference tranches. It is sent after a set of tranche_target_device
+        and tranche_formats events; it represents the end of a tranche. The
+        next tranche will have a lower preference.
+      </description>
+    </event>
+
+    <event name="tranche_target_device">
+      <description summary="target device">
+        This event advertises the target device that the server prefers to use
+        for a buffer created given this tranche. The advertised target device
+        may be different for each preference tranche, and may change over time.
+
+        There is exactly one target device per tranche.
+
+        The target device may be a scan-out device, for example if the
+        compositor prefers to directly scan-out a buffer created given this
+        tranche. The target device may be a rendering device, for example if
+        the compositor prefers to texture from said buffer.
+
+        The client can use this hint to allocate the buffer in a way that makes
+        it accessible from the target device, ideally directly. The buffer must
+        still be accessible from the main device, either through direct import
+        or through a potentially more expensive fallback path. If the buffer
+        can't be directly imported from the main device then clients must be
+        prepared for the compositor changing the tranche priority or making
+        wl_buffer creation fail (see the zwp_linux_buffer_params_v1.create and
+        create_immed requests for details).
+
+        If the device is a DRM node, the DRM node type (primary vs. render) is
+        unspecified. Clients must not rely on the compositor sending a
+        particular node type. Clients cannot check two devices for equality by
+        comparing the dev_t value.
+
+        This event is tied to a preference tranche, see the tranche_done event.
+      </description>
+      <arg name="device" type="array" summary="device dev_t value"/>
+    </event>
+
+    <event name="tranche_formats">
+      <description summary="supported buffer format modifiers">
+        This event advertises the format + modifier combinations that the
+        compositor supports.
+
+        It carries an array of indices, each referring to a format + modifier
+        pair in the last received format table (see the format_table event).
+        Each index is a 16-bit unsigned integer in native endianness.
+
+        For legacy support, DRM_FORMAT_MOD_INVALID is an allowed modifier.
+        It indicates that the server can support the format with an implicit
+        modifier. When a buffer has DRM_FORMAT_MOD_INVALID as its modifier, it
+        is as if no explicit modifier is specified. The effective modifier
+        will be derived from the dmabuf.
+
+        A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for
+        a given format supports both explicit modifiers and implicit modifiers.
+
+        Compositors must not send duplicate format + modifier pairs within the
+        same tranche or across two different tranches with the same target
+        device and flags.
+
+        This event is tied to a preference tranche, see the tranche_done event.
+
+        For the definition of the format and modifier codes, see the
+        zwp_linux_buffer_params_v1.create request.
+      </description>
+      <arg name="indices" type="array" summary="array of 16-bit indexes"/>
+    </event>
+
+    <enum name="tranche_flags" bitfield="true">
+      <entry name="scanout" value="1" summary="direct scan-out tranche"/>
+    </enum>
+
+    <event name="tranche_flags">
+      <description summary="tranche flags">
+        This event sets tranche-specific flags.
+
+        The scanout flag is a hint that direct scan-out may be attempted by the
+        compositor on the target device if the client appropriately allocates a
+        buffer. How to allocate a buffer that can be scanned out on the target
+        device is implementation-defined.
+
+        This event is tied to a preference tranche, see the tranche_done event.
+      </description>
+      <arg name="flags" type="uint" enum="tranche_flags" summary="tranche flags"/>
+    </event>
+  </interface>
+
+</protocol>

stable/presentation-time/README

@@ -0,0 +1,5 @@
+Presentation time protocol
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen@collabora.co.uk> (@pq)
+

stable/presentation-time/presentation-time.xml

@@ -0,0 +1,268 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="presentation_time">
+<!-- wrap:70 -->
+
+  <copyright>
+    Copyright © 2013-2014 Collabora, Ltd.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_presentation" version="2">
+    <description summary="timed presentation related wl_surface requests">
+
+<!-- Introduction -->
+
+      The main feature of this interface is accurate presentation
+      timing feedback to ensure smooth video playback while maintaining
+      audio/video synchronization. Some features use the concept of a
+      presentation clock, which is defined in the
+      presentation.clock_id event.
+
+      A content update for a wl_surface is submitted by a
+      wl_surface.commit request. Request 'feedback' associates with
+      the wl_surface.commit and provides feedback on the content
+      update, particularly the final realized presentation time.
+
+<!-- Completing presentation -->
+
+      When the final realized presentation time is available, e.g.
+      after a framebuffer flip completes, the requested
+      presentation_feedback.presented events are sent. The final
+      presentation time can differ from the compositor's predicted
+      display update time and the update's target time, especially
+      when the compositor misses its target vertical blanking period.
+    </description>
+
+    <enum name="error">
+      <description summary="fatal presentation errors">
+        These fatal protocol errors may be emitted in response to
+        illegal presentation requests.
+      </description>
+      <entry name="invalid_timestamp" value="0"
+             summary="invalid value in tv_nsec"/>
+      <entry name="invalid_flag" value="1"
+             summary="invalid flag"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="unbind from the presentation interface">
+        Informs the server that the client will no longer be using
+        this protocol object. Existing objects created by this object
+        are not affected.
+      </description>
+    </request>
+
+    <request name="feedback">
+      <description summary="request presentation feedback information">
+        Request presentation feedback for the current content submission
+        on the given surface. This creates a new presentation_feedback
+        object, which will deliver the feedback information once. If
+        multiple presentation_feedback objects are created for the same
+        submission, they will all deliver the same information.
+
+        For details on what information is returned, see the
+        presentation_feedback interface.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="target surface"/>
+      <arg name="callback" type="new_id" interface="wp_presentation_feedback"
+           summary="new feedback object"/>
+    </request>
+
+    <event name="clock_id">
+      <description summary="clock ID for timestamps">
+        This event tells the client in which clock domain the
+        compositor interprets the timestamps used by the presentation
+        extension. This clock is called the presentation clock.
+
+        The compositor sends this event when the client binds to the
+        presentation interface. The presentation clock does not change
+        during the lifetime of the client connection.
+
+        The clock identifier is platform dependent. On POSIX platforms, the
+        identifier value is one of the clockid_t values accepted by
+        clock_gettime(). clock_gettime() is defined by POSIX.1-2001.
+
+        Timestamps in this clock domain are expressed as tv_sec_hi,
+        tv_sec_lo, tv_nsec triples, each component being an unsigned
+        32-bit value. Whole seconds are in tv_sec which is a 64-bit
+        value combined from tv_sec_hi and tv_sec_lo, and the
+        additional fractional part in tv_nsec as nanoseconds. Hence,
+        for valid timestamps tv_nsec must be in [0, 999999999].
+
+        Note that clock_id applies only to the presentation clock,
+        and implies nothing about e.g. the timestamps used in the
+        Wayland core protocol input events.
+
+        Compositors should prefer a clock which does not jump and is
+        not slewed e.g. by NTP. The absolute value of the clock is
+        irrelevant. Precision of one millisecond or better is
+        recommended. Clients must be able to query the current clock
+        value directly, not by asking the compositor.
+      </description>
+      <arg name="clk_id" type="uint" summary="platform clock identifier"/>
+    </event>
+
+  </interface>
+
+  <interface name="wp_presentation_feedback" version="2">
+    <description summary="presentation time feedback event">
+      A presentation_feedback object returns an indication that a
+      wl_surface content update has become visible to the user.
+      One object corresponds to one content update submission
+      (wl_surface.commit). There are two possible outcomes: the
+      content update is presented to the user, and a presentation
+      timestamp delivered; or, the user did not see the content
+      update because it was superseded or its surface destroyed,
+      and the content update is discarded.
+
+      Once a presentation_feedback object has delivered a 'presented'
+      or 'discarded' event it is automatically destroyed.
+    </description>
+
+    <event name="sync_output">
+      <description summary="presentation synchronized to this output">
+        As presentation can be synchronized to only one output at a
+        time, this event tells which output it was. This event is only
+        sent prior to the presented event.
+
+        As clients may bind to the same global wl_output multiple
+        times, this event is sent for each bound instance that matches
+        the synchronized output. If a client has not bound to the
+        right wl_output global at all, this event is not sent.
+      </description>
+      <arg name="output" type="object" interface="wl_output"
+           summary="presentation output"/>
+    </event>
+
+    <enum name="kind" bitfield="true">
+      <description summary="bitmask of flags in presented event">
+        These flags provide information about how the presentation of
+        the related content update was done. The intent is to help
+        clients assess the reliability of the feedback and the visual
+        quality with respect to possible tearing and timings.
+      </description>
+      <entry name="vsync" value="0x1">
+        <description summary="presentation was vsync'd">
+          The presentation was synchronized to the "vertical retrace" by
+          the display hardware such that tearing does not happen.
+          Relying on software scheduling is not acceptable for this
+          flag. If presentation is done by a copy to the active
+          frontbuffer, then it must guarantee that tearing cannot
+          happen.
+        </description>
+      </entry>
+      <entry name="hw_clock" value="0x2">
+        <description summary="hardware provided the presentation timestamp">
+          The display hardware provided measurements that the hardware
+          driver converted into a presentation timestamp. Sampling a
+          clock in software is not acceptable for this flag.
+        </description>
+      </entry>
+      <entry name="hw_completion" value="0x4">
+        <description summary="hardware signalled the start of the presentation">
+          The display hardware signalled that it started using the new
+          image content. The opposite of this is e.g. a timer being used
+          to guess when the display hardware has switched to the new
+          image content.
+        </description>
+      </entry>
+      <entry name="zero_copy" value="0x8">
+        <description summary="presentation was done zero-copy">
+          The presentation of this update was done zero-copy. This means
+          the buffer from the client was given to display hardware as
+          is, without copying it. Compositing with OpenGL counts as
+          copying, even if textured directly from the client buffer.
+          Possible zero-copy cases include direct scanout of a
+          fullscreen surface and a surface on a hardware overlay.
+        </description>
+      </entry>
+    </enum>
+
+    <event name="presented" type="destructor">
+      <description summary="the content update was displayed">
+        The associated content update was displayed to the user at the
+        indicated time (tv_sec_hi/lo, tv_nsec). For the interpretation of
+        the timestamp, see presentation.clock_id event.
+
+        The timestamp corresponds to the time when the content update
+        turned into light the first time on the surface's main output.
+        Compositors may approximate this from the framebuffer flip
+        completion events from the system, and the latency of the
+        physical display path if known.
+
+        This event is preceded by all related sync_output events
+        telling which output's refresh cycle the feedback corresponds
+        to, i.e. the main output for the surface. Compositors are
+        recommended to choose the output containing the largest part
+        of the wl_surface, or keeping the output they previously
+        chose. Having a stable presentation output association helps
+        clients predict future output refreshes (vblank).
+
+        The 'refresh' argument gives the compositor's prediction of how
+        many nanoseconds after tv_sec, tv_nsec the very next output
+        refresh may occur. This is to further aid clients in
+        predicting future refreshes, i.e., estimating the timestamps
+        targeting the next few vblanks. If such prediction cannot
+        usefully be done, the argument is zero.
+
+        For version 2 and later, if the output does not have a constant
+        refresh rate, explicit video mode switches excluded, then the
+        refresh argument must be either an appropriate rate picked by the
+        compositor (e.g. fastest rate), or 0 if no such rate exists.
+        For version 1, if the output does not have a constant refresh rate,
+        the refresh argument must be zero.
+
+        The 64-bit value combined from seq_hi and seq_lo is the value
+        of the output's vertical retrace counter when the content
+        update was first scanned out to the display. This value must
+        be compatible with the definition of MSC in
+        GLX_OML_sync_control specification. Note, that if the display
+        path has a non-zero latency, the time instant specified by
+        this counter may differ from the timestamp's.
+
+        If the output does not have a concept of vertical retrace or a
+        refresh cycle, or the output device is self-refreshing without
+        a way to query the refresh count, then the arguments seq_hi
+        and seq_lo must be zero.
+      </description>
+      <arg name="tv_sec_hi" type="uint"
+           summary="high 32 bits of the seconds part of the presentation timestamp"/>
+      <arg name="tv_sec_lo" type="uint"
+           summary="low 32 bits of the seconds part of the presentation timestamp"/>
+      <arg name="tv_nsec" type="uint"
+           summary="nanoseconds part of the presentation timestamp"/>
+      <arg name="refresh" type="uint" summary="nanoseconds till next refresh"/>
+      <arg name="seq_hi" type="uint"
+           summary="high 32 bits of refresh counter"/>
+      <arg name="seq_lo" type="uint"
+           summary="low 32 bits of refresh counter"/>
+      <arg name="flags" type="uint" enum="kind" summary="combination of 'kind' values"/>
+    </event>
+
+    <event name="discarded" type="destructor">
+      <description summary="the content update was not displayed">
+        The content update was never displayed to the user.
+      </description>
+    </event>
+  </interface>
+
+</protocol>

stable/tablet/README

@@ -0,0 +1,4 @@
+Tablet protocol
+
+Maintainers:
+Peter Hutterer <peter.hutterer@who-t.net> (@whot)

stable/viewporter/README

@@ -0,0 +1,7 @@
+Viewporter: cropping and scaling extension for surface contents
+
+Previously known as wl_scaler.
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen@collabora.co.uk> (@pq)
+

stable/viewporter/viewporter.xml

@@ -0,0 +1,177 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="viewporter">
+
+  <copyright>
+    Copyright © 2013-2016 Collabora, Ltd.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_viewporter" version="1">
+    <description summary="surface cropping and scaling">
+      The global interface exposing surface cropping and scaling
+      capabilities is used to instantiate an interface extension for a
+      wl_surface object. This extended interface will then allow
+      cropping and scaling the surface contents, effectively
+      disconnecting the direct relationship between the buffer and the
+      surface size.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="unbind from the cropping and scaling interface">
+	Informs the server that the client will not be using this
+	protocol object anymore. This does not affect any other objects,
+	wp_viewport objects included.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="viewport_exists" value="0"
+             summary="the surface already has a viewport object associated"/>
+    </enum>
+
+    <request name="get_viewport">
+      <description summary="extend surface interface for crop and scale">
+	Instantiate an interface extension for the given wl_surface to
+	crop and scale its content. If the given wl_surface already has
+	a wp_viewport object associated, the viewport_exists
+	protocol error is raised.
+      </description>
+      <arg name="id" type="new_id" interface="wp_viewport"
+           summary="the new viewport interface id"/>
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="the surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_viewport" version="1">
+    <description summary="crop and scale interface to a wl_surface">
+      An additional interface to a wl_surface object, which allows the
+      client to specify the cropping and scaling of the surface
+      contents.
+
+      This interface works with two concepts: the source rectangle (src_x,
+      src_y, src_width, src_height), and the destination size (dst_width,
+      dst_height). The contents of the source rectangle are scaled to the
+      destination size, and content outside the source rectangle is ignored.
+      This state is double-buffered, see wl_surface.commit.
+
+      The two parts of crop and scale state are independent: the source
+      rectangle, and the destination size. Initially both are unset, that
+      is, no scaling is applied. The whole of the current wl_buffer is
+      used as the source, and the surface size is as defined in
+      wl_surface.attach.
+
+      If the destination size is set, it causes the surface size to become
+      dst_width, dst_height. The source (rectangle) is scaled to exactly
+      this size. This overrides whatever the attached wl_buffer size is,
+      unless the wl_buffer is NULL. If the wl_buffer is NULL, the surface
+      has no content and therefore no size. Otherwise, the size is always
+      at least 1x1 in surface local coordinates.
+
+      If the source rectangle is set, it defines what area of the wl_buffer is
+      taken as the source. If the source rectangle is set and the destination
+      size is not set, then src_width and src_height must be integers, and the
+      surface size becomes the source rectangle size. This results in cropping
+      without scaling. If src_width or src_height are not integers and
+      destination size is not set, the bad_size protocol error is raised when
+      the surface state is applied.
+
+      The coordinate transformations from buffer pixel coordinates up to
+      the surface-local coordinates happen in the following order:
+        1. buffer_transform (wl_surface.set_buffer_transform)
+        2. buffer_scale (wl_surface.set_buffer_scale)
+        3. crop and scale (wp_viewport.set*)
+      This means, that the source rectangle coordinates of crop and scale
+      are given in the coordinates after the buffer transform and scale,
+      i.e. in the coordinates that would be the surface-local coordinates
+      if the crop and scale was not applied.
+
+      If src_x or src_y are negative, the bad_value protocol error is raised.
+      Otherwise, if the source rectangle is partially or completely outside of
+      the non-NULL wl_buffer, then the out_of_buffer protocol error is raised
+      when the surface state is applied. A NULL wl_buffer does not raise the
+      out_of_buffer error.
+
+      If the wl_surface associated with the wp_viewport is destroyed,
+      all wp_viewport requests except 'destroy' raise the protocol error
+      no_surface.
+
+      If the wp_viewport object is destroyed, the crop and scale
+      state is removed from the wl_surface. The change will be applied
+      on the next wl_surface.commit.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="remove scaling and cropping from the surface">
+	The associated wl_surface's crop and scale state is removed.
+	The change is applied on the next wl_surface.commit.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="bad_value" value="0"
+	     summary="negative or zero values in width or height"/>
+      <entry name="bad_size" value="1"
+	     summary="destination size is not integer"/>
+      <entry name="out_of_buffer" value="2"
+	     summary="source rectangle extends outside of the content area"/>
+      <entry name="no_surface" value="3"
+	     summary="the wl_surface was destroyed"/>
+    </enum>
+
+    <request name="set_source">
+      <description summary="set the source rectangle for cropping">
+	Set the source rectangle of the associated wl_surface. See
+	wp_viewport for the description, and relation to the wl_buffer
+	size.
+
+	If all of x, y, width and height are -1.0, the source rectangle is
+	unset instead. Any other set of values where width or height are zero
+	or negative, or x or y are negative, raise the bad_value protocol
+	error.
+
+	The crop and scale state is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="x" type="fixed" summary="source rectangle x"/>
+      <arg name="y" type="fixed" summary="source rectangle y"/>
+      <arg name="width" type="fixed" summary="source rectangle width"/>
+      <arg name="height" type="fixed" summary="source rectangle height"/>
+    </request>
+
+    <request name="set_destination">
+      <description summary="set the surface size for scaling">
+	Set the destination size of the associated wl_surface. See
+	wp_viewport for the description, and relation to the wl_buffer
+	size.
+
+	If width is -1 and height is -1, the destination size is unset
+	instead. Any other pair of values for width and height that
+	contains zero or negative values raises the bad_value protocol
+	error.
+
+	The crop and scale state is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="width" type="int" summary="surface width"/>
+      <arg name="height" type="int" summary="surface height"/>
+    </request>
+  </interface>
+
+</protocol>

stable/xdg-shell/README

@@ -0,0 +1,5 @@
+xdg shell protocol
+
+Maintainers:
+Jonas Ådahl <jadahl@gmail.com> (@jadahl)
+Mike Blumenkrantz <michael.blumenkrantz@gmail.com> (@zmike)

staging/alpha-modifier/README

@@ -0,0 +1,4 @@
+Alpha modifier protocol
+
+Maintainers:
+Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)

staging/alpha-modifier/alpha-modifier-v1.xml

@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="alpha_modifier_v1">
+  <copyright>
+    Copyright © 2024 Xaver Hugl
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_alpha_modifier_v1" version="1">
+    <description summary="surface alpha modifier manager">
+      This interface allows a client to set a factor for the alpha values on a
+      surface, which can be used to offload such operations to the compositor,
+      which can in turn for example offload them to KMS.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the alpha modifier manager object">
+        Destroy the alpha modifier manager. This doesn't destroy objects
+        created with the manager.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="already_constructed" value="0"
+             summary="wl_surface already has a alpha modifier object"/>
+    </enum>
+
+    <request name="get_surface">
+      <description summary="create a new alpha modifier surface object">
+        Create a new alpha modifier surface object associated with the
+        given wl_surface. If there is already such an object associated with
+        the wl_surface, the already_constructed error will be raised.
+      </description>
+      <arg name="id" type="new_id" interface="wp_alpha_modifier_surface_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_alpha_modifier_surface_v1" version="1">
+    <description summary="alpha modifier object for a surface">
+      This interface allows the client to set a factor for the alpha values on
+      a surface, which can be used to offload such operations to the compositor.
+      The default factor is UINT32_MAX.
+
+      This object has to be destroyed before the associated wl_surface. Once the
+      wl_surface is destroyed, all request on this object will raise the
+      no_surface error.
+    </description>
+
+    <enum name="error">
+      <entry name="no_surface" value="0" summary="wl_surface was destroyed"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the alpha modifier object">
+        This destroys the object, and is equivalent to set_multiplier with
+        a value of UINT32_MAX, with the same double-buffered semantics as
+        set_multiplier.
+      </description>
+    </request>
+
+    <request name="set_multiplier">
+      <description summary="specify the alpha multiplier">
+        Sets the alpha multiplier for the surface. The alpha multiplier is
+        double-buffered state, see wl_surface.commit for details.
+
+        This factor is applied in the compositor's blending space, as an
+        additional step after the processing of per-pixel alpha values for the
+        wl_surface. The exact meaning of the factor is thus undefined, unless
+        the blending space is specified in a different extension.
+
+        This multiplier is applied even if the buffer attached to the
+        wl_surface doesn't have an alpha channel; in that case an alpha value
+        of one is used instead.
+
+        Zero means completely transparent, UINT32_MAX means completely opaque.
+      </description>
+      <arg name="factor" type="uint"/>
+    </request>
+  </interface>
+</protocol>

staging/color-management/README

@@ -0,0 +1,11 @@
+Color management and HDR protocol
+
+Maintainers:
+Sebastian Wick <sebastian at sebastianwick.net>
+Pekka Paalanen <pekka.paalanen@collabora.com>
+
+
+Historical credits not mentioned in the first commit:
+
+- Niels Ole Salscheider, for an early protocol version
+  https://lists.freedesktop.org/archives/wayland-devel/2014-October/017755.html

staging/color-management/appendix.md

@@ -0,0 +1,144 @@
+---
+SPDX-FileCopyrightText: 2025 Collabora, Ltd.
+SPDX-License-Identifier: MIT
+---
+
+Contents
+
+[TOC]
+
+# Wayland Color-Management Protocol
+
+This document is an appendix to the [color-management][cm-spec]
+protocol specification.
+
+## Transfer functions (normative)
+
+`wp_color_manager_v1` enumeration `transfer_function` lists a selection
+of transfer functions describing display-referred image encoding between
+normalized [electrical] $`E`$ and [optical] $`L`$ values. The function
+definitions are as follows.
+
+$`L`$
+: Screen luminance in cd/m² in the assumed viewing environment.
+Since the protocol uses the reference luminance level as a proxy for the
+environment, these values must be interpreted in the context of the
+reference luminance level.
+
+$`L_W`$
+: Screen luminance for peak white; the primary color volume maximum luminance.
+
+$`L_B`$
+: Screen luminance for black; the primary color volume minimum luminance.
+
+
+### `bt1886`
+
+```math
+L = a\left(\max\left(E + b,0\right)\right)^\gamma
+```
+
+where $`\gamma = 2.4`$ and the parameters
+
+```math
+a = \left(L_W^{1/\gamma} - L_B^{1/\gamma}\right)^\gamma,
+```
+
+```math
+b = \frac{L_B^{1/\gamma}}{L_W^{1/\gamma} - L_B^{1/\gamma}}.
+```
+
+The above are specified by [ITU-R BT.1886].
+
+Note, that $`E < 0`$ and $`E > 1`$ are possible with limited range
+quantization, as required by e.g. the calibration method in [ITU-R BT.814].
+
+### `compound_power_2_4`
+
+```math
+O = \begin{cases}
+\frac{E}{12.92}, & 0 \leq E < 0.04045\\
+\left( \frac{E + 0.055}{1.055} \right)^{2.4}, & 0.04045 \leq E \leq 1
+\end{cases}
+```
+
+The above is the IEC 61966-2-1 piece-wise transfer function,
+as recorded in [Khronos Data Format Specification][KDFS] 1.4.0
+Section 13.3, and restricted to the unit range.
+
+```math
+L = (L_W - L_B)O + L_B
+```
+
+### `gamma22`
+
+```math
+O = E^{2.2}, \quad 0 \leq E \leq 1
+```
+
+```math
+L = (L_W - L_B)O + L_B
+```
+
+### `gamma28`
+
+```math
+O = E^{2.8}, \quad 0 \leq E \leq 1
+```
+
+```math
+L = (L_W - L_B)O + L_B
+```
+
+### `ext_linear`
+
+```math
+O = E, \quad \forall E \in \Reals
+```
+
+```math
+L = (L_W - L_B)O + L_B
+```
+
+### `st2084_pq`
+
+```math
+\begin{align*}
+m_1 &=& \vphantom{\Bigg(} \frac{2610}{16384} &= 0.1593017578125\\
+m_2 &=& \vphantom{\Bigg(} 128\left(\frac{2523}{4096}\right) &= 78.84375\\
+c_1 = c_3 − c_2 + 1 &=& \vphantom{\Bigg(} \frac{3424}{4096} &= 0.8359375\\
+c_2 &=& \vphantom{\Bigg(} 32\left(\frac{2413}{4096}\right) &= 18.8515625\\
+c_3 &=& \vphantom{\Bigg(} 32\left(\frac{2392}{4096}\right) &= 18.6875
+\end{align*}
+```
+
+```math
+O = \left(
+  \frac{\max\left[
+    \left(E^\frac{1}{m_2} - c_1\right), 0
+  \right]}{c_2 - c_3 E^\frac{1}{m_2}}
+\right)^\frac{1}{m_1},
+\quad 0 \leq E \leq 1
+```
+
+And the inverse
+
+```math
+E = \left( \frac{c_1 + c_2 O^{m_1}}{1 + c_3 O^{m_1}} \right)^{m_2},
+\quad 0 \leq O \leq 1
+```
+
+The above are specified by [ITU-R BT.2100].
+
+```math
+L = 10'000\ \mathrm{cd/m²} \cdot O + L_B
+```
+
+
+[cm-spec]: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/tree/main/staging/color-management
+[electrical]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/glossary.md#electrical-color-value
+[optical]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/glossary.md#optical-color-value
+[ITU-R BT.814]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt814
+[ITU-R BT.1886]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt1886
+[ITU-R BT.2100]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt2100
+[KDFS]: https://registry.khronos.org/DataFormat/

staging/color-representation/README

@@ -0,0 +1,6 @@
+color-representation protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr>
+Sebastian Wick <sebastian@sebastianwick.net>
+Pekka Paalanen <pekka.paalanen@collabora.com>

staging/color-representation/color-representation-v1.xml

@@ -0,0 +1,433 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="color_representation_v1">
+  <copyright>
+    Copyright 2022 Simon Ser
+    Copyright 2022 Red Hat, Inc.
+    Copyright 2022 Collabora, Ltd.
+    Copyright 2022-2025 Red Hat, Inc.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="color representation protocol extension">
+    This protocol extension delivers the metadata required to define alpha mode,
+    the color model, sub-sampling and quantization range used when interpreting
+    buffer contents. The main use case is defining how the YCbCr family of pixel
+    formats convert to RGB.
+
+    Note that this protocol does not define the colorimetry of the resulting RGB
+    channels / tristimulus values. Without the help of other extensions the
+    resulting colorimetry is therefore implementation defined.
+
+    If this extension is not used, the color representation used is compositor
+    implementation defined.
+
+    Recommendation ITU-T H.273
+    "Coding-independent code points for video signal type identification"
+    shall be referred to as simply H.273 here.
+  </description>
+
+  <interface name="wp_color_representation_manager_v1" version="1">
+    <description summary="color representation manager singleton">
+      A singleton global interface used for getting color representation
+      extensions for wl_surface. The extension interfaces allow setting the
+      color representation of surfaces.
+
+      Compositors should never remove this global.
+    </description>
+
+    <enum name="error">
+      <description summary="protocol errors"/>
+      <entry name="surface_exists" value="1"
+             summary="color representation surface exists already"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the wp_color_representation_manager_v1 object. This does not
+        affect any other objects in any way.
+      </description>
+
+    </request>
+
+    <request name="get_surface">
+      <description summary="create a color representation interface for a wl_surface">
+        If a wp_color_representation_surface_v1 object already exists for the
+        given wl_surface, the protocol error surface_exists is raised.
+
+        This creates a new color wp_color_representation_surface_v1 object for
+        the given wl_surface.
+
+        See the wp_color_representation_surface_v1 interface for more details.
+      </description>
+      <arg name="id"
+           type="new_id" interface="wp_color_representation_surface_v1"/>
+      <arg name="surface"
+           type="object" interface="wl_surface"/>
+    </request>
+
+    <event name="supported_alpha_mode">
+      <description summary="supported alpha modes">
+        When this object is created, it shall immediately send this event once
+        for each alpha mode the compositor supports.
+
+        For the definition of the supported values, see the
+        wp_color_representation_surface_v1::alpha_mode enum.
+      </description>
+      <arg name="alpha_mode"
+           type="uint" enum="wp_color_representation_surface_v1.alpha_mode"
+           summary="supported alpha mode"/>
+    </event>
+
+    <event name="supported_coefficients_and_ranges">
+      <description summary="supported matrix coefficients and ranges">
+        When this object is created, it shall immediately send this event once
+        for each matrix coefficient and color range combination the compositor
+        supports.
+
+        For the definition of the supported values, see the
+        wp_color_representation_surface_v1::coefficients and
+        wp_color_representation_surface_v1::range enums.
+      </description>
+      <arg name="coefficients"
+           type="uint" enum="wp_color_representation_surface_v1.coefficients"
+           summary="supported matrix coefficients"/>
+      <arg name="range"
+           type="uint" enum="wp_color_representation_surface_v1.range"
+           summary="full range flag"/>
+    </event>
+
+    <event name="done">
+      <description summary="all features have been sent">
+        This event is sent when all supported features have been sent.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="wp_color_representation_surface_v1" version="1">
+    <description summary="color representation extension to a surface">
+      A wp_color_representation_surface_v1 allows the client to set the color
+      representation metadata of a surface.
+
+      By default, a surface does not have any color representation metadata set.
+      The reconstruction of R, G, B signals on such surfaces is compositor
+      implementation defined. The alpha mode is assumed to be
+      premultiplied_electrical when the alpha mode is unset.
+
+      If the wl_surface associated with the wp_color_representation_surface_v1
+      is destroyed, the wp_color_representation_surface_v1 object becomes inert.
+    </description>
+
+    <enum name="error">
+      <description summary="protocol errors"/>
+      <entry name="alpha_mode" value="1"
+             summary="unsupported alpha mode"/>
+      <entry name="coefficients" value="2"
+             summary="unsupported coefficients"/>
+      <entry name="pixel_format" value="3"
+             summary="the pixel format and a set value are incompatible"/>
+      <entry name="inert" value="4"
+             summary="forbidden request on inert object"/>
+      <entry name="chroma_location" value="5"
+             summary="invalid chroma location"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the color representation">
+        Destroy the wp_color_representation_surface_v1 object.
+
+        Destroying this object unsets all the color representation metadata from
+        the surface. See the wp_color_representation_surface_v1 interface
+        description for how a compositor handles a surface without color
+        representation metadata. Unsetting is double-buffered state, see
+        wl_surface.commit.
+      </description>
+    </request>
+
+    <enum name="alpha_mode">
+      <description summary="alpha mode">
+        Specifies how the alpha channel affects the color channels.
+      </description>
+      <entry name="premultiplied_electrical" value="0">
+        <description summary="premultiplied alpha in electrical values">
+          Electrical color channel values (after transfer function encoding)
+          are already multiplied with the alpha channel value.
+        </description>
+      </entry>
+      <entry name="premultiplied_optical" value="1">
+        <description summary="premultiplied alpha in optical values">
+          Optical color channel values (before transfer function encoding)
+          are already multiplied with the alpha channel value.
+        </description>
+      </entry>
+      <entry name="straight" value="2">
+        <description summary="straight alpha">
+          Alpha channel has not been pre-multiplied into color channels.
+        </description>
+      </entry>
+    </enum>
+
+    <enum name="coefficients">
+      <description summary="named coefficients">
+        Named matrix coefficients used to encode well-known sets of
+        coefficients. H.273 is the authority, when it comes to the exact values
+        of coefficients and authoritative specifications, where an equivalent
+        code point exists.
+
+        A value of 0 is invalid and will never be present in the list of enums.
+
+        Descriptions do list the specifications for convenience.
+      </description>
+      <entry name="identity" value="1">
+        <description summary="The identity matrix">
+          Coefficients as defined by
+          - IEC 61966-2-1 sRGB
+          - SMPTE ST 428-1 (2019)
+
+          Equivalent to H.273 MatrixCoefficients code point 0.
+          Compatible with pixel formats of the RGB family.
+        </description>
+      </entry>
+      <entry name="bt709" value="2">
+        <description summary="BT.709 matrix coefficients">
+          Coefficients as defined by
+          - Rec. ITU-R BT.709-6
+          - Rec. ITU-R BT.1361-0 conventional colour gamut system (historical)
+          - Rec. ITU-R BT.1361-0 conventional colour gamut system and extended
+            colour gamut system (historical)
+          - IEC 61966-2-4 xvYCC709
+          - SMPTE RP 177 (1993) Annex B
+
+          Equivalent to H.273 MatrixCoefficients code point 1.
+          Compatible with pixel formats of the YCbCr family.
+        </description>
+      </entry>
+      <entry name="fcc" value="3">
+        <description summary="FCC matrix coefficients">
+          Coefficients as defined by
+          - United States Federal Communications Commission (2003) Title 47
+            Code of Federal Regulations 73.682 (a) (20)
+
+          Equivalent to H.273 MatrixCoefficients code point 4.
+          Compatible with pixel formats of the YCbCr family.
+        </description>
+      </entry>
+      <entry name="bt601" value="4">
+        <description summary="BT.601-7 matrix coefficients">
+          Coefficients as defined by
+          - Rec. ITU-R BT.470-6 System B, G (historical)
+          - Rec. ITU-R BT.601-7 625
+          - Rec. ITU-R BT.601-7 525
+          - Rec. ITU-R BT.1358-0 625 (historical)
+          - Rec. ITU-R BT.1358-1 525 or 625 (historical)
+          - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
+          - Rec. ITU-R BT.1700-0 NTSC
+          - IEC 61966-2-1 sYCC
+          - IEC 61966-2-4 xvYCC601
+          - SMPTE ST 170 (2004)
+
+          Equivalent to H.273 MatrixCoefficients code point 5, 6.
+          Compatible with pixel formats of the YCbCr family.
+        </description>
+      </entry>
+      <entry name="smpte240" value="5">
+        <description summary="SMPTE ST 240 matrix coefficients">
+          Coefficients as defined by
+          - SMPTE ST 240 (1999)
+
+          Equivalent to H.273 MatrixCoefficients code point 7.
+          Compatible with pixel formats of the YCbCr family.
+        </description>
+      </entry>
+      <entry name="bt2020" value="6">
+        <description summary="BT.2020 and BT.2100 YCbCr matrix coefficients">
+          Coefficients as defined by
+          - Rec. ITU-R BT.2020-2 (non-constant luminance)
+          - Rec. ITU-R BT.2100-2 Y′CbCr
+
+          Equivalent to H.273 MatrixCoefficients code point 9.
+          Compatible with pixel formats of the YCbCr family.
+        </description>
+      </entry>
+      <entry name="bt2020_cl" value="7">
+        <description summary="BT.2020 matrix coefficients for constant luminance">
+          Coefficients as defined by
+          - Rec. ITU-R BT.2020-2 (constant luminance)
+
+          Equivalent to H.273 MatrixCoefficients code point 10.
+          Compatible with pixel formats of the YCbCr family.
+        </description>
+      </entry>
+      <entry name="ictcp" value="8">
+        <description summary="BT.2100 ICtCp matrix coefficients">
+          Coefficients as defined by
+          - Rec. ITU-R BT.2100-2 ICTCP
+
+          Equivalent to H.273 MatrixCoefficients code point 14.
+          Compatible with pixel formats of the YCbCr family.
+        </description>
+      </entry>
+    </enum>
+
+    <enum name="range">
+      <description summary="Color range values">
+        Possible color range values.
+
+        A value of 0 is invalid and will never be present in the list of enums.
+      </description>
+      <entry name="full" value="1" summary="Full color range"/>
+      <entry name="limited" value="2" summary="Limited color range"/>
+    </enum>
+
+    <enum name="chroma_location">
+      <description summary="Chroma sample location for 4:2:0 YCbCr">
+        Chroma sample location as defined by H.273 Chroma420SampleLocType.
+
+        A value of 0 is invalid and will never be present in the list of enums.
+
+        The descriptions list the matching Vulkan VkChromaLocation combinations
+        for convenience.
+      </description>
+      <entry name="type_0" value="1">
+        <description summary="Horizontal offset of 0, vertical offset of 0.5">
+          Corresponding to VkChromaLocations:
+          - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
+          - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
+
+          Equivalent to H.273 Chroma420SampleLocType 0.
+        </description>
+      </entry>
+      <entry name="type_1" value="2">
+        <description summary="Horizontal offset of 0.5, vertical offset of 0.5">
+          Corresponding to VkChromaLocations:
+          - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
+          - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
+
+          Equivalent to H.273 Chroma420SampleLocType 1.
+        </description>
+      </entry>
+      <entry name="type_2" value="3">
+        <description summary="Horizontal offset of 0, vertical offset of 0">
+          Corresponding to VkChromaLocations:
+          - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
+          - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
+
+          Equivalent to H.273 Chroma420SampleLocType 2.
+        </description>
+      </entry>
+      <entry name="type_3" value="4">
+        <description summary="Horizontal offset of 0.5, vertical offset of 0">
+          Corresponding to VkChromaLocations:
+          - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
+          - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
+
+          Equivalent to H.273 Chroma420SampleLocType 3.
+        </description>
+      </entry>
+      <entry name="type_4" value="5">
+        <description summary="Horizontal offset of 0, vertical offset of 1">
+          Equivalent to H.273 Chroma420SampleLocType 4.
+        </description>
+      </entry>
+      <entry name="type_5" value="6">
+        <description summary="Horizontal offset of 0.5, vertical offset of 1">
+          Equivalent to H.273 Chroma420SampleLocType 5.
+        </description>
+      </entry>
+    </enum>
+
+    <request name="set_alpha_mode">
+      <description summary="set the surface alpha mode">
+        If this protocol object is inert, the protocol error inert is raised.
+
+        Assuming an alpha channel exists, it is always linear. The alpha mode
+        determines whether and how the color channels include pre-multiplied
+        alpha. Using straight alpha might have performance benefits.
+
+        Only alpha modes advertised by the compositor are allowed to be used as
+        argument for this request. The "alpha_mode" protocol error is raised
+        otherwise.
+
+        Alpha mode is double buffered, see wl_surface.commit.
+      </description>
+      <arg name="alpha_mode" type="uint" enum="alpha_mode"
+           summary="alpha mode"/>
+    </request>
+
+    <request name="set_coefficients_and_range">
+      <description summary="set the matrix coefficients and range">
+        If this protocol object is inert, the protocol error inert is raised.
+
+        Set the matrix coefficients and video range which defines the formula
+        and the related constants used to derive red, green and blue signals.
+        Usually coefficients correspond to MatrixCoefficients code points in
+        H.273.
+
+        Only combinations advertised by the compositor are allowed to be used as
+        argument for this request. The "coefficients" protocol error is raised
+        otherwise.
+
+        A call to wl_surface.commit verifies that the pixel format and the
+        coefficients-range combination in the committed surface contents are
+        compatible, if contents exist. The "pixel_format" protocol error is
+        raised otherwise.
+
+        A pixel format is compatible with the coefficients-range combination if
+        the related equations and conventions as defined in H.273 can produce
+        the color channels (RGB or YCbCr) of the pixel format.
+
+        For the definition of the supported combination, see the
+        wp_color_representation_surface_v1::coefficients and
+        wp_color_representation_surface_v1::range enums.
+
+        The coefficients-range combination is double-buffered, see
+        wl_surface.commit.
+      </description>
+      <arg name="coefficients" type="uint" enum="coefficients"
+           summary="matrix coefficients"/>
+      <arg name="range" type="uint" enum="range"
+           summary="range"/>
+    </request>
+
+    <request name="set_chroma_location">
+      <description summary="set the chroma location">
+        If this protocol object is inert, the protocol error inert is raised.
+
+        Set the chroma location type which defines the position of downsampled
+        chroma samples, corresponding to Chroma420SampleLocType code points in
+        H.273.
+
+        An invalid chroma location enum value raises the "chroma_location"
+        protocol error.
+
+        A call to wl_surface.commit verifies that the pixel format and chroma
+        location type in the committed surface contents are compatible, if
+        contents exist. The "pixel_format" protocol error is raised otherwise.
+
+        For the definition of the supported chroma location types, see the
+        wp_color_representation_surface_v1::chroma_location enum.
+
+        The chroma location type is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="chroma_location" type="uint" enum="chroma_location"
+           summary="chroma sample location"/>
+    </request>
+  </interface>
+</protocol>

staging/color-representation/notes.rst

@@ -0,0 +1,79 @@
+.. Copyright 2022 Red Hat, Inc.
+
+.. contents::
+
+Rec ITU-T H.273
+===============
+
+Rec ITU-T H.273 (short H.273) is a Recommendation from the International
+Telecommunication Union (ITU) with the title "Coding-independent code points for
+video signal type identification". All published versions can be found at
+https://www.itu.int/rec/T-REC-H.273/en.
+
+For a quick introduction to Rec ITU-T H.273 see
+https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/cicp_h273.md.
+
+Code point and pixel format compatibility
+=========================================
+
+Certain color representation metadata requires the selected code point to be
+compatible with the buffer's pixel format. Which code points are compatible with
+which pixel formats depends on the type of metadata.
+
+All ``Chroma420SampleLocType`` chroma location code points are compatible with
+4:2:0 subsampled pixel formats. Using a pixel format which is not 4:2:0
+subsampled in a commit where a ``Chroma420SampleLocType`` code point is set
+results in a protocol error. Clients can unset all code points again by
+destroying the wp_color_representation_surface_v1, when they switch to such
+formats.
+
+The matrix coefficients' code point and pixel format compatibility is harder to
+determine and depends on the specific code point.
+
+The ``MatrixCoefficients`` code points are defined by "Rec ITU-T H.273
+Coding-independent code points for video signal type identification". This
+document further defines equations which describe how a tristimulus value can be
+transformed. Which equations can be applied depends on which
+``MatrixCoefficients`` code point is selected and if the ``VideoFullRangeFlag``
+is set or not. By applying the applicable equations on a tristimulus value one
+or more color encodings can be inferred. This color encoding has three channels
+and each of those channels must map to the pixel format of the surface's buffer.
+In Rec ITU-T H.273 (07/21) those channels are either R, G and B or Y, Cb and Cr.
+
+Equations numbers used in the examples below are taken from Rec ITU-T H.273
+(07/21) and might change in future versions.
+
+For example code point 0: equations 11-13 transform the tristimulus values E\
+:sub:`R`, E\ :sub:`G`, E\ :sub:`B` to a non-linear encoding E'\ :sub:`R`, E'\
+:sub:`G`, E'\ :sub:`B`. Those can be transformed to an RGB encoding with
+equations 20-22 (if the ``VideoFullRangeFlag`` is not set) or 26-28 (if the
+``VideoFullRangeFlag`` is set). A YCbCr encoding can be inferred from the RGB
+encoding with equations 41-43.
+
+Therefore the code point 0 is compatible only with pixel formats which contain
+the RGB or YCbCr color channels. The pixel formats may additionally carry unused
+bits, alpha or other channels.
+
+For example code point 1: apply equations 11-13, 38-40 and either 23-25 or 29-31
+(depending on the ``VideoFullRangeFlag``) to arrive at the YCbCr encoding. An
+RGB encoding cannot be inferred from the applicable equations.
+
+Therefore code point 1 is is compatible only with pixel formats which contain
+the YCbCr color channels.
+
+MatrixCoefficients usage
+========================
+
+Note that the ``MatrixCoefficients`` equations as defined by Rec ITU-T H.273
+describe how the client transforms the tristimulus values to an encoding which
+ends up in the buffer it sends to the compositor. Compositors will use the
+inverse steps, including the transfer characteristics which are not defined by
+this protocol to convert the encoding back to tristimulus values with color
+primaries which are also not defined by this protocol.
+
+Some ``MatrixCoefficients`` code points require applying formulas or inferring
+constants from the transfer characteristics or color primaries of the image.
+Compositors should not advertise support for such code points if the client
+can't communicate the transfer characteristics and color primaries to the
+compositor. Communicating those when needed is left for other Wayland extensions
+to be used in conjunction with color-representation.

staging/commit-timing/README

@@ -0,0 +1,4 @@
+Commit Timing Protocol
+
+Maintainers:
+Derek Foreman <derek.foreman@collabora.com> (@derekf)

staging/commit-timing/commit-timing-v1.xml

@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="commit_timing_v1">
+
+  <copyright>
+    Copyright © 2023 Valve Corporation
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_commit_timing_manager_v1" version="1">
+    <description summary="commit timing">
+      When a compositor latches on to new content updates it will check for
+      any number of requirements of the available content updates (such as
+      fences of all buffers being signalled) to consider the update ready.
+
+      This protocol provides a method for adding a time constraint to surface
+      content. This constraint indicates to the compositor that a content
+      update should be presented as closely as possible to, but not before,
+      a specified time.
+
+      This protocol does not change the Wayland property that content
+      updates are applied in the order they are received, even when some
+      content updates contain timestamps and others do not.
+
+      To provide timestamps, this global factory interface must be used to
+      acquire a wp_commit_timing_v1 object for a surface, which may then be
+      used to provide timestamp information for commits.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+    <enum name="error">
+      <entry name="commit_timer_exists" value="0"
+             summary="commit timer already exists for surface"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="unbind from the commit timing interface">
+        Informs the server that the client will no longer be using
+        this protocol object. Existing objects created by this object
+        are not affected.
+      </description>
+    </request>
+
+    <request name="get_timer">
+      <description summary="request commit timer interface for surface">
+        Establish a timing controller for a surface.
+
+        Only one commit timer can be created for a surface, or a
+        commit_timer_exists protocol error will be generated.
+      </description>
+      <arg name="id" type="new_id" interface="wp_commit_timer_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_commit_timer_v1" version="1">
+    <description summary="Surface commit timer">
+      An object to set a time constraint for a content update on a surface.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_timestamp" value="0"
+             summary="timestamp contains an invalid value"/>
+      <entry name="timestamp_exists" value="1"
+             summary="timestamp exists"/>
+      <entry name="surface_destroyed" value="2"
+             summary="the associated surface no longer exists"/>
+    </enum>
+
+    <request name="set_timestamp">
+      <description summary="Specify time the following commit takes effect">
+        Provide a timing constraint for a surface content update.
+
+        A set_timestamp request may be made before a wl_surface.commit to
+        tell the compositor that the content is intended to be presented
+        as closely as possible to, but not before, the specified time.
+        The time is in the domain of the compositor's presentation clock.
+
+        An invalid_timestamp error will be generated for invalid tv_nsec.
+
+        If a timestamp already exists on the surface, a timestamp_exists
+        error is generated.
+
+        Requesting set_timestamp after the commit_timer object's surface is
+        destroyed will generate a "surface_destroyed" error.
+      </description>
+      <arg name="tv_sec_hi" type="uint"
+           summary="high 32 bits of the seconds part of target time"/>
+      <arg name="tv_sec_lo" type="uint"
+           summary="low 32 bits of the seconds part of target time"/>
+      <arg name="tv_nsec" type="uint"
+           summary="nanoseconds part of target time"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the timer">
+        Informs the server that the client will no longer be using
+        this protocol object.
+
+        Existing timing constraints are not affected by the destruction.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/content-type/README

@@ -0,0 +1,5 @@
+Content type hint protocol
+
+Maintainers:
+Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> (@linkmauve)
+Xaver Hugl <xaver.hugl@gmail.com> (@Zamundaaa)

staging/content-type/content-type-v1.xml

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="content_type_v1">
+  <copyright>
+    Copyright © 2021 Emmanuel Gil Peyrot
+    Copyright © 2022 Xaver Hugl
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_content_type_manager_v1" version="1">
+    <description summary="surface content type manager">
+      This interface allows a client to describe the kind of content a surface
+      will display, to allow the compositor to optimize its behavior for it.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the content type manager object">
+        Destroy the content type manager. This doesn't destroy objects created
+        with the manager.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="already_constructed" value="0"
+             summary="wl_surface already has a content type object"/>
+    </enum>
+
+    <request name="get_surface_content_type">
+      <description summary="create a new content type object">
+        Create a new content type object associated with the given surface.
+
+        Creating a wp_content_type_v1 from a wl_surface which already has one
+        attached is a client error: already_constructed.
+      </description>
+      <arg name="id" type="new_id" interface="wp_content_type_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_content_type_v1" version="1">
+    <description summary="content type object for a surface">
+      The content type object allows the compositor to optimize for the kind
+      of content shown on the surface. A compositor may for example use it to
+      set relevant drm properties like "content type".
+
+      The client may request to switch to another content type at any time.
+      When the associated surface gets destroyed, this object becomes inert and
+      the client should destroy it.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the content type object">
+        Switch back to not specifying the content type of this surface. This is
+        equivalent to setting the content type to none, including double
+        buffering semantics. See set_content_type for details.
+      </description>
+    </request>
+
+    <enum name="type">
+      <description summary="possible content types">
+        These values describe the available content types for a surface.
+      </description>
+      <entry name="none" value="0">
+        <description summary="no content type applies">
+          The content type none means that either the application has no data
+          about the content type, or that the content doesn't fit into one of
+          the other categories.
+        </description>
+      </entry>
+      <entry name="photo" value="1">
+        <description summary="photo content type">
+          The content type photo describes content derived from digital still
+          pictures and may be presented with minimal processing.
+        </description>
+      </entry>
+      <entry name="video" value="2">
+        <description summary="video content type">
+          The content type video describes a video or animation and may be
+          presented with more accurate timing to avoid stutter. Where scaling
+          is needed, scaling methods more appropriate for video may be used.
+        </description>
+      </entry>
+      <entry name="game" value="3">
+        <description summary="game content type">
+          The content type game describes a running game. Its content may be
+          presented with reduced latency.
+        </description>
+      </entry>
+    </enum>
+
+    <request name="set_content_type">
+      <description summary="specify the content type">
+        Set the surface content type. This informs the compositor that the
+        client believes it is displaying buffers matching this content type.
+
+        This is purely a hint for the compositor, which can be used to adjust
+        its behavior or hardware settings to fit the presented content best.
+
+        The content type is double-buffered state, see wl_surface.commit for
+        details.
+      </description>
+      <arg name="content_type" type="uint" enum="type"
+           summary="the content type"/>
+    </request>
+  </interface>
+</protocol>

staging/cursor-shape/README

@@ -0,0 +1,4 @@
+cursor-shape protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr> (@emersion)

staging/cursor-shape/cursor-shape-v1.xml

@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="cursor_shape_v1">
+  <copyright>
+    Copyright 2018 The Chromium Authors
+    Copyright 2023 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_cursor_shape_manager_v1" version="2">
+    <description summary="cursor shape manager">
+      This global offers an alternative, optional way to set cursor images. This
+      new way uses enumerated cursors instead of a wl_surface like
+      wl_pointer.set_cursor does.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the cursor shape manager.
+      </description>
+    </request>
+
+    <request name="get_pointer">
+      <description summary="manage the cursor shape of a pointer device">
+        Obtain a wp_cursor_shape_device_v1 for a wl_pointer object.
+
+        When the pointer capability is removed from the wl_seat, the
+        wp_cursor_shape_device_v1 object becomes inert.
+      </description>
+      <arg name="cursor_shape_device" type="new_id" interface="wp_cursor_shape_device_v1"/>
+      <arg name="pointer" type="object" interface="wl_pointer"/>
+    </request>
+
+    <request name="get_tablet_tool_v2">
+      <description summary="manage the cursor shape of a tablet tool device">
+        Obtain a wp_cursor_shape_device_v1 for a zwp_tablet_tool_v2 object.
+
+        When the zwp_tablet_tool_v2 is removed, the wp_cursor_shape_device_v1
+        object becomes inert.
+      </description>
+      <arg name="cursor_shape_device" type="new_id" interface="wp_cursor_shape_device_v1"/>
+      <arg name="tablet_tool" type="object" interface="zwp_tablet_tool_v2"/>
+    </request>
+  </interface>
+
+  <interface name="wp_cursor_shape_device_v1" version="2">
+    <description summary="cursor shape for a device">
+      This interface allows clients to set the cursor shape.
+    </description>
+
+    <enum name="shape">
+      <description summary="cursor shapes">
+        This enum describes cursor shapes.
+
+        The names are taken from the CSS W3C specification:
+        https://w3c.github.io/csswg-drafts/css-ui/#cursor
+        with a few additions.
+
+        Note that there are some groups of cursor shapes that are related:
+        The first group is drag-and-drop cursors which are used to indicate
+        the selected action during dnd operations. The second group is resize
+        cursors which are used to indicate resizing and moving possibilities
+        on window borders. It is recommended that the shapes in these groups
+        should use visually compatible images and metaphors.
+      </description>
+      <entry name="default" value="1" summary="default cursor"/>
+      <entry name="context_menu" value="2" summary="a context menu is available for the object under the cursor"/>
+      <entry name="help" value="3" summary="help is available for the object under the cursor"/>
+      <entry name="pointer" value="4" summary="pointer that indicates a link or another interactive element"/>
+      <entry name="progress" value="5" summary="progress indicator"/>
+      <entry name="wait" value="6" summary="program is busy, user should wait"/>
+      <entry name="cell" value="7" summary="a cell or set of cells may be selected"/>
+      <entry name="crosshair" value="8" summary="simple crosshair"/>
+      <entry name="text" value="9" summary="text may be selected"/>
+      <entry name="vertical_text" value="10" summary="vertical text may be selected"/>
+      <entry name="alias" value="11" summary="drag-and-drop: alias of/shortcut to something is to be created"/>
+      <entry name="copy" value="12" summary="drag-and-drop: something is to be copied"/>
+      <entry name="move" value="13" summary="drag-and-drop: something is to be moved"/>
+      <entry name="no_drop" value="14" summary="drag-and-drop: the dragged item cannot be dropped at the current cursor location"/>
+      <entry name="not_allowed" value="15" summary="drag-and-drop: the requested action will not be carried out"/>
+      <entry name="grab" value="16" summary="drag-and-drop: something can be grabbed"/>
+      <entry name="grabbing" value="17" summary="drag-and-drop: something is being grabbed"/>
+      <entry name="e_resize" value="18" summary="resizing: the east border is to be moved"/>
+      <entry name="n_resize" value="19" summary="resizing: the north border is to be moved"/>
+      <entry name="ne_resize" value="20" summary="resizing: the north-east corner is to be moved"/>
+      <entry name="nw_resize" value="21" summary="resizing: the north-west corner is to be moved"/>
+      <entry name="s_resize" value="22" summary="resizing: the south border is to be moved"/>
+      <entry name="se_resize" value="23" summary="resizing: the south-east corner is to be moved"/>
+      <entry name="sw_resize" value="24" summary="resizing: the south-west corner is to be moved"/>
+      <entry name="w_resize" value="25" summary="resizing: the west border is to be moved"/>
+      <entry name="ew_resize" value="26" summary="resizing: the east and west borders are to be moved"/>
+      <entry name="ns_resize" value="27" summary="resizing: the north and south borders are to be moved"/>
+      <entry name="nesw_resize" value="28" summary="resizing: the north-east and south-west corners are to be moved"/>
+      <entry name="nwse_resize" value="29" summary="resizing: the north-west and south-east corners are to be moved"/>
+      <entry name="col_resize" value="30" summary="resizing: that the item/column can be resized horizontally"/>
+      <entry name="row_resize" value="31" summary="resizing: that the item/row can be resized vertically"/>
+      <entry name="all_scroll" value="32" summary="something can be scrolled in any direction"/>
+      <entry name="zoom_in" value="33" summary="something can be zoomed in"/>
+      <entry name="zoom_out" value="34" summary="something can be zoomed out"/>
+      <entry name="dnd_ask" value="35" summary="drag-and-drop: the user will select which action will be carried out (non-css value)" since="2"/>
+      <entry name="all_resize" value="36" summary="resizing: something can be moved or resized in any direction (non-css value)" since="2"/>
+    </enum>
+
+    <enum name="error">
+      <entry name="invalid_shape" value="1"
+        summary="the specified shape value is invalid"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the cursor shape device">
+        Destroy the cursor shape device.
+
+        The device cursor shape remains unchanged.
+      </description>
+    </request>
+
+    <request name="set_shape">
+      <description summary="set device cursor to the shape">
+        Sets the device cursor to the specified shape. The compositor will
+        change the cursor image based on the specified shape.
+
+        The cursor actually changes only if the input device focus is one of
+        the requesting client's surfaces. If any, the previous cursor image
+        (surface or shape) is replaced.
+
+        The "shape" argument must be a valid enum entry, otherwise the
+        invalid_shape protocol error is raised.
+
+        This is similar to the wl_pointer.set_cursor and
+        zwp_tablet_tool_v2.set_cursor requests, but this request accepts a
+        shape instead of contents in the form of a surface. Clients can mix
+        set_cursor and set_shape requests.
+
+        The serial parameter must match the latest wl_pointer.enter or
+        zwp_tablet_tool_v2.proximity_in serial number sent to the client.
+        Otherwise the request will be ignored.
+      </description>
+      <arg name="serial" type="uint" summary="serial number of the enter event"/>
+      <arg name="shape" type="uint" enum="shape"/>
+    </request>
+  </interface>
+</protocol>

staging/drm-lease/README

@@ -0,0 +1,6 @@
+Linux DRM lease
+
+Maintainers:
+Simon Zeni <simon@bl4ckb0ne.ca> (@bl4ckb0ne)
+Marius Vlad <marius.vlad@collabora.com> (@mvlad)
+Xaver Hugl <xaver.hugl@gmail.com> (@Zamundaaa)

staging/drm-lease/drm-lease-v1.xml

@@ -0,0 +1,317 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="drm_lease_v1">
+  <copyright>
+    Copyright © 2018 NXP
+    Copyright © 2019 Status Research &amp; Development GmbH.
+    Copyright © 2021 Xaver Hugl
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_drm_lease_device_v1" version="1">
+    <description summary="lease device">
+      This protocol is used by Wayland compositors which act as Direct
+      Rendering Manager (DRM) masters to lease DRM resources to Wayland
+      clients.
+
+      The compositor will advertise one wp_drm_lease_device_v1 global for each
+      DRM node. Some time after a client binds to the wp_drm_lease_device_v1
+      global, the compositor will send a drm_fd event followed by zero, one or
+      more connector events. After all currently available connectors have been
+      sent, the compositor will send a wp_drm_lease_device_v1.done event.
+
+      When the list of connectors available for lease changes the compositor
+      will send wp_drm_lease_device_v1.connector events for added connectors and
+      wp_drm_lease_connector_v1.withdrawn events for removed connectors,
+      followed by a wp_drm_lease_device_v1.done event.
+
+      The compositor will indicate when a device is gone by removing the global
+      via a wl_registry.global_remove event. Upon receiving this event, the
+      client should destroy any matching wp_drm_lease_device_v1 object.
+
+      To destroy a wp_drm_lease_device_v1 object, the client must first issue
+      a release request. Upon receiving this request, the compositor will
+      immediately send a released event and destroy the object. The client must
+      continue to process and discard drm_fd and connector events until it
+      receives the released event. Upon receiving the released event, the
+      client can safely cleanup any client-side resources.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="create_lease_request">
+      <description summary="create a lease request object">
+        Creates a lease request object.
+
+        See the documentation for wp_drm_lease_request_v1 for details.
+      </description>
+      <arg name="id" type="new_id" interface="wp_drm_lease_request_v1" />
+    </request>
+
+    <request name="release">
+      <description summary="release this object">
+        Indicates the client no longer wishes to use this object. In response
+        the compositor will immediately send the released event and destroy
+        this object. It can however not guarantee that the client won't receive
+        connector events before the released event. The client must not send any
+        requests after this one, doing so will raise a wl_display error.
+        Existing connectors, lease request and leases will not be affected.
+      </description>
+    </request>
+
+    <event name="drm_fd">
+      <description summary="open a non-master fd for this DRM node">
+        The compositor will send this event when the wp_drm_lease_device_v1
+        global is bound, although there are no guarantees as to how long this
+        takes - the compositor might need to wait until regaining DRM master.
+        The included fd is a non-master DRM file descriptor opened for this
+        device and the compositor must not authenticate it.
+        The purpose of this event is to give the client the ability to
+        query DRM and discover information which may help them pick the
+        appropriate DRM device or select the appropriate connectors therein.
+      </description>
+      <arg name="fd" type="fd" summary="DRM file descriptor" />
+    </event>
+
+    <event name="connector">
+      <description summary="advertise connectors available for leases">
+        The compositor will use this event to advertise connectors available for
+        lease by clients. This object may be passed into a lease request to
+        indicate the client would like to lease that connector, see
+        wp_drm_lease_request_v1.request_connector for details. While the
+        compositor will make a best effort to not send disconnected connectors,
+        no guarantees can be made.
+
+        The compositor must send the drm_fd event before sending connectors.
+        After the drm_fd event it will send all available connectors but may
+        send additional connectors at any time.
+      </description>
+      <arg name="id" type="new_id" interface="wp_drm_lease_connector_v1" />
+    </event>
+
+    <event name="done">
+      <description summary="signals grouping of connectors">
+        The compositor will send this event to indicate that it has sent all
+        currently available connectors after the client binds to the global or
+        when it updates the connector list, for example on hotplug, drm master
+        change or when a leased connector becomes available again. It will
+        similarly send this event to group wp_drm_lease_connector_v1.withdrawn
+        events of connectors of this device.
+      </description>
+    </event>
+
+    <event name="released" type="destructor">
+      <description summary="the compositor has finished using the device">
+        This event is sent in response to the release request and indicates
+        that the compositor is done sending connector events.
+        The compositor will destroy this object immediately after sending the
+        event and it will become invalid. The client should release any
+        resources associated with this device after receiving this event.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="wp_drm_lease_connector_v1" version="1">
+    <description summary="a leasable DRM connector">
+      Represents a DRM connector which is available for lease. These objects are
+      created via wp_drm_lease_device_v1.connector events, and should be passed
+      to lease requests via wp_drm_lease_request_v1.request_connector.
+      Immediately after the wp_drm_lease_connector_v1 object is created the
+      compositor will send a name, a description, a connector_id and a done
+      event. When the description is updated the compositor will send a
+      description event followed by a done event.
+    </description>
+
+    <event name="name">
+      <description summary="name">
+        The compositor sends this event once the connector is created to
+        indicate the name of this connector. This will not change for the
+        duration of the Wayland session, but is not guaranteed to be consistent
+        between sessions.
+
+        If the compositor supports wl_output version 4 and this connector
+        corresponds to a wl_output, the compositor should use the same name as
+        for the wl_output.
+      </description>
+      <arg name="name" type="string" summary="connector name" />
+    </event>
+
+    <event name="description">
+      <description summary="description">
+        The compositor sends this event once the connector is created to provide
+        a human-readable description for this connector, which may be presented
+        to the user. The compositor may send this event multiple times over the
+        lifetime of this object to reflect changes in the description.
+      </description>
+      <arg name="description" type="string" summary="connector description" />
+    </event>
+
+    <event name="connector_id">
+      <description summary="connector_id">
+        The compositor sends this event once the connector is created to
+        indicate the DRM object ID which represents the underlying connector
+        that is being offered. Note that the final lease may include additional
+        object IDs, such as CRTCs and planes.
+      </description>
+      <arg name="connector_id" type="uint" summary="DRM connector ID" />
+    </event>
+
+    <event name="done">
+      <description summary="all properties have been sent">
+        This event is sent after all properties of a connector have been sent.
+        This allows changes to the properties to be seen as atomic even if they
+        happen via multiple events.
+      </description>
+    </event>
+
+    <event name="withdrawn">
+      <description summary="lease offer withdrawn">
+        Sent to indicate that the compositor will no longer honor requests for
+        DRM leases which include this connector. The client may still issue a
+        lease request including this connector, but the compositor will send
+        wp_drm_lease_v1.finished without issuing a lease fd. Compositors are
+        encouraged to send this event when they lose access to connector, for
+        example when the connector is hot-unplugged, when the connector gets
+        leased to a client or when the compositor loses DRM master.
+
+        If a client holds a lease for the connector, the status of the lease
+        remains the same. The client should destroy the object after receiving
+        this event.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy connector">
+        The client may send this request to indicate that it will not use this
+        connector. Clients are encouraged to send this after receiving the
+        "withdrawn" event so that the server can release the resources
+        associated with this connector offer. Neither existing lease requests
+        nor leases will be affected.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="wp_drm_lease_request_v1" version="1">
+    <description summary="DRM lease request">
+      A client that wishes to lease DRM resources will attach the list of
+      connectors advertised with wp_drm_lease_device_v1.connector that they
+      wish to lease, then use wp_drm_lease_request_v1.submit to submit the
+      request.
+    </description>
+
+    <enum name="error">
+      <entry name="wrong_device" value="0"
+             summary="requested a connector from a different lease device"/>
+      <entry name="duplicate_connector" value="1"
+             summary="requested a connector twice"/>
+      <entry name="empty_lease" value="2"
+             summary="requested a lease without requesting a connector"/>
+    </enum>
+
+    <request name="request_connector">
+      <description summary="request a connector for this lease">
+        Indicates that the client would like to lease the given connector.
+        This is only used as a suggestion, the compositor may choose to
+        include any resources in the lease it issues, or change the set of
+        leased resources at any time. Compositors are however encouraged to
+        include the requested connector and other resources necessary
+        to drive the connected output in the lease.
+
+        Requesting a connector that was created from a different lease device
+        than this lease request raises the wrong_device error. Requesting a
+        connector twice will raise the duplicate_connector error.
+      </description>
+      <arg name="connector" type="object"
+           interface="wp_drm_lease_connector_v1" />
+    </request>
+
+    <request name="submit" type="destructor">
+      <description summary="submit the lease request">
+        Submits the lease request and creates a new wp_drm_lease_v1 object.
+        After calling submit the compositor will immediately destroy this
+        object, issuing any more requests will cause a wl_display error.
+        The compositor doesn't make any guarantees about the events of the
+        lease object, clients cannot expect an immediate response.
+        Not requesting any connectors before submitting the lease request
+        will raise the empty_lease error.
+      </description>
+      <arg name="id" type="new_id" interface="wp_drm_lease_v1" />
+    </request>
+  </interface>
+
+  <interface name="wp_drm_lease_v1" version="1">
+    <description summary="a DRM lease">
+      A DRM lease object is used to transfer the DRM file descriptor to the
+      client and manage the lifetime of the lease.
+
+      Some time after the wp_drm_lease_v1 object is created, the compositor
+      will reply with the lease request's result. If the lease request is
+      granted, the compositor will send a lease_fd event. If the lease request
+      is denied, the compositor will send a finished event without a lease_fd
+      event.
+    </description>
+
+    <event name="lease_fd">
+      <description summary="shares the DRM file descriptor">
+        This event returns a file descriptor suitable for use with DRM-related
+        ioctls. The client should use drmModeGetLease to enumerate the DRM
+        objects which have been leased to them. The compositor guarantees it
+        will not use the leased DRM objects itself until it sends the finished
+        event. If the compositor cannot or will not grant a lease for the
+        requested connectors, it will not send this event, instead sending the
+        finished event.
+
+        The compositor will send this event at most once during this objects
+        lifetime.
+      </description>
+      <arg name="leased_fd" type="fd" summary="leased DRM file descriptor" />
+    </event>
+
+    <event name="finished">
+      <description summary="sent when the lease has been revoked">
+        The compositor uses this event to either reject a lease request, or if
+        it previously sent a lease_fd, to notify the client that the lease has
+        been revoked. If the client requires a new lease, they should destroy
+        this object and submit a new lease request. The compositor will send
+        no further events for this object after sending the finish event.
+        Compositors should revoke the lease when any of the leased resources
+        become unavailable, namely when a hot-unplug occurs or when the
+        compositor loses DRM master. Compositors may advertise the connector
+        for leasing again, if the resource is available, by sending the
+        connector event through the wp_drm_lease_device_v1 interface.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroys the lease object">
+        The client should send this to indicate that it no longer wishes to use
+        this lease. The compositor should use drmModeRevokeLease on the
+        appropriate file descriptor, if necessary.
+
+        Upon destruction, the compositor should advertise the connector for
+        leasing again by sending the connector event through the
+        wp_drm_lease_device_v1 interface.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/ext-background-effect/README

@@ -0,0 +1,6 @@
+ext_blur protocol
+
+Maintainers:
+David Edmundson <davidedmundson@kde.org>
+Vlad Zahorodnii <vlad.zahorodnii@kde.org>
+Xaver Hugl <xaver.hugl@kde.org>

staging/ext-background-effect/ext-background-effect-v1.xml

@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_background_effect_v1">
+  <copyright>
+    Copyright (C) 2015 Martin Gräßlin
+    Copyright (C) 2015 Marco Martin
+    Copyright (C) 2020 Vlad Zahorodnii
+    Copyright (C) 2024 Xaver Hugl
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="ext_background_effect_manager_v1" version="1">
+    <description summary="background effect factory">
+      This protocol provides a way to improve visuals of translucent surfaces
+      by applying effects like blur to the background behind them.
+
+      The capabilities are send when the global is bound, and every time they
+      change. Note that when the capability goes away, the corresponding effect
+      is no longer applied by the compositor, even if it was set before.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the background effect manager">
+        Informs the server that the client will no longer be using this
+        protocol object. Existing objects created by this object are not
+        affected.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="background_effect_exists" value="0"
+             summary="the surface already has a background effect object"/>
+    </enum>
+
+    <enum name="capability" bitfield="true">
+      <entry name="blur" value="1"
+             summary="the compositor supports applying blur"/>
+    </enum>
+
+    <event name="capabilities">
+      <description summary="capabilities of the compositor"/>
+      <arg name="flags" type="uint" enum="capability"/>
+    </event>
+
+    <request name="get_background_effect">
+      <description summary="get a background effects object">
+        Instantiate an interface extension for the given wl_surface to add
+        effects like blur for the background behind it.
+
+        If the given wl_surface already has a ext_background_effect_surface_v1
+        object associated, the background_effect_exists protocol error will be
+        raised.
+      </description>
+      <arg name="id" type="new_id" interface="ext_background_effect_surface_v1"
+           summary="the new ext_background_effect_surface_v1 object"/>
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="the surface"/>
+    </request>
+  </interface>
+
+  <interface name="ext_background_effect_surface_v1" version="1">
+    <description summary="background effects for a surface">
+      The background effect object provides a way to specify a region behind
+      a surface that should have background effects like blur applied.
+
+      If the wl_surface associated with the ext_background_effect_surface_v1
+      object has been destroyed, this object becomes inert.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="release the blur object">
+        Informs the server that the client will no longer be using this protocol
+        object. The effect regions will be removed on the next commit.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="surface_destroyed" value="0"
+             summary="the associated surface has been destroyed"/>
+    </enum>
+
+    <request name="set_blur_region">
+      <description summary="set blur region">
+        This request sets the region of the surface that will have its
+        background blurred.
+
+        The blur region is specified in the surface-local coordinates, and
+        clipped by the compositor to the surface size.
+
+        The initial value for the blur region is empty. Setting the pending
+        blur region has copy semantics, and the wl_region object can be
+        destroyed immediately. A NULL wl_region removes the effect.
+
+        The blur region is double-buffered state, and will be applied on
+        the next wl_surface.commit.
+
+        The blur algorithm is subject to compositor policies.
+
+        If the associated surface has been destroyed, the surface_destroyed
+        error will be raised.
+      </description>
+      <arg name="region" type="object" interface="wl_region" allow-null="true"
+           summary="blur region of the surface"/>
+    </request>
+
+  </interface>
+</protocol>

staging/ext-data-control/README

@@ -0,0 +1,4 @@
+data-control protocol
+
+Maintainers:
+Neal Gompa <neal@gompa.dev> (@Conan_Kudo)

staging/ext-data-control/ext-data-control-v1.xml

@@ -0,0 +1,276 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_data_control_v1">
+  <copyright>
+    Copyright © 2018 Simon Ser
+    Copyright © 2019 Ivan Molodetskikh
+    Copyright © 2024 Neal Gompa
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+    THIS SOFTWARE.
+  </copyright>
+
+  <description summary="control data devices">
+    This protocol allows a privileged client to control data devices. In
+    particular, the client will be able to manage the current selection and take
+    the role of a clipboard manager.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="ext_data_control_manager_v1" version="1">
+    <description summary="manager to control data devices">
+      This interface is a manager that allows creating per-seat data device
+      controls.
+    </description>
+
+    <request name="create_data_source">
+      <description summary="create a new data source">
+        Create a new data source.
+      </description>
+      <arg name="id" type="new_id" interface="ext_data_control_source_v1"
+        summary="data source to create"/>
+    </request>
+
+    <request name="get_data_device">
+      <description summary="get a data device for a seat">
+        Create a data device that can be used to manage a seat's selection.
+      </description>
+      <arg name="id" type="new_id" interface="ext_data_control_device_v1"/>
+      <arg name="seat" type="object" interface="wl_seat"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        All objects created by the manager will still remain valid, until their
+        appropriate destroy request has been called.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_data_control_device_v1" version="1">
+    <description summary="manage a data device for a seat">
+      This interface allows a client to manage a seat's selection.
+
+      When the seat is destroyed, this object becomes inert.
+    </description>
+
+    <request name="set_selection">
+      <description summary="copy data to the selection">
+        This request asks the compositor to set the selection to the data from
+        the source on behalf of the client.
+
+        The given source may not be used in any further set_selection or
+        set_primary_selection requests. Attempting to use a previously used
+        source triggers the used_source protocol error.
+
+        To unset the selection, set the source to NULL.
+      </description>
+      <arg name="source" type="object" interface="ext_data_control_source_v1"
+        allow-null="true"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this data device">
+        Destroys the data device object.
+      </description>
+    </request>
+
+    <event name="data_offer">
+      <description summary="introduce a new ext_data_control_offer">
+        The data_offer event introduces a new ext_data_control_offer object,
+        which will subsequently be used in either the
+        ext_data_control_device.selection event (for the regular clipboard
+        selections) or the ext_data_control_device.primary_selection event (for
+        the primary clipboard selections). Immediately following the
+        ext_data_control_device.data_offer event, the new data_offer object
+        will send out ext_data_control_offer.offer events to describe the MIME
+        types it offers.
+      </description>
+      <arg name="id" type="new_id" interface="ext_data_control_offer_v1"/>
+    </event>
+
+    <event name="selection">
+      <description summary="advertise new selection">
+        The selection event is sent out to notify the client of a new
+        ext_data_control_offer for the selection for this device. The
+        ext_data_control_device.data_offer and the ext_data_control_offer.offer
+        events are sent out immediately before this event to introduce the data
+        offer object. The selection event is sent to a client when a new
+        selection is set. The ext_data_control_offer is valid until a new
+        ext_data_control_offer or NULL is received. The client must destroy the
+        previous selection ext_data_control_offer, if any, upon receiving this
+        event. Regardless, the previous selection will be ignored once a new
+        selection ext_data_control_offer is received.
+
+        The first selection event is sent upon binding the
+        ext_data_control_device object.
+      </description>
+      <arg name="id" type="object" interface="ext_data_control_offer_v1"
+        allow-null="true"/>
+    </event>
+
+    <event name="finished">
+      <description summary="this data control is no longer valid">
+        This data control object is no longer valid and should be destroyed by
+        the client.
+      </description>
+    </event>
+
+    <event name="primary_selection">
+      <description summary="advertise new primary selection">
+        The primary_selection event is sent out to notify the client of a new
+        ext_data_control_offer for the primary selection for this device. The
+        ext_data_control_device.data_offer and the ext_data_control_offer.offer
+        events are sent out immediately before this event to introduce the data
+        offer object. The primary_selection event is sent to a client when a
+        new primary selection is set. The ext_data_control_offer is valid until
+        a new ext_data_control_offer or NULL is received. The client must
+        destroy the previous primary selection ext_data_control_offer, if any,
+        upon receiving this event. Regardless, the previous primary selection
+        will be ignored once a new primary selection ext_data_control_offer is
+        received.
+
+        If the compositor supports primary selection, the first
+        primary_selection event is sent upon binding the
+        ext_data_control_device object.
+      </description>
+      <arg name="id" type="object" interface="ext_data_control_offer_v1"
+        allow-null="true"/>
+    </event>
+
+    <request name="set_primary_selection">
+      <description summary="copy data to the primary selection">
+        This request asks the compositor to set the primary selection to the
+        data from the source on behalf of the client.
+
+        The given source may not be used in any further set_selection or
+        set_primary_selection requests. Attempting to use a previously used
+        source triggers the used_source protocol error.
+
+        To unset the primary selection, set the source to NULL.
+
+        The compositor will ignore this request if it does not support primary
+        selection.
+      </description>
+      <arg name="source" type="object" interface="ext_data_control_source_v1"
+        allow-null="true"/>
+    </request>
+
+    <enum name="error">
+      <entry name="used_source" value="1"
+        summary="source given to set_selection or set_primary_selection was already used before"/>
+    </enum>
+  </interface>
+
+  <interface name="ext_data_control_source_v1" version="1">
+    <description summary="offer to transfer data">
+      The ext_data_control_source object is the source side of a
+      ext_data_control_offer. It is created by the source client in a data
+      transfer and provides a way to describe the offered data and a way to
+      respond to requests to transfer the data.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_offer" value="1"
+        summary="offer sent after ext_data_control_device.set_selection"/>
+    </enum>
+
+    <request name="offer">
+      <description summary="add an offered MIME type">
+        This request adds a MIME type to the set of MIME types advertised to
+        targets. Can be called several times to offer multiple types.
+
+        Calling this after ext_data_control_device.set_selection is a protocol
+        error.
+      </description>
+      <arg name="mime_type" type="string"
+        summary="MIME type offered by the data source"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this source">
+        Destroys the data source object.
+      </description>
+    </request>
+
+    <event name="send">
+      <description summary="send the data">
+        Request for data from the client. Send the data as the specified MIME
+        type over the passed file descriptor, then close it.
+      </description>
+      <arg name="mime_type" type="string" summary="MIME type for the data"/>
+      <arg name="fd" type="fd" summary="file descriptor for the data"/>
+    </event>
+
+    <event name="cancelled">
+      <description summary="selection was cancelled">
+        This data source is no longer valid. The data source has been replaced
+        by another data source.
+
+        The client should clean up and destroy this data source.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="ext_data_control_offer_v1" version="1">
+    <description summary="offer to transfer data">
+      A ext_data_control_offer represents a piece of data offered for transfer
+      by another client (the source client). The offer describes the different
+      MIME types that the data can be converted to and provides the mechanism
+      for transferring the data directly from the source client.
+    </description>
+
+    <request name="receive">
+      <description summary="request that the data is transferred">
+        To transfer the offered data, the client issues this request and
+        indicates the MIME type it wants to receive. The transfer happens
+        through the passed file descriptor (typically created with the pipe
+        system call). The source client writes the data in the MIME type
+        representation requested and then closes the file descriptor.
+
+        The receiving client reads from the read end of the pipe until EOF and
+        then closes its end, at which point the transfer is complete.
+
+        This request may happen multiple times for different MIME types.
+      </description>
+      <arg name="mime_type" type="string"
+        summary="MIME type desired by receiver"/>
+      <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this offer">
+        Destroys the data offer object.
+      </description>
+    </request>
+
+    <event name="offer">
+      <description summary="advertise offered MIME type">
+        Sent immediately after creating the ext_data_control_offer object.
+        One event per offered MIME type.
+      </description>
+      <arg name="mime_type" type="string" summary="offered MIME type"/>
+    </event>
+  </interface>
+</protocol>

staging/ext-foreign-toplevel-list/README

@@ -0,0 +1,4 @@
+Foreign toplevel list protocol
+
+Maintainers:
+i509VCB <mail@i509.me> (@i509VCB)

staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml

@@ -0,0 +1,219 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_foreign_toplevel_list_v1">
+  <copyright>
+    Copyright © 2018 Ilia Bozhinov
+    Copyright © 2020 Isaac Freund
+    Copyright © 2022 wb9688
+    Copyright © 2023 i509VCB
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+    THIS SOFTWARE.
+  </copyright>
+
+  <description summary="list toplevels">
+    The purpose of this protocol is to provide protocol object handles for
+    toplevels, possibly originating from another client.
+
+    This protocol is intentionally minimalistic and expects additional
+    functionality (e.g. creating a screencopy source from a toplevel handle,
+    getting information about the state of the toplevel) to be implemented
+    in extension protocols.
+
+    The compositor may choose to restrict this protocol to a special client
+    launched by the compositor itself or expose it to all clients,
+    this is compositor policy.
+
+    The key words "must", "must not", "required", "shall", "shall not",
+    "should", "should not", "recommended",  "may", and "optional" in this
+    document are to be interpreted as described in IETF RFC 2119.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="ext_foreign_toplevel_list_v1" version="1">
+    <description summary="list toplevels">
+      A toplevel is defined as a surface with a role similar to xdg_toplevel.
+      XWayland surfaces may be treated like toplevels in this protocol.
+
+      After a client binds the ext_foreign_toplevel_list_v1, each mapped
+      toplevel window will be sent using the ext_foreign_toplevel_list_v1.toplevel
+      event.
+
+      Clients which only care about the current state can perform a roundtrip after
+      binding this global.
+
+      For each instance of ext_foreign_toplevel_list_v1, the compositor must
+      create a new ext_foreign_toplevel_handle_v1 object for each mapped toplevel.
+
+      If a compositor implementation sends the ext_foreign_toplevel_list_v1.finished
+      event after the global is bound, the compositor must not send any
+      ext_foreign_toplevel_list_v1.toplevel events.
+    </description>
+
+    <event name="toplevel">
+      <description summary="a toplevel has been created">
+        This event is emitted whenever a new toplevel window is created. It is
+        emitted for all toplevels, regardless of the app that has created them.
+
+        All initial properties of the toplevel (identifier, title, app_id) will be sent
+        immediately after this event using the corresponding events for
+        ext_foreign_toplevel_handle_v1. The compositor will use the
+        ext_foreign_toplevel_handle_v1.done event to indicate when all data has
+        been sent.
+      </description>
+      <arg name="toplevel" type="new_id" interface="ext_foreign_toplevel_handle_v1"/>
+    </event>
+
+    <event name="finished">
+      <description summary="the compositor has finished with the toplevel manager">
+        This event indicates that the compositor is done sending events
+        to this object. The client should destroy the object.
+        See ext_foreign_toplevel_list_v1.destroy for more information.
+
+        The compositor must not send any more toplevel events after this event.
+      </description>
+    </event>
+
+    <request name="stop">
+      <description summary="stop sending events">
+        This request indicates that the client no longer wishes to receive
+        events for new toplevels.
+
+        The Wayland protocol is asynchronous, meaning the compositor may send
+        further toplevel events until the stop request is processed.
+        The client should wait for a ext_foreign_toplevel_list_v1.finished
+        event before destroying this object.
+      </description>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the ext_foreign_toplevel_list_v1 object">
+        This request should be called either when the client will no longer
+        use the ext_foreign_toplevel_list_v1 or after the finished event
+        has been received to allow destruction of the object.
+
+        If a client wishes to destroy this object it should send a
+        ext_foreign_toplevel_list_v1.stop request and wait for a ext_foreign_toplevel_list_v1.finished
+        event, then destroy the handles and then this object.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_foreign_toplevel_handle_v1" version="1">
+    <description summary="a mapped toplevel">
+      A ext_foreign_toplevel_handle_v1 object represents a mapped toplevel
+      window. A single app may have multiple mapped toplevels.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the ext_foreign_toplevel_handle_v1 object">
+        This request should be used when the client will no longer use the handle
+        or after the closed event has been received to allow destruction of the
+        object.
+
+        When a handle is destroyed, a new handle may not be created by the server
+        until the toplevel is unmapped and then remapped. Destroying a toplevel handle
+        is not recommended unless the client is cleaning up child objects
+        before destroying the ext_foreign_toplevel_list_v1 object, the toplevel
+        was closed or the toplevel handle will not be used in the future.
+
+        Other protocols which extend the ext_foreign_toplevel_handle_v1
+        interface should require destructors for extension interfaces be
+        called before allowing the toplevel handle to be destroyed.
+      </description>
+    </request>
+
+    <event name="closed">
+      <description summary="the toplevel has been closed">
+        The server will emit no further events on the ext_foreign_toplevel_handle_v1
+        after this event. Any requests received aside from the destroy request must
+        be ignored. Upon receiving this event, the client should destroy the handle.
+
+        Other protocols which extend the ext_foreign_toplevel_handle_v1
+        interface must also ignore requests other than destructors.
+      </description>
+    </event>
+
+    <event name="done">
+      <description summary="all information about the toplevel has been sent">
+        This event is sent after all changes in the toplevel state have
+        been sent.
+
+        This allows changes to the ext_foreign_toplevel_handle_v1 properties
+        to be atomically applied. Other protocols which extend the
+        ext_foreign_toplevel_handle_v1 interface may use this event to also
+        atomically apply any pending state.
+
+        This event must not be sent after the ext_foreign_toplevel_handle_v1.closed
+        event.
+      </description>
+    </event>
+
+    <event name="title">
+      <description summary="title change">
+        The title of the toplevel has changed.
+
+        The configured state must not be applied immediately. See
+        ext_foreign_toplevel_handle_v1.done for details.
+      </description>
+      <arg name="title" type="string"/>
+    </event>
+
+    <event name="app_id">
+      <description summary="app_id change">
+        The app id of the toplevel has changed.
+
+        The configured state must not be applied immediately. See
+        ext_foreign_toplevel_handle_v1.done for details.
+      </description>
+      <arg name="app_id" type="string"/>
+    </event>
+
+    <event name="identifier">
+      <description summary="a stable identifier for a toplevel">
+        This identifier is used to check if two or more toplevel handles belong
+        to the same toplevel.
+
+        The identifier is useful for command line tools or privileged clients
+        which may need to reference an exact toplevel across processes or
+        instances of the ext_foreign_toplevel_list_v1 global.
+
+        The compositor must only send this event when the handle is created.
+
+        The identifier must be unique per toplevel and its handles. Two different
+        toplevels must not have the same identifier. The identifier is only valid
+        as long as the toplevel is mapped. If the toplevel is unmapped the identifier
+        must not be reused. An identifier must not be reused by the compositor to
+        ensure there are no races when sharing identifiers between processes.
+
+        An identifier is a string that contains up to 32 printable ASCII bytes.
+        An identifier must not be an empty string. It is recommended that a
+        compositor includes an opaque generation value in identifiers. How the
+        generation value is used when generating the identifier is implementation
+        dependent.
+      </description>
+      <arg name="identifier" type="string"/>
+    </event>
+  </interface>
+</protocol>

staging/ext-idle-notify/README

@@ -0,0 +1,4 @@
+idle_notify protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr> (@emersion)

staging/ext-idle-notify/ext-idle-notify-v1.xml

@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_idle_notify_v1">
+  <copyright>
+    Copyright © 2015 Martin Gräßlin
+    Copyright © 2022 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="ext_idle_notifier_v1" version="2">
+    <description summary="idle notification manager">
+      This interface allows clients to monitor user idle status.
+
+      After binding to this global, clients can create ext_idle_notification_v1
+      objects to get notified when the user is idle for a given amount of time.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the manager object. All objects created via this interface
+        remain valid.
+      </description>
+    </request>
+
+    <request name="get_idle_notification">
+      <description summary="create a notification object">
+        Create a new idle notification object.
+
+        The notification object has a minimum timeout duration and is tied to a
+        seat. The client will be notified if the seat is inactive for at least
+        the provided timeout. See ext_idle_notification_v1 for more details.
+
+        A zero timeout is valid and means the client wants to be notified as
+        soon as possible when the seat is inactive.
+      </description>
+      <arg name="id" type="new_id" interface="ext_idle_notification_v1"/>
+      <arg name="timeout" type="uint" summary="minimum idle timeout in msec"/>
+      <arg name="seat" type="object" interface="wl_seat"/>
+    </request>
+
+    <!-- Version 2 additions -->
+
+    <request name="get_input_idle_notification" since="2">
+      <description summary="create a notification object">
+        Create a new idle notification object to track input from the
+        user, such as keyboard and mouse movement. Because this object is
+        meant to track user input alone, it ignores idle inhibitors.
+
+        The notification object has a minimum timeout duration and is tied to a
+        seat. The client will be notified if the seat is inactive for at least
+        the provided timeout. See ext_idle_notification_v1 for more details.
+
+        A zero timeout is valid and means the client wants to be notified as
+        soon as possible when the seat is inactive.
+      </description>
+      <arg name="id" type="new_id" interface="ext_idle_notification_v1"/>
+      <arg name="timeout" type="uint" summary="minimum idle timeout in msec"/>
+      <arg name="seat" type="object" interface="wl_seat"/>
+    </request>
+    
+  </interface>
+
+  <interface name="ext_idle_notification_v1" version="2">
+    <description summary="idle notification">
+      This interface is used by the compositor to send idle notification events
+      to clients.
+
+      Initially the notification object is not idle. The notification object
+      becomes idle when no user activity has happened for at least the timeout
+      duration, starting from the creation of the notification object. User
+      activity may include input events or a presence sensor, but is
+      compositor-specific.
+
+      How this notification responds to idle inhibitors depends on how
+      it was constructed. If constructed from the
+      get_idle_notification request, then if an idle inhibitor is
+      active (e.g. another client has created a zwp_idle_inhibitor_v1
+      on a visible surface), the compositor must not make the
+      notification object idle. However, if constructed from the
+      get_input_idle_notification request, then idle inhibitors are
+      ignored, and only input from the user, e.g. from a keyboard or
+      mouse, counts as activity.
+
+      When the notification object becomes idle, an idled event is sent. When
+      user activity starts again, the notification object stops being idle,
+      a resumed event is sent and the timeout is restarted.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the notification object">
+        Destroy the notification object.
+      </description>
+    </request>
+
+    <event name="idled">
+      <description summary="notification object is idle">
+        This event is sent when the notification object becomes idle.
+
+        It's a compositor protocol error to send this event twice without a
+        resumed event in-between.
+      </description>
+    </event>
+
+    <event name="resumed">
+      <description summary="notification object is no longer idle">
+        This event is sent when the notification object stops being idle.
+
+        It's a compositor protocol error to send this event twice without an
+        idled event in-between. It's a compositor protocol error to send this
+        event prior to any idled event.
+      </description>
+    </event>
+  </interface>
+</protocol>

staging/ext-image-capture-source/README

@@ -0,0 +1,5 @@
+Image Capture Source Protocol
+
+Maintainers:
+Andri Yngvason <andri@yngvason.is> (@andri)
+Simon Ser <contact@emersion.fr> (@emersion)

staging/ext-image-capture-source/ext-image-capture-source-v1.xml

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_image_capture_source_v1">
+  <copyright>
+    Copyright © 2022 Andri Yngvason
+    Copyright © 2024 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="opaque image capture source objects">
+    This protocol serves as an intermediary between capturing protocols and
+    potential image capture sources such as outputs and toplevels.
+
+    This protocol may be extended to support more image capture sources in the
+    future, thereby adding those image capture sources to other protocols that
+    use the image capture source object without having to modify those
+    protocols.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="ext_image_capture_source_v1" version="1" frozen="true">
+    <description summary="opaque image capture source object">
+      The image capture source object is an opaque descriptor for a capturable
+      resource.  This resource may be any sort of entity from which an image
+      may be derived.
+
+      Note, because ext_image_capture_source_v1 objects are created from multiple
+      independent factory interfaces, the ext_image_capture_source_v1 interface is
+      frozen at version 1.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object">
+        Destroys the image capture source. This request may be sent at any time
+        by the client.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_output_image_capture_source_manager_v1" version="1">
+    <description summary="image capture source manager for outputs">
+      A manager for creating image capture source objects for wl_output objects.
+    </description>
+
+    <request name="create_source">
+      <description summary="create source object for output">
+        Creates a source object for an output. Images captured from this source
+        will show the same content as the output. Some elements may be omitted,
+        such as cursors and overlays that have been marked as transparent to
+        capturing.
+      </description>
+      <arg name="source" type="new_id" interface="ext_image_capture_source_v1"/>
+      <arg name="output" type="object" interface="wl_output"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object">
+        Destroys the manager. This request may be sent at any time by the client
+        and objects created by the manager will remain valid after its
+        destruction.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_foreign_toplevel_image_capture_source_manager_v1" version="1">
+    <description summary="image capture source manager for foreign toplevels">
+      A manager for creating image capture source objects for
+      ext_foreign_toplevel_handle_v1 objects.
+    </description>
+
+    <request name="create_source">
+      <description summary="create source object for foreign toplevel">
+        Creates a source object for a foreign toplevel handle. Images captured
+        from this source will show the same content as the toplevel.
+      </description>
+      <arg name="source" type="new_id" interface="ext_image_capture_source_v1"/>
+      <arg name="toplevel_handle" type="object" interface="ext_foreign_toplevel_handle_v1"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object">
+        Destroys the manager. This request may be sent at any time by the client
+        and objects created by the manager will remain valid after its
+        destruction.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/ext-image-copy-capture/README

@@ -0,0 +1,5 @@
+Image Copy Capture protocol
+
+Maintainers:
+Andri Yngvason <andri@yngvason.is> (@andri)
+Simon Ser <contact@emersion.fr> (@emersion)

staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml

@@ -0,0 +1,456 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_image_copy_capture_v1">
+  <copyright>
+    Copyright © 2021-2023 Andri Yngvason
+    Copyright © 2024 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="image capturing into client buffers">
+    This protocol allows clients to ask the compositor to capture image sources
+    such as outputs and toplevels into user submitted buffers.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="ext_image_copy_capture_manager_v1" version="1">
+    <description summary="manager to inform clients and begin capturing">
+      This object is a manager which offers requests to start capturing from a
+      source.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_option" value="1" summary="invalid option flag"/>
+    </enum>
+
+    <enum name="options" bitfield="true">
+      <entry name="paint_cursors" value="1" summary="paint cursors onto captured frames"/>
+    </enum>
+
+    <request name="create_session">
+      <description summary="capture an image capture source">
+        Create a capturing session for an image capture source.
+
+        If the paint_cursors option is set, cursors shall be composited onto
+        the captured frame. The cursor must not be composited onto the frame
+        if this flag is not set.
+
+        If the options bitfield is invalid, the invalid_option protocol error
+        is sent.
+      </description>
+      <arg name="session" type="new_id" interface="ext_image_copy_capture_session_v1"/>
+      <arg name="source" type="object" interface="ext_image_capture_source_v1"/>
+      <arg name="options" type="uint" enum="options"/>
+    </request>
+
+    <request name="create_pointer_cursor_session">
+      <description summary="capture the pointer cursor of an image capture source">
+        Create a cursor capturing session for the pointer of an image capture
+        source.
+      </description>
+      <arg name="session" type="new_id" interface="ext_image_copy_capture_cursor_session_v1"/>
+      <arg name="source" type="object" interface="ext_image_capture_source_v1"/>
+      <arg name="pointer" type="object" interface="wl_pointer"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the manager object.
+
+        Other objects created via this interface are unaffected.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_image_copy_capture_session_v1" version="1">
+    <description summary="image copy capture session">
+      This object represents an active image copy capture session.
+
+      After a capture session is created, buffer constraint events will be
+      emitted from the compositor to tell the client which buffer types and
+      formats are supported for reading from the session. The compositor may
+      re-send buffer constraint events whenever they change.
+
+      To advertise buffer constraints, the compositor must send in no
+      particular order: zero or more shm_format and dmabuf_format events, zero
+      or one dmabuf_device event, and exactly one buffer_size event. Then the
+      compositor must send a done event.
+
+      When the client has received all the buffer constraints, it can create a
+      buffer accordingly, attach it to the capture session using the
+      attach_buffer request, set the buffer damage using the damage_buffer
+      request and then send the capture request.
+    </description>
+
+    <enum name="error">
+      <entry name="duplicate_frame" value="1"
+        summary="create_frame sent before destroying previous frame"/>
+    </enum>
+
+    <event name="buffer_size">
+      <description summary="image capture source dimensions">
+        Provides the dimensions of the source image in buffer pixel coordinates.
+
+        The client must attach buffers that match this size.
+      </description>
+      <arg name="width" type="uint" summary="buffer width"/>
+      <arg name="height" type="uint" summary="buffer height"/>
+    </event>
+
+    <event name="shm_format">
+      <description summary="shm buffer format">
+        Provides the format that must be used for shared-memory buffers.
+
+        This event may be emitted multiple times, in which case the client may
+        choose any given format.
+      </description>
+      <arg name="format" type="uint" enum="wl_shm.format" summary="shm format"/>
+    </event>
+
+    <event name="dmabuf_device">
+      <description summary="dma-buf device">
+        This event advertises the device buffers must be allocated on for
+        dma-buf buffers.
+
+        In general the device is a DRM node. The DRM node type (primary vs.
+        render) is unspecified. Clients must not rely on the compositor sending
+        a particular node type. Clients cannot check two devices for equality
+        by comparing the dev_t value.
+      </description>
+      <arg name="device" type="array" summary="device dev_t value"/>
+    </event>
+
+    <event name="dmabuf_format">
+      <description summary="dma-buf format">
+        Provides the format that must be used for dma-buf buffers.
+
+        The client may choose any of the modifiers advertised in the array of
+        64-bit unsigned integers.
+
+        This event may be emitted multiple times, in which case the client may
+        choose any given format.
+      </description>
+      <arg name="format" type="uint" summary="drm format code"/>
+      <arg name="modifiers" type="array" summary="drm format modifiers"/>
+    </event>
+
+    <event name="done">
+      <description summary="all constraints have been sent">
+        This event is sent once when all buffer constraint events have been
+        sent.
+
+        The compositor must always end a batch of buffer constraint events with
+        this event, regardless of whether it sends the initial constraints or
+        an update.
+      </description>
+    </event>
+
+    <event name="stopped">
+      <description summary="session is no longer available">
+        This event indicates that the capture session has stopped and is no
+        longer available. This can happen in a number of cases, e.g. when the
+        underlying source is destroyed, if the user decides to end the image
+        capture, or if an unrecoverable runtime error has occurred.
+
+        The client should destroy the session after receiving this event.
+      </description>
+    </event>
+
+    <request name="create_frame">
+      <description summary="create a frame">
+        Create a capture frame for this session.
+
+        At most one frame object can exist for a given session at any time. If
+        a client sends a create_frame request before a previous frame object
+        has been destroyed, the duplicate_frame protocol error is raised.
+      </description>
+      <arg name="frame" type="new_id" interface="ext_image_copy_capture_frame_v1"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object">
+        Destroys the session. This request can be sent at any time by the
+        client.
+
+        This request doesn't affect ext_image_copy_capture_frame_v1 objects created by
+        this object.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_image_copy_capture_frame_v1" version="1">
+    <description summary="image capture frame">
+      This object represents an image capture frame.
+
+      The client should attach a buffer, damage the buffer, and then send a
+      capture request.
+
+      If the capture is successful, the compositor must send the frame metadata
+      (transform, damage, presentation_time in any order) followed by the ready
+      event.
+
+      If the capture fails, the compositor must send the failed event.
+    </description>
+
+    <enum name="error">
+      <entry name="no_buffer" value="1" summary="capture sent without attach_buffer"/>
+      <entry name="invalid_buffer_damage" value="2" summary="invalid buffer damage"/>
+      <entry name="already_captured" value="3" summary="capture request has been sent"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy this object">
+        Destroys the frame. This request can be sent at any time by the
+        client.
+      </description>
+    </request>
+
+    <request name="attach_buffer">
+      <description summary="attach buffer to session">
+        Attach a buffer to the session.
+
+        The wl_buffer.release request is unused.
+
+        The new buffer replaces any previously attached buffer.
+
+        This request must not be sent after capture, or else the
+        already_captured protocol error is raised.
+      </description>
+      <arg name="buffer" type="object" interface="wl_buffer"/>
+    </request>
+
+    <request name="damage_buffer">
+      <description summary="damage buffer">
+        Apply damage to the buffer which is to be captured next. This request
+        may be sent multiple times to describe a region.
+
+        The client indicates the accumulated damage since this wl_buffer was
+        last captured. During capture, the compositor will update the buffer
+        with at least the union of the region passed by the client and the
+        region advertised by ext_image_copy_capture_frame_v1.damage.
+
+        When a wl_buffer is captured for the first time, or when the client
+        doesn't track damage, the client must damage the whole buffer.
+
+        This is for optimisation purposes. The compositor may use this
+        information to reduce copying.
+
+        These coordinates originate from the upper left corner of the buffer.
+
+        If x or y are strictly negative, or if width or height are negative or
+        zero, the invalid_buffer_damage protocol error is raised.
+
+        This request must not be sent after capture, or else the
+        already_captured protocol error is raised.
+      </description>
+      <arg name="x" type="int" summary="region x coordinate"/>
+      <arg name="y" type="int" summary="region y coordinate"/>
+      <arg name="width" type="int" summary="region width"/>
+      <arg name="height" type="int" summary="region height"/>
+    </request>
+
+    <request name="capture">
+      <description summary="capture a frame">
+        Capture a frame.
+
+        Unless this is the first successful captured frame performed in this
+        session, the compositor may wait an indefinite amount of time for the
+        source content to change before performing the copy.
+
+        This request may only be sent once, or else the already_captured
+        protocol error is raised. A buffer must be attached before this request
+        is sent, or else the no_buffer protocol error is raised.
+      </description>
+    </request>
+
+    <event name="transform">
+      <description summary="buffer transform">
+        This event is sent before the ready event and holds the transform that
+        the compositor has applied to the buffer contents.
+      </description>
+      <arg name="transform" type="uint" enum="wl_output.transform"/>
+    </event>
+
+    <event name="damage">
+      <description summary="buffer damaged region">
+        This event is sent before the ready event. It may be generated multiple
+        times to describe a region.
+
+        The first captured frame in a session will always carry full damage.
+        Subsequent frames' damaged regions describe which parts of the buffer
+        have changed since the last ready event.
+
+        These coordinates originate in the upper left corner of the buffer.
+      </description>
+      <arg name="x" type="int" summary="damage x coordinate"/>
+      <arg name="y" type="int" summary="damage y coordinate"/>
+      <arg name="width" type="int" summary="damage width"/>
+      <arg name="height" type="int" summary="damage height"/>
+    </event>
+
+    <event name="presentation_time">
+      <description summary="presentation time of the frame">
+        This event indicates the time at which the frame is presented to the
+        output in system monotonic time. This event is sent before the ready
+        event.
+
+        The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
+        each component being an unsigned 32-bit value. Whole seconds are in
+        tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo,
+        and the additional fractional part in tv_nsec as nanoseconds. Hence,
+        for valid timestamps tv_nsec must be in [0, 999999999].
+      </description>
+      <arg name="tv_sec_hi" type="uint"
+           summary="high 32 bits of the seconds part of the timestamp"/>
+      <arg name="tv_sec_lo" type="uint"
+           summary="low 32 bits of the seconds part of the timestamp"/>
+      <arg name="tv_nsec" type="uint"
+           summary="nanoseconds part of the timestamp"/>
+    </event>
+
+    <event name="ready">
+      <description summary="frame is available for reading">
+        Called as soon as the frame is copied, indicating it is available
+        for reading.
+
+        The buffer may be re-used by the client after this event.
+
+        After receiving this event, the client must destroy the object.
+      </description>
+    </event>
+
+    <enum name="failure_reason">
+      <entry name="unknown" value="0">
+        <description summary="unknown runtime error">
+          An unspecified runtime error has occurred. The client may retry.
+        </description>
+      </entry>
+      <entry name="buffer_constraints" value="1">
+        <description summary="buffer constraints mismatch">
+          The buffer submitted by the client doesn't match the latest session
+          constraints. The client should re-allocate its buffers and retry.
+        </description>
+      </entry>
+      <entry name="stopped" value="2">
+        <description summary="session is no longer available">
+          The session has stopped. See ext_image_copy_capture_session_v1.stopped.
+        </description>
+      </entry>
+    </enum>
+
+    <event name="failed">
+      <description summary="capture failed">
+        This event indicates that the attempted frame copy has failed.
+
+        After receiving this event, the client must destroy the object.
+      </description>
+      <arg name="reason" type="uint" enum="failure_reason"/>
+    </event>
+  </interface>
+
+  <interface name="ext_image_copy_capture_cursor_session_v1" version="1">
+    <description summary="cursor capture session">
+      This object represents a cursor capture session. It extends the base
+      capture session with cursor-specific metadata.
+    </description>
+
+    <enum name="error">
+      <entry name="duplicate_session" value="1" summary="get_capture_session sent twice"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object">
+        Destroys the session. This request can be sent at any time by the
+        client.
+
+        This request doesn't affect ext_image_copy_capture_frame_v1 objects created by
+        this object.
+      </description>
+    </request>
+
+    <request name="get_capture_session">
+      <description summary="get image copy capturer session">
+        Gets the image copy capture session for this cursor session.
+
+        The session will produce frames of the cursor image. The compositor may
+        pause the session when the cursor leaves the captured area.
+
+        This request must not be sent more than once, or else the
+        duplicate_session protocol error is raised.
+      </description>
+      <arg name="session" type="new_id" interface="ext_image_copy_capture_session_v1"/>
+    </request>
+
+    <event name="enter">
+      <description summary="cursor entered captured area">
+        Sent when a cursor enters the captured area. It shall be generated
+        before the "position" and "hotspot" events when and only when a cursor
+        enters the area.
+
+        The cursor enters the captured area when the cursor image intersects
+        with the captured area. Note, this is different from e.g.
+        wl_pointer.enter.
+      </description>
+    </event>
+
+    <event name="leave">
+      <description summary="cursor left captured area">
+        Sent when a cursor leaves the captured area. No "position" or "hotspot"
+        event is generated for the cursor until the cursor enters the captured
+        area again.
+      </description>
+    </event>
+
+    <event name="position">
+      <description summary="position changed">
+        Cursors outside the image capture source do not get captured and no
+        event will be generated for them.
+
+        The given position is the position of the cursor's hotspot and it is
+        relative to the main buffer's top left corner in transformed buffer
+        pixel coordinates. The coordinates may be negative or greater than the
+        main buffer size.
+      </description>
+      <arg name="x" type="int" summary="position x coordinates"/>
+      <arg name="y" type="int" summary="position y coordinates"/>
+    </event>
+
+    <event name="hotspot">
+      <description summary="hotspot changed">
+        The hotspot describes the offset between the cursor image and the
+        position of the input device.
+
+        The given coordinates are the hotspot's offset from the origin in
+        buffer coordinates.
+
+        Clients should not apply the hotspot immediately: the hotspot becomes
+        effective when the next ext_image_copy_capture_frame_v1.ready event is received.
+
+        Compositors may delay this event until the client captures a new frame.
+      </description>
+      <arg name="x" type="int" summary="hotspot x coordinates"/>
+      <arg name="y" type="int" summary="hotspot y coordinates"/>
+    </event>
+  </interface>
+</protocol>

staging/ext-session-lock/README

@@ -0,0 +1,4 @@
+ext session lock protocol
+
+Maintainers:
+Isaac Freund <mail@isaacfreund.com> (@ifreund)

staging/ext-session-lock/ext-session-lock-v1.xml

@@ -0,0 +1,328 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_session_lock_v1">
+  <copyright>
+    Copyright 2021 Isaac Freund
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+  </copyright>
+
+  <description summary="secure session locking with arbitrary graphics">
+    This protocol allows for a privileged Wayland client to lock the session
+    and display arbitrary graphics while the session is locked.
+
+    The compositor may choose to restrict this protocol to a special client
+    launched by the compositor itself or expose it to all privileged clients,
+    this is compositor policy.
+
+    The client is responsible for performing authentication and informing the
+    compositor when the session should be unlocked. If the client dies while
+    the session is locked the session remains locked, possibly permanently
+    depending on compositor policy.
+
+    The key words "must", "must not", "required", "shall", "shall not",
+    "should", "should not", "recommended",  "may", and "optional" in this
+    document are to be interpreted as described in IETF RFC 2119.
+
+    Warning! The protocol described in this file is currently in the
+    testing phase. Backward compatible changes may be added together with
+    the corresponding interface version bump. Backward incompatible changes
+    can only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="ext_session_lock_manager_v1" version="1">
+    <description summary="used to lock the session">
+      This interface is used to request that the session be locked.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the session lock manager object">
+        This informs the compositor that the session lock manager object will
+        no longer be used. Existing objects created through this interface
+        remain valid.
+      </description>
+    </request>
+
+    <request name="lock">
+      <description summary="attempt to lock the session">
+        This request creates a session lock and asks the compositor to lock the
+        session. The compositor will send either the ext_session_lock_v1.locked
+        or ext_session_lock_v1.finished event on the created object in
+        response to this request.
+      </description>
+      <arg name="id" type="new_id" interface="ext_session_lock_v1"/>
+    </request>
+  </interface>
+
+  <interface name="ext_session_lock_v1" version="1">
+    <description summary="manage lock state and create lock surfaces">
+      In response to the creation of this object the compositor must send
+      either the locked or finished event.
+
+      The locked event indicates that the session is locked. This means
+      that the compositor must stop rendering and providing input to normal
+      clients. Instead the compositor must blank all outputs with an opaque
+      color such that their normal content is fully hidden.
+
+      The only surfaces that should be rendered while the session is locked
+      are the lock surfaces created through this interface and optionally,
+      at the compositor's discretion, special privileged surfaces such as
+      input methods or portions of desktop shell UIs.
+
+      The locked event must not be sent until a new "locked" frame (either
+      from a session lock surface or the compositor blanking the output) has
+      been presented on all outputs and no security sensitive normal/unlocked
+      content is possibly visible.
+
+      The finished event should be sent immediately on creation of this
+      object if the compositor decides that the locked event will not be sent.
+
+      The compositor may wait for the client to create and render session lock
+      surfaces before sending the locked event to avoid displaying intermediate
+      blank frames. However, it must impose a reasonable time limit if
+      waiting and send the locked event as soon as the hard requirements
+      described above can be met if the time limit expires. Clients should
+      immediately create lock surfaces for all outputs on creation of this
+      object to make this possible.
+
+      This behavior of the locked event is required in order to prevent
+      possible race conditions with clients that wish to suspend the system
+      or similar after locking the session. Without these semantics, clients
+      triggering a suspend after receiving the locked event would race with
+      the first "locked" frame being presented and normal/unlocked frames
+      might be briefly visible as the system is resumed if the suspend
+      operation wins the race.
+
+      If the client dies while the session is locked, the compositor must not
+      unlock the session in response. It is acceptable for the session to be
+      permanently locked if this happens. The compositor may choose to continue
+      to display the lock surfaces the client had mapped before it died or
+      alternatively fall back to a solid color, this is compositor policy.
+
+      Compositors may also allow a secure way to recover the session, the
+      details of this are compositor policy. Compositors may allow a new
+      client to create a ext_session_lock_v1 object and take responsibility
+      for unlocking the session, they may even start a new lock client
+      instance automatically.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_destroy" value="0"
+        summary="attempted to destroy session lock while locked"/>
+      <entry name="invalid_unlock" value="1"
+        summary="unlock requested but locked event was never sent"/>
+      <entry name="role" value="2"
+        summary="given wl_surface already has a role"/>
+      <entry name="duplicate_output" value="3"
+        summary="given output already has a lock surface"/>
+      <entry name="already_constructed" value="4"
+        summary="given wl_surface has a buffer attached or committed"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the session lock">
+        This informs the compositor that the lock object will no longer be
+        used. Existing objects created through this interface remain valid.
+
+        After this request is made, lock surfaces created through this object
+        should be destroyed by the client as they will no longer be used by
+        the compositor.
+
+        It is a protocol error to make this request if the locked event was
+        sent, the unlock_and_destroy request must be used instead.
+      </description>
+    </request>
+
+    <event name="locked">
+      <description summary="session successfully locked">
+        This client is now responsible for displaying graphics while the
+        session is locked and deciding when to unlock the session.
+
+        The locked event must not be sent until a new "locked" frame has been
+        presented on all outputs and no security sensitive normal/unlocked
+        content is possibly visible.
+
+        If this event is sent, making the destroy request is a protocol error,
+        the lock object must be destroyed using the unlock_and_destroy request.
+      </description>
+    </event>
+
+    <event name="finished">
+      <description summary="the session lock object should be destroyed">
+        The compositor has decided that the session lock should be destroyed
+        as it will no longer be used by the compositor. Exactly when this
+        event is sent is compositor policy, but it must never be sent more
+        than once for a given session lock object.
+
+        This might be sent because there is already another ext_session_lock_v1
+        object held by a client, or the compositor has decided to deny the
+        request to lock the session for some other reason. This might also
+        be sent because the compositor implements some alternative, secure
+        way to authenticate and unlock the session.
+
+        The finished event should be sent immediately on creation of this
+        object if the compositor decides that the locked event will not
+        be sent.
+
+        If the locked event is sent on creation of this object the finished
+        event may still be sent at some later time in this object's
+        lifetime. This is compositor policy.
+
+        Upon receiving this event, the client should make either the destroy
+        request or the unlock_and_destroy request, depending on whether or
+        not the locked event was received on this object.
+      </description>
+    </event>
+
+    <request name="get_lock_surface">
+      <description summary="create a lock surface for a given output">
+        The client is expected to create lock surfaces for all outputs
+        currently present and any new outputs as they are advertised. These
+        won't be displayed by the compositor unless the lock is successful
+        and the locked event is sent.
+
+        Providing a wl_surface which already has a role or already has a buffer
+        attached or committed is a protocol error, as is attaching/committing
+        a buffer before the first ext_session_lock_surface_v1.configure event.
+
+        Attempting to create more than one lock surface for a given output
+        is a duplicate_output protocol error.
+      </description>
+      <arg name="id" type="new_id" interface="ext_session_lock_surface_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="output" type="object" interface="wl_output"/>
+    </request>
+
+    <request name="unlock_and_destroy" type="destructor">
+      <description summary="unlock the session, destroying the object">
+        This request indicates that the session should be unlocked, for
+        example because the user has entered their password and it has been
+        verified by the client.
+
+        This request also informs the compositor that the lock object will
+        no longer be used and should be destroyed. Existing objects created
+        through this interface remain valid.
+
+        After this request is made, lock surfaces created through this object
+        should be destroyed by the client as they will no longer be used by
+        the compositor.
+
+        It is a protocol error to make this request if the locked event has
+        not been sent. In that case, the lock object must be destroyed using
+        the destroy request.
+
+        Note that a correct client that wishes to exit directly after unlocking
+        the session must use the wl_display.sync request to ensure the server
+        receives and processes the unlock_and_destroy request. Otherwise
+        there is no guarantee that the server has unlocked the session due
+        to the asynchronous nature of the Wayland protocol. For example,
+        the server might terminate the client with a protocol error before
+        it processes the unlock_and_destroy request.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_session_lock_surface_v1" version="1">
+    <description summary="a surface displayed while the session is locked">
+      The client may use lock surfaces to display a screensaver, render a
+      dialog to enter a password and unlock the session, or however else it
+      sees fit.
+
+      On binding this interface the compositor will immediately send the
+      first configure event. After making the ack_configure request in
+      response to this event the client should attach and commit the first
+      buffer. Committing the surface before acking the first configure is a
+      protocol error. Committing the surface with a null buffer at any time
+      is a protocol error.
+
+      The compositor is free to handle keyboard/pointer focus for lock
+      surfaces however it chooses. A reasonable way to do this would be to
+      give the first lock surface created keyboard focus and change keyboard
+      focus if the user clicks on other surfaces.
+    </description>
+
+    <enum name="error">
+      <entry name="commit_before_first_ack" value="0"
+        summary="surface committed before first ack_configure request"/>
+      <entry name="null_buffer" value="1"
+        summary="surface committed with a null buffer"/>
+      <entry name="dimensions_mismatch" value="2"
+        summary="failed to match ack'd width/height"/>
+      <entry name="invalid_serial" value="3"
+        summary="serial provided in ack_configure is invalid"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the lock surface object">
+        This informs the compositor that the lock surface object will no
+        longer be used.
+
+        It is recommended for a lock client to destroy lock surfaces if
+        their corresponding wl_output global is removed.
+
+        If a lock surface on an active output is destroyed before the
+        ext_session_lock_v1.unlock_and_destroy event is sent, the compositor
+        must fall back to rendering a solid color.
+      </description>
+    </request>
+
+    <request name="ack_configure">
+      <description summary="ack a configure event">
+        When a configure event is received, if a client commits the surface
+        in response to the configure event, then the client must make an
+        ack_configure request sometime before the commit request, passing
+        along the serial of the configure event.
+
+        If the client receives multiple configure events before it can
+        respond to one, it only has to ack the last configure event.
+
+        A client is not required to commit immediately after sending an
+        ack_configure request - it may even ack_configure several times
+        before its next surface commit.
+
+        A client may send multiple ack_configure requests before committing,
+        but only the last request sent before a commit indicates which
+        configure event the client really is responding to.
+
+        Sending an ack_configure request consumes the configure event
+        referenced by the given serial, as well as all older configure events
+        sent on this object.
+
+        It is a protocol error to issue multiple ack_configure requests
+        referencing the same configure event or to issue an ack_configure
+        request referencing a configure event older than the last configure
+        event acked for a given lock surface.
+      </description>
+      <arg name="serial" type="uint" summary="serial from the configure event"/>
+    </request>
+
+    <event name="configure">
+      <description summary="the client should resize its surface">
+        This event is sent once on binding the interface and may be sent again
+        at the compositor's discretion, for example if output geometry changes.
+
+        The width and height are in surface-local coordinates and are exact
+        requirements. Failing to match these surface dimensions in the next
+        commit after acking a configure is a protocol error.
+      </description>
+      <arg name="serial" type="uint" summary="serial for use in ack_configure"/>
+      <arg name="width" type="uint"/>
+      <arg name="height" type="uint"/>
+    </event>
+  </interface>
+</protocol>

staging/ext-transient-seat/README

@@ -0,0 +1,4 @@
+Transient Seat
+
+Maintainers:
+Andri Yngvason <andri@yngvason.is> (@andri)

staging/ext-transient-seat/ext-transient-seat-v1.xml

@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_transient_seat_v1">
+  <copyright>
+    Copyright © 2020 - 2023 Andri Yngvason
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="protocol for creating temporary seats">
+    The transient seat protocol can be used by privileged clients to create
+    independent seats that will be removed from the compositor when the client
+    destroys its transient seat.
+
+    This protocol is intended for use with virtual input protocols such as
+    "virtual_keyboard_unstable_v1" or "wlr_virtual_pointer_unstable_v1", both
+    of which allow the user to select a seat.
+
+    The "wl_seat" global created by this protocol does not generate input events
+    on its own, or have any capabilities except those assigned to it by other
+    protocol extensions, such as the ones mentioned above.
+
+    For example, a remote desktop server can create a seat with virtual inputs
+    for each remote user by following these steps for each new connection:
+     * Create a transient seat
+     * Wait for the transient seat to be created
+     * Locate a "wl_seat" global with a matching name
+     * Create virtual inputs using the resulting "wl_seat" global
+  </description>
+
+  <interface name="ext_transient_seat_manager_v1" version="1">
+    <description summary="transient seat manager">
+      The transient seat manager creates short-lived seats.
+    </description>
+
+    <request name="create">
+      <description summary="create a transient seat">
+        Create a new seat that is removed when the client side transient seat
+        object is destroyed.
+
+        The actual seat may be removed sooner, in which case the transient seat
+        object shall become inert.
+      </description>
+      <arg name="seat" type="new_id" interface="ext_transient_seat_v1"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the manager.
+
+        All objects created by the manager will remain valid until they are
+        destroyed themselves.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_transient_seat_v1" version="1">
+    <description summary="transient seat handle">
+      When the transient seat handle is destroyed, the seat itself will also be
+      destroyed.
+    </description>
+
+    <event name="ready">
+      <description summary="transient seat is ready">
+        This event advertises the global name for the wl_seat to be used with
+        wl_registry_bind.
+
+        It is sent exactly once, immediately after the transient seat is created
+        and the new "wl_seat" global is advertised, if and only if the creation
+        of the transient seat was allowed.
+      </description>
+      <arg name="global_name" type="uint"/>
+    </event>
+
+    <event name="denied">
+      <description summary="transient seat creation denied">
+        The event informs the client that the compositor denied its request to
+        create a transient seat.
+
+        It is sent exactly once, immediately after the transient seat object is
+        created, if and only if the creation of the transient seat was denied.
+
+        After receiving this event, the client should destroy the object.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy transient seat">
+        When the transient seat object is destroyed by the client, the
+        associated seat created by the compositor is also destroyed.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/ext-workspace/README

@@ -0,0 +1,5 @@
+Workspace protocol
+
+Maintainers:
+Ilia Bozhinov <ammen99@gmail.com>
+Victoria Brekenfeld <wayland@drakulix.de>

staging/ext-workspace/ext-workspace-v1.xml

@@ -0,0 +1,422 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_workspace_v1">
+  <copyright>
+    Copyright © 2019 Christopher Billington
+    Copyright © 2020 Ilia Bozhinov
+    Copyright © 2022 Victoria Brekenfeld
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+    THIS SOFTWARE.
+  </copyright>
+
+  <interface name="ext_workspace_manager_v1" version="1">
+    <description summary="list and control workspaces">
+      Workspaces, also called virtual desktops, are groups of surfaces. A
+      compositor with a concept of workspaces may only show some such groups of
+      surfaces (those of 'active' workspaces) at a time. 'Activating' a
+      workspace is a request for the compositor to display that workspace's
+      surfaces as normal, whereas the compositor may hide or otherwise
+      de-emphasise surfaces that are associated only with 'inactive' workspaces.
+      Workspaces are grouped by which sets of outputs they correspond to, and
+      may contain surfaces only from those outputs. In this way, it is possible
+      for each output to have its own set of workspaces, or for all outputs (or
+      any other arbitrary grouping) to share workspaces. Compositors may
+      optionally conceptually arrange each group of workspaces in an
+      N-dimensional grid.
+
+      The purpose of this protocol is to enable the creation of taskbars and
+      docks by providing them with a list of workspaces and their properties,
+      and allowing them to activate and deactivate workspaces.
+
+      After a client binds the ext_workspace_manager_v1, each workspace will be
+      sent via the workspace event.
+    </description>
+
+    <event name="workspace_group">
+      <description summary="a workspace group has been created">
+        This event is emitted whenever a new workspace group has been created.
+
+        All initial details of the workspace group (outputs) will be
+        sent immediately after this event via the corresponding events in
+        ext_workspace_group_handle_v1 and ext_workspace_handle_v1.
+      </description>
+      <arg name="workspace_group" type="new_id" interface="ext_workspace_group_handle_v1"/>
+    </event>
+
+    <event name="workspace">
+      <description summary="workspace has been created">
+        This event is emitted whenever a new workspace has been created.
+
+        All initial details of the workspace (name, coordinates, state) will
+        be sent immediately after this event via the corresponding events in
+        ext_workspace_handle_v1.
+
+        Workspaces start off unassigned to any workspace group.
+      </description>
+      <arg name="workspace" type="new_id" interface="ext_workspace_handle_v1"/>
+    </event>
+  
+    <request name="commit">
+      <description summary="all requests about the workspaces have been sent">
+        The client must send this request after it has finished sending other
+        requests. The compositor must process a series of requests preceding a
+        commit request atomically.
+
+        This allows changes to the workspace properties to be seen as atomic,
+        even if they happen via multiple events, and even if they involve
+        multiple ext_workspace_handle_v1 objects, for example, deactivating one
+        workspace and activating another.
+      </description>
+    </request>
+
+    <event name="done">
+      <description summary="all information about the workspaces and workspace groups has been sent">
+        This event is sent after all changes in all workspaces and workspace groups have been
+        sent.
+
+        This allows changes to one or more ext_workspace_group_handle_v1
+        properties and ext_workspace_handle_v1 properties
+        to be seen as atomic, even if they happen via multiple events.
+        In particular, an output moving from one workspace group to
+        another sends an output_enter event and an output_leave event to the two
+        ext_workspace_group_handle_v1 objects in question. The compositor sends
+        the done event only after updating the output information in both
+        workspace groups.
+      </description>
+    </event>
+
+    <event name="finished" type="destructor">
+      <description summary="the compositor has finished with the workspace_manager">
+        This event indicates that the compositor is done sending events to the
+        ext_workspace_manager_v1. The server will destroy the object
+        immediately after sending this request.
+      </description>
+    </event>
+
+    <request name="stop">
+      <description summary="stop sending events">
+        Indicates the client no longer wishes to receive events for new
+        workspace groups. However the compositor may emit further workspace
+        events, until the finished event is emitted. The compositor is expected
+        to send the finished event eventually once the stop request has been processed.
+
+        The client must not send any requests after this one, doing so will raise a wl_display
+        invalid_object error.
+      </description>
+    </request>
+
+  </interface>
+
+  <interface name="ext_workspace_group_handle_v1" version="1">
+    <description summary="a workspace group assigned to a set of outputs">
+      A ext_workspace_group_handle_v1 object represents a workspace group
+      that is assigned a set of outputs and contains a number of workspaces.
+
+      The set of outputs assigned to the workspace group is conveyed to the client via
+      output_enter and output_leave events, and its workspaces are conveyed with
+      workspace events.
+
+      For example, a compositor which has a set of workspaces for each output may
+      advertise a workspace group (and its workspaces) per output, whereas a compositor
+      where a workspace spans all outputs may advertise a single workspace group for all
+      outputs.
+    </description>
+
+    <enum name="group_capabilities" bitfield="true">
+      <entry name="create_workspace" value="1" summary="create_workspace request is available"/>
+    </enum>
+
+    <event name="capabilities">
+      <description summary="compositor capabilities">
+        This event advertises the capabilities supported by the compositor. If
+        a capability isn't supported, clients should hide or disable the UI
+        elements that expose this functionality. For instance, if the
+        compositor doesn't advertise support for creating workspaces, a button
+        triggering the create_workspace request should not be displayed.
+
+        The compositor will ignore requests it doesn't support. For instance,
+        a compositor which doesn't advertise support for creating workspaces will ignore
+        create_workspace requests.
+
+        Compositors must send this event once after creation of an
+        ext_workspace_group_handle_v1. When the capabilities change, compositors
+        must send this event again.
+      </description>
+      <arg name="capabilities" type="uint" summary="capabilities" enum="group_capabilities"/>
+    </event>
+
+    <event name="output_enter">
+      <description summary="output assigned to workspace group">
+        This event is emitted whenever an output is assigned to the workspace
+        group or a new `wl_output` object is bound by the client, which was already
+        assigned to this workspace_group.
+      </description>
+      <arg name="output" type="object" interface="wl_output"/>
+    </event>
+
+    <event name="output_leave">
+      <description summary="output removed from workspace group">
+        This event is emitted whenever an output is removed from the workspace
+        group.
+      </description>
+      <arg name="output" type="object" interface="wl_output"/>
+    </event>
+
+    <event name="workspace_enter">
+      <description summary="workspace added to workspace group">
+        This event is emitted whenever a workspace is assigned to this group.
+        A workspace may only ever be assigned to a single group at a single point
+        in time, but can be re-assigned during its lifetime.
+      </description>
+      <arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
+    </event>
+
+    <event name="workspace_leave">
+      <description summary="workspace removed from workspace group">
+        This event is emitted whenever a workspace is removed from this group.
+      </description>
+      <arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
+    </event>
+
+    <event name="removed">
+      <description summary="this workspace group has been removed">
+        This event is send when the group associated with the ext_workspace_group_handle_v1
+        has been removed. After sending this request the compositor will immediately consider
+        the object inert. Any requests will be ignored except the destroy request.
+        It is guaranteed there won't be any more events referencing this
+        ext_workspace_group_handle_v1.
+
+        The compositor must remove all workspaces belonging to a workspace group
+        via a workspace_leave event before removing the workspace group.
+      </description>
+    </event>
+
+    <request name="create_workspace">
+      <description summary="create a new workspace">
+        Request that the compositor create a new workspace with the given name
+        and assign it to this group.
+
+        There is no guarantee that the compositor will create a new workspace,
+        or that the created workspace will have the provided name.
+      </description>
+      <arg name="workspace" type="string"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the ext_workspace_group_handle_v1 object">
+        Destroys the ext_workspace_group_handle_v1 object.
+
+        This request should be send either when the client does not want to
+        use the workspace group object any more or after the removed event to finalize
+        the destruction of the object.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_workspace_handle_v1" version="1">
+    <description summary="a workspace handing a group of surfaces">
+      A ext_workspace_handle_v1 object represents a workspace that handles a
+      group of surfaces.
+
+      Each workspace has:
+      - a name, conveyed to the client with the name event
+      - potentially an id conveyed with the id event
+      - a list of states, conveyed to the client with the state event
+      - and optionally a set of coordinates, conveyed to the client with the
+      coordinates event
+      
+      The client may request that the compositor activate or deactivate the workspace.
+
+      Each workspace can belong to only a single workspace group.
+      Depending on the compositor policy, there might be workspaces with
+      the same name in different workspace groups, but these workspaces are still
+      separate (e.g. one of them might be active while the other is not).
+    </description>
+
+    <event name="id">
+      <description summary="workspace id">
+        If this event is emitted, it will be send immediately after the
+        ext_workspace_handle_v1 is created or when an id is assigned to
+        a workspace (at most once during its lifetime).
+
+        An id will never change during the lifetime of the `ext_workspace_handle_v1`
+        and is guaranteed to be unique during its lifetime.
+
+        Ids are not human-readable and shouldn't be displayed, use `name` for that purpose.
+
+        Compositors are expected to only send ids for workspaces likely stable across multiple
+        sessions and can be used by clients to store preferences for workspaces. Workspaces without
+        ids should be considered temporary and any data associated with them should be deleted once
+        the respective object is lost.
+      </description>
+      <arg name="id" type="string"/>
+    </event>
+
+    <event name="name">
+      <description summary="workspace name changed">
+        This event is emitted immediately after the ext_workspace_handle_v1 is
+        created and whenever the name of the workspace changes.
+
+        A name is meant to be human-readable and can be displayed to a user.
+        Unlike the id it is neither stable nor unique.
+      </description>
+      <arg name="name" type="string"/>
+    </event>
+
+    <event name="coordinates">
+      <description summary="workspace coordinates changed">
+        This event is used to organize workspaces into an N-dimensional grid
+        within a workspace group, and if supported, is emitted immediately after
+        the ext_workspace_handle_v1 is created and whenever the coordinates of
+        the workspace change. Compositors may not send this event if they do not
+        conceptually arrange workspaces in this way. If compositors simply
+        number workspaces, without any geometric interpretation, they may send
+        1D coordinates, which clients should not interpret as implying any
+        geometry. Sending an empty array means that the compositor no longer
+        orders the workspace geometrically.
+
+        Coordinates have an arbitrary number of dimensions N with an uint32
+        position along each dimension. By convention if N > 1, the first
+        dimension is X, the second Y, the third Z, and so on. The compositor may
+        chose to utilize these events for a more novel workspace layout
+        convention, however. No guarantee is made about the grid being filled or
+        bounded; there may be a workspace at coordinate 1 and another at
+        coordinate 1000 and none in between. Within a workspace group, however,
+        workspaces must have unique coordinates of equal dimensionality.
+      </description>
+      <arg name="coordinates" type="array"/>
+    </event>
+
+    <enum name="state" bitfield="true">
+      <description summary="types of states on the workspace">
+        The different states that a workspace can have.
+      </description>
+
+      <entry name="active" value="1" summary="the workspace is active"/>
+      <entry name="urgent" value="2" summary="the workspace requests attention"/>
+      <entry name="hidden" value="4">
+        <description summary="the workspace is not visible">
+          The workspace is not visible in its workspace group, and clients
+          attempting to visualize the compositor workspace state should not
+          display such workspaces.
+        </description>
+      </entry>
+    </enum>
+
+    <event name="state">
+      <description summary="the state of the workspace changed">
+        This event is emitted immediately after the ext_workspace_handle_v1 is
+        created and each time the workspace state changes, either because of a
+        compositor action or because of a request in this protocol.
+
+        Missing states convey the opposite meaning, e.g. an unset active bit
+        means the workspace is currently inactive.
+      </description>
+      <arg name="state" type="uint" enum="state"/>
+    </event>
+
+    <enum name="workspace_capabilities" bitfield="true">
+      <entry name="activate" value="1" summary="activate request is available"/>
+      <entry name="deactivate" value="2" summary="deactivate request is available"/>
+      <entry name="remove" value="4" summary="remove request is available"/>
+      <entry name="assign" value="8" summary="assign request is available"/>
+    </enum>
+
+    <event name="capabilities">
+      <description summary="compositor capabilities">
+        This event advertises the capabilities supported by the compositor. If
+        a capability isn't supported, clients should hide or disable the UI
+        elements that expose this functionality. For instance, if the
+        compositor doesn't advertise support for removing workspaces, a button
+        triggering the remove request should not be displayed.
+
+        The compositor will ignore requests it doesn't support. For instance,
+        a compositor which doesn't advertise support for remove will ignore
+        remove requests.
+
+        Compositors must send this event once after creation of an
+        ext_workspace_handle_v1 . When the capabilities change, compositors
+        must send this event again.
+      </description>
+      <arg name="capabilities" type="uint" summary="capabilities" enum="workspace_capabilities"/>
+    </event>
+
+    <event name="removed">
+      <description summary="this workspace has been removed">
+        This event is send when the workspace associated with the ext_workspace_handle_v1
+        has been removed. After sending this request, the compositor will immediately consider
+        the object inert. Any requests will be ignored except the destroy request.
+
+        It is guaranteed there won't be any more events referencing this
+        ext_workspace_handle_v1.
+
+        The compositor must only remove a workspaces not currently belonging to any
+        workspace_group.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the ext_workspace_handle_v1 object">
+        Destroys the ext_workspace_handle_v1 object.
+
+        This request should be made either when the client does not want to
+        use the workspace object any more or after the remove event to finalize
+        the destruction of the object.
+      </description>
+    </request>
+
+    <request name="activate">
+      <description summary="activate the workspace">
+        Request that this workspace be activated.
+
+        There is no guarantee the workspace will be actually activated, and
+        behaviour may be compositor-dependent. For example, activating a
+        workspace may or may not deactivate all other workspaces in the same
+        group.
+      </description>
+    </request>
+
+    <request name="deactivate">
+      <description summary="deactivate the workspace">
+        Request that this workspace be deactivated.
+
+        There is no guarantee the workspace will be actually deactivated.
+      </description>
+    </request>
+
+    <request name="assign">
+      <description summary="assign workspace to group">
+        Requests that this workspace is assigned to the given workspace group.
+
+        There is no guarantee the workspace will be assigned.
+      </description>
+      <arg name="workspace_group" type="object" interface="ext_workspace_group_handle_v1"/>
+    </request>
+
+    <request name="remove">
+      <description summary="remove the workspace">
+        Request that this workspace be removed.
+
+        There is no guarantee the workspace will be actually removed.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/fifo/README

@@ -0,0 +1,4 @@
+Fifo Protocol
+
+Maintainers:
+Derek Foreman <derek.foreman@collabora.com> (@derekf)

staging/fifo/fifo-v1.xml

@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="fifo_v1">
+  <copyright>
+    Copyright © 2023 Valve Corporation
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_fifo_manager_v1" version="1">
+    <description summary="protocol for fifo constraints">
+      When a Wayland compositor considers applying a content update,
+      it must ensure all the update's readiness constraints (fences, etc)
+      are met.
+
+      This protocol provides a way to use the completion of a display refresh
+      cycle as an additional readiness constraint.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <enum name="error">
+      <description summary="fatal presentation error">
+        These fatal protocol errors may be emitted in response to
+        illegal requests.
+      </description>
+      <entry name="already_exists" value="0"
+             summary="fifo manager already exists for surface"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="unbind from the manager interface">
+        Informs the server that the client will no longer be using
+        this protocol object. Existing objects created by this object
+        are not affected.
+      </description>
+    </request>
+
+    <request name="get_fifo">
+      <description summary="request fifo interface for surface">
+        Establish a fifo object for a surface that may be used to add
+        display refresh constraints to content updates.
+
+        Only one such object may exist for a surface and attempting
+        to create more than one will result in an already_exists
+        protocol error. If a surface is acted on by multiple software
+        components, general best practice is that only the component
+        performing wl_surface.attach operations should use this protocol.
+      </description>
+      <arg name="id" type="new_id" interface="wp_fifo_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_fifo_v1" version="1">
+    <description summary="fifo interface">
+      A fifo object for a surface that may be used to add
+      display refresh constraints to content updates.
+    </description>
+
+    <enum name="error">
+      <description summary="fatal error">
+        These fatal protocol errors may be emitted in response to
+        illegal requests.
+      </description>
+      <entry name="surface_destroyed" value="0"
+             summary="the associated surface no longer exists"/>
+    </enum>
+
+    <request name="set_barrier">
+      <description summary="sets the start point for a fifo constraint">
+        When the content update containing the "set_barrier" is applied,
+        it sets a "fifo_barrier" condition on the surface associated with
+        the fifo object. The condition is cleared immediately after the
+        following latching deadline for non-tearing presentation.
+
+        The compositor may clear the condition early if it must do so to
+        ensure client forward progress assumptions.
+
+        To wait for this condition to clear, use the "wait_barrier" request.
+
+        "set_barrier" is double-buffered state, see wl_surface.commit.
+
+        Requesting set_barrier after the fifo object's surface is
+        destroyed will generate a "surface_destroyed" error.
+      </description>
+    </request>
+
+    <request name="wait_barrier">
+      <description summary="adds a fifo constraint to a content update">
+        Indicate that this content update is not ready while a
+        "fifo_barrier" condition is present on the surface.
+
+        This means that when the content update containing "set_barrier"
+        was made active at a latching deadline, it will be active for
+        at least one refresh cycle. A content update which is allowed to
+        tear might become active after a latching deadline if no content
+        update became active at the deadline.
+
+        The constraint must be ignored if the surface is a subsurface in
+        synchronized mode. If the surface is not being updated by the
+        compositor (off-screen, occluded) the compositor may ignore the
+        constraint. Clients must use an additional mechanism such as
+        frame callbacks or timestamps to ensure throttling occurs under
+        all conditions.
+
+        "wait_barrier" is double-buffered state, see wl_surface.commit.
+
+        Requesting "wait_barrier" after the fifo object's surface is
+        destroyed will generate a "surface_destroyed" error.
+      </description>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the fifo interface">
+        Informs the server that the client will no longer be using
+        this protocol object.
+
+        Surface state changes previously made by this protocol are
+        unaffected by this object's destruction.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/fractional-scale/README

@@ -0,0 +1,4 @@
+wp fractional scale protocol
+
+Maintainers:
+Kenny Levinsen <kl@kl.wtf> (@kennylevinsen)

staging/fractional-scale/fractional-scale-v1.xml

@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="fractional_scale_v1">
+  <copyright>
+    Copyright © 2022 Kenny Levinsen
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for requesting fractional surface scales">
+    This protocol allows a compositor to suggest for surfaces to render at
+    fractional scales.
+
+    A client can submit scaled content by utilizing wp_viewport. This is done by
+    creating a wp_viewport object for the surface and setting the destination
+    rectangle to the surface size before the scale factor is applied.
+
+    The buffer size is calculated by multiplying the surface size by the
+    intended scale.
+
+    The wl_surface buffer scale should remain set to 1.
+
+    If a surface has a surface-local size of 100 px by 50 px and wishes to
+    submit buffers with a scale of 1.5, then a buffer of 150px by 75 px should
+    be used and the wp_viewport destination rectangle should be 100 px by 50 px.
+
+    For toplevel surfaces, the size is rounded halfway away from zero. The
+    rounding algorithm for subsurface position and size is not defined.
+  </description>
+
+  <interface name="wp_fractional_scale_manager_v1" version="1">
+    <description summary="fractional surface scale information">
+      A global interface for requesting surfaces to use fractional scales.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="unbind the fractional surface scale interface">
+        Informs the server that the client will not be using this protocol
+        object anymore. This does not affect any other objects,
+        wp_fractional_scale_v1 objects included.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="fractional_scale_exists" value="0"
+        summary="the surface already has a fractional_scale object associated"/>
+    </enum>
+
+    <request name="get_fractional_scale">
+      <description summary="extend surface interface for scale information">
+        Create an add-on object for the the wl_surface to let the compositor
+        request fractional scales. If the given wl_surface already has a
+        wp_fractional_scale_v1 object associated, the fractional_scale_exists
+        protocol error is raised.
+      </description>
+      <arg name="id" type="new_id" interface="wp_fractional_scale_v1"
+           summary="the new surface scale info interface id"/>
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="the surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_fractional_scale_v1" version="1">
+    <description summary="fractional scale interface to a wl_surface">
+      An additional interface to a wl_surface object which allows the compositor
+      to inform the client of the preferred scale.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="remove surface scale information for surface">
+        Destroy the fractional scale object. When this object is destroyed,
+        preferred_scale events will no longer be sent.
+      </description>
+    </request>
+
+    <event name="preferred_scale">
+      <description summary="notify of new preferred scale">
+        Notification of a new preferred scale for this surface that the
+        compositor suggests that the client should use.
+
+        The sent scale is the numerator of a fraction with a denominator of 120.
+      </description>
+      <arg name="scale" type="uint" summary="the new preferred scale"/>
+    </event>
+  </interface>
+</protocol>

staging/linux-drm-syncobj/README

@@ -0,0 +1,4 @@
+Linux DRM syncobj protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr> (@emersion)

staging/linux-drm-syncobj/linux-drm-syncobj-v1.xml

@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="linux_drm_syncobj_v1">
+  <copyright>
+    Copyright 2016 The Chromium Authors.
+    Copyright 2017 Intel Corporation
+    Copyright 2018 Collabora, Ltd
+    Copyright 2021 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="protocol for providing explicit synchronization">
+    This protocol allows clients to request explicit synchronization for
+    buffers. It is tied to the Linux DRM synchronization object framework.
+
+    Synchronization refers to co-ordination of pipelined operations performed
+    on buffers. Most GPU clients will schedule an asynchronous operation to
+    render to the buffer, then immediately send the buffer to the compositor
+    to be attached to a surface.
+
+    With implicit synchronization, ensuring that the rendering operation is
+    complete before the compositor displays the buffer is an implementation
+    detail handled by either the kernel or userspace graphics driver.
+
+    By contrast, with explicit synchronization, DRM synchronization object
+    timeline points mark when the asynchronous operations are complete. When
+    submitting a buffer, the client provides a timeline point which will be
+    waited on before the compositor accesses the buffer, and another timeline
+    point that the compositor will signal when it no longer needs to access the
+    buffer contents for the purposes of the surface commit.
+
+    Linux DRM synchronization objects are documented at:
+    https://dri.freedesktop.org/docs/drm/gpu/drm-mm.html#drm-sync-objects
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="wp_linux_drm_syncobj_manager_v1" version="1">
+    <description summary="global for providing explicit synchronization">
+      This global is a factory interface, allowing clients to request
+      explicit synchronization for buffers on a per-surface basis.
+
+      See wp_linux_drm_syncobj_surface_v1 for more information.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy explicit synchronization factory object">
+        Destroy this explicit synchronization factory object. Other objects
+        shall not be affected by this request.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="surface_exists" value="0"
+        summary="the surface already has a synchronization object associated"/>
+      <entry name="invalid_timeline" value="1"
+        summary="the timeline object could not be imported"/>
+    </enum>
+
+    <request name="get_surface">
+      <description summary="extend surface interface for explicit synchronization">
+        Instantiate an interface extension for the given wl_surface to provide
+        explicit synchronization.
+
+        If the given wl_surface already has an explicit synchronization object
+        associated, the surface_exists protocol error is raised.
+
+        Graphics APIs, like EGL or Vulkan, that manage the buffer queue and
+        commits of a wl_surface themselves, are likely to be using this
+        extension internally. If a client is using such an API for a
+        wl_surface, it should not directly use this extension on that surface,
+        to avoid raising a surface_exists protocol error.
+      </description>
+      <arg name="id" type="new_id" interface="wp_linux_drm_syncobj_surface_v1"
+        summary="the new synchronization surface object id"/>
+      <arg name="surface" type="object" interface="wl_surface"
+        summary="the surface"/>
+    </request>
+
+    <request name="import_timeline">
+      <description summary="import a DRM syncobj timeline">
+        Import a DRM synchronization object timeline.
+
+        If the FD cannot be imported, the invalid_timeline error is raised.
+      </description>
+      <arg name="id" type="new_id" interface="wp_linux_drm_syncobj_timeline_v1"/>
+      <arg name="fd" type="fd" summary="drm_syncobj file descriptor"/>
+    </request>
+  </interface>
+
+  <interface name="wp_linux_drm_syncobj_timeline_v1" version="1">
+    <description summary="synchronization object timeline">
+      This object represents an explicit synchronization object timeline
+      imported by the client to the compositor.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the timeline">
+        Destroy the synchronization object timeline. Other objects are not
+        affected by this request, in particular timeline points set by
+        set_acquire_point and set_release_point are not unset.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="wp_linux_drm_syncobj_surface_v1" version="1">
+    <description summary="per-surface explicit synchronization">
+      This object is an add-on interface for wl_surface to enable explicit
+      synchronization.
+
+      Each surface can be associated with only one object of this interface at
+      any time.
+
+      Explicit synchronization is guaranteed to be supported for buffers
+      created with any version of the linux-dmabuf protocol. Compositors are
+      free to support explicit synchronization for additional buffer types.
+      If at surface commit time the attached buffer does not support explicit
+      synchronization, an unsupported_buffer error is raised.
+
+      As long as the wp_linux_drm_syncobj_surface_v1 object is alive, the
+      compositor may ignore implicit synchronization for buffers attached and
+      committed to the wl_surface. The delivery of wl_buffer.release events
+      for buffers attached to the surface becomes undefined.
+
+      Clients must set both acquire and release points if and only if a
+      non-null buffer is attached in the same surface commit. See the
+      no_buffer, no_acquire_point and no_release_point protocol errors.
+
+      If at surface commit time the acquire and release DRM syncobj timelines
+      are identical, the acquire point value must be strictly less than the
+      release point value, or else the conflicting_points protocol error is
+      raised.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the surface synchronization object">
+        Destroy this surface synchronization object.
+
+        Any timeline point set by this object with set_acquire_point or
+        set_release_point since the last commit may be discarded by the
+        compositor. Any timeline point set by this object before the last
+        commit will not be affected.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="no_surface" value="1"
+        summary="the associated wl_surface was destroyed"/>
+      <entry name="unsupported_buffer" value="2"
+        summary="the buffer does not support explicit synchronization"/>
+      <entry name="no_buffer" value="3" summary="no buffer was attached"/>
+      <entry name="no_acquire_point" value="4"
+        summary="no acquire timeline point was set"/>
+      <entry name="no_release_point" value="5"
+        summary="no release timeline point was set"/>
+      <entry name="conflicting_points" value="6"
+        summary="acquire and release timeline points are in conflict"/>
+    </enum>
+
+    <request name="set_acquire_point">
+      <description summary="set the acquire timeline point">
+        Set the timeline point that must be signalled before the compositor may
+        sample from the buffer attached with wl_surface.attach.
+
+        The 64-bit unsigned value combined from point_hi and point_lo is the
+        point value.
+
+        The acquire point is double-buffered state, and will be applied on the
+        next wl_surface.commit request for the associated surface. Thus, it
+        applies only to the buffer that is attached to the surface at commit
+        time.
+
+        If an acquire point has already been attached during the same commit
+        cycle, the new point replaces the old one.
+
+        If the associated wl_surface was destroyed, a no_surface error is
+        raised.
+
+        If at surface commit time there is a pending acquire timeline point set
+        but no pending buffer attached, a no_buffer error is raised. If at
+        surface commit time there is a pending buffer attached but no pending
+        acquire timeline point set, the no_acquire_point protocol error is
+        raised.
+      </description>
+      <arg name="timeline" type="object" interface="wp_linux_drm_syncobj_timeline_v1"/>
+      <arg name="point_hi" type="uint" summary="high 32 bits of the point value"/>
+      <arg name="point_lo" type="uint" summary="low 32 bits of the point value"/>
+    </request>
+
+    <request name="set_release_point">
+      <description summary="set the release timeline point">
+        Set the timeline point that must be signalled by the compositor when it
+        has finished its usage of the buffer attached with wl_surface.attach
+        for the relevant commit.
+
+        Once the timeline point is signaled, and assuming the associated buffer
+        is not pending release from other wl_surface.commit requests, no
+        additional explicit or implicit synchronization with the compositor is
+        required to safely re-use the buffer.
+
+        Note that clients cannot rely on the release point being always
+        signaled after the acquire point: compositors may release buffers
+        without ever reading from them. In addition, the compositor may use
+        different presentation paths for different commits, which may have
+        different release behavior. As a result, the compositor may signal the
+        release points in a different order than the client committed them.
+
+        Because signaling a timeline point also signals every previous point,
+        it is generally not safe to use the same timeline object for the
+        release points of multiple buffers. The out-of-order signaling
+        described above may lead to a release point being signaled before the
+        compositor has finished reading. To avoid this, it is strongly
+        recommended that each buffer should use a separate timeline for its
+        release points.
+
+        The 64-bit unsigned value combined from point_hi and point_lo is the
+        point value.
+
+        The release point is double-buffered state, and will be applied on the
+        next wl_surface.commit request for the associated surface. Thus, it
+        applies only to the buffer that is attached to the surface at commit
+        time.
+
+        If a release point has already been attached during the same commit
+        cycle, the new point replaces the old one.
+
+        If the associated wl_surface was destroyed, a no_surface error is
+        raised.
+
+        If at surface commit time there is a pending release timeline point set
+        but no pending buffer attached, a no_buffer error is raised. If at
+        surface commit time there is a pending buffer attached but no pending
+        release timeline point set, the no_release_point protocol error is
+        raised.
+      </description>
+      <arg name="timeline" type="object" interface="wp_linux_drm_syncobj_timeline_v1"/>
+      <arg name="point_hi" type="uint" summary="high 32 bits of the point value"/>
+      <arg name="point_lo" type="uint" summary="low 32 bits of the point value"/>
+    </request>
+  </interface>
+</protocol>

staging/pointer-warp/README

@@ -0,0 +1,7 @@
+pointer-warp protocol
+
+Maintainers:
+Neal Gompa <neal@gompa.dev> (@Conan_Kudo)
+Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)
+Matthias Klumpp <matthias@tenstral.net> (@mak)
+Vlad Zahorodnii <vlad.zahorodnii@kde.org> (@zzag)

staging/pointer-warp/pointer-warp-v1.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="pointer_warp_v1">
+  <copyright>
+    Copyright © 2024 Neal Gompa
+    Copyright © 2024 Xaver Hugl
+    Copyright © 2024 Matthias Klumpp
+    Copyright © 2024 Vlad Zahorodnii
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_pointer_warp_v1" version="1">
+    <description summary="reposition the pointer to a location on a surface">
+      This global interface allows applications to request the pointer to be
+      moved to a position relative to a wl_surface.
+
+      Note that if the desired behavior is to constrain the pointer to an area
+      or lock it to a position, this protocol does not provide a reliable way
+      to do that. The pointer constraint and pointer lock protocols should be
+      used for those use cases instead.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the warp manager">
+        Destroy the pointer warp manager.
+      </description>
+    </request>
+
+    <request name="warp_pointer">
+      <description summary="reposition the pointer">
+        Request the compositor to move the pointer to a surface-local position.
+        Whether or not the compositor honors the request is implementation defined,
+        but it should
+        - honor it if the surface has pointer focus, including
+          when it has an implicit pointer grab
+        - reject it if the enter serial is incorrect
+        - reject it if the requested position is outside of the surface
+
+        Note that the enter serial is valid for any surface of the client,
+        and does not have to be from the surface the pointer is warped to.
+
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="surface to position the pointer on"/>
+      <arg name="pointer" type="object" interface="wl_pointer"
+           summary="the pointer that should be repositioned"/>
+      <arg name="x" type="fixed"/>
+      <arg name="y" type="fixed"/>
+      <arg name="serial" type="uint" summary="serial number of the enter event"/>
+    </request>
+  </interface>
+</protocol>

staging/security-context/README

@@ -0,0 +1,4 @@
+security_context protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr> (@emersion)

staging/security-context/engines.md

@@ -0,0 +1,18 @@
+# security-context-v1 engines
+
+This document describes how some specific engine implementations populate the
+metadata in security-context-v1 and provide further metadata with out of band
+mechanisms.
+
+## [Flatpak]
+
+* `sandbox_engine` is always set to `org.flatpak`.
+* `app_id` is the Flatpak application ID (in reverse-DNS style). It is always
+  set.
+* `instance_id` is the Flatpak instance ID of the running sandbox. It is always
+  set.
+
+More metadata is stored in `$XDG_RUNTIME_DIR/.flatpak/$instance_id/info`. This
+file will be readable when `wp_security_context_v1.commit` is called.
+
+[Flatpak]: https://flatpak.org/

staging/security-context/security-context-v1.xml

@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="security_context_v1">
+  <copyright>
+    Copyright © 2021 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_security_context_manager_v1" version="1">
+    <description summary="client security context manager">
+      This interface allows a client to register a new Wayland connection to
+      the compositor and attach a security context to it.
+
+      This is intended to be used by sandboxes. Sandbox engines attach a
+      security context to all connections coming from inside the sandbox. The
+      compositor can then restrict the features that the sandboxed connections
+      can use.
+
+      Compositors should forbid nesting multiple security contexts by not
+      exposing wp_security_context_manager_v1 global to clients with a security
+      context attached, or by sending the nested protocol error. Nested
+      security contexts are dangerous because they can potentially allow
+      privilege escalation of a sandboxed client.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_listen_fd" value="1"
+        summary="listening socket FD is invalid"/>
+      <entry name="nested" value="2"
+        summary="nested security contexts are forbidden"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager object">
+        Destroy the manager. This doesn't destroy objects created with the
+        manager.
+      </description>
+    </request>
+
+    <request name="create_listener">
+      <description summary="create a new security context">
+        Creates a new security context with a socket listening FD.
+
+        The compositor will accept new client connections on listen_fd.
+        listen_fd must be ready to accept new connections when this request is
+        sent by the client. In other words, the client must call bind(2) and
+        listen(2) before sending the FD.
+
+        close_fd is a FD that will signal hangup when the compositor should stop
+        accepting new connections on listen_fd.
+
+        The compositor must continue to accept connections on listen_fd when
+        the Wayland client which created the security context disconnects.
+
+        After sending this request, closing listen_fd and close_fd remains the
+        only valid operation on them.
+      </description>
+      <arg name="id" type="new_id" interface="wp_security_context_v1"/>
+      <arg name="listen_fd" type="fd" summary="listening socket FD"/>
+      <arg name="close_fd" type="fd" summary="FD signaling when done"/>
+    </request>
+  </interface>
+
+  <interface name="wp_security_context_v1" version="1">
+    <description summary="client security context">
+      The security context allows a client to register a new client and attach
+      security context metadata to the connections.
+
+      When both are set, the combination of the application ID and the sandbox
+      engine must uniquely identify an application. The same application ID
+      will be used across instances (e.g. if the application is restarted, or
+      if the application is started multiple times).
+
+      When both are set, the combination of the instance ID and the sandbox
+      engine must uniquely identify a running instance of an application.
+    </description>
+
+    <enum name="error">
+      <entry name="already_used" value="1"
+        summary="security context has already been committed"/>
+      <entry name="already_set" value="2"
+        summary="metadata has already been set"/>
+      <entry name="invalid_metadata" value="3"
+        summary="metadata is invalid"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the security context object">
+        Destroy the security context object.
+      </description>
+    </request>
+
+    <request name="set_sandbox_engine">
+      <description summary="set the sandbox engine">
+        Attach a unique sandbox engine name to the security context. The name
+        should follow the reverse-DNS style (e.g. "org.flatpak").
+
+        A list of well-known engines is maintained at:
+        https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/security-context/engines.md
+
+        It is a protocol error to call this request twice. The already_set
+        error is sent in this case.
+      </description>
+      <arg name="name" type="string" summary="the sandbox engine name"/>
+    </request>
+
+    <request name="set_app_id">
+      <description summary="set the application ID">
+        Attach an application ID to the security context.
+
+        The application ID is an opaque, sandbox-specific identifier for an
+        application. See the well-known engines document for more details:
+        https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/security-context/engines.md
+
+        The compositor may use the application ID to group clients belonging to
+        the same security context application.
+
+        Whether this request is optional or not depends on the sandbox engine used.
+
+        It is a protocol error to call this request twice. The already_set
+        error is sent in this case.
+      </description>
+      <arg name="app_id" type="string" summary="the application ID"/>
+    </request>
+
+    <request name="set_instance_id">
+      <description summary="set the instance ID">
+        Attach an instance ID to the security context.
+
+        The instance ID is an opaque, sandbox-specific identifier for a running
+        instance of an application. See the well-known engines document for
+        more details:
+        https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/security-context/engines.md
+
+        Whether this request is optional or not depends on the sandbox engine used.
+
+        It is a protocol error to call this request twice. The already_set
+        error is sent in this case.
+      </description>
+      <arg name="instance_id" type="string" summary="the instance ID"/>
+    </request>
+
+    <request name="commit">
+      <description summary="register the security context">
+        Atomically register the new client and attach the security context
+        metadata.
+
+        If the provided metadata is inconsistent or does not match with out of
+        band metadata (see
+        https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/security-context/engines.md),
+        the invalid_metadata error may be sent eventually.
+
+        It's a protocol error to send any request other than "destroy" after
+        this request. In this case, the already_used error is sent.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/single-pixel-buffer/README

@@ -0,0 +1,4 @@
+Single-pixel buffer protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr> (@emersion)

staging/single-pixel-buffer/single-pixel-buffer-v1.xml

@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="single_pixel_buffer_v1">
+  <copyright>
+    Copyright © 2022 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="single pixel buffer factory">
+    This protocol extension allows clients to create single-pixel buffers.
+
+    Compositors supporting this protocol extension should also support the
+    viewporter protocol extension. Clients may use viewporter to scale a
+    single-pixel buffer to a desired size.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="wp_single_pixel_buffer_manager_v1" version="1">
+    <description summary="global factory for single-pixel buffers">
+      The wp_single_pixel_buffer_manager_v1 interface is a factory for
+      single-pixel buffers.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the wp_single_pixel_buffer_manager_v1 object.
+
+        The child objects created via this interface are unaffected.
+      </description>
+    </request>
+
+    <request name="create_u32_rgba_buffer">
+      <description summary="create a 1×1 buffer from 32-bit RGBA values">
+        Create a single-pixel buffer from four 32-bit RGBA values.
+
+        Unless specified in another protocol extension, the RGBA values use
+        pre-multiplied alpha.
+
+        The width and height of the buffer are 1.
+
+        The r, g, b and a arguments valid range is from UINT32_MIN (0)
+        to UINT32_MAX (0xffffffff).
+        
+        These arguments should be interpreted as a percentage, i.e.
+        - UINT32_MIN = 0% of the given color component
+        - UINT32_MAX = 100% of the given color component
+      </description>
+      <arg name="id" type="new_id" interface="wl_buffer"/>
+      <arg name="r" type="uint" summary="value of the buffer's red channel"/>
+      <arg name="g" type="uint" summary="value of the buffer's green channel"/>
+      <arg name="b" type="uint" summary="value of the buffer's blue channel"/>
+      <arg name="a" type="uint" summary="value of the buffer's alpha channel"/>
+    </request>
+  </interface>
+</protocol>

staging/tearing-control/README

@@ -0,0 +1,4 @@
+Tearing control protocol
+
+Maintainers:
+Xaver Hugl <xaver.hugl@gmail.com> (@Zamundaaa)

staging/tearing-control/tearing-control-v1.xml

@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="tearing_control_v1">
+  <copyright>
+    Copyright © 2021 Xaver Hugl
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="wp_tearing_control_manager_v1" version="1">
+    <description summary="protocol for tearing control">
+      For some use cases like games or drawing tablets it can make sense to
+      reduce latency by accepting tearing with the use of asynchronous page
+      flips. This global is a factory interface, allowing clients to inform
+      which type of presentation the content of their surfaces is suitable for.
+
+      Graphics APIs like EGL or Vulkan, that manage the buffer queue and commits
+      of a wl_surface themselves, are likely to be using this extension
+      internally. If a client is using such an API for a wl_surface, it should
+      not directly use this extension on that surface, to avoid raising a
+      tearing_control_exists protocol error.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy tearing control factory object">
+        Destroy this tearing control factory object. Other objects, including
+        wp_tearing_control_v1 objects created by this factory, are not affected
+        by this request.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="tearing_control_exists" value="0"
+             summary="the surface already has a tearing object associated"/>
+    </enum>
+
+    <request name="get_tearing_control">
+      <description summary="extend surface interface for tearing control">
+        Instantiate an interface extension for the given wl_surface to request
+        asynchronous page flips for presentation.
+
+        If the given wl_surface already has a wp_tearing_control_v1 object
+        associated, the tearing_control_exists protocol error is raised.
+      </description>
+      <arg name="id" type="new_id" interface="wp_tearing_control_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_tearing_control_v1" version="1">
+    <description summary="per-surface tearing control interface">
+      An additional interface to a wl_surface object, which allows the client
+      to hint to the compositor if the content on the surface is suitable for
+      presentation with tearing.
+      The default presentation hint is vsync. See presentation_hint for more
+      details.
+
+      If the associated wl_surface is destroyed, this object becomes inert and
+      should be destroyed.
+    </description>
+
+    <enum name="presentation_hint">
+      <description summary="presentation hint values">
+        This enum provides information for if submitted frames from the client
+        may be presented with tearing.
+      </description>
+      <entry name="vsync" value="0">
+        <description summary="tearing-free presentation">
+          The content of this surface is meant to be synchronized to the
+          vertical blanking period. This should not result in visible tearing
+          and may result in a delay before a surface commit is presented.
+        </description>
+      </entry>
+      <entry name="async" value="1">
+        <description summary="asynchronous presentation">
+          The content of this surface is meant to be presented with minimal
+          latency and tearing is acceptable.
+        </description>
+      </entry>
+    </enum>
+
+    <request name="set_presentation_hint">
+      <description summary="set presentation hint">
+        Set the presentation hint for the associated wl_surface. This state is
+        double-buffered, see wl_surface.commit.
+
+        The compositor is free to dynamically respect or ignore this hint based
+        on various conditions like hardware capabilities, surface state and
+        user preferences.
+      </description>
+      <arg name="hint" type="uint" enum="presentation_hint"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy tearing control object">
+        Destroy this surface tearing object and revert the presentation hint to
+        vsync. The change will be applied on the next wl_surface.commit.
+      </description>
+    </request>
+  </interface>
+
+</protocol>

staging/xdg-activation/README

@@ -0,0 +1,4 @@
+XDG Activation protocol
+
+Maintainers:
+Aleix Pol Gonzalez <aleixpol@kde.org> (@apol)

staging/xdg-activation/x11-interoperation.rst

@@ -0,0 +1,63 @@
+Interoperation with X11
+=======================
+
+*This document is non-normative.*
+
+The former
+`X11 Startup notification protocol <https://cgit.freedesktop.org/startup-notification/tree/doc/startup-notification.txt>`_
+defines the use of the ``DESKTOP_STARTUP_ID`` environment variable to propagate
+startup sequences ("activation tokens" in this protocol) between launcher and
+launchee.
+
+These startup sequence IDs are defined as a globally unique string with a
+``[unique]_TIME[timestamp]`` format, where the ID as a whole is used for startup
+notification and the timestamp is used for focus requests and focus stealing
+prevention.
+
+In order to observe mixed usage scenarios where Wayland and X11 clients might
+be launching each other, it is possible for a compositor to manage a shared
+pool of activation tokens.
+
+Scenario 1. Wayland client spawns X11 client
+--------------------------------------------
+
+1. Wayland client requests token.
+2. Wayland client spawns X11 client, sets ``$DESKTOP_STARTUP_ID`` in its
+   environment with the token string.
+3. X11 client starts.
+4. X11 client sends startup-notification ``remove`` message with the activation
+   ``$DESKTOP_STARTUP_ID`` content.
+5. Compositor receives startup notification message, matches ID with
+   the common pool.
+6. The startup feedback is finished.
+7. X11 client requests focus.
+8. Compositor applies internal policies to allow/deny focus switch.
+
+Scenario 2. X11 client spawns Wayland client
+--------------------------------------------
+
+1. X11 client builds a "globally unique" ID
+2. X11 client sends startup-notification ``new`` message with the ID.
+3. Compositor receives startup notification message, adds the ID to
+   the common pool.
+4. X11 client spawns Wayland client, sets ``$DESKTOP_STARTUP_ID`` in its
+   environment.
+5. Wayland client starts.
+6. Wayland client requests surface activation with the activation token,
+   as received from ``$DESKTOP_STARTUP_ID``.
+7. Compositor receives the request, matches ID with the common pool
+8. The startup feedback is finished.
+9. Compositor applies internal policies to allow/deny focus switch.
+
+Caveats
+-------
+
+- For legacy reasons, the usage of ``$DESKTOP_STARTUP_ID`` (even if as a
+  fallback) should be observed in compositors and clients that are
+  concerned with X11 interoperation.
+
+- Depending on the X11 startup-notification implementation in use by the
+  compositor, the usage of the ``_TIME[timestamp]`` suffix may be mandatory
+  for its correct behavior in the first scenario, the startup-notification
+  reference library is one such implementation. Compositors may work
+  this around by adding a matching suffix to the generated activation tokens.

staging/xdg-activation/xdg-activation-v1.xml

@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_activation_v1">
+
+  <copyright>
+    Copyright © 2020 Aleix Pol Gonzalez &lt;aleixpol@kde.org&gt;
+    Copyright © 2020 Carlos Garnacho &lt;carlosg@gnome.org&gt;
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for requesting activation of surfaces">
+    The way for a client to pass focus to another toplevel is as follows.
+
+    The client that intends to activate another toplevel uses the
+    xdg_activation_v1.get_activation_token request to get an activation token.
+    This token is then forwarded to the client, which is supposed to activate
+    one of its surfaces, through a separate band of communication.
+
+    One established way of doing this is through the XDG_ACTIVATION_TOKEN
+    environment variable of a newly launched child process. The child process
+    should unset the environment variable again right after reading it out in
+    order to avoid propagating it to other child processes.
+
+    Another established way exists for Applications implementing the D-Bus
+    interface org.freedesktop.Application, which should get their token under
+    activation-token on their platform_data.
+
+    In general activation tokens may be transferred across clients through
+    means not described in this protocol.
+
+    The client to be activated will then pass the token
+    it received to the xdg_activation_v1.activate request. The compositor can
+    then use this token to decide how to react to the activation request.
+
+    The token the activating client gets may be ineffective either already at
+    the time it receives it, for example if it was not focused, for focus
+    stealing prevention. The activating client will have no way to discover
+    the validity of the token, and may still forward it to the to be activated
+    client.
+
+    The created activation token may optionally get information attached to it
+    that can be used by the compositor to identify the application that we
+    intend to activate. This can for example be used to display a visual hint
+    about what application is being started.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="xdg_activation_v1" version="1">
+    <description summary="interface for activating surfaces">
+      A global interface used for informing the compositor about applications
+      being activated or started, or for applications to request to be
+      activated.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the xdg_activation object">
+        Notify the compositor that the xdg_activation object will no longer be
+        used.
+
+        The child objects created via this interface are unaffected and should
+        be destroyed separately.
+      </description>
+    </request>
+
+    <request name="get_activation_token">
+      <description summary="requests a token">
+        Creates an xdg_activation_token_v1 object that will provide
+        the initiating client with a unique token for this activation. This
+        token should be offered to the clients to be activated.
+      </description>
+
+      <arg name="id" type="new_id" interface="xdg_activation_token_v1"/>
+    </request>
+
+    <request name="activate">
+      <description summary="notify new interaction being available">
+        Requests surface activation. It's up to the compositor to display
+        this information as desired, for example by placing the surface above
+        the rest.
+
+        The compositor may know who requested this by checking the activation
+        token and might decide not to follow through with the activation if it's
+        considered unwanted.
+
+        Compositors can ignore unknown activation tokens when an invalid
+        token is passed.
+      </description>
+      <arg name="token" type="string" summary="the activation token of the initiating client"/>
+      <arg name="surface" type="object" interface="wl_surface"
+	   summary="the wl_surface to activate"/>
+    </request>
+  </interface>
+
+  <interface name="xdg_activation_token_v1" version="1">
+    <description summary="an exported activation handle">
+      An object for setting up a token and receiving a token handle that can
+      be passed as an activation token to another client.
+
+      The object is created using the xdg_activation_v1.get_activation_token
+      request. This object should then be populated with the app_id, surface
+      and serial information and committed. The compositor shall then issue a
+      done event with the token. In case the request's parameters are invalid,
+      the compositor will provide an invalid token.
+    </description>
+
+    <enum name="error">
+      <entry name="already_used" value="0"
+             summary="The token has already been used previously"/>
+    </enum>
+
+    <request name="set_serial">
+      <description summary="specifies the seat and serial of the activating event">
+        Provides information about the seat and serial event that requested the
+        token.
+
+        The serial can come from an input or focus event. For instance, if a
+        click triggers the launch of a third-party client, the launcher client
+        should send a set_serial request with the serial and seat from the
+        wl_pointer.button event.
+
+        Some compositors might refuse to activate toplevels when the token
+        doesn't have a valid and recent enough event serial.
+
+        Must be sent before commit. This information is optional.
+      </description>
+      <arg name="serial" type="uint"
+           summary="the serial of the event that triggered the activation"/>
+      <arg name="seat" type="object" interface="wl_seat"
+           summary="the wl_seat of the event"/>
+    </request>
+
+    <request name="set_app_id">
+      <description summary="specifies the application being activated">
+        The requesting client can specify an app_id to associate the token
+        being created with it.
+
+        Must be sent before commit. This information is optional.
+      </description>
+      <arg name="app_id" type="string"
+           summary="the application id of the client being activated."/>
+    </request>
+
+    <request name="set_surface">
+      <description summary="specifies the surface requesting activation">
+        This request sets the surface requesting the activation. Note, this is
+        different from the surface that will be activated.
+
+        Some compositors might refuse to activate toplevels when the token
+        doesn't have a requesting surface.
+
+        Must be sent before commit. This information is optional.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"
+	   summary="the requesting surface"/>
+    </request>
+
+    <request name="commit">
+      <description summary="issues the token request">
+        Requests an activation token based on the different parameters that
+        have been offered through set_serial, set_surface and set_app_id.
+      </description>
+    </request>
+
+    <event name="done">
+      <description summary="the exported activation token">
+        The 'done' event contains the unique token of this activation request
+        and notifies that the provider is done.
+      </description>
+      <arg name="token" type="string" summary="the exported activation token"/>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the xdg_activation_token_v1 object">
+        Notify the compositor that the xdg_activation_token_v1 object will no
+        longer be used. The received token stays valid.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/xdg-dialog/README

@@ -0,0 +1,5 @@
+Dialog windows
+
+Maintainers:
+Carlos Garnacho <carlosg@gnome.org> (@carlosg)
+Jonas Ådahl <jadahl@gmail.com> (@jadahl)

staging/xdg-dialog/xdg-dialog-v1.xml

@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_dialog_v1">
+  <copyright>
+    Copyright © 2023 Carlos Garnacho
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="xdg_wm_dialog_v1" version="1">
+    <description summary="create dialogs related to other toplevels">
+      The xdg_wm_dialog_v1 interface is exposed as a global object allowing
+      to register surfaces with a xdg_toplevel role as "dialogs" relative to
+      another toplevel.
+
+      The compositor may let this relation influence how the surface is
+      placed, displayed or interacted with.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <enum name="error">
+      <entry name="already_used" value="0"
+             summary="the xdg_toplevel object has already been used to create a xdg_dialog_v1"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the dialog manager object">
+        Destroys the xdg_wm_dialog_v1 object. This does not affect
+        the xdg_dialog_v1 objects generated through it.
+      </description>
+    </request>
+
+    <request name="get_xdg_dialog">
+      <description summary="create a dialog object">
+        Creates a xdg_dialog_v1 object for the given toplevel. See the interface
+        description for more details.
+
+	Compositors must raise an already_used error if clients attempt to
+	create multiple xdg_dialog_v1 objects for the same xdg_toplevel.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_dialog_v1"/>
+      <arg name="toplevel" type="object" interface="xdg_toplevel"/>
+    </request>
+  </interface>
+
+  <interface name="xdg_dialog_v1" version="1">
+    <description summary="dialog object">
+      A xdg_dialog_v1 object is an ancillary object tied to a xdg_toplevel. Its
+      purpose is hinting the compositor that the toplevel is a "dialog" (e.g. a
+      temporary window) relative to another toplevel (see
+      xdg_toplevel.set_parent). If the xdg_toplevel is destroyed, the xdg_dialog_v1
+      becomes inert.
+
+      Through this object, the client may provide additional hints about
+      the purpose of the secondary toplevel. This interface has no effect
+      on toplevels that are not attached to a parent toplevel.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the dialog object">
+        Destroys the xdg_dialog_v1 object. If this object is destroyed
+        before the related xdg_toplevel, the compositor should unapply its
+        effects.
+      </description>
+    </request>
+
+    <request name="set_modal">
+      <description summary="mark dialog as modal">
+        Hints that the dialog has "modal" behavior. Modal dialogs typically
+        require to be fully addressed by the user (i.e. closed) before resuming
+        interaction with the parent toplevel, and may require a distinct
+        presentation.
+
+        Clients must implement the logic to filter events in the parent
+        toplevel on their own.
+
+        Compositors may choose any policy in event delivery to the parent
+        toplevel, from delivering all events unfiltered to using them for
+        internal consumption.
+      </description>
+    </request>
+
+    <request name="unset_modal">
+      <description summary="mark dialog as not modal">
+        Drops the hint that this dialog has "modal" behavior. See
+        xdg_dialog_v1.set_modal for more details.
+      </description>
+    </request>
+  </interface>
+</protocol>

staging/xdg-session-management/README

@@ -0,0 +1,5 @@
+xdg session management protocol
+
+Maintainers:
+Jonas Ådahl <jadahl@gmail.com>
+Mike Blumenkrantz <michael.blumenkrantz@gmail.com>

staging/xdg-session-management/xdg-session-management-v1.xml

@@ -0,0 +1,333 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_session_management_v1">
+  <copyright>
+    Copyright 2018 Mike Blumenkrantz
+    Copyright 2018 Samsung Electronics Co., Ltd
+    Copyright 2018 Red Hat Inc.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for managing application sessions">
+    This description provides a high-level overview of the interplay between
+    the interfaces defined this protocol. For details, see the protocol
+    specification.
+
+    The xdg_session_manager protocol declares interfaces necessary to
+    allow clients to restore toplevel state from previous executions. The
+    xdg_session_manager_v1.get_session request can be used to obtain a
+    xdg_session_v1 resource representing the state of a set of toplevels.
+
+    Clients may obtain the session string to use in future calls through
+    the xdg_session_v1.created event. Compositors will use this string
+    as an identifiable token for future runs, possibly storing data about
+    the related toplevels in persistent storage. Clients that wish to
+    track sessions in multiple environments may use the $XDG_CURRENT_DESKTOP
+    environment variable.
+
+    Toplevels are managed through the xdg_session_v1.add_toplevel and
+    xdg_session_v1.remove_toplevel pair of requests. Clients will explicitly
+    request a toplevel to be restored according to prior state through the
+    xdg_session_v1.restore_toplevel request before the toplevel is mapped.
+
+    Compositors may store session information up to any arbitrary level, and
+    apply any limits and policies to the amount of data stored and its lifetime.
+    Clients must account for missing sessions and partial session restoration.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="xdg_session_manager_v1" version="1">
+    <description summary="manage sessions for applications">
+      The xdg_session_manager_v1 interface defines base requests for creating and
+      managing a session for an application. Sessions persist across application
+      and compositor restarts unless explicitly destroyed. A session is created
+      for the purpose of maintaining an application's xdg_toplevel surfaces
+      across compositor or application restarts. The compositor should remember
+      as many states as possible for surfaces in a given session, but there is
+      no requirement for which states must be remembered.
+
+      Policies such as cache eviction are declared an implementation detail of
+      the compositor. Clients should account for no longer existing sessions.
+    </description>
+
+    <enum name="error">
+      <entry name="in_use" summary="a requested session is already in use"
+             value="1"/>
+      <entry name="invalid_session_id" summary="invalid session identifier"
+             value="2"/>
+      <entry name="invalid_reason" summary="invalid reason" value="3"/>
+    </enum>
+
+    <enum name="reason">
+      <description summary="reason for getting a session">
+        The reason may determine in what way a session restores the window
+        management state of associated toplevels.
+
+        For example newly launched applications might be launched on the active
+        workspace with restored size and position, while a recovered
+        application might restore additional state such as active workspace and
+        stacking order.
+      </description>
+      <entry name="launch" value="1">
+        <description summary="an app is newly launched">
+          A new app instance is launched, for example from an app launcher.
+        </description>
+      </entry>
+      <entry name="recover" value="2">
+        <description summary="an app recovered">
+          An app instance is recovering from for example a compositor or app crash.
+        </description>
+      </entry>
+      <entry name="session_restore" value="3">
+        <description summary="an app restored">
+          An app instance is restored, for example part of a restored session, or
+          restored from having been temporarily terminated due to resource
+          constraints.
+        </description>
+      </entry>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy this object">
+        Destroy the manager object. The existing session objects will be
+        unaffected.
+      </description>
+    </request>
+
+    <request name="get_session">
+      <description summary="create or restore a session">
+        Create a session object corresponding to either an existing session
+        identified by the given session identifier string or a new session.
+        While the session object exists, the session is considered to be "in
+        use".
+
+        If an identifier string represents a session that is currently actively
+        in use by the the same client, an 'in_use' error is raised. If some
+        other client is currently using the same session, the new session will
+        replace managing the associated state.
+
+        If the reason is not a valid enum entry, the 'invalid_reason' protocol
+        error is raised.
+
+        NULL is passed to initiate a new session. If a session_id is passed
+        which does not represent a valid session, the compositor treats it as if
+        NULL had been passed.
+
+        The session id string must be UTF-8 encoded. It is also limited by the
+        maximum length of wayland messages (around 4KB). The 'invalid_session_id'
+        protocol error will be raised if an invalid string is provided.
+
+        A client is allowed to have any number of in use sessions at the same
+        time.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_session_v1"/>
+      <arg name="reason" type="uint" enum="reason"
+           summary="reason for session"/>
+      <arg name="session_id" type="string"
+           summary="the session to restore"
+           allow-null="true"/>
+    </request>
+  </interface>
+
+  <interface name="xdg_session_v1" version="1">
+    <description summary="A session for an application">
+      A xdg_session_v1 object represents a session for an application. While the
+      object exists, all surfaces which have been added to the session will
+      have states stored by the compositor which can be reapplied at a later
+      time. Two sessions cannot exist for the same identifier string.
+
+      States for surfaces added to a session are automatically updated by the
+      compositor when they are changed.
+    </description>
+
+    <enum name="error">
+      <entry name="name_in_use"
+             summary="toplevel name is already in use"
+             value="1"/>
+      <entry name="already_mapped"
+             summary="toplevel was already mapped when restored"
+             value="2"/>
+      <entry name="invalid_name"
+             summary="provided toplevel name is invalid"
+             value="3"/>
+      <entry name="already_added"
+             summary="toplevel already added"
+             value="4"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the session">
+        Destroy a session object, preserving the current state but not continuing
+        to make further updates if state changes occur. This makes the associated
+        xdg_toplevel_session_v1 objects inert.
+      </description>
+    </request>
+
+    <request name="remove" type="destructor">
+      <description summary="Remove the session">
+        Remove the session, making it no longer available for restoration. A
+        compositor should in response to this request remove the data related to
+        this session from its storage.
+      </description>
+    </request>
+
+    <request name="add_toplevel">
+      <description summary="add a new surface to the session">
+        Attempt to add a given surface to the session. The passed name is used
+        to identify what window is being restored, and may be used to store
+        window specific state within the session.
+
+        The name given to the toplevel must not correspond to any previously
+        existing toplevel names in the session. If the name matches an already
+        known toplevel name in the session, a 'name_in_use' protocol error will
+        be raised.
+
+        The toplevel object must not be added more than once to any session
+        created by the client, otherwise the 'already_added' protocol error
+        will be raised.
+
+        This request will return a xdg_toplevel_session_v1 for later
+        manipulation. As this resource is created from an empty initial state,
+        compositors must not emit a xdg_toplevel_session_v1.restored event for
+        resources created through this request.
+
+        The name string must be UTF-8 encoded. It is also limited by the maximum
+        length of wayland messages (around 4KB). The 'invalid_name' protocol
+        error will be raised if an invalid string is provided.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_toplevel_session_v1"/>
+      <arg name="toplevel" type="object" interface="xdg_toplevel"/>
+      <arg name="name" type="string" summary="name identifying the toplevel"/>
+    </request>
+
+    <request name="restore_toplevel">
+      <description summary="restore a surface state">
+        Inform the compositor that the toplevel associated with the passed name
+        should have its window management state restored.
+
+        If the toplevel name was previously granted to another xdg_toplevel,
+        the 'name_in_use' protocol error will be raised.
+
+        The toplevel object must not be added more than once to any session
+        created by the client, otherwise the 'already_added' protocol error
+        will be raised.
+
+        This request must be called prior to the first commit on the associated
+        wl_surface after creating the toplevel, otherwise an 'already_mapped'
+        error is raised.
+
+        As part of the initial configure sequence, if the toplevel was
+        successfully restored, a xdg_toplevel_session_v1.restored event is
+        emitted. If the toplevel name was not known in the session, this request
+        will be equivalent to the xdg_toplevel_session_v1.add_toplevel request,
+        and no such event will be emitted. See the xdg_toplevel_session_v1.restored
+        event for further details.
+
+        The name string must be UTF-8 encoded. It is also limited by the maximum
+        length of wayland messages (around 4KB). The 'invalid_name' protocol
+        error will be raised if an invalid string is provided.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_toplevel_session_v1"/>
+      <arg name="toplevel" type="object" interface="xdg_toplevel"/>
+      <arg name="name" type="string" summary="name identifying the toplevel"/>
+    </request>
+
+    <request name="remove_toplevel">
+      <description summary="remove a surface from the session">
+        Remove a specified surface from the session and render any related
+        xdg_toplevel_session_v1 object inert. The compositor should remove any
+        data related to the toplevel in the corresponding session from its internal
+        storage.
+
+        The window is specified by its name in the session. The name string
+        must be encoded in UTF-8, and it is limited in size by the maximum
+        length of wayland messages (around 4KB).
+      </description>
+      <arg name="name" type="string" summary="name identifying the toplevel"/>
+    </request>
+
+    <event name="created">
+      <description summary="newly-created session id">
+        Emitted at most once some time after getting a new session object. It
+        means that no previous state was restored, and a new session was created.
+        The passed id can be persistently stored and used to restore previous
+        sessions.
+      </description>
+      <arg name="session_id" type="string"/>
+    </event>
+
+    <event name="restored">
+      <description summary="the session has been restored">
+        Emitted at most once some time after getting a new session object. It
+        means that previous state was at least partially restored. The same id
+        can again be used to restore previous sessions.
+      </description>
+    </event>
+
+    <event name="replaced">
+      <description summary="the session has been replaced">
+        Emitted at most once, if the session was taken over by some other
+        client. When this happens, the session and all its toplevel session
+        objects become inert, and should be destroyed.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="xdg_toplevel_session_v1" version="1">
+    <description summary="A session for an application">
+      A xdg_toplevel_session_v1 resource acts as a handle for the given
+      toplevel in the session. It allows for receiving events after a
+      toplevel state was restored, and has the requests to manage them.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the object">
+        Destroy the object. This has no effect over window management of the
+        associated toplevel.
+      </description>
+    </request>
+
+    <request name="rename">
+      <description summary="change the name of toplevel session">
+        Renames the toplevel session. The new name can be used in subsequent requests
+        to identify this session object. The state associated with this toplevel
+        session will be preserved.
+
+        If the xdg_session_v1 already contains a toplevel with the specified name,
+        the 'name_in_use' protocol error will be raised.
+      </description>
+      <arg name="name" type="string" summary="new name to identify the toplevel"/>
+    </request>
+
+    <event name="restored">
+      <description summary="a toplevel's session has been restored">
+        The "restored" event is emitted prior to the first
+        xdg_toplevel.configure for the toplevel. It will only be emitted after
+        xdg_session_v1.restore_toplevel, and the initial empty surface state has
+        been applied, and it indicates that the surface's session is being
+        restored with this configure event.
+      </description>
+    </event>
+  </interface>
+</protocol>

staging/xdg-system-bell/README

@@ -0,0 +1,5 @@
+system_bell protocol
+
+Maintainers:
+Jonas Ådahl <jadahl@gmail.com>
+Carlos Garnacho <carlosg@gnome.org>

staging/xdg-system-bell/xdg-system-bell-v1.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_system_bell_v1">
+  <copyright>
+    Copyright © 2016, 2023 Red Hat
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="xdg_system_bell_v1" version="1">
+    <description summary="system bell">
+      This global interface enables clients to ring the system bell.
+
+      Warning! The protocol described in this file is currently in the testing
+      phase. Backward compatible changes may be added together with the
+      corresponding interface version bump. Backward incompatible changes can
+      only be done by creating a new major version of the extension.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the system bell object">
+	Notify that the object will no longer be used.
+      </description>
+    </request>
+
+    <request name="ring">
+      <description summary="ring the system bell">
+	This requests rings the system bell on behalf of a client. How ringing
+	the bell is implemented is up to the compositor. It may be an audible
+	sound, a visual feedback of some kind, or any other thing including
+	nothing.
+
+        The passed surface should correspond to a toplevel like surface role,
+        or be null, meaning the client doesn't have a particular toplevel it
+        wants to associate the bell ringing with. See the xdg-shell protocol
+        extension for a toplevel like surface role.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface"
+	   allow-null="true" summary="associated surface"/>
+    </request>
+  </interface>
+</protocol>

staging/xdg-toplevel-drag/README

@@ -0,0 +1,5 @@
+xdg toplevel drag protocol
+
+Maintainers:
+David Redondo <kde@david-redondo.de> (@davidre)
+Nick Yamane <nickdiego@igalia.com> (@nickdiego)