From 68a8164a3e197e04c406ee7d9d0b913ce9f7dd48 Mon Sep 17 00:00:00 2001 From: vasilito Date: Mon, 20 Jul 2026 09:02:21 +0900 Subject: [PATCH] wayland-protocols: sync tracked source tree to 1.49 Sync the tracked source tree to the wayland-protocols 1.49 release tarball already pinned in recipe.toml (blake3-verified). Upstream 1.49 drops the pkg-config .pc.in files, switches scanner discovery to a native wayland-scanner dependency with fallback, and adds the new stable/staging protocol XMLs (ext-image-*, xdg-toplevel-icon, cursor-shape, content-type, alpha-modifier, ...). --- .../wayland-protocols/source/.gitlab-ci.yml | 4 +- .../source/.gitlab-ci/debian-install.sh | 2 +- .../wayland-protocols/source/GOVERNANCE.md | 162 +- .../wayland-protocols/source/MEMBERS.md | 6 +- .../wayland-protocols/source/README.md | 139 +- .../source/experimental/xx-cutouts/README | 4 + .../experimental/xx-cutouts/xx-cutouts-v1.xml | 232 +++ .../experimental/xx-fractional-scale/README | 4 + .../xx-fractional-scale-v2.xml | 128 ++ .../experimental/xx-input-method/README | 4 + .../xx-input-method/xx-input-method-v2.xml | 948 +++++++++ .../experimental/xx-keyboard-filter/README | 4 + .../xx-keyboard-filter-v1.xml | 178 ++ .../experimental/xx-session-management/README | 4 + .../xx-session-management-v1.xml | 264 +++ .../source/experimental/xx-text-input/README | 6 + .../xx-text-input/xx-text-input-v3.xml | 592 ++++++ .../source/experimental/xx-zones/README | 4 + .../experimental/xx-zones/xx-zones-v1.xml | 493 +++++ .../include/wayland-protocols/meson.build | 2 +- .../wayland-protocols/source/meson.build | 225 ++- .../source/stable/linux-dmabuf/feedback.rst | 31 +- .../stable/linux-dmabuf/linux-dmabuf-v1.xml | 126 +- .../source/stable/tablet/tablet-v2.xml | 393 ++-- .../source/stable/xdg-shell/xdg-shell.xml | 115 +- .../alpha-modifier/alpha-modifier-v1.xml | 2 +- .../source/staging/color-management/README | 11 + .../staging/color-management/appendix.md | 144 ++ .../color-management/color-management-v1.xml | 1756 +++++++++++++++++ .../staging/color-representation/README | 6 + .../color-representation-v1.xml | 433 ++++ .../staging/color-representation/notes.rst | 79 + .../staging/content-type/content-type-v1.xml | 2 +- .../staging/cursor-shape/cursor-shape-v1.xml | 14 +- .../source/staging/drm-lease/README | 2 +- .../staging/ext-background-effect/README | 6 + .../ext-background-effect-v1.xml | 129 ++ .../source/staging/ext-data-control/README | 4 + .../ext-data-control/ext-data-control-v1.xml | 276 +++ .../ext-foreign-toplevel-list-v1.xml | 2 +- .../ext-idle-notify/ext-idle-notify-v1.xml | 39 +- .../ext-image-capture-source-v1.xml | 2 +- .../ext-image-copy-capture-v1.xml | 4 +- .../source/staging/ext-workspace/README | 5 + .../ext-workspace/ext-workspace-v1.xml | 422 ++++ .../source/staging/pointer-warp/README | 7 + .../staging/pointer-warp/pointer-warp-v1.xml | 72 + .../single-pixel-buffer-v1.xml | 7 + .../staging/xdg-session-management/README | 5 + .../xdg-session-management-v1.xml | 333 ++++ .../source/staging/xdg-toplevel-drag/README | 1 + .../xdg-toplevel-icon-v1.xml | 12 +- .../source/staging/xdg-toplevel-tag/README | 4 + .../xdg-toplevel-tag/xdg-toplevel-tag-v1.xml | 85 + .../source/tests/meson.build | 45 +- .../pointer-gestures-unstable-v1.xml | 28 +- .../text-input/text-input-unstable-v3.xml | 163 +- .../xdg-decoration-unstable-v1.xml | 32 +- .../wayland-protocols-uninstalled.pc.in | 5 - .../source/wayland-protocols.pc.in | 7 - 60 files changed, 7760 insertions(+), 454 deletions(-) create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/README create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/xx-cutouts-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/README create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/xx-fractional-scale-v2.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/README create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/xx-input-method-v2.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/README create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/xx-keyboard-filter-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/README create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/xx-session-management-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/README create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/xx-text-input-v3.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/README create mode 100644 local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/xx-zones-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/color-management/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/color-management/appendix.md create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/color-management/color-management-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/color-representation/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/color-representation/color-representation-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/color-representation/notes.rst create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/ext-background-effect-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/ext-data-control-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/ext-workspace-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/pointer-warp-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/xdg-session-management-v1.xml create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/README create mode 100644 local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/xdg-toplevel-tag-v1.xml delete mode 100644 local/recipes/wayland/wayland-protocols/source/wayland-protocols-uninstalled.pc.in delete mode 100644 local/recipes/wayland/wayland-protocols/source/wayland-protocols.pc.in diff --git a/local/recipes/wayland/wayland-protocols/source/.gitlab-ci.yml b/local/recipes/wayland/wayland-protocols/source/.gitlab-ci.yml index 5c9e82378d..1de0113a6e 100644 --- a/local/recipes/wayland/wayland-protocols/source/.gitlab-ci.yml +++ b/local/recipes/wayland/wayland-protocols/source/.gitlab-ci.yml @@ -25,9 +25,9 @@ workflow: .debian: variables: - FDO_DISTRIBUTION_VERSION: bookworm + FDO_DISTRIBUTION_VERSION: trixie FDO_DISTRIBUTION_PACKAGES: 'build-essential pkg-config meson git ca-certificates libffi-dev libexpat1-dev libxml2-dev' - FDO_DISTRIBUTION_TAG: '2024-09-05.0' + FDO_DISTRIBUTION_TAG: '2026-04-05.0' FDO_DISTRIBUTION_EXEC: 'env FDO_CI_CONCURRENT=${FDO_CI_CONCURRENT} ./.gitlab-ci/debian-install.sh' check-commit: diff --git a/local/recipes/wayland/wayland-protocols/source/.gitlab-ci/debian-install.sh b/local/recipes/wayland/wayland-protocols/source/.gitlab-ci/debian-install.sh index a66624f8cd..e6bb06c7fc 100755 --- a/local/recipes/wayland/wayland-protocols/source/.gitlab-ci/debian-install.sh +++ b/local/recipes/wayland/wayland-protocols/source/.gitlab-ci/debian-install.sh @@ -2,7 +2,7 @@ # Note: don't forget to bump FDO_DISTRIBUTION_TAG when editing this file! -git clone --branch 1.23.1 --depth=1 https://gitlab.freedesktop.org/wayland/wayland +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 diff --git a/local/recipes/wayland/wayland-protocols/source/GOVERNANCE.md b/local/recipes/wayland/wayland-protocols/source/GOVERNANCE.md index c583da9aad..407cd50515 100644 --- a/local/recipes/wayland/wayland-protocols/source/GOVERNANCE.md +++ b/local/recipes/wayland/wayland-protocols/source/GOVERNANCE.md @@ -13,39 +13,47 @@ standardization. ### 1.1. Membership requirements 1. Membership is extended to projects, rather than individuals. -2. Members 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 project must provide one or two named individuals as points-of-contact +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 two points-of-contact for the same member disagree, the - member's vote is considered blank. +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 members who meet the criteria outlined in 1.1 are established by +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 asking for this invitation. -2. New members shall write to the wayland-devel mailing list stating their - intention of joining and their sponsor. -3. The sponsor shall respond acknowledging their sponsorship of the membership. + 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 members. +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 may step down by writing their intention to do so to the - wayland-devel mailing list. -2. A removal vote may be called for by an existing member by posting to the - wayland-devel mailing list. This begins a 14 day voting & discussion - period. +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 members. + 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 who called for the vote cannot +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 @@ -65,6 +73,12 @@ standardization. 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 @@ -77,13 +91,21 @@ standardization. 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 members. + 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's point-of-contact different from the author. + 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 @@ -92,9 +114,9 @@ standardization. 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. Protocols which require a - certain level of implementation status, ACKs from members, and so on, should - use this time to acquire them. + 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. @@ -102,14 +124,94 @@ standardization. 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. -## 3. Amending this document +### 2.4. Development stalemate resolution -1. An amendment to this document may be proposed any member by +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 members, - and NACKed by none. The sponsoring member may merge their change to the - wayland-protocols repository at this point. + 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. diff --git a/local/recipes/wayland/wayland-protocols/source/MEMBERS.md b/local/recipes/wayland/wayland-protocols/source/MEMBERS.md index 2946f817c4..97e994d240 100644 --- a/local/recipes/wayland/wayland-protocols/source/MEMBERS.md +++ b/local/recipes/wayland/wayland-protocols/source/MEMBERS.md @@ -3,7 +3,8 @@ - GTK/Mutter: Jonas Ådahl (@jadahl), Carlos Garnacho (@carlosg) - KWin: Vlad Zahorodnii (@zzag), - David Edmundson (@davidedmundson) + David Edmundson (@davidedmundson), + Xaver Hugl (@Zamundaaa) - mesa: Daniel Stone (@daniels), Mike Blumenkrantz (@zmike) - Mir: Christopher James Halse Rogers (@RAOF), @@ -15,3 +16,6 @@ Derek Foreman (@derekf) - wlroots/Sway: Simon Ser (@emersion), Simon Zeni (@bl4ckb0ne) +- Chromium: Fangzhou Ge (@fangzhoug), + Nick Yamane (@nickdiego), + Max Ihlenfeldt (@mihlenfeldt) diff --git a/local/recipes/wayland/wayland-protocols/source/README.md b/local/recipes/wayland/wayland-protocols/source/README.md index 901047c609..7110eca122 100644 --- a/local/recipes/wayland/wayland-protocols/source/README.md +++ b/local/recipes/wayland/wayland-protocols/source/README.md @@ -16,28 +16,30 @@ compositor and client developers. The governance rules are described in ## Protocol phases -Protocols in general have three phases: the development phase, the testing -phase, and the stable phase. +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. -In the development phase, a protocol is not officially part of -wayland-protocols, but is actively being developed, for example by -iterating over it in a [merge request] or planning it in an [issue]. +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. -During this phase, patches for clients and compositors are written as a test -vehicle. Such patches must not be merged in clients and compositors, because -the protocol can still change. +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, -and after the [GOVERNANCE section 2.3] requirements have been met, it enters -the "testing" phase. At this point, the protocol is added to the `staging/` -directory of wayland-protocols and made part of a release. What this means is -that implementation is encouraged in clients and compositors where the -functionality it specifies is wanted. - -Extensions in staging cannot have backward incompatible changes, in that -sense they are equal to stable extensions. However, they may be completely -replaced with a new major version, or a different protocol extension altogether, -if design flaws are found in the testing phase. +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 @@ -53,11 +55,10 @@ 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 protocols initially -placed in the `unstable/` directory had certain naming conventions were +previously used by wayland-protocols, where certain naming conventions were applied, requiring a backward incompatible change to be declared "stable". -During this phase, protocol extension interface names were, in addition to +During this phase, protocol interface names were, in addition to the major version postfix, also prefixed with `z` to distinguish them from stable protocols. @@ -66,8 +67,9 @@ stable protocols. 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, and deprecated protocols are -placed in the `deprecated/` directory. +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. @@ -94,6 +96,16 @@ 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 @@ -114,10 +126,10 @@ prefixed with both `wp_` and the operating system, for example For more information about namespaces, see [GOVERNANCE section 2.1]. -Each new 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. +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. @@ -128,17 +140,6 @@ 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. -## Include a disclaimer - -Include the following disclaimer: - -``` -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. -``` - ## Use of RFC 2119 keywords Descriptions of all new protocols must use (in lowercase) and adhere to the @@ -166,9 +167,8 @@ element attributes. ## Backward incompatible protocol changes -While not preferred, a protocol may at any stage, especially during the -testing phase, when it is located in the `staging/` directory, see -backward incompatible 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: @@ -181,13 +181,56 @@ do so is the following: the interfaces to 1. - Remove all of the `since` attributes. -## Declaring a protocol stable +## 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. -The procedure of doing this is the following: +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. @@ -195,24 +238,18 @@ The procedure of doing this is the following: 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 testing phase. +- 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 extension has been marked stable. This copy is +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. ``` -Note that the major version of the stable protocol extension, as well as -all the interface versions and names, must remain unchanged. - -There are other requirements for declaring a protocol stable, see -[GOVERNANCE section 2.3]. - ## Releases Each release of wayland-protocols finalizes the version of the protocols diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/README b/local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/README new file mode 100644 index 0000000000..5ef267be83 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/README @@ -0,0 +1,4 @@ +xx cutouts protocol + +Maintainers: +Guido Günther diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/xx-cutouts-v1.xml b/local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/xx-cutouts-v1.xml new file mode 100644 index 0000000000..62a86e78ed --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/xx-cutouts-v1.xml @@ -0,0 +1,232 @@ + + + + + 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. + + + + 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. + + + + + This interface allows a compositor to announce support for + supplying cutout information to the client. + + + + + + + + + + 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. + + + + + + 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. + + + + + + + + + + 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. + + + + + These values indicate the type of cutout. The information is + meant to help clients to decide whether they can possibly + ignore the element. + + + + + This element type can be used by the compositor if it + doesn't want to provide a more specific type. + + + + + A functional, irregular shape on one of the device's + edges. It often contains a camera. + + + + + A curved display edge intended to make the device appear + like not having any bezel. + + + + + + + The position of a corner on a surface + + + + + + + + + + + + + + + Using this request a client can tell the server that it is not + going to use the xx_cutouts object anymore. + + + + + + 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. + + + + + + + + + + + + The cutout_corner event describes a rounded corner in + surface-local coordinates. The area towards the screen edge is + the cutout corner part. + + + + + + + + + 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. + + + + + + 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. + + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/README b/local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/README new file mode 100644 index 0000000000..2fd452e8be --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/README @@ -0,0 +1,4 @@ +xx fractional scale v2 protocol + +Maintainers: +Xaver Hugl (@Zamundaaa) diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/xx-fractional-scale-v2.xml b/local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/xx-fractional-scale-v2.xml new file mode 100644 index 0000000000..12ae5d347c --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/xx-fractional-scale-v2.xml @@ -0,0 +1,128 @@ + + + + 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. + + + + This protocol allows compositors and clients to communicate the + coordinate space their surfaces act in. + + + + + A global interface to create xx_fractional_scale_v2 interfaces. + + + + + Informs the server that the client will not be using this protocol + object anymore. This does not affect any other objects. + + + + + + + + + + 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. + + + + + + + + + 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. + + + + + 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. + + + + + + + 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. + + + + + + + The wl_surface's xx_fractional_scale_v2 object is destroyed, and the + associated scale is reset to 1. + + + + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/README b/local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/README new file mode 100644 index 0000000000..5e16fdc721 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/README @@ -0,0 +1,4 @@ +Input method protocol + +Maintainers: +Dorota Czaplejewicz \ No newline at end of file diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/xx-input-method-v2.xml b/local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/xx-input-method-v2.xml new file mode 100644 index 0000000000..2e64c2f6f3 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/xx-input-method-v2.xml @@ -0,0 +1,948 @@ + + + + + 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. + + + + 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. + + + + + 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. + + + + + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + + + + 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. + + + + + + + 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. + + + + + + + + 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. + + + + + + + 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. + + + + + + + Tells the input method client what kinds of events the text input client supports. + + + + + Changes the meaning of serial compared to v3. + The text input client now applies requested updates on a "best-effort" basis. + + + + + + + + Tells the input method client what kinds of events the text input client supports. + + + + 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. + + + + + + + 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. + + + + + + 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. + + + + + + + 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. + + + + + + + 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. + + + + + + + + + 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. + + + + + + + + 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. + + + + + + + + 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. + + + + + + + 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. + + + + + + + + + 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. + + + + + + Destroys the xx_input_method_v1 object and any associated child + objects. + + + + + + + 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. + + + + + + + + + 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 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. + + + + + + + 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. + + + + + + + + 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. + + + + + + + This destroys the popup. Explicitly destroying the input_popup_surface + object will also dismiss the popup, and unmap the surface. + + + + + + + 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. + + + + + + + + + Notify the compositor that the positioner will no longer be used. + + + + + + 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. + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + 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. + + + + + + + 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. + + + + Don't alter the surface position even if it is constrained on some + axis, for example partially outside the edge of an output. + + + + + 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. + + + + + 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. + + + + + 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. + + + + + 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. + + + + + Resize the surface horizontally so that it is completely + unconstrained. + + + + + Resize the surface vertically so that it is completely unconstrained. + + + + + + + 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. + + + + + + + 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. + + + + + + + + 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. + + + + + + + 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. + + + + + Request a new input xx_input_method_v1 object associated with a given + seat. + + + + + + + + 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. + + + + + + + Destroys the xx_input_method_manager_v2 object. + + The xx_input_method_v1 objects originating from it remain valid. + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/README b/local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/README new file mode 100644 index 0000000000..2848dd184a --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/README @@ -0,0 +1,4 @@ +Keyboard filter protocol + +Maintainers: +Dorota Czaplejewicz \ No newline at end of file diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/xx-keyboard-filter-v1.xml b/local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/xx-keyboard-filter-v1.xml new file mode 100644 index 0000000000..4af0aea0c0 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/xx-keyboard-filter-v1.xml @@ -0,0 +1,178 @@ + + + + + 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. + + + + 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. + + + + + Manages the filtering of key presses. + + + + + + + + + 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. + + + + + + + + + + + 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. + + + + + + + + Destroys the keyboard_filter object, stops event interception, and unbinds the wl_keyboard and input_method objects bound to it. + + + + + + + + + + + + + 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. + + + + + + + + + + Destroys the xx_keyboard_filter_manager_v1 object. + + The xx_keyboard_filter_v1 objects originating from it remain unaffected. + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/README b/local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/README new file mode 100644 index 0000000000..f5fd4d3961 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/README @@ -0,0 +1,4 @@ +Session management protocol + +Maintainers: +Carlos Garnacho diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/xx-session-management-v1.xml b/local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/xx-session-management-v1.xml new file mode 100644 index 0000000000..a7f5570996 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/xx-session-management-v1.xml @@ -0,0 +1,264 @@ + + + + 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. + + + + 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. + + + + + 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. + + + + + + + + + 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. + + + + A new app instance is launched, for example from an app launcher. + + + + + An app instance is recovering from for example a compositor or app crash. + + + + + An app instance is restored, for example part of a restored session, or + restored from having been temporarily terminated due to resource + constraints. + + + + + + + This has no effect other than to destroy the xx_session_manager object. + + + + + + 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. + + + + + + + + + + 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. + + + + + + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + + + + 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. + + + + + + + + + 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. + + + + + + + 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. + + + + + + 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. + + + + + + + + Destroy the object. This has no effect window management of the + associated toplevel. + + + + + + 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. + + + + + + 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. + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/README b/local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/README new file mode 100644 index 0000000000..f63be2b1d2 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/README @@ -0,0 +1,6 @@ +Text input protocol + +Maintainers: +Dorota Czaplejewicz + + diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/xx-text-input-v3.xml b/local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/xx-text-input-v3.xml new file mode 100644 index 0000000000..6d6ce5c6bb --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/xx-text-input-v3.xml @@ -0,0 +1,592 @@ + + + + + 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. + + + + 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. + + + + + 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. + + + + + Destroy the xx_text_input object. Also disables all surfaces enabled + through this xx_text_input object. + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + + + + Reason for the change of surrounding text or cursor posision. + + + + + + + + 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. + + + + + + + Content hint is a bitmask to allow to modify the behavior of the text + input. + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + 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. + + + + + + + + + + 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. + + + + + + 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. + + + + + + + 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. + + + + + + + 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. + + + + + + + + + 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. + + + + + + + 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. + + + + + + + + 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. + + + 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. + + + + + + + + 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. + + + + + + + A possible action to perform on a text input. + + + + This enum value exists only to provide a default to make double-buffering implementation easier. It should not be used explicitly. + + + + + + + + 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. + + + + + + + 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. + + + + + + + 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. + + + + + + + + + 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. + + + + + + + + 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. + + + + + + + + A factory for text-input objects. This object is a global singleton. + + + + + Destroy the xx_text_input_manager object. + + + + + + Creates a new text-input object for a given seat. + + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/README b/local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/README new file mode 100644 index 0000000000..fffb969523 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/README @@ -0,0 +1,4 @@ +Zones protocol + +Maintainers: +Matthias Klumpp (@mak) diff --git a/local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/xx-zones-v1.xml b/local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/xx-zones-v1.xml new file mode 100644 index 0000000000..63468e04e7 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/xx-zones-v1.xml @@ -0,0 +1,493 @@ + + + + + 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. + + + + 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. + + + + + The 'xx_zone_manager' interface defines base requests for obtaining and + managing zones for a client. + + + + + This has no effect other than to destroy the xx_zone_manager object. + + + + + + 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. + + + + + + + + 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. + + + + + + + + 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. + + + + + + + + + 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. + + + + + 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. + + + + + + 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. + + + + + + + + + + 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 & 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. + + + + + + + + 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. + + + + + + + + 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. + + + + + + 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. + + + + + + + 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'. + + + + + 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. + + + + + + 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. + + + + + + + + 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. + + + + + + + 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. + + + + + + + + + + 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. + + + + + + + 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. + + + + + + + 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. + + + + + + + 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. + + + + + + + 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'. + + + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/include/wayland-protocols/meson.build b/local/recipes/wayland/wayland-protocols/source/include/wayland-protocols/meson.build index 95af9dea0c..a4e872b58a 100644 --- a/local/recipes/wayland/wayland-protocols/source/include/wayland-protocols/meson.build +++ b/local/recipes/wayland/wayland-protocols/source/include/wayland-protocols/meson.build @@ -1,7 +1,7 @@ header_install_dir = get_option('includedir') / 'wayland-protocols' foreach protocol_file : protocol_files header_name = fs.name(protocol_file).replace('.xml', '-enum.h') - custom_target( + headers += custom_target( header_name, output: header_name, input: '../..' / protocol_file, diff --git a/local/recipes/wayland/wayland-protocols/source/meson.build b/local/recipes/wayland/wayland-protocols/source/meson.build index 4ac7926c25..25d42cead6 100644 --- a/local/recipes/wayland/wayland-protocols/source/meson.build +++ b/local/recipes/wayland/wayland-protocols/source/meson.build @@ -1,5 +1,5 @@ project('wayland-protocols', - version: '1.38', + version: '1.49', meson_version: '>= 0.58.0', license: 'MIT/Expat', ) @@ -8,90 +8,153 @@ wayland_protocols_version = meson.project_version() fs = import('fs') -prog_scanner = find_program('/usr/bin/wayland-scanner', native: true) +dep_scanner = dependency('wayland-scanner', + version: get_option('tests') ? '>=1.25.0' : '>=1.22.90', + required: get_option('tests'), + native: true, + fallback: 'wayland' +) +if dep_scanner.found() + prog_scanner = find_program(dep_scanner.get_variable(pkgconfig: 'wayland_scanner', internal: 'wayland_scanner')) +endif stable_protocols = { - 'presentation-time': [''], - 'viewporter': [''], - 'xdg-shell': [''], - 'linux-dmabuf': ['v1'], - 'tablet': ['v2'], + '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'], - 'xdg-foreign': ['v1', 'v2'], - 'xdg-output': ['v1'], - 'xdg-shell': ['v5', 'v6'], - 'xwayland-keyboard-grab': ['v1'], + '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 = { - 'commit-timing': ['v1'], - 'content-type': ['v1'], - 'cursor-shape': ['v1'], - 'drm-lease': ['v1'], - 'ext-foreign-toplevel-list': ['v1'], - 'ext-idle-notify': ['v1'], - 'ext-image-capture-source': ['v1'], - 'ext-image-copy-capture': ['v1'], - 'ext-session-lock': ['v1'], - 'ext-transient-seat': ['v1'], - 'fifo': ['v1'], - 'fractional-scale': ['v1'], - 'linux-drm-syncobj': ['v1'], - 'security-context': ['v1'], - 'single-pixel-buffer': ['v1'], - 'tearing-control': ['v1'], - 'xdg-activation': ['v1'], - 'xdg-dialog': ['v1'], - 'xdg-system-bell': ['v1'], - 'xdg-toplevel-drag': ['v1'], - 'xdg-toplevel-icon': ['v1'], - 'xwayland-shell': ['v1'], - 'alpha-modifier': ['v1'], + '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 : versions + foreach version, deps : versions if version == '' - protocol_files += ['stable/@0@/@0@.xml'.format(name)] + protocol_file = 'stable/@0@/@0@.xml'.format(name) else - protocol_files += ['stable/@0@/@0@-@1@.xml'.format(name, version)] + 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 : versions - protocol_files += [ - 'staging/@0@/@0@-@1@.xml'.format(name, version) - ] + 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 : versions - protocol_files += [ - 'unstable/@0@/@0@-unstable-@1@.xml'.format(name, version) - ] + 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 @@ -101,7 +164,7 @@ foreach protocol_file : protocol_files endif endforeach -foreach protocol_file : protocol_files +foreach protocol_file : installed_protocol_files protocol_install_dir = fs.parent(join_paths( get_option('datadir'), 'wayland-protocols', @@ -114,39 +177,37 @@ foreach protocol_file : protocol_files endforeach include_dirs = [] -if true +headers = [] +if dep_scanner.found() subdir('include/wayland-protocols') include_dirs = ['include'] endif -wayland_protocols_srcdir = meson.current_source_dir() +pkgconfig = import('pkgconfig') -pkgconfig_configuration = configuration_data() -pkgconfig_configuration.set('prefix', get_option('prefix')) -pkgconfig_configuration.set('datarootdir', '${prefix}/@0@'.format(get_option('datadir'))) -pkgconfig_configuration.set('abs_top_srcdir', wayland_protocols_srcdir) -pkgconfig_configuration.set('PACKAGE', 'wayland-protocols') -pkgconfig_configuration.set('WAYLAND_PROTOCOLS_VERSION', wayland_protocols_version) - -pkg_install_dir = join_paths(get_option('datadir'), 'pkgconfig') -configure_file( - input: 'wayland-protocols.pc.in', - output: 'wayland-protocols.pc', - configuration: pkgconfig_configuration, - install_dir: pkg_install_dir, -) - -configure_file( - input: 'wayland-protocols-uninstalled.pc.in', - output: 'wayland-protocols-uninstalled.pc', - configuration: pkgconfig_configuration, +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': wayland_protocols_srcdir, + 'pkgdatadir': meson.project_source_root(), }, + sources: headers, ) meson.override_dependency('wayland-protocols', wayland_protocols) diff --git a/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/feedback.rst b/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/feedback.rst index a3f94ed456..709424c436 100644 --- a/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/feedback.rst +++ b/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/feedback.rst @@ -31,10 +31,12 @@ linux-dmabuf feedback introduces the following concepts: 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 -========================================== +3. Starting with version 6, the assumption of a single main device is removed. + Clients should instead use the target device of any tranche marked with the + ``sampling`` flag instead. -This section contains recommendations for client and compositor implementations. +linux-dmabuf feedback implementation notes for version 4 and 5 +============================================================== For clients ----------- @@ -162,6 +164,29 @@ 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. +linux-dmabuf feedback implementation nodes for version 6 +========================================== + +With version 6 of the protocol, most of the logic described for version 4 still +stands, with a few exceptions: + +- the main device is no longer sent. If the client needs an equivalent to the + main device, the target device of the first tranche of the default feedback + with the ``sampling`` flag can be used. +- compositors should send tranches with the ``sampling`` flag for all devices + they can sample from without triggering buffer migrations. +- clients are strongly recommended to set the device they allocated buffers for + with ``wp_linux_buffer_params.set_sampling_device``. This avoids both implicit + buffer migrations and unnecessary copies by the compositor. +- compositors should avoid directly importing buffers into devices other than the + one set by the client with the ``sampling`` device whenever possible, to avoid + implicit buffer migrations by the graphics driver (which can reduce performance + significantly) +- if the compositor wishes a client to change which device it's rendering on, it + can change the order of tranches (and thus devices) in the per-surface feedback. + In response, clients that are capable of switching devices should re-allocate + on the first device they can use. + ``dev_t`` encoding ================== diff --git a/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/linux-dmabuf-v1.xml b/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/linux-dmabuf-v1.xml index 299923d2dd..7d727f75d2 100644 --- a/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/linux-dmabuf-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/linux-dmabuf-v1.xml @@ -24,15 +24,13 @@ DEALINGS IN THE SOFTWARE. - + - Following the interfaces from: - https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt - https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt - and the Linux DRM sub-system's AddFb2 ioctl. - 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. @@ -63,7 +61,7 @@ import later fails. To create a wl_buffer from one or more dmabufs, a client creates a - zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params + 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. @@ -107,7 +105,7 @@ received. + summary="id for the newly created zwp_linux_buffer_params_v1"/> @@ -164,7 +162,7 @@ - This request creates a new wp_linux_dmabuf_feedback object not bound + 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). @@ -174,11 +172,11 @@ - This request creates a new wp_linux_dmabuf_feedback object for the + 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 wp_linux_dmabuf_feedback object, + If the surface is destroyed before the zwp_linux_dmabuf_feedback_v1 object, the feedback object becomes inert. @@ -186,7 +184,7 @@ - + This temporary object is a collection of dmabufs and other parameters that together form a single logical buffer. The temporary @@ -201,12 +199,14 @@ 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 be set only once. + 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. + summary="the zwp_linux_buffer_params_v1 object has already been used to create a wl_buffer"/> + @@ -282,7 +284,7 @@ authoritative source on how the format codes should work. The 'flags' is a bitfield of the flags defined in enum "flags". - 'y_invert' means the that the image needs to be y-flipped. + '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 @@ -326,7 +328,7 @@ 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 ALREADY_USED protocol error. + 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. @@ -346,7 +348,7 @@ zwp_linux_buffer_params_v1 object. + summary="id for the the newly created wl_buffer"/> @@ -394,9 +396,28 @@ + + + + Set the device the compositor should import the dmabufs to for sampling + in the next create or create_immed request. + + To avoid race conditions when the compositor removes a device from the + tranches, it is not a protocol error if the device hasn't been advertised + by the compositor in a tranche with the sampling flag, but the import is + likely to fail in that case. + + If the client doesn't know a suitable target device, it shouldn't set one, + and the compositor should attempt import on all devices it supports. + + If the array is too small to contain a dev_t or larger than required, the + invalid_dev_t_size error will be emitted. + + + - + This object advertises dmabuf parameters feedback. This includes the preferred devices and the supported formats/modifiers. @@ -419,25 +440,28 @@ 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. + To send parameters, the compositor sends one main_device event (unless + the client bound version 6 or above), 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. + + With version 6 and above, the compositor must always advertise at least + one tranche with the sampling flag set. Using this request a client can tell the server that it is not going to - use the wp_linux_dmabuf_feedback object anymore. + use the zwp_linux_dmabuf_feedback_v1 object anymore. - This event is sent after all parameters of a wp_linux_dmabuf_feedback + This event is sent after all parameters of a zwp_linux_dmabuf_feedback_v1 object have been sent. - This allows changes to the wp_linux_dmabuf_feedback parameters to be + This allows changes to the zwp_linux_dmabuf_feedback_v1 parameters to be seen as atomic, even if they happen via multiple events. @@ -463,19 +487,19 @@ - + 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 - wp_linux_dmabuf_feedback object, and may change over time. + 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 - wp_linux_buffer_params.create and create_immed requests for details). + 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. @@ -488,13 +512,16 @@ 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. + + With version 6 and above, this event is no longer sent. Clients should + use a device with the sampling flag in the tranches instead. - This event splits tranche_target_device and tranche_formats events in + 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. @@ -516,11 +543,11 @@ 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 + still be accessible from a device with the sampling flag, either through + direct import or a potentially more expensive fallback path. If the + buffer can't be directly imported for sampling, then clients must be prepared for the compositor changing the tranche priority or making - wl_buffer creation fail (see the wp_linux_buffer_params.create and + 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 @@ -534,7 +561,7 @@ - + This event advertises the format + modifier combinations that the compositor supports. @@ -558,25 +585,36 @@ This event is tied to a preference tranche, see the tranche_done event. For the definition of the format and modifier codes, see the - wp_linux_buffer_params.create request. + zwp_linux_buffer_params_v1.create request. - + + + 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. + + + + + The sampling flag describes that the compositor is able to efficiently + sample from buffers imported to the target device if the client + appropriately allocates a buffer. How to allocate a buffer that can be + efficiently sampled on the target device is implementation defined. + + - 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. + This event sets tranche-specific flags. This event is tied to a + preference tranche, see the tranche_done event. + With version 6 and above, the compositor must set at least one flag + in each tranche. diff --git a/local/recipes/wayland/wayland-protocols/source/stable/tablet/tablet-v2.xml b/local/recipes/wayland/wayland-protocols/source/stable/tablet/tablet-v2.xml index 58329f72da..85529bdfa3 100644 --- a/local/recipes/wayland/wayland-protocols/source/stable/tablet/tablet-v2.xml +++ b/local/recipes/wayland/wayland-protocols/source/stable/tablet/tablet-v2.xml @@ -3,7 +3,7 @@ Copyright 2014 © Stephen "Lyude" Chandler Paul - Copyright 2015-2016 © Red Hat, Inc. + Copyright 2015-2024 © Red Hat, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files @@ -35,19 +35,19 @@ More than one tablet may exist, and device-specifics matter. Tablets are not represented by a single virtual device like wl_pointer. A client binds to the tablet manager object which is just a proxy object. From - that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat) + that, the client requests zwp_tablet_manager_v2.get_tablet_seat(wl_seat) and that returns the actual interface that has all the tablets. With - this indirection, we can avoid merging wp_tablet into the actual Wayland + this indirection, we can avoid merging zwp_tablet_v2 into the actual Wayland protocol, a long-term benefit. - The wp_tablet_seat sends a "tablet added" event for each tablet + The zwp_tablet_seat_v2 sends a "tablet added" event for each tablet connected. That event is followed by descriptive events about the hardware; currently that includes events for name, vid/pid and - a wp_tablet.path event that describes a local path. This path can be + a zwp_tablet_v2.path event that describes a local path. This path can be used to uniquely identify a tablet or get more information through libwacom. Emulated or nested tablets can skip any of those, e.g. a virtual tablet may not have a vid/pid. The sequence of descriptive - events is terminated by a wp_tablet.done event to signal that a client + events is terminated by a zwp_tablet_v2.done event to signal that a client may now finalize any initialization for that tablet. Events from tablets require a tool in proximity. Tools are also managed @@ -55,15 +55,15 @@ to the compositor. That event is followed by a number of descriptive events about the hardware; currently that includes capabilities, hardware id and serial number, and tool type. Similar to the tablet - interface, a wp_tablet_tool.done event is sent to terminate that initial + interface, a zwp_tablet_tool_v2.done event is sent to terminate that initial sequence. - Any event from a tool happens on the wp_tablet_tool interface. When the + Any event from a tool happens on the zwp_tablet_tool_v2 interface. When the tool gets into proximity of the tablet, a proximity_in event is sent on - the wp_tablet_tool interface, listing the tablet and the surface. That + the zwp_tablet_tool_v2 interface, listing the tablet and the surface. That event is followed by a motion event with the coordinates. After that, it's the usual motion, axis, button, etc. events. The protocol's - serialisation means events are grouped by wp_tablet_tool.frame events. + serialisation means events are grouped by zwp_tablet_tool_v2.frame events. Two special events (that don't exist in X) are down and up. They signal "tip touching the surface". For tablets without real proximity @@ -95,7 +95,7 @@ Since tablets work independently of the pointer controlled by the mouse, the focus handling is independent too and controlled by proximity. - The wp_tablet_tool.set_cursor request sets a tool-specific cursor. + The zwp_tablet_tool_v2.set_cursor request sets a tool-specific cursor. This cursor surface may be the same as the mouse cursor, and it may be the same across tools but it is possible to be more fine-grained. For example, a client may set different cursors for the pen and eraser. @@ -106,16 +106,16 @@ tool was used on are removed. - + An object that provides access to the graphics tablets available on this system. All tablets are associated with a seat, to get access to the - actual tablets, use wp_tablet_manager.get_tablet_seat. + actual tablets, use zwp_tablet_manager_v2.get_tablet_seat. - Get the wp_tablet_seat object for the given seat. This object + Get the zwp_tablet_seat_v2 object for the given seat. This object provides access to all graphics tablets in this seat. @@ -124,22 +124,22 @@ - Destroy the wp_tablet_manager object. Objects created from this + Destroy the zwp_tablet_manager_v2 object. Objects created from this object are unaffected and should be destroyed separately. - + An object that provides access to the graphics tablets available on this seat. After binding to this interface, the compositor sends a set of - wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events. + zwp_tablet_seat_v2.tablet_added and zwp_tablet_seat_v2.tool_added events. - Destroy the wp_tablet_seat object. Objects created from this + Destroy the zwp_tablet_seat_v2 object. Objects created from this object are unaffected and should be destroyed separately. @@ -149,7 +149,7 @@ This event is sent whenever a new tablet becomes available on this seat. This event only provides the object id of the tablet, any static information about the tablet (device name, vid/pid, etc.) is - sent through the wp_tablet interface. + sent through the zwp_tablet_v2 interface. @@ -159,7 +159,7 @@ This event is sent whenever a tool that has not previously been used with a tablet comes into use. This event only provides the object id of the tool; any static information about the tool (capabilities, - type, etc.) is sent through the wp_tablet_tool interface. + type, etc.) is sent through the zwp_tablet_tool_v2 interface. @@ -168,40 +168,40 @@ This event is sent whenever a new pad is known to the system. Typically, pads are physically attached to tablets and a pad_added event is - sent immediately after the wp_tablet_seat.tablet_added. + sent immediately after the zwp_tablet_seat_v2.tablet_added. However, some standalone pad devices logically attach to tablets at - runtime, and the client must wait for wp_tablet_pad.enter to know + runtime, and the client must wait for zwp_tablet_pad_v2.enter to know the tablet a pad is attached to. This event only provides the object id of the pad. All further - features (buttons, strips, rings) are sent through the wp_tablet_pad + features (buttons, strips, rings) are sent through the zwp_tablet_pad_v2 interface. - + An object that represents a physical tool that has been, or is - currently in use with a tablet in this seat. Each wp_tablet_tool + currently in use with a tablet in this seat. Each zwp_tablet_tool_v2 object stays valid until the client destroys it; the compositor - reuses the wp_tablet_tool object to indicate that the object's + reuses the zwp_tablet_tool_v2 object to indicate that the object's respective physical tool has come into proximity of a tablet again. - A wp_tablet_tool object's relation to a physical tool depends on the + A zwp_tablet_tool_v2 object's relation to a physical tool depends on the tablet's ability to report serial numbers. If the tablet supports this capability, then the object represents a specific physical tool and can be identified even when used on multiple tablets. A tablet tool has a number of static characteristics, e.g. tool type, hardware_serial and capabilities. These capabilities are sent in an - event sequence after the wp_tablet_seat.tool_added event before any + event sequence after the zwp_tablet_seat_v2.tool_added event before any actual events from this tool. This initial event sequence is - terminated by a wp_tablet_tool.done event. + terminated by a zwp_tablet_tool_v2.done event. - Tablet tool events are grouped by wp_tablet_tool.frame events. - Any events received before a wp_tablet_tool.frame event should be + Tablet tool events are grouped by zwp_tablet_tool_v2.frame events. + Any events received before a zwp_tablet_tool_v2.frame event should be considered part of the same hardware state change. @@ -232,9 +232,9 @@ and pending input regions become undefined, and the wl_surface is unmapped. - This request gives the surface the role of a wp_tablet_tool cursor. A + This request gives the surface the role of a zwp_tablet_tool_v2 cursor. A surface may only ever be used as the cursor surface for one - wp_tablet_tool. If the surface already has another role or has + zwp_tablet_tool_v2. If the surface already has another role or has previously been used as cursor surface for a different tool, a protocol error is raised. @@ -278,7 +278,7 @@ the interaction expected from this tool. This event is sent in the initial burst of events before the - wp_tablet_tool.done event. + zwp_tablet_tool_v2.done event. @@ -295,11 +295,11 @@ Otherwise, if the tool has no serial number and this event is missing, the tool is tied to the tablet it first comes into proximity with. Even if the physical tool is used on multiple - tablets, separate wp_tablet_tool objects will be created, one per + tablets, separate zwp_tablet_tool_v2 objects will be created, one per tablet. This event is sent in the initial burst of events before the - wp_tablet_tool.done event. + zwp_tablet_tool_v2.done event. @@ -316,7 +316,7 @@ Pen (a stylus) is 0x802. This event is sent in the initial burst of events before the - wp_tablet_tool.done event. + zwp_tablet_tool_v2.done event. @@ -345,7 +345,7 @@ One event is sent for each extra capability available on this tool. This event is sent in the initial burst of events before the - wp_tablet_tool.done event. + zwp_tablet_tool_v2.done event. @@ -362,17 +362,17 @@ This event is sent when the tool is removed from the system and will send no further events. Should the physical tool come back into - proximity later, a new wp_tablet_tool object will be created. + proximity later, a new zwp_tablet_tool_v2 object will be created. It is compositor-dependent when a tool is removed. A compositor may remove a tool on proximity out, tablet removal or any other reason. A compositor may also keep a tool alive until shutdown. If the tool is currently in proximity, a proximity_out event will be - sent before the removed event. See wp_tablet_tool.proximity_out for + sent before the removed event. See zwp_tablet_tool_v2.proximity_out for the handling of any buttons logically down. - When this event is received, the client must wp_tablet_tool.destroy + When this event is received, the client must zwp_tablet_tool_v2.destroy the object. @@ -402,7 +402,7 @@ When the tablet tool leaves proximity of the tablet, button release events are sent for each button that was held down at the time of leaving proximity. These events are sent before the proximity_out - event but within the same wp_tablet.frame. + event but within the same zwp_tablet_v2.frame. If the tool stays within proximity of the tablet, but the focus changes from one surface to another, a button release event may not @@ -418,8 +418,8 @@ If the tool is already in contact with the tablet when entering the input region, the client owning said region will receive a - wp_tablet.proximity_in event, followed by a wp_tablet.down - event and a wp_tablet.frame event. + zwp_tablet_v2.proximity_in event, followed by a zwp_tablet_v2.down + event and a zwp_tablet_v2.frame event. Note that this event describes logical contact, not physical contact. On some devices, a compositor may not consider a tool in @@ -438,8 +438,8 @@ If the tablet tool moves out of the input region while in contact with the surface of the tablet and the compositor does not have an ongoing grab on the surface, the client owning said region will - receive a wp_tablet.up event, followed by a wp_tablet.proximity_out - event and a wp_tablet.frame event. If the compositor has an ongoing + receive a zwp_tablet_v2.up event, followed by a zwp_tablet_v2.proximity_out + event and a zwp_tablet_v2.frame event. If the compositor has an ongoing grab on this device, this event sequence is sent whenever the grab is dismissed in the future. @@ -523,7 +523,7 @@ Clients should choose either value and avoid mixing degrees and clicks. The compositor may accumulate values smaller than a logical click and emulate click events when a certain threshold is met. - Thus, wl_tablet_tool.wheel events with non-zero clicks values may + Thus, zwp_tablet_tool_v2.wheel events with non-zero clicks values may have different degrees values. @@ -544,7 +544,7 @@ If a button is held down when the tool moves in or out of proximity, button events are generated by the compositor. See - wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for + zwp_tablet_tool_v2.proximity_in and zwp_tablet_tool_v2.proximity_out for details. @@ -567,16 +567,16 @@ - + - The wp_tablet interface represents one graphics tablet device. The + The zwp_tablet_v2 interface represents one graphics tablet device. The tablet interface itself does not generate events; all events are - generated by wp_tablet_tool objects when in proximity above a tablet. + generated by zwp_tablet_tool_v2 objects when in proximity above a tablet. A tablet has a number of static characteristics, e.g. device name and pid/vid. These capabilities are sent in an event sequence after the - wp_tablet_seat.tablet_added event. This initial event sequence is - terminated by a wp_tablet.done event. + zwp_tablet_seat_v2.tablet_added event. This initial event sequence is + terminated by a zwp_tablet_v2.done event. @@ -592,33 +592,38 @@ If the device has no descriptive name, this event is not sent. This event is sent in the initial burst of events before the - wp_tablet.done event. + zwp_tablet_v2.done event. - - The USB vendor and product IDs for the tablet device. + + The vendor and product IDs for the tablet device. - If the device has no USB vendor/product ID, this event is not sent. + The interpretation of the id depends on the zwp_tablet_v2.bustype. + Prior to version v2 of this protocol, the id was implied to be a USB + vendor and product ID. If no zwp_tablet_v2.bustype is sent, the ID + is to be interpreted as USB vendor and product ID. + + If the device has no vendor/product ID, this event is not sent. This can happen for virtual devices or non-USB devices, for instance. This event is sent in the initial burst of events before the - wp_tablet.done event. + zwp_tablet_v2.done event. - - + + A system-specific device path that indicates which device is behind - this wp_tablet. This information may be used to gather additional + this zwp_tablet_v2. This information may be used to gather additional information about the device, e.g. through libwacom. A device may have more than one device path. If so, multiple - wp_tablet.path events are sent. A device may be emulated and not + zwp_tablet_v2.path events are sent. A device may be emulated and not have a device path, and in that case this event will not be sent. The format of the path is unspecified, it may be a device node, a @@ -626,7 +631,7 @@ identify the string provided. This event is sent in the initial burst of events before the - wp_tablet.done event. + zwp_tablet_v2.done event. @@ -645,18 +650,45 @@ Sent when the tablet has been removed from the system. When a tablet is removed, some tools may be removed. - When this event is received, the client must wp_tablet.destroy + When this event is received, the client must zwp_tablet_v2.destroy the object. + + + + + + Describes the bus types this tablet is connected to. + + + + + + + + + + + The bustype argument is one of the BUS_ defines in the Linux kernel's + linux/input.h + + If the device has no known bustype or the bustype cannot be + queried, this event is not sent. + + This event is sent in the initial burst of events before the + zwp_tablet_v2.done event. + + + - + A circular interaction area, such as the touch ring on the Wacom Intuos Pro series tablets. - Events on a ring are logically grouped by the wl_tablet_pad_ring.frame + Events on a ring are logically grouped by the zwp_tablet_pad_ring_v2.frame event. @@ -664,9 +696,9 @@ Request that the compositor use the provided feedback string associated with this ring. This request should be issued immediately - after a wp_tablet_pad_group.mode_switch event from the corresponding + after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding group is received, or whenever the ring is mapped to a different - action. See wp_tablet_pad_group.mode_switch for more details. + action. See zwp_tablet_pad_group_v2.mode_switch for more details. Clients are encouraged to provide context-aware descriptions for the actions associated with the ring; compositors may use this @@ -678,7 +710,7 @@ internationalization rules apply. The serial argument will be that of the last - wp_tablet_pad_group.mode_switch event received for the group of this + zwp_tablet_pad_group_v2.mode_switch event received for the group of this ring. Requests providing other serials than the most recent one will be ignored. @@ -707,11 +739,11 @@ Source information for ring events. This event does not occur on its own. It is sent before a - wp_tablet_pad_ring.frame event and carries the source information + zwp_tablet_pad_ring_v2.frame event and carries the source information for all events within that frame. The source specifies how this event was generated. If the source is - wp_tablet_pad_ring.source.finger, a wp_tablet_pad_ring.stop event + zwp_tablet_pad_ring_v2.source.finger, a zwp_tablet_pad_ring_v2.stop event will be sent when the user lifts the finger off the device. This event is optional. If the source is unknown for an interaction, @@ -734,13 +766,13 @@ Stop notification for ring events. - For some wp_tablet_pad_ring.source types, a wp_tablet_pad_ring.stop + For some zwp_tablet_pad_ring_v2.source types, a zwp_tablet_pad_ring_v2.stop event is sent to notify a client that the interaction with the ring has terminated. This enables the client to implement kinetic scrolling. - See the wp_tablet_pad_ring.source documentation for information on + See the zwp_tablet_pad_ring_v2.source documentation for information on when this event may be generated. - Any wp_tablet_pad_ring.angle events with the same source after this + Any zwp_tablet_pad_ring_v2.angle events with the same source after this event should be considered as the start of a new interaction. @@ -751,13 +783,13 @@ together. A client is expected to accumulate the data in all events within the frame before proceeding. - All wp_tablet_pad_ring events before a wp_tablet_pad_ring.frame event belong + All zwp_tablet_pad_ring_v2 events before a zwp_tablet_pad_ring_v2.frame event belong logically together. For example, on termination of a finger interaction - on a ring the compositor will send a wp_tablet_pad_ring.source event, - a wp_tablet_pad_ring.stop event and a wp_tablet_pad_ring.frame event. + on a ring the compositor will send a zwp_tablet_pad_ring_v2.source event, + a zwp_tablet_pad_ring_v2.stop event and a zwp_tablet_pad_ring_v2.frame event. - A wp_tablet_pad_ring.frame event is sent for every logical event - group, even if the group only contains a single wp_tablet_pad_ring + A zwp_tablet_pad_ring_v2.frame event is sent for every logical event + group, even if the group only contains a single zwp_tablet_pad_ring_v2 event. Specifically, a client may get a sequence: angle, frame, angle, frame, etc. @@ -765,12 +797,12 @@ - + A linear interaction area, such as the strips found in Wacom Cintiq models. - Events on a strip are logically grouped by the wl_tablet_pad_strip.frame + Events on a strip are logically grouped by the zwp_tablet_pad_strip_v2.frame event. @@ -778,9 +810,9 @@ Requests the compositor to use the provided feedback string associated with this strip. This request should be issued immediately - after a wp_tablet_pad_group.mode_switch event from the corresponding + after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding group is received, or whenever the strip is mapped to a different - action. See wp_tablet_pad_group.mode_switch for more details. + action. See zwp_tablet_pad_group_v2.mode_switch for more details. Clients are encouraged to provide context-aware descriptions for the actions associated with the strip, and compositors may use this @@ -792,7 +824,7 @@ internationalization rules apply. The serial argument will be that of the last - wp_tablet_pad_group.mode_switch event received for the group of this + zwp_tablet_pad_group_v2.mode_switch event received for the group of this strip. Requests providing other serials than the most recent one will be ignored. @@ -821,11 +853,11 @@ Source information for strip events. This event does not occur on its own. It is sent before a - wp_tablet_pad_strip.frame event and carries the source information + zwp_tablet_pad_strip_v2.frame event and carries the source information for all events within that frame. The source specifies how this event was generated. If the source is - wp_tablet_pad_strip.source.finger, a wp_tablet_pad_strip.stop event + zwp_tablet_pad_strip_v2.source.finger, a zwp_tablet_pad_strip_v2.stop event will be sent when the user lifts their finger off the device. This event is optional. If the source is unknown for an interaction, @@ -849,13 +881,13 @@ Stop notification for strip events. - For some wp_tablet_pad_strip.source types, a wp_tablet_pad_strip.stop + For some zwp_tablet_pad_strip_v2.source types, a zwp_tablet_pad_strip_v2.stop event is sent to notify a client that the interaction with the strip has terminated. This enables the client to implement kinetic - scrolling. See the wp_tablet_pad_strip.source documentation for + scrolling. See the zwp_tablet_pad_strip_v2.source documentation for information on when this event may be generated. - Any wp_tablet_pad_strip.position events with the same source after this + Any zwp_tablet_pad_strip_v2.position events with the same source after this event should be considered as the start of a new interaction. @@ -866,14 +898,14 @@ hardware strip event. A client is expected to accumulate the data in all events within the frame before proceeding. - All wp_tablet_pad_strip events before a wp_tablet_pad_strip.frame event belong + All zwp_tablet_pad_strip_v2 events before a zwp_tablet_pad_strip_v2.frame event belong logically together. For example, on termination of a finger interaction - on a strip the compositor will send a wp_tablet_pad_strip.source event, - a wp_tablet_pad_strip.stop event and a wp_tablet_pad_strip.frame + on a strip the compositor will send a zwp_tablet_pad_strip_v2.source event, + a zwp_tablet_pad_strip_v2.stop event and a zwp_tablet_pad_strip_v2.frame event. - A wp_tablet_pad_strip.frame event is sent for every logical event - group, even if the group only contains a single wp_tablet_pad_strip + A zwp_tablet_pad_strip_v2.frame event is sent for every logical event + group, even if the group only contains a single zwp_tablet_pad_strip_v2 event. Specifically, a client may get a sequence: position, frame, position, frame, etc. @@ -881,7 +913,7 @@ - + A pad group describes a distinct (sub)set of buttons, rings and strips present in the tablet. The criteria of this grouping is usually positional, @@ -890,40 +922,40 @@ change on the fly. Pad groups will announce their features during pad initialization. Between - the corresponding wp_tablet_pad.group event and wp_tablet_pad_group.done, the + the corresponding zwp_tablet_pad_v2.group event and zwp_tablet_pad_group_v2.done, the pad group will announce the buttons, rings and strips contained in it, plus the number of supported modes. Modes are a mechanism to allow multiple groups of actions for every element in the pad group. The number of groups and available modes in each is persistent across device plugs. The current mode is user-switchable, it - will be announced through the wp_tablet_pad_group.mode_switch event both - whenever it is switched, and after wp_tablet_pad.enter. + will be announced through the zwp_tablet_pad_group_v2.mode_switch event both + whenever it is switched, and after zwp_tablet_pad_v2.enter. The current mode logically applies to all elements in the pad group, although it is at clients' discretion whether to actually perform different actions, and/or issue the respective .set_feedback requests to notify the - compositor. See the wp_tablet_pad_group.mode_switch event for more details. + compositor. See the zwp_tablet_pad_group_v2.mode_switch event for more details. - Destroy the wp_tablet_pad_group object. Objects created from this object + Destroy the zwp_tablet_pad_group_v2 object. Objects created from this object are unaffected and should be destroyed separately. - Sent on wp_tablet_pad_group initialization to announce the available + Sent on zwp_tablet_pad_group_v2 initialization to announce the available buttons in the group. Button indices start at 0, a button may only be in one group at a time. This event is first sent in the initial burst of events before the - wp_tablet_pad_group.done event. + zwp_tablet_pad_group_v2.done event. Some buttons are reserved by the compositor. These buttons may not be - assigned to any wp_tablet_pad_group. Compositors may broadcast this + assigned to any zwp_tablet_pad_group_v2. Compositors may broadcast this event in the case of changes to the mapping of these reserved buttons. If the compositor happens to reserve all buttons in a group, this event will be sent with an empty array. @@ -933,39 +965,39 @@ - Sent on wp_tablet_pad_group initialization to announce available rings. + Sent on zwp_tablet_pad_group_v2 initialization to announce available rings. One event is sent for each ring available on this pad group. This event is sent in the initial burst of events before the - wp_tablet_pad_group.done event. + zwp_tablet_pad_group_v2.done event. - Sent on wp_tablet_pad initialization to announce available strips. + Sent on zwp_tablet_pad_v2 initialization to announce available strips. One event is sent for each strip available on this pad group. This event is sent in the initial burst of events before the - wp_tablet_pad_group.done event. + zwp_tablet_pad_group_v2.done event. - Sent on wp_tablet_pad_group initialization to announce that the pad + Sent on zwp_tablet_pad_group_v2 initialization to announce that the pad group may switch between modes. A client may use a mode to store a specific configuration for buttons, rings and strips and use the - wl_tablet_pad_group.mode_switch event to toggle between these + zwp_tablet_pad_group_v2.mode_switch event to toggle between these configurations. Mode indices start at 0. Switching modes is compositor-dependent. See the - wp_tablet_pad_group.mode_switch event for more details. + zwp_tablet_pad_group_v2.mode_switch event for more details. This event is sent in the initial burst of events before the - wp_tablet_pad_group.done event. This event is only sent when more than + zwp_tablet_pad_group_v2.done event. This event is only sent when more than one mode is available. @@ -984,7 +1016,7 @@ Notification that the mode was switched. - A mode applies to all buttons, rings and strips in a group + A mode applies to all buttons, rings, strips and dials in a group simultaneously, but a client is not required to assign different actions for each mode. For example, a client may have mode-specific button mappings but map the ring to vertical scrolling in all modes. Mode @@ -997,28 +1029,41 @@ Intuos Pro, the button inside the ring may be assigned to switch between modes. - The compositor will also send this event after wp_tablet_pad.enter on + The compositor will also send this event after zwp_tablet_pad_v2.enter on each group in order to notify of the current mode. Groups that only feature one mode will use mode=0 when emitting this event. If a button action in the new mode differs from the action in the previous mode, the client should immediately issue a - wp_tablet_pad.set_feedback request for each changed button. + zwp_tablet_pad_v2.set_feedback request for each changed button. - If a ring or strip action in the new mode differs from the action + If a ring, strip or dial action in the new mode differs from the action in the previous mode, the client should immediately issue a - wp_tablet_ring.set_feedback or wp_tablet_strip.set_feedback request - for each changed ring or strip. + zwp_tablet_ring_v2.set_feedback, zwp_tablet_strip_v2.set_feedback or + zwp_tablet_dial_v2.set_feedback request for each changed ring, strip or dial. + + + + + + Sent on zwp_tablet_pad_v2 initialization to announce available dials. + One event is sent for each dial available on this pad group. + + This event is sent in the initial burst of events before the + zwp_tablet_pad_group_v2.done event. + + + - - - A pad device is a set of buttons, rings and strips + + + A pad device is a set of buttons, rings, strips and dials usually physically present on the tablet device itself. Some exceptions exist where the pad device is physically detached, e.g. the Wacom ExpressKey Remote. @@ -1028,14 +1073,14 @@ A pad device has a number of static characteristics, e.g. the number of rings. These capabilities are sent in an event sequence after the - wp_tablet_seat.pad_added event before any actual events from this pad. - This initial event sequence is terminated by a wp_tablet_pad.done + zwp_tablet_seat_v2.pad_added event before any actual events from this pad. + This initial event sequence is terminated by a zwp_tablet_pad_v2.done event. - All pad features (buttons, rings and strips) are logically divided into + All pad features (buttons, rings, strips and dials) are logically divided into groups and all pads have at least one group. The available groups are - notified through the wp_tablet_pad.group event; the compositor will - emit one event per group before emitting wp_tablet_pad.done. + notified through the zwp_tablet_pad_v2.group event; the compositor will + emit one event per group before emitting zwp_tablet_pad_v2.done. Groups may have multiple modes. Modes allow clients to map multiple actions to a single pad feature. Only one mode can be active per group, @@ -1046,9 +1091,9 @@ Requests the compositor to use the provided feedback string associated with this button. This request should be issued immediately - after a wp_tablet_pad_group.mode_switch event from the corresponding + after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding group is received, or whenever a button is mapped to a different - action. See wp_tablet_pad_group.mode_switch for more details. + action. See zwp_tablet_pad_group_v2.mode_switch for more details. Clients are encouraged to provide context-aware descriptions for the actions associated with each button, and compositors may use @@ -1057,7 +1102,7 @@ Button indices start at 0. Setting the feedback string on a button that is reserved by the compositor (i.e. not belonging to any - wp_tablet_pad_group) does not generate an error but the compositor + zwp_tablet_pad_group_v2) does not generate an error but the compositor is free to ignore the request. The provided string 'description' is a UTF-8 encoded string to be @@ -1065,7 +1110,7 @@ internationalization rules apply. The serial argument will be that of the last - wp_tablet_pad_group.mode_switch event received for the group of this + zwp_tablet_pad_group_v2.mode_switch event received for the group of this button. Requests providing other serials than the most recent one will be ignored. @@ -1076,18 +1121,18 @@ - Destroy the wp_tablet_pad object. Objects created from this object + Destroy the zwp_tablet_pad_v2 object. Objects created from this object are unaffected and should be destroyed separately. - Sent on wp_tablet_pad initialization to announce available groups. + Sent on zwp_tablet_pad_v2 initialization to announce available groups. One event is sent for each pad group available. This event is sent in the initial burst of events before the - wp_tablet_pad.done event. At least one group will be announced. + zwp_tablet_pad_v2.done event. At least one group will be announced. @@ -1095,7 +1140,7 @@ A system-specific device path that indicates which device is behind - this wp_tablet_pad. This information may be used to gather additional + this zwp_tablet_pad_v2. This information may be used to gather additional information about the device, e.g. through libwacom. The format of the path is unspecified, it may be a device node, a @@ -1103,18 +1148,18 @@ identify the string provided. This event is sent in the initial burst of events before the - wp_tablet_pad.done event. + zwp_tablet_pad_v2.done event. - Sent on wp_tablet_pad initialization to announce the available + Sent on zwp_tablet_pad_v2 initialization to announce the available buttons. This event is sent in the initial burst of events before the - wp_tablet_pad.done event. This event is only sent when at least one + zwp_tablet_pad_v2.done event. This event is only sent when at least one button is available. @@ -1170,9 +1215,83 @@ is removed its pad(s) will be removed too. When this event is received, the client must destroy all rings, strips - and groups that were offered by this pad, and issue wp_tablet_pad.destroy + and groups that were offered by this pad, and issue zwp_tablet_pad_v2.destroy the pad itself. + + + + A rotary control, e.g. a dial or a wheel. + + Events on a dial are logically grouped by the zwp_tablet_pad_dial_v2.frame + event. + + + + + Requests the compositor to use the provided feedback string + associated with this dial. This request should be issued immediately + after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding + group is received, or whenever the dial is mapped to a different + action. See zwp_tablet_pad_group_v2.mode_switch for more details. + + Clients are encouraged to provide context-aware descriptions for + the actions associated with the dial, and compositors may use this + information to offer visual feedback about the button layout + (eg. on-screen displays). + + The provided string 'description' is a UTF-8 encoded string to be + associated with this ring, and is considered user-visible; general + internationalization rules apply. + + The serial argument will be that of the last + zwp_tablet_pad_group_v2.mode_switch event received for the group of this + dial. Requests providing other serials than the most recent one will be + ignored. + + + + + + + + This destroys the client's resource for this dial object. + + + + + + Sent whenever the position on a dial changes. + + This event carries the wheel delta as multiples or fractions + of 120 with each multiple of 120 representing one logical wheel detent. + For example, an axis_value120 of 30 is one quarter of + a logical wheel step in the positive direction, a value120 of + -240 are two logical wheel steps in the negative direction within the + same hardware event. See the wl_pointer.axis_value120 for more details. + + The value120 must not be zero. + + + + + + + Indicates the end of a set of events that represent one logical + hardware dial event. A client is expected to accumulate the data + in all events within the frame before proceeding. + + All zwp_tablet_pad_dial_v2 events before a zwp_tablet_pad_dial_v2.frame event belong + logically together. + + A zwp_tablet_pad_dial_v2.frame event is sent for every logical event + group, even if the group only contains a single zwp_tablet_pad_dial_v2 + event. Specifically, a client may get a sequence: delta, frame, + delta, frame, etc. + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/stable/xdg-shell/xdg-shell.xml b/local/recipes/wayland/wayland-protocols/source/stable/xdg-shell/xdg-shell.xml index 1caf6f1001..f8b78eea7b 100644 --- a/local/recipes/wayland/wayland-protocols/source/stable/xdg-shell/xdg-shell.xml +++ b/local/recipes/wayland/wayland-protocols/source/stable/xdg-shell/xdg-shell.xml @@ -29,7 +29,7 @@ DEALINGS IN THE SOFTWARE. - + The xdg_wm_base interface is exposed as a global object enabling clients to turn their wl_surfaces into windows in a desktop environment. It @@ -75,17 +75,16 @@ - This creates an xdg_surface for the given surface. While xdg_surface - itself is not a role, the corresponding surface may only be assigned - a role extending xdg_surface, such as xdg_toplevel or xdg_popup. It is - illegal to create an xdg_surface for a wl_surface which already has an - assigned role and this will result in a role error. - This creates an xdg_surface for the given surface. An xdg_surface is used as basis to define a role to a given surface, such as xdg_toplevel or xdg_popup. It also manages functionality shared between xdg_surface based surface roles. + While xdg_surface itself is not a role, the corresponding surface may + only be assigned a role extending xdg_surface, such as xdg_toplevel or + xdg_popup. It is illegal to create an xdg_surface for a wl_surface which + already has anassigned role and this will result in a role error. + See the documentation of xdg_surface for more details about what an xdg_surface is and how it is used. @@ -122,7 +121,7 @@ - + The xdg_positioner provides a collection of rules for the placement of a child surface relative to a parent surface. Rules can be defined to ensure @@ -201,14 +200,14 @@ Defines the anchor point for the anchor rectangle. The specified anchor - is used derive an anchor point that the child surface will be + is used to derive an anchor point that the child 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. + summary="anchor point"/> @@ -380,7 +379,7 @@ - + Set the parent window geometry the compositor should use when positioning the popup. The compositor may use this information to determine the future state the popup should be constrained using. If @@ -407,7 +406,7 @@ - + An interface that may be implemented by a wl_surface, for implementations that provide a desktop-style user interface. @@ -505,8 +504,8 @@ xdg_popup is and how it is used. - - + + @@ -514,7 +513,10 @@ The window geometry of a surface is its "visible bounds" from the user's perspective. Client-side decorations often have invisible portions like drop-shadows which should be ignored for the - purposes of aligning, placing and constraining windows. + purposes of aligning, placing and constraining windows. Note that + in some situations, compositors may clip rendering to the window + geometry, so the client should avoid putting functional elements + outside of it. The window geometry is double-buffered state, see wl_surface.commit. @@ -549,10 +551,10 @@ greater than zero. Setting an invalid size will raise an invalid_size error. - - - - + + + + @@ -617,7 +619,7 @@ - + This interface defines an xdg_surface role which allows a surface to, among other things, set window-like properties such as maximize, @@ -625,7 +627,7 @@ id, and well as trigger user interactive operations such as interactive resize and move. - A xdg_toplevel by default is responsible for providing the full intended + An xdg_toplevel by default is responsible for providing the full intended visual representation of the toplevel, which depending on the window state, may mean things like a title bar, window controls and drop shadow. @@ -681,7 +683,7 @@ descendants, and the parent must be different from the child toplevel, otherwise the invalid_parent protocol error is raised. - + @@ -694,7 +696,7 @@ The string must be encoded in UTF-8. - + @@ -723,7 +725,7 @@ [0] https://standards.freedesktop.org/desktop-entry-spec/ - + @@ -911,6 +913,38 @@ outputs are switched off due to screen locking. + + + The left edge of the window is currently constrained, meaning it + shouldn't attempt to resize from that edge. It can for example mean + it's tiled next to a monitor edge on the constrained side of the + window. + + + + + The right edge of the window is currently constrained, meaning it + shouldn't attempt to resize from that edge. It can for example mean + it's tiled next to a monitor edge on the constrained side of the + window. + + + + + The top edge of the window is currently constrained, meaning it + shouldn't attempt to resize from that edge. It can for example mean + it's tiled next to a monitor edge on the constrained side of the + window. + + + + + The bottom edge of the window is currently constrained, meaning it + shouldn't attempt to resize from that edge. It can for example mean + it's tiled next to a monitor edge on the constrained side of the + window. + + @@ -946,11 +980,11 @@ a surface is illegal and will result in an invalid_size error. The width and height must be greater than or equal to zero. Using - strictly negative values for width or height will result in a + strictly negative values for width or height will result in an invalid_size error. - - + + @@ -986,11 +1020,11 @@ a surface is illegal and will result in an invalid_size error. The width and height must be greater than or equal to zero. Using - strictly negative values for width and height will result in a + strictly negative values for width and height will result in an invalid_size error. - - + + @@ -1060,7 +1094,7 @@ If the surface doesn't cover the whole output, the compositor will position the surface in the center of the output and compensate with - with border fill covering the rest of the output. The content of the + border fill covering the rest of the output. The content of the border fill is undefined, but should be assumed to be in some way that attempts to blend into the surrounding area (e.g. solid black). @@ -1069,7 +1103,7 @@ up of subsurfaces, popups or similarly coupled surfaces) are not visible below the fullscreened surface. - + @@ -1126,12 +1160,15 @@ arguments should be interpreted, and possibly how it should be drawn. + The states are sent as an array of 32-bit unsigned integers in + native endianness. State values are defined in the state enum. + Clients must send an ack_configure in response to this event. See xdg_surface.configure and xdg_surface.ack_configure for details. - - - + + + @@ -1167,8 +1204,8 @@ xdg_toplevel.configure_bounds will be sent, followed by xdg_toplevel.configure and xdg_surface.configure. - - + + @@ -1201,13 +1238,13 @@ xdg_surface.configure for details. The capabilities are sent as an array of 32-bit unsigned integers in - native endianness. + native endianness. Capability values are defined in the wm_capabilities enum. - + A popup surface is a short-lived, temporary surface. It can be used to implement for example menus, popovers, tooltips and other similar user diff --git a/local/recipes/wayland/wayland-protocols/source/staging/alpha-modifier/alpha-modifier-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/alpha-modifier/alpha-modifier-v1.xml index 932fa6f2a9..ab0a401d1a 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/alpha-modifier/alpha-modifier-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/alpha-modifier/alpha-modifier-v1.xml @@ -48,7 +48,7 @@ - + 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. diff --git a/local/recipes/wayland/wayland-protocols/source/staging/color-management/README b/local/recipes/wayland/wayland-protocols/source/staging/color-management/README new file mode 100644 index 0000000000..e14f2a8cb0 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/color-management/README @@ -0,0 +1,11 @@ +Color management and HDR protocol + +Maintainers: +Sebastian Wick +Pekka Paalanen + + +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 diff --git a/local/recipes/wayland/wayland-protocols/source/staging/color-management/appendix.md b/local/recipes/wayland/wayland-protocols/source/staging/color-management/appendix.md new file mode 100644 index 0000000000..bdac16e13d --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/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/ diff --git a/local/recipes/wayland/wayland-protocols/source/staging/color-management/color-management-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/color-management/color-management-v1.xml new file mode 100644 index 0000000000..b47e1080e2 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/color-management/color-management-v1.xml @@ -0,0 +1,1756 @@ + + + + Copyright 2019 Sebastian Wick + Copyright 2019 Erwin Burema + Copyright 2020 AMD + Copyright 2020-2024 Collabora, Ltd. + Copyright 2024 Xaver Hugl + 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. + + + + The aim of the color management extension is to allow clients to know + the color properties of outputs, and to tell the compositor about the color + properties of their content on surfaces. All surface contents must be + readily intended for some display, but not necessarily for the display at + hand. Doing this enables a compositor to perform automatic color management + of content for different outputs according to how content is intended to + look like. + + For an introduction, see the section "Color management" in the Wayland + documentation at https://wayland.freedesktop.org/docs/html/ . + + The color properties are represented as an image description object which + is immutable after it has been created. A wl_output always has an + associated image description that clients can observe. A wl_surface + always has an associated preferred image description as a hint chosen by + the compositor that clients can also observe. Clients can set an image + description on a wl_surface to denote the color characteristics of the + surface contents. + + An image description essentially defines a display and (indirectly) its + viewing environment. An image description includes SDR and HDR colorimetry + and encoding, HDR metadata, and some parameters related to the viewing + environment. An image description does not include the properties set + through color-representation extension. It is expected that the + color-representation extension is used in conjunction with the + color-management extension when necessary, particularly with the YUV family + of pixel formats. + + The normative appendix for this protocol is in the appendix.md file beside + this XML file. + + The color-and-hdr repository + (https://gitlab.freedesktop.org/pq/color-and-hdr) contains + background information on the protocol design and legacy color management. + It also contains a glossary, learning resources for digital color, tools, + samples and more. + + The terminology used in this protocol is based on common color science and + color encoding terminology where possible. The glossary in the color-and-hdr + repository shall be the authority on the definition of terms in this + protocol. + + 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. + + + + + A singleton global interface used for getting color management extensions + for wl_surface and wl_output objects, and for creating client defined + image description objects. The extension interfaces allow + getting the image description of outputs and setting the image + description of surfaces. + + Compositors should never remove this global. + + + + + Destroy the wp_color_manager_v1 object. This does not affect any other + objects in any way. + + + + + + + + + + + See the ICC.1:2022 specification from the International Color Consortium + for more details about rendering intents. + + The principles of ICC defined rendering intents apply with all types of + image descriptions, not only those with ICC file profiles. + + Compositors must support the perceptual rendering intent. Other + rendering intents are optional. + + + + + + + + + + This rendering intent is a modified absolute rendering intent that + assumes the viewer is not adapted to the display white point, so no + chromatic adaptation between surface and display is done. + This can be useful for color proofing applications. + + + + + + + + + + + + + + + The compositor supports set_mastering_display_primaries request with a + target color volume fully contained inside the primary color volume. + + + + + The compositor additionally supports target color volumes that + extend outside of the primary color volume. + + This can only be advertised if feature set_mastering_display_primaries + is supported as well. + + + + + + + + + Named color primaries used to encode well-known sets of primaries. + + A value of 0 is invalid and will never be present in the list of enums. + + + + + Color primaries as defined by + - Rec. ITU-R BT.709-6 + - Rec. ITU-R BT.1361-0 conventional colour gamut system and extended + colour gamut system (historical) + - IEC 61966-2-1 sRGB or sYCC + - IEC 61966-2-4 + - Society of Motion Picture and Television Engineers (SMPTE) RP 177 + (1993) Annex B + + + + + Color primaries as defined by + - Rec. ITU-R BT.470-6 System M (historical) + - United States National Television System Committee 1953 + Recommendation for transmission standards for color television + - United States Federal Communications Commission (2003) Title 47 Code + of Federal Regulations 73.682 (a)(20) + + + + + Color primaries as defined by + - Rec. ITU-R BT.470-6 System B, G (historical) + - Rec. ITU-R BT.601-7 625 + - Rec. ITU-R BT.1358-0 625 (historical) + - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM + + + + + Color primaries as defined by + - Rec. ITU-R BT.601-7 525 + - Rec. ITU-R BT.1358-1 525 or 625 (historical) + - Rec. ITU-R BT.1700-0 NTSC + - SMPTE 170M (2004) + - SMPTE 240M (1999) (historical) + + + + + Color primaries as defined by Recommendation ITU-T H.273 + "Coding-independent code points for video signal type identification" + for "generic film". + + + + + Color primaries as defined by + - Rec. ITU-R BT.2020-2 + - Rec. ITU-R BT.2100-0 + + + + + Color primaries as defined as the maximum of the CIE 1931 XYZ color + space by + - SMPTE ST 428-1 + - (CIE 1931 XYZ as in ISO 11664-1) + + + + + Color primaries as defined by Digital Cinema System and published in + SMPTE RP 431-2 (2011). + + + + + Color primaries as defined by Digital Cinema System and published in + SMPTE EG 432-1 (2010). + + + + + Color primaries as defined by Adobe as "Adobe RGB" and later published + by ISO 12640-4 (2011). + + + + + + + Named transfer functions used to represent well-known transfer + characteristics of displays. + + A value of 0 is invalid and will never be present in the list of enums. + + See appendix.md for the formulae. + + + + + Rec. ITU-R BT.1886 is the display transfer characteristic assumed by + - Rec. ITU-R BT.601-7 525 and 625 + - Rec. ITU-R BT.709-6 + - Rec. ITU-R BT.2020-2 + + This TF implies these default luminances from Rec. ITU-R BT.2035: + - primary color volume minimum: 0.01 cd/m² + - primary color volume maximum: 100 cd/m² + - reference white: 100 cd/m² + + + + + Transfer characteristics as defined by + - Rec. ITU-R BT.470-6 System M (historical) + - United States National Television System Committee 1953 + Recommendation for transmission standards for color television + - United States Federal Communications Commission (2003) Title 47 Code + of Federal Regulations 73.682 (a) (20) + - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM + - IEC 61966-2-1 (reference display) + + + + + Transfer characteristics as defined by + - Rec. ITU-R BT.470-6 System B, G (historical) + + + + + Transfer characteristics as defined by + - SMPTE ST 240 (1999) + + + + + Linear transfer function defined over all real numbers. + Normalised electrical values are equal the normalised optical values. + + + + + Logarithmic transfer characteristic (100:1 range). + + + + + Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range). + + + + + Transfer characteristics as defined by + - IEC 61966-2-4 + + + + + Transfer characteristics as defined by + - IEC 61966-2-1 sRGB + + As a rule of thumb, use gamma22 for video, motion picture and + computer graphics, or compound_power_2_4 for ICC calibrated print + workflows. + + + + + Transfer characteristics as defined by + - IEC 61966-2-1 sYCC + + + + + Transfer characteristics as defined by + - SMPTE ST 2084 (2014) for 10-, 12-, 14- and 16-bit systems + - Rec. ITU-R BT.2100-2 perceptual quantization (PQ) system + + This TF implies these default luminances + - primary color volume minimum: 0.005 cd/m² + - primary color volume maximum: 10000 cd/m² + - reference white: 203 cd/m² + + The difference between the primary color volume minimum and maximum + must be approximately 10000 cd/m² as that is the swing of the EOTF + defined by ST 2084 and BT.2100. The default value for the + reference white is a protocol addition: it is suggested by + Report ITU-R BT.2408-7 and is not part of ST 2084 or BT.2100. + + + + + Transfer characteristics as defined by + - SMPTE ST 428-1 (2019) + + + + + Transfer characteristics as defined by + - ARIB STD-B67 (2015) + - Rec. ITU-R BT.2100-2 hybrid log-gamma (HLG) system + + This TF implies these default luminances + - primary color volume minimum: 0.005 cd/m² + - primary color volume maximum: 1000 cd/m² + - reference white: 203 cd/m² + + HLG is a relative display-referred signal with a specified + non-linear mapping to the display peak luminance (the HLG OOTF). + All absolute luminance values used here for HLG assume a 1000 cd/m² + peak display. + + The default value for the reference white is a protocol addition: + it is suggested by Report ITU-R BT.2408-7 and is not part of + ARIB STD-B67 or BT.2100. + + + + + Encoding characteristics as defined by IEC 61966-2-1, for displays + that invert the encoding function. + + + + + + + This creates a new wp_color_management_output_v1 object for the + given wl_output. + + See the wp_color_management_output_v1 interface for more details. + + + + + + + + + If a wp_color_management_surface_v1 object already exists for the given + wl_surface, the protocol error surface_exists is raised. + + This creates a new color wp_color_management_surface_v1 object for the + given wl_surface. + + See the wp_color_management_surface_v1 interface for more details. + + + + + + + + + This creates a new color wp_color_management_surface_feedback_v1 object + for the given wl_surface. + + See the wp_color_management_surface_feedback_v1 interface for more + details. + + + + + + + + + Makes a new ICC-based image description creator object with all + properties initially unset. The client can then use the object's + interface to define all the required properties for an image description + and finally create a wp_image_description_v1 object. + + This request can be used when the compositor advertises + wp_color_manager_v1.feature.icc_v2_v4. + Otherwise this request raises the protocol error unsupported_feature. + + + + + + + + Makes a new parametric image description creator object with all + properties initially unset. The client can then use the object's + interface to define all the required properties for an image description + and finally create a wp_image_description_v1 object. + + This request can be used when the compositor advertises + wp_color_manager_v1.feature.parametric. + Otherwise this request raises the protocol error unsupported_feature. + + + + + + + + This creates a pre-defined image description for the so-called + Windows-scRGB stimulus encoding. This comes from the Windows 10 handling + of its own definition of an scRGB color space for an HDR screen + driven in BT.2100/PQ signalling mode. + + Windows-scRGB uses sRGB (BT.709) color primaries and white point. + The transfer characteristic is extended linear. + + The nominal color channel value range is extended, meaning it includes + negative and greater than 1.0 values. Negative values are used to + escape the sRGB color gamut boundaries. To make use of the extended + range, the client needs to use a pixel format that can represent those + values, e.g. floating-point 16 bits per channel. + + Nominal color value R=G=B=0.0 corresponds to BT.2100/PQ system + 0 cd/m², and R=G=B=1.0 corresponds to BT.2100/PQ system 80 cd/m². + The maximum is R=G=B=125.0 corresponding to 10k cd/m². + + Windows-scRGB is displayed by Windows 10 by converting it to + BT.2100/PQ, maintaining the CIE 1931 chromaticity and mapping the + luminance as above. No adjustment is made to the signal to account + for the viewing conditions. + + The reference white level of Windows-scRGB is unknown. If a + reference white level must be assumed for compositor processing, it + should be R=G=B=2.5375 corresponding to 203 cd/m² of Report ITU-R + BT.2408-7. + + The target color volume of Windows-scRGB is unknown. The color gamut + may be anything between sRGB and BT.2100. + + Note: EGL_EXT_gl_colorspace_scrgb_linear definition differs from + Windows-scRGB by using R=G=B=1.0 as the reference white level, while + Windows-scRGB reference white level is unknown or varies. However, + it seems probable that Windows implements both + EGL_EXT_gl_colorspace_scrgb_linear and Vulkan + VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT as Windows-scRGB. + + This request can be used when the compositor advertises + wp_color_manager_v1.feature.windows_scrgb. + Otherwise this request raises the protocol error unsupported_feature. + + The resulting image description object does not allow get_information + request. The wp_image_description_v1.ready event shall be sent. + + + + + + + + When this object is created, it shall immediately send this event once + for each rendering intent the compositor supports. + + A compositor must not advertise intents that are deprecated in the + bound version of the interface. + + + + + + + + When this object is created, it shall immediately send this event once + for each compositor supported feature listed in the enumeration. + + A compositor must not advertise features that are deprecated in the + bound version of the interface. + + + + + + + + When this object is created, it shall immediately send this event once + for each named transfer function the compositor supports with the + parametric image description creator. + + A compositor must not advertise transfer functions that are deprecated + in the bound version of the interface. + + + + + + + + When this object is created, it shall immediately send this event once + for each named set of primaries the compositor supports with the + parametric image description creator. + + A compositor must not advertise names that are deprecated in the + bound version of the interface. + + + + + + + + This event is sent when all supported rendering intents, features, + transfer functions and named primaries have been sent. + + + + + + This request retrieves the image description backing a reference. + + The get_information request can be used if and only if the request that + creates the reference allows it. + + + + + + + + + This creates a pre-defined image description for the so-called + Windows-BT.2100 stimulus encoding. This comes from the Windows 10 + handling of its own definition of a BT.2100 color space for an HDR + screen driven in BT.2100/PQ signalling mode. + + Windows-BT.2100 uses BT.2020 color primaries and white point. + The transfer characteristic is st2084_pq. + + Windows-BT.2100 is generally displayed by Windows 10 without any + adjustments to the signal to account for viewing conditions. + + The reference white level of Windows-BT.2100 is unknown. If a + reference white level must be assumed for compositor processing, it + should be 203 cd/m² of Report ITU-R BT.2408-7. + + The target color volume of Windows-BT.2100 is unknown. The color gamut + may be anything up to BT.2100. + + This request can be used when the compositor advertises + wp_color_manager_v1.feature.windows_bt2100. + Otherwise this request raises the protocol error unsupported_feature. + + The resulting image description object does not allow get_information + request. The wp_image_description_v1.ready event shall be sent. + + + + + + + + + A wp_color_management_output_v1 describes the color properties of an + output. + + The wp_color_management_output_v1 is associated with the wl_output global + underlying the wl_output object. Therefore the client destroying the + wl_output object has no impact, but the compositor removing the output + global makes the wp_color_management_output_v1 object inert. + + + + + Destroy the color wp_color_management_output_v1 object. This does not + affect any remaining protocol objects. + + + + + + This event is sent whenever the image description of the output changed, + followed by one wl_output.done event common to output events across all + extensions. + + If the client wants to use the updated image description, it needs to do + get_image_description again, because image description objects are + immutable. + + + + + + This creates a new wp_image_description_v1 object for the current image + description of the output. There always is exactly one image description + active for an output so the client should destroy the image description + created by earlier invocations of this request. This request is usually + sent as a reaction to the image_description_changed event or when + creating a wp_color_management_output_v1 object. + + The image description of an output represents the color encoding the + output expects. There might be performance and power advantages, as well + as improved color reproduction, if a content update matches the image + description of the output it is being shown on. If a content update is + shown on any other output than the one it matches the image description + of, then the color reproduction on those outputs might be considerably + worse. + + The created wp_image_description_v1 object preserves the image + description of the output from the time the object was created. + + The resulting image description object allows get_information request. + + If this protocol object is inert, the resulting image description object + shall immediately deliver the wp_image_description_v1.failed event with + the no_output cause. + + If the interface version is inadequate for the output's image + description, meaning that the client does not support all the events + needed to deliver the crucial information, the resulting image + description object shall immediately deliver the + wp_image_description_v1.failed event with the low_version cause. + + Otherwise the object shall immediately deliver the ready event. + + + + + + + + + A wp_color_management_surface_v1 allows the client to set the color + space and HDR properties of a surface. + + If the wl_surface associated with the wp_color_management_surface_v1 is + destroyed, the wp_color_management_surface_v1 object becomes inert. + + + + + Destroy the wp_color_management_surface_v1 object and do the same as + unset_image_description. + + + + + + + + + + + + + If this protocol object is inert, the protocol error inert is raised. + + Set the image description of the underlying surface. The image + description and rendering intent are double-buffered state, see + wl_surface.commit. + + It is the client's responsibility to understand the image description + it sets on a surface, and to provide content that matches that image + description. Compositors might convert images to match their own or any + other image descriptions. + + Image descriptions which are not ready (see wp_image_description_v1) + are forbidden in this request, and in such case the protocol error + image_description is raised. + + All image descriptions which are ready (see wp_image_description_v1) + are allowed and must always be accepted by the compositor. + + When an image description is set on a surface, it establishes an + explicit link between surface pixel values and surface colorimetry. + This link may be undefined for some pixel values, see the image + description creator interfaces for the conditions. Non-finite + floating-point values (NaN, Inf) always have an undefined colorimetry. + + A rendering intent provides the client's preference on how surface + colorimetry should be mapped to each output. The render_intent value + must be one advertised by the compositor with + wp_color_manager_v1.render_intent event, otherwise the protocol error + render_intent is raised. + + By default, a surface does not have an associated image description + nor a rendering intent. The handling of color on such surfaces is + compositor implementation defined. Compositors should handle such + surfaces as sRGB, but may handle them differently if they have specific + requirements. + + Setting the image description has copy semantics; after this request, + the image description can be immediately destroyed without affecting + the pending state of the surface. + + + + + + + + + If this protocol object is inert, the protocol error inert is raised. + + This request removes any image description from the surface. See + set_image_description for how a compositor handles a surface without + an image description. This is double-buffered state, see + wl_surface.commit. + + + + + + + A wp_color_management_surface_feedback_v1 allows the client to get the + preferred image description of a surface. + + If the wl_surface associated with this object is destroyed, the + wp_color_management_surface_feedback_v1 object becomes inert. + + + + + Destroy the wp_color_management_surface_feedback_v1 object. + + + + + + + + + + + + Starting from interface version 2, 'preferred_changed2' is sent instead + of this event. See the 'preferred_changed2' event for the definition. + + + + + + + + If this protocol object is inert, the protocol error inert is raised. + + The preferred image description represents the compositor's preferred + color encoding for this wl_surface at the current time. There might be + performance and power advantages, as well as improved color + reproduction, if the image description of a content update matches the + preferred image description. + + This creates a new wp_image_description_v1 object for the currently + preferred image description for the wl_surface. The client should + stop using and destroy the image descriptions created by earlier + invocations of this request for the associated wl_surface. + This request is usually sent as a reaction to the preferred_changed + event or when creating a wp_color_management_surface_feedback_v1 object + if the client is capable of adapting to image descriptions. + + The created wp_image_description_v1 object preserves the preferred image + description of the wl_surface from the time the object was created. + + The resulting image description object allows get_information request. + + If the image description is parametric, the client should set it on its + wl_surface only if the image description is an exact match with the + client content. Particularly if everything else matches, but the target + color volume is greater than what the client needs, the client should + create its own parameric image description with its exact parameters. + + If the interface version is inadequate for the preferred image + description, meaning that the client does not support all the + events needed to deliver the crucial information, the resulting image + description object shall immediately deliver the + wp_image_description_v1.failed event with the low_version cause, + otherwise the object shall immediately deliver the ready event. + + + + + + + + The same description as for get_preferred applies, except the returned + image description is guaranteed to be parametric. This is meant for + clients that can only deal with parametric image descriptions. + + If the compositor doesn't support parametric image descriptions, the + unsupported_feature error is emitted. + + + + + + + + + + The preferred image description is the one which likely has the most + performance and/or quality benefits for the compositor if used by the + client for its wl_surface contents. This event is sent whenever the + compositor changes the wl_surface's preferred image description. + + This event sends the identity of the new preferred state as the argument, + so clients who are aware of the image description already can reuse it. + Otherwise, if the client client wants to know what the preferred image + description is, it shall use the get_preferred request. + + The preferred image description is not automatically used for anything. + It is only a hint, and clients may set any valid image description with + set_image_description, but there might be performance and color accuracy + improvements by providing the wl_surface contents in the preferred + image description. Therefore clients that can, should render according + to the preferred image description + + + + + + + + + + + This type of object is used for collecting all the information required + to create a wp_image_description_v1 object from an ICC file. A complete + set of required parameters consists of these properties: + - ICC file + + Each required property must be set exactly once if the client is to create + an image description. The set requests verify that a property was not + already set. The create request verifies that all required properties are + set. There may be several alternative requests for setting each property, + and in that case the client must choose one of them. + + Once all properties have been set, the create request must be used to + create the image description object, destroying the creator in the + process. + + The link between a pixel value (a device value in ICC) and its respective + colorimetry is defined by the details of the particular ICC profile. + Those details also determine when colorimetry becomes undefined. + + + + + + + + + + + + + + + Create an image description object based on the ICC information + previously set on this object. A compositor must parse the ICC data in + some undefined but finite amount of time. + + The completeness of the parameter set is verified. If the set is not + complete, the protocol error incomplete_set is raised. For the + definition of a complete set, see the description of this interface. + + If the particular combination of the information is not supported + by the compositor, the resulting image description object shall + immediately deliver the wp_image_description_v1.failed event with the + 'unsupported' cause. If a valid image description was created from the + information, the wp_image_description_v1.ready event will eventually + be sent instead. + + This request destroys the wp_image_description_creator_icc_v1 object. + + The resulting image description object does not allow get_information + request. + + + + + + + + Sets the ICC profile file to be used as the basis of the image + description. + + The data shall be found through the given fd at the given offset, having + the given length. The fd must be seekable and readable. Violating these + requirements raises the bad_fd protocol error. + + If reading the data fails due to an error independent of the client, the + compositor shall send the wp_image_description_v1.failed event on the + created wp_image_description_v1 with the 'operating_system' cause. + + The maximum size of the ICC profile is 32 MB. If length is greater than + that or zero, the protocol error bad_size is raised. If offset + length + exceeds the file size, the protocol error out_of_file is raised. + + A compositor may read the file at any time starting from this request + and only until whichever happens first: + - If create request was issued, the wp_image_description_v1 object + delivers either failed or ready event; or + - if create request was not issued, this + wp_image_description_creator_icc_v1 object is destroyed. + + A compositor shall not modify the contents of the file, and the fd may + be sealed for writes and size changes. The client must ensure to its + best ability that the data does not change while the compositor is + reading it. + + The data must represent a valid ICC profile. The ICC profile version + must be 2 or 4, it must be a 3 channel profile and the class must be + Display or ColorSpace. Violating these requirements will not result in a + protocol error, but will eventually send the + wp_image_description_v1.failed event on the created + wp_image_description_v1 with the 'unsupported' cause. + + See the International Color Consortium specification ICC.1:2022 for more + details about ICC profiles. + + If ICC file has already been set on this object, the protocol error + already_set is raised. + + + + + + + + + + + This type of object is used for collecting all the parameters required + to create a wp_image_description_v1 object. A complete set of required + parameters consists of these properties: + - transfer characteristic function (tf) + - chromaticities of primaries and white point (primary color volume) + + The following properties are optional and have a well-defined default + if not explicitly set: + - primary color volume luminance range + - reference white luminance level + - mastering display primaries and white point (target color volume) + - mastering luminance range + + The following properties are optional and will be ignored + if not explicitly set: + - maximum content light level + - maximum frame-average light level + + Each required property must be set exactly once if the client is to create + an image description. The set requests verify that a property was not + already set. The create request verifies that all required properties are + set. There may be several alternative requests for setting each property, + and in that case the client must choose one of them. + + Once all properties have been set, the create request must be used to + create the image description object, destroying the creator in the + process. + + A viewer, who is viewing the display defined by the resulting image + description (the viewing environment included), is assumed to be fully + adapted to the primary color volume's white point. + + Any of the following conditions will cause the colorimetry of a pixel + to become undefined: + - Values outside of the defined range of the transfer characteristic. + - Tristimulus that exceeds the target color volume. + - If extended_target_volume is not supported: tristimulus that exceeds + the primary color volume. + + The closest correspondence to an image description created through this + interface is the Display class of profiles in ICC. + + + + + + + + + + + + + + + + Create an image description object based on the parameters previously + set on this object. + + The completeness of the parameter set is verified. If the set is not + complete, the protocol error incomplete_set is raised. For the + definition of a complete set, see the description of this interface. + + When both max_cll and max_fall are set, max_fall must be less or equal + to max_cll otherwise the invalid_luminance protocol error is raised. + + In version 1, these following conditions also result in the + invalid_luminance protocol error. Version 2 and later do not have this + requirement. + - When max_cll is set, it must be greater than min L and less or equal + to max L of the mastering luminance range. + - When max_fall is set, it must be greater than min L and less or equal + to max L of the mastering luminance range. + + If the particular combination of the parameter set is not supported + by the compositor, the resulting image description object shall + immediately deliver the wp_image_description_v1.failed event with the + 'unsupported' cause. If a valid image description was created from the + parameter set, the wp_image_description_v1.ready event will eventually + be sent instead. + + This request destroys the wp_image_description_creator_params_v1 + object. + + The resulting image description object does not allow get_information + request. + + + + + + + + Sets the transfer characteristic using explicitly enumerated named + functions. + + When the resulting image description is attached to an image, the + content should be decoded according to the industry standard + practices for the transfer characteristic. + + Only names advertised with wp_color_manager_v1 event supported_tf_named + are allowed. Other values shall raise the protocol error invalid_tf. + + If transfer characteristic has already been set on this object, the + protocol error already_set is raised. + + + + + + + + Sets the color component transfer characteristic to a power curve with + the given exponent. Negative values are handled by mirroring the + positive half of the curve through the origin. The valid domain and + range of the curve are all finite real numbers. This curve represents + the conversion from electrical to optical color channel values. + + The curve exponent shall be multiplied by 10000 to get the argument eexp + value to carry the precision of 4 decimals. + + The curve exponent must be at least 1.0 and at most 10.0. Otherwise the + protocol error invalid_tf is raised. + + If transfer characteristic has already been set on this object, the + protocol error already_set is raised. + + This request can be used when the compositor advertises + wp_color_manager_v1.feature.set_tf_power. Otherwise this request raises + the protocol error unsupported_feature. + + + + + + + + Sets the color primaries and white point using explicitly named sets. + This describes the primary color volume which is the basis for color + value encoding. + + Only names advertised with wp_color_manager_v1 event + supported_primaries_named are allowed. Other values shall raise the + protocol error invalid_primaries_named. + + If primaries have already been set on this object, the protocol error + already_set is raised. + + + + + + + + Sets the color primaries and white point using CIE 1931 xy chromaticity + coordinates. This describes the primary color volume which is the basis + for color value encoding. + + Each coordinate value is multiplied by 1 million to get the argument + value to carry precision of 6 decimals. + + If primaries have already been set on this object, the protocol error + already_set is raised. + + This request can be used if the compositor advertises + wp_color_manager_v1.feature.set_primaries. Otherwise this request raises + the protocol error unsupported_feature. + + + + + + + + + + + + + + + Sets the primary color volume luminance range and the reference white + luminance level. These values include the minimum display emission, but + not external flare. The minimum display emission is assumed to have + the chromaticity of the primary color volume white point. + + The default luminances from + https://www.color.org/chardata/rgb/srgb.xalter are + - primary color volume minimum: 0.2 cd/m² + - primary color volume maximum: 80 cd/m² + - reference white: 80 cd/m² + + Setting a named transfer characteristic can imply other default + luminances. + + The default luminances get overwritten when this request is used. + With transfer_function.st2084_pq the given 'max_lum' value is ignored, + and 'max_lum' is taken as 'min_lum' + 10000 cd/m². + + 'min_lum' and 'max_lum' specify the minimum and maximum luminances of + the primary color volume as reproduced by the targeted display. + + 'reference_lum' specifies the luminance of the reference white as + reproduced by the targeted display, and reflects the targeted viewing + environment. + + Compositors should make sure that all content is anchored, meaning that + an input signal level of 'reference_lum' on one image description and + another input signal level of 'reference_lum' on another image + description should produce the same output level, even though the + 'reference_lum' on both image representations can be different. + + 'reference_lum' may be higher than 'max_lum'. In that case reaching + the reference white output level in image content requires the + 'extended_target_volume' feature support. + + If 'max_lum' or 'reference_lum' are less than or equal to 'min_lum', + the protocol error invalid_luminance is raised. + + The minimum luminance is multiplied by 10000 to get the argument + 'min_lum' value and carries precision of 4 decimals. The maximum + luminance and reference white luminance values are unscaled. + + If the primary color volume luminance range and the reference white + luminance level have already been set on this object, the protocol error + already_set is raised. + + This request can be used if the compositor advertises + wp_color_manager_v1.feature.set_luminances. Otherwise this request + raises the protocol error unsupported_feature. + + + + + + + + + + Provides the color primaries and white point of the mastering display + using CIE 1931 xy chromaticity coordinates. This is compatible with the + SMPTE ST 2086 definition of HDR static metadata. + + The mastering display primaries and mastering display luminances define + the target color volume. + + If mastering display primaries are not explicitly set, the target color + volume is assumed to have the same primaries as the primary color volume. + + The target color volume is defined by all tristimulus values between 0.0 + and 1.0 (inclusive) of the color space defined by the given mastering + display primaries and white point. The colorimetry is identical between + the container color space and the mastering display color space, + including that no chromatic adaptation is applied even if the white + points differ. + + The target color volume can exceed the primary color volume to allow for + a greater color volume with an existing color space definition (for + example scRGB). It can be smaller than the primary color volume to + minimize gamut and tone mapping distances for big color spaces (HDR + metadata). + + To make use of the entire target color volume a suitable pixel format + has to be chosen (e.g. floating point to exceed the primary color + volume, or abusing limited quantization range as with xvYCC). + + Each coordinate value is multiplied by 1 million to get the argument + value to carry precision of 6 decimals. + + If mastering display primaries have already been set on this object, the + protocol error already_set is raised. + + This request can be used if the compositor advertises + wp_color_manager_v1.feature.set_mastering_display_primaries. Otherwise + this request raises the protocol error unsupported_feature. The + advertisement implies support only for target color volumes fully + contained within the primary color volume. + + If a compositor additionally supports target color volume exceeding the + primary color volume, it must advertise + wp_color_manager_v1.feature.extended_target_volume. If a client uses + target color volume exceeding the primary color volume and the + compositor does not support it, the result is implementation defined. + Compositors are recommended to detect this case and fail the image + description gracefully, but it may as well result in color artifacts. + + + + + + + + + + + + + + + Sets the luminance range that was used during the content mastering + process as the minimum and maximum absolute luminance L. These values + include the minimum display emission and ambient flare luminances, + assumed to be optically additive and have the chromaticity of the + primary color volume white point. This should be + compatible with the SMPTE ST 2086 definition of HDR static metadata. + + The mastering display primaries and mastering display luminances define + the target color volume. + + If mastering luminances are not explicitly set, the target color volume + is assumed to have the same min and max luminances as the primary color + volume. + + If max L is less than or equal to min L, the protocol error + invalid_luminance is raised. + + Min L value is multiplied by 10000 to get the argument min_lum value + and carry precision of 4 decimals. Max L value is unscaled for max_lum. + + This request can be used if the compositor advertises + wp_color_manager_v1.feature.set_mastering_display_primaries. Otherwise + this request raises the protocol error unsupported_feature. The + advertisement implies support only for target color volumes fully + contained within the primary color volume. + + If a compositor additionally supports target color volume exceeding the + primary color volume, it must advertise + wp_color_manager_v1.feature.extended_target_volume. If a client uses + target color volume exceeding the primary color volume and the + compositor does not support it, the result is implementation defined. + Compositors are recommended to detect this case and fail the image + description gracefully, but it may as well result in color artifacts. + + + + + + + + + Sets the maximum content light level (max_cll) as defined by CTA-861-H. + + max_cll is undefined by default. + + + + + + + + Sets the maximum frame-average light level (max_fall) as defined by + CTA-861-H. + + max_fall is undefined by default. + + + + + + + + + An image description carries information about the pixel color encoding + and its intended display and viewing environment. The image description is + attached to a wl_surface via + wp_color_management_surface_v1.set_image_description. A compositor can use + this information to decode pixel values into colorimetrically meaningful + quantities, which allows the compositor to transform the surface contents + to become suitable for various displays and viewing environments. + + Note, that the wp_image_description_v1 object is not ready to be used + immediately after creation. The object eventually delivers either the + 'ready' or the 'failed' event, specified in all requests creating it. The + object is deemed "ready" after receiving the 'ready' event. + + An object which is not ready is illegal to use, it can only be destroyed. + Any other request in this interface shall result in the 'not_ready' + protocol error. Attempts to use an object which is not ready through other + interfaces shall raise protocol errors defined there. + + Once created and regardless of how it was created, a + wp_image_description_v1 object always refers to one fixed image + description. It cannot change after creation. + + + + + Destroy this object. It is safe to destroy an object which is not ready. + + Destroying a wp_image_description_v1 object has no side-effects, not + even if a wp_color_management_surface_v1.set_image_description has not + yet been followed by a wl_surface.commit. + + + + + + + + + + + + + + + + + + + + + + If creating a wp_image_description_v1 object fails for a reason that is + not defined as a protocol error, this event is sent. + + The requests that create image description objects define whether and + when this can occur. Only such creation requests can trigger this event. + This event cannot be triggered after the image description was + successfully formed. + + Once this event has been sent, the wp_image_description_v1 object will + never become ready and it can only be destroyed. + + + + + + + + + Starting from interface version 2, the 'ready2' event is sent instead + of this event. + + For the definition of this event, see the 'ready2' event. The + difference to this event is as follows. + + The id number is valid only as long as the protocol object is alive. If + all protocol objects referring to the same image description record are + destroyed, the id number may be recycled for a different image + description record. + + + + + + + + Creates a wp_image_description_info_v1 object which delivers the + information that makes up the image description. + + Not all image description protocol objects allow get_information + request. Whether it is allowed or not is defined by the request that + created the object. If get_information is not allowed, the protocol + error no_information is raised. + + + + + + + + + + Once this event has been sent, the wp_image_description_v1 object is + deemed "ready". Ready objects can be used to send requests and can be + used through other interfaces. + + Every ready wp_image_description_v1 protocol object refers to an + underlying image description record in the compositor. Multiple protocol + objects may end up referring to the same record. Clients may identify + these "copies" by comparing their id numbers: if the numbers from two + protocol objects are identical, the protocol objects refer to the same + image description record. Two different image description records + cannot have the same id number simultaneously. The id number does not + change during the lifetime of the image description record. + + Image description id number is not a protocol object id. Zero is + reserved as an invalid id number. It shall not be possible for a client + to refer to an image description by its id number in protocol. The id + numbers might not be portable between Wayland connections. A compositor + shall not send an invalid id number. + + Compositors must not recycle image description id numbers. + + This identity allows clients to de-duplicate image description records + and avoid get_information request if they already have the image + description information. + + + + + + + + + + Sends all matching events describing an image description object exactly + once and finally sends the 'done' event. + + This means + - if the image description is parametric, it must send + - primaries + - named_primaries, if applicable + - at least one of tf_power and tf_named, as applicable + - luminances + - target_primaries + - target_luminance + - if the image description is parametric, it may send, if applicable, + - target_max_cll + - target_max_fall + - if the image description contains an ICC profile, it must send the + icc_file event + + Once a wp_image_description_info_v1 object has delivered a 'done' event it + is automatically destroyed. + + Every wp_image_description_info_v1 created from the same + wp_image_description_v1 shall always return the exact same data. + + + + + Signals the end of information events and destroys the object. + + + + + + The icc argument provides a file descriptor to the client which may be + memory-mapped to provide the ICC profile matching the image description. + The fd is read-only, and if mapped then it must be mapped with + MAP_PRIVATE by the client. + + The ICC profile version and other details are determined by the + compositor. There is no provision for a client to ask for a specific + kind of a profile. + + + + + + + + + + Delivers the primary color volume primaries and white point using CIE + 1931 xy chromaticity coordinates. + + Each coordinate value is multiplied by 1 million to get the argument + value to carry precision of 6 decimals. + + + + + + + + + + + + + + + Delivers the primary color volume primaries and white point using an + explicitly enumerated named set. + + + + + + + + The color component transfer characteristic of this image description is + a pure power curve. This event provides the exponent of the power + function. This curve represents the conversion from electrical to + optical pixel or color values. + + The curve exponent has been multiplied by 10000 to get the argument eexp + value to carry the precision of 4 decimals. + + + + + + + + Delivers the transfer characteristic using an explicitly enumerated + named function. + + + + + + + + Delivers the primary color volume luminance range and the reference + white luminance level. These values include the minimum display emission + and ambient flare luminances, assumed to be optically additive and have + the chromaticity of the primary color volume white point. + + The minimum luminance is multiplied by 10000 to get the argument + 'min_lum' value and carries precision of 4 decimals. The maximum + luminance and reference white luminance values are unscaled. + + + + + + + + + + Provides the color primaries and white point of the target color volume + using CIE 1931 xy chromaticity coordinates. This is compatible with the + SMPTE ST 2086 definition of HDR static metadata for mastering displays. + + While primary color volume is about how color is encoded, the target + color volume is the actually displayable color volume. + + Each coordinate value is multiplied by 1 million to get the argument + value to carry precision of 6 decimals. + + + + + + + + + + + + + + + Provides the luminance range that the image description is targeting as + the minimum and maximum absolute luminance L. These values include the + minimum display emission and ambient flare luminances, assumed to be + optically additive and have the chromaticity of the primary color + volume white point. This should be compatible with the SMPTE ST 2086 + definition of HDR static metadata. + + This luminance range is only theoretical and may not correspond to the + luminance of light emitted on an actual display. + + Min L value is multiplied by 10000 to get the argument min_lum value and + carry precision of 4 decimals. Max L value is unscaled for max_lum. + + + + + + + + + Provides the targeted max_cll of the image description. max_cll is + defined by CTA-861-H. + + This luminance is only theoretical and may not correspond to the + luminance of light emitted on an actual display. + + + + + + + + Provides the targeted max_fall of the image description. max_fall is + defined by CTA-861-H. + + This luminance is only theoretical and may not correspond to the + luminance of light emitted on an actual display. + + + + + + + + + This object is a reference to an image description. This interface is + frozen at version 1 to allow other protocols to create + wp_image_description_v1 objects. + + The wp_color_manager_v1.get_image_description request can be used to + retrieve the underlying image description. + + + + + Destroy this object. This has no effect on the referenced image + description. + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/color-representation/README b/local/recipes/wayland/wayland-protocols/source/staging/color-representation/README new file mode 100644 index 0000000000..5665025b69 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/color-representation/README @@ -0,0 +1,6 @@ +color-representation protocol + +Maintainers: +Simon Ser +Sebastian Wick +Pekka Paalanen diff --git a/local/recipes/wayland/wayland-protocols/source/staging/color-representation/color-representation-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/color-representation/color-representation-v1.xml new file mode 100644 index 0000000000..3256a9d013 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/color-representation/color-representation-v1.xml @@ -0,0 +1,433 @@ + + + + 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. + + + + 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. + + + + + 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. + + + + + + + + + + Destroy the wp_color_representation_manager_v1 object. This does not + affect any other objects in any way. + + + + + + + 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. + + + + + + + + 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. + + + + + + + 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. + + + + + + + + This event is sent when all supported features have been sent. + + + + + + + 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. + + + + + + + + + + + + + + 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. + + + + + + Specifies how the alpha channel affects the color channels. + + + + Electrical color channel values (after transfer function encoding) + are already multiplied with the alpha channel value. + + + + + Optical color channel values (before transfer function encoding) + are already multiplied with the alpha channel value. + + + + + Alpha channel has not been pre-multiplied into color channels. + + + + + + + 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. + + + + 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. + + + + + 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. + + + + + 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. + + + + + 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. + + + + + Coefficients as defined by + - SMPTE ST 240 (1999) + + Equivalent to H.273 MatrixCoefficients code point 7. + Compatible with pixel formats of the YCbCr family. + + + + + 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. + + + + + 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. + + + + + 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. + + + + + + + Possible color range values. + + A value of 0 is invalid and will never be present in the list of enums. + + + + + + + + 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. + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + + Equivalent to H.273 Chroma420SampleLocType 0. + + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + + Equivalent to H.273 Chroma420SampleLocType 1. + + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + + Equivalent to H.273 Chroma420SampleLocType 2. + + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + + Equivalent to H.273 Chroma420SampleLocType 3. + + + + + Equivalent to H.273 Chroma420SampleLocType 4. + + + + + Equivalent to H.273 Chroma420SampleLocType 5. + + + + + + + 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. + + + + + + + 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. + + + + + + + + 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. + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/color-representation/notes.rst b/local/recipes/wayland/wayland-protocols/source/staging/color-representation/notes.rst new file mode 100644 index 0000000000..a68db33a83 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/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. diff --git a/local/recipes/wayland/wayland-protocols/source/staging/content-type/content-type-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/content-type/content-type-v1.xml index 2624aa12b5..65a1acb80f 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/content-type/content-type-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/content-type/content-type-v1.xml @@ -48,7 +48,7 @@ - + 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 diff --git a/local/recipes/wayland/wayland-protocols/source/staging/cursor-shape/cursor-shape-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/cursor-shape/cursor-shape-v1.xml index 8df2e4ba9e..64b2f9b2c8 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/cursor-shape/cursor-shape-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/cursor-shape/cursor-shape-v1.xml @@ -22,7 +22,7 @@ DEALINGS IN THE SOFTWARE. - + This global offers an alternative, optional way to set cursor images. This new way uses enumerated cursors instead of a wl_surface like @@ -63,7 +63,7 @@ - + This interface allows clients to set the cursor shape. @@ -74,6 +74,14 @@ 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. @@ -109,6 +117,8 @@ + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/drm-lease/README b/local/recipes/wayland/wayland-protocols/source/staging/drm-lease/README index 30bb44fc69..86c3408fe5 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/drm-lease/README +++ b/local/recipes/wayland/wayland-protocols/source/staging/drm-lease/README @@ -1,6 +1,6 @@ Linux DRM lease Maintainers: -Drew DeVault +Simon Zeni (@bl4ckb0ne) Marius Vlad (@mvlad) Xaver Hugl (@Zamundaaa) diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/README b/local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/README new file mode 100644 index 0000000000..c9ee9d69eb --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/README @@ -0,0 +1,6 @@ +ext_blur protocol + +Maintainers: +David Edmundson +Vlad Zahorodnii +Xaver Hugl diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/ext-background-effect-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/ext-background-effect-v1.xml new file mode 100644 index 0000000000..fa6d7116aa --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/ext-background-effect-v1.xml @@ -0,0 +1,129 @@ + + + + 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. + + + + + 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. + + + + + Informs the server that the client will no longer be using this + protocol object. Existing objects created by this object are not + affected. + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + 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. + + + + + Informs the server that the client will no longer be using this protocol + object. The effect regions will be removed on the next commit. + + + + + + + + + + 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. + + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/README b/local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/README new file mode 100644 index 0000000000..e0dce8970a --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/README @@ -0,0 +1,4 @@ +data-control protocol + +Maintainers: +Neal Gompa (@Conan_Kudo) diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/ext-data-control-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/ext-data-control-v1.xml new file mode 100644 index 0000000000..37ee577ed9 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/ext-data-control-v1.xml @@ -0,0 +1,276 @@ + + + + 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. + + + + 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. + + + + + This interface is a manager that allows creating per-seat data device + controls. + + + + + Create a new data source. + + + + + + + Create a data device that can be used to manage a seat's selection. + + + + + + + + All objects created by the manager will still remain valid, until their + appropriate destroy request has been called. + + + + + + + This interface allows a client to manage a seat's selection. + + When the seat is destroyed, this object becomes inert. + + + + + 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. + + + + + + + Destroys the data device object. + + + + + + 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. + + + + + + + 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. + + + + + + + This data control object is no longer valid and should be destroyed by + the client. + + + + + + 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. + + + + + + + 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. + + + + + + + + + + + + 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. + + + + + + + + + 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. + + + + + + + Destroys the data source object. + + + + + + Request for data from the client. Send the data as the specified MIME + type over the passed file descriptor, then close it. + + + + + + + + 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. + + + + + + + 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. + + + + + 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. + + + + + + + + Destroys the data offer object. + + + + + + Sent immediately after creating the ext_data_control_offer object. + One event per offered MIME type. + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml index 11b0113a9c..f1bbe0ea7e 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml @@ -201,7 +201,7 @@ The compositor must only send this event when the handle is created. - The identifier must be unique per toplevel and it's handles. Two different + 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 diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-idle-notify/ext-idle-notify-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/ext-idle-notify/ext-idle-notify-v1.xml index 6fe97d737a..db7d9c1650 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/ext-idle-notify/ext-idle-notify-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-idle-notify/ext-idle-notify-v1.xml @@ -24,7 +24,7 @@ DEALINGS IN THE SOFTWARE. - + This interface allows clients to monitor user idle status. @@ -54,9 +54,30 @@ + + + + + + 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. + + + + + + - + This interface is used by the compositor to send idle notification events to clients. @@ -65,9 +86,17 @@ 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. 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. + 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, diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-image-capture-source/ext-image-capture-source-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/ext-image-capture-source/ext-image-capture-source-v1.xml index b31a5da3eb..e0808c25a8 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/ext-image-capture-source/ext-image-capture-source-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-image-capture-source/ext-image-capture-source-v1.xml @@ -39,7 +39,7 @@ only be done by creating a new major version of the extension. - + 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 diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml index 7a501cc59e..1ac43696a0 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml @@ -376,7 +376,7 @@ - + @@ -390,7 +390,7 @@ - + Gets the image copy capture session for this cursor session. The session will produce frames of the cursor image. The compositor may diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/README b/local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/README new file mode 100644 index 0000000000..7d5f2a347f --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/README @@ -0,0 +1,5 @@ +Workspace protocol + +Maintainers: +Ilia Bozhinov +Victoria Brekenfeld \ No newline at end of file diff --git a/local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/ext-workspace-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/ext-workspace-v1.xml new file mode 100644 index 0000000000..7b58d45b1c --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/ext-workspace-v1.xml @@ -0,0 +1,422 @@ + + + + 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. + + + + + 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. + + + + + 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. + + + + + + + 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. + + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + + + 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. + + + + + + + + + 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. + + + + + + + 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. + + + + + + + This event is emitted whenever an output is removed from the 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. + + + + + + + This event is emitted whenever a workspace is removed from this group. + + + + + + + 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. + + + + + + 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. + + + + + + + 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. + + + + + + + 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). + + + + + 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. + + + + + + + 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. + + + + + + + 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. + + + + + + + The different states that a workspace can have. + + + + + + + The workspace is not visible in its workspace group, and clients + attempting to visualize the compositor workspace state should not + display such workspaces. + + + + + + + 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. + + + + + + + + + + + + + + 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. + + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + Request that this workspace be deactivated. + + There is no guarantee the workspace will be actually deactivated. + + + + + + Requests that this workspace is assigned to the given workspace group. + + There is no guarantee the workspace will be assigned. + + + + + + + Request that this workspace be removed. + + There is no guarantee the workspace will be actually removed. + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/README b/local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/README new file mode 100644 index 0000000000..a948475454 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/README @@ -0,0 +1,7 @@ +pointer-warp protocol + +Maintainers: +Neal Gompa (@Conan_Kudo) +Xaver Hugl (@Zamundaaa) +Matthias Klumpp (@mak) +Vlad Zahorodnii (@zzag) diff --git a/local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/pointer-warp-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/pointer-warp-v1.xml new file mode 100644 index 0000000000..158dad83c5 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/pointer-warp-v1.xml @@ -0,0 +1,72 @@ + + + + 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. + + + + + 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. + + + + + Destroy the pointer warp manager. + + + + + + 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. + + + + + + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/single-pixel-buffer/single-pixel-buffer-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/single-pixel-buffer/single-pixel-buffer-v1.xml index b157155781..bcbd0382eb 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/single-pixel-buffer/single-pixel-buffer-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/single-pixel-buffer/single-pixel-buffer-v1.xml @@ -58,6 +58,13 @@ 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 diff --git a/local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/README b/local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/README new file mode 100644 index 0000000000..441ae33866 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/README @@ -0,0 +1,5 @@ +xdg session management protocol + +Maintainers: +Jonas Ådahl +Mike Blumenkrantz diff --git a/local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/xdg-session-management-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/xdg-session-management-v1.xml new file mode 100644 index 0000000000..9cfe5f8792 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/xdg-session-management-v1.xml @@ -0,0 +1,333 @@ + + + + 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. + + + + 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. + + + + + 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. + + + + + + + + + + + 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. + + + + A new app instance is launched, for example from an app launcher. + + + + + An app instance is recovering from for example a compositor or app crash. + + + + + An app instance is restored, for example part of a restored session, or + restored from having been temporarily terminated due to resource + constraints. + + + + + + + Destroy the manager object. The existing session objects will be + unaffected. + + + + + + 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. + + + + + + + + + + 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. + + + + + + + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + + + + 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. + + + + + + + + + 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). + + + + + + + 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. + + + + + + + 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. + + + + + + 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. + + + + + + + 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. + + + + + Destroy the object. This has no effect over window management of the + associated toplevel. + + + + + + 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. + + + + + + + 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. + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-drag/README b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-drag/README index 70efe8b551..659295f5a4 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-drag/README +++ b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-drag/README @@ -2,3 +2,4 @@ xdg toplevel drag protocol Maintainers: David Redondo (@davidre) +Nick Yamane (@nickdiego) diff --git a/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-icon/xdg-toplevel-icon-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-icon/xdg-toplevel-icon-v1.xml index fc409fef7c..985c3f3da6 100644 --- a/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-icon/xdg-toplevel-icon-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-icon/xdg-toplevel-icon-v1.xml @@ -107,7 +107,7 @@ 'done' event, without any preceding 'icon_size' events. + summary="the edge size of the square icon in surface-local coordinates, e.g. 64"/> @@ -132,10 +132,10 @@ + value="1"/> + value="2"/> @@ -163,7 +163,7 @@ fall back to using pixel buffer data instead. If this request is made after the icon has been assigned to a toplevel - via 'set_icon', a 'immutable' error must be raised. + via 'set_icon', an 'immutable' error must be raised. [1]: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html @@ -195,11 +195,11 @@ request is sent. The wl_buffer.release event is unused. If this request is made after the icon has been assigned to a toplevel - via 'set_icon', a 'immutable' error must be raised. + via 'set_icon', an 'immutable' error must be raised. + summary="the scaling factor of the icon, e.g. 1"/> diff --git a/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/README b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/README new file mode 100644 index 0000000000..b4910eef48 --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/README @@ -0,0 +1,4 @@ +Toplevel tag protocol + +Maintainers: +Xaver Hugl diff --git a/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/xdg-toplevel-tag-v1.xml b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/xdg-toplevel-tag-v1.xml new file mode 100644 index 0000000000..5e20bdf45f --- /dev/null +++ b/local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/xdg-toplevel-tag-v1.xml @@ -0,0 +1,85 @@ + + + + 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. + + + + + In order to make some window properties like position, size, + "always on top" or user defined rules for window behavior persistent, the + compositor needs some way to identify windows even after the application + has been restarted. + This protocol allows clients to make this possible by setting a tag for + toplevels. + + 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. + + + + + Destroy this toplevel tag manager object. This request has no other + effects. + + + + + + Set a tag for a toplevel. The tag may be shown to the user in UI, so + it's preferable for it to be human readable, but it must be suitable + for configuration files and should not be translated. + Suitable tags would for example be "main window", "settings", + "e-mail composer" or similar. + + The tag does not need to be unique across applications, and the client + may set the same tag for multiple windows, for example if the user has + opened the same UI twice. How the potentially resulting conflicts are + handled is compositor policy. + + The client should set the tag as part of the initial commit on the + associated toplevel, but it may set it at any time afterwards as well, + for example if the purpose of the toplevel changes. + + + + + + + + Set a description for a toplevel. This description may be shown to the + user in UI or read by a screen reader for accessibility purposes, and + should be translated. + It is recommended to make the description the translation of the tag. + + The client should set the description as part of the initial commit on + the associated toplevel, but it may set it at any time afterwards as + well, for example if the purpose of the toplevel changes. + + + + + + + diff --git a/local/recipes/wayland/wayland-protocols/source/tests/meson.build b/local/recipes/wayland/wayland-protocols/source/tests/meson.build index aa216ec2cd..f36f14f195 100644 --- a/local/recipes/wayland/wayland-protocols/source/tests/meson.build +++ b/local/recipes/wayland/wayland-protocols/source/tests/meson.build @@ -7,7 +7,7 @@ libwayland = [ # Check that each protocol passes through the scanner foreach protocol_file : protocol_files - protocol_path = join_paths(wayland_protocols_srcdir, protocol_file) + protocol_path = join_paths(meson.project_source_root(), protocol_file) test_name = 'scan-@0@'.format(protocol_file.underscorify()) test(test_name, prog_scan_sh, args: protocol_path, @@ -22,16 +22,19 @@ endforeach add_languages('c', 'cpp', native: false) replace = find_program('replace.py') -extra_linker_flags = meson.get_compiler('c').get_supported_link_arguments([ - '-Wl,--unresolved-symbols=ignore-all', -]) +# First pass: generate scanner outputs for each protocol and record the +# generated custom_targets for use when building test executables. +protocol_code = {} +protocol_client_header = {} +protocol_server_header = {} +protocol_replace_command = {} foreach protocol_file : protocol_files xml_file = fs.name(protocol_file) xml_components = xml_file.split('.') protocol_base_file_name = xml_components[0] - protocol_path = files(join_paths(wayland_protocols_srcdir, protocol_file)) + protocol_path = files(join_paths(meson.project_source_root(), protocol_file)) client_header_path = '@0@-client.h'.format(protocol_base_file_name) server_header_path = '@0@-server.h'.format(protocol_base_file_name) code_path = '@0@-code.c'.format(protocol_base_file_name) @@ -75,7 +78,10 @@ foreach protocol_file : protocol_files install: false, ) - replace_command = [ + protocol_code += {protocol_file: code} + protocol_client_header += {protocol_file: client_header} + protocol_server_header += {protocol_file: server_header} + protocol_replace_command += {protocol_file: [ replace, '@INPUT@', '@OUTPUT@', @@ -83,7 +89,22 @@ foreach protocol_file : protocol_files client_header.full_path(), 'PROTOCOL_SERVER_INCLUDE_FILE', server_header.full_path(), - ] + ]} +endforeach + +# Second pass: build test executables, linking in dependency code. +foreach protocol_file : protocol_files + client_header = protocol_client_header[protocol_file] + server_header = protocol_server_header[protocol_file] + code = protocol_code[protocol_file] + replace_command = protocol_replace_command[protocol_file] + + dep_code = [] + if protocol_file in protocol_deps + foreach dep : protocol_deps[protocol_file] + dep_code += [protocol_code[dep]] + endforeach + endif # Check that header can be included by a pedantic C99 compiler test_name = 'test-build-pedantic-@0@'.format(protocol_file.underscorify()) @@ -100,9 +121,8 @@ foreach protocol_file : protocol_files test_source, client_header, server_header, - code - ], - link_args: extra_linker_flags, + code, + ] + dep_code, dependencies: libwayland, c_args: [ '-std=c99', @@ -129,9 +149,8 @@ foreach protocol_file : protocol_files test_source, client_header, server_header, - ], - link_args: extra_linker_flags, - dependencies: libwayland, + ] + dep_code, + dependencies: libwayland, cpp_args: [ '-Wall', '-Werror', diff --git a/local/recipes/wayland/wayland-protocols/source/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml b/local/recipes/wayland/wayland-protocols/source/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml index 9c513a68ca..824e8737c0 100644 --- a/local/recipes/wayland/wayland-protocols/source/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml @@ -1,5 +1,29 @@ + + Copyright © 2015, 2021 Red Hat Inc. + + 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. + @@ -61,7 +85,7 @@ - + A swipe gesture object notifies a client about a multi-finger swipe gesture detected on an indirect input device such as a touchpad. @@ -124,7 +148,7 @@ - + A pinch gesture object notifies a client about a multi-finger pinch gesture detected on an indirect input device such as a touchpad. diff --git a/local/recipes/wayland/wayland-protocols/source/unstable/text-input/text-input-unstable-v3.xml b/local/recipes/wayland/wayland-protocols/source/unstable/text-input/text-input-unstable-v3.xml index 1fae54d7ba..01c1e21042 100644 --- a/local/recipes/wayland/wayland-protocols/source/unstable/text-input/text-input-unstable-v3.xml +++ b/local/recipes/wayland/wayland-protocols/source/unstable/text-input/text-input-unstable-v3.xml @@ -47,7 +47,7 @@ interface version number is reset. - + The zwp_text_input_v3 interface represents text input and input methods associated with a seat. It provides enter/leave events to follow the @@ -89,16 +89,15 @@ Requests text input on the surface previously obtained from the enter event. - This request must be issued every time the active text input changes + This request must be issued every time the focused text input changes to a new one, including within the current surface. Use zwp_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. + Requests to enable a text input when another text input is enabled + on the same seat 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 @@ -211,6 +210,15 @@ + + + @@ -274,6 +282,19 @@ 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. + + As of version 2, the zwp_text_input_v3.commit request does not apply + values sent with this request. Instead, it stores them in a separate + "committed" area. The committed values, if still valid, get applied on + the next wl_surface.commit request on the surface with text-input focus. + Both committed and applied values get invalidated on: + + - the next committed enable or disable request, or + - a change of the focused surface of the text-input (leave or enter events). + + This double stage application allows the compositor to position + the input method popup in the same frame as the contents + of the text on the surface are updated. @@ -404,8 +425,10 @@ Instruct the application to apply changes to state requested by the - preedit_string, commit_string and delete_surrounding_text events. The - state relating to these events is double-buffered, and each one + 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. @@ -418,6 +441,7 @@ 4. Calculate surrounding text to send. 5. Insert new preedit text in cursor position. 6. Place cursor inside preedit text. + 7. Perform the requested action. The serial number reflects the last state of the zwp_text_input_v3 object known to the compositor. The value of the serial argument must @@ -433,9 +457,132 @@ + + + + + + + + + A possible action to perform on a text input. + + The submit action is intended for input entries that expect some sort of + activation after user interaction, e.g. the URL entry in a browser. + + + + + + + + An action was performed on this text input. + + Values set with this event are double-buffered. They must be applied + and reset to initial on the next zwp_text_input_v3.done event. + + The initial value of action is none. + + + + + + + + Notify the application of language used by the input method. + + This event will be sent on creation if known and for all subsequent changes. + + The language should be specified as an IETF BCP 47 tag. + Setting an empty string will reset any known language back to the default unknown state. + + + + + + + Set the actions available for this text input. + + Values set with this request are double-buffered. They will get applied + on the next zwp_text_input_v3.commit request. + + If the available_actions array contains the none action, or contains the + same action multiple times, the compositor must raise the invalid_action + protocol error. + + Initially, no actions are available. + + + + + + + Requests an input panel to be shown (e.g. a on-screen keyboard). + + This request only hints the desired interaction pattern from the + client side, and its effect may be ignored by compositors given + other environmental factors. Repeated calls will be ignored. + + + + + + Requests an input panel to be hidden. + + This request only hints the desired interaction pattern from the + client side, and its effect may be ignored by compositors given + other environmental factors. Repeated calls will be ignored. + + + + + + Style hints for the preedit string. + + + + + + + + + + + + + Notify of contextual hints for the pre-edit string. This + event is always sent together with a zwp_text_input_v3.preedit_string + event. + + The parameters start and end are counted in bytes relative to the + beginning of the text buffer submitted through + zwp_text_input_v3.preedit_string, and represent the substring in the + pre-edit text affected by the hint. + + Multiple events may be submitted if the preedit string has different + sections. The extent of hints may overlap. The parts of the preedit + string that are not covered by any zwp_text_input_v3.preedit_hint event, + the text will be considered unhinted. This is also the case if no + preedit_hint event is sent. + + Clients should provide recognizable visuals to these hints. if they are + unable to comply with this requisition, it may be preferable for them + keep the preedit_shown content hint disabled. + + Values set with this event are double-buffered. They must be applied + and reset on the next zwp_text_input_v3.done event. + + + + + - + A factory for text-input objects. This object is a global singleton. diff --git a/local/recipes/wayland/wayland-protocols/source/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml b/local/recipes/wayland/wayland-protocols/source/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml index 82ca247c74..023589ad04 100644 --- a/local/recipes/wayland/wayland-protocols/source/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml +++ b/local/recipes/wayland/wayland-protocols/source/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml @@ -23,7 +23,7 @@ DEALINGS IN THE SOFTWARE. - + This interface allows a compositor to announce support for server-side decorations. @@ -60,18 +60,33 @@ Create a new decoration object associated with the given toplevel. - Creating an xdg_toplevel_decoration from an xdg_toplevel which has a - buffer attached or committed is a client error, and any attempts by a - client to attach or manipulate a buffer prior to the first - xdg_toplevel_decoration.configure event must also be treated as - errors. + For objects of version 1, creating an xdg_toplevel_decoration from an + xdg_toplevel which has a buffer attached or committed is a client + error, and any attempts by a client to attach or manipulate a buffer + prior to the first xdg_toplevel_decoration.configure event must also be + treated as errors. + + For objects of version 2 or newer, creating an xdg_toplevel_decoration + from an xdg_toplevel which has a buffer attached or committed is + allowed. The initial decoration mode of the surface if a buffer is + already attached depends on whether a xdg_toplevel_decoration object + has been associated with the surface or not prior to this request. + + If an xdg_toplevel_decoration was associated with the surface, then + destroyed without a surface commit, the previous decoration mode is + retained. + + If no xdg_toplevel_decoration was associated with the surface prior to + this request, or if a surface commit has been performed after a previous + xdg_toplevel_decoration object associated with the surface was + destroyed, the decoration mode is assumed to be client-side. - + The decoration object allows the compositor to toggle server-side window decorations for a toplevel surface. The client can request to switch to @@ -94,7 +109,8 @@ Switch back to a mode without any server-side decorations at the next - commit. + commit, unless a new xdg_toplevel_decoration is created for the surface + first. diff --git a/local/recipes/wayland/wayland-protocols/source/wayland-protocols-uninstalled.pc.in b/local/recipes/wayland/wayland-protocols/source/wayland-protocols-uninstalled.pc.in deleted file mode 100644 index cf7adf257a..0000000000 --- a/local/recipes/wayland/wayland-protocols/source/wayland-protocols-uninstalled.pc.in +++ /dev/null @@ -1,5 +0,0 @@ -pkgdatadir=@abs_top_srcdir@ - -Name: Wayland Protocols -Description: Wayland protocol files (not installed) -Version: @WAYLAND_PROTOCOLS_VERSION@ diff --git a/local/recipes/wayland/wayland-protocols/source/wayland-protocols.pc.in b/local/recipes/wayland/wayland-protocols/source/wayland-protocols.pc.in deleted file mode 100644 index 4571fa8180..0000000000 --- a/local/recipes/wayland/wayland-protocols/source/wayland-protocols.pc.in +++ /dev/null @@ -1,7 +0,0 @@ -prefix=@prefix@ -datarootdir=@datarootdir@ -pkgdatadir=${pc_sysrootdir}${datarootdir}/@PACKAGE@ - -Name: Wayland Protocols -Description: Wayland protocol files -Version: @WAYLAND_PROTOCOLS_VERSION@