latest modificationslatest_modifs

1 files changed, 140 insertions, 94 deletions

diff --git a/protocol/videosurface.xml b/protocol/videosurface.xml
index 4fa2b871..c88f73f8 100644
--- a/protocol/videosurface.xml
+++ b/protocol/videosurface.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<protocol name="buffer_queue">
+<protocol name="presentation_timing">
 
   <copyright>
     Copyright © 2012-2013 Collabora, Ltd.
@@ -26,135 +26,146 @@
     THIS SOFTWARE.
   </copyright>
 
-  <interface name="wl_buffer_queue_factory" version="1">
-    <description summary="timestamped-buffer surface factory">
-      The global factory interface exposing timestamped-buffer queuing composi-
+  <interface name="wl_presentation" version="1">
+    <description summary="buffer queues with presentation timing information/
+                          for surfaces">
+      The global factory interface exposing timestamped buffer queuing composi-
       ting capabilities.
 
       The aim of presentation timing is to support streaming video generally
       coming from videosink clients that typically need to queue video buffers
-      with presentation timestamps (target times) in order to accurately synch-
-      ronize video and audio streams. This global interface allows for the cre-
-      ation of buffer-queueing-capable surfaces.
+      with presentation timestamps in order to accurately synchronize video 
+      and audio streams.
+
+      This global interface allows for the creation of timestamped buffer 
+      queues for wl_surface objects.
     </description>
 
     <request name="destroy" type="destructor">
-      <description summary="unbind from the buffer_queue_compositor interface">
+      <description summary="unbind from the wl_presentation interface">
         Tell the server that the client will not be using this
         protocol object anymore. This does not affect any other
-        objects, wl_wayland_queue_surface objects included.
+        objects, wl_buffer_queue objects included.
       </description>
     </request>
 
-  <enum name="error">
-      <entry name="buffer-queue surface exists" value="0"
-             summary="the surface already has a buffer-queue surface object \
+    <enum name="error">
+      <entry name="buffer_queue_exists" value="0"
+             summary="the surface already has a buffer_queue object/
                       associated to it"/>
     </enum>
 
-    <request name="get_buffer_queue">
-      <description summary="promote a plain surface to a buffer_queue surface">
-        Create and attach a buffer-queue surface interface for the given sur-
-        face. This effectively turns a plain wl_surface into a specialized
-        wl_buffer_queue surface with synched video-streaming capabilities via
-        the use of buffer queues. If the given wl_surface already has a
-        wl_buffer_queue object associated to it, the buffer_queue_exists pro-
-        tocol error is raised.
+    <event name="clock_id", type="uint">
+      <description summary="clock ID to use">
+        Tell the client which clock ID is the compositor going to use for time-
+        stamps and presentation feedback.
+
+        Compositor sends that event once to a client right after it binds to 
+        the global interface.
+      </description>
+    </event>
+
+    <request name="create_queue">
+      <description summary="add buffer queueing capabilities to a wl_surface">
+        Create and attach a wl_buffer_queue interface to the given wl_sur-
+        face. This effectively adds buffer queueing and presentation timing
+        feedback capabilities to the surface through the use of buffer queues
+        and presentation callbacks.
+
+        If the given wl_surface already has a wl_buffer_queue object associated
+        to it, the buffer_queue_exists protocol error is raised.
 
-        Here, clockid is needed to negociate time domain with the compositor
+        Here, clock_id is needed to negociate time domain with the compositor
         as a common basis when specifing timestamps and presentation callbacks.
-        clockid is an implementation-specific integer representing the clock
+        clock_id is an implementation-specific integer representing the clock
         identification.
-
-        Since 'clock_id' is required at buffer_queue factory time, this means 
-        requested timestamps and fired presentation callbacks clock domain is
-        assumed to be of type clock_id for buffer_queue surface's whole life.
-        If time domain needs to change at some point, clients will have to 
-        destroy the previous interface and call get_buffer_queue again with a
-        different clock_id.  
       </description>
 
       <arg name="id" type="new_id" interface="wl_buffer_queue"
            summary="the new buffer_queue object id"/>
       <arg name="surface" type="object" interface="wl_surface"
            summary="the surface to be turned intio a buffer_queue surface"/>
-      <arg name="clock_id" type="uint" summary="clockid to be used for timestamps">
+      <arg name="clock_id" type="uint" summary="clock ID to be used for/
+                                                timestamps">
     </request>
   </interface>
 
   <interface name="wl_buffer_queue" version="1">
     <description summary="buffer queue interface to a wl_surface">
