aboutsummaryrefslogtreecommitdiff
path: root/protocol
diff options
context:
space:
mode:
authoremersion <contact@emersion.fr>2018-06-22 22:31:33 +0100
committeremersion <contact@emersion.fr>2018-06-30 22:18:03 +0100
commitbd8be19b792797925f5cca14049a5ab2d0f6d06c (patch)
tree8aca19c6cb99b38c80076116cf18c4ad4b4e2334 /protocol
parent73755ad348657fdf8d9e0f9a48ee13a2ab947e35 (diff)
screencopy: add presentation timestamp
Diffstat (limited to 'protocol')
-rw-r--r--protocol/wlr-screencopy-unstable-v1.xml48
1 files changed, 41 insertions, 7 deletions
diff --git a/protocol/wlr-screencopy-unstable-v1.xml b/protocol/wlr-screencopy-unstable-v1.xml
index 6bd5a75f..52f3385e 100644
--- a/protocol/wlr-screencopy-unstable-v1.xml
+++ b/protocol/wlr-screencopy-unstable-v1.xml
@@ -26,6 +26,15 @@
<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="1">
@@ -36,9 +45,11 @@
<request name="capture_output">
<description summary="start capturing">
- Request to start capturing from the given output.
+ Capture the next frame of a an entire output.
</description>
<arg name="frame" type="new_id" interface="zwlr_screencopy_frame_v1"/>
+ <arg name="overlay_cursor" type="int"
+ summary="include custom client hardware cursor on top of the frame"/>
<arg name="output" type="object" interface="wl_output"/>
</request>
@@ -52,8 +63,17 @@
<interface name="zwlr_screencopy_frame_v1" version="1">
<description summary="a frame ready for copy">
- This object represents a frame which is ready to have its resources
- fetched and used.
+ This object represents a single frame.
+
+ When created, a "buffer" event will be sent. The client will then be able
+ to send a "copy" request. If the capture is successful, the compositor
+ will finally a "ready" event.
+
+ 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>
<enum name="flags" bitfield="true">
@@ -99,23 +119,37 @@
<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.
+ 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.
- Upon receiving this event, the client should destroy the object.
+ 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.
- Upon receiving this event, the client should destroy the object.
+ 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.
+ Destroys the frame. This request can be sent at any time by the client.
</description>
</request>
</interface>