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

Thu Aug 31 15:37:05 UTC 2017

On Fri, Aug 25, 2017 at 12:08:39PM +0300, Pekka Paalanen wrote:
> On Fri, 18 Aug 2017 16:09:42 +0300
> Alexandros Frantzis <alexandros.frantzis at collabora.com> wrote:
> 
> > 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.
> 
> Hi,
> 
> cool. The spec looks good to me, but I still had a few comments below.
> 

Hi Pekka,

thank you for the additional feedback. I have attached an updated
version which addresses your comments.

I still haven't got any feedback from Chromium concerning the potential
change from wl_output based timings to wl_surface based timings as
discussed in previous emails, so, for the time being, I am keeping this
proposal in RFC status.

> Yes, the spirit of the text is good. The "wl_output ... destroyed by
> client or compositor" actually referes to two different concepts and as
> is might be slightly confusing as the server cannot destroy the
> wl_output proxy. IOW, the client can destroy the proxy, and the server
> can destroy the global.

I have changed the text to mention only the destruction of the wl_output
global from the server as making the timing object inert (i.e.,
destroying the wl_output proxy has no effect).

diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml
index a46994c..0531ff7 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 global associated with the given wl_output is destroyed
+        by the server 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,77 @@
     </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 global associated with a presentation_timing object is
+      destroyed by the server, the presentation_timing object becomes inert.
+      No more events are emitted and 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" bitfield="true">
+      <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>
+      <entry name="defaults" value="0"
+             summary="default flags"/>
+    </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 wp_presentation_feedback.presented
+        event.
+
+        For the interpretation of the interval see the information about the
+        related 'refresh' argument in the wp_presentation_feedback.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 wp_presentation_feedback.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" enum="flag" summary="combination of 'flag' values"/>
+    </event>
+  </interface>
+
 </protocol>
