vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wayland-protocols: sync tracked source tree to 1.49

Browse Source 
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, ...).
This commit is contained in:
vasilito
2026-07-20 09:02:21 +09:00
parent 6dab9b2953
commit 68a8164a3e
60 changed files with 7760 additions and 454 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/recipes/wayland/wayland-protocols/source/.gitlab-ci.yml
+2 -2
View File
@@ -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:
local/recipes/wayland/wayland-protocols/source/.gitlab-ci/debian-install.sh
+1 -1
View File
@@ -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
local/recipes/wayland/wayland-protocols/source/GOVERNANCE.md
+132 -30
View File
@@ -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.
local/recipes/wayland/wayland-protocols/source/MEMBERS.md
+5 -1
View File
@@ -3,7 +3,8 @@
- GTK/Mutter: Jonas Ådahl <jadahl@gmail.com> (@jadahl),
Carlos Garnacho <carlosg@gnome.org> (@carlosg)
- KWin: Vlad Zahorodnii <vlad.zahorodnii@kde.org> (@zzag),
David Edmundson <david@davidedmundson.co.uk> (@davidedmundson)
David Edmundson <david@davidedmundson.co.uk> (@davidedmundson),
Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)
- mesa: Daniel Stone <daniel@fooishbar.org> (@daniels),
Mike Blumenkrantz <michael.blumenkrantz@gmail.com> (@zmike)
- Mir: Christopher James Halse Rogers <raof@ubuntu.com> (@RAOF),
@@ -15,3 +16,6 @@
Derek Foreman <derek.foreman@collabora.com> (@derekf)
- wlroots/Sway: Simon Ser <contact@emersion.fr> (@emersion),
Simon Zeni <simon@bl4ckb0ne.ca> (@bl4ckb0ne)
- Chromium: Fangzhou Ge <fangzhoug@chromium.org> (@fangzhoug),
Nick Yamane <nickdiego@igalia.com> (@nickdiego),
Max Ihlenfeldt <max@igalia.com> (@mihlenfeldt)
local/recipes/wayland/wayland-protocols/source/README.md
+88 -51
View File
@@ -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
local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/README
+4
View File
@@ -0,0 +1,4 @@
xx cutouts protocol
Maintainers:
Guido Günther <agx@sigxcpu.org>
local/recipes/wayland/wayland-protocols/source/experimental/xx-cutouts/xx-cutouts-v1.xml
+232
View File
@@ -0,0 +1,232 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xx_cutouts_unstable_v1">
<copyright>
Copyright © 2026 Phosh.mobi e.V.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Warning! The protocol described in this file is currently in the
experimental phase. Backwards incompatible major versions of the protocol
are to be expected. Exposing this protocol without an opt-in mechanism is
discouraged.
</copyright>
<description summary="Protocol to describe cut out surface regions">
This protocol describes the areas of a toplevel that are cut out
of the available surface area by hardware elements present in the
physical display. This allows clients to avoid placing user interface
elements in those areas.
Typical cutout areas are notches (i.e. embedding a camera) or
"waterfall" display edges. In the case of a notch the compositor
would usually supply the bounding box of the notch or an
approximation by multiple rectangles. Thus a single physical
element in the display can correspond to multiple cutout events in
the protocol.
The protocol currently supports xdg_toplevel surfaces but is meant
to be extended to other surfaces (like layer surfaces) in the
future.
Warning! The protocol described in this file is experimental and
backward incompatible changes may be made. Backward compatible
changes may be added together with the corresponding interface
version bump. Backward incompatible changes can only be done by
creating a new major version of the extension.
</description>
<interface name="xx_cutouts_manager_v1" version="1">
<description summary="Display cutouts area manager">
This interface allows a compositor to announce support for
supplying cutout information to the client.
</description>
<enum name="error">
<entry name="invalid_role" value="0" summary="given wl_surface has incorrect role"/>
<entry name="defunct_cutouts_object" value="1"
summary="wl_surface or surface role was destroyed before the cutouts object"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the xx_cutouts_manager object">
Using this request a client can tell the server that it is not
going to use the xx_cutouts_manger object anymore.
Any objects already created through this instance are not affected.
</description>
</request>
<request name="get_cutouts">
<description summary="create a cutout notifier from a xdg toplevel">
This creates a new xx_cutouts object for the given
surface. The role of the surface must be xdg_toplevel
otherwise an invalid_role protocol error will be raised. Later
versions of this protocol might allow for other surface roles.
</description>
<arg name="id" type="new_id" interface="xx_cutouts_v1"/>
<arg name="surface" type="object" interface="wl_surface"/>
</request>
</interface>
<interface name="xx_cutouts_v1" version="1">
<description summary="cutout regions information">
An xx_cutouts describes the areas currently "cut out" of a
toplevel.
Each cutout event carries an id that identifies the
physical element. If the compositor describes an element by
multiple cutout events these should use the same element
id. A typical example is a curved notch that is approximated
by several cutout_box elements. Using the same element
id allows the client to identify that these belong to the
same physical object. Ids are only valid during one configure
sequence. No guarantee is given that the same id identifies
the same element in different configure sequences.
Typically compositors would only send cutout information when
the toplevel enters fullscreen or maxmized state (as specified
in the xdg_shell protocol).
The xx_cutouts_v1 object must be destroyed before its
underlying xdg_toplevel and wl_surface. Otherwise the
defunct_cutouts_object protocol error will be send.
</description>
<enum name="type">
<description summary="Cutout type">
These values indicate the type of cutout. The information is
meant to help clients to decide whether they can possibly
ignore the element.
</description>
<entry name="cutout" value="0">
<description summary="A generic cutout">
This element type can be used by the compositor if it
doesn't want to provide a more specific type.
</description>
</entry>
<entry name="notch" value="1">
<description summary="Small functional cutout area">
A functional, irregular shape on one of the device's
edges. It often contains a camera.
</description>
</entry>
<entry name="waterfall" value="2">
<description summary="A curved display edge">
A curved display edge intended to make the device appear
like not having any bezel.
</description>
</entry>
</enum>
<enum name="corner_position">
<description summary="Corner position">
The position of a corner on a surface
</description>
<entry name="top_left" value="0"/>
<entry name="top_right" value="1"/>
<entry name="bottom_right" value="2"/>
<entry name="bottom_left" value="3"/>
</enum>
<enum name="error">
<entry name="invalid_element_id" value="0"
summary="Invalid element id in a set_unhandled request"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the xx_cutouts object">
Using this request a client can tell the server that it is not
going to use the xx_cutouts object anymore.
</description>
</request>
<event name="cutout_box">
<description summary="A rectangular cutout region">
The cutout_box event describes a rectangular cutout area in
surface-local coordinates.
This can be an approximation of e.g. a circular camera notch.
</description>
<arg name="x" type="int"
summary="x coordinate of the box's top left corner"/>
<arg name="y" type="int"
summary="y coordinate of the box's top left corner"/>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
<arg name="type" type="uint" enum="type" summary="The type of cutout"/>
<arg name="id" type="uint" summary="An identifier identifying the physical element"/>
</event>
<event name="cutout_corner">
<description summary="A cutout corner">
The cutout_corner event describes a rounded corner in
surface-local coordinates. The area towards the screen edge is
the cutout corner part.
</description>
<arg name="position" type="uint" enum="corner_position" summary="The position of the described corner"/>
<arg name="radius" type="uint" summary="The corner's radius"/>
<arg name="id" type="uint" summary="An identifier identifying the physical element"/>
</event>
<event name="configure">
<description summary="notify cutout changes">
The configure event marks the end of a configure sequence. A
configure sequence is a set of zero or more cutout events and
the final xx_cutout.configure event.
In the case of a xdg_toplevel clients should arrange their
surface for the new cutouts, and then send an
xdg_surface.ack_configure request at some point before
committing the new surface. See xdg_surface.configure and
xdg_surface.ack_configure in the xdg_shell protocol for
details.
If the cutout sequence consists of only a configure event and
contains no cutout or corner events this indicates that the
surface isn't overlapping with any cutouts or corners.
If the client receives multiple configure events before it can
respond to one, it is free to discard all but the last event
it received.
</description>
</event>
<request name="set_unhandled">
<description summary="Notify about unhandled cutouts">
If a client doesn't handle one or more cutouts in the to be
acked sequence, it can add their element's id to the
unhandled array. The compositor might then try to reposition
the surface in a way that avoids these elements in a future
configure sequence.
The request (if used) must be sent before acking the configure
sequence. State set with this request is double-buffered. It
will get applied on the next ack_configure and stay valid
until the next configure event.
</description>
<arg name="unhandled" type="array" summary="array of unhandled element ids"/>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/README
+4
View File
@@ -0,0 +1,4 @@
xx fractional scale v2 protocol
Maintainers:
Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)
local/recipes/wayland/wayland-protocols/source/experimental/xx-fractional-scale/xx-fractional-scale-v2.xml
+128
View File
@@ -0,0 +1,128 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xx_fractional_scale_v2">
<copyright>
Copyright © 2022 Xaver Hugl
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="Protocol for fractional scaling">
This protocol allows compositors and clients to communicate the
coordinate space their surfaces act in.
</description>
<interface name="xx_fractional_scale_manager_v2" version="1">
<description summary="creates surface scale interfaces">
A global interface to create xx_fractional_scale_v2 interfaces.
</description>
<request name="destroy" type="destructor">
<description summary="release the global">
Informs the server that the client will not be using this protocol
object anymore. This does not affect any other objects.
</description>
</request>
<enum name="error">
<entry name="fractional_scale_exists" value="0"
summary="xx_fractional_scale_v2 for the surface already exists"/>
</enum>
<request name="get_fractional_scale">
<description summary="create an interface to enable fractional scaling">
Create an interface object for a wl_surface to communicate scale.
If the given wl_surface already has a xx_fractional_scale_v2 object
associated, the fractional_scale_exists protocol error is raised.
</description>
<arg name="id" type="new_id" interface="xx_fractional_scale_v2"
summary="the new scale interface"/>
<arg name="surface" type="object" interface="wl_surface"
summary="the surface"/>
</request>
</interface>
<interface name="xx_fractional_scale_v2" version="1">
<description summary="interface for fractional scaling">
An additional interface for a wl_surface object that allows compositor and
client to communicate in a different coordinate space, in order to enable
them to accurately describe coordinates and sizes in pixels.
The two coordinate spaces in consideration are logical and pixels, where
logical coordinates describe the size content should have and pixels
describe the size of buffers.
A scale of one equals a lack of scaling, where the communicated values
define both logical coordinates and pixels.
A scale greater than one describes that for every logical coordinate,
more than one pixel is used, and a scale less than one describes that
multiple logical coordinates make up one pixel.
In mathematical terms, logical coordinates can be obtained by dividing
the provided values by the currently active scale.
The initial compositor and client coordinate scale factors are 1.
</description>
<event name="scale_factor">
<description summary="set the compositor coordinate space scale factor">
This event sets a scale factor for the associated wl_surface that
describes the coordinate system the compositor will use for events
following xx_fractional_scale_v2.scale_factor.
The scale factor is encoded in a 8.24 fixed point format.
The compositor must not send a scale of zero.
The client should re-render and commit a new buffer with the new scale
as soon as possible, in order to avoid artifacts caused by the mismatch
in compositor and client scales.
</description>
<arg name="scale_8_24" type="uint" summary="surface scale factor"/>
</event>
<request name="set_scale_factor">
<description summary="set the client coordinate space scale factor">
This request sets a scale factor for the associated wl_surface that
describes the coordinate system the client uses for requests following
xx_fractional_scale_v2.set_scale_factor.
The scale factor is encoded in a 8.24 fixed point format.
If this scale factor does not match the scale factor provided by the
compositor with xx_fractional_scale_v2.scale_factor, the compositor may
apply transformations to the wl_surface that can result in blurriness
or other artifacts.
If scale_8_24 is zero, the error invalid_scale will be raised.
</description>
<arg name="scale_8_24" type="uint" summary="surface scale factor"/>
</request>
<request name="destroy" type="destructor">
<description summary="remove the scale interface from the surface">
The wl_surface's xx_fractional_scale_v2 object is destroyed, and the
associated scale is reset to 1.
</description>
</request>
<enum name="error">
<entry name="invalid_scale" value="0"
summary="scale value is not valid"/>
</enum>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/README
+4
View File
@@ -0,0 +1,4 @@
Input method protocol
Maintainers:
Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>
local/recipes/wayland/wayland-protocols/source/experimental/xx-input-method/xx-input-method-v2.xml
+948
View File
@@ -0,0 +1,948 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="input_method_experimental_v2">
<copyright>
Copyright © 2008-2011 Kristian Høgsberg
Copyright © 2010-2011 Intel Corporation
Copyright © 2012-2013 Collabora, Ltd.
Copyright © 2012, 2013 Intel Corporation
Copyright © 2015, 2016 Jan Arne Petersen
Copyright © 2017, 2018 Red Hat, Inc.
Copyright © 2018 Purism SPC
Copyright © 2025 DorotaC
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="Protocol for creating input methods">
This protocol allows applications to act as input methods for compositors.
An input method context is used to manage the state of the input method.
Text strings are UTF-8 encoded, their indices and lengths are in bytes.
This document adheres to the RFC 2119 when using words like "must",
"should", "may", etc.
Warning! The protocol described in this file is currently in the
experimental phase. Backwards incompatible major versions of the
protocol are to be expected. Exposing this protocol without an opt-in
mechanism is discouraged.
</description>
<interface name="xx_input_method_v1" version="4">
<description summary="input method">
An input method object allows for clients to compose text.
The objects connects the client to a text input in an application, and
lets the client to serve as an input method for a seat.
The xx_input_method_v1 object can occupy two distinct states: active and
inactive. In the active state, the object is associated to and
communicates with a text input. In the inactive state, there is no
associated text input, and the only communication is with the compositor.
Initially, the input method is in the inactive state.
Requests issued in the inactive state must be accepted by the compositor.
Because of the serial mechanism, and the state reset on activate event,
they will not have any effect on the state of the next text input.
There must be no more than one input method object per seat.
</description>
<enum name="error">
<entry name="surface_has_role" value="0x0" summary="surface already has a role"/>
<entry name="inactive" value="0x1" summary="operation requires the input method to be active"/>
</enum>
<event name="activate">
<description summary="input method has been requested">
Notification that a text input focused on this seat requested the input
method to be activated.
This event serves the purpose of providing the compositor with an
active input method.
This event resets all state associated with previous
surrounding_text, text_change_cause, and content_type events, as well
as the state associated with set_preedit_string, commit_string, and
delete_surrounding_text requests, and destroys any existing input_popup_surface objects.
In addition, it marks the xx_input_method_v1 object as active.
The surrounding_text, and content_type events must follow before the
next done event if the text input supports the respective
functionality.
State set with this event is double-buffered. It will get applied on
the next xx_input_method_v1.done event, and stay valid until changed.
</description>
</event>
<event name="deactivate">
<description summary="deactivate event">
Notification that no focused text input currently needs an active
input method on this seat.
This event marks the xx_input_method_v1 object as inactive.
compositor must destroy all existing xx_input_popup_surface_v2 objects.
This event resets all state associated with previous
surrounding_text, text_change_cause, and content_type events, as well
as the state associated with set_preedit_string, commit_string, and
delete_surrounding_text requests.
State set with this event is double-buffered. It will get applied on
the next xx_input_method_v1.done event, and stay valid until changed.
</description>
</event>
<event name="surrounding_text">
<description summary="surrounding text event">
Updates the surrounding plain text around the cursor, excluding the
preedit text.
If any preedit text is present, it is replaced with the cursor for the
purpose of this event.
The argument text is a buffer containing the preedit string, and must
include the cursor position, and the complete selection. It should
contain additional characters before and after these. There is a
maximum length of wayland messages, so text can not be longer than 4000
bytes.
cursor is the byte offset of the cursor within the text buffer.
anchor is the byte offset of the selection anchor within the text
buffer. If there is no selected text, anchor must be the same as
cursor.
If this event does not arrive before the first done event, the input
method may assume that the text input does not support this
functionality and ignore following surrounding_text events.
Values set with this event are double-buffered. They will get applied
and set to initial values on the next xx_input_method_v1.done
event.
The initial state for affected fields is empty, meaning that the text
input does not support sending surrounding text. If the empty values
get applied, subsequent attempts to change them may have no effect.
</description>
<arg name="text" type="string"/>
<arg name="cursor" type="uint"/>
<arg name="anchor" type="uint"/>
</event>
<event name="text_change_cause">
<description summary="indicates the cause of surrounding text change">
Tells the input method why the text surrounding the cursor changed.
Whenever the client detects an external change in text, cursor, or
anchor position, it must issue this request to the compositor. This
request is intended to give the input method a chance to update the
preedit text in an appropriate way, e.g. by removing it when the user
starts typing with a keyboard.
cause describes the source of the change.
The value set with this event is double-buffered. It will get applied
and set to its initial value on the next xx_input_method_v1.done
event.
The initial value of cause is input_method.
</description>
<arg name="cause" type="uint" enum="xx_text_input_v3.change_cause"/>
</event>
<event name="content_type">
<description summary="content purpose and hint">
Indicates the content type and hint for the current
xx_input_method_v1 instance.
Values set with this event are double-buffered. They will get applied
on the next xx_input_method_v1.done event.
They get reset to initial on the next committed deactivate event.
The initial value for hint is none, and the initial value for purpose
is normal.
</description>
<arg name="hint" type="uint" enum="xx_text_input_v3.content_hint"/>
<arg name="purpose" type="uint" enum="xx_text_input_v3.content_purpose"/>
</event>
<event name="set_available_actions" since="3">
<description summary="announce the available actions">
Announces the actions available for the currently active text input.
Values set with this event are double-buffered. They will get applied
on the next .done event.
They get reset to the initial value on the next committed deactivate event.
The initial value is an empty set: no actions are available.
Values in the available_actions array come from text-input-v3.action.
</description>
<arg name="available_actions" type="array" summary="available actions"/>
</event>
<event name="announce_supported_features" since="3">
<description summary="announce extra supported features">
Notifies the input method what the currently active text input client is able to do.
This event should come within the same .done sequence as .activate. Otherwise, the input method may ignore it.
Values set with this event are double-buffered. They will get applied
on the next .done event.
They get reset to initial on the next committed deactivate event.
The initial value for features is none.
</description>
<arg name="features" type="uint" enum="xx_text_input_v3.supported_features"/>
</event>
<enum name="protocol_compat" since="4">
<description summary="protocol compatibility value">
Tells the input method client what kinds of events the text input client supports.
</description>
<entry name="text_input_v3" value="0x0" summary="zwp-text-input-v3 semantics"/>
<entry name="xx_text_input" value="0x1">
<description summary="xx-text-input semantics">
Changes the meaning of serial compared to v3.
The text input client now applies requested updates on a "best-effort" basis.
</description>
</entry>
<!-- This doesn't need disambiguating. Both protocols are pdated in lockstep, and the compositor should implement both protocols to the current version. By the experimental protocols contract, every version bump is breaking compatibility. -->
</enum>
<event name="announce_protocol_compat" since="3">
<description summary="set text input's compatibility level">
Tells the input method client what kinds of events the text input client supports.
<!-- While text input protocols and input method protocols are updated in lockstep, nobody knows what versions of either will end up on a user's computer. Old input method with new apps? New input method with old apps?
To limit the scope for now, let's assume the user always keeps the input method up to date, and uses old apps. -->
Values set with this event are double-buffered. They will get applied
on the next .done event.
They get reset to initial on the next committed deactivate event.
The compositor may send this event as part of a .done chain that switches the active state from inactive to active. It must not send this event otherwise.
The initial value for version is text_input_v3.
</description>
<arg name="compat_level" type="uint" enum="protocol_compat"/>
</event>
<event name="done">
<description summary="apply state">
Atomically applies state changes recently sent to the client.
The done event establishes and updates the state of the client, and
must be issued after any changes to apply them.
Text input state (content purpose, content hint, surrounding text, and
change cause) is conceptually double-buffered within an input method
context.
Events modify the pending state, as opposed to the current state in use
by the input method. A done event atomically applies all pending state,
replacing the current state. After done, the new pending state is as
documented for each related request.
Events must be applied in the order of arrival.
Neither current nor pending state are modified unless noted otherwise.
</description>
</event>
<request name="perform_action" since="3">
<description summary="perform action">
Perform an action on this text input.
Values set with this event are double-buffered. They must be applied
and reset to initial on the next commit request.
The initial value of action is none.
</description>
<arg name="action" type="uint" enum="xx_text_input_v3.action" summary="action to perform"/>
</request>
<request name="commit_string">
<description summary="commit string">
Send the commit string text for insertion to the application.
Inserts a string at current cursor position (see commit event
sequence). The string to commit could be either just a single character
after a key press or the result of some composing.
The argument text is a buffer containing the string to insert. There is
a maximum length of wayland messages, so text can not be longer than
4000 bytes.
Values set with this request are double-buffered. They must be applied
and reset to initial on the next .commit request.
The initial value of text is an empty string.
</description>
<arg name="text" type="string"/>
</request>
<request name="set_preedit_string">
<description summary="pre-edit string">
Send the pre-edit string text to the application text input.
Place a new composing text (pre-edit) at the current cursor position.
Any previously set composing text must be removed. Any previously
existing selected text must be removed. The cursor is moved to a new
position within the preedit string.
The argument text is a buffer containing the preedit string. There is
a maximum length of wayland messages, so text can not be longer than
4000 bytes.
The arguments cursor_begin and cursor_end are counted in bytes relative
to the beginning of the submitted string buffer. Cursor should be
hidden by the text input when both are equal to -1.
cursor_begin indicates the beginning of the cursor. cursor_end
indicates the end of the cursor. It may be equal or different than
cursor_begin.
Values set with this request are double-buffered. They must be applied on
the next xx_input_method_v1.commit request.
They must be reset to initial on the next committed .deactivate event.
The initial value of text is an empty string. The initial value of
cursor_begin, and cursor_end are both 0.
</description>
<arg name="text" type="string"/>
<arg name="cursor_begin" type="int"/>
<arg name="cursor_end" type="int"/>
</request>
<request name="delete_surrounding_text">
<description summary="delete text">
Remove the surrounding text.
before_length and after_length are the number of bytes before and after
the current cursor index (excluding the preedit text) to delete.
If text is selected, it must be deleted.
If indices exceed the available text boundaries, they should be adjusted to fit in boundaries and deletion reattempted.
If indices do not lie on byte boundaries, then the text input client should delete at least that many bytes. In this case, the client decides the end point, but a character boundary same as when deleting using the keyboard is recommended.
If any preedit text is present, it is replaced with the cursor for the
purpose of this event. In effect before_length is counted from the
beginning of preedit text, and after_length from its end (see commit
event sequence).
Values set with this request are double-buffered. They must be applied
and reset to initial on the next xx_input_method_v1.commit request.
The initial values of both before_length and after_length are 0.
</description>
<arg name="before_length" type="uint"/>
<arg name="after_length" type="uint"/>
</request>
<request name="move_cursor" since="3">
<description summary="move cursor and change selection">
Unselects text, moves the cursor and selects text.
This is equivalent to dragging the mouse over some text: it deselects whatever might be currently selected and selects a new range of text.
The offsets used in arguments are in bytes relative to the current cursor position. Cursor is the new position of the cursor, and anchor is the opposite end of selection. If there's no selection, anchor should be equal to cursor.
The offsets do not take preedit contents into account, nor is preedit changed in any way with this request.
Both cursor and anchor must fall on code point boundaries, otherwise text input client may ignore the request. It is therefore not recommended for an input method to move any of them beyond the text received in surrounding_text.
When surrounding_text is not supported, the offsets must not be interpreted as bytes, but as some human-readable unit at least as big as a code point, for example a grapheme.
The cursor and anchor arguments can also take the following special values:
BEGINNING := 0x8000_0000 = i32::MIN
END := 0x7fff_ffff = i32::MAX
meaning, respectively, the beginning and the end of of all text in the input field.
Values set with this event are double-buffered. They must be applied
and reset to initial on the next commit request.
The initial values of both cursor and anchor are 0.
</description>
<arg name="cursor" type="int"/>
<arg name="anchor" type="int"/>
</request>
<request name="commit">
<description summary="apply state">
Apply state changes from commit_string, set_preedit_string and
delete_surrounding_text requests.
The state relating to these events is double-buffered, and each one
modifies the pending state. This request replaces the current state
with the pending state.
The connected text input is expected to proceed by evaluating the
changes in the following order:
1. Replace existing preedit string with the cursor.
2. Delete requested surrounding text.
3. Insert commit string with the cursor at its end.
4. Move the cursor and selection.
5. Calculate surrounding text to send.
6. Insert new preedit text in cursor position.
7. Place cursor inside preedit text.
8. Perform the requested action.
Note that the input method can not receive more than 4000 bytes of selection text, which might be the case for example when the entire document is selected. Nevertheless, the text input must delete the entire selected range before inserting the commit string.
Serial handling with protocol_compat == xx_text_input
The serial number should be set to 0.
Serial handling with protocol_compat == text_input_v3
The serial number reflects the last state of the xx_input_method_v1
object known to the client. The value of the serial argument must be
equal to the number of done events already issued by that object. When
the compositor receives a commit request with a serial different than
the number of past done events, it must proceed as normal, except it
should not change the current state of the xx_input_method_v1 object.
</description>
<arg name="serial" type="uint"/>
</request>
<request name="get_input_popup_surface" since="2">
<description summary="create popup surface">
Creates a new xx_input_popup_surface_v2 object wrapping a given
surface.
The surface gets assigned the "input_popup" role. If the surface
already has an assigned role, the compositor must issue a protocol
error.
Issuing this request before receiving a committed .activate causes the "inactive" error.
</description>
<arg name="id" type="new_id" interface="xx_input_popup_surface_v2"/>
<arg name="surface" type="object" interface="wl_surface"/>
<arg name="positioner" type="object" interface="xx_input_popup_positioner_v1"/>
</request>
<event name="unavailable">
<description summary="input method unavailable">
The input method ceased to be available.
The compositor must issue this event as the only event on the object if
there was another input_method object associated with the same seat at
the time of its creation.
The compositor must issue this request when the object is no longer
usable, e.g. due to seat removal.
The input method context becomes inert and should be destroyed after
deactivation is handled. Any further requests and events except for the
destroy request must be ignored.
</description>
</event>
<request name="destroy" type="destructor">
<description summary="destroy the input method">
Destroys the xx_input_method_v1 object and any associated child
objects.
</description>
</request>
</interface>
<interface name="xx_input_popup_surface_v2" version="1">
<description summary="popup surface">
An input method popup surface is a short-lived, temporary surface.
It is meant as an area to show suggestions, candidates, or for other input-related uses.
The compositor should anchor it at the active text input cursor area.
The client must call wl_surface.commit on the corresponding wl_surface
for input_popup_surface state updates to take effect, unless otherwise noted.
After the initial wl_surface.commit, the compositor must reply with a configure sequence (see .start_configure) initializing all the compositor-provided state of the popup. That means providing values for:
- width
- height
- anchor_x
- anchor_y
- anchor_width
- anchor_height
- serial
using the appropriate events.
The popup will only be presented to the user after the client receives the configure sequence and replies with .ack_configure.
An example init sequence could look like this:
1. client (Cl): popup = input_method.get_popup(wl_surface, positioner)
2. Cl: wl_surface.commit()
3. compositor (Co): popup.start_configure(150, 150, 10, -2, 5, 30)
5. Co: input_method.done()
6. Cl: ack_configure()
7. Cl: wl_surface.commit()
A newly created input_popup_surface will be stacked on top of all previously created
input_popup_surfaces associated with the same text input.
A typical sequence resulting from the user selecting a new text field and typing some text:
1. compositor (Co): input_method.activate()
2. Co: input_method.done()
3. [init sequence]
4. Co: input_method.set_surrounding_text("new text")
5. Co: popup.start_configure(150, 150, -60, -2, 55, 30)
6. Co: input_method.done()
7. client (Cl): ack_configure()
8. Cl: wl_surface.commit()
When the corresponding input_method receives a committed .deactivate event, the popup gets destroyed and becomes invalid and its surface gets unmapped.
The client must not destroy the underlying wl_surface while the
xx_input_popup_surface_v2 object exists.
</description>
<enum name="error">
<entry name="invalid_serial" value="0" summary="received acknowledgement for a serial which has already been acknowledged or has never been issued"/>
</enum>
<event name="start_configure">
<description summary="configure the popup surface">
The start_configure event updates the popup geometry and marks the start of a configure sequence.
The anchor_* arguments represent the geometry of the anchor to which the popup was attached, relative to the upper left corner of the
popup's surface. Note that this makes anchor_x, anchor_y the reverse of the what they represent in xdg_popup.
A configure sequence is a set of one or more events configuring the state of the
input_popup_surface, starting with this event and ending with input_method.done. After the input_method.done event, the configure sequence is considered submitted.
State set by event in a configure sequence is conceptually double-buffered.
Every argument overwrites its previous value. The state change should get applied atomically with the input_method.done ending the sequence, and the value of serial should return to the undefined value.
Events on the input_popup_surface object received outside a configure sequence (while serial is undefined) must be ignored by the client.
A configure sequence shall be sent every time the compositor (re)positions the popup, or the shape of the anchor changes, for example after popup creation, or in response to text being typed and the text cursor moving.
The client may update the surface in response to input_method.done. Unless the popup is destroyed by the input_method.done, the client must reply with
an .ack_configure request with the serial sent in the start_configure event at
some point after the sequence ends and before committing the new surface.
If the client receives multiple configure sequences before it can respond
to one, it is free to discard all but the last event it received.
<!--
This sounds complicated because it is.
There are two semi-dependent states: that of the text input and that of the popup surface(s).
Alternatives:
1. Don't synchronize the state of the popup and the state of the text.
Rejected because every¹ time the pre-edit changes shape there are two events: the .configure for the surface and the .done from the input method.
¹Actually only when the pre-edit is committed. In the current design, changing the pre-edit doesn't get reported to input-method and doesn't cause a .done. A .done gets emitted for the cursor shape change (so on every stroke), so the compositor would be able to filter it out by paying attention to state changes. That would leave double-rendering only in the case of committing the text (surrounding-text changes) or text changing without input causing reposition (collaborative editing). Worth it maybe?
On the other hand, it's not impossible in the future that some other property gets updated on nearly every text change.
2. Complicate some and mandate .done after some .configures
Rejected because the different path for syncing (on .configure or on .done) are difficult to explain and sound like a source of bugs. Also, this ended up needing additional events.
3. Simplify a lot and remove .configure in favor of relying on .done entirely
Rejected because it pulls in .ack_configure after every .done regardless of surface status. Also underspecifed regarding which popup needs to be configured.
-->
</description>
<arg name="width" type="uint" summary="popup width"/>
<arg name="height" type="uint" summary="popup height"/>
<arg name="anchor_x" type="int"
summary="x position relative to anchor geometry"/>
<arg name="anchor_y" type="int"
summary="y position relative to anchor geometry"/>
<arg name="anchor_width" type="uint"
summary="width of the anchor area"/>
<arg name="anchor_height" type="uint"
summary="height of the anchor area"/>
<arg name="serial" type="uint" summary="serial of the configure sequence"/>
</event>
<request name="ack_configure">
<description summary="acknowledge a configure sequence">
This request notifies the compositor that the client updated its surface in response to a configure sequence.
The purpose of this request is to synchronize the updates of the surface geometry with the surface contents.
For example, when the compositor assigns a size larger than previously, the client must fill the additional space before the popup gets displayed to the user with the new size. When the compositor receives .ack_configure, it can proceed to draw the new size.
.ack_configure should be sent after every submitted configure sequence, passing along the serial received in it.
An .ack_configure request is conceptually double-buffered.
Every request overrides the previous one. The request takes effect once the .commit request is sent on the corresponding surface.
If the client receives multiple configure sequences before it
can respond to one, it may acknowledge only the last configure sequence by using its serial in the .ack_configure request.
Committing an .ack_configure request consumes the serial number sent with
the request, as well as serial numbers sent by all configure sequences
submitted on this input_popup_surface prior to the configure sequence referenced by
the committed serial.
Committing this request with a serial that, for this surface, never appeared in a submitted configure sequence, or one that was already committed before, raises an invalid_serial
error.
</description>
<arg name="serial" type="uint" summary="the serial from the configure sequence"/>
</request>
<request name="reposition">
<description summary="recalculate the popup's location">
Reposition an already-mapped popup. The popup will be placed given the
details in the passed input_popup_positioner object.
The request is processed immediately, without the need to issue wl_surface.commit, but the actual repositioning takes place later, after .ack_configure.
The compositor should reply with a configure sequence including:
- input_popup_surface.start_configure,
- input_popup_surface.repositioned, including the token passed in this request.
This will discard any parameters set by the previous positioner.
If multiple .reposition requests are sent before the .repositioned event is submitted as part of a configure sequence, the compositor may ignore all
but the last one.
The new popup position will not take
effect until the corresponding configure sequence is acknowledged by the
client. See input_popup_surface.repositioned for details.
The token itself is opaque, and has no other special meaning.
</description>
<arg name="positioner" type="object" interface="xx_input_popup_positioner_v1"/>
<arg name="token" type="uint" summary="reposition request token"/>
</request>
<event name="repositioned">
<description summary="signal the completion of a reposition request">
The compositor sends the .repositioned event in response to the .reposition request to notify about its completion.
The new geometry of the popup can be communicated using additional events within a configure sequence including:
- input_popup_surface.start_configure, and
- the .anchor_position event to update the relative position to the anchor.
When responding to a .reposition request, the token argument is the token passed in the that request.
This event is sent as part of a configure sequence.
State set by this event is conceptually double-buffered.
Every argument overwrites its previous value. The state change should get applied atomically with the next input_method.done event.
The client should optionally update the content of the popup, but must
acknowledge the new popup configuration for the new position to take
effect. See input_popup_surface.ack_configure for details.
</description>
<arg name="token" type="uint" summary="reposition request token"/>
</event>
<request name="destroy" type="destructor">
<description summary="remove the popup">
This destroys the popup. Explicitly destroying the input_popup_surface
object will also dismiss the popup, and unmap the surface.
</description>
</request>
</interface>
<interface name="xx_input_popup_positioner_v1" version="1">
<description summary="input method popup positioner">
The input_popup_positioner provides a collection of rules for the placement of an input method popup surface relative to the cursor.
Rules can be defined to ensure
the text input area remains within the visible area's borders, and to
specify how the popup changes its position, such as sliding along
an axis, or flipping around a rectangle. These positioner-created rules are
constrained by the requirement that a popup must intersect with or
be at least partially adjacent to the surface containing the text input.
See the various requests for details about possible rules.
A newly created positioner has the following state:
- 0 surface width
- 0 surface height
- anchor at the center ("none")
- gravity towards the center ("none")
- constraints adjustment set to none
- offset at x = 0, y = 0
- not reactive
Upon receiving a request taking the positioner as an argument, the compositor makes a copy of the rules
specified by the input_popup_positioner. Thus, after the request is complete the
input_popup_positioner object can be destroyed or reused; further changes to the
object will have no effect on previous usages.
For an input_popup_positioner object to be considered complete, its state must contain a non-zero width and height. Passing an incomplete input_popup_positioner object when
positioning a surface raises an invalid_positioner error.
</description>
<enum name="error">
<entry name="invalid_input" value="0" summary="invalid input provided"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the input_popup_positioner object">
Notify the compositor that the positioner will no longer be used.
</description>
</request>
<request name="set_size">
<description summary="set the size of the to-be positioned rectangle">
Set the size of the surface that is to be positioned with the positioner
object. The size is in surface-local coordinates and corresponds to the
window geometry. See xdg_surface.set_window_geometry.
If any dimension is set to zero, the invalid_input error is raised.
</description>
<arg name="width" type="uint" summary="width of positioned rectangle"/>
<arg name="height" type="uint" summary="height of positioned rectangle"/>
</request>
<enum name="anchor">
<entry name="none" value="0" summary="no edge, specifies center"/>
<entry name="top" value="1"/>
<entry name="bottom" value="2"/>
<entry name="left" value="3"/>
<entry name="right" value="4"/>
<entry name="top_left" value="5"/>
<entry name="bottom_left" value="6"/>
<entry name="top_right" value="7"/>
<entry name="bottom_right" value="8"/>
</enum>
<request name="set_anchor">
<description summary="set anchor rectangle anchor">
Defines the anchor point for the anchor rectangle. The specified anchor
is used to derive an anchor point that the popup surface will be
positioned relative to. If a corner anchor is set (e.g. 'top_left' or
'bottom_right'), the anchor point will be at the specified corner;
otherwise, the derived anchor point will be centered on the specified
edge, or in the center of the anchor rectangle if no edge is specified.
</description>
<arg name="anchor" type="uint" enum="anchor"
summary="anchor"/>
</request>
<enum name="gravity">
<entry name="none" value="0" summary="center to center"/>
<entry name="top" value="1"/>
<entry name="bottom" value="2"/>
<entry name="left" value="3"/>
<entry name="right" value="4"/>
<entry name="top_left" value="5"/>
<entry name="bottom_left" value="6"/>
<entry name="top_right" value="7"/>
<entry name="bottom_right" value="8"/>
</enum>
<request name="set_gravity">
<description summary="set surface gravity">
Defines in what direction the surface should be positioned, relative to
the anchor point of the anchor rectangle. If a corner gravity is
specified (e.g. 'bottom_right' or 'top_left'), then the surface
will be placed towards the specified gravity; otherwise, the child
surface will be centered over the anchor point on any axis that had no
gravity specified. If the gravity is not in the ‘gravity’ enum, an
invalid_input error is raised.
</description>
<arg name="gravity" type="uint" enum="gravity"
summary="gravity direction"/>
</request>
<enum name="constraint_adjustment" bitfield="true">
<description summary="constraint adjustments">
The constraint adjustment value define ways the compositor will adjust
the position of the surface, if the unadjusted position would result
in the surface being partly constrained.
Whether a surface is considered 'constrained' is left to the compositor
to determine. For example, the surface may be partly outside the
compositor's defined 'work area', thus necessitating the child surface's
position be adjusted until it is entirely inside the work area.
The adjustments can be combined, according to a defined precedence: 1)
Flip, 2) Slide, 3) Resize.
</description>
<entry name="none" value="0">
<description summary="don't move the surface when constrained">
Don't alter the surface position even if it is constrained on some
axis, for example partially outside the edge of an output.
</description>
</entry>
<entry name="slide_x" value="1">
<description summary="move along the x axis until unconstrained">
Slide the surface along the x axis until it is no longer constrained.
First try to slide towards the direction of the gravity on the x axis
until either the edge in the opposite direction of the gravity is
unconstrained or the edge in the direction of the gravity is
constrained.
Then try to slide towards the opposite direction of the gravity on the
x axis until either the edge in the direction of the gravity is
unconstrained or the edge in the opposite direction of the gravity is
constrained.
</description>
</entry>
<entry name="slide_y" value="2">
<description summary="move along the y axis until unconstrained">
Slide the surface along the y axis until it is no longer constrained.
First try to slide towards the direction of the gravity on the y axis
until either the edge in the opposite direction of the gravity is
unconstrained or the edge in the direction of the gravity is
constrained.
Then try to slide towards the opposite direction of the gravity on the
y axis until either the edge in the direction of the gravity is
unconstrained or the edge in the opposite direction of the gravity is
constrained.
</description>
</entry>
<entry name="flip_x" value="4">
<description summary="invert the anchor and gravity on the x axis">
Invert the anchor and gravity on the x axis if the surface is
constrained on the x axis. For example, if the left edge of the
surface is constrained, the gravity is 'left' and the anchor is
'left', change the gravity to 'right' and the anchor to 'right'.
If the adjusted position also ends up being constrained, the resulting
position of the flip_x adjustment will be the one before the
adjustment.
</description>
</entry>
<entry name="flip_y" value="8">
<description summary="invert the anchor and gravity on the y axis">
Invert the anchor and gravity on the y axis if the surface is
constrained on the y axis. For example, if the bottom edge of the
surface is constrained, the gravity is 'bottom' and the anchor is
'bottom', change the gravity to 'top' and the anchor to 'top'.
The adjusted position is calculated given the original anchor
rectangle and offset, but with the new flipped anchor and gravity
values.
If the adjusted position also ends up being constrained, the resulting
position of the flip_y adjustment will be the one before the
adjustment.
</description>
</entry>
<entry name="resize_x" value="16">
<description summary="horizontally resize the surface">
Resize the surface horizontally so that it is completely
unconstrained.
</description>
</entry>
<entry name="resize_y" value="32">
<description summary="vertically resize the surface">
Resize the surface vertically so that it is completely unconstrained.
</description>
</entry>
</enum>
<request name="set_constraint_adjustment">
<description summary="set the adjustment to be done when constrained">
Specify how the popup should be positioned if the originally intended
position caused the surface to be constrained, meaning at least
partially outside positioning boundaries set by the compositor. The
adjustment is set by constructing a bitmask describing the adjustment to
be made when the surface is constrained on that axis.
If no bit for one axis is set, the compositor will assume that the child
surface should not change its position on that axis when constrained.
If more than one bit for one axis is set, the order of how adjustments
are applied is specified in the corresponding adjustment descriptions.
The default adjustment is none.
</description>
<arg name="constraint_adjustment" type="uint" enum="constraint_adjustment"
summary="bit mask of constraint adjustments"/>
</request>
<request name="set_offset">
<description summary="set surface position offset">
Specify the surface position offset relative to the position of the
anchor on the anchor rectangle and the anchor on the surface. For
example if the anchor of the anchor rectangle is at (x, y), the surface
has the gravity bottom|right, and the offset is (ox, oy), the calculated
surface position will be (x + ox, y + oy). The offset position of the
surface is the one used for constraint testing. See
set_constraint_adjustment.
An example use case is placing a popup menu on top of a user interface
element, while aligning the user interface element of the parent surface
with some user interface element placed somewhere in the popup surface.
</description>
<arg name="x" type="int" summary="surface position x offset"/>
<arg name="y" type="int" summary="surface position y offset"/>
</request>
<request name="set_reactive">
<description summary="continuously reconstrain the surface">
When set reactive, the surface is reconstrained if the conditions used
for constraining changed, e.g. the window containing the text input moved.
Whenever the conditions change and the popup gets reconstrained, a
configure sequence is sent with updated geometry.
</description>
</request>
</interface>
<interface name="xx_input_method_manager_v2" version="4">
<description summary="input method manager">
The input method manager allows the client to become the input method on
a chosen seat.
No more than one input method must be associated with any seat at any
given time.
</description>
<request name="get_input_method">
<description summary="request an input method object">
Request a new input xx_input_method_v1 object associated with a given
seat.
</description>
<arg name="seat" type="object" interface="wl_seat"/>
<arg name="input_method" type="new_id" interface="xx_input_method_v1"/>
</request>
<request name="get_positioner">
<description summary="create a positioner object">
Create a positioner object. A positioner object is used to position
surfaces relative to some parent surface. See the interface description
and xdg_surface.get_popup for details.
</description>
<arg name="id" type="new_id" interface="xx_input_popup_positioner_v1"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy the input method manager">
Destroys the xx_input_method_manager_v2 object.
The xx_input_method_v1 objects originating from it remain valid.
</description>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/README
+4
View File
@@ -0,0 +1,4 @@
Keyboard filter protocol
Maintainers:
Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>
local/recipes/wayland/wayland-protocols/source/experimental/xx-keyboard-filter/xx-keyboard-filter-v1.xml
+178
View File
@@ -0,0 +1,178 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="keyboard_filter_experimental_v1">
<copyright>
Copyright 2018 Mike Blumenkrantz
Copyright 2018 Samsung Electronics Co., Ltd
Copyright 2018 Red Hat Inc.
Copyright 2025 DorotaC
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="filter and intercept keyboard events">
The keyboard_filter protocol allows a client to intercept selected keyboard events and prevent them from reaching the focused surface.
This protocol offers a way to alter events reaching an application without the need to allow generating arbitrary keyboard events.
High-level overview of the interfaces:
The keyboard_filter_manager exposes the bind_to_input_method request which binds a wl_keyboard to an xx_input_method.
The resulting keyboard_filter object has the can be then used for intercepting keyboard events in accordance to input method needs.
This document adheres to the RFC 2119 when using words like "must",
"should", "may", etc.
Warning! The protocol described in this file is currently in the
experimental phase. Backwards incompatible major versions of the
protocol are to be expected. Exposing this protocol without an opt-in
mechanism is discouraged.
</description>
<interface name="xx_keyboard_filter_v1" version="1">
<description summary="keyboard event filtering functionality">
Manages the filtering of key presses.
</description>
<enum name="error">
<entry name="invalid_serial" value="0x1" summary="compositor received serial not adhering to requirements"/>
</enum>
<request name="unbind">
<description summary="Stop intercepting">
Unbind the keyboard and stop intercepting events.
Unbinds the bound keyboard and the input method. the compositor must stop redirecting keyboard events. Events that the keyboard_filter client has not yet responded to are treated as if they received the "passthrough" action.
This request takes effect immediately.
</description>
</request>
<enum name="filter_action">
<entry name="consume" value="0" summary="consume the key event"/>
<entry name="passthrough" value="1" summary="pass the key event to the text input client"/>
</enum>
<request name="filter">
<description summary="decide the processing of a keyboard event">
This request controls the filtering of keyboard input events before reaching the focused surface.
Usage:
While keyboard_filter is intercepting, the compositor must send every intercepted event to its bound wl_keyboard, and hold a copy of it in an internal queue.
When the client responds with the .filter request, the compositor either removes the event from the queue (filter_action.consume), or sends the copy to the original wl_keyboard objects (filter_action.passthrough).
The compositor must process .filter the oldest event in the queue before processing more recent ones.
For this reason, the client sets the argument "serial" to the serial of the corresponding event it received.
Exceptions:
If the event is other than wl_keyboard.key or contains no serial, it cannot be filtered. The keyboard_filter client must not respond to it with .filter request. When such an event is oldest in the queue, the compositor must proceed as if the event had received a "passthrough" reply.
As of wl_keyboard v10 and keyboard_filter_v1, the only event that can be filtered is the wl_keyboard.key event.
Sequence:
The wl_keyboard begins to receive events after input_method.activate is committed.
The valid serial is the serial of the oldest wl_keyboard event which has been sent after input_method.activate but which hasn't yet received a .filter confirmation.
The compositor may raise the invalid_serial error in response to events with serials it had not issued.
The compositor must ignore events with all other serials. (Particularly, this means events with repeating serials are accepted normally and are not ignored).
Events must be filtered in order of arrival.
</description>
<arg name="serial" type="uint"/>
<arg name="action" type="uint" enum="filter_action"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy the keyboard">
Destroys the keyboard_filter object, stops event interception, and unbinds the wl_keyboard and input_method objects bound to it.
</description>
</request>
</interface>
<interface name="xx_keyboard_filter_manager_v1" version="1">
<enum name="error">
<entry name="already_bound" value="0x1" summary="an argument is already bound"/>
<entry name="wrong_seat" value="0x2" summary="the keyboard i attached to the wrong seat for this operation"/>
</enum>
<request name="bind_to_input_method">
<description summary="Bind a keyboard to an input method">
Bind a keyboard to an input method for the purpose of capturing key presses before they reach the text input client.
When a wl_keyboard is bound, the compositor must redirect to it the input events intended for the focused surface with text input enabled. The wl_keyboard instance receives no other events from then on.
See keyboard_filter.filter.
For the bound wl_keyboard instance to intercept events, the following conditions must be fulfilled:
- there's a focused surface,
- the surface has an enabled text input object,
- the bound input method is active (for the meaning of "active", see input_method.activate, input_method.deactivate).
When those conditions are fulfilled, the compositor must start redirecting input events intended for the text input surface to the wl_keyboard bound with this request. Otherwise, the text input surface receives events without intercepting them.
Be aware that the text input client might use a wl_keyboard object(s) of different version(s) than the one used by the input method. The compositor should issue events as it would normally do for the versions in question. This protocol assumes that events to multiple keyboards of different protocol versions are equivalent.
Background:
Whenever the input method is activated, the compositor must start sending it keyboard events intended for the text-input client, so that the input method can be controlled using a keyboard.
Traditionally, from the user perspective, input methods receive keys as if they were an overlay: keys which are interesting to the input method gain a special input method meaning, all others work as usual.
The binding and the keyboard_filter.filter request together make this possible by letting the input method indicate which events it is interested in.
Conceptually, when a wl_keyboard is bound to an input_method, the compositor prevents all keyboard events directed to the text input client from reaching it. They are delayed until the input method decides how to filter them using the keyboard_filter.filter request.
Arguments:
The wl_keyboard must not be already bound to another interface.
The wl_keyboard must only receive events between committed .activate and .deactivate.
The surface argument represents an arbitrary wl_surface. When issuing wl_keyboard.enter and wl_keyboard.leave on the bound wl_keyboard, the compositor must replace the original surface argument with the one provided by the input method in this request.
Because the wl_keyboard.enter and wl_keyboard.leave events require a surface as the target, one must be provided even if the input method doesn't display one. A dummy one is sufficient. The provided wl_surface will not be used for any other purpose than explained above.
The surface must outlive the input method.
NOTE: This feature works much better with compositor-side key repeat introduced in wl_seat version 10. This protocol doesn't provide controls for filtering repeat key events generated client-side.
A compositor implementing this protocol should implement compositor-side key repeat.
This request takes effect immediately.
Attempting to bind a keyboard to an input method which is already bound must cause the already_bound error.
Attempting to bind a keyboard object which was already bound must cause the already_bound error.
Attempting to bind a keyboard object to an input method acting on a different seat must cause the wrong_seat error.
Once any of the bound objects are destroyed, the xx_keyboard_filter_v1 instance becomes disabled and it must ignore all following requests.
When the input method gets destroyed, the compositor must stop issuing events to the keyboard and ignore any further requests to keyboard_filter, except keyboard_filter.destroy.
</description>
<arg name="keyboard" type="object" interface="wl_keyboard" />
<arg name="input_method" type="object" interface="xx_input_method_v1" />
<arg name="surface" type="object" interface="wl_surface" />
<arg name="extensions" type="new_id" interface="xx_keyboard_filter_v1"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy the input method manager">
Destroys the xx_keyboard_filter_manager_v1 object.
The xx_keyboard_filter_v1 objects originating from it remain unaffected.
</description>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/README
+4
View File
@@ -0,0 +1,4 @@
Session management protocol
Maintainers:
Carlos Garnacho <carlosg@gnome.org>
local/recipes/wayland/wayland-protocols/source/experimental/xx-session-management/xx-session-management-v1.xml
+264
View File
@@ -0,0 +1,264 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xx_session_management_v1">
<copyright>
Copyright 2018 Mike Blumenkrantz
Copyright 2018 Samsung Electronics Co., Ltd
Copyright 2018 Red Hat Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="Protocol for managing application sessions">
This description provides a high-level overview of the interplay between
the interfaces defined this protocol. For details, see the protocol
specification.
The xx_session_manager protocol declares interfaces necessary to
allow clients to restore toplevel state from previous executions. The
xx_session_manager_v1.get_session request can be used to obtain a
xx_session_v1 resource representing the state of a set of toplevels.
Clients may obtain the session string to use in future calls through
the xx_session_v1.created event. Compositors will use this string
as an identifiable token for future runs, possibly storing data about
the related toplevels in persistent storage.
Toplevels are managed through the xx_session_v1.add_toplevel and
xx_session_toplevel_v1.remove pair of requests. Clients will explicitly
request a toplevel to be restored according to prior state through the
xx_session_v1.restore_toplevel request before the toplevel is mapped.
Warning! The protocol described in this file is currently in the
experimental phase. Backwards incompatible major versions of the
protocol are to be expected. Exposing this protocol without an opt-in
mechanism is discouraged.
</description>
<interface name="xx_session_manager_v1" version="1">
<description summary="manage sessions for applications">
The xx_session_manager interface defines base requests for creating and
managing a session for an application. Sessions persist across application
and compositor restarts unless explicitly destroyed. A session is created
for the purpose of maintaining an application's xdg_toplevel surfaces
across compositor or application restarts. The compositor should remember
as many states as possible for surfaces in a given session, but there is
no requirement for which states must be remembered.
</description>
<enum name="error">
<entry name="in_use" summary="a requested session is already in use"
value="1"/>
</enum>
<enum name="reason">
<description summary="reason for getting a session">
The reason may determine in what way a session restores the window
management state of associated toplevels.
For example newly launched applications might be launched on the active
workspace with restored size and position, while a recovered
applications might restore additional state such as active workspace and
stacking order.
</description>
<entry name="launch" value="1">
<description summary="an app is newly launched">
A new app instance is launched, for example from an app launcher.
</description>
</entry>
<entry name="recover" value="2">
<description summary="an app recovered">
An app instance is recovering from for example a compositor or app crash.
</description>
</entry>
<entry name="session_restore" value="3">
<description summary="an app restored">
An app instance is restored, for example part of a restored session, or
restored from having been temporarily terminated due to resource
constraints.
</description>
</entry>
</enum>
<request name="destroy" type="destructor">
<description summary="Destroy this object">
This has no effect other than to destroy the xx_session_manager object.
</description>
</request>
<request name="get_session">
<description summary="create or restore a session">
Create a session object corresponding to either an existing session
identified by the given session identifier string or a new session.
While the session object exists, the session is considered to be "in
use".
If a identifier string represents a session that is currently actively
in use by the the same client, an 'in_use' error is raised. If some
other client is currently using the same session, the new session will
replace managing the associated state.
NULL is passed to initiate a new session. If an id is passed which does
not represent a valid session, the compositor treats it as if NULL had
been passed.
A client is allowed to have any number of in use sessions at the same
time.
</description>
<arg name="id" type="new_id" interface="xx_session_v1"/>
<arg name="reason" type="uint" enum="reason"
summary="reason for session"/>
<arg name="session" type="string"
summary="the session to restore"
allow-null="true"/>
</request>
</interface>
<interface name="xx_session_v1" version="1">
<description summary="A session for an application">
A xx_session_v1 object represents a session for an application. While the
object exists, all surfaces which have been added to the session will
have states stored by the compositor which can be reapplied at a later
time. Two sessions cannot exist for the same identifier string.
States for surfaces added to a session are automatically updated by the
compositor when they are changed.
Surfaces which have been added to a session are automatically removed from
the session if xdg_toplevel.destroy is called for the surface.
</description>
<enum name="error">
<entry name="invalid_restore"
summary="restore cannot be performed after initial toplevel commit"
value="1"/>
<entry name="name_in_use"
summary="toplevel name is already in used"
value="2"/>
<entry name="already_mapped"
summary="toplevel was already mapped when restored"
value="3"/>
</enum>
<request name="destroy" type="destructor">
<description summary="Destroy the session">
Destroy a session object, preserving the current state but not continuing
to make further updates if state changes occur. This makes the associated
xx_toplevel_session_v1 objects inert.
</description>
</request>
<request name="remove" type="destructor">
<description summary="Remove the session">
Remove the session, making it no longer available for restoration. A
compositor should in response to this request remove the data related to
this session from its storage.
</description>
</request>
<request name="add_toplevel">
<description summary="add a new surface to the session">
Attempt to add a given surface to the session. The passed name is used
to identify what window is being restored, and may be used store window
specific state within the session.
Calling this with a toplevel that is already managed by the session with
the same associated will raise an in_use error.
</description>
<arg name="id" type="new_id" interface="xx_toplevel_session_v1"/>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
<arg name="name" type="string"/>
</request>
<request name="restore_toplevel">
<description summary="restore a surface state">
Inform the compositor that the toplevel associated with the passed name
should have its window management state restored.
Calling this with a toplevel that is already managed by the session with
the same associated will raise an in_use error.
This request must be called prior to the first commit on the associated
wl_surface, otherwise an already_mapped error is raised.
As part of the initial configure sequence, if the toplevel was
successfully restored, a xx_toplevel_session_v1.restored event is
emitted. See the xx_toplevel_session_v1.restored event for further
details.
</description>
<arg name="id" type="new_id" interface="xx_toplevel_session_v1"/>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
<arg name="name" type="string"/>
</request>
<event name="created">
<description summary="newly-created session id">
Emitted at most once some time after getting a new session object. It
means that no previous state was restored, and a new session was created.
The passed id can be used to restore previous sessions.
</description>
<arg name="id" type="string"/>
</event>
<event name="restored">
<description summary="the session has been restored">
Emitted at most once some time after getting a new session object. It
means that previous state was at least partially restored. The same id
can again be used to restore previous sessions.
</description>
</event>
<event name="replaced">
<description summary="the session has been restored">
Emitted at most once, if the session was taken over by some other
client. When this happens, the session and all its toplevel session
objects become inert, and should be destroyed.
</description>
</event>
</interface>
<interface name="xx_toplevel_session_v1" version="1">
<request name="destroy" type="destructor">
<description summary="Destroy the object">
Destroy the object. This has no effect window management of the
associated toplevel.
</description>
</request>
<request name="remove" type="destructor">
<description summary="remove a surface from the session">
Remove a specified surface from the session and render any corresponding
xx_toplevel_session_v1 object inert. The compositor should remove any
data related to the toplevel in the corresponding session from its internal
storage.
</description>
</request>
<event name="restored">
<description summary="a toplevel's session has been restored">
The "restored" event is emitted prior to the first
xdg_toplevel.configure for the toplevel. It will only be emitted after
xx_session_v1.restore_toplevel, and the initial empty surface state has
been applied, and it indicates that the surface's session is being
restored with this configure event.
</description>
<arg name="surface" type="object" interface="xdg_toplevel"/>
</event>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/README
+6
View File
@@ -0,0 +1,6 @@
Text input protocol
Maintainers:
Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>
local/recipes/wayland/wayland-protocols/source/experimental/xx-text-input/xx-text-input-v3.xml
+592
View File
@@ -0,0 +1,592 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xx_text_input_unstable_v3">
<copyright>
Copyright © 2012, 2013 Intel Corporation
Copyright © 2015, 2016 Jan Arne Petersen
Copyright © 2017, 2018 Red Hat, Inc.
Copyright © 2018 Purism SPC
Copyright © 2025 DorotaC
Permission to use, copy, modify, distribute, and sell this
software and its documentation for any purpose is hereby granted
without fee, provided that the above copyright notice appear in
all copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
the copyright holders not be used in advertising or publicity
pertaining to distribution of the software without specific,
written prior permission. The copyright holders make no
representations about the suitability of this software for any
purpose. It is provided "as is" without express or implied
warranty.
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.
</copyright>
<description summary="Protocol for composing text">
This protocol allows compositors to act as input methods and to send text
to applications. A text input object is used to manage state of what are
typically text entry fields in the application.
This document adheres to the RFC 2119 when using words like "must",
"should", "may", etc.
Warning! The protocol described in this file is experimental and
backward incompatible changes may be made. Backward compatible changes
may be added together with the corresponding interface version bump.
Backward incompatible changes are done by bumping the version number in
the protocol and interface names and resetting the interface version.
Once the protocol is to be declared stable, the 'xx' prefix and the
version number in the protocol and interface names are removed and the
interface version number is reset.
</description>
<interface name="xx_text_input_v3" version="3">
<description summary="text input">
The xx_text_input_v3 interface represents text input and input methods
associated with a seat. It provides enter/leave events to follow the
text input focus for a seat.
Requests are used to enable/disable the text-input object and set
state information like surrounding and selected text or the content type.
The information about the entered text is sent to the text-input object
via the preedit_string and commit_string events.
Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices
must not point to middle bytes inside a code point: they must either
point to the first byte of a code point or to the end of the buffer.
Lengths must be measured between two valid indices.
Focus moving throughout surfaces will result in the emission of
xx_text_input_v3.enter and xx_text_input_v3.leave events. The focused
surface must commit xx_text_input_v3.enable and
xx_text_input_v3.disable requests as the keyboard focus moves across
editable and non-editable elements of the UI. Those two requests are not
expected to be paired with each other, the compositor must be able to
handle consecutive series of the same request.
State is sent by the state requests (set_surrounding_text,
set_content_type and set_cursor_rectangle) and a commit request. After an
enter event or disable request all state information is invalidated and
needs to be resent by the client.
</description>
<request name="destroy" type="destructor">
<description summary="Destroy the xx_text_input">
Destroy the xx_text_input object. Also disables all surfaces enabled
through this xx_text_input object.
</description>
</request>
<request name="enable">
<description summary="Request text input to be enabled">
Requests text input on the surface previously obtained from the enter
event.
This request must be issued every time the active text input changes
to a new one, including within the current surface. Use
xx_text_input_v3.disable when there is no longer any input focus on
the current surface.
Clients must not enable more than one text input on the single seat
and should disable the current text input before enabling the new one.
At most one instance of text input may be in enabled state per instance,
Requests to enable the another text input when some text input is active
must be ignored by compositor.
This request resets all state associated with previous enable, disable,
set_surrounding_text, set_text_change_cause, set_content_type, and
set_cursor_rectangle requests, as well as the state associated with
preedit_string, commit_string, delete_surrounding_text, and action
events.
The set_surrounding_text, set_content_type and set_cursor_rectangle
requests must follow if the text input supports the necessary
functionality.
State set with this request is double-buffered. It will get applied on
the next xx_text_input_v3.commit request, and stay valid until the
next committed enable or disable request.
The changes must be applied by the compositor after issuing a
xx_text_input_v3.commit request.
</description>
</request>
<request name="disable">
<description summary="Disable text input on a surface">
Explicitly disable text input on the current surface (typically when
there is no focus on any text entry inside the surface).
State set with this request is double-buffered. It will get applied on
the next xx_text_input_v3.commit request.
</description>
</request>
<request name="set_surrounding_text">
<description summary="sets the surrounding text">
Sets the surrounding plain text around the input, excluding the preedit
text.
The client should notify the compositor of any changes in any of the
values carried with this request, including changes caused by handling
incoming text-input events as well as changes caused by other
mechanisms like keyboard typing.
If the client is unaware of the text around the cursor, it should not
issue this request, to signify lack of support to the compositor.
Text is UTF-8 encoded, and should include the cursor position, the
complete selection and additional characters before and after them.
There is a maximum length of wayland messages, so text can not be
longer than 4000 bytes.
Cursor is the byte offset of the cursor within text buffer.
Anchor is the byte offset of the selection anchor within text buffer.
If there is no selected text, anchor is the same as cursor.
If any preedit text is present, it is replaced with a cursor for the
purpose of this event.
Values set with this request are double-buffered. They will get applied
on the next xx_text_input_v3.commit request, and stay valid until the
next committed enable or disable request.
The initial state for affected fields is empty, meaning that the text
input does not support sending surrounding text. If the empty values
get applied, subsequent attempts to change them may have no effect.
</description>
<arg name="text" type="string"/>
<arg name="cursor" type="int"/>
<arg name="anchor" type="int"/>
</request>
<enum name="change_cause">
<description summary="text change reason">
Reason for the change of surrounding text or cursor posision.
</description>
<entry name="input_method" value="0" summary="input method caused the change"/>
<entry name="other" value="1" summary="something else than the input method caused the change"/>
</enum>
<request name="set_text_change_cause">
<description summary="indicates the cause of surrounding text change">
Tells the compositor why the text surrounding the cursor changed.
Whenever the client detects an external change in text, cursor, or
anchor posision, it must issue this request to the compositor. This
request is intended to give the input method a chance to update the
preedit text in an appropriate way, e.g. by removing it when the user
starts typing with a keyboard.
cause describes the source of the change.
The value set with this request is double-buffered. It must be applied
and reset to initial at the next xx_text_input_v3.commit request.
The initial value of cause is input_method.
</description>
<arg name="cause" type="uint" enum="change_cause"/>
</request>
<enum name="content_hint" bitfield="true">
<description summary="content hint">
Content hint is a bitmask to allow to modify the behavior of the text
input.
</description>
<entry name="none" value="0x0" summary="no special behavior"/>
<entry name="completion" value="0x1" summary="suggest word completions"/>
<entry name="spellcheck" value="0x2" summary="suggest word corrections"/>
<entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/>
<entry name="lowercase" value="0x8" summary="prefer lowercase letters"/>
<entry name="uppercase" value="0x10" summary="prefer uppercase letters"/>
<entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/>
<entry name="hidden_text" value="0x40" summary="characters should be hidden"/>
<entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
<entry name="latin" value="0x100" summary="just Latin characters should be entered"/>
<entry name="multiline" value="0x200" summary="the text input is multiline"/>
</enum>
<enum name="content_purpose">
<description summary="content purpose">
The content purpose allows to specify the primary purpose of a text
input.
This allows an input method to show special purpose input panels with
extra characters or to disallow some characters.
</description>
<entry name="normal" value="0" summary="default input, allowing all characters"/>
<entry name="alpha" value="1" summary="allow only alphabetic characters"/>
<entry name="digits" value="2" summary="allow only digits"/>
<entry name="number" value="3" summary="input a number (including decimal separator and sign)"/>
<entry name="phone" value="4" summary="input a phone number"/>
<entry name="url" value="5" summary="input an URL"/>
<entry name="email" value="6" summary="input an email address"/>
<entry name="name" value="7" summary="input a name of a person"/>
<entry name="password" value="8" summary="input a password (combine with sensitive_data hint)"/>
<entry name="pin" value="9" summary="input is a numeric password (combine with sensitive_data hint)"/>
<entry name="date" value="10" summary="input a date"/>
<entry name="time" value="11" summary="input a time"/>
<entry name="datetime" value="12" summary="input a date and time"/>
<entry name="terminal" value="13" summary="input for a terminal"/>
</enum>
<request name="set_content_type">
<description summary="set content purpose and hint">
Sets the content purpose and content hint. While the purpose is the
basic purpose of an input field, the hint flags allow to modify some of
the behavior.
Values set with this request are double-buffered. They will get applied
on the next xx_text_input_v3.commit request.
Subsequent attempts to update them may have no effect. The values
remain valid until the next committed enable or disable request.
The initial value for hint is none, and the initial value for purpose
is normal.
</description>
<arg name="hint" type="uint" enum="content_hint"/>
<arg name="purpose" type="uint" enum="content_purpose"/>
</request>
<request name="set_cursor_rectangle">
<description summary="set cursor position">
Marks an area around the cursor as a x, y, width, height rectangle in
surface local coordinates.
Allows the compositor to put a window with word suggestions near the
cursor, without obstructing the text being input.
If the client is unaware of the position of edited text, it should not
issue this request, to signify lack of support to the compositor.
Values set with this request are double-buffered. They will get applied
on the next xx_text_input_v3.commit request, and stay valid until the
next committed enable or disable request.
The initial values describing a cursor rectangle are empty. That means
the text input does not support describing the cursor area. If the
empty values get applied, subsequent attempts to change them may have
no effect.
</description>
<arg name="x" type="int"/>
<arg name="y" type="int"/>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
</request>
<request name="commit">
<description summary="commit state">
Atomically applies state changes recently sent to the compositor.
The commit request establishes and updates the state of the client, and
must be issued after any changes to apply them.
Text input state (enabled status, content purpose, content hint,
surrounding text and change cause, cursor rectangle) is conceptually
double-buffered within the context of a text input, i.e. between a
committed enable request and the following committed enable or disable
request.
Protocol requests modify the pending state, as opposed to the current
state in use by the input method. A commit request atomically applies
all pending state, replacing the current state. After commit, the new
pending state is as documented for each related request.
Requests are applied in the order of arrival.
Neither current nor pending state are modified unless noted otherwise.
The compositor must count the number of commit requests coming from
each xx_text_input_v3 object and use the count as the serial in done
events.
</description>
</request>
<event name="enter">
<description summary="enter event">
Notification that this seat's text-input focus is on a certain surface.
If client has created multiple text input objects, compositor must send
this event to all of them.
When the seat has the keyboard capability the text-input focus follows
the keyboard focus. This event sets the current surface for the
text-input object.
</description>
<arg name="surface" type="object" interface="wl_surface"/>
</event>
<event name="leave">
<description summary="leave event">
Notification that this seat's text-input focus is no longer on a
certain surface. The client should reset any preedit string previously
set.
The leave notification clears the current surface. It is sent before
the enter notification for the new focus. After leave event, compositor
must ignore requests from any text input instances until next enter
event.
When the seat has the keyboard capability the text-input focus follows
the keyboard focus.
</description>
<arg name="surface" type="object" interface="wl_surface"/>
</event>
<event name="preedit_string">
<description summary="pre-edit">
Notify when a new composing text (pre-edit) should be set at the
current cursor position. Any previously set composing text must be
removed. Any previously existing selected text must be removed.
The argument text contains the pre-edit string buffer.
The parameters cursor_begin and cursor_end are counted in bytes
relative to the beginning of the submitted text buffer. Cursor should
be hidden when both are equal to -1.
They could be represented by the client as a line if both values are
the same, or as a text highlight otherwise.
Values set with this event are double-buffered. They must be applied
and reset to initial on the next xx_text_input_v3.done event.
The initial value of text is an empty string, and cursor_begin,
cursor_end and cursor_hidden are all 0.
</description>
<arg name="text" type="string" allow-null="true"/>
<arg name="cursor_begin" type="int"/>
<arg name="cursor_end" type="int"/>
</event>
<event name="commit_string">
<description summary="text commit">
Notify when text should be inserted into the editor widget. The text to
commit could be either just a single character after a key press or the
result of some composing (pre-edit).
Values set with this event are double-buffered. They must be applied
and reset to initial on the next xx_text_input_v3.done event.
The initial value of text is an empty string.
</description>
<arg name="text" type="string" allow-null="true"/>
</event>
<event name="delete_surrounding_text">
<description summary="delete surrounding text">
Notify when the text around the current cursor position should be
deleted.
Before_length and after_length are the number of bytes before and after
the current cursor index (excluding the selection) to delete.
If text is selected, it must be deleted.
If indices exceed the available text boundaries, they should be adjusted to fit in boundaries and deletion reattempted.
If indices do not lie on byte boundaries, then the text input client should delete at least that many bytes. In this case, the client decides the end point, but a character boundary same as when deleting using the keyboard is recommended.
If a preedit text is present, in effect before_length is counted from
the beginning of it, and after_length from its end (see done event
sequence).
Values set with this event are double-buffered. They must be applied
and reset to initial on the next xx_text_input_v3.done event.
The initial values of both before_length and after_length are 0.
</description>
<arg name="before_length" type="uint" summary="length of text before current cursor position"/>
<arg name="after_length" type="uint" summary="length of text after current cursor position"/>
</event>
<event name="move_cursor" since="2">
<description summary="move cursor and change selection">
Unselects text, moves the cursor and selects text.
This is equivalent to dragging the mouse over some text: it deselects whatever might be currently selected and selects a new range of text.
The offsets used in arguments are in bytes relative to the current cursor position. Cursor is the new position of the cursor, and anchor is the opposite end of selection. If there's no selection, anchor should be equal to cursor.
In terms of dragging the mouse, the anchor is the start, and cursor the end.
The offsets do not take preedit contents into account, nor is preedit changed in any way with this request.
Both cursor and anchor must fall on code point boundaries, otherwise text input client may ignore the request. It is therefore not recommended for an input method to move any of them beyond the text received in surrounding_text.
<!-- Code point boundary checking must happen in the application because no one else is obliged to track the contents.
There are two ways to handle it:
1. add a request from the application informing the compositor of the mistake, so that the compositor can send an error and crash the input method, giving it the chance to reset and go back to normal
2. just ignore the request and hope the input method can resynchronize through surrounding_text
Choosing 2. because it's easier to implement.
-->
When surrounding_text is not supported, the offsets must not be interpreted as bytes, but as some human-readable unit at least as big as a code point, for example a grapheme.
The cursor and anchor arguments can also take the following special values:
BEGINNING := 0x8000_0000 = i32::MIN
END := 0x7fff_ffff = i32::MAX
meaning, respectively, the beginning and the end of of all text in the input field.
Values set with this event are double-buffered. They must be applied
and reset to initial on the next commit request.
The initial values of both cursor and anchor are 0.
</description>
<arg name="cursor" type="int"/>
<arg name="anchor" type="int"/>
</event>
<event name="done">
<description summary="apply changes">
Instruct the application to apply changes to state requested by the
preedit_string, commit_string delete_surrounding_text, and action
events.
The state relating to these events is double-buffered, and each one
modifies the pending state. This event replaces the current state with
the pending state.
The application must proceed by evaluating the changes in the following
order:
1. Replace existing preedit string with the cursor.
2. Delete requested surrounding text.
3. Insert commit string with the cursor at its end.
4. Move the cursor and selection.
5. Calculate surrounding text to send.
6. Insert new preedit text in cursor position.
7. Place cursor inside preedit text.
8. Perform the requested action.
Serial handling starting version 2:
The argument "serial" is ignored.
Serial handling version 1:
The serial number reflects the last state of the xx_text_input_v3
object known to the compositor. The value of the serial argument must
be equal to the number of commit requests already issued on that object.
When the client receives a done event with a serial different than the
number of past commit requests, it must proceed with evaluating and
applying the changes as normal, except it should not change the current
state of the xx_text_input_v3 object. All pending state requests
(set_surrounding_text, set_content_type and set_cursor_rectangle) on
the xx_text_input_v3 object should be sent and committed after
receiving a xx_text_input_v3.done event with a matching serial.
</description>
<arg name="serial" type="uint"/>
</event>
<enum name="action" since="2">
<description summary="action">
A possible action to perform on a text input.
</description>
<entry name="none" value="1">
<description summary="no action">
This enum value exists only to provide a default to make double-buffering implementation easier. It should not be used explicitly.
</description>
</entry>
<!-- Notably missing: moving cursor, deleting and setting a selection. They are nicer to use as part of the text manipulation interface: ranges can be selected there.
Exceptions: the IME doesn't know where lines start or end. The IME will not get to see the entire 4MB document so it can't select all through the text interface. But this doesn't seem urgent. -->
<!-- types of finish actions are better communicated as a hint: this triggers a URL navigation, this sends a search query, this sends a message, etc. The input method can then choose the appropriate buttons to display -->
<entry name="finish" value="0">
<description summary="trigger appropriate action for the completion of editing">
This should be triggered when the user is done with editing the field and wants to move on. For example, the query was typed and the user wants the search result. Or the name was entered and the address needs to be typed next.
The action to perform depends on the application, and should match the value of the current content_purpose.
All clients SHOULD implement this action. Without it, on-screen keyboards don't work as expected.
</description>
</entry>
</enum>
<event name="perform_action" since="2">
<description summary="action performed">
The input method issued an action to perform on this text input.
Values set with this event are double-buffered. They must be applied
and reset to initial on the next .done event.
The initial value of action is none.
</description>
<arg name="action" type="uint" enum="action" summary="action performed"/>
</event>
<request name="set_available_actions" since="2">
<description summary="announce the available actions">
Announces the actions available for the currently active text input.
Values set with this event are double-buffered. They will get applied
on the next .done event.
They get reset to the initial value on the next committed deactivate event.
The initial value is an empty set: no actions are available.
Values in the available_actions array come from text-input-v3.action.
</description>
<!-- Removed the protocol error on none and duplicates because a client has no interest in crashing for slight compositor misbehaviour. Ignoring extraneous values should not be a problem for any half-competent library. -->
<arg name="available_actions" type="array" summary="available actions"/>
<!-- Should this be a bitmap instead of an array? 32 generic actions should be enough, and client-specific actions would need a new protocol anyway -->
</request>
<enum name="supported_features" bitfield="true" since="2">
<description summary="possible supported features">
Client functionality over the baseline that isn't indicated implicitly.
This does not include events coming with .enable: when the input method receives such an event, it is clear the text input supports it, e.g. content_type, available_actions.
Baseline functionality like commit_string, set_preedit_string must always be supported for the protocol to be useful.
The flags match text-input protocol versions, but should be kept general enough to support other protocols.
</description>
<entry name="none" value="0x0" summary="no extra functionality supported"/>
<entry name="move_cursor" value="0x1" summary="the move_cursor request"/>
</enum>
<request name="announce_supported_features" since="2">
<description summary="announce extra supported features">
Notifies the input method what the currently active text input client is able to do.
This event should come within the same .done sequence as .activate. Otherwise, the input method may ignore it.
Values set with this event are double-buffered. They will get applied
on the next .done event.
They get reset to initial on the next committed deactivate event.
The initial value for features is none.
</description>
<arg name="features" type="uint" enum="xx_text_input_v3.supported_features"/>
</request>
</interface>
<interface name="xx_text_input_manager_v3" version="3">
<description summary="text input manager">
A factory for text-input objects. This object is a global singleton.
</description>
<request name="destroy" type="destructor">
<description summary="Destroy the xx_text_input_manager">
Destroy the xx_text_input_manager object.
</description>
</request>
<request name="get_text_input">
<description summary="create a new text input object">
Creates a new text-input object for a given seat.
</description>
<arg name="id" type="new_id" interface="xx_text_input_v3"/>
<arg name="seat" type="object" interface="wl_seat"/>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/README
+4
View File
@@ -0,0 +1,4 @@
Zones protocol
Maintainers:
Matthias Klumpp <matthias@tenstral.net> (@mak)
local/recipes/wayland/wayland-protocols/source/experimental/xx-zones/xx-zones-v1.xml
+493
View File
@@ -0,0 +1,493 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xx_zones_v1">
<copyright>
Copyright © 2023-2026 Matthias Klumpp
Copyright © 2024-2025 Frank Praznik
Copyright © 2024 Victoria Brekenfeld
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="protocol to manage client-specific zones for explicit window placement">
This protocol provides a way for clients to create and add toplevel windows
to "zones".
A zone is an environment with its own coordinate space where clients can
add and arrange windows that logically belong and relate to each other.
It provides means for, among other things, requesting that windows are
placed at specific coordinates within the zone coordinate space.
See the description of "xx_zone_v1" for more details.
This document adheres to RFC 2119 when using words like "must",
"should", "may", etc.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<interface name="xx_zone_manager_v1" version="1">
<description summary="manage zones for clients">
The 'xx_zone_manager' interface defines base requests for obtaining and
managing zones for a client.
</description>
<request name="destroy" type="destructor">
<description summary="Destroy this object">
This has no effect other than to destroy the xx_zone_manager object.
</description>
</request>
<request name="get_zone_item">
<description summary="create a positionable item representing a toplevel">
Create a new positionable zone item from an 'xdg_toplevel'.
The resulting wrapper object can then be used to position the
toplevel window in a zone.
</description>
<arg name="id" type="new_id" interface="xx_zone_item_v1"/>
<arg name="toplevel" type="object" interface="xdg_toplevel" summary="the toplevel window"/>
</request>
<request name="get_zone">
<description summary="join a zone or request a new one">
Create a new zone. While the zone object exists, the compositor
must consider it "used" and keep track of it.
A zone is represented by a string 'handle'.
The compositor must keep zone handles valid while any client is
referencing the corresponding zone.
The compositor may always give a client the same zone for a given
output, and remember its position and size for the client, but
clients should not rely on this behavior.
A client can request a zone to be placed on a specific
output by passing a wl_output as 'output'. If a valid output
is set, the compositor should place the zone on that output.
If NULL is passed, the compositor decides the output.
The compositor should provide the biggest reasonable zone space
for the client, governed by its own policy.
If the compositor wants to deny zone creation (e.g. on a specific
output), the returned zone must be "invalid". A zone is invalid
if it has a negative size, in which case the client is forbidden
to place items in it.
</description>
<arg name="id" type="new_id" interface="xx_zone_v1"/>
<arg name="output" type="object" interface="wl_output"
summary="the preferred output to place the zone on, or NULL"
allow-null="true"/>
</request>
<request name="get_zone_from_handle">
<description summary="join a zone via its handle">
Create a new zone object using the zone's handle.
For the returned zone, the same rules as described in
'get_zone' apply.
This request returns a reference to an existing or remembered zone
that is represented by 'handle'.
The zone may potentially have been created by a different client.
This allows cooperating clients to share the same coordinate space.
If the zone handle was invalid or unknown, a new zone must
be created and returned instead, following the rules outlined
in 'get_zone' and assuming no output preference.
Every new zone object created by this request emits its initial event
sequence, including the 'handle' event, which must return a different
handle from the one passed to this request in case the existing zone
could not be joined.
</description>
<arg name="id" type="new_id" interface="xx_zone_v1"/>
<arg name="handle" type="string" summary="the handle of a zone"/>
</request>
</interface>
<interface name="xx_zone_item_v1" version="1">
<description summary="opaque surface object that can be positioned in a zone">
The zone item object is an opaque descriptor for a positionable
element, such as a toplevel window.
It currently can only be created from an 'xdg_toplevel' via the
'get_zone_item' request on a 'xx_zone_manager'.
The lifetime of a zone item is tied to its referenced item (usually
a toplevel).
When the reference is destroyed, the compositor must send a 'closed'
event and the zone item becomes inert.
</description>
<request name="destroy" type="destructor">
<description summary="delete this object">
Destroys the zone item. This request may be sent at any time by the
client.
By destroying the object, the respective item surface remains at its
last position, but its association with its zone is lost.
This will also cause it to lose any other attached state described by
this protocol.
If the item was associated with a zone when this request is sent,
the compositor must emit 'item_left' on the respective zone, unless
it had already been emitted before a 'closed' event.
</description>
</request>
<event name="frame_extents">
<description summary="the extents of the frame bordering the item">
The 'frame_extents' event describes the current extents of the frame
bordering the item's content area.
This event is sent immediately after the item joins a zone, or if
the item frame extents have been changed by other means (e.g. toggled
by a client request, or compositor involvement). The dimensions are in
the same coordinate space as the item's zone (the surface coordinate
space).
This event must be followed by a 'position' event, even if the item's
coordinates did not change as a result of the frame extents changing.
If the item has no associated frame, the event should still be sent,
but extents must be set to zero.
This event can only be emitted if the item is currently associated
with a zone.
</description>
<arg name="top" type="int" summary="current height of the frame bordering the top of the item"/>
<arg name="bottom" type="int" summary="current height of the frame bordering the bottom of the item"/>
<arg name="left" type="int" summary="current width of the frame bordering the left of the item"/>
<arg name="right" type="int" summary="current width of the frame bordering the right of the item"/>
</event>
<request name="set_position">
<description summary="set a preferred item surface position">
Request a preferred position (x, y) for the specified item
surface to be placed at, relative to its associated zone.
This state is double-buffered and is applied on the next
wl_surface.commit of the surface represented by 'item'.
X and Y coordinates are relative to the zone this item is associated
with, and must not be larger than the dimensions set by the zone size.
They may be smaller than zero, if the item's top-left edge is to be
placed beyond the zone's top-left sides, but clients should expect the
compositor to more aggressively sanitize the coordinate values in that
case.
If a coordinate exceeds the zone's maximum bounds, the compositor must
sanitize it to more appropriate values (e.g. by clamping the values to
the maximum size).
For infinite zones, the client may pick any coordinate.
Compositors implementing this protocol should try to place an item
at the requested coordinates relative to the item's zone, unless doing
so is not allowed by compositor policy (because e.g. the user has set
custom rules for the surface represented by the respective item, the
surface overlaps with a protected shell component, session management
has loaded previous surface positions or the placement request would
send the item out of bounds).
Clients should be aware that their placement preferences might not
always be followed and must be prepared to handle the case where the
item is placed at a different position by the compositor.
Once an item has been mapped, a change to its preferred placement can
still be requested and should be applied, but must not be followed
by the compositor while the user is interacting with the affected item
surface (e.g. clicking &amp; dragging within the window, or resizing it).
After a call to this request, a 'position' event must be emitted with the
item's new actual position.
If the current item has no zone associated with it, a 'position_failed'
event must be emitted.
If the compositor did not move the item at all, not even with sanitized
values, a 'position_failed' event must be emitted as well.
</description>
<arg name="x" type="int" summary="x position relative to zone"/>
<arg name="y" type="int" summary="y position relative to zone"/>
</request>
<event name="position">
<description summary="notify about the position of an item">
This event notifies the client of the current position (x, y) of
the item relative to its zone.
Coordinates are relative to the zone this item belongs to, and only
valid within it.
Negative coordinates are possible, if the user has moved an item
surface beyond the zone's top-left boundary.
This event is sent in response to a 'set_position' request,
or if the item position has been changed by other means
(e.g. user interaction or compositor involvement).
This event can only be emitted if the item is currently associated
with a zone.
</description>
<arg name="x" type="int" summary="current x position relative to zone"/>
<arg name="y" type="int" summary="current y position relative to zone"/>
</event>
<event name="position_failed">
<description summary="a set_position request has failed">
The compositor was unable to set the position of this item entirely,
and could not even find sanitized coordinates to place the item at
instead.
This event will also be emitted if 'set_position' was called while the
item had no zone associated with it.
</description>
</event>
<event name="closed">
<description summary="the underlying surface has been destroyed">
This event indicates that the surface wrapped by this
zone item has been destroyed.
The 'xx_zone_item_v1' object becomes inert and the client should
destroy it. Any requests made on an inert zone item must be silently
ignored by the compositor, and no further events will be sent for this
item.
If the item was associated with a zone when this event is sent,
the compositor must also emit 'item_left' on the respective zone
before sending this event.
</description>
</event>
</interface>
<interface name="xx_zone_v1" version="1">
<description summary="area for a client in which it can set window positioning preferences">
An 'xx_zone' describes a display area provided by the compositor in
which a client can place windows and move them around.
A zone's area could, for example, correspond to the space usable for
placing windows on a specific output (space without panels or other
restricted elements) or it could be an area of the output the compositor
has specifically chosen for a client to place its surfaces in.
Clients should make no assumptions about how a zone is presented to the
user (e.g. compositors may visually distinguish what makes up a zone).
Items are added to a zone as 'xx_zone_item' objects.
All item surface position coordinates (x, y) are relative to the selected
zone.
They are using the 'size' of the respective zone as coordinate system,
with (0, 0) being in the top left corner.
If a zone item is moved out of the top/left boundaries of the zone by
user interaction, its coordinates must become negative, relative to the
zone's top-left coordinate origin. A client may position an item at negative
coordinates.
The compositor must ensure that any item positioned by the client is
visible and accessible to the user, and is not moved into invisible space
outside of a zone.
Positioning requests may be rejected or altered by the compositor, depending
on its policy.
The absolute position of the zone within the compositor's coordinate space
is opaque to the client and the compositor may move the entire zone without
the client noticing it. A zone may also be arbitrarily resized, in which
case the respective 'size' event must be emitted again to notify the client.
A zone is always tied to an output and does not extend beyond it.
A zone may be "invalid". An invalid zone is created with a negative
'size' and must not be used for item arrangement.
Upon creation the compositor must emit 'size' and 'handle' events for the
newly created 'xx_zone', followed by 'done'.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the xx_zone object">
Using this request a client can tell the compositor that it is not
going to use the 'xx_zone' object anymore.
The zone itself must only be destroyed if no other client
is currently referencing it, so this request may only destroy the
object reference owned by the client.
</description>
</request>
<event name="size">
<description summary="size of the zone">
The 'size' event describes the size of this zone.
It is a rectangle with its origin in the top-left corner, using
the surface coordinate space (device pixels divided by the scaling
factor of the output this zone is attached to).
If a width or height value is zero, the zone is infinite
in that direction.
If the width and height values are negative, the zone is considered
"invalid" and must not be used.
A size event declaring the zone invalid may only be emitted immediately
after the zone was created.
A zone must not become invalid at a later time by sending a negative
'size' after the zone has been established.
The 'size' event is sent immediately after creating an 'xx_zone_v1',
and whenever the size of the zone changes. A zone size can change at
any time, for any reason, for example due to output size or scaling
changes, or by compositor policy.
Upon subsequent emissions of 'size' after 'xx_zone' has already
been created, the 'done' event does not have to be sent again.
</description>
<arg name="width" type="int"
summary="zone width in logical pixels"/>
<arg name="height" type="int"
summary="zone height in logical pixels"/>
</event>
<event name="handle">
<description summary="the zone handle">
The handle event provides the unique handle of this zone.
The handle may be shared with any client, which then can use it to
join this client's zone by calling
'xx_zone_manager.get_zone_from_handle'.
This event must only be emitted once after the zone was created.
If this zone is invalid, the handle must be an empty string.
</description>
<arg name="handle" type="string" summary="the exported zone handle"/>
</event>
<event name="done">
<description summary="all information about the zone has been sent">
This event is sent after all other properties (size, handle) of an
'xx_zone' have been sent.
This allows changes to the xx_zone properties to be seen as
atomic, even if they happen via multiple events.
</description>
</event>
<enum name="error">
<entry name="invalid" summary="an invalid value has been submitted"
value="0"/>
</enum>
<request name="add_item">
<description summary="associate an item with this zone">
Make 'item' a member of this zone.
This state is double-buffered and is applied on the next
'wl_surface.commit' of the surface represented by 'item'.
This request associates an item with this zone.
If this request is called on an item that already has a zone
association with a different zone, the item must leave its old zone
(with 'item_left' being emitted on its old zone) and will instead
be associated with this zone.
Upon receiving this request and if the target zone is allowed for 'item',
a compositor must emit 'item_entered' to confirm the zone association.
It must even emit this event if the item was already associated with this
zone before.
The compositor must move the surface represented by 'item' into the
boundary of this zone upon receiving this request and accepting it
(either by extending the zone size, or by moving the item surface).
If the compositor does not allow the item to switch zone associations,
and wants it to remain in its previous zone, it must emit
'item_blocked' instead.
Compositors might want to prevent zone associations if they
perform specialized window management (e.g. autotiling) that would
make clients moving items between certain zones undesirable.
Once the 'item' is added to its zone, the compositor must first send
a 'frame_extents' event on the item, followed by an initial 'position'
event with the item's current position.
The compositor must then send 'position' events when the position
of the item in its zone is changed, for as long as the item is
associated with a zone.
If the zone is invalid, an 'invalid' error must be raised and the item
must not be associated with the invalid zone.
If the referenced item is inert (its underlying surface has been
destroyed), the request must be silently ignored.
</description>
<arg name="item" type="object" interface="xx_zone_item_v1" summary="the zone item"/>
</request>
<request name="remove_item">
<description summary="disassociate an item from this zone">
Remove 'item' as a member of this zone.
This state is double-buffered and is applied on the next
'wl_surface.commit' of the surface represented by 'item'.
This request removes the item from this zone explicitly,
making the client unable to retrieve coordinates again.
Upon receiving this request, the compositor should not change the
item surface position on screen, and must emit 'item_left' to confirm
the item's removal. It must even emit this event if the
item was never associated with this zone.
If the referenced item is inert (its underlying surface has been
destroyed), the request must be silently ignored.
</description>
<arg name="item" type="object" interface="xx_zone_item_v1" summary="the zone item"/>
</request>
<event name="item_blocked">
<description summary="an item could not be associated with this zone">
This event notifies the client that an item was prevented from
joining this zone.
It is emitted as a response to 'add_item' if the compositor did not
allow the item to join this particular zone.
</description>
<arg name="item" type="object" interface="xx_zone_item_v1" summary="the item that was prevented from joining this zone"/>
</event>
<event name="item_entered">
<description summary="notify about an item having joined this zone">
This event notifies the client of an item joining this zone.
It is emitted as a response to 'add_item' or if the compositor
automatically had the item surface (re)join an existing zone.
</description>
<arg name="item" type="object" interface="xx_zone_item_v1" summary="the item that has joined the zone"/>
</event>
<event name="item_left">
<description summary="notify about an item having left this zone">
This event notifies the client of an item leaving this zone, and
therefore the client will no longer receive updated coordinates
or frame extents for this item.
If the client still wishes to adjust the item surface coordinates, it
may associate the item with a zone again by calling 'add_item'.
This event is emitted for example if the user moved an item surface out
of a smaller zone's boundaries, or onto a different screen where the
previous zone can not expand to. It is also emitted in response to
explicitly removing an item via 'remove_item'.
</description>
<arg name="item" type="object" interface="xx_zone_item_v1" summary="the item that has left the zone"/>
</event>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/include/wayland-protocols/meson.build
+1 -1
View File
@@ -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,
local/recipes/wayland/wayland-protocols/source/meson.build
+143 -82
View File
@@ -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)
local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/feedback.rst
+28 -3
View File
@@ -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
==================
local/recipes/wayland/wayland-protocols/source/stable/linux-dmabuf/linux-dmabuf-v1.xml
+82 -44
View File
@@ -24,15 +24,13 @@
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="zwp_linux_dmabuf_v1" version="5">
<interface name="zwp_linux_dmabuf_v1" version="6">
<description summary="factory for creating dmabuf-based wl_buffers">
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.
</description>
<arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1"
summary="the new temporary"/>
summary="id for the newly created zwp_linux_buffer_params_v1"/>
</request>
<event name="format" deprecated-since="4">
@@ -164,7 +162,7 @@
<request name="get_default_feedback" since="4">
<description summary="get default feedback">
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 @@
<request name="get_surface_feedback" since="4">
<description summary="get feedback for a surface">
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.
</description>
<arg name="id" type="new_id" interface="zwp_linux_dmabuf_feedback_v1"/>
@@ -186,7 +184,7 @@
</request>
</interface>
<interface name="zwp_linux_buffer_params_v1" version="5">
<interface name="zwp_linux_buffer_params_v1" version="6">
<description summary="parameters for creating a dmabuf-based wl_buffer">
This temporary object is a collection of dmabufs and other
parameters that together form a single logical buffer. The temporary
@@ -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.
</description>
<enum name="error">
<entry name="already_used" value="0"
summary="the dmabuf_batch object has already been used to create a wl_buffer"/>
summary="the zwp_linux_buffer_params_v1 object has already been used to create a wl_buffer"/>
<entry name="plane_idx" value="1"
summary="plane index out of bounds"/>
<entry name="plane_set" value="2"
@@ -222,6 +222,8 @@
<entry name="invalid_wl_buffer" value="7"
summary="invalid wl_buffer resulted from importing dmabufs via
the create_immed request on given buffer_params"/>
<entry name="invalid_dev_t_size" value="8"
summary="an array with mismatching size for a dev_t was used"/>
</enum>
<request name="destroy" type="destructor">
@@ -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.
</description>
<arg name="buffer" type="new_id" interface="wl_buffer"
summary="the newly created wl_buffer"/>
summary="id for the the newly created wl_buffer"/>
</event>
<event name="failed">
@@ -394,9 +396,28 @@
<arg name="format" type="uint" summary="DRM_FORMAT code"/>
<arg name="flags" type="uint" enum="flags" summary="see enum flags"/>
</request>
<request name="set_sampling_device" since="6">
<description summary="set the target device of the wl_buffer">
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.
</description>
<arg name="device" type="array" summary="device dev_t value"/>
</request>
</interface>
<interface name="zwp_linux_dmabuf_feedback_v1" version="5">
<interface name="zwp_linux_dmabuf_feedback_v1" version="6">
<description summary="dmabuf feedback">
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.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the feedback object">
Using this request a client can tell the server that it is not going to
use the wp_linux_dmabuf_feedback object anymore.
use the zwp_linux_dmabuf_feedback_v1 object anymore.
</description>
</request>
<event name="done">
<description summary="all feedback has been sent">
This event is sent after all parameters of a 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.
</description>
</event>
@@ -463,19 +487,19 @@
<arg name="size" type="uint" summary="table size, in bytes"/>
</event>
<event name="main_device">
<event name="main_device" deprecated-since="6">
<description summary="preferred main device">
This event advertises the main device that the server prefers to use
when direct scan-out to the target device isn't possible. The
advertised main device may be different for each
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.
</description>
<arg name="device" type="array" summary="device dev_t value"/>
</event>
<event name="tranche_done">
<description summary="a preference tranche has been sent">
This event splits tranche_target_device and tranche_formats events 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 @@
</event>
<event name="tranche_formats">
<description summary="supported buffer format modifier">
<description summary="supported buffer format modifiers">
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.
</description>
<arg name="indices" type="array" summary="array of 16-bit indexes"/>
</event>
<enum name="tranche_flags" bitfield="true">
<entry name="scanout" value="1" summary="direct scan-out tranche"/>
<entry name="scanout" value="1" since="4">
<description summary="direct scan-out tranche">
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.
</description>
</entry>
<entry name="sampling" value="2" since="6">
<description summary="sampling tranche">
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.
</description>
</entry>
</enum>
<event name="tranche_flags">
<description summary="tranche flags">
This event sets tranche-specific flags.
The scanout flag is a hint that direct scan-out may be attempted by the
compositor on the target device if the client appropriately allocates a
buffer. How to allocate a buffer that can be scanned out on the target
device is implementation-defined.
This event is tied to a preference tranche, see the tranche_done event.
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.
</description>
<arg name="flags" type="uint" enum="tranche_flags" summary="tranche flags"/>
</event>
local/recipes/wayland/wayland-protocols/source/stable/tablet/tablet-v2.xml
+256 -137
View File
@@ -3,7 +3,7 @@
<copyright>
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.
</description>
<interface name="zwp_tablet_manager_v2" version="1">
<interface name="zwp_tablet_manager_v2" version="2">
<description summary="controller object for graphic tablet devices">
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.
</description>
<request name="get_tablet_seat">
<description summary="get the 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.
</description>
<arg name="tablet_seat" type="new_id" interface="zwp_tablet_seat_v2"/>
@@ -124,22 +124,22 @@
<request name="destroy" type="destructor">
<description summary="release the memory for the tablet manager object">
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.
</description>
</request>
</interface>
<interface name="zwp_tablet_seat_v2" version="1">
<interface name="zwp_tablet_seat_v2" version="2">
<description summary="controller object for graphic tablet devices of a seat">
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.
</description>
<request name="destroy" type="destructor">
<description summary="release the memory for the tablet seat object">
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.
</description>
</request>
@@ -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.
</description>
<arg name="id" type="new_id" interface="zwp_tablet_v2" summary="the newly added graphics tablet"/>
</event>
@@ -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.
</description>
<arg name="id" type="new_id" interface="zwp_tablet_tool_v2" summary="the newly added tablet tool"/>
</event>
@@ -168,40 +168,40 @@
<description summary="new pad notification">
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.
</description>
<arg name="id" type="new_id" interface="zwp_tablet_pad_v2" summary="the newly added pad"/>
</event>
</interface>
<interface name="zwp_tablet_tool_v2" version="1">
<interface name="zwp_tablet_tool_v2" version="2">
<description summary="a physical tablet tool">
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.
</description>
@@ -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.
</description>
@@ -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.
</description>
<arg name="tool_type" type="uint" enum="type" summary="the physical tool type"/>
</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.
</description>
<arg name="hardware_serial_hi" type="uint" summary="the unique serial number of the tool, most significant bits"/>
<arg name="hardware_serial_lo" type="uint" summary="the unique serial number of the tool, least significant bits"/>
@@ -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.
</description>
<arg name="hardware_id_hi" type="uint" summary="the hardware id, most significant bits"/>
<arg name="hardware_id_lo" type="uint" summary="the hardware id, least significant bits"/>
@@ -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.
</description>
<arg name="capability" type="uint" enum="capability" summary="the capability"/>
</event>
@@ -362,17 +362,17 @@
<description summary="tool removed">
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.
</description>
</event>
@@ -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.
</description>
<arg name="degrees" type="fixed" summary="The wheel delta in degrees"/>
@@ -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.
</description>
<arg name="serial" type="uint"/>
@@ -567,16 +567,16 @@
</enum>
</interface>
<interface name="zwp_tablet_v2" version="1">
<interface name="zwp_tablet_v2" version="2">
<description summary="graphics tablet device">
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.
</description>
<request name="destroy" type="destructor">
@@ -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.
</description>
<arg name="name" type="string" summary="the device name"/>
</event>
<event name="id">
<description summary="tablet device USB vendor/product id">
The USB vendor and product IDs for the tablet device.
<description summary="tablet device vendor/product id">
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.
</description>
<arg name="vid" type="uint" summary="USB vendor id"/>
<arg name="pid" type="uint" summary="USB product id"/>
<arg name="vid" type="uint" summary="vendor id"/>
<arg name="pid" type="uint" summary="product id"/>
</event>
<event name="path">
<description summary="path to the device">
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.
</description>
<arg name="path" type="string" summary="path to local device"/>
</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.
</description>
</event>
<!-- Version 2 additions -->
<enum name="bustype" since="2">
<description summary="bus type ">
Describes the bus types this tablet is connected to.
</description>
<entry name="usb" value="3" summary="USB"/>
<entry name="bluetooth" value="5" summary="Bluetooth"/>
<entry name="virtual" value="6" summary="Virtual"/>
<entry name="serial" value="17" summary="Serial"/>
<entry name="i2c" value="24" summary="I2C"/>
</enum>
<event name="bustype" since="2">
<description summary="tablet device bus type">
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.
</description>
<arg name="bustype" type="uint" enum="bustype" summary="bus type"/>
</event>
</interface>
<interface name="zwp_tablet_pad_ring_v2" version="1">
<interface name="zwp_tablet_pad_ring_v2" version="2">
<description summary="pad ring">
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.
</description>
@@ -664,9 +696,9 @@
<description summary="set compositor feedback">
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.
</description>
@@ -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 @@
<description summary="interaction stopped">
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.
</description>
</event>
@@ -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.
</description>
@@ -765,12 +797,12 @@
</event>
</interface>
<interface name="zwp_tablet_pad_strip_v2" version="1">
<interface name="zwp_tablet_pad_strip_v2" version="2">
<description summary="pad strip">
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.
</description>
@@ -778,9 +810,9 @@
<description summary="set compositor feedback">
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.
</description>
@@ -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 @@
<description summary="interaction stopped">
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.
</description>
</event>
@@ -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.
</description>
@@ -881,7 +913,7 @@
</event>
</interface>
<interface name="zwp_tablet_pad_group_v2" version="1">
<interface name="zwp_tablet_pad_group_v2" version="2">
<description summary="a set of buttons, rings and strips">
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.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the pad object">
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.
</description>
</request>
<event name="buttons">
<description summary="buttons announced">
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 @@
<event name="ring">
<description summary="ring announced">
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.
</description>
<arg name="ring" type="new_id" interface="zwp_tablet_pad_ring_v2"/>
</event>
<event name="strip">
<description summary="strip announced">
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.
</description>
<arg name="strip" type="new_id" interface="zwp_tablet_pad_strip_v2"/>
</event>
<event name="modes">
<description summary="mode-switch ability announced">
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.
</description>
<arg name="modes" type="uint" summary="the number of modes"/>
@@ -984,7 +1016,7 @@
<description summary="mode switch event">
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.
</description>
<arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
<arg name="serial" type="uint"/>
<arg name="mode" type="uint" summary="the new mode of the pad"/>
</event>
<!-- Version 2 additions -->
<event name="dial" since="2">
<description summary="dial announced">
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.
</description>
<arg name="dial" type="new_id" interface="zwp_tablet_pad_dial_v2"/>
</event>
</interface>
<interface name="zwp_tablet_pad_v2" version="1">
<description summary="a set of buttons, rings and strips">
A pad device is a set of buttons, rings and strips
<interface name="zwp_tablet_pad_v2" version="2">
<description summary="a set of buttons, rings, strips and dials">
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 @@
<description summary="set compositor feedback">
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.
</description>
@@ -1076,18 +1121,18 @@
<request name="destroy" type="destructor">
<description summary="destroy the pad object">
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.
</description>
</request>
<event name="group">
<description summary="group announced">
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.
</description>
<arg name="pad_group" type="new_id" interface="zwp_tablet_pad_group_v2"/>
</event>
@@ -1095,7 +1140,7 @@
<event name="path">
<description summary="path to the device">
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.
</description>
<arg name="path" type="string" summary="path to local device"/>
</event>
<event name="buttons">
<description summary="buttons announced">
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.
</description>
<arg name="buttons" type="uint" summary="the number of buttons"/>
@@ -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.
</description>
</event>
</interface>
<interface name="zwp_tablet_pad_dial_v2" version="2">
<description summary="pad dial">
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.
</description>
<request name="set_feedback">
<description summary="set compositor feedback">
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.
</description>
<arg name="description" type="string" summary="dial description"/>
<arg name="serial" type="uint" summary="serial of the mode switch event"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy the dial object">
This destroys the client's resource for this dial object.
</description>
</request>
<event name="delta">
<description summary="delta movement">
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.
</description>
<arg name="value120" type="int" summary="rotation distance as fraction of 120"/>
</event>
<event name="frame">
<description summary="end of a dial event sequence">
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.
</description>
<arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
</event>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/stable/xdg-shell/xdg-shell.xml
+76 -39
View File
@@ -29,7 +29,7 @@
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="xdg_wm_base" version="6">
<interface name="xdg_wm_base" version="7">
<description summary="create desktop-style surfaces">
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 @@
<request name="get_xdg_surface">
<description summary="create a shell surface from a surface">
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.
</description>
@@ -122,7 +121,7 @@
</event>
</interface>
<interface name="xdg_positioner" version="6">
<interface name="xdg_positioner" version="7">
<description summary="child surface positioner">
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 @@
<request name="set_anchor">
<description summary="set anchor rectangle anchor">
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.
</description>
<arg name="anchor" type="uint" enum="anchor"
summary="anchor"/>
summary="anchor point"/>
</request>
<enum name="gravity">
@@ -380,7 +379,7 @@
</request>
<request name="set_parent_size" since="3">
<description summary="">
<description summary="set parent size">
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 @@
</request>
</interface>
<interface name="xdg_surface" version="6">
<interface name="xdg_surface" version="7">
<description summary="desktop user interface surface base interface">
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.
</description>
<arg name="id" type="new_id" interface="xdg_popup"/>
<arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
<arg name="positioner" type="object" interface="xdg_positioner"/>
<arg name="parent" type="object" interface="xdg_surface" allow-null="true" summary="parent surface for this popup"/>
<arg name="positioner" type="object" interface="xdg_positioner" summary="positioner for this popup"/>
</request>
<request name="set_window_geometry">
@@ -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.
</description>
<arg name="x" type="int"/>
<arg name="y" type="int"/>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
<arg name="x" type="int" summary="x coordinate of the top-left corner of the window inside this surface"/>
<arg name="y" type="int" summary="y coordinate of the top-left corner of the window inside this surface"/>
<arg name="width" type="int" summary="width of the window"/>
<arg name="height" type="int" summary="height of the window"/>
</request>
<request name="ack_configure">
@@ -617,7 +619,7 @@
</interface>
<interface name="xdg_toplevel" version="6">
<interface name="xdg_toplevel" version="7">
<description summary="toplevel surface">
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.
</description>
<arg name="parent" type="object" interface="xdg_toplevel" allow-null="true"/>
<arg name="parent" type="object" interface="xdg_toplevel" allow-null="true" summary="parent surface for this surface"/>
</request>
<request name="set_title">
@@ -694,7 +696,7 @@
The string must be encoded in UTF-8.
</description>
<arg name="title" type="string"/>
<arg name="title" type="string" summary="title of the surface"/>
</request>
<request name="set_app_id">
@@ -723,7 +725,7 @@
[0] https://standards.freedesktop.org/desktop-entry-spec/
</description>
<arg name="app_id" type="string"/>
<arg name="app_id" type="string" summary="application identifier surface belongs to"/>
</request>
<request name="show_window_menu">
@@ -911,6 +913,38 @@
outputs are switched off due to screen locking.
</description>
</entry>
<entry name="constrained_left" value="10" since="7">
<description summary="the surface’s left edge is constrained">
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.
</description>
</entry>
<entry name="constrained_right" value="11" since="7">
<description summary="the surface’s right edge is constrained">
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.
</description>
</entry>
<entry name="constrained_top" value="12" since="7">
<description summary="the surface’s top edge is constrained">
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.
</description>
</entry>
<entry name="constrained_bottom" value="13" since="7">
<description summary="the surface’s bottom edge is constrained">
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.
</description>
</entry>
</enum>
<request name="set_max_size">
@@ -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.
</description>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
<arg name="width" type="int" summary="maximum width of the window"/>
<arg name="height" type="int" summary="maximum height of the window"/>
</request>
<request name="set_min_size">
@@ -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.
</description>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
<arg name="width" type="int" summary="minimum width of the window"/>
<arg name="height" type="int" summary="minimum height of the window"/>
</request>
<request name="set_maximized">
@@ -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.
</description>
<arg name="output" type="object" interface="wl_output" allow-null="true"/>
<arg name="output" type="object" interface="wl_output" allow-null="true" summary="preferred output to place surface on"/>
</request>
<request name="unset_fullscreen">
@@ -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.
</description>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
<arg name="states" type="array"/>
<arg name="width" type="int" summary="suggested width of window"/>
<arg name="height" type="int" summary="suggested height of window"/>
<arg name="states" type="array" summary="suggested states of the window"/>
</event>
<event name="close">
@@ -1167,8 +1204,8 @@
xdg_toplevel.configure_bounds will be sent, followed by
xdg_toplevel.configure and xdg_surface.configure.
</description>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
<arg name="width" type="int" summary="suggested maximum width of surface"/>
<arg name="height" type="int" summary="suggested maximum height of surface"/>
</event>
<!-- Version 5 additions -->
@@ -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.
</description>
<arg name="capabilities" type="array" summary="array of 32-bit capabilities"/>
</event>
</interface>
<interface name="xdg_popup" version="6">
<interface name="xdg_popup" version="7">
<description summary="short-lived, popup surfaces for menus">
A popup surface is a short-lived, temporary surface. It can be used to
implement for example menus, popovers, tooltips and other similar user
local/recipes/wayland/wayland-protocols/source/staging/alpha-modifier/alpha-modifier-v1.xml
+1 -1
View File
@@ -48,7 +48,7 @@
</enum>
<request name="get_surface">
<description summary="create a new toplevel decoration object">
<description summary="create a new alpha modifier surface object">
Create a new alpha modifier surface object associated with the
given wl_surface. If there is already such an object associated with
the wl_surface, the already_constructed error will be raised.
local/recipes/wayland/wayland-protocols/source/staging/color-management/README
+11
View File
@@ -0,0 +1,11 @@
Color management and HDR protocol
Maintainers:
Sebastian Wick <sebastian at sebastianwick.net>
Pekka Paalanen <pekka.paalanen@collabora.com>
Historical credits not mentioned in the first commit:
- Niels Ole Salscheider, for an early protocol version
https://lists.freedesktop.org/archives/wayland-devel/2014-October/017755.html
local/recipes/wayland/wayland-protocols/source/staging/color-management/appendix.md
+144
View File
@@ -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/
local/recipes/wayland/wayland-protocols/source/staging/color-management/color-management-v1.xml
+1756
View File
File diff suppressed because it is too large Load Diff
local/recipes/wayland/wayland-protocols/source/staging/color-representation/README
+6
View File
@@ -0,0 +1,6 @@
color-representation protocol
Maintainers:
Simon Ser <contact@emersion.fr>
Sebastian Wick <sebastian@sebastianwick.net>
Pekka Paalanen <pekka.paalanen@collabora.com>
local/recipes/wayland/wayland-protocols/source/staging/color-representation/color-representation-v1.xml
+433
View File
@@ -0,0 +1,433 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="color_representation_v1">
<copyright>
Copyright 2022 Simon Ser
Copyright 2022 Red Hat, Inc.
Copyright 2022 Collabora, Ltd.
Copyright 2022-2025 Red Hat, Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="color representation protocol extension">
This protocol extension delivers the metadata required to define alpha mode,
the color model, sub-sampling and quantization range used when interpreting
buffer contents. The main use case is defining how the YCbCr family of pixel
formats convert to RGB.
Note that this protocol does not define the colorimetry of the resulting RGB
channels / tristimulus values. Without the help of other extensions the
resulting colorimetry is therefore implementation defined.
If this extension is not used, the color representation used is compositor
implementation defined.
Recommendation ITU-T H.273
"Coding-independent code points for video signal type identification"
shall be referred to as simply H.273 here.
</description>
<interface name="wp_color_representation_manager_v1" version="1">
<description summary="color representation manager singleton">
A singleton global interface used for getting color representation
extensions for wl_surface. The extension interfaces allow setting the
color representation of surfaces.
Compositors should never remove this global.
</description>
<enum name="error">
<description summary="protocol errors"/>
<entry name="surface_exists" value="1"
summary="color representation surface exists already"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the manager">
Destroy the wp_color_representation_manager_v1 object. This does not
affect any other objects in any way.
</description>
</request>
<request name="get_surface">
<description summary="create a color representation interface for a wl_surface">
If a wp_color_representation_surface_v1 object already exists for the
given wl_surface, the protocol error surface_exists is raised.
This creates a new color wp_color_representation_surface_v1 object for
the given wl_surface.
See the wp_color_representation_surface_v1 interface for more details.
</description>
<arg name="id"
type="new_id" interface="wp_color_representation_surface_v1"/>
<arg name="surface"
type="object" interface="wl_surface"/>
</request>
<event name="supported_alpha_mode">
<description summary="supported alpha modes">
When this object is created, it shall immediately send this event once
for each alpha mode the compositor supports.
For the definition of the supported values, see the
wp_color_representation_surface_v1::alpha_mode enum.
</description>
<arg name="alpha_mode"
type="uint" enum="wp_color_representation_surface_v1.alpha_mode"
summary="supported alpha mode"/>
</event>
<event name="supported_coefficients_and_ranges">
<description summary="supported matrix coefficients and ranges">
When this object is created, it shall immediately send this event once
for each matrix coefficient and color range combination the compositor
supports.
For the definition of the supported values, see the
wp_color_representation_surface_v1::coefficients and
wp_color_representation_surface_v1::range enums.
</description>
<arg name="coefficients"
type="uint" enum="wp_color_representation_surface_v1.coefficients"
summary="supported matrix coefficients"/>
<arg name="range"
type="uint" enum="wp_color_representation_surface_v1.range"
summary="full range flag"/>
</event>
<event name="done">
<description summary="all features have been sent">
This event is sent when all supported features have been sent.
</description>
</event>
</interface>
<interface name="wp_color_representation_surface_v1" version="1">
<description summary="color representation extension to a surface">
A wp_color_representation_surface_v1 allows the client to set the color
representation metadata of a surface.
By default, a surface does not have any color representation metadata set.
The reconstruction of R, G, B signals on such surfaces is compositor
implementation defined. The alpha mode is assumed to be
premultiplied_electrical when the alpha mode is unset.
If the wl_surface associated with the wp_color_representation_surface_v1
is destroyed, the wp_color_representation_surface_v1 object becomes inert.
</description>
<enum name="error">
<description summary="protocol errors"/>
<entry name="alpha_mode" value="1"
summary="unsupported alpha mode"/>
<entry name="coefficients" value="2"
summary="unsupported coefficients"/>
<entry name="pixel_format" value="3"
summary="the pixel format and a set value are incompatible"/>
<entry name="inert" value="4"
summary="forbidden request on inert object"/>
<entry name="chroma_location" value="5"
summary="invalid chroma location"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the color representation">
Destroy the wp_color_representation_surface_v1 object.
Destroying this object unsets all the color representation metadata from
the surface. See the wp_color_representation_surface_v1 interface
description for how a compositor handles a surface without color
representation metadata. Unsetting is double-buffered state, see
wl_surface.commit.
</description>
</request>
<enum name="alpha_mode">
<description summary="alpha mode">
Specifies how the alpha channel affects the color channels.
</description>
<entry name="premultiplied_electrical" value="0">
<description summary="premultiplied alpha in electrical values">
Electrical color channel values (after transfer function encoding)
are already multiplied with the alpha channel value.
</description>
</entry>
<entry name="premultiplied_optical" value="1">
<description summary="premultiplied alpha in optical values">
Optical color channel values (before transfer function encoding)
are already multiplied with the alpha channel value.
</description>
</entry>
<entry name="straight" value="2">
<description summary="straight alpha">
Alpha channel has not been pre-multiplied into color channels.
</description>
</entry>
</enum>
<enum name="coefficients">
<description summary="named coefficients">
Named matrix coefficients used to encode well-known sets of
coefficients. H.273 is the authority, when it comes to the exact values
of coefficients and authoritative specifications, where an equivalent
code point exists.
A value of 0 is invalid and will never be present in the list of enums.
Descriptions do list the specifications for convenience.
</description>
<entry name="identity" value="1">
<description summary="The identity matrix">
Coefficients as defined by
- IEC 61966-2-1 sRGB
- SMPTE ST 428-1 (2019)
Equivalent to H.273 MatrixCoefficients code point 0.
Compatible with pixel formats of the RGB family.
</description>
</entry>
<entry name="bt709" value="2">
<description summary="BT.709 matrix coefficients">
Coefficients as defined by
- Rec. ITU-R BT.709-6
- Rec. ITU-R BT.1361-0 conventional colour gamut system (historical)
- Rec. ITU-R BT.1361-0 conventional colour gamut system and extended
colour gamut system (historical)
- IEC 61966-2-4 xvYCC709
- SMPTE RP 177 (1993) Annex B
Equivalent to H.273 MatrixCoefficients code point 1.
Compatible with pixel formats of the YCbCr family.
</description>
</entry>
<entry name="fcc" value="3">
<description summary="FCC matrix coefficients">
Coefficients as defined by
- United States Federal Communications Commission (2003) Title 47
Code of Federal Regulations 73.682 (a) (20)
Equivalent to H.273 MatrixCoefficients code point 4.
Compatible with pixel formats of the YCbCr family.
</description>
</entry>
<entry name="bt601" value="4">
<description summary="BT.601-7 matrix coefficients">
Coefficients as defined by
- Rec. ITU-R BT.470-6 System B, G (historical)
- Rec. ITU-R BT.601-7 625
- Rec. ITU-R BT.601-7 525
- Rec. ITU-R BT.1358-0 625 (historical)
- Rec. ITU-R BT.1358-1 525 or 625 (historical)
- Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
- Rec. ITU-R BT.1700-0 NTSC
- IEC 61966-2-1 sYCC
- IEC 61966-2-4 xvYCC601
- SMPTE ST 170 (2004)
Equivalent to H.273 MatrixCoefficients code point 5, 6.
Compatible with pixel formats of the YCbCr family.
</description>
</entry>
<entry name="smpte240" value="5">
<description summary="SMPTE ST 240 matrix coefficients">
Coefficients as defined by
- SMPTE ST 240 (1999)
Equivalent to H.273 MatrixCoefficients code point 7.
Compatible with pixel formats of the YCbCr family.
</description>
</entry>
<entry name="bt2020" value="6">
<description summary="BT.2020 and BT.2100 YCbCr matrix coefficients">
Coefficients as defined by
- Rec. ITU-R BT.2020-2 (non-constant luminance)
- Rec. ITU-R BT.2100-2 Y′CbCr
Equivalent to H.273 MatrixCoefficients code point 9.
Compatible with pixel formats of the YCbCr family.
</description>
</entry>
<entry name="bt2020_cl" value="7">
<description summary="BT.2020 matrix coefficients for constant luminance">
Coefficients as defined by
- Rec. ITU-R BT.2020-2 (constant luminance)
Equivalent to H.273 MatrixCoefficients code point 10.
Compatible with pixel formats of the YCbCr family.
</description>
</entry>
<entry name="ictcp" value="8">
<description summary="BT.2100 ICtCp matrix coefficients">
Coefficients as defined by
- Rec. ITU-R BT.2100-2 ICTCP
Equivalent to H.273 MatrixCoefficients code point 14.
Compatible with pixel formats of the YCbCr family.
</description>
</entry>
</enum>
<enum name="range">
<description summary="Color range values">
Possible color range values.
A value of 0 is invalid and will never be present in the list of enums.
</description>
<entry name="full" value="1" summary="Full color range"/>
<entry name="limited" value="2" summary="Limited color range"/>
</enum>
<enum name="chroma_location">
<description summary="Chroma sample location for 4:2:0 YCbCr">
Chroma sample location as defined by H.273 Chroma420SampleLocType.
A value of 0 is invalid and will never be present in the list of enums.
The descriptions list the matching Vulkan VkChromaLocation combinations
for convenience.
</description>
<entry name="type_0" value="1">
<description summary="Horizontal offset of 0, vertical offset of 0.5">
Corresponding to VkChromaLocations:
- xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
- yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
Equivalent to H.273 Chroma420SampleLocType 0.
</description>
</entry>
<entry name="type_1" value="2">
<description summary="Horizontal offset of 0.5, vertical offset of 0.5">
Corresponding to VkChromaLocations:
- xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
- yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
Equivalent to H.273 Chroma420SampleLocType 1.
</description>
</entry>
<entry name="type_2" value="3">
<description summary="Horizontal offset of 0, vertical offset of 0">
Corresponding to VkChromaLocations:
- xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
- yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
Equivalent to H.273 Chroma420SampleLocType 2.
</description>
</entry>
<entry name="type_3" value="4">
<description summary="Horizontal offset of 0.5, vertical offset of 0">
Corresponding to VkChromaLocations:
- xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
- yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
Equivalent to H.273 Chroma420SampleLocType 3.
</description>
</entry>
<entry name="type_4" value="5">
<description summary="Horizontal offset of 0, vertical offset of 1">
Equivalent to H.273 Chroma420SampleLocType 4.
</description>
</entry>
<entry name="type_5" value="6">
<description summary="Horizontal offset of 0.5, vertical offset of 1">
Equivalent to H.273 Chroma420SampleLocType 5.
</description>
</entry>
</enum>
<request name="set_alpha_mode">
<description summary="set the surface alpha mode">
If this protocol object is inert, the protocol error inert is raised.
Assuming an alpha channel exists, it is always linear. The alpha mode
determines whether and how the color channels include pre-multiplied
alpha. Using straight alpha might have performance benefits.
Only alpha modes advertised by the compositor are allowed to be used as
argument for this request. The "alpha_mode" protocol error is raised
otherwise.
Alpha mode is double buffered, see wl_surface.commit.
</description>
<arg name="alpha_mode" type="uint" enum="alpha_mode"
summary="alpha mode"/>
</request>
<request name="set_coefficients_and_range">
<description summary="set the matrix coefficients and range">
If this protocol object is inert, the protocol error inert is raised.
Set the matrix coefficients and video range which defines the formula
and the related constants used to derive red, green and blue signals.
Usually coefficients correspond to MatrixCoefficients code points in
H.273.
Only combinations advertised by the compositor are allowed to be used as
argument for this request. The "coefficients" protocol error is raised
otherwise.
A call to wl_surface.commit verifies that the pixel format and the
coefficients-range combination in the committed surface contents are
compatible, if contents exist. The "pixel_format" protocol error is
raised otherwise.
A pixel format is compatible with the coefficients-range combination if
the related equations and conventions as defined in H.273 can produce
the color channels (RGB or YCbCr) of the pixel format.
For the definition of the supported combination, see the
wp_color_representation_surface_v1::coefficients and
wp_color_representation_surface_v1::range enums.
The coefficients-range combination is double-buffered, see
wl_surface.commit.
</description>
<arg name="coefficients" type="uint" enum="coefficients"
summary="matrix coefficients"/>
<arg name="range" type="uint" enum="range"
summary="range"/>
</request>
<request name="set_chroma_location">
<description summary="set the chroma location">
If this protocol object is inert, the protocol error inert is raised.
Set the chroma location type which defines the position of downsampled
chroma samples, corresponding to Chroma420SampleLocType code points in
H.273.
An invalid chroma location enum value raises the "chroma_location"
protocol error.
A call to wl_surface.commit verifies that the pixel format and chroma
location type in the committed surface contents are compatible, if
contents exist. The "pixel_format" protocol error is raised otherwise.
For the definition of the supported chroma location types, see the
wp_color_representation_surface_v1::chroma_location enum.
The chroma location type is double-buffered, see wl_surface.commit.
</description>
<arg name="chroma_location" type="uint" enum="chroma_location"
summary="chroma sample location"/>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/staging/color-representation/notes.rst
+79
View File
@@ -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.
local/recipes/wayland/wayland-protocols/source/staging/content-type/content-type-v1.xml
+1 -1
View File
@@ -48,7 +48,7 @@
</enum>
<request name="get_surface_content_type">
<description summary="create a new toplevel decoration object">
<description summary="create a new content type object">
Create a new content type object associated with the given surface.
Creating a wp_content_type_v1 from a wl_surface which already has one
local/recipes/wayland/wayland-protocols/source/staging/cursor-shape/cursor-shape-v1.xml
+12 -2
View File
@@ -22,7 +22,7 @@
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="wp_cursor_shape_manager_v1" version="1">
<interface name="wp_cursor_shape_manager_v1" version="2">
<description summary="cursor shape manager">
This global offers an alternative, optional way to set cursor images. This
new way uses enumerated cursors instead of a wl_surface like
@@ -63,7 +63,7 @@
</request>
</interface>
<interface name="wp_cursor_shape_device_v1" version="1">
<interface name="wp_cursor_shape_device_v1" version="2">
<description summary="cursor shape for a device">
This interface allows clients to set the cursor shape.
</description>
@@ -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.
</description>
<entry name="default" value="1" summary="default cursor"/>
<entry name="context_menu" value="2" summary="a context menu is available for the object under the cursor"/>
@@ -109,6 +117,8 @@
<entry name="all_scroll" value="32" summary="something can be scrolled in any direction"/>
<entry name="zoom_in" value="33" summary="something can be zoomed in"/>
<entry name="zoom_out" value="34" summary="something can be zoomed out"/>
<entry name="dnd_ask" value="35" summary="drag-and-drop: the user will select which action will be carried out (non-css value)" since="2"/>
<entry name="all_resize" value="36" summary="resizing: something can be moved or resized in any direction (non-css value)" since="2"/>
</enum>
<enum name="error">
local/recipes/wayland/wayland-protocols/source/staging/drm-lease/README
+1 -1
View File
@@ -1,6 +1,6 @@
Linux DRM lease
Maintainers:
Drew DeVault <sir@cmpwn.com>
Simon Zeni <simon@bl4ckb0ne.ca> (@bl4ckb0ne)
Marius Vlad <marius.vlad@collabora.com> (@mvlad)
Xaver Hugl <xaver.hugl@gmail.com> (@Zamundaaa)
local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/README
+6
View File
@@ -0,0 +1,6 @@
ext_blur protocol
Maintainers:
David Edmundson <davidedmundson@kde.org>
Vlad Zahorodnii <vlad.zahorodnii@kde.org>
Xaver Hugl <xaver.hugl@kde.org>
local/recipes/wayland/wayland-protocols/source/staging/ext-background-effect/ext-background-effect-v1.xml
+129
View File
@@ -0,0 +1,129 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ext_background_effect_v1">
<copyright>
Copyright (C) 2015 Martin Gräßlin
Copyright (C) 2015 Marco Martin
Copyright (C) 2020 Vlad Zahorodnii
Copyright (C) 2024 Xaver Hugl
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="ext_background_effect_manager_v1" version="1">
<description summary="background effect factory">
This protocol provides a way to improve visuals of translucent surfaces
by applying effects like blur to the background behind them.
The capabilities are send when the global is bound, and every time they
change. Note that when the capability goes away, the corresponding effect
is no longer applied by the compositor, even if it was set before.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the background effect manager">
Informs the server that the client will no longer be using this
protocol object. Existing objects created by this object are not
affected.
</description>
</request>
<enum name="error">
<entry name="background_effect_exists" value="0"
summary="the surface already has a background effect object"/>
</enum>
<enum name="capability" bitfield="true">
<entry name="blur" value="1"
summary="the compositor supports applying blur"/>
</enum>
<event name="capabilities">
<description summary="capabilities of the compositor"/>
<arg name="flags" type="uint" enum="capability"/>
</event>
<request name="get_background_effect">
<description summary="get a background effects object">
Instantiate an interface extension for the given wl_surface to add
effects like blur for the background behind it.
If the given wl_surface already has a ext_background_effect_surface_v1
object associated, the background_effect_exists protocol error will be
raised.
</description>
<arg name="id" type="new_id" interface="ext_background_effect_surface_v1"
summary="the new ext_background_effect_surface_v1 object"/>
<arg name="surface" type="object" interface="wl_surface"
summary="the surface"/>
</request>
</interface>
<interface name="ext_background_effect_surface_v1" version="1">
<description summary="background effects for a surface">
The background effect object provides a way to specify a region behind
a surface that should have background effects like blur applied.
If the wl_surface associated with the ext_background_effect_surface_v1
object has been destroyed, this object becomes inert.
</description>
<request name="destroy" type="destructor">
<description summary="release the blur object">
Informs the server that the client will no longer be using this protocol
object. The effect regions will be removed on the next commit.
</description>
</request>
<enum name="error">
<entry name="surface_destroyed" value="0"
summary="the associated surface has been destroyed"/>
</enum>
<request name="set_blur_region">
<description summary="set blur region">
This request sets the region of the surface that will have its
background blurred.
The blur region is specified in the surface-local coordinates, and
clipped by the compositor to the surface size.
The initial value for the blur region is empty. Setting the pending
blur region has copy semantics, and the wl_region object can be
destroyed immediately. A NULL wl_region removes the effect.
The blur region is double-buffered state, and will be applied on
the next wl_surface.commit.
The blur algorithm is subject to compositor policies.
If the associated surface has been destroyed, the surface_destroyed
error will be raised.
</description>
<arg name="region" type="object" interface="wl_region" allow-null="true"
summary="blur region of the surface"/>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/README
+4
View File
@@ -0,0 +1,4 @@
data-control protocol
Maintainers:
Neal Gompa <neal@gompa.dev> (@Conan_Kudo)
local/recipes/wayland/wayland-protocols/source/staging/ext-data-control/ext-data-control-v1.xml
+276
View File
@@ -0,0 +1,276 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ext_data_control_v1">
<copyright>
Copyright © 2018 Simon Ser
Copyright © 2019 Ivan Molodetskikh
Copyright © 2024 Neal Gompa
Permission to use, copy, modify, distribute, and sell this
software and its documentation for any purpose is hereby granted
without fee, provided that the above copyright notice appear in
all copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
the copyright holders not be used in advertising or publicity
pertaining to distribution of the software without specific,
written prior permission. The copyright holders make no
representations about the suitability of this software for any
purpose. It is provided "as is" without express or implied
warranty.
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.
</copyright>
<description summary="control data devices">
This protocol allows a privileged client to control data devices. In
particular, the client will be able to manage the current selection and take
the role of a clipboard manager.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<interface name="ext_data_control_manager_v1" version="1">
<description summary="manager to control data devices">
This interface is a manager that allows creating per-seat data device
controls.
</description>
<request name="create_data_source">
<description summary="create a new data source">
Create a new data source.
</description>
<arg name="id" type="new_id" interface="ext_data_control_source_v1"
summary="data source to create"/>
</request>
<request name="get_data_device">
<description summary="get a data device for a seat">
Create a data device that can be used to manage a seat's selection.
</description>
<arg name="id" type="new_id" interface="ext_data_control_device_v1"/>
<arg name="seat" type="object" interface="wl_seat"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy the manager">
All objects created by the manager will still remain valid, until their
appropriate destroy request has been called.
</description>
</request>
</interface>
<interface name="ext_data_control_device_v1" version="1">
<description summary="manage a data device for a seat">
This interface allows a client to manage a seat's selection.
When the seat is destroyed, this object becomes inert.
</description>
<request name="set_selection">
<description summary="copy data to the selection">
This request asks the compositor to set the selection to the data from
the source on behalf of the client.
The given source may not be used in any further set_selection or
set_primary_selection requests. Attempting to use a previously used
source triggers the used_source protocol error.
To unset the selection, set the source to NULL.
</description>
<arg name="source" type="object" interface="ext_data_control_source_v1"
allow-null="true"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy this data device">
Destroys the data device object.
</description>
</request>
<event name="data_offer">
<description summary="introduce a new ext_data_control_offer">
The data_offer event introduces a new ext_data_control_offer object,
which will subsequently be used in either the
ext_data_control_device.selection event (for the regular clipboard
selections) or the ext_data_control_device.primary_selection event (for
the primary clipboard selections). Immediately following the
ext_data_control_device.data_offer event, the new data_offer object
will send out ext_data_control_offer.offer events to describe the MIME
types it offers.
</description>
<arg name="id" type="new_id" interface="ext_data_control_offer_v1"/>
</event>
<event name="selection">
<description summary="advertise new selection">
The selection event is sent out to notify the client of a new
ext_data_control_offer for the selection for this device. The
ext_data_control_device.data_offer and the ext_data_control_offer.offer
events are sent out immediately before this event to introduce the data
offer object. The selection event is sent to a client when a new
selection is set. The ext_data_control_offer is valid until a new
ext_data_control_offer or NULL is received. The client must destroy the
previous selection ext_data_control_offer, if any, upon receiving this
event. Regardless, the previous selection will be ignored once a new
selection ext_data_control_offer is received.
The first selection event is sent upon binding the
ext_data_control_device object.
</description>
<arg name="id" type="object" interface="ext_data_control_offer_v1"
allow-null="true"/>
</event>
<event name="finished">
<description summary="this data control is no longer valid">
This data control object is no longer valid and should be destroyed by
the client.
</description>
</event>
<event name="primary_selection">
<description summary="advertise new primary selection">
The primary_selection event is sent out to notify the client of a new
ext_data_control_offer for the primary selection for this device. The
ext_data_control_device.data_offer and the ext_data_control_offer.offer
events are sent out immediately before this event to introduce the data
offer object. The primary_selection event is sent to a client when a
new primary selection is set. The ext_data_control_offer is valid until
a new ext_data_control_offer or NULL is received. The client must
destroy the previous primary selection ext_data_control_offer, if any,
upon receiving this event. Regardless, the previous primary selection
will be ignored once a new primary selection ext_data_control_offer is
received.
If the compositor supports primary selection, the first
primary_selection event is sent upon binding the
ext_data_control_device object.
</description>
<arg name="id" type="object" interface="ext_data_control_offer_v1"
allow-null="true"/>
</event>
<request name="set_primary_selection">
<description summary="copy data to the primary selection">
This request asks the compositor to set the primary selection to the
data from the source on behalf of the client.
The given source may not be used in any further set_selection or
set_primary_selection requests. Attempting to use a previously used
source triggers the used_source protocol error.
To unset the primary selection, set the source to NULL.
The compositor will ignore this request if it does not support primary
selection.
</description>
<arg name="source" type="object" interface="ext_data_control_source_v1"
allow-null="true"/>
</request>
<enum name="error">
<entry name="used_source" value="1"
summary="source given to set_selection or set_primary_selection was already used before"/>
</enum>
</interface>
<interface name="ext_data_control_source_v1" version="1">
<description summary="offer to transfer data">
The ext_data_control_source object is the source side of a
ext_data_control_offer. It is created by the source client in a data
transfer and provides a way to describe the offered data and a way to
respond to requests to transfer the data.
</description>
<enum name="error">
<entry name="invalid_offer" value="1"
summary="offer sent after ext_data_control_device.set_selection"/>
</enum>
<request name="offer">
<description summary="add an offered MIME type">
This request adds a MIME type to the set of MIME types advertised to
targets. Can be called several times to offer multiple types.
Calling this after ext_data_control_device.set_selection is a protocol
error.
</description>
<arg name="mime_type" type="string"
summary="MIME type offered by the data source"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy this source">
Destroys the data source object.
</description>
</request>
<event name="send">
<description summary="send the data">
Request for data from the client. Send the data as the specified MIME
type over the passed file descriptor, then close it.
</description>
<arg name="mime_type" type="string" summary="MIME type for the data"/>
<arg name="fd" type="fd" summary="file descriptor for the data"/>
</event>
<event name="cancelled">
<description summary="selection was cancelled">
This data source is no longer valid. The data source has been replaced
by another data source.
The client should clean up and destroy this data source.
</description>
</event>
</interface>
<interface name="ext_data_control_offer_v1" version="1">
<description summary="offer to transfer data">
A ext_data_control_offer represents a piece of data offered for transfer
by another client (the source client). The offer describes the different
MIME types that the data can be converted to and provides the mechanism
for transferring the data directly from the source client.
</description>
<request name="receive">
<description summary="request that the data is transferred">
To transfer the offered data, the client issues this request and
indicates the MIME type it wants to receive. The transfer happens
through the passed file descriptor (typically created with the pipe
system call). The source client writes the data in the MIME type
representation requested and then closes the file descriptor.
The receiving client reads from the read end of the pipe until EOF and
then closes its end, at which point the transfer is complete.
This request may happen multiple times for different MIME types.
</description>
<arg name="mime_type" type="string"
summary="MIME type desired by receiver"/>
<arg name="fd" type="fd" summary="file descriptor for data transfer"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy this offer">
Destroys the data offer object.
</description>
</request>
<event name="offer">
<description summary="advertise offered MIME type">
Sent immediately after creating the ext_data_control_offer object.
One event per offered MIME type.
</description>
<arg name="mime_type" type="string" summary="offered MIME type"/>
</event>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml
+1 -1
View File
@@ -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
local/recipes/wayland/wayland-protocols/source/staging/ext-idle-notify/ext-idle-notify-v1.xml
+34 -5
View File
@@ -24,7 +24,7 @@
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="ext_idle_notifier_v1" version="1">
<interface name="ext_idle_notifier_v1" version="2">
<description summary="idle notification manager">
This interface allows clients to monitor user idle status.
@@ -54,9 +54,30 @@
<arg name="timeout" type="uint" summary="minimum idle timeout in msec"/>
<arg name="seat" type="object" interface="wl_seat"/>
</request>
<!-- Version 2 additions -->
<request name="get_input_idle_notification" since="2">
<description summary="create a notification object">
Create a new idle notification object to track input from the
user, such as keyboard and mouse movement. Because this object is
meant to track user input alone, it ignores idle inhibitors.
The notification object has a minimum timeout duration and is tied to a
seat. The client will be notified if the seat is inactive for at least
the provided timeout. See ext_idle_notification_v1 for more details.
A zero timeout is valid and means the client wants to be notified as
soon as possible when the seat is inactive.
</description>
<arg name="id" type="new_id" interface="ext_idle_notification_v1"/>
<arg name="timeout" type="uint" summary="minimum idle timeout in msec"/>
<arg name="seat" type="object" interface="wl_seat"/>
</request>
</interface>
<interface name="ext_idle_notification_v1" version="1">
<interface name="ext_idle_notification_v1" version="2">
<description summary="idle notification">
This interface is used by the compositor to send idle notification events
to clients.
@@ -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,
local/recipes/wayland/wayland-protocols/source/staging/ext-image-capture-source/ext-image-capture-source-v1.xml
+1 -1
View File
@@ -39,7 +39,7 @@
only be done by creating a new major version of the extension.
</description>
<interface name="ext_image_capture_source_v1" version="1">
<interface name="ext_image_capture_source_v1" version="1" frozen="true">
<description summary="opaque image capture source object">
The image capture source object is an opaque descriptor for a capturable
resource. This resource may be any sort of entity from which an image
local/recipes/wayland/wayland-protocols/source/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml
+2 -2
View File
@@ -376,7 +376,7 @@
</description>
<enum name="error">
<entry name="duplicate_session" value="1" summary="get_captuerer_session sent twice"/>
<entry name="duplicate_session" value="1" summary="get_capture_session sent twice"/>
</enum>
<request name="destroy" type="destructor">
@@ -390,7 +390,7 @@
</request>
<request name="get_capture_session">
<description summary="get image copy captuerer session">
<description summary="get image copy capturer session">
Gets the image copy capture session for this cursor session.
The session will produce frames of the cursor image. The compositor may
local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/README
+5
View File
@@ -0,0 +1,5 @@
Workspace protocol
Maintainers:
Ilia Bozhinov <ammen99@gmail.com>
Victoria Brekenfeld <wayland@drakulix.de>
local/recipes/wayland/wayland-protocols/source/staging/ext-workspace/ext-workspace-v1.xml
+422
View File
@@ -0,0 +1,422 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ext_workspace_v1">
<copyright>
Copyright © 2019 Christopher Billington
Copyright © 2020 Ilia Bozhinov
Copyright © 2022 Victoria Brekenfeld
Permission to use, copy, modify, distribute, and sell this
software and its documentation for any purpose is hereby granted
without fee, provided that the above copyright notice appear in
all copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
the copyright holders not be used in advertising or publicity
pertaining to distribution of the software without specific,
written prior permission. The copyright holders make no
representations about the suitability of this software for any
purpose. It is provided "as is" without express or implied
warranty.
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.
</copyright>
<interface name="ext_workspace_manager_v1" version="1">
<description summary="list and control workspaces">
Workspaces, also called virtual desktops, are groups of surfaces. A
compositor with a concept of workspaces may only show some such groups of
surfaces (those of 'active' workspaces) at a time. 'Activating' a
workspace is a request for the compositor to display that workspace's
surfaces as normal, whereas the compositor may hide or otherwise
de-emphasise surfaces that are associated only with 'inactive' workspaces.
Workspaces are grouped by which sets of outputs they correspond to, and
may contain surfaces only from those outputs. In this way, it is possible
for each output to have its own set of workspaces, or for all outputs (or
any other arbitrary grouping) to share workspaces. Compositors may
optionally conceptually arrange each group of workspaces in an
N-dimensional grid.
The purpose of this protocol is to enable the creation of taskbars and
docks by providing them with a list of workspaces and their properties,
and allowing them to activate and deactivate workspaces.
After a client binds the ext_workspace_manager_v1, each workspace will be
sent via the workspace event.
</description>
<event name="workspace_group">
<description summary="a workspace group has been created">
This event is emitted whenever a new workspace group has been created.
All initial details of the workspace group (outputs) will be
sent immediately after this event via the corresponding events in
ext_workspace_group_handle_v1 and ext_workspace_handle_v1.
</description>
<arg name="workspace_group" type="new_id" interface="ext_workspace_group_handle_v1"/>
</event>
<event name="workspace">
<description summary="workspace has been created">
This event is emitted whenever a new workspace has been created.
All initial details of the workspace (name, coordinates, state) will
be sent immediately after this event via the corresponding events in
ext_workspace_handle_v1.
Workspaces start off unassigned to any workspace group.
</description>
<arg name="workspace" type="new_id" interface="ext_workspace_handle_v1"/>
</event>
<request name="commit">
<description summary="all requests about the workspaces have been sent">
The client must send this request after it has finished sending other
requests. The compositor must process a series of requests preceding a
commit request atomically.
This allows changes to the workspace properties to be seen as atomic,
even if they happen via multiple events, and even if they involve
multiple ext_workspace_handle_v1 objects, for example, deactivating one
workspace and activating another.
</description>
</request>
<event name="done">
<description summary="all information about the workspaces and workspace groups has been sent">
This event is sent after all changes in all workspaces and workspace groups have been
sent.
This allows changes to one or more ext_workspace_group_handle_v1
properties and ext_workspace_handle_v1 properties
to be seen as atomic, even if they happen via multiple events.
In particular, an output moving from one workspace group to
another sends an output_enter event and an output_leave event to the two
ext_workspace_group_handle_v1 objects in question. The compositor sends
the done event only after updating the output information in both
workspace groups.
</description>
</event>
<event name="finished" type="destructor">
<description summary="the compositor has finished with the workspace_manager">
This event indicates that the compositor is done sending events to the
ext_workspace_manager_v1. The server will destroy the object
immediately after sending this request.
</description>
</event>
<request name="stop">
<description summary="stop sending events">
Indicates the client no longer wishes to receive events for new
workspace groups. However the compositor may emit further workspace
events, until the finished event is emitted. The compositor is expected
to send the finished event eventually once the stop request has been processed.
The client must not send any requests after this one, doing so will raise a wl_display
invalid_object error.
</description>
</request>
</interface>
<interface name="ext_workspace_group_handle_v1" version="1">
<description summary="a workspace group assigned to a set of outputs">
A ext_workspace_group_handle_v1 object represents a workspace group
that is assigned a set of outputs and contains a number of workspaces.
The set of outputs assigned to the workspace group is conveyed to the client via
output_enter and output_leave events, and its workspaces are conveyed with
workspace events.
For example, a compositor which has a set of workspaces for each output may
advertise a workspace group (and its workspaces) per output, whereas a compositor
where a workspace spans all outputs may advertise a single workspace group for all
outputs.
</description>
<enum name="group_capabilities" bitfield="true">
<entry name="create_workspace" value="1" summary="create_workspace request is available"/>
</enum>
<event name="capabilities">
<description summary="compositor capabilities">
This event advertises the capabilities supported by the compositor. If
a capability isn't supported, clients should hide or disable the UI
elements that expose this functionality. For instance, if the
compositor doesn't advertise support for creating workspaces, a button
triggering the create_workspace request should not be displayed.
The compositor will ignore requests it doesn't support. For instance,
a compositor which doesn't advertise support for creating workspaces will ignore
create_workspace requests.
Compositors must send this event once after creation of an
ext_workspace_group_handle_v1. When the capabilities change, compositors
must send this event again.
</description>
<arg name="capabilities" type="uint" summary="capabilities" enum="group_capabilities"/>
</event>
<event name="output_enter">
<description summary="output assigned to workspace group">
This event is emitted whenever an output is assigned to the workspace
group or a new `wl_output` object is bound by the client, which was already
assigned to this workspace_group.
</description>
<arg name="output" type="object" interface="wl_output"/>
</event>
<event name="output_leave">
<description summary="output removed from workspace group">
This event is emitted whenever an output is removed from the workspace
group.
</description>
<arg name="output" type="object" interface="wl_output"/>
</event>
<event name="workspace_enter">
<description summary="workspace added to workspace group">
This event is emitted whenever a workspace is assigned to this group.
A workspace may only ever be assigned to a single group at a single point
in time, but can be re-assigned during its lifetime.
</description>
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
</event>
<event name="workspace_leave">
<description summary="workspace removed from workspace group">
This event is emitted whenever a workspace is removed from this group.
</description>
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
</event>
<event name="removed">
<description summary="this workspace group has been removed">
This event is send when the group associated with the ext_workspace_group_handle_v1
has been removed. After sending this request the compositor will immediately consider
the object inert. Any requests will be ignored except the destroy request.
It is guaranteed there won't be any more events referencing this
ext_workspace_group_handle_v1.
The compositor must remove all workspaces belonging to a workspace group
via a workspace_leave event before removing the workspace group.
</description>
</event>
<request name="create_workspace">
<description summary="create a new workspace">
Request that the compositor create a new workspace with the given name
and assign it to this group.
There is no guarantee that the compositor will create a new workspace,
or that the created workspace will have the provided name.
</description>
<arg name="workspace" type="string"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy the ext_workspace_group_handle_v1 object">
Destroys the ext_workspace_group_handle_v1 object.
This request should be send either when the client does not want to
use the workspace group object any more or after the removed event to finalize
the destruction of the object.
</description>
</request>
</interface>
<interface name="ext_workspace_handle_v1" version="1">
<description summary="a workspace handing a group of surfaces">
A ext_workspace_handle_v1 object represents a workspace that handles a
group of surfaces.
Each workspace has:
- a name, conveyed to the client with the name event
- potentially an id conveyed with the id event
- a list of states, conveyed to the client with the state event
- and optionally a set of coordinates, conveyed to the client with the
coordinates event
The client may request that the compositor activate or deactivate the workspace.
Each workspace can belong to only a single workspace group.
Depending on the compositor policy, there might be workspaces with
the same name in different workspace groups, but these workspaces are still
separate (e.g. one of them might be active while the other is not).
</description>
<event name="id">
<description summary="workspace id">
If this event is emitted, it will be send immediately after the
ext_workspace_handle_v1 is created or when an id is assigned to
a workspace (at most once during its lifetime).
An id will never change during the lifetime of the `ext_workspace_handle_v1`
and is guaranteed to be unique during its lifetime.
Ids are not human-readable and shouldn't be displayed, use `name` for that purpose.
Compositors are expected to only send ids for workspaces likely stable across multiple
sessions and can be used by clients to store preferences for workspaces. Workspaces without
ids should be considered temporary and any data associated with them should be deleted once
the respective object is lost.
</description>
<arg name="id" type="string"/>
</event>
<event name="name">
<description summary="workspace name changed">
This event is emitted immediately after the ext_workspace_handle_v1 is
created and whenever the name of the workspace changes.
A name is meant to be human-readable and can be displayed to a user.
Unlike the id it is neither stable nor unique.
</description>
<arg name="name" type="string"/>
</event>
<event name="coordinates">
<description summary="workspace coordinates changed">
This event is used to organize workspaces into an N-dimensional grid
within a workspace group, and if supported, is emitted immediately after
the ext_workspace_handle_v1 is created and whenever the coordinates of
the workspace change. Compositors may not send this event if they do not
conceptually arrange workspaces in this way. If compositors simply
number workspaces, without any geometric interpretation, they may send
1D coordinates, which clients should not interpret as implying any
geometry. Sending an empty array means that the compositor no longer
orders the workspace geometrically.
Coordinates have an arbitrary number of dimensions N with an uint32
position along each dimension. By convention if N > 1, the first
dimension is X, the second Y, the third Z, and so on. The compositor may
chose to utilize these events for a more novel workspace layout
convention, however. No guarantee is made about the grid being filled or
bounded; there may be a workspace at coordinate 1 and another at
coordinate 1000 and none in between. Within a workspace group, however,
workspaces must have unique coordinates of equal dimensionality.
</description>
<arg name="coordinates" type="array"/>
</event>
<enum name="state" bitfield="true">
<description summary="types of states on the workspace">
The different states that a workspace can have.
</description>
<entry name="active" value="1" summary="the workspace is active"/>
<entry name="urgent" value="2" summary="the workspace requests attention"/>
<entry name="hidden" value="4">
<description summary="the workspace is not visible">
The workspace is not visible in its workspace group, and clients
attempting to visualize the compositor workspace state should not
display such workspaces.
</description>
</entry>
</enum>
<event name="state">
<description summary="the state of the workspace changed">
This event is emitted immediately after the ext_workspace_handle_v1 is
created and each time the workspace state changes, either because of a
compositor action or because of a request in this protocol.
Missing states convey the opposite meaning, e.g. an unset active bit
means the workspace is currently inactive.
</description>
<arg name="state" type="uint" enum="state"/>
</event>
<enum name="workspace_capabilities" bitfield="true">
<entry name="activate" value="1" summary="activate request is available"/>
<entry name="deactivate" value="2" summary="deactivate request is available"/>
<entry name="remove" value="4" summary="remove request is available"/>
<entry name="assign" value="8" summary="assign request is available"/>
</enum>
<event name="capabilities">
<description summary="compositor capabilities">
This event advertises the capabilities supported by the compositor. If
a capability isn't supported, clients should hide or disable the UI
elements that expose this functionality. For instance, if the
compositor doesn't advertise support for removing workspaces, a button
triggering the remove request should not be displayed.
The compositor will ignore requests it doesn't support. For instance,
a compositor which doesn't advertise support for remove will ignore
remove requests.
Compositors must send this event once after creation of an
ext_workspace_handle_v1 . When the capabilities change, compositors
must send this event again.
</description>
<arg name="capabilities" type="uint" summary="capabilities" enum="workspace_capabilities"/>
</event>
<event name="removed">
<description summary="this workspace has been removed">
This event is send when the workspace associated with the ext_workspace_handle_v1
has been removed. After sending this request, the compositor will immediately consider
the object inert. Any requests will be ignored except the destroy request.
It is guaranteed there won't be any more events referencing this
ext_workspace_handle_v1.
The compositor must only remove a workspaces not currently belonging to any
workspace_group.
</description>
</event>
<request name="destroy" type="destructor">
<description summary="destroy the ext_workspace_handle_v1 object">
Destroys the ext_workspace_handle_v1 object.
This request should be made either when the client does not want to
use the workspace object any more or after the remove event to finalize
the destruction of the object.
</description>
</request>
<request name="activate">
<description summary="activate the workspace">
Request that this workspace be activated.
There is no guarantee the workspace will be actually activated, and
behaviour may be compositor-dependent. For example, activating a
workspace may or may not deactivate all other workspaces in the same
group.
</description>
</request>
<request name="deactivate">
<description summary="deactivate the workspace">
Request that this workspace be deactivated.
There is no guarantee the workspace will be actually deactivated.
</description>
</request>
<request name="assign">
<description summary="assign workspace to group">
Requests that this workspace is assigned to the given workspace group.
There is no guarantee the workspace will be assigned.
</description>
<arg name="workspace_group" type="object" interface="ext_workspace_group_handle_v1"/>
</request>
<request name="remove">
<description summary="remove the workspace">
Request that this workspace be removed.
There is no guarantee the workspace will be actually removed.
</description>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/README
+7
View File
@@ -0,0 +1,7 @@
pointer-warp protocol
Maintainers:
Neal Gompa <neal@gompa.dev> (@Conan_Kudo)
Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)
Matthias Klumpp <matthias@tenstral.net> (@mak)
Vlad Zahorodnii <vlad.zahorodnii@kde.org> (@zzag)
local/recipes/wayland/wayland-protocols/source/staging/pointer-warp/pointer-warp-v1.xml
+72
View File
@@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="pointer_warp_v1">
<copyright>
Copyright © 2024 Neal Gompa
Copyright © 2024 Xaver Hugl
Copyright © 2024 Matthias Klumpp
Copyright © 2024 Vlad Zahorodnii
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="wp_pointer_warp_v1" version="1">
<description summary="reposition the pointer to a location on a surface">
This global interface allows applications to request the pointer to be
moved to a position relative to a wl_surface.
Note that if the desired behavior is to constrain the pointer to an area
or lock it to a position, this protocol does not provide a reliable way
to do that. The pointer constraint and pointer lock protocols should be
used for those use cases instead.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the warp manager">
Destroy the pointer warp manager.
</description>
</request>
<request name="warp_pointer">
<description summary="reposition the pointer">
Request the compositor to move the pointer to a surface-local position.
Whether or not the compositor honors the request is implementation defined,
but it should
- honor it if the surface has pointer focus, including
when it has an implicit pointer grab
- reject it if the enter serial is incorrect
- reject it if the requested position is outside of the surface
Note that the enter serial is valid for any surface of the client,
and does not have to be from the surface the pointer is warped to.
</description>
<arg name="surface" type="object" interface="wl_surface"
summary="surface to position the pointer on"/>
<arg name="pointer" type="object" interface="wl_pointer"
summary="the pointer that should be repositioned"/>
<arg name="x" type="fixed"/>
<arg name="y" type="fixed"/>
<arg name="serial" type="uint" summary="serial number of the enter event"/>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/staging/single-pixel-buffer/single-pixel-buffer-v1.xml
+7
View File
@@ -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
</description>
<arg name="id" type="new_id" interface="wl_buffer"/>
<arg name="r" type="uint" summary="value of the buffer's red channel"/>
local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/README
+5
View File
@@ -0,0 +1,5 @@
xdg session management protocol
Maintainers:
Jonas Ådahl <jadahl@gmail.com>
Mike Blumenkrantz <michael.blumenkrantz@gmail.com>
local/recipes/wayland/wayland-protocols/source/staging/xdg-session-management/xdg-session-management-v1.xml
+333
View File
@@ -0,0 +1,333 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xdg_session_management_v1">
<copyright>
Copyright 2018 Mike Blumenkrantz
Copyright 2018 Samsung Electronics Co., Ltd
Copyright 2018 Red Hat Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="Protocol for managing application sessions">
This description provides a high-level overview of the interplay between
the interfaces defined this protocol. For details, see the protocol
specification.
The xdg_session_manager protocol declares interfaces necessary to
allow clients to restore toplevel state from previous executions. The
xdg_session_manager_v1.get_session request can be used to obtain a
xdg_session_v1 resource representing the state of a set of toplevels.
Clients may obtain the session string to use in future calls through
the xdg_session_v1.created event. Compositors will use this string
as an identifiable token for future runs, possibly storing data about
the related toplevels in persistent storage. Clients that wish to
track sessions in multiple environments may use the $XDG_CURRENT_DESKTOP
environment variable.
Toplevels are managed through the xdg_session_v1.add_toplevel and
xdg_session_v1.remove_toplevel pair of requests. Clients will explicitly
request a toplevel to be restored according to prior state through the
xdg_session_v1.restore_toplevel request before the toplevel is mapped.
Compositors may store session information up to any arbitrary level, and
apply any limits and policies to the amount of data stored and its lifetime.
Clients must account for missing sessions and partial session restoration.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<interface name="xdg_session_manager_v1" version="1">
<description summary="manage sessions for applications">
The xdg_session_manager_v1 interface defines base requests for creating and
managing a session for an application. Sessions persist across application
and compositor restarts unless explicitly destroyed. A session is created
for the purpose of maintaining an application's xdg_toplevel surfaces
across compositor or application restarts. The compositor should remember
as many states as possible for surfaces in a given session, but there is
no requirement for which states must be remembered.
Policies such as cache eviction are declared an implementation detail of
the compositor. Clients should account for no longer existing sessions.
</description>
<enum name="error">
<entry name="in_use" summary="a requested session is already in use"
value="1"/>
<entry name="invalid_session_id" summary="invalid session identifier"
value="2"/>
<entry name="invalid_reason" summary="invalid reason" value="3"/>
</enum>
<enum name="reason">
<description summary="reason for getting a session">
The reason may determine in what way a session restores the window
management state of associated toplevels.
For example newly launched applications might be launched on the active
workspace with restored size and position, while a recovered
application might restore additional state such as active workspace and
stacking order.
</description>
<entry name="launch" value="1">
<description summary="an app is newly launched">
A new app instance is launched, for example from an app launcher.
</description>
</entry>
<entry name="recover" value="2">
<description summary="an app recovered">
An app instance is recovering from for example a compositor or app crash.
</description>
</entry>
<entry name="session_restore" value="3">
<description summary="an app restored">
An app instance is restored, for example part of a restored session, or
restored from having been temporarily terminated due to resource
constraints.
</description>
</entry>
</enum>
<request name="destroy" type="destructor">
<description summary="Destroy this object">
Destroy the manager object. The existing session objects will be
unaffected.
</description>
</request>
<request name="get_session">
<description summary="create or restore a session">
Create a session object corresponding to either an existing session
identified by the given session identifier string or a new session.
While the session object exists, the session is considered to be "in
use".
If an identifier string represents a session that is currently actively
in use by the the same client, an 'in_use' error is raised. If some
other client is currently using the same session, the new session will
replace managing the associated state.
If the reason is not a valid enum entry, the 'invalid_reason' protocol
error is raised.
NULL is passed to initiate a new session. If a session_id is passed
which does not represent a valid session, the compositor treats it as if
NULL had been passed.
The session id string must be UTF-8 encoded. It is also limited by the
maximum length of wayland messages (around 4KB). The 'invalid_session_id'
protocol error will be raised if an invalid string is provided.
A client is allowed to have any number of in use sessions at the same
time.
</description>
<arg name="id" type="new_id" interface="xdg_session_v1"/>
<arg name="reason" type="uint" enum="reason"
summary="reason for session"/>
<arg name="session_id" type="string"
summary="the session to restore"
allow-null="true"/>
</request>
</interface>
<interface name="xdg_session_v1" version="1">
<description summary="A session for an application">
A xdg_session_v1 object represents a session for an application. While the
object exists, all surfaces which have been added to the session will
have states stored by the compositor which can be reapplied at a later
time. Two sessions cannot exist for the same identifier string.
States for surfaces added to a session are automatically updated by the
compositor when they are changed.
</description>
<enum name="error">
<entry name="name_in_use"
summary="toplevel name is already in use"
value="1"/>
<entry name="already_mapped"
summary="toplevel was already mapped when restored"
value="2"/>
<entry name="invalid_name"
summary="provided toplevel name is invalid"
value="3"/>
<entry name="already_added"
summary="toplevel already added"
value="4"/>
</enum>
<request name="destroy" type="destructor">
<description summary="Destroy the session">
Destroy a session object, preserving the current state but not continuing
to make further updates if state changes occur. This makes the associated
xdg_toplevel_session_v1 objects inert.
</description>
</request>
<request name="remove" type="destructor">
<description summary="Remove the session">
Remove the session, making it no longer available for restoration. A
compositor should in response to this request remove the data related to
this session from its storage.
</description>
</request>
<request name="add_toplevel">
<description summary="add a new surface to the session">
Attempt to add a given surface to the session. The passed name is used
to identify what window is being restored, and may be used to store
window specific state within the session.
The name given to the toplevel must not correspond to any previously
existing toplevel names in the session. If the name matches an already
known toplevel name in the session, a 'name_in_use' protocol error will
be raised.
The toplevel object must not be added more than once to any session
created by the client, otherwise the 'already_added' protocol error
will be raised.
This request will return a xdg_toplevel_session_v1 for later
manipulation. As this resource is created from an empty initial state,
compositors must not emit a xdg_toplevel_session_v1.restored event for
resources created through this request.
The name string must be UTF-8 encoded. It is also limited by the maximum
length of wayland messages (around 4KB). The 'invalid_name' protocol
error will be raised if an invalid string is provided.
</description>
<arg name="id" type="new_id" interface="xdg_toplevel_session_v1"/>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
<arg name="name" type="string" summary="name identifying the toplevel"/>
</request>
<request name="restore_toplevel">
<description summary="restore a surface state">
Inform the compositor that the toplevel associated with the passed name
should have its window management state restored.
If the toplevel name was previously granted to another xdg_toplevel,
the 'name_in_use' protocol error will be raised.
The toplevel object must not be added more than once to any session
created by the client, otherwise the 'already_added' protocol error
will be raised.
This request must be called prior to the first commit on the associated
wl_surface after creating the toplevel, otherwise an 'already_mapped'
error is raised.
As part of the initial configure sequence, if the toplevel was
successfully restored, a xdg_toplevel_session_v1.restored event is
emitted. If the toplevel name was not known in the session, this request
will be equivalent to the xdg_toplevel_session_v1.add_toplevel request,
and no such event will be emitted. See the xdg_toplevel_session_v1.restored
event for further details.
The name string must be UTF-8 encoded. It is also limited by the maximum
length of wayland messages (around 4KB). The 'invalid_name' protocol
error will be raised if an invalid string is provided.
</description>
<arg name="id" type="new_id" interface="xdg_toplevel_session_v1"/>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
<arg name="name" type="string" summary="name identifying the toplevel"/>
</request>
<request name="remove_toplevel">
<description summary="remove a surface from the session">
Remove a specified surface from the session and render any related
xdg_toplevel_session_v1 object inert. The compositor should remove any
data related to the toplevel in the corresponding session from its internal
storage.
The window is specified by its name in the session. The name string
must be encoded in UTF-8, and it is limited in size by the maximum
length of wayland messages (around 4KB).
</description>
<arg name="name" type="string" summary="name identifying the toplevel"/>
</request>
<event name="created">
<description summary="newly-created session id">
Emitted at most once some time after getting a new session object. It
means that no previous state was restored, and a new session was created.
The passed id can be persistently stored and used to restore previous
sessions.
</description>
<arg name="session_id" type="string"/>
</event>
<event name="restored">
<description summary="the session has been restored">
Emitted at most once some time after getting a new session object. It
means that previous state was at least partially restored. The same id
can again be used to restore previous sessions.
</description>
</event>
<event name="replaced">
<description summary="the session has been replaced">
Emitted at most once, if the session was taken over by some other
client. When this happens, the session and all its toplevel session
objects become inert, and should be destroyed.
</description>
</event>
</interface>
<interface name="xdg_toplevel_session_v1" version="1">
<description summary="A session for an application">
A xdg_toplevel_session_v1 resource acts as a handle for the given
toplevel in the session. It allows for receiving events after a
toplevel state was restored, and has the requests to manage them.
</description>
<request name="destroy" type="destructor">
<description summary="Destroy the object">
Destroy the object. This has no effect over window management of the
associated toplevel.
</description>
</request>
<request name="rename">
<description summary="change the name of toplevel session">
Renames the toplevel session. The new name can be used in subsequent requests
to identify this session object. The state associated with this toplevel
session will be preserved.
If the xdg_session_v1 already contains a toplevel with the specified name,
the 'name_in_use' protocol error will be raised.
</description>
<arg name="name" type="string" summary="new name to identify the toplevel"/>
</request>
<event name="restored">
<description summary="a toplevel's session has been restored">
The "restored" event is emitted prior to the first
xdg_toplevel.configure for the toplevel. It will only be emitted after
xdg_session_v1.restore_toplevel, and the initial empty surface state has
been applied, and it indicates that the surface's session is being
restored with this configure event.
</description>
</event>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-drag/README
+1
View File
@@ -2,3 +2,4 @@ xdg toplevel drag protocol
Maintainers:
David Redondo <kde@david-redondo.de> (@davidre)
Nick Yamane <nickdiego@igalia.com> (@nickdiego)
local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-icon/xdg-toplevel-icon-v1.xml
+6 -6
View File
@@ -107,7 +107,7 @@
'done' event, without any preceding 'icon_size' events.
</description>
<arg name="size" type="int"
summary="the edge size of the square icon in surface-local coordinates, e.g. 64"/>
summary="the edge size of the square icon in surface-local coordinates, e.g. 64"/>
</event>
<event name="done">
@@ -132,10 +132,10 @@
<enum name="error">
<entry name="invalid_buffer"
summary="the provided buffer does not satisfy requirements"
value="1"/>
value="1"/>
<entry name="immutable"
summary="the icon has already been assigned to a toplevel and must not be changed"
value="2"/>
value="2"/>
<entry name="no_buffer"
summary="the provided buffer has been destroyed before the toplevel icon"
value="3"/>
@@ -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
</description>
@@ -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.
</description>
<arg name="buffer" type="object" interface="wl_buffer"/>
<arg name="scale" type="int"
summary="the scaling factor of the icon, e.g. 1"/>
summary="the scaling factor of the icon, e.g. 1"/>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/README
+4
View File
@@ -0,0 +1,4 @@
Toplevel tag protocol
Maintainers:
Xaver Hugl <xaver.hugl@kde.org>
local/recipes/wayland/wayland-protocols/source/staging/xdg-toplevel-tag/xdg-toplevel-tag-v1.xml
+85
View File
@@ -0,0 +1,85 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xdg_toplevel_tag_v1">
<copyright>
Copyright © 2024 Xaver Hugl
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="xdg_toplevel_tag_manager_v1" version="1">
<description summary="protocol for setting toplevel tags">
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.
</description>
<request name="destroy" type="destructor">
<description summary="destroy toplevel tag object">
Destroy this toplevel tag manager object. This request has no other
effects.
</description>
</request>
<request name="set_toplevel_tag">
<description summary="set tag">
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.
</description>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
<arg name="tag" type="string" summary="untranslated tag"/>
</request>
<request name="set_toplevel_description">
<description summary="set description">
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.
</description>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
<arg name="description" type="string" summary="translated description"/>
</request>
</interface>
</protocol>
local/recipes/wayland/wayland-protocols/source/tests/meson.build
+32 -13
View File
@@ -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',
local/recipes/wayland/wayland-protocols/source/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml
+26 -2
View File
@@ -1,5 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="pointer_gestures_unstable_v1">
<copyright>
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.
</copyright>
<interface name="zwp_pointer_gestures_v1" version="3">
<description summary="touchpad gestures">
@@ -61,7 +85,7 @@
</interface>
<interface name="zwp_pointer_gesture_swipe_v1" version="2">
<interface name="zwp_pointer_gesture_swipe_v1" version="3">
<description summary="a swipe gesture object">
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 @@
</event>
</interface>
<interface name="zwp_pointer_gesture_pinch_v1" version="2">
<interface name="zwp_pointer_gesture_pinch_v1" version="3">
<description summary="a pinch gesture object">
A pinch gesture object notifies a client about a multi-finger pinch
gesture detected on an indirect input device such as a touchpad.
local/recipes/wayland/wayland-protocols/source/unstable/text-input/text-input-unstable-v3.xml
+155 -8
View File
@@ -47,7 +47,7 @@
interface version number is reset.
</description>
<interface name="zwp_text_input_v3" version="1">
<interface name="zwp_text_input_v3" version="2">
<description summary="text input">
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 @@
<entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
<entry name="latin" value="0x100" summary="just Latin characters should be entered"/>
<entry name="multiline" value="0x200" summary="the text input is multiline"/>
<entry
name="on_screen_input_provided" value="0x400" since="2"
summary="an on-screen way to fill in the input is already provided by the client"/>
<entry
name="no_emoji" value="0x800" since="2"
summary="prefer not offering emoji support"/>
<entry
name="preedit_shown" value="0x1000" since="2"
summary="the text input will display preedit text in place"/>
</enum>
<enum name="content_purpose">
@@ -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.
</description>
<arg name="x" type="int"/>
<arg name="y" type="int"/>
@@ -404,8 +425,10 @@
<event name="done">
<description summary="apply changes">
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 @@
</description>
<arg name="serial" type="uint"/>
</event>
<!-- Version 2 additions -->
<enum name="error" since="2">
<entry name="invalid_action" value="0" summary="an invalid or duplicate action was specified"/>
</enum>
<enum name="action" since="2">
<description summary="action">
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.
</description>
<entry name="none" value="0" summary="no action"/>
<entry name="submit" value="1" summary="the action is submitted"/>
</enum>
<event name="action" since="2">
<description summary="action performed">
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.
</description>
<arg name="action" type="uint" enum="action" summary="action performed"/>
<arg name="serial" type="uint" summary="serial number of the action event"/>
</event>
<event name="language" since="2">
<description summary="notify of language selection">
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.
</description>
<arg name="language" type="string" summary="new language set by IME"/>
</event>
<request name="set_available_actions" since="2">
<description summary="set the available actions">
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.
</description>
<arg name="available_actions" type="array" summary="available actions"/>
</request>
<request name="show_input_panel" since="2">
<description summary="show input panel">
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.
</description>
</request>
<request name="hide_input_panel" since="2">
<description summary="hide input panel">
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.
</description>
</request>
<enum name="preedit_hint">
<description summary="preedit style hint">
Style hints for the preedit string.
</description>
<entry name="whole" value="1" summary="simple pre-edit text style, typically underlined"/>
<entry name="selection" value="2"
summary="hint for a selected piece of text, e.g. per-character navigation and composition"/>
<entry name="prediction" value="3" summary="predicted text, not typed by the user"/>
<entry name="prefix" value="4"
summary="prefixed text not being currently edited, e.g. prior to a 'selection' section"/>
<entry name="suffix" value="5"
summary="suffixed text not being currently edited, e.g. after a 'selection' section"/>
<entry name="spelling_error" value="6" summary="spelling error"/>
<entry name="compose_error" value="7"
summary="wrong composition, e.g. user input that can not be transliterated"/>
</enum>
<event name="preedit_hint" since="2">
<description summary="pre-edit">
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.
</description>
<arg name="start" type="uint" summary="starting point of the affected substring"/>
<arg name="end" type="uint" summary="end point of the affected substring"/>
<arg name="hint" type="uint" enum="preedit_hint" summary="hint to apply"/>
</event>
</interface>
<interface name="zwp_text_input_manager_v3" version="1">
<interface name="zwp_text_input_manager_v3" version="2">
<description summary="text input manager">
A factory for text-input objects. This object is a global singleton.
</description>
local/recipes/wayland/wayland-protocols/source/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml
+24 -8
View File
@@ -23,7 +23,7 @@
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="zxdg_decoration_manager_v1" version="1">
<interface name="zxdg_decoration_manager_v1" version="2">
<description summary="window decoration manager">
This interface allows a compositor to announce support for server-side
decorations.
@@ -60,18 +60,33 @@
<description summary="create a new toplevel decoration object">
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.
</description>
<arg name="id" type="new_id" interface="zxdg_toplevel_decoration_v1"/>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
</request>
</interface>
<interface name="zxdg_toplevel_decoration_v1" version="1">
<interface name="zxdg_toplevel_decoration_v1" version="2">
<description summary="decoration object for a toplevel surface">
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 @@
<request name="destroy" type="destructor">
<description summary="destroy the decoration object">
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.
</description>
</request>
local/recipes/wayland/wayland-protocols/source/wayland-protocols-uninstalled.pc.in
-5
View File
@@ -1,5 +0,0 @@
pkgdatadir=@abs_top_srcdir@
Name: Wayland Protocols
Description: Wayland protocol files (not installed)
Version: @WAYLAND_PROTOCOLS_VERSION@
local/recipes/wayland/wayland-protocols/source/wayland-protocols.pc.in
-7
View File
@@ -1,7 +0,0 @@
prefix=@prefix@
datarootdir=@datarootdir@
pkgdatadir=${pc_sysrootdir}${datarootdir}/@PACKAGE@
Name: Wayland Protocols
Description: Wayland protocol files
Version: @WAYLAND_PROTOCOLS_VERSION@