[PATCH weston 2/6] protocol: add Presentation feedback flags

[Pekka Paalanen]

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

Add the missing feedback flags to the Presentation extension protocol
specification.

These flags are slightly different from the previous RFCv3.1 definition:
http://lists.freedesktop.org/archives/wayland-devel/2014-March/013598.html

Now, all compositors are safe to use 0 as the flags if they don't bother
setting them properly. 0 is the "worst case" with the least guarantees.

The meaning of ZERO_COPY is not exactly the opposite of the old COPY
flag. ZERO_COPY is more strict, but applies only to that one surface.
Therefore it can be used to verify a zero-copy video playback pipeline,
also to a hardware overlay.

There is no longer a flag to clearly indicate if the final presentation
was done by a copy or a page flip. ZERO_COPY forbids the copy, but VSYNC
alone does allow copy in case it cannot tear.  It is possible to have
first a compositing pass, and then another copy into the frontbuffer,
and still set VSYNC if it cannot tear.  Usually "cannot tear" is too
hard to guarantee with a copy, so it often implies a page flip.

Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
Cc: Mario Kleiner <mario.kleiner.de at gmail.com>
---
 protocol/presentation_timing.xml | 42 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/protocol/presentation_timing.xml b/protocol/presentation_timing.xml
index 5752c13..4058d47 100644
--- a/protocol/presentation_timing.xml
+++ b/protocol/presentation_timing.xml
@@ -164,11 +164,47 @@
 
     <enum name="kind">
       <description summary="bitmask of flags in presented event">
-        Currently no flags are defined. Some flags will be added
-        into presentation_feedback version 1 before it is released.
+        These flags provide information about how the presentation of
+        the related content update was done. The intent is to help
+        clients assess the reliability of the feedback and the visual
+        quality with respect to possible tearing and timings. The
+        flags are:
+
+        VSYNC:
+        The presentation was synchronized to the "vertical retrace" by
+        the display hardware such that tearing does not happen.
+        Relying on user space scheduling is not acceptable for this
+        flag. If presentation is done by a copy to the active
+        frontbuffer, then it must guarantee that tearing cannot
+        happen.
+
+        HW_CLOCK:
+        The display hardware provided measurements that the hardware
+        driver converted into a presentation timestamp. Sampling a
+        clock in user space is not acceptable for this flag.
+
+        HW_COMPLETION:
+        The display hardware signalled that it started using the new
+        image content. The opposite of this is e.g. a timer being used
+        to guess when the display hardware has switched to the new
+        image content.
+
+        ZERO_COPY:
+        The presentation of this update was done zero-copy. This means
+        the buffer from the client was given to display hardware as
+        is, without copying it. Compositing with OpenGL counts as
+        copying, even if textured directly from the client buffer.
+        Possible zero-copy cases include direct scanout of a
+        fullscreen surface and a surface on a hardware overlay.
       </description>
 
-      <entry name="dummy" value="0"/>
+      <entry name="vsync" value="0x1" summary="presentation was vsync'd"/>
+      <entry name="hw_clock" value="0x2"
+             summary="hardware provided the presentation timestamp"/>
+      <entry name="hw_completion" value="0x4"
+             summary="hardware signalled the start of the presentation"/>
+      <entry name="zero_copy" value="0x8"
+             summary="presentation was done zero-copy"/>
     </enum>
 
     <event name="presented">
-- 
2.0.4