[RFC wayland-protocols] presentation-time: Add request to subscribe to wl_output presentation timings

[Alexandros Frantzis]

Hi Pekka,

I have updated the RFC patch with the changes discussed until now.

I haven't got any feedback yet from the Chromium team about associating
the timing object to wl_surface. I will provide further updates when I
get more information. In any case, I think the updated patch is a good
basis for further discussion and development regardless of the path we
follow.

Note that for RFC completeness I have added the flag enumeration in the
patch, but it causes the wayland-scanner to fail since it doesn't
currently contain any values.

Thanks,
Alexandros

---
 stable/presentation-time/presentation-time.xml | 108 ++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 3 deletions(-)

diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml
index a46994c..1a8195f 100644
--- a/stable/presentation-time/presentation-time.xml
+++ b/stable/presentation-time/presentation-time.xml
@@ -3,7 +3,8 @@
 <!-- wrap:70 -->
 
   <copyright>
-    Copyright © 2013-2014 Collabora, Ltd.
+    Copyright © 2013-2017 Collabora, Ltd.
+    Copyright © 2016 The Chromium Authors.
 
     Permission is hereby granted, free of charge, to any person obtaining a
     copy of this software and associated documentation files (the "Software"),
@@ -25,8 +26,8 @@
     DEALINGS IN THE SOFTWARE.
   </copyright>
 
-  <interface name="wp_presentation" version="1">
-    <description summary="timed presentation related wl_surface requests">
+  <interface name="wp_presentation" version="2">
+    <description summary="timed presentation related requests">
 
 <!-- Introduction -->
 
@@ -49,6 +50,16 @@
       presentation time can differ from the compositor's predicted
       display update time and the update's target time, especially
       when the compositor misses its target vertical blanking period.
+
+<!-- Presentation timing -->
+
+      In some cases it's also useful for clients to know about the
+      presentation timing of an output without having submitted a
+      surface content update. For this purpose the 'timing' request
+      creates an object that is used to inform the client about
+      the presentation timing of an wl_output in a precise and
+      low-overhead way.
+
     </description>
 
     <enum name="error">
@@ -122,6 +133,27 @@
       <arg name="clk_id" type="uint" summary="platform clock identifier"/>
     </event>
 
+    <!-- Version 2 additions -->
+
+    <request name="timing" since="2">
+      <description summary="request timing information">
+        Create a new timing object that represents a subscription to
+        presentation timing updates on the given wl_output object.
+
+        The newly created object will signal an update to notify the
+        subscriber of initial timing parameters as soon as these
+        become available.
+
+        If the given wl_output is destroyed before the initial timing
+        parameters become available, then no initial update event will
+        be sent.
+      </description>
+      <arg name="output" type="object" interface="wl_output"
+           summary="the wl_output object to subscribe for timings of"/>
+      <arg name="id" type="new_id" interface="wp_presentation_timing"
+           summary="the new timing object"/>
+    </request>
+
   </interface>
 
   <interface name="wp_presentation_feedback" version="1">
@@ -263,4 +295,74 @@
     </event>
   </interface>
 
+  <interface name="wp_presentation_timing" version="1">
+    <description summary="presentation timing event">
+      A presentation_timing object provides information about the expected
+      presentation times on the associated wl_output.
+
+      When the wl_output associated with a presentation_timing object is
+      destroyed by either the client or the compositor, the presentation_timing
+      object becomes inert. No more events are emitted and the the client
+      is responsible for destroying the object.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy timing object">
+        Destroy this timing object.
+      </description>
+    </request>
+
+    <enum name="flag">
+      <description summary="bitmask of flags in updated event">
+        These flags provide additional information about the timing reported in
+        the 'updated' event. The intent is to help clients assess the reliability
+        of the timing.
+      </description>
+    </enum>
+
+    <event name="updated">
+      <description summary="the timing has been updated">
+        Notifies the client that the presentation timing information of
+        the associated wl_output has changed.
+
+        Timing information consists of the timebase and the interval. This
+        event informs clients that presentation on the associated output is
+        expected to occur at regular intervals of duration 'interval' starting
+        at time 'timebase', i.e., at the following time points:
+
+          timebase + N * interval, for N=1,2,...
+
+        Change to any timing parameter (i.e., either timebase or interval) may
+        cause this event to be emitted.
+
+        For the interpretation of the timebase see the information about the
+        related timestamp ('tv_*') argument in the presentation.presented event.
+
+        For the interpretation of the interval see the information about the
+        related 'refresh' argument in the presentation.presented event.
+
+        If the server cannot accurately predict the interval between subsequent
+        presentation events for the output, or the output does not have a
+        constant presentation rate, then the interval argument must be zero.
+        Note that the inability to predict the interval may be temporary.
+
+        For the interpretion of seq_hi and seq_lo, see the related information
+        in the presentation.presented event.
+      </description>
+      <arg name="timebase_tv_sec_hi" type="uint"
+           summary="high 32 bits of the seconds part of the new presentation timebase"/>
+      <arg name="timebase_tv_sec_low" type="uint"
+           summary="low 32 bits of the seconds part of the new presentation timebase"/>
+      <arg name="timebase_tv_nsec" type="uint"
+           summary="nanoseconds part of the new presentation timebase"/>
+      <arg name="interval" type="uint"
+           summary="new presentation interval in nanoseconds"/>
+      <arg name="seq_hi" type="uint"
+           summary="high 32 bits of refresh counter"/>
+      <arg name="seq_lo" type="uint"
+           summary="low 32 bits of refresh counter"/>
+      <arg name="flags" type="uint" summary="combination of 'flag' values"/>
+    </event>
+  </interface>
+
 </protocol>
-- 
2.14.1