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

[Alexandros Frantzis]

The presentation.timing request creates an object that informs the
client about the presentation timing of an wl_output in a precise and
low-overhead way, without the need to submit any surface content updates.

This functionality can be useful, among others, for clients that want to know
the output timings before submitting any frames, and also for clients that
want to synchronize with server presentation timings using a simpler and lower
overhead way compared to the presentation.feedback objects.

This functionality is inspired by the vsync-feedback protocol used in
Chromium OS ([1]), and, hopefully, with such an addition, Chromium OS may
be able to transition to the upstream protocol.

It may be useful to add a flags argument to the presentation_timing.updated
event, containing information that can be used to assess the reliability (and
other aspects) of the provided information, in a manner similar to the 'kind'
flags for the presentation_feedback.presented event.

A proof-of-concept implementation for Weston can be found at:

https://git.collabora.com/cgit/user/alf/weston.git/log/?h=presentation-time-v2

[1] https://chromium.googlesource.com/chromium/src/third_party/+/master/wayland-protocols/unstable/vsync-feedback/vsync-feedback-unstable-v1.xml

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

diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml
index a46994c..56a9c9b 100644
--- a/stable/presentation-time/presentation-time.xml
+++ b/stable/presentation-time/presentation-time.xml
@@ -3,7 +3,7 @@
 <!-- wrap:70 -->
 
   <copyright>
-    Copyright © 2013-2014 Collabora, Ltd.
+    Copyright © 2013-2017 Collabora, Ltd.
 
     Permission is hereby granted, free of charge, to any person obtaining a
     copy of this software and associated documentation files (the "Software"),
@@ -25,8 +25,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 +49,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 +132,22 @@
       <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.
+      </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 +289,40 @@
     </event>
   </interface>
 
+  <interface name="wp_presentation_timing" version="1">
+    <request name="destroy" type="destructor">
+      <description summary="destroy timing object">
+        Destroy this timing object.
+      </description>
+    </request>
+
+    <event name="updated">
+      <description summary="the timing has been updated">
+        Notifies the client that the timing of the associated wl_output
+        has changed.
+
+        Timing information consists of two data, timebase and interval.
+        Timebase is an absolute timestamp of the event that caused the
+        timing to change. Interval is a period of time between subsequent
+        presentation events.
+
+        For the interpretation of the timestamp, see presentation.clock_id
+        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.
+      </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"/>
+    </event>
+  </interface>
+
 </protocol>
-- 
2.13.2