xx_cutouts_unstable_v1

• # xx_cutouts_manager_v1

  This interface allows a compositor to announce support for supplying cutout information to the client.

  Requests

  • #

    destroy

    destroy the xx_cutouts_manager object
    void xx_cutouts_manager_v1_destroy(

    struct xx_cutouts_manager_v1* xx_cutouts_manager_v1

    )
    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.
  • #

    get_cutouts

    create a cutout notifier from a xdg toplevel
    struct xx_cutouts_v1* xx_cutouts_manager_v1_get_cutouts(

    struct xx_cutouts_manager_v1* xx_cutouts_manager_v1,

    struct wl_surface* surface

    )
    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.

  Enums

  • #

    error
    XX_CUTOUTS_MANAGER_V1_ERROR_INVALID_ROLE /* given wl_surface has incorrect role */
    XX_CUTOUTS_MANAGER_V1_ERROR_DEFUNCT_CUTOUTS_OBJECT /* wl_surface or surface role was destroyed before the cutouts object */

• # xx_cutouts_v1

  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.

  Requests

  • #

    destroy

    destroy the xx_cutouts object
    void xx_cutouts_v1_destroy(

    struct xx_cutouts_v1* xx_cutouts_v1

    )
    Using this request a client can tell the server that it is not going to use the xx_cutouts object anymore.
  • #

    set_unhandled

    Notify about unhandled cutouts
    void xx_cutouts_v1_set_unhandled(

    struct xx_cutouts_v1* xx_cutouts_v1,

    struct wl_array* unhandled /* array of unhandled element ids */

    )
    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.

  Events

  • #

    cutout_box

    A rectangular cutout region
    int32_t x /* x coordinate of the box's top left corner */
    int32_t y /* y coordinate of the box's top left corner */
    int32_t width
    int32_t height
    uint32_t type /* The type of cutout */
    uint32_t id /* An identifier identifying the physical element */
    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.
  • #

    cutout_corner

    A cutout corner
    uint32_t position /* The position of the described corner */
    uint32_t radius /* The corner's radius */
    uint32_t id /* An identifier identifying the physical element */
    The cutout_corner event describes a rounded corner in surface-local coordinates. The area towards the screen edge is the cutout corner part.
  • #

    configure

    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 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.

  Enums

  • #

    type

    Cutout type
    XX_CUTOUTS_V1_TYPE_CUTOUT
    XX_CUTOUTS_V1_TYPE_NOTCH
    XX_CUTOUTS_V1_TYPE_WATERFALL
    These values indicate the type of cutout. The information is meant to help clients to decide whether they can possibly ignore the element.
  • #

    corner_position

    Corner position
    XX_CUTOUTS_V1_CORNER_POSITION_TOP_LEFT
    XX_CUTOUTS_V1_CORNER_POSITION_TOP_RIGHT
    XX_CUTOUTS_V1_CORNER_POSITION_BOTTOM_RIGHT
    XX_CUTOUTS_V1_CORNER_POSITION_BOTTOM_LEFT
    The position of a corner on a surface
  • #

    error
    XX_CUTOUTS_V1_ERROR_INVALID_ELEMENT_ID /* Invalid element id in a set_unhandled request */

Copyright Info