325 lines
13 KiB
XML
325 lines
13 KiB
XML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<protocol name="ext_screencopy_v1">
|
||
|
|
<copyright>
|
||
|
|
Copyright © 2021-2022 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 capture screen
|
||
|
|
contents to user submitted buffers.
|
||
|
|
|
||
|
|
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="ext_screencopy_manager_v1" 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>
|
||
|
|
|
||
|
|
<enum name="options" bitfield="true">
|
||
|
|
<entry name="render_cursors" value="1"/>
|
||
|
|
</enum>
|
||
|
|
|
||
|
|
<enum name="input_type">
|
||
|
|
<entry name="pointer" value="1"/>
|
||
|
|
<entry name="touch" value="2"/>
|
||
|
|
</enum>
|
||
|
|
|
||
|
|
<request name="capture">
|
||
|
|
<description summary="capture an image source">
|
||
|
|
Create a capturing session for an image source.
|
||
|
|
|
||
|
|
If the "render_cursors" flag is set, cursors shall be composited onto
|
||
|
|
the captured frame. The cursor should not be composited onto the frame
|
||
|
|
if this flag is not set.
|
||
|
|
</description>
|
||
|
|
<arg name="session" type="new_id" interface="ext_screencopy_session_v1"/>
|
||
|
|
<arg name="source" type="object" interface="ext_image_source_v1"/>
|
||
|
|
<arg name="options" type="uint" enum="options"/>
|
||
|
|
</request>
|
||
|
|
|
||
|
|
<request name="capture_cursor">
|
||
|
|
<description summary="capture the cursor of an image source">
|
||
|
|
Create a cursor capturing session for an image source.
|
||
|
|
|
||
|
|
The options argument has no effect and should be set to 0. This is
|
||
|
|
intended for any future flags that might be added.
|
||
|
|
</description>
|
||
|
|
<arg name="session" type="new_id" interface="ext_screencopy_cursor_session_v1"/>
|
||
|
|
<arg name="source" type="object" interface="ext_image_source_v1"/>
|
||
|
|
<arg name="seat" type="object" interface="wl_seat"/>
|
||
|
|
<arg name="input_type" type="uint" enum="input_type"/>
|
||
|
|
<arg name="options" type="uint"/>
|
||
|
|
</request>
|
||
|
|
</interface>
|
||
|
|
|
||
|
|
<interface name="ext_screencopy_session_v1" version="1">
|
||
|
|
<description summary="capturing session">
|
||
|
|
This is the frame capturing interface. It keeps track of changes between
|
||
|
|
frames.
|
||
|
|
|
||
|
|
After a screencopy session is created, buffer constraint events will be
|
||
|
|
emitted from the compositor to tell the client which buffer types and
|
||
|
|
formats are supported for reading from the session.
|
||
|
|
|
||
|
|
When the client knows all the buffer attributes, it can create a buffer,
|
||
|
|
attach it to the screencopy session using the "attach_buffer" request,
|
||
|
|
set the buffer damage using the "damage_buffer" request and then call
|
||
|
|
the "commit" request.
|
||
|
|
|
||
|
|
After copying, a series of events will be generated, ending with the
|
||
|
|
"ready" event, which means that the buffer is ready to be used and a
|
||
|
|
buffer may be committed to the session again. The buffer may be re-used
|
||
|
|
after the "ready" event. The "wl_buffer.release" event is not used.
|
||
|
|
|
||
|
|
The compositor should present frames to the client at a steady rate,
|
||
|
|
unless otherwise instructed (see "on_damage" option).
|
||
|
|
|
||
|
|
A client wishing to capture all frames without missing any of them, should
|
||
|
|
commit a new buffer immediately after receiving the "ready" event.
|
||
|
|
|
||
|
|
The "failed" event may be sent at any time. When this happens, the client
|
||
|
|
must destroy the session. Depending on the failure reason, the client can
|
||
|
|
create a new session to replace it.
|
||
|
|
</description>
|
||
|
|
|
||
|
|
<enum name="failure_reason">
|
||
|
|
<entry name="invalid_buffer" value="1"/>
|
||
|
|
<entry name="output_missing" value="2"/>
|
||
|
|
<entry name="output_disabled" value="3"/>
|
||
|
|
<entry name="unknown_input" value="4"/>
|
||
|
|
</enum>
|
||
|
|
|
||
|
|
<enum name="options" bitfield="true">
|
||
|
|
<entry name="on_damage" value="1"/>
|
||
|
|
</enum>
|
||
|
|
|
||
|
|
<event name="format_shm">
|
||
|
|
<description summary="shm buffer format">
|
||
|
|
Provides the format that must be used for shm buffers.
|
||
|
|
|
||
|
|
This may be emitted multiple times, in which case the client may choose
|
||
|
|
any given format.
|
||
|
|
</description>
|
||
|
|
<arg name="format" type="uint" enum="wl_shm.format" summary="shm format"/>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="format_drm">
|
||
|
|
<description summary="dma buffer constraints">
|
||
|
|
Provides the format that must be used for dma buffers.
|
||
|
|
|
||
|
|
This may be emitted multiple times, in which case the client may choose
|
||
|
|
any given format.
|
||
|
|
</description>
|
||
|
|
<arg name="format" type="uint" summary="drm format"/>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="dimensions">
|
||
|
|
<description summary="image source dimensions">
|
||
|
|
Provides the dimensions of the source image in buffer pixel coordinates.
|
||
|
|
|
||
|
|
The client must submit buffers that are large enough for the source
|
||
|
|
image.
|
||
|
|
</description>
|
||
|
|
<arg name="width" type="uint" summary="buffer width"/>
|
||
|
|
<arg name="height" type="uint" summary="buffer height"/>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="constraints_done">
|
||
|
|
<description summary="session initialisation done">
|
||
|
|
This event is sent once when all constraint events have been sent.
|
||
|
|
</description>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<request name="attach_buffer">
|
||
|
|
<description summary="attach buffer to session">
|
||
|
|
Attach a buffer to the session.
|
||
|
|
|
||
|
|
The buffer must satisfy the constraints given by the
|
||
|
|
"buffer_constraints_shm" and "buffer_constraints_dmabuf" events.
|
||
|
|
|
||
|
|
If an over-sized buffer is committed, the compositor will place the
|
||
|
|
image into the top left corner of the buffer.
|
||
|
|
</description>
|
||
|
|
<arg name="buffer" type="object" interface="wl_buffer"/>
|
||
|
|
</request>
|
||
|
|
|
||
|
|
<request name="damage_buffer">
|
||
|
|
<description summary="damage buffer">
|
||
|
|
Apply damage to the buffer which is to be committed next.
|
||
|
|
|
||
|
|
This is for optimisation purposes. The compositor may use this
|
||
|
|
information to reduce copying.
|
||
|
|
|
||
|
|
The client must submit damage if it's using multiple buffers. Otherwise,
|
||
|
|
the server might not copy into damaged regions of the buffer.
|
||
|
|
|
||
|
|
These coordinates originate in the upper left corner of the buffer.
|
||
|
|
</description>
|
||
|
|
<arg name="x" type="uint" summary="region x coordinates"/>
|
||
|
|
<arg name="y" type="uint" summary="region y coordinates"/>
|
||
|
|
<arg name="width" type="uint" summary="region width"/>
|
||
|
|
<arg name="height" type="uint" summary="region height"/>
|
||
|
|
</request>
|
||
|
|
|
||
|
|
<request name="commit">
|
||
|
|
<description summary="commit session">
|
||
|
|
Commit the screencopy session.
|
||
|
|
|
||
|
|
The frame will be copied to the attached buffer on next output commit. A
|
||
|
|
ready event is generated when the buffer is ready.
|
||
|
|
|
||
|
|
If the "on_damage" flag is set, the compositor should skip sending new
|
||
|
|
frames to the client until there is damage.
|
||
|
|
</description>
|
||
|
|
<arg name="options" type="uint" enum="options"/>
|
||
|
|
</request>
|
||
|
|
|
||
|
|
<request name="destroy" type="destructor">
|
||
|
|
<description summary="delete this object">
|
||
|
|
Destroys the session. This request can be sent at any time by the
|
||
|
|
client.
|
||
|
|
</description>
|
||
|
|
</request>
|
||
|
|
|
||
|
|
<event name="transform">
|
||
|
|
<description summary="carries the output transform">
|
||
|
|
This event is sent before the ready event and holds the output transform
|
||
|
|
of the source buffer.
|
||
|
|
</description>
|
||
|
|
<arg name="transform" type="int" enum="wl_output.transform"/>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="damage">
|
||
|
|
<description summary="carries the coordinates of the damaged region">
|
||
|
|
This event is sent before the ready event. It may be generated multiple
|
||
|
|
times for each commit.
|
||
|
|
|
||
|
|
A capture session's initial damage encompasses the whole captured area.
|
||
|
|
|
||
|
|
The arguments describe a box around an area that has changed since the
|
||
|
|
last ready event.
|
||
|
|
|
||
|
|
These coordinates originate in the upper left corner of the buffer.
|
||
|
|
</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>
|
||
|
|
|
||
|
|
<event name="failed">
|
||
|
|
<description summary="commit failed">
|
||
|
|
This event indicates that the attempted frame copy has failed.
|
||
|
|
|
||
|
|
After receiving this event, the client must destroy the object.
|
||
|
|
</description>
|
||
|
|
<arg name="reason" type="uint" enum="failure_reason"/>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="presentation_time">
|
||
|
|
<description summary="indicates the presentation time of the frame">
|
||
|
|
This event indicates the time at which the frame is presented to the
|
||
|
|
output in system monotonic time.
|
||
|
|
|
||
|
|
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].
|
||
|
|
</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="ready">
|
||
|
|
<description summary="indicates frame is available for reading">
|
||
|
|
Called as soon as the frame is copied, indicating it is available
|
||
|
|
for reading.
|
||
|
|
|
||
|
|
The buffer may be re-used by the client after the "ready" event.
|
||
|
|
</description>
|
||
|
|
</event>
|
||
|
|
</interface>
|
||
|
|
|
||
|
|
<interface name="ext_screencopy_cursor_session_v1" version="1">
|
||
|
|
<request name="get_screencopy_session">
|
||
|
|
<description summary="get screencopy session">
|
||
|
|
Gets the screencopy session for this cursor session.
|
||
|
|
</description>
|
||
|
|
<arg name="session" type="new_id" interface="ext_screencopy_session_v1"/>
|
||
|
|
</request>
|
||
|
|
|
||
|
|
<event name="enter">
|
||
|
|
<description summary="cursor entered captured are">
|
||
|
|
Sent when a cursor enters the captured area. It shall be generated
|
||
|
|
before the "position" and "hotspot" events when and only when a cursor
|
||
|
|
enters the area.
|
||
|
|
</description>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="leave">
|
||
|
|
<description summary="cursor left area">
|
||
|
|
Sent when a cursor leaves the captured area. No "position" or "hotspot"
|
||
|
|
event is generated for the cursor.
|
||
|
|
</description>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="position">
|
||
|
|
<description summary="position changed">
|
||
|
|
Cursors outside the image source do not get captured and no event will
|
||
|
|
be generated for them.
|
||
|
|
|
||
|
|
The given position is the position of the cursor's hotspot and it is
|
||
|
|
relative to the main buffer's top left corner in transformed buffer
|
||
|
|
pixel coordinates.
|
||
|
|
|
||
|
|
The hotspot coordinates are relative to the cursor buffers upper left
|
||
|
|
corner.
|
||
|
|
</description>
|
||
|
|
<arg name="x" type="int" summary="position x coordinates"/>
|
||
|
|
<arg name="y" type="int" summary="position y coordinates"/>
|
||
|
|
</event>
|
||
|
|
|
||
|
|
<event name="hotspot">
|
||
|
|
<description summary="hotspot changed">
|
||
|
|
The given coordinates are the hotspot's offset from the origin in
|
||
|
|
buffer coordinates.
|
||
|
|
</description>
|
||
|
|
<arg name="x" type="int" summary="hotspot x coordinates"/>
|
||
|
|
<arg name="y" type="int" summary="hotspot y coordinates"/>
|
||
|
|
</event>
|
||
|
|
</interface>
|
||
|
|
</protocol>
|