wlr-screencopy-unstable-v2.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="wlr_screencopy_unstable_v2">
  <copyright>
    Copyright © 2021 Guanzhong Chen

    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>

  <description summary="screen content capturing on client buffers">
    This protocol allows clients to ask the compositor to copy part of the
    screen content to a client buffer, providing screenshot and screencast
    functionality.

    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 are done by bumping the version number in
    the protocol and interface names and resetting the interface version.
    Once the protocol is to be declared stable, the 'z' prefix and the
    version number in the protocol and interface names are removed and the
    interface version number is reset.
  </description>

  <interface name="zwlr_screencopy_manager_v2" version="1">
    <description summary="manager to inform clients and begin capturing">
      This object is a manager which offers requests to start capturing from a
      source.
    </description>

    <request name="capture_output">
      <description summary="capture an output">
        Capture a snapshot of an entire output.

        When overlay_cursor is 0, software cursors will still be visible on
        the frame.
      </description>
      <arg name="screenshot" type="new_id" interface="zwlr_screenshot_v1"/>
      <arg name="overlay_cursor" type="int"
        summary="composite cursor onto the frame"/>
      <arg name="output" type="object" interface="wl_output"/>
    </request>

    <request name="capture_output_region">
      <description summary="capture an output's region">
        Capture a snapshot of an output's region.

        The region is given in output logical coordinates, see
        xdg_output.logical_size. The region will be clipped to the output's
        extents.

        When overlay_cursor is 0, software cursors will still be visible on
        the frame.
      </description>
      <arg name="screenshot" type="new_id" interface="zwlr_screenshot_v1"/>
      <arg name="overlay_cursor" type="int"
        summary="composite cursor onto the frame"/>
      <arg name="output" type="object" interface="wl_output"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <enum name="record_mode">
      <entry name="no_cursor" value="0"
        summary="do not record the hardware cursor"/>
      <entry name="compose_cursor" value="1"
        summary="compose the hardware cursor onto the frame"/>
      <entry name="separate_cursor" value="2"
        summary="record the hardware cursor separately"/>
    </enum>

    <request name="record_output">
      <description summary="record an output">
        Continuously record an entire output.

        If the "separate_cursor" recording mode is used, then a wl_seat must
        be passed to indicate the seat whose pointer will be captured.
      </description>
      <arg name="screencast" type="new_id" interface="zwlr_screencast_v1"/>
      <arg name="output" type="object" interface="wl_output"/>
      <arg name="seat" type="object" interface="wl_seat" allow-null="true"/>
      <arg name="type" type="uint" enum="record_type"/>
    </request>

    <request name="record_output_region">
      <description summary="record an output's region">
        Continuously record an region of the output.

        The region is given in output logical coordinates, see
        xdg_output.logical_size. The region will be clipped to the output's
        extents.

        If the "separate_cursor" recording mode is used, then a wl_seat must
        be passed to indicate the seat whose pointer will be captured.
      </description>
      <arg name="screencast" type="new_id" interface="zwlr_screencast_v1"/>
      <arg name="output" type="object" interface="wl_output"/>
      <arg name="seat" type="object" interface="wl_seat" allow-null="true"/>
      <arg name="mode" type="uint" enum="record_type"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the manager">
        All objects created by the manager will still remain valid, until their
        appropriate destroy request has been called.
      </description>
    </request>
  </interface>

  <interface name="zwlr_screenshot_v1" version="1">
    <description summary="a screenshot ready for copy">
      This object represents a screenshot.

      When created, a buffer event will be sent, representing the wl_shm buffer
      type. The client will then be able to send a "copy" request. If the capture
      is successful, the compositor will send a "succeeded" event. If the capture
      failed, a "failed" event is sent.

      Once either a "succeeded" or a "failed" event is received, the client should
      destroy the frame.
    </description>

    <event name="buffer">
      <description summary="wl_shm buffer information">
        Provides information about wl_shm buffer parameters that need to be
        used for this frame.
      </description>
      <arg name="format" type="uint" enum="wl_shm.format" summary="buffer format"/>
      <arg name="width" type="uint" summary="buffer width"/>
      <arg name="height" type="uint" summary="buffer height"/>
      <arg name="stride" type="uint" summary="buffer stride"/>
    </event>

    <request name="copy">
      <description summary="copy the frame">
        Copy the frame to the supplied buffer. The buffer must have a the
        correct size, see zwlr_screenshot_v1.buffer. The buffer needs to be of a
        the format specified by the "buffer" event.

        If the frame is successfully copied, a "succeeded" event is sent.
        Otherwise, a "failed" event is sent.
      </description>
      <arg name="buffer" type="object" interface="wl_buffer"/>
    </request>

    <enum name="flags" bitfield="true">
      <entry name="y_invert" value="1" summary="contents are y-inverted"/>
    </enum>

    <event name="ready">
      <description summary="indicates frame is available for reading">
        Called as soon as the frame is copied, indicating it is available
        for reading. This event includes the time at which presentation happened
        at.

        The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
        each component being an unsigned 32-bit value. Whole seconds are in
        tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo,
        and the additional fractional part in tv_nsec as nanoseconds. Hence,
        for valid timestamps tv_nsec must be in [0, 999999999]. The seconds part
        may have an arbitrary offset at start.

        After receiving this event, the client should destroy the object.
      </description>
      <arg name="tv_sec_hi" type="uint"
           summary="high 32 bits of the seconds part of the timestamp"/>
      <arg name="tv_sec_lo" type="uint"
           summary="low 32 bits of the seconds part of the timestamp"/>
      <arg name="tv_nsec" type="uint"
           summary="nanoseconds part of the timestamp"/>
      <arg name="flags" type="uint" enum="flags" summary="screenshot flags"/>
    </event>

    <enum name="error">
      <entry name="already_used" value="0"
        summary="the object has already been used to copy a wl_buffer"/>
      <entry name="invalid_buffer" value="1"
        summary="buffer attributes are invalid"/>
    </enum>

    <event name="failed">
      <description summary="screenshot failed">
        This event indicates that the attempted screenshot has failed.

        After receiving this event, the client should destroy the object.
      </description>
      <arg name="error" type="uint" enum="error" summary="error code"/>
    </event>

    <request name="destroy" type="destructor">
      <description summary="delete this object, used or not">
        Destroys the screenshot. This request can be sent at any time by the
        client.
      </description>
    </request>
  </interface>

  <interface name="zwlr_screencast_v1" version="1">
    <description summary="records the screen into a buffer">
      This object continuously records a region of an output into a buffer.

      When this object is created, a series of "buffer" and "linux_dmabuf"
      events will be sent, each representing a supported buffer type. Then,
      the "buffer_done" event is sent to indicate that all supported buffer
      types have been enumerated.

      The client will then be able to send the "capture" request, passing a
      buffer that will be used to store the frame data.

      Once the "capture" request is sent, when an update happens, the client
      will receive an "update" event, followed by other events depending on
      the type of the update, followed by the "update_done" event.

      The screencast will then be paused until the client signals it is ready
      for a new frame with another "capture" request.

      If the update includes a frame update, then the client is considered to
      be in ownership of the buffer, and the compositor may not update it.
      Otherwise, the compositor retains control over the buffer.
    </description>

    <event name="buffer">
      <description summary="wl_shm buffer information">
        Provides information about wl_shm buffer parameters that need to be
        used for this frame. This event is sent once after the frame is created
        if wl_shm buffers are supported.
      </description>
      <arg name="format" type="uint" enum="wl_shm.format" summary="buffer format"/>
      <arg name="width" type="uint" summary="buffer width"/>
      <arg name="height" type="uint" summary="buffer height"/>
      <arg name="stride" type="uint" summary="buffer stride"/>
    </event>

    <event name="linux_dmabuf">
      <description summary="linux-dmabuf buffer information">
        Provides information about linux-dmabuf buffer parameters that need to
        be used for this frame. This event is sent once after the frame is
        created if linux-dmabuf buffers are supported.
      </description>
      <arg name="format" type="uint" summary="fourcc pixel format"/>
      <arg name="width" type="uint" summary="buffer width"/>
      <arg name="height" type="uint" summary="buffer height"/>
    </event>

    <request name="capture">
      <description summary="begins the recording">
        Captures the next frame to the supplied buffer. The buffer must have the
        correct size, see zwlr_screencast_v1.buffer and
        zwlr_screencast_v1.linux_dmabuf. The buffer needs to have a supported
        format.

        If the buffer size is invalid or ceases to be valid, a "failed" event
        is sent.

        The "age" argument provides a hint to the compositor that the buffer
        contains the frame from "age" frames ago. This allows the compositor to
        execute partial copies. An age of 0 indicates that the compositor should
        copy the full frame.
      </description>
      <arg name="buffer" type="object" interface="wl_buffer"/>
      <arg name="age" type="uint" summary="age of the buffer"/>
    </request>

    <enum name="error">
      <entry name="invalid_buffer" value="0"
        summary="buffer attributes are invalid"/>
    </enum>

    <event name="failed">
      <description summary="recording has failed">
        This event is sent to indicate that the recording has failed. Once this
        event is received, the client should destroy this object.
      </description>
    </event>

    <enum name="update_type" bitfield="true">
      <entry name="frame" value="1" summary="the frame has changed"/>
      <entry name="cursor" value="2" summary="the cursor has changed"/>
      <entry name="pointer" value="4" summary="the pointer has moved"/>
    </enum>

    <event name="update">
      <description summary="the screen has changed">
        This event is sent when something has changed on the screen.

        The type of update is indicated by the value of the "type" bitfield.
        "cursor" and "pointer" updates will only be set if the
        zwlr_screencast_v1 is created with the "separate_cursor" mode.

        If an update type is set in the bitfield, an event with the same name
        will also be sent. Once all updates are complete, the "update_done"
        event is sent.
      </description>
      <arg name="type" type="uint" enum="update_type" summary="update type"/>
    </event>

    <event name="damage">
      <description summary="carries the coordinates of the damaged region">
        This event is sent after the update event and before the frame event if
        the frame has changed. It may be generated multiple times for each frame
        event.

        The arguments describe a box around an area that has changed since the
        last copy request that was derived from the current screencopy manager
        instance.

        The union of all regions received between the update and frame events
        is the total damage since the previous frame event. On the first frame,
        the damaged area will be the entire capture region.
      </description>
      <arg name="x" type="uint" summary="damaged x coordinates"/>
      <arg name="y" type="uint" summary="damaged y coordinates"/>
      <arg name="width" type="uint" summary="damage rectangle width"/>
      <arg name="height" type="uint" summary="damage rectangle height"/>
    </event>

    <enum name="flags" bitfield="true">
      <entry name="y_invert" value="1" summary="contents are y-inverted"/>
    </enum>

    <event name="frame">
      <description summary="the frame has changed">
        This event is sent when the frame has changed.

        When this event is sent, the buffer passed to zwlr_screencast_v1.begin
        has already been updated to contain the content of the frame. This event
        is preceded by a number of damage events.

        The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
        each component being an unsigned 32-bit value. Whole seconds are in
        tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo,
        and the additional fractional part in tv_nsec as nanoseconds. Hence,
        for valid timestamps tv_nsec must be in [0, 999999999]. The seconds part
        may have an arbitrary offset at start.
      </description>
      <arg name="tv_sec_hi" type="uint"
           summary="high 32 bits of the seconds part of the timestamp"/>
      <arg name="tv_sec_lo" type="uint"
           summary="low 32 bits of the seconds part of the timestamp"/>
      <arg name="tv_nsec" type="uint"
           summary="nanoseconds part of the timestamp"/>
      <arg name="flags" type="uint" enum="flags" summary="frame flags"/>
    </event>

    <event name="cursor">
      <description summary="the cursor has changed">
        This event is sent when the cursor image has changed.

        The new cursor is passed to the client as a server allocated wl_shm
        buffer. This buffer may be used until the client sends a "capture"
        request.

        The format, width, height, stride arguments define the parameters of
        the buffer. The hotspot_x and hotspot_y arguments define the hotspot
        of the cursor.

        If no hardware cursor is visible, the buffer will be null. All arguments
        will be zero.
      </description>
      <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"/>
      <arg name="format" type="uint" enum="wl_shm.format" summary="buffer format"/>
      <arg name="width" type="uint" summary="buffer width"/>
      <arg name="height" type="uint" summary="buffer height"/>
      <arg name="stride" type="uint" summary="buffer stride"/>
      <arg name="hotspot_x" type="uint" summary="hotspot x coordinate"/>
      <arg name="hotspot_y" type="uint" summary="hotspot y coordinate"/>
    </event>

    <event name="pointer">
      <description summary="the pointer position has changed">
        This event is sent when the pointer position has changed in the capture
        region. The coordinates are given in buffer coordinates.

        When no part of the cursor image intersects the capture region, the
        compositor should send this event with inside set to 0, indicating that
        the cursor is no longer present on the screen. The compositor does not
        have to send any more pointer updates until it moves back into the
        capture region.
      </description>
      <arg name="inside" type="uint"
        summary="whether the pointer is inside the capture region"/>
      <arg name="x" type="int" summary="pointer position x coordinate"/>
      <arg name="y" type="int" summary="pointer position y coordinate"/>
    </event>

    <event name="update_done">
      <description summary="the update has finished">
        This event indicates that all events associated with a given "update"
        event has been sent.

        The screencast will pause until the next "capture" request is sent by
        the client.
      </description>
    </event>

    <request name="destroy" type="destructor">
      <description summary="delete this object">
        Stops the screencast.
      </description>
    </request>
  </interface>
</protocol>