Update example and protocol

1 files changed, 91 insertions, 89 deletions

diff --git a/protocol/wlr-export-dmabuf-unstable-v1.xml b/protocol/wlr-export-dmabuf-unstable-v1.xml
index 760345a7..751f7efb 100644
--- a/protocol/wlr-export-dmabuf-unstable-v1.xml
+++ b/protocol/wlr-export-dmabuf-unstable-v1.xml
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <protocol name="wlr_export_dmabuf_unstable_v1">
-
   <copyright>
     Copyright © 2018 Rostislav Pehlivanov
 
@@ -25,29 +24,56 @@
   </copyright>
 
   <description summary="a protocol for low overhead screen content capturing">
-    An interface to capture surfaces in an efficient way.
-    Overall usage:
-
-    1.) client registers with zwlr_screencontent_manager_v1
-    2.) server sends client info about surfaces via "receive_surface_info"
-    3.) client subscribes to capture a surface via the "capture" requests
-    4.) server sends client events via the "zwlr_screencontent_frame" interface
-    5.) client finishes and informs server via the "frame_destroy" event
-    6.) client optionally resubscribes via repeating steps 3.) through 5.)
+    An interface to capture surfaces in an efficient way by exporting DMA-BUFs.
+
+    Warning! The protocol described in this file is experimental and
+    backward incompatible changes may be made. Backward compatible changes
+    may be added together with the corresponding interface version bump.
+    Backward incompatible changes are done by bumping the version number in
+    the protocol and interface names and resetting the interface version.
+    Once the protocol is to be declared stable, the 'z' prefix and the
+    version number in the protocol and interface names are removed and the
+    interface version number is reset.
   </description>
 
+  <interface name="zwlr_export_dmabuf_manager_v1" version="1">
+    <description summary="manager to inform clients and begin capturing">
+      This object is a manager with which to start capturing from sources.
+    </description>
+
+    <request name="capture_output">
+      <description summary="capture a frame from an output">
+        Capture the next frame of a an entire output.
+      </description>
+      <arg name="frame" type="new_id" interface="zwlr_export_dmabuf_frame_v1"/>
+      <arg name="overlay_cursor" type="int"
+           summary="include custom client hardware cursor on top of the frame"/>
+      <arg name="output" type="object" interface="wl_output"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        All objects created by the manager will still remain valid, until their
+        appropriate destroy request has been called.
+      </description>
+    </request>
+  </interface>
+
   <interface name="zwlr_export_dmabuf_frame_v1" version="1">
-    <description summary="a frame ready for readout">
-      This object represents a frame which is ready to have its resources
-      fetched and used.
-
-      The receive callback shall be called first, followed by the "object"
-      callback once per dmabuf object or the "plane" callback, once per dmabuf
-      plane. The "ready" event is called last to indicate that all the data has
-      been made available for readout, as well as the time at which presentation
-      happened at. The ownership of the frame is passed to the client, who's
-      responsible for destroying it via the "destroy" event once finished and
-      by calling close() on the file descriptors received.
+    <description summary="a DMA-BUF frame">
+      This object represents a single DMA-BUF frame.
+
+      If the capture is successful, the compositor will first send a "frame"
+      event, followed by one or several "object". When the frame is available
+      for readout, the "ready" event is sent.
+
+      If the capture failed, the "cancel" event is sent. This can happen anytime
+      before the "ready" event.
+
+      Once either a "ready" or a "cancel" event is received, the client should
+      destroy the frame. Once an "object" event is received, the client is
+      responsible for closing the associated file descriptor.
+
       All frames are read-only and may not be written into or altered.
     </description>
 
@@ -55,25 +81,23 @@
       <description summary="frame flags">
         Special flags that should be respected by the client.
       </description>
-      <entry name="transient" value="0x1" since="1"
+      <entry name="transient" value="0x1"
              summary="clients should copy frame before processing"/>
     </enum>
 
     <event name="frame">
-      <description summary="main callback">
-        Main callback supplying the client with information about the frame,
-        as well as an object to serve as context for destruction. Always called
-        first before any other events.
-
-        The "transform" argument describes the orientation needed to be applied
-        to correctly orient the buffer. For example, a buffer rotated by 90
-        degrees will have a value of "3" here, corresponding to the need to
-        apply a 270 degree transpose to correctly present the buffer.
+      <description summary="a frame description">
+        Main event supplying the client with information about the frame. If the
+        capture didn't fail, this event is always emitted first before any other
+        events.
+
+        This event is followed by a number of "object" as specified by the
+        "num_objects" argument.
       </description>
       <arg name="width" type="uint"
-           summary="frame width, scaling factor included"/>
+           summary="frame width in pixels"/>
       <arg name="height" type="uint"
-           summary="frame height, scaling factor included"/>
+           summary="frame height in pixels"/>
       <arg name="offset_x" type="uint"
            summary="crop offset for the x axis"/>
       <arg name="offset_y" type="uint"
@@ -91,13 +115,15 @@
            summary="drm format modifier, low"/>
       <arg name="num_objects" type="uint"
            summary="indicates how many objects (FDs) the frame has (max 4)"/>
