chromium/components/exo/wayland/protocol/aura-output-management.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="aura_output_management">

  <copyright>
    Copyright 2024 The Chromium Authors

    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>

  <interface name="zaura_output_manager_v2" version="1">
    <description summary="aura output manager singleton">
      A global responsible for propagating atomic output configuration changes
      to clients. An output configuration is a union of added / removed outputs
      and updated output metrics.

      Added outputs arrive at the client as wl_registry.global events, removed
      outputs as wl_registry.global_remove events and updated output metrics as
      a sequence of events defined on the zaura_output_manager_v2 interface.
      This is followed by the manager's done event which signals the end of the
      transaction.

      The change should be processed by clients in a way that transitions from
      one output configuration state to another without exposing the
      intermediate output state to the rest of the application.

      Participating servers should emit the zaura_output_manager_v2 global
      before any wl_output globals in the sequence of wl_registry.global events.

      Participating clients should bind the zaura_output_manager_v2 before any
      wl_output globals. This ordering is required to ensure clients receive all
      necessary output configuration information before receiving any further
      server events that may reference bound wl_outputs.

      Clients can expect that all events comprising a configuration change are
      sent synchronously, one after the other, before any other server events
      that leverage the output as an event param.
    </description>

    <event name="done" since="1">
      <description
          summary="sent all information about the output configuration change">
        This event is sent after all added, changed and removed output events
        for a given wl_output have been dispatched to the client.
      </description>
    </event>

    <event name="display_id" since="1">
      <description summary="advertise the output's display id">
        This event describes the 64bit display id assigned to each display by
        ChromeOS. The value is opaque and should not be interpreted.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="display_id_hi" type="uint" />
      <arg name="display_id_lo" type="uint" />
    </event>

    <event name="logical_position" since="1">
      <description
          summary="position of the output within the global compositor space">
        The position event describes the location of the wl_output within the
        global compositor space.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="x" type="int"
          summary="x position within the global compositor space" />
      <arg name="y" type="int"
          summary="y position within the global compositor space" />
    </event>

    <event name="logical_size" since="1">
      <description summary="size of the output in the global compositor space">
        The logical_size event describes the logical size of the output in the
        global compositor space.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="width" type="int" summary="width in global compositor space" />
      <arg name="height" type="int"
          summary="height in global compositor space" />
    </event>

    <event name="physical_size" since="1">
      <description summary="size of the output in pixels">
        The physical resolution of the display in pixels. The value should not
        include any overscan insets or display rotation, except for any panel
        orientation adjustment.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="width" type="int"
          summary="width in global compositor space" />
      <arg name="height" type="int"
          summary="height in global compositor space" />
    </event>

    <event name="work_area_insets" since="1">
      <description summary="advertise the work area insets for the output">
        This event describes the work area insets for the output in logical
        screen coordinates, from which the work area can be calculated.

        The event is sent when binding to the output object and subsequently as
        output state changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="top" type="int" />
      <arg name="left" type="int" />
      <arg name="bottom" type="int" />
      <arg name="right" type="int" />
    </event>

    <event name="device_scale_factor" since="1">
      <description summary="advertise device scale factor for the output">
        The scale factor of the output device. We reinterpret_cast the float
        scale factor into a 32-bit uint and later cast back into a float. This
        is because wayland does not support native transport of floats. As
        different CPU architectures may use different endian representations for
        IEEE 754 floats, this protocol implicitly assumes that the caller and
        receiver are the same machine.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="device_scale_factor" type="uint"
          summary="display scale factor, in float format" />
    </event>

    <event name="logical_transform" since="1">
      <description summary="logical transform of the output">
        This event describes the logical transform for the output. Whereas
        panel transform corresponds to the display's panel rotation, the logical
        transform corresponds to the display's logical rotation.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="transform" type="int" enum="wl_output.transform"
        summary="transform that maps framebuffer to output" />
    </event>

    <event name="panel_transform" since="1">
      <description summary="panel transform of the output">
        This event describes the panel transform for the output, which is the
        associated display's panel rotation.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="transform" type="int" enum="wl_output.transform"
        summary="transform that maps framebuffer to output" />
    </event>

    <event name="name" since="1">
      <description summary="human-readable name of this output">
        The name is a UTF-8 string with no convention defined for its contents.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="name" type="string" summary="output name" />
    </event>

    <event name="description" since="1">
      <description summary="human-readable description of this output">
        The description is a UTF-8 string with no convention defined for its
        contents.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="description" type="string" summary="output description" />
    </event>

    <event name="overscan_insets" since="1">
      <description summary="advertise the overscan insets for the output">
        This event describes the overscan insets for the output in physical
        pixels.

        The event is sent immediately after the wl_registry.global event for the
        output and subsequently in latter display configuration changes.
      </description>
      <arg name="output_name" type="uint" />
      <arg name="top" type="int" />
      <arg name="left" type="int" />
      <arg name="bottom" type="int" />
      <arg name="right" type="int" />
    </event>

    <event name="activated" since="1">
      <description summary="target display for new windows">
        Notifies that this output is now active output. It is typically used as
        a target when a new window is created without specific bounds.
      </description>
      <arg name="output_name" type="uint" />
    </event>
  </interface>
</protocol>