From ea7ff8255e07cd11d5250fb99810d9c89c2b9602 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Wed, 1 Jan 2025 17:03:11 +0100 Subject: [PATCH] experimental: Add xx-cutouts protocol MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This protocol allows compositors to send information about cut out display areas to clients. This way compositors can describe display notches, waterfalls and low resolution areas to clients so that these can avoid placing important information there. This is a copy of https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/372 adjusted for the experimental namespace. Helps: #87 Signed-off-by: Guido Günther --- experimental/xx-cutouts/README | 4 + experimental/xx-cutouts/xx-cutouts-v1.xml | 232 ++++++++++++++++++++++ meson.build | 1 + 3 files changed, 237 insertions(+) create mode 100644 experimental/xx-cutouts/README create mode 100644 experimental/xx-cutouts/xx-cutouts-v1.xml diff --git a/experimental/xx-cutouts/README b/experimental/xx-cutouts/README new file mode 100644 index 0000000..5ef267b --- /dev/null +++ b/experimental/xx-cutouts/README @@ -0,0 +1,4 @@ +xx cutouts protocol + +Maintainers: +Guido Günther diff --git a/experimental/xx-cutouts/xx-cutouts-v1.xml b/experimental/xx-cutouts/xx-cutouts-v1.xml new file mode 100644 index 0000000..62a86e7 --- /dev/null +++ b/experimental/xx-cutouts/xx-cutouts-v1.xml @@ -0,0 +1,232 @@ + + + + + Copyright © 2026 Phosh.mobi e.V. + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + + Warning! The protocol described in this file is currently in the + experimental phase. Backwards incompatible major versions of the protocol + are to be expected. Exposing this protocol without an opt-in mechanism is + discouraged. + + + + This protocol describes the areas of a toplevel that are cut out + of the available surface area by hardware elements present in the + physical display. This allows clients to avoid placing user interface + elements in those areas. + + Typical cutout areas are notches (i.e. embedding a camera) or + "waterfall" display edges. In the case of a notch the compositor + would usually supply the bounding box of the notch or an + approximation by multiple rectangles. Thus a single physical + element in the display can correspond to multiple cutout events in + the protocol. + + The protocol currently supports xdg_toplevel surfaces but is meant + to be extended to other surfaces (like layer surfaces) in the + future. + + Warning! The protocol described in this file is experimental and + backward incompatible changes may be made. Backward compatible + changes may be added together with the corresponding interface + version bump. Backward incompatible changes can only be done by + creating a new major version of the extension. + + + + + This interface allows a compositor to announce support for + supplying cutout information to the client. + + + + + + + + + + Using this request a client can tell the server that it is not + going to use the xx_cutouts_manger object anymore. + + Any objects already created through this instance are not affected. + + + + + + This creates a new xx_cutouts object for the given + surface. The role of the surface must be xdg_toplevel + otherwise an invalid_role protocol error will be raised. Later + versions of this protocol might allow for other surface roles. + + + + + + + + + + An xx_cutouts describes the areas currently "cut out" of a + toplevel. + + Each cutout event carries an id that identifies the + physical element. If the compositor describes an element by + multiple cutout events these should use the same element + id. A typical example is a curved notch that is approximated + by several cutout_box elements. Using the same element + id allows the client to identify that these belong to the + same physical object. Ids are only valid during one configure + sequence. No guarantee is given that the same id identifies + the same element in different configure sequences. + + Typically compositors would only send cutout information when + the toplevel enters fullscreen or maxmized state (as specified + in the xdg_shell protocol). + + The xx_cutouts_v1 object must be destroyed before its + underlying xdg_toplevel and wl_surface. Otherwise the + defunct_cutouts_object protocol error will be send. + + + + + These values indicate the type of cutout. The information is + meant to help clients to decide whether they can possibly + ignore the element. + + + + + This element type can be used by the compositor if it + doesn't want to provide a more specific type. + + + + + A functional, irregular shape on one of the device's + edges. It often contains a camera. + + + + + A curved display edge intended to make the device appear + like not having any bezel. + + + + + + + The position of a corner on a surface + + + + + + + + + + + + + + + Using this request a client can tell the server that it is not + going to use the xx_cutouts object anymore. + + + + + + The cutout_box event describes a rectangular cutout area in + surface-local coordinates. + + This can be an approximation of e.g. a circular camera notch. + + + + + + + + + + + + The cutout_corner event describes a rounded corner in + surface-local coordinates. The area towards the screen edge is + the cutout corner part. + + + + + + + + + The configure event marks the end of a configure sequence. A + configure sequence is a set of zero or more cutout events and + the final xx_cutout.configure event. + + In the case of a xdg_toplevel clients should arrange their + surface for the new cutouts, and then send an + xdg_surface.ack_configure request at some point before + committing the new surface. See xdg_surface.configure and + xdg_surface.ack_configure in the xdg_shell protocol for + details. + + If the cutout sequence consists of only a configure event and + contains no cutout or corner events this indicates that the + surface isn't overlapping with any cutouts or corners. + + If the client receives multiple configure events before it can + respond to one, it is free to discard all but the last event + it received. + + + + + + If a client doesn't handle one or more cutouts in the to be + acked sequence, it can add their element's id to the + unhandled array. The compositor might then try to reposition + the surface in a way that avoids these elements in a future + configure sequence. + + The request (if used) must be sent before acking the configure + sequence. State set with this request is double-buffered. It + will get applied on the next ack_configure and stay valid + until the next configure event. + + + + + + diff --git a/meson.build b/meson.build index a04384f..ff4f32b 100644 --- a/meson.build +++ b/meson.build @@ -78,6 +78,7 @@ staging_protocols = { } experimental_protocols = { + 'xx-cutouts': ['v1'], 'xx-input-method': ['v2'], 'xx-keyboard-filter': ['v1'], 'xx-session-management': ['v1'],