[RFCv3.1 weston] WIP protocol: add flags and refresh stream to presentation

[Pekka Paalanen]

From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>

This is quick write-up of
http://cgit.collabora.com/git/user/pq/weston.git/tree/buffer-queue3.txt?h=buffer-queue-spec

How would this idea feel?

Thanks,
pq
---
 protocol/presentation_timing.xml | 66 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/protocol/presentation_timing.xml b/protocol/presentation_timing.xml
index e191b87..7da735b 100644
--- a/protocol/presentation_timing.xml
+++ b/protocol/presentation_timing.xml
@@ -235,6 +235,24 @@
            summary="new feedback object"/>
     </request>
 
+    <enum name="queue">
+      <description summary="queueing flags">
+        The no-skip flag will cause the compositor to never discard the
+        flagged update. Instead, it will postpone following updates to the
+        next output refresh cycle if needed to ensure, that this update
+        will be on screen for at least one refresh cycle.
+
+        Normally, the compositor will try to match the given target timestamp
+        to the closest refresh cycle, which means that the update may hit
+        the screen slightly earlier than requested. Not-before flag guarantees
+        that the update is never shown before the given target time.
+      </description>
+
+      <entry name="no_skip" value="1" summary="never skip this update"/>
+      <entry name="not_before" value="2"
+             summary="do not show the update before the target time"/>
+    </enum>
+
     <request name="queue">
       <description summary="queue the buffer instead of immediate presentation">
         This request changes the behaviour of the very next
@@ -265,6 +283,7 @@
            summary="low 32 bits of the seconds part of the target timestamp"/>
       <arg name="tv_nsec" type="uint"
            summary="nanoseconds part of the target timestamp"/>
+      <arg name="flags" type="uint" summary="queueing flags"/>
     </request>
 
     <request name="discard_queue">
@@ -288,6 +307,16 @@
            summary="target surface"/>
     </request>
 
+    <request name="open_refresh_stream">
+      <description summary="">
+      </description>
+
+      <arg name="surface" type="object" interface="wl_surface"
+           summary="target surface"/>
+      <arg name="callback" type="new_id" interface="refresh_stream"
+           summary="new refresh stream delivering events"/>
+    </request>
+
     <event name="clock_id">
       <description summary="clock ID for timestamps">
         This event tells the client, in which clock domain the
@@ -366,6 +395,19 @@
            summary="presentation output"/>
     </event>
 
+    <enum name="kind">
+      <description summary="bitmask of flags in presented event">
+      </description>
+
+      <entry name="vsync" value="1" summary="presentation was vsync'd"/>
+      <entry name="user_clock" value="2"
+             summary="timestamp was retrieved by user space reading a clock"/>
+      <entry name="hw_completion" value="4"
+             summary="hardware signalled the completion of the presentation"/>
+      <entry name="copy" value="8"
+             summary="final presentation was done as a copy, not a flip"/>
+    </enum>
+
     <event name="presented">
       <description summary="the content update was displayed">
         The associated content update was displayed to the user at the
@@ -422,6 +464,7 @@
            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 'kind' values"/>
     </event>
 
     <event name="discarded">
@@ -431,4 +474,27 @@
     </event>
   </interface>
 
+  <interface name="refresh_stream" version="1">
+    <description summary="delivers refresh events">
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="close the refresh stream">
+      </description>
+    </request>
+
+    <event name="refresh">
+      <arg name="tv_sec_hi" type="uint"
+           summary="high 32 bits of the seconds part of the presentation timestamp"/>
+      <arg name="tv_sec_lo" type="uint"
+           summary="low 32 bits of the seconds part of the presentation timestamp"/>
+      <arg name="tv_nsec" type="uint"
+           summary="nanoseconds part of the presentation timestamp"/>
+      <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"/>
+    </event>
+  </interface>
+
 </protocol>
-- 
1.8.3.2