-      An additional interface to a wl_surface object, which has been promoted
-      to a buffer_queue surface. A buffer_queue surface is a special kinda of
-      surface that contains a buffer queue and exposes protocol that allows for
-      queuing timestamped wl_buffer objects into the buffer queue and retrie-
-      ving post-submission presentation callbacks after the frame hit the
-      screen.
-
-      Buffer_queue surfaces do not declare any state in addition to the ones
-      plain surfaces already use by default. Thus, once a plain wl_surface has
-      been created and promoted to a buffer_queue surface, buffer queuing hap-
-      pens through the "queue_buffer request". This means that queuing up
+      An additional interface to a wl_surface object to enable buffer queueing
+      capabilities. A buffer_queue-enabled surface contains a buffer queue and
+      exposes protocol that allows for queuing timestamped wl_buffer objects
+      into the queue and requesting presentation time feedback.
+
+      Buffer_queue-enabled surfaces do not declare any state in addition to the
+      ones wl_surfaces already use by default. Thus, once a plain wl_surface has
+      been turned into a buffer_queue-enabled surface, buffer queuing hap-
+      pens through the "queue" request. This means that queuing up
       buffers does *not* require any surface.attach nor surface.commit. More-
-      over, such an .attach or .commit will clear the buffer queue in order to
-      exclusively attach the newly provided buffer via .attach. Hence,
+      over, such an attach + commit sequence will clear the buffer queue in
+      order to exclusively consider the newly attached buffer. Hence,
       surface.attach and surface.commit should *not* be used when specifying
-      streaming buffer content of a buffer_queue surface.
-
-      At every repaint cycle, enqueued buffers with past-timestamps will be
-      considered, if any, and the most recent one will be presented. At that
-      point, buffers with older timestamps will be removed from the queue and
-      destroyed (a BUFFER_RELEASE event will be fired for every removed one).
-      Also, at every repaint cycle, future-timestamped buffers will be kept
-      untouched.
-
-      By default, fullscreen damage will be assumed, so there is no need to
-      commit any damage on the surface.
+      streaming surface content via buffer_queue. Also, queuing up a wl_buffer
+      makes it "reserved" in the compositor just like attach + commit does.
+
+      Besides, it is perfectly acceptable to commit (without attach) some
+      states on a buffer_queue-enabled surface, as it will not clear the buffer
+      queue nor interfere with any presentation timing mechanism brought by
+      the presentation_timing interfaces.
+
+      The compositor will attempt to repaint so that each queued buffer gets
+      presented at the requested target time. However, this may not always be
+      possible e.g. when a requested presentation time cannot be met accurately
+      or when the target time has completely passed already and been replaced by
+      another buffer by the time the compositor can repaint again. Therefore,     
+      At every repaint cycle, enqueued buffers with past-timestamps, if any,
+      will be considered and the compositor will present the most recent one
+      among them. At that point, buffers with older timestamps will be removed
+      from the queue and released (a BUFFER_RELEASE event will be fired for
+      every removed one). Also, at every repaint cycle, future-timestamped
+      buffers will be kept untouched in the queue.
+
+      When applying a buffer from the queue, the compositor implies full
+      surface damage. If the client manages to attach + damage + commit in the
+      meantime, then the damage is what it explicitely specified (and the
+      buffer_queue gets cleared)
     </description>
 
-    <event name="buffer_presented">
-      <description summary="buffer was displayed">
-        Tell the client that a buffer was presented at time T= tv_sec+tv_nsec. 
-        This event fires only if a 'presentation_time' request was priorly
-        made on the surface buffer_queue.
-      </description>
-      <arg name="buffer" type="object" interface="wl_buffer"
-           summary="the wl_buffer that was presented"/>
-      <arg name="tv_sec" type="uint"
-           summary="seconds value of the buffer presentation timestamp"/>
-      <arg name="tv_nsec" type="uint"
-           summary="nanoseconds value of the buffer presentation timestamp"/>
-    </event>
-
-    <event name="buffer_discarded">
-      <description summary="buffer was discarded without being displayed">
-        The buffer scheduled for presentation was not displayed and was
-        removed from the buffer_queue.
-      </description>
-      <arg name="buffer" type="object" interface="wl_buffer"
-           summary="the wl_buffer that was discarded."/>
-    </event>
-
     <request name="destroy" type="destructor">
       <description summary="remove buffer_queue interface">
-        The buffer_queue interface is removed from the wl_surface object
-        that was turned into a buffer_queue surface with the
-        wl_buffer_queue_factory.get_buffer_queue request.
+        The buffer_queue interface is removed from the buffer_queue-enabled
+        surface.
       </description>
     </request>
 
     <request name="queue">
       <description summary="enqueue a buffer into the surface's buffer queue">
         Queue a buffer along with its timestamp into the surface's internal
