From: Pekka Paalanen <ppaalanen@gmail.com>
Date: Wed, 10 Oct 2012 09:47:49 +0000 (+0300)
Subject: protocol: wl_surface.frame needs wl_surface.commit
X-Git-Tag: 0.99.0~39
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a4fd9e6583c47e9b997fff09dc32de1fc96f3b07;p=platform%2Fupstream%2Fwayland.git

protocol: wl_surface.frame needs wl_surface.commit

Clarify, when frame request takes effect.
Explain when to send/receive the callback.

Signed-off-by: Pekka Paalanen <ppaalanen@gmail.com>
---

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index e5c8c91..61bf268 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -705,10 +705,20 @@
 
     <request name="frame">
       <description summary="request repaint feedback">
-	Request notification when the next frame is displayed.  Useful
+	Request notification when the next frame is displayed. 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.
+
+	A server should avoid signalling the frame callbacks if the
+	surface is not visible in any way, e.g. the surface is off-screen,
+	or completely obscured by other opaque surfaces.
+
+	A client can request a frame callback even without an attach,
+	damage, or any other state changes. wl_surface.commit triggers a
+	repaint, so the callback event will arrive after the next output
+	refresh where the surface is visible.
       </description>
 
       <arg name="callback" type="new_id" interface="wl_callback"/>