mirror of
https://gitlab.freedesktop.org/wlroots/wlr-protocols.git
synced 2026-05-05 05:18:31 +02:00
310 lines
13 KiB
XML
310 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<protocol name="wlr_screencopy_unstable_v1">
|
|
<copyright>
|
|
Copyright © 2018 Simon Ser
|
|
Copyright © 2019 Andri Yngvason
|
|
|
|
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.
|
|
|
|
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_v1" version="4">
|
|
<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 the next frame of an entire output.
|
|
|
|
When overlay_cursor is 0, software cursors will still be visible on
|
|
the frame.
|
|
</description>
|
|
<arg name="frame" type="new_id" interface="zwlr_screencopy_frame_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 the next frame 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.
|
|
</description>
|
|
<arg name="frame" type="new_id" interface="zwlr_screencopy_frame_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>
|
|
|
|
<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>
|
|
|
|
<!-- Version 4 additions -->
|
|
<request name="capture_cursor" since="3">
|
|
<description summary="capture the hardware cursor">
|
|
Capture the current hardware cursor used by the compositor, if any.
|
|
</description>
|
|
<arg name="cursor" type="new_id" interface="zwlr_screencopy_frame_v1"/>
|
|
<arg name="seat" type="object" interface="wl_seat"/>
|
|
</request>
|
|
|
|
<request name="pointer_position" since="3">
|
|
<description summary="report the cursor position">
|
|
Creates an object that reports the current pointer position on the
|
|
given wl_output for the given wl_seat.
|
|
</description>
|
|
<arg name="reporter" type="new_id"
|
|
interface="zwlr_screencopy_pointer_reporter_v1"/>
|
|
<arg name="seat" type="object" interface="wl_seat"/>
|
|
<arg name="output" type="object" interface="wl_output"/>
|
|
</request>
|
|
</interface>
|
|
|
|
<interface name="zwlr_screencopy_frame_v1" version="4">
|
|
<description summary="a frame ready for copy">
|
|
This object represents a single frame.
|
|
|
|
When created, a series of buffer events will be sent, each representing a
|
|
supported buffer type. The "buffer_done" event is sent afterwards to
|
|
indicate that all supported buffer types have been enumerated. The client
|
|
will then be able to send a "copy" request. If the capture is successful,
|
|
the compositor will send a "flags" followed by a "ready" event.
|
|
|
|
For objects version 2 or lower, wl_shm buffers are always supported, ie.
|
|
the "buffer" event is guaranteed to be sent.
|
|
|
|
If the capture failed, the "failed" event is sent. This can happen anytime
|
|
before the "ready" event.
|
|
|
|
Once either a "ready" 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. 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>
|
|
|
|
<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_screencopy_frame_v1.buffer and
|
|
zwlr_screencopy_frame_v1.linux_dmabuf. The buffer needs to have a
|
|
supported format.
|
|
|
|
If the frame is successfully copied, a "flags" and a "ready" events are
|
|
sent. Otherwise, a "failed" event is sent.
|
|
</description>
|
|
<arg name="buffer" type="object" interface="wl_buffer"/>
|
|
</request>
|
|
|
|
<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>
|
|
|
|
<enum name="flags" bitfield="true">
|
|
<entry name="y_invert" value="1" summary="contents are y-inverted"/>
|
|
</enum>
|
|
|
|
<event name="flags">
|
|
<description summary="frame flags">
|
|
Provides flags about the frame. This event is sent once before the
|
|
"ready" event.
|
|
</description>
|
|
<arg name="flags" type="uint" enum="flags" summary="frame flags"/>
|
|
</event>
|
|
|
|
<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"/>
|
|
</event>
|
|
|
|
<event name="failed">
|
|
<description summary="frame copy failed">
|
|
This event indicates that the attempted frame copy has failed.
|
|
|
|
After receiving this event, the client should destroy the object.
|
|
</description>
|
|
</event>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="delete this object, used or not">
|
|
Destroys the frame. This request can be sent at any time by the client.
|
|
</description>
|
|
</request>
|
|
|
|
<!-- Version 2 additions -->
|
|
<request name="copy_with_damage" since="2">
|
|
<description summary="copy the frame when it's damaged">
|
|
Same as copy, except it waits until there is damage to copy.
|
|
|
|
It is a protocol error to send this request on a zwlr_screencopy_frame_v1
|
|
that is created by zwlr_screencopy_manager_v1.capture_cursor.
|
|
</description>
|
|
<arg name="buffer" type="object" interface="wl_buffer"/>
|
|
</request>
|
|
|
|
<event name="damage" since="2">
|
|
<description summary="carries the coordinates of the damaged region">
|
|
This event is sent right before the ready event when copy_with_damage is
|
|
requested. It may be generated multiple times for each copy_with_damage
|
|
request.
|
|
|
|
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 call to copy_with_damage
|
|
and a ready event is the total damage since the prior ready event.
|
|
</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="current width"/>
|
|
<arg name="height" type="uint" summary="current height"/>
|
|
</event>
|
|
|
|
<!-- Version 3 additions -->
|
|
<event name="linux_dmabuf" since="3">
|
|
<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>
|
|
|
|
<event name="buffer_done" since="3">
|
|
<description summary="all buffer types reported">
|
|
This event is sent once after all buffer events have been sent.
|
|
|
|
The client should proceed to create a buffer of one of the supported
|
|
types, and send a "copy" request.
|
|
</description>
|
|
</event>
|
|
|
|
<!-- Version 4 additions -->
|
|
<event name="hotspot" since="4">
|
|
<description summary="cursor hotspot information">
|
|
Provides information about cursor hotspot. This event is sent once after
|
|
the frame is created if the frame is created by
|
|
zwlr_screencopy_manager_v1.capture_cursor.
|
|
</description>
|
|
<arg name="x" type="uint" summary="cursor hotspot x coordinate"/>
|
|
<arg name="y" type="uint" summary="cursor hotspot y coordinate"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="zwlr_screencopy_pointer_reporter_v1" version="1">
|
|
<description summary="reports pointer information for a seat">
|
|
This object reports pointer information for a given wl_seat on the given
|
|
wl_output until destroyed.
|
|
|
|
Information reported include the pointer position and cursor image.
|
|
</description>
|
|
|
|
<event name="position">
|
|
<description summary="reports current pointer position">
|
|
This event is sent every time the pointer on the wl_seat is moved,
|
|
reporting its current position in output logical coordinates, see
|
|
xdg_output.logical_size.
|
|
|
|
If the pointer is not on the given wl_output, this event is not sent.
|
|
</description>
|
|
<arg name="x" type="uint" summary="pointer position x coordinate"/>
|
|
<arg name="y" type="uint" summary="pointer position y coordinate"/>
|
|
</event>
|
|
|
|
<event name="cursor">
|
|
<description summary="reports a cursor image change">
|
|
This event is sent immediately after the pointer reporter is created,
|
|
every time a client calls wl_pointer.set_cursor, and every time the
|
|
pointer is moved on and off the given wl_output.
|
|
|
|
If the cursor is rendered as a hardware cursor and is visible on the
|
|
given wl_output, visible is set to 1 and the image may be obtained by
|
|
calling zwlr_screencopy_manager_v1.capture_cursor. Otherwise, it is
|
|
set to 0.
|
|
</description>
|
|
<arg name="visible" type="uint" summary="whether the cursor is visible"/>
|
|
</event>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="delete this object">
|
|
Destroys this cursor reporter.
|
|
</description>
|
|
</request>
|
|
</interface>
|
|
</protocol>
|