-        buffer queue. The timestamp can be posterior (future) or anterior
-        (past) to the current time.
+        buffer queue. This timestamp is the intended presentation time. While
+        clients generally want to queue posterior timestamps (future), queueing
+        up anterior timestamps (in the past) is allowed and does not raise any
+        protocol error.
 
         The speficied timestamp is two-part. tv_sec is the number of seconds
         and tv_nsec defines the number of nanoseconds spent after tv_sec.
+
+        Calling queue() will create a wl_presentation_time object that is ex-
+        clusively associated with the provided wl_buffer lifetime in the queue
+        at the moment the object was created. This means that presentation
+        feedback concerning this wl_buffer will be provided through wl_presen-
+        tation_time events, but only once. As soon as the buffer is presented
+        and removed from the queue by the compositor, it's internal link to
+        the wl_presentation_time object is broken and associated presentation
+        events will never be called again. So a client, right after having recei-
+        ved a wl_presentation_time event will generally destroy that object.
+        On the other hand, if a client does not want feedback, it may destroy
+        presentation_time object right after queuing a buffer.
       </description>
 
       <arg name="buffer" type="object" interface="wl_buffer"
            summary="the buffer to queue"/>
+      <arg name="id" type="new_id" interface="wl_presentation_time"
+           summary="the new presentation_time object id"/>
       <arg name="tv_sec" type="uint"
            summary="seconds value of the buffer target timestamp"/>
       <arg name="tv_nsec" type="uint"
@@ -163,23 +174,58 @@
 
     <request name="clear">
       <description summary="clear the surface's buffer queue">
-        Clear the surface's buffer_queue from all its buffers. None of the
-        removed buffers will be presented at given times and associated time-
-        stamps will cleared, but every removed buffer will still trigger a
-        BUFFER_RELEASE event so clients can recycle them appropriately.
+        Clear the surface's buffer queue. All buffers are removed from the
+        queue and released as appropriate. The requested presentation times are
+        discarded. The surface retains the contents it currently has, at the
+        time the compositor processes this request. The compositor may not
+        release the buffer(s) currently being displayed if it is needed for
+        repainting or scanout, as usual.
       </description>
     </request>
+  </interface>
 
-    <request name="presentation_time">
-      <description summary="request presentation event for next buffer">
-        Ask the compositor to initiate a presentation_time feedback when it
-        next presents a buffer (taken from buffer_queue) to display hardware.
+  <interface name="wl_presentation_time" version="1">
+    <description summary="presentation time feedback event">
+      The wl_presentation_time object encapsulates presentation time events
+      sent as feedback by the compositor to a client that previously queued
+      a wl_buffer. wl_presentation_time objects are created and returned when
+      a client enqueues a buffer through the wl_buffer_queue.queue() request.
+
+      Note that presentation time only tells client when the compositor presen-
+      ted the buffer to display hardware, not when the buffer was turned into
+      light (actually displayed on screen) by this hardware. As there could
+      be anything displaying those buffers, from very fast, low-latency
+      computer monitors to slow, hi-latency HDMI TV screens, it is the client's
+      responsibility to make sure it knows what display hardware is currently
+      connected and what is its latency.
+    </description>
 
-        This request concerns only the next buffer that will be presented
-        and thus has to be called once for each buffer for which presentation
-        feedback is required.
+    <request name="destroy" type="destructor">
+      <description summary="destroy presentation time request">
+        The presentation_time object is destroyed and none of its events will
+        ever be called again.
       </description>
     </request>
-  </interface>
 
+    <event name="presented">
+      <description summary="buffer was displayed">
+         Tell the client that a buffer was presented at time T=tv_sec+tv_nsec.
+         This event only pertains to the one wl_buffer that was passed in when
+         calling the buffer_queue.queue Thus, a particular presentation time
+         feeback event is always associated with specific wl_buffer lifetime in
+         the buffer queue.
+      </description>
+      <arg name="tv_sec" type="uint"
+           summary="seconds value of the buffer presentation timestamp"/>
+      <arg name="tv_nsec" type="uint"
+           summary="nanoseconds value of the buffer presentation timestamp"/>
+    </event>
+
+    <event name="discarded">
+      <description summary="buffer was not displayed">
+        The buffer scheduled for presentation was not displayed and was
+        removed from the buffer_queue.
+      </description>
+    </event>
+  </interface>
 </protocol>