-      <arg name="num_planes" type="uint"
-           summary="indicates how many planes the frame has (max 4)"/>
     </event>
+
     <event name="object">
-      <description summary="object receiving callback">
-        Callback which serves to supply the client with the file descriptors
+      <description summary="an object description">
+        Event which serves to supply the client with the file descriptors
         containing the data for each object.
+
+        After receiving this event, the client must always close the file
+        descriptor as soon as they're done with it and even if the frame fails.
       </description>
       <arg name="index" type="uint"
            summary="index of the current object"/>
@@ -105,31 +131,28 @@
            summary="fd of the current object"/>
       <arg name="size" type="uint"
            summary="size in bytes for the current object"/>
-    </event>
-    <event name="plane">
-      <description summary="plane info receiving callback">
-        Callback which supplies the client with plane information for each
-        plane.
-      </description>
-      <arg name="index" type="uint"
-           summary="index of the current plane"/>
-      <arg name="object_index" type="uint"
-           summary="index of the object the plane applies to"/>
       <arg name="offset" type="uint"
            summary="starting point for the data in the object's fd"/>
       <arg name="stride" type="uint"
            summary="line size in bytes"/>
+      <arg name="plane_index" type="uint"
+           summary="index of the the plane the data in the object applies to"/>
     </event>
+
     <event name="ready">
       <description summary="indicates frame is available for reading">
-        Called as soon as the frame is presented, indicating it is available
-        for reading.
+        This event is sent as soon as the frame is presented, indicating it is
+        available for reading. This event includes the time at which
+        presentation happened at.
+
         The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
         each component being an unsigned 32-bit value. Whole seconds are in
         tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo,
         and the additional fractional part in tv_nsec as nanoseconds. Hence,
-        for valid timestamps tv_nsec must be in [0, 999999999].
-        The seconds part may have an arbitrary offset at start.
+        for valid timestamps tv_nsec must be in [0, 999999999]. The seconds part
+        may have an arbitrary offset at start.
+
+        After receiving this event, the client should destroy this object.
       </description>
       <arg name="tv_sec_hi" type="uint"
            summary="high 32 bits of the seconds part of the timestamp"/>
@@ -143,22 +166,25 @@
       <description summary="cancel reason">
         Indicates reason for cancelling the frame.
       </description>
-      <entry name="temporary" value="0" since="1"
+      <entry name="temporary" value="0"
              summary="temporary error, source will produce more frames"/>
-      <entry name="pernament" value="1" since="1"
+      <entry name="permanent" value="1"
              summary="fatal error, source will not produce frames"/>
-      <entry name="resizing" value="2" since="1"
-             summary="temporary error, source will produce frames"/>
+      <entry name="resizing" value="2"
+             summary="temporary error, source will produce more frames"/>
     </enum>
 
     <event name="cancel">
       <description summary="indicates the frame is no longer valid">
-        If the frame is no longer valid after the "frame" event has been called,
-        this callback will be used to inform the client to scrap the frame.
-        Source is still valid for as long as the subscription function does not
-        return NULL.
-        This may get called if for instance the surface is in the process of
-        resizing.
+        If the capture failed or if the frame is no longer valid after the
+        "frame" event has been emitted, this event will be used to inform the
+        client to scrap the frame.
+
+        If the failure is temporary, the client may capture again the same
+        source. If the failure is permanent, any further attempts to capture the
+        same source will fail again.
+
+        After receiving this event, the client should destroy this object.
       </description>
       <arg name="reason" type="uint" enum="cancel_reason"
            summary="indicates a reason for cancelling this frame capture"/>
@@ -166,35 +192,11 @@
 
     <request name="destroy" type="destructor">
       <description summary="delete this object, used or not">
-        Unreferences the frame, allowing it to be reused. Must be called as soon
-        as its no longer used.
-        Can be called at any time by the client after the "frame" event, after
-        which the compositor will not call any other events unless the client
-        resubscribes to capture more. The client will still have to close any
-        FDs it has been given.
-      </description>
-    </request>
-  </interface>
+        Unreferences the frame. This request must be called as soon as its no
+        longer used.
 
-  <interface name="zwlr_export_dmabuf_manager_v1" version="1">
-    <description summary="manager to inform clients and begin capturing">
-      This object is a manager with which to start capturing from sources.
-    </description>
-
-    <request name="capture_output">
-      <description summary="subscribe to start capturing">
-        Request to start capturing from an entire wl_output.
-      </description>
-      <arg name="frame" type="new_id"
-           interface="zwlr_export_dmabuf_frame_v1"/>
-      <arg name="overlay_cursor" type="int"
-           summary="include custom client hardware cursor on top of the frame"/>
-      <arg name="output" type="object" interface="wl_output"/>
-    </request>
-    <request name="destroy" type="destructor">
-      <description summary="destroy the manager">
-        All objects created by the manager will still remain valid, until their
-        appropriate destroy request has been called.
+        It can be called at any time by the client. The client will still have
+        to close any FDs it has been given.
       </description>
     </request>
   </interface>