refact: notify buffer format in context

Source buffer format can be reused in context.

Author: asterwyx

xml/treeland-capture-unstable-v1.xml

@@ -25,8 +25,9 @@
 
     <request name="start">
       <description summary="start session">
-          Start session and keeps sending frame.
+          Start session and keeps sending frame with the given buffer.
       </description>
+      <arg name="buffer" type="object" interface="wl_buffer" allow-null=true summary="buffer to receive frame data, null for export dmabuf"/>
     </request>
 
     <request name="frame_done">
@@ -41,9 +42,15 @@
     </request>
 
     <event name="frame">
+        <description summary="notify the client a new frame">
+        Notify the client that a new frame is coming, client should copy or import dmabuf.
+        </description>
+    </event>
+
+    <event name="dmabuf_frame">
       <description summary="supply the client with information about the frame">
-          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.
+          Main event supplying the client with information about the dmabuf frame.
+          If the capture didn't fail, this event is directly after the frame event.
           When mask is provided, x and y should be offset relative to mask surface origin. Otherwise offset_x and offset_y should always
           be zero.
       </description>
@@ -59,7 +66,7 @@
       <arg name="num_objects" type="uint"/>
     </event>
 
-    <event name="object">
+    <event name="dmabuf_object">
       <description summary="supply the client with object fd">
       </description>
       <arg name="index" type="uint"/>
@@ -87,7 +94,6 @@
       </description>
       <arg name="reason" type="uint" enum="treeland_capture_session_v1.cancel_reason"/>
     </event>
-
   </interface>
 
   <interface name="treeland_capture_frame_v1" version="1">
@@ -100,22 +106,6 @@
       <entry name="y_inverted" value="0x1" summary="contents are y-inverted"/>
     </enum>
 
-    <event name="buffer">
-      <description summary="inform client to prepare buffer">
-        Inform client to prepare buffer.
-      </description>
-      <arg name="format" type="uint" enum="wl_shm.format"/>
-      <arg name="width" type="uint"/>
-      <arg name="height" type="uint"/>
-      <arg name="stride" type="uint"/>
-    </event>
-
-    <event name="buffer_done">
-      <description summary="all buffer formats have done">
-        Inform client that all buffer formats supported are emitted.
-      </description>
-    </event>
-
     <request name="copy">
       <description summary="copy capture contents">
         Copy capture contents to provided buffer
@@ -190,6 +180,41 @@
       <arg name="source_type" type="uint" enum="source_type" summary="final capture source type"/>
     </event>
 
+    <event name="source_shm_buffer">
+        <description summary="notify client the supported shm buffer format">
+        This event notify the client what kind of shm buffer is supported. It may be sent several times after "source_ready".
+        If client receives dmabuf notification, it should use dmabuf instead.
+        </description>
+        <arg name="format" type="uint" enum="wl_shm.format" summary="shm buffer format"/>
+        <arg name="width" type="uint" summary="shm buffer width"/>
+        <arg name="height" type="uint" summary="shm buffer height"/>
+        <arg name="stride" type="uint" summary="shm buffer stride"/>
+    </event>
+
+    <event name="source_dmabuf">
+        <description summary="notify client the supported dmabuf format">
+        This event notify the client what kind of dmabuf is supported. It may be sent several times after "source_ready".
+        If client receives the notification, it should use dmabuf instead of shm buffer.
+        </description>
+        <arg name="format" type="uint" summary="fourcc pixel format"/>
+        <arg name="width" type="uint" summary="dmabuf width"/>
+        <arg name="height" type="uint" summary="dmabuf height"/>
+    </event>
+
+    <event name="source_export_dmabuf">
+        <description summary="notify client that compositor supports export dmabuf">
+        This event notify the client that compositor supports export dmabuf. It should be sent just once
+        after "source_ready". Client should prefer export dmabuf over dmabuf or shm buffer.
+        </description>
+    </event>
+
+    <event name="source_buffer_done">
+        <description summary="notify client that all supported buffer formats are sent">
+        This event indicates an end of source_shm_buffer, source_dmabuf and source_export_dmabuf event
+        sequence.
+        </description>
+    </event>
+
     <event name="source_failed">
         <description summary="notify client that source selection is failed">
           There could a lot of reasons but the most common one is that selector is busy