Skip to content
Commits on Source (14)
Hide whitespace changes
Inline Side-by-side
.editorconfig 0 → 100644
View file @ b0a25f26
root = true
[*.xml]
indent_style = space
indent_size = 2
tab_width = 8
.gitlab-ci.yml 0 → 100644
View file @ b0a25f26
variables:
DEBIAN_TAG: 2019-11-21.0
DEBIAN_VERSION: stable
TEST_IMAGE: "$CI_REGISTRY_IMAGE/debian/$DEBIAN_VERSION:$DEBIAN_TAG"
include:
- project: 'wayland/ci-templates'
ref: f69acac60d5dde0410124fd5674764600821b7a6
file: '/templates/debian.yml'
stages:
- containers-build
- test
container_build:
extends: .debian@container-ifnot-exists
stage: containers-build
variables:
GIT_STRATEGY: none # no need to pull the whole tree for rebuilding the image
DEBIAN_DEBS: 'build-essential automake autoconf libtool pkg-config libwayland-dev'
test:
stage: test
image: $TEST_IMAGE
script:
- ./autogen.sh
- make check
GOVERNANCE.md 0 → 100644
View file @ b0a25f26
# wayland-protocols governance
This document governs the maintenance of wayland-protocols and serves to outline
the broader process for standardization of protocol extensions in the Wayland
ecosystem.
## 1. Membership
Membership in wayland-protocols is offered to stakeholders in the Wayland
ecosystem who have an interest in participating in protocol extension
standardization.
### 1.1. Membership requirements
1. Membership is extended to projects, rather than individuals.
2. 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
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.
### 1.2. Becoming a member
1. New members 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.
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.
### 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.
3. At the conclusion of the voting period, the member is removed if the votes
total 2/3rds of all current members.
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
call for a re-vote or propose any other removal for 90 days.
## 2. Protocols
### 2.1. Protocol namespaces
1. Namespaces are implemented in practice by prefixing each interface name in a
protocol definition (XML) with the namespace name, and an underscore (e.g.
"xdg_wm_base").
2. Protocols in a namespace may optionally use the namespace followed by a dash
in the name (e.g. "xdg-shell").
3. The "xdg" namespace is established for protocols letting clients
configure its surfaces as "windows", allowing clients to affect how they
are managed.
4. The "wp" namespace is established for protocols generally useful to Wayland
implementations (i.e. "plumbing" protocols).
5. The "ext" namespace is established as a general catch-all for protocols that
fit into no other namespace.
### 2.2. Protocol inclusion requirements
1. All protocols found in the "xdg" and "wp" namespaces at the time of writing
are grandfathered into their respective namespace without further discussion.
2. Protocols in the "xdg" and "wp" namespace are eligible for inclusion only if
ACKed by at least 3 members.
3. Protocols in the "xdg" and "wp" namespace are ineligible for inclusion if
if NACKed by any member.
4. Protocols in the "xdg" and "wp" namespaces must have at least 3 open-source
implementations (either 1 client + 2 servers, or 2 clients + 1 server) to be
eligible for inclusion.
5. Protocols in the "ext" namespace are eligible for inclusion only if ACKed by
at least one other member.
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.
### 2.3. Introducing new protocols
1. A new protocol may be proposed by submitting a merge request to the
wayland-protocols Gitlab repository.
2. Protocol proposal posts must include justification for their inclusion in
their namespace per the requirements outlined in section 2.2.
3. An indefinite discussion period for comments from wayland-protocols members
will be held, with a minimum duration of 30 days. 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 in the wayland-protocol repository.
5. Amendments to existing protocols may be proposed by the same process, with
no minimum discussion period.
6. Declaring a protocol stable may be proposed by the same process, with the
regular 30 day minimum discussion period.
## 3. Protocol adoption documentation
### 3.1. Adoption website
1. This section is informational.
2. A website will be made available for interested parties to browse the
implementation status of protocols included in wayland-protocols.
3. A statement from each member of wayland-protocols will be included on the
site.
4. Each protocol will be listed along with its approval status from each member.
5. The approval statuses are:
1. NACK, or "negative acknowledgement", meaning that the member is opposed to
the protocol in principle.
2. NOPP, or "no opposition", meaning that the member is not opposed to the
protocol in principle, but does not provide an implementation.
3. ACK, or "acknowledged", meaning that the member supports the protocol in
principle, but does not provide an implementation.
4. IMPL, or "implemented", meaning that the member supports the protocol and
provides an implementation.
6. Each member may write a short statement expanding on the rationale for their
approval status, which will be included on the site.
7. A supplementary list of implementations will also be provided on the site,
which may include implementations supported by non-members.
### 3.2. Changes to the adoption website
1. This section is informational.
2. A new protocol is added to the website by the sponsoring member at the
conclusion of the discussion period (section 2.3.3).
3. During the discussion period (section 2.3.3), interested parties may express
their approval status on the Gitlab merge request. The default approval
status for members who do not participate in the discussion is "NOPP".
4. Members may change their acknowledgement status or support statement at any
time after the discussion period (section 2.3.3) has closed by simply merging
their update in the wayland-protocols repository.
## 4. Amending this document
1. An amendment to this document may be proposed any member 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.
MEMBERS.md 0 → 100644
View file @ b0a25f26
# wayland-protocols members
- EFL/Enlightenment: Mike Blumenkrantz <michael.blumenkrantz@gmail.com>
- GTK/Mutter: Jonas Ådahl <jadahl@gmail.com>,
Carlos Garnacho <carlosg@gnome.org>
- KWin: Roman Gilg <subdiff@gmail.com>,
David Edmundson <david@davidedmundson.co.uk>
- Mir: Christopher James Halse Rogers <raof@ubuntu.com>,
Alan Griffiths <alan.griffiths@canonical.com>
- Qt: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>
- Weston: Pekka Paalanen <pekka.paalanen@collabora.com>,
Daniel Stone <daniel@fooishbar.org>
- wlroots/Sway: Drew DeVault <sir@cmpwn.com>, Simon Ser <contact@emersion.fr>
Makefile.am
View file @ b0a25f26
......@@ -39,6 +39,9 @@ nobase_dist_pkgdata_DATA = \
dist_noinst_DATA = \
$(sort $(foreach p,$(unstable_protocols),$(dir $p)README)) \
$(sort $(foreach p,$(stable_protocols),$(dir $p)README)) \
README.md \
GOVERNANCE.md \
MEMBERS.md \
$(NULL)
noarch_pkgconfig_DATA = wayland-protocols.pc
......
README → README.md
View file @ b0a25f26
Wayland protocols
-----------------
# Wayland protocols
wayland-protocols contains Wayland protocols that add functionality not
available in the Wayland core protocol. Such protocols either add
......@@ -11,9 +10,9 @@ A protocol in wayland-protocols consists of a directory containing a set
of XML files containing the protocol specification, and a README file
containing detailed state and a list of maintainers.
Protocol directory tree structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Protocols may be 'stable', 'unstable' or 'deprecated', and the interface
## Protocol directory tree structure
Protocols may be "stable", "unstable" or "deprecated", and the interface
and protocol names as well as place in the directory tree will reflect
this.
......@@ -22,8 +21,8 @@ the maintainers. Changes to such protocols will always be backward
compatible.
An unstable protocol is a protocol currently under development and this
will be reflected in the protocol and interface names. See <<Unstable
naming convention>>.
will be reflected in the protocol and interface names. See [Unstable
naming convention](#unstable-naming-convention).
A deprecated protocol is a protocol that has either been replaced by some
other protocol, or declared undesirable for some other reason. No more
......@@ -31,44 +30,51 @@ changes will be made to a deprecated protocol.
Depending on which of the above states the protocol is in, the protocol
is placed within the toplevel directory containing the protocols with the
same state. Stable protocols are placed in the +stable/+ directory,
unstable protocols are placed in the +unstable/+ directory, and
deprecated protocols are placed in the +deprecated/+ directory.
Protocol development procedure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To propose a new protocol, create a patch adding the relevant files and
Makefile.am entry to the wayland-protocols git repository with the
explanation and motivation in the commit message. Then send the patch to
the wayland-devel@lists.freedesktop.org mailing list using
'git send-email' with the subject prefix 'RFC wayland-protocols' or
'PATCH wayland-protocols' depending on what state the protocol is in.
To propose changes to existing protocols, create a patch with the
changes and send it to the list mentioned above while also CC:ing the
maintainers mentioned in the README file. Use the same rule for adding a
subject prefix as above and method for sending the patch.
same state. Stable protocols are placed in the `stable/` directory,
unstable protocols are placed in the `unstable/` directory, and
deprecated protocols are placed in the `deprecated/` directory.
## Protocol development procedure
To propose a new protocol, create a GitLab merge request adding the
relevant files and Makefile.am entry to the repository with the
explanation and motivation in the commit message. Protocols are
organized in namespaces describing their scope ("wp", "xdg" and "ext").
There are different requirements for each namespace, see [GOVERNANCE
section 2](GOVERNANCE.md#2-protocols) for more information.
If the new protocol is just an idea, open an issue on the GitLab issue
tracker. If the protocol isn't ready for complete review yet and is an
RFC, create a merge request and add the "WIP:" prefix in the title.
To propose changes to existing protocols, create a GitLab merge request.
If the changes are backward incompatible changes to an unstable protocol,
see <<Unstable protocol changes>>.
see [Unstable protocol changes](#unstable-protocol-changes).
## Interface naming convention
Interface naming convention
~~~~~~~~~~~~~~~~~~~~~~~~~~~
All protocols should avoid using generic namespaces or no namespaces in
the protocol interface names in order to minimize risk that the generated
C API collides with other C API. Interface names that may collide with
interface names from other protocols should also be avoided.
For generic protocols not limited to certain configurations (such as
specific desktop environment or operating system) the +wp_+ prefix
specific desktop environment or operating system) the `wp_` prefix
should be used on all interfaces in the protocol.
For protocols allowing clients to configure how their windows are
managed, the `xdg_` prefix should be used.
For operating system specific protocols, the interfaces should be
prefixed with both +wp_+ and the operating system, for example
+wp_linux_+, or +wp_freebsd_+, etc.
prefixed with both `wp_` and the operating system, for example
`wp_linux_`, or `wp_freebsd_`, etc.
For more information about namespaces, see [GOVERNANCE section 2.1
](GOVERNANCE.md#21-protocol-namespaces).
## Unstable naming convention
Unstable naming convention
~~~~~~~~~~~~~~~~~~~~~~~~~~
Unstable protocols have a special naming convention in order to make it
possible to make discoverable backward incompatible changes.
......@@ -84,18 +90,18 @@ There may be more than one minor version per protocol, if there are more
than one global.
The XML file and protocol name also has the word 'unstable' in them, and
all of the interfaces in the protocol are prefixed with +z+ and
all of the interfaces in the protocol are prefixed with `z` and
suffixed with the major version number.
For example, an unstable protocol called foo-bar with major version 2
containing the two interfaces wp_foo and wp_bar both minor version 1 will
be placed in the directory +unstable/foo-bar/+ consisting of one file
called +README+ and one called +foo-bar-unstable-v2.xml+. The XML file
will consist of two interfaces called +zwp_foo_v2+ and +zwp_bar_v2+ with
the +version+ attribute set to +1+.
For example, an unstable protocol called `foo-bar` with major version 2
containing the two interfaces `wp_foo` and `wp_bar` both minor version 1
will be placed in the directory `unstable/foo-bar/` consisting of one file
called `README` and one called `foo-bar-unstable-v2.xml`. The XML file
will consist of two interfaces called `zwp_foo_v2` and `zwp_bar_v2` with
the `version` attribute set to 1.
## Unstable protocol changes
Unstable protocol changes
~~~~~~~~~~~~~~~~~~~~~~~~~
During the development of a new protocol it is possible that backward
incompatible changes are needed. Such a change needs to be represented
in the major and minor versions of the protocol.
......@@ -103,39 +109,42 @@ in the major and minor versions of the protocol.
Assuming a backward incompatible change is needed, the procedure for how to
do so is the following:
. Make a copy of the XML file with the major version increased by +1+.
. Increase the major version number in the protocol XML by +1+.
. Increase the major version number in all of the interfaces in the
XML by +1+.
. Reset the minor version number (interface version attribute) of all
the interfaces to +1+.
- Make a copy of the XML file with the major version increased by 1.
- Increase the major version number in the protocol XML by 1.
- Increase the major version number in all of the interfaces in the
XML by 1.
- Reset the minor version number (interface version attribute) of all
the interfaces to 1.
Backward compatible changes within a major unstable version can be done
in the regular way as done in core Wayland or in stable protocols.
Declaring a protocol stable
~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Declaring a protocol stable
Once it is decided that a protocol should be declared stable, meaning no
more backward incompatible changes will ever be allowed, one last
breakage is needed.
The procedure of doing this is the following:
. Create a new directory in the +stable/+ toplevel directory with the
same name as the protocol directory in the +unstable/+ directory.
. Copy the final version of the XML that is the version that was
decided to be declared stable into the new directory. The target name
should be the same name as the protocol directory but with the +.xml+
suffix.
. Rename the name of the protocol in the XML by removing the
'unstable' part and the major version number.
. Remove the +z+ prefix and the major version number suffix from all
of the interfaces in the protocol.
. Reset all of the interface version attributes to +1+.
. Update the +README+ file in the unstable directory and create a new
+README+ file in the new directory.
Releases
~~~~~~~~
- Create a new directory in the `stable/` toplevel directory with the
same name as the protocol directory in the `unstable/` directory.
- Copy the final version of the XML that is the version that was
decided to be declared stable into the new directory. The target name
should be the same name as the protocol directory but with the `.xml`
suffix.
- Rename the name of the protocol in the XML by removing the
`unstable` part and the major version number.
- Remove the `z` prefix and the major version number suffix from all
of the interfaces in the protocol.
- Reset all of the interface version attributes to 1.
- Update the `README` file in the unstable directory and create a new
`README` file in the new directory.
There are other requirements for declaring a protocol stable, see
[GOVERNANCE section 2.3](GOVERNANCE.md#23-introducing-new-protocols).
## Releases
Each release of wayland-protocols finalizes the version of the protocols
to their state they had at that time.
configure.ac
View file @ b0a25f26
AC_PREREQ([2.64])
m4_define([wayland_protocols_major_version], [1])
m4_define([wayland_protocols_minor_version], [18])
m4_define([wayland_protocols_minor_version], [20])
m4_define([wayland_protocols_version],
[wayland_protocols_major_version.wayland_protocols_minor_version])
......
stable/presentation-time/presentation-time.xml
View file @ b0a25f26
......@@ -154,7 +154,7 @@
summary="presentation output"/>
</event>
<enum name="kind">
<enum name="kind" bitfield="true">
<description summary="bitmask of flags in presented event">
These flags provide information about how the presentation of
the related content update was done. The intent is to help
......
stable/xdg-shell/xdg-shell.xml
View file @ b0a25f26
......@@ -29,7 +29,7 @@
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="xdg_wm_base" version="2">
<interface name="xdg_wm_base" version="3">
<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
......@@ -115,7 +115,7 @@
</event>
</interface>
<interface name="xdg_positioner" version="2">
<interface name="xdg_positioner" version="3">
<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
......@@ -357,9 +357,49 @@
<arg name="x" type="int" summary="surface position x offset"/>
<arg name="y" type="int" summary="surface position y offset"/>
</request>
<!-- Version 3 additions -->
<request name="set_reactive" since="3">
<description summary="continuously reconstrain the surface">
When set reactive, the surface is reconstrained if the conditions used
for constraining changed, e.g. the parent window moved.
If the conditions changed and the popup was reconstrained, an
xdg_popup.configure event is sent with updated geometry, followed by an
xdg_surface.configure event.
</description>
</request>
<request name="set_parent_size" since="3">
<description summary="">
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
this doesn't match the dimension of the parent the popup is eventually
positioned against, the behavior is undefined.
The arguments are given in the surface-local coordinate space.
</description>
<arg name="parent_width" type="int"
summary="future window geometry width of parent"/>
<arg name="parent_height" type="int"
summary="future window geometry height of parent"/>
</request>
<request name="set_parent_configure" since="3">
<description summary="set parent configure this is a response to">
Set the serial of a xdg_surface.configure event this positioner will be
used in response to. The compositor may use this information together
with set_parent_size to determine what future state the popup should be
constrained using.
</description>
<arg name="serial" type="uint"
summary="serial of parent configure event"/>
</request>
</interface>
<interface name="xdg_surface" version="2">
<interface name="xdg_surface" version="3">
<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.
......@@ -526,9 +566,10 @@
</description>
<arg name="serial" type="uint" summary="serial of the configure event"/>
</event>
</interface>
<interface name="xdg_toplevel" version="2">
<interface name="xdg_toplevel" version="3">
<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,
......@@ -710,7 +751,7 @@
</description>
<arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
<arg name="serial" type="uint" summary="the serial of the user event"/>
<arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
<arg name="edges" type="uint" enum="resize_edge" summary="which edge or corner is being dragged"/>
</request>
<enum name="state">
......@@ -1019,7 +1060,7 @@
</event>
</interface>
<interface name="xdg_popup" version="2">
<interface name="xdg_popup" version="3">
<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
......@@ -1043,12 +1084,6 @@
The parent of an xdg_popup must be mapped (see the xdg_surface
description) before the xdg_popup itself.
The x and y arguments passed when creating the popup object specify
where the top left of the popup should be placed, relative to the
local surface coordinates of the parent surface. See
xdg_surface.get_popup. An xdg_popup must intersect with or be at least
partially adjacent to its parent surface.
The client must call wl_surface.commit on the corresponding wl_surface
for the xdg_popup state to take effect.
</description>
......@@ -1126,6 +1161,11 @@
The x and y arguments represent the position the popup was placed at
given the xdg_positioner rule, relative to the upper left corner of the
window geometry of the parent surface.
For version 2 or older, the configure event for an xdg_popup is only
ever sent once for the initial configuration. Starting with version 3,
it may be sent again if the popup is setup with an xdg_positioner with
set_reactive requested, or in response to xdg_popup.reposition requests.
</description>
<arg name="x" type="int"
summary="x position relative to parent surface window geometry"/>
......@@ -1143,5 +1183,58 @@
</description>
</event>
<!-- Version 3 additions -->
<request name="reposition" since="3">
<description summary="recalculate the popup's location">
Reposition an already-mapped popup. The popup will be placed given the
details in the passed xdg_positioner object, and a
xdg_popup.repositioned followed by xdg_popup.configure and
xdg_surface.configure will be emitted in response. Any parameters set
by the previous positioner will be discarded.
The passed token will be sent in the corresponding
xdg_popup.repositioned event. The new popup position will not take
effect until the corresponding configure event is acknowledged by the
client. See xdg_popup.repositioned for details. The token itself is
opaque, and has no other special meaning.
If multiple reposition requests are sent, the compositor may skip all
but the last one.
If the popup is repositioned in response to a configure event for its
parent, the client should send an xdg_positioner.set_parent_configure
and possibly a xdg_positioner.set_parent_size request to allow the
compositor to properly constrain the popup.
If the popup is repositioned together with a parent that is being
resized, but not in response to a configure event, the client should
send a xdg_positioner.set_parent_size request.
</description>
<arg name="positioner" type="object" interface="xdg_positioner"/>
<arg name="token" type="uint" summary="reposition request token"/>
</request>
<event name="repositioned" since="3">
<description summary="signal the completion of a repositioned request">
The repositioned event is sent as part of a popup configuration
sequence, together with xdg_popup.configure and lastly
xdg_surface.configure to notify the completion of a reposition request.
The repositioned event is to notify about the completion of a
xdg_popup.reposition request. The token argument is the token passed
in the xdg_popup.reposition request.
Immediately after this event is emitted, xdg_popup.configure and
xdg_surface.configure will be sent with the updated size and position,
as well as a new configure serial.
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 xdg_surface.ack_configure for details.
</description>
<arg name="token" type="uint" summary="reposition request token"/>
</event>
</interface>
</protocol>