You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
457 lines
19 KiB
457 lines
19 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<protocol name="ext_image_copy_capture_v1">
|
|
<copyright>
|
|
Copyright © 2021-2023 Andri Yngvason
|
|
Copyright © 2024 Simon Ser
|
|
|
|
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="image capturing into client buffers">
|
|
This protocol allows clients to ask the compositor to capture image sources
|
|
such as outputs and toplevels into user submitted buffers.
|
|
|
|
Warning! The protocol described in this file is currently in the testing
|
|
phase. Backward compatible changes may be added together with the
|
|
corresponding interface version bump. Backward incompatible changes can
|
|
only be done by creating a new major version of the extension.
|
|
</description>
|
|
|
|
<interface name="ext_image_copy_capture_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="error">
|
|
<entry name="invalid_option" value="1" summary="invalid option flag"/>
|
|
</enum>
|
|
|
|
<enum name="options" bitfield="true">
|
|
<entry name="paint_cursors" value="1" summary="paint cursors onto captured frames"/>
|
|
</enum>
|
|
|
|
<request name="create_session">
|
|
<description summary="capture an image capture source">
|
|
Create a capturing session for an image capture source.
|
|
|
|
If the paint_cursors option is set, cursors shall be composited onto
|
|
the captured frame. The cursor must not be composited onto the frame
|
|
if this flag is not set.
|
|
|
|
If the options bitfield is invalid, the invalid_option protocol error
|
|
is sent.
|
|
</description>
|
|
<arg name="session" type="new_id" interface="ext_image_copy_capture_session_v1"/>
|
|
<arg name="source" type="object" interface="ext_image_capture_source_v1"/>
|
|
<arg name="options" type="uint" enum="options"/>
|
|
</request>
|
|
|
|
<request name="create_pointer_cursor_session">
|
|
<description summary="capture the pointer cursor of an image capture source">
|
|
Create a cursor capturing session for the pointer of an image capture
|
|
source.
|
|
</description>
|
|
<arg name="session" type="new_id" interface="ext_image_copy_capture_cursor_session_v1"/>
|
|
<arg name="source" type="object" interface="ext_image_capture_source_v1"/>
|
|
<arg name="pointer" type="object" interface="wl_pointer"/>
|
|
</request>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="destroy the manager">
|
|
Destroy the manager object.
|
|
|
|
Other objects created via this interface are unaffected.
|
|
</description>
|
|
</request>
|
|
</interface>
|
|
|
|
<interface name="ext_image_copy_capture_session_v1" version="1">
|
|
<description summary="image copy capture session">
|
|
This object represents an active image copy capture session.
|
|
|
|
After a capture 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. The compositor may
|
|
re-send buffer constraint events whenever they change.
|
|
|
|
The advertise buffer constraints, the compositor must send in no
|
|
particular order: zero or more shm_format and dmabuf_format events, zero
|
|
or one dmabuf_device event, and exactly one buffer_size event. Then the
|
|
compositor must send a done event.
|
|
|
|
When the client has received all the buffer constraints, it can create a
|
|
buffer accordingly, attach it to the capture session using the
|
|
attach_buffer request, set the buffer damage using the damage_buffer
|
|
request and then send the capture request.
|
|
</description>
|
|
|
|
<enum name="error">
|
|
<entry name="duplicate_frame" value="1"
|
|
summary="create_frame sent before destroying previous frame"/>
|
|
</enum>
|
|
|
|
<event name="buffer_size">
|
|
<description summary="image capture source dimensions">
|
|
Provides the dimensions of the source image in buffer pixel coordinates.
|
|
|
|
The client must attach buffers that match this size.
|
|
</description>
|
|
<arg name="width" type="uint" summary="buffer width"/>
|
|
<arg name="height" type="uint" summary="buffer height"/>
|
|
</event>
|
|
|
|
<event name="shm_format">
|
|
<description summary="shm buffer format">
|
|
Provides the format that must be used for shared-memory buffers.
|
|
|
|
This event 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="dmabuf_device">
|
|
<description summary="dma-buf device">
|
|
This event advertises the device buffers must be allocated on for
|
|
dma-buf buffers.
|
|
|
|
In general the device is a DRM node. The DRM node type (primary vs.
|
|
render) is unspecified. Clients must not rely on the compositor sending
|
|
a particular node type. Clients cannot check two devices for equality
|
|
by comparing the dev_t value.
|
|
</description>
|
|
<arg name="device" type="array" summary="device dev_t value"/>
|
|
</event>
|
|
|
|
<event name="dmabuf_format">
|
|
<description summary="dma-buf format">
|
|
Provides the format that must be used for dma-buf buffers.
|
|
|
|
The client may choose any of the modifiers advertised in the array of
|
|
64-bit unsigned integers.
|
|
|
|
This event may be emitted multiple times, in which case the client may
|
|
choose any given format.
|
|
</description>
|
|
<arg name="format" type="uint" summary="drm format code"/>
|
|
<arg name="modifiers" type="array" summary="drm format modifiers"/>
|
|
</event>
|
|
|
|
<event name="done">
|
|
<description summary="all constraints have been sent">
|
|
This event is sent once when all buffer constraint events have been
|
|
sent.
|
|
|
|
The compositor must always end a batch of buffer constraint events with
|
|
this event, regardless of whether it sends the initial constraints or
|
|
an update.
|
|
</description>
|
|
</event>
|
|
|
|
<event name="stopped">
|
|
<description summary="session is no longer available">
|
|
This event indicates that the capture session has stopped and is no
|
|
longer available. This can happen in a number of cases, e.g. when the
|
|
underlying source is destroyed, if the user decides to end the image
|
|
capture, or if an unrecoverable runtime error has occurred.
|
|
|
|
The client should destroy the session after receiving this event.
|
|
</description>
|
|
</event>
|
|
|
|
<request name="create_frame">
|
|
<description summary="create a frame">
|
|
Create a capture frame for this session.
|
|
|
|
At most one frame object can exist for a given session at any time. If
|
|
a client sends a create_frame request before a previous frame object
|
|
has been destroyed, the duplicate_frame protocol error is raised.
|
|
</description>
|
|
<arg name="frame" type="new_id" interface="ext_image_copy_capture_frame_v1"/>
|
|
</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.
|
|
|
|
This request doesn't affect ext_image_copy_capture_frame_v1 objects created by
|
|
this object.
|
|
</description>
|
|
</request>
|
|
</interface>
|
|
|
|
<interface name="ext_image_copy_capture_frame_v1" version="1">
|
|
<description summary="image capture frame">
|
|
This object represents an image capture frame.
|
|
|
|
The client should attach a buffer, damage the buffer, and then send a
|
|
capture request.
|
|
|
|
If the capture is successful, the compositor must send the frame metadata
|
|
(transform, damage, presentation_time in any order) followed by the ready
|
|
event.
|
|
|
|
If the capture fails, the compositor must send the failed event.
|
|
</description>
|
|
|
|
<enum name="error">
|
|
<entry name="no_buffer" value="1" summary="capture sent without attach_buffer"/>
|
|
<entry name="invalid_buffer_damage" value="2" summary="invalid buffer damage"/>
|
|
<entry name="already_captured" value="3" summary="capture request has been sent"/>
|
|
</enum>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="destroy this object">
|
|
Destroys the session. This request can be sent at any time by the
|
|
client.
|
|
</description>
|
|
</request>
|
|
|
|
<request name="attach_buffer">
|
|
<description summary="attach buffer to session">
|
|
Attach a buffer to the session.
|
|
|
|
The wl_buffer.release request is unused.
|
|
|
|
The new buffer replaces any previously attached buffer.
|
|
|
|
This request must not be sent after capture, or else the
|
|
already_captured protocol error is raised.
|
|
</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 captured next. This request
|
|
may be sent multiple times to describe a region.
|
|
|
|
The client indicates the accumulated damage since this wl_buffer was
|
|
last captured. During capture, the compositor will update the buffer
|
|
with at least the union of the region passed by the client and the
|
|
region advertised by ext_image_copy_capture_frame_v1.damage.
|
|
|
|
When a wl_buffer is captured for the first time, or when the client
|
|
doesn't track damage, the client must damage the whole buffer.
|
|
|
|
This is for optimisation purposes. The compositor may use this
|
|
information to reduce copying.
|
|
|
|
These coordinates originate from the upper left corner of the buffer.
|
|
|
|
If x or y are strictly negative, or if width or height are negative or
|
|
zero, the invalid_buffer_damage protocol error is raised.
|
|
|
|
This request must not be sent after capture, or else the
|
|
already_captured protocol error is raised.
|
|
</description>
|
|
<arg name="x" type="int" summary="region x coordinate"/>
|
|
<arg name="y" type="int" summary="region y coordinate"/>
|
|
<arg name="width" type="int" summary="region width"/>
|
|
<arg name="height" type="int" summary="region height"/>
|
|
</request>
|
|
|
|
<request name="capture">
|
|
<description summary="capture a frame">
|
|
Capture a frame.
|
|
|
|
Unless this is the first successful captured frame performed in this
|
|
session, the compositor may wait an indefinite amount of time for the
|
|
source content to change before performing the copy.
|
|
|
|
This request may only be sent once, or else the already_captured
|
|
protocol error is raised. A buffer must be attached before this request
|
|
is sent, or else the no_buffer protocol error is raised.
|
|
</description>
|
|
</request>
|
|
|
|
<event name="transform">
|
|
<description summary="buffer transform">
|
|
This event is sent before the ready event and holds the transform that
|
|
the compositor has applied to the buffer contents.
|
|
</description>
|
|
<arg name="transform" type="uint" enum="wl_output.transform"/>
|
|
</event>
|
|
|
|
<event name="damage">
|
|
<description summary="buffer damaged region">
|
|
This event is sent before the ready event. It may be generated multiple
|
|
times to describe a region.
|
|
|
|
The first captured frame in a session will always carry full damage.
|
|
Subsequent frames' damaged regions describe which parts of the buffer
|
|
have changed since the last ready event.
|
|
|
|
These coordinates originate in the upper left corner of the buffer.
|
|
</description>
|
|
<arg name="x" type="int" summary="damage x coordinate"/>
|
|
<arg name="y" type="int" summary="damage y coordinate"/>
|
|
<arg name="width" type="int" summary="damage width"/>
|
|
<arg name="height" type="int" summary="damage height"/>
|
|
</event>
|
|
|
|
<event name="presentation_time">
|
|
<description summary="presentation time of the frame">
|
|
This event indicates the time at which the frame is presented to the
|
|
output in system monotonic time. This event is sent before the ready
|
|
event.
|
|
|
|
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="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 this event.
|
|
|
|
After receiving this event, the client must destroy the object.
|
|
</description>
|
|
</event>
|
|
|
|
<enum name="failure_reason">
|
|
<entry name="unknown" value="0">
|
|
<description summary="unknown runtime error">
|
|
An unspecified runtime error has occurred. The client may retry.
|
|
</description>
|
|
</entry>
|
|
<entry name="buffer_constraints" value="1">
|
|
<description summary="buffer constraints mismatch">
|
|
The buffer submitted by the client doesn't match the latest session
|
|
constraints. The client should re-allocate its buffers and retry.
|
|
</description>
|
|
</entry>
|
|
<entry name="stopped" value="2">
|
|
<description summary="session is no longer available">
|
|
The session has stopped. See ext_image_copy_capture_session_v1.stopped.
|
|
</description>
|
|
</entry>
|
|
</enum>
|
|
|
|
<event name="failed">
|
|
<description summary="capture 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>
|
|
</interface>
|
|
|
|
<interface name="ext_image_copy_capture_cursor_session_v1" version="1">
|
|
<description summary="cursor capture session">
|
|
This object represents a cursor capture session. It extends the base
|
|
capture session with cursor-specific metadata.
|
|
</description>
|
|
|
|
<enum name="error">
|
|
<entry name="duplicate_session" value="1" summary="get_captuerer_session sent twice"/>
|
|
</enum>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="delete this object">
|
|
Destroys the session. This request can be sent at any time by the
|
|
client.
|
|
|
|
This request doesn't affect ext_image_copy_capture_frame_v1 objects created by
|
|
this object.
|
|
</description>
|
|
</request>
|
|
|
|
<request name="get_capture_session">
|
|
<description summary="get image copy captuerer session">
|
|
Gets the image copy capture session for this cursor session.
|
|
|
|
The session will produce frames of the cursor image. The compositor may
|
|
pause the session when the cursor leaves the captured area.
|
|
|
|
This request must not be sent more than once, or else the
|
|
duplicate_session protocol error is raised.
|
|
</description>
|
|
<arg name="session" type="new_id" interface="ext_image_copy_capture_session_v1"/>
|
|
</request>
|
|
|
|
<event name="enter">
|
|
<description summary="cursor entered captured area">
|
|
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.
|
|
|
|
The cursor enters the captured area when the cursor image intersects
|
|
with the captured area. Note, this is different from e.g.
|
|
wl_pointer.enter.
|
|
</description>
|
|
</event>
|
|
|
|
<event name="leave">
|
|
<description summary="cursor left captured area">
|
|
Sent when a cursor leaves the captured area. No "position" or "hotspot"
|
|
event is generated for the cursor until the cursor enters the captured
|
|
area again.
|
|
</description>
|
|
</event>
|
|
|
|
<event name="position">
|
|
<description summary="position changed">
|
|
Cursors outside the image capture 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 coordinates may be negative or greater than the
|
|
main buffer size.
|
|
</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 hotspot describes the offset between the cursor image and the
|
|
position of the input device.
|
|
|
|
The given coordinates are the hotspot's offset from the origin in
|
|
buffer coordinates.
|
|
|
|
Clients should not apply the hotspot immediately: the hotspot becomes
|
|
effective when the next ext_image_copy_capture_frame_v1.ready event is received.
|
|
|
|
Compositors may delay this event until the client captures a new frame.
|
|
</description>
|
|
<arg name="x" type="int" summary="hotspot x coordinates"/>
|
|
<arg name="y" type="int" summary="hotspot y coordinates"/>
|
|
</event>
|
|
</interface>
|
|
</protocol>
|