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'],