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. 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 xdg_cutouts_manger object anymore. Any objects already created through this instance are not affected. 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. 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. 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 xdg_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 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. 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.