fdo-mirrors/wayland-protocols
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland-protocols.git synced 2026-01-03 04:40:14 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'occlusion' into 'main'

Browse source 
staging: Add xdg-cutouts protocol

Closes #87

See merge request wayland/wayland-protocols!372
This commit is contained in:
Guido Günther 2025-12-17 01:47:40 +00:00
commit 9be3e6d32b
3 changed files with 232 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
meson.build
View file

@ -69,6 +69,7 @@ staging_protocols = {
'single-pixel-buffer': ['v1'],
'tearing-control': ['v1'],
'xdg-activation': ['v1'],
'xdg-cutouts': ['v1'],
'xdg-dialog': ['v1'],
'xdg-system-bell': ['v1'],
'xdg-toplevel-drag': ['v1'],

4
staging/xdg-cutouts/README Normal file
View file

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

227
staging/xdg-cutouts/xdg-cutouts-v1.xml Normal file
View file

@ -0,0 +1,227 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xdg_cutouts_unstable_v1">
<copyright>
Copyright © 2025 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.
</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="xdg_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 xdg_cutouts_manager object">
Using this request a client can tell the server that it is not
going to use the xdg_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 xdg_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="xdg_cutouts_v1"/>
<arg name="surface" type="object" interface="wl_surface"/>
</request>
</interface>
<interface name="xdg_cutouts_v1" version="1">
<description summary="cutout regions information">
An xdg_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 xdg_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 xdg_cutouts object">
Using this request a client can tell the server that it is not
going to use the xdg_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 xdg_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 events this indicates that the surface
isn't overlapping with any cutouts.
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>