From 3674a4181b4e6ba5d2e05081d8727e1465d73a04 Mon Sep 17 00:00:00 2001
From: Greg Lamberson <greg@lamco.io>
Date: Sat, 9 May 2026 14:56:47 -0500
Subject: [PATCH] ext-image-copy-capture: add capture_time event

Adds an optional capture_time event on ext_image_copy_capture_frame_v1
that reports the CLOCK_MONOTONIC time at which the compositor sampled
the source content into the capture buffer. It is the symmetric
counterpart of the existing presentation_time event on the same
interface, uses the same tv_sec_hi/tv_sec_lo/tv_nsec triple, and is
sent before ready.

The event is informational and does not change the buffer delivery
contract or the meaning of ready. Compositors may emit it when they
can determine the sampling time precisely; consumers must handle
absence gracefully.

Capture clients (wayvnc, lamco-rdp-server) use the timestamp to
compute the budget remaining in the current frame interval for codec
selection, and as the source timestamp on any downstream encoded
stream the capture client produces.

Bumps frame_v1 and manager_v1 to version 2.

Closes #309.

Signed-off-by: Greg Lamberson <greg@lamco.io>
---
 .../ext-image-copy-capture-v1.xml             | 40 ++++++++++++++++++-
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml b/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml
index 1ac4369..d541bdc 100644
--- a/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml
+++ b/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml
@@ -34,7 +34,7 @@
     only be done by creating a new major version of the extension.
   </description>
 
-  <interface name="ext_image_copy_capture_manager_v1" version="1">
+  <interface name="ext_image_copy_capture_manager_v1" version="2">
     <description summary="manager to inform clients and begin capturing">
       This object is a manager which offers requests to start capturing from a
       source.
@@ -199,7 +199,7 @@
     </request>
   </interface>
 
-  <interface name="ext_image_copy_capture_frame_v1" version="1">
+  <interface name="ext_image_copy_capture_frame_v1" version="2">
     <description summary="image capture frame">
       This object represents an image capture frame.
 
@@ -367,6 +367,42 @@
       </description>
       <arg name="reason" type="uint" enum="failure_reason"/>
     </event>
+
+    <event name="capture_time" since="2">
+      <description summary="time at which the source content was sampled">
+        This event reports the time, in CLOCK_MONOTONIC, at which the
+        compositor sampled the source content into the capture buffer
+        for this frame. It is the symmetric counterpart of the
+        presentation_time event on the same interface: presentation_time
+        reports when the frame was or will be presented on its output;
+        capture_time reports when the frame's content was captured.
+
+        Together with the wall-clock time at which the client receives
+        the ready event, this allows the client to determine how much
+        time has elapsed between the source becoming current and the
+        buffer becoming readable, and to embed an accurate source
+        timestamp in any downstream stream encoded from this frame.
+
+        Compositors may emit this event before the ready event.
+        Compositors that cannot determine the sampling time precisely
+        must not send this event; consumers must handle absence
+        gracefully.
+
+        At most one capture_time event is sent per frame. The format of
+        the timestamp matches presentation_time: the seconds part is a
+        64-bit value combined from tv_sec_hi and tv_sec_lo, and tv_nsec
+        is in [0, 999999999].
+
+        This event is informational. It does not change the buffer
+        delivery contract or the meaning of the ready event.
+      </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>
   </interface>
 
   <interface name="ext_image_copy_capture_cursor_session_v1" version="1">