[PATCH] Add presentation_time and hit requests to wl_surface.

[Axel Davy]

These two new requests are designed to help video players
to synchronize what is displayed on the screen and the audio,
and to implement the X Present extension in XWayland.
---
 protocol/wayland.xml | 70 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index a1df007..553af61 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -959,7 +959,7 @@
     </event>
   </interface>
 
-  <interface name="wl_surface" version="3">
+  <interface name="wl_surface" version="4">
     <description summary="an onscreen surface">
       A surface is a rectangular area that is displayed on the screen.
       It has a location, size and pixel contents.
@@ -1057,8 +1057,9 @@
 
     <request name="frame">
       <description summary="request repaint feedback">
-	Request notification when the next frame is displayed. Useful
-	for throttling redrawing operations, and driving animations.
+	Request notification when the next frame is used for the first time
+	by the compositor. Useful for throttling redrawing operations, and
+	driving animations.
 	The frame request will take effect on the next wl_surface.commit.
 	The notification will only be posted for one frame unless
 	requested again.
@@ -1235,6 +1236,69 @@
     </request>
    </interface>
 
+    <!-- Version 4 additions -->
+
+    <request name="presentation_time" since="4">
+      <description summary="request the frame of next commit to hit the screen at a specific time">
+	This request is used to indicate the compositor at which ust time the
+	client wish the frame of next commit to hit the screen.
+
+	The request will take effect on the next wl_surface.commit.
+	The ust time indicated is in Milliseconds.
+
+	If the ust time requested has already happened, then the next commit
+	will be processed as any other commit.
+
+	The client can do another commit request without cancelling
+	a commit associated to a requested presentation time that has not
+	already happened.
+
+	The compositor can choose to ignore the indicated ust time, and for
+	example, if the client has queued too much buffers, it can choose to
+	treat some past commit with a future ust time, as commits with no
+	ust time indicated.
+
+	Calling a second time presentation_time on a wl_surface without doing
+	a commit will replace the last ust time indicated.
+      </description>
+
+      <arg name="ust" type="uint"/>
+    </request>
+
+    <request name="hit" since="4">
+      <description summary="request hit feedback">
+	Request notification when the next frame hits a physical screen.
+	This notification, which should happen after the frame notification,
+	can be used to synchronize video and audio better. The time given
+	will be ust time, in Milliseconds.
+
+	If, for any reason, the compositor determines that the frame will
+	never hit the screen, then the callback is called with 0 as argument,
+	instead of the ust time. One possible reason is that the compositor
+	choose to use a newer frame sent by the client.
+
+	The client is not supposed to throttle its drawing to this
+	notification, but to the frame notification.
+
+	If the frame hits multiple physical screens, only the first time it
+	hits a screen triggers the hit callback.
+
+	The hit request will take effect on the next wl_surface.commit.
+	The notification will only be posted for one frame unless
+	requested again.
+
+	A client can request a hit callback even without an attach,
+	damage, or any other state changes, since wl_surface.commit triggers a
+	display update.
+
+	The object returned by this request will be destroyed by the
+	compositor after the callback is fired and as such the client must not
+	attempt to use it after that point.
+      </description>
+
+      <arg name="callback" type="new_id" interface="wl_callback"/>
+    </request>
+
   <interface name="wl_seat" version="3">
     <description summary="group of input devices">
       A seat is a group of keyboards, pointer and touch devices. This
-- 
1.8.1.2