pwg: add allocation docs

docs/pwg/advanced-allocation.xml

@@ -33,32 +33,182 @@
   <sect1 id="section-allocation-memory" xreflabel="GstMemory">
     <title>GstMemory</title>
     <para>
-      
+      <classname>GstMemory</classname> is an object that manages a region
+      of memory. The memory object points to a region of memory of
+      <quote>maxsize</quote>. The area in this memory starting at
+      <quote>offset</quote> and for <quote>size</quote> bytes is the
+      accessible region in the memory. the maxsize of the memory can
+      never be changed after the object is created, however, the offset
+      and size can be changed.
+    </para>
+    <para>
+      Data access to the memory wrapped by the <classname>GstMemory</classname>
+      object is always protected with a <function>gst_memory_map()</function>
+      and <function>gst_memory_unmap()</function> pair. An access mode
+      (read/write) must be given when mapping memory. The map
+      function returns a pointer to the valid memory region that can
+      then be accessed according to the requested access mode. 
+    </para>
+    <para>
+      <classname>GstMemory</classname> objects are created by a
+      <classname>GstAllocator</classname> object. To implement support
+      for a new kind of memory type, you must implement a new allocator
+      object.
     </para>
   </sect1>
 
   <sect1 id="section-allocation-buffer" xreflabel="GstBuffer">
     <title>GstBuffer</title>
     <para>
+      A <classname>GstBuffer</classname> is an lightweight object that
+      is passed from an upstream to a downstream element and contains
+      memory and metadata. It represents the multimedia content that
+      is pushed or pull downstream by elements.
+    </para>
+    <para>
+      The buffer contains one or more <classname>GstMemory</classname>
+      objects thet represent the data in the buffer.
+    </para>
+    <para>
+      Metadata in the buffer consists of:
+    </para>
+    <itemizedlist mark="opencircle">
+      <listitem>
+        <para>
+          DTS and PTS timestamps. These represent the decoding and
+          presentation timestamps of the buffer content and is used by
+          synchronizing elements to schedule buffers. Both these timestamps
+          can be GST_CLOCK_TIME_NONE when unknown/undefined.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The duration of the buffer contents. This duration can be
+          GST_CLOCK_TIME_NONE when unknown/undefined.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Media specific offsets and offset_end. For video this is the 
+          frame number in the stream and for audio the sample number. Other
+          definitions for other media exist. 
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Arbitrary structures via <classname>GstMeta</classname>, see below.
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      A buffer is writable when the refcount of the object is exactly 1, meaning
+      that only one object is holding a ref to the buffer. You can only
+      modify anything in the buffer when the buffer is writable. This means
+      that you need to call <function>gst_buffer_make_writable()</function>
+      before changing the timestamps, offsets, metadata or adding and
+      removing memory blocks.
     </para>
   </sect1>
 
   <sect1 id="section-allocation-meta" xreflabel="GstMeta">
     <title>GstMeta</title>
     <para>
+      With the <classname>GstMeta</classname> system you can add arbitrary
+      structures of on buffers. These structures describe extra properties
+      of the buffer such as cropping, stride, region of interest etc.
+    </para>
+    <para>
+      Metadata is also used to store, for example, the X image that is
+      backing up the memory of the buffer. This makes it easier for elements
+      to locate the X image from the buffer.
     </para>
   </sect1>
 
   <sect1 id="section-allocation-bufferpool" xreflabel="GstBufferPool">
     <title>GstBufferPool</title>
     <para>
+      The <classname>GstBufferPool</classname> object provides a convenient
+      base class for managing lists of reusable buffers. Essential for this
+      object is that all the buffers have the same properties such as size,
+      padding, metadata and alignment.
+    </para>
+    <para>
+      A bufferpool object can be configured to manage a minimum and maximum
+      amount of buffers of a specific size. A bufferpool can also be
+      configured to use a specific <classname>GstAllocator</classname> for
+      the memory of the buffers. There is support in the bufferpool to enable
+      bufferpool specific options, such as adding <classname>GstMeta</classname>
+      to the buffers in the pool or such as enabling specific padding on
+      the memory in the buffers.
     </para>
   </sect1>
 
   <sect1 id="section-allocation-query" xreflabel="GST_QUERY_ALLOCATION">
     <title>GST_QUERY_ALLOCATION</title>
     <para>
+      The ALLOCATION query is used to negotiate
+      <classname>GstMeta</classname>, <classname>GstBufferPool</classname>
+      and <classname>GstAllocator</classname> between elements. Negotiation
+      of the allocation strategy is always initiated and decided by a srcpad
+      after it has negotiated a format and before it decides to push buffers.
+      A sinkpad can suggest an allocation strategy but it is ultimately the
+      source pad that will decide based on the suggestions of the downstream
+      sink pad.
     </para>
+    <para>
+      The source pad will do a GST_QUERY_ALLOCATION with the negotiated caps
+      as a parameter. This is needed so that the downstream element knows
+      what media type is being handled. A downstream sink pad can answer the
+      allocation query with the following results:
+    </para>
+    <itemizedlist mark="opencircle">
+      <listitem>
+        <para>
+          An array of possible <classname>GstBufferPool</classname> suggestions
+          with suggested size, minimum and maximum amount of buffers.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          An array of GstAllocator objects along with suggested allocation
+          parameters such as flags, prefix, alignment and padding. These
+          allocators can also be configured in a bufferpool when this is
+          supported by the bufferpool.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          An array of supported <classname>GstMeta</classname> implementations
+          along with metadata specific parameters.
+          It is important that the upstream element knows what kind of
+          metadata is supported downstream before it places that metadata
+          on buffers.
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      When the GST_QUERY_ALLOCATION returns, the source pad will select
+      from the available bufferpools, allocators and metadata how it will
+      allocate buffers.
+    </para>
+    <para>
+      In many baseclasses you will see the following virtual methods for
+      influencing the allocation strategy:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <function>propose_allocation ()</function> should suggest
+          allocation parameters for the upstream element.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <function>decide_allocation ()</function> should decide the
+          allocation parameters from the suggestions received from
+          downstream.
+        </para>
+      </listitem>
+    </itemizedlist>
   </sect1>
-
 </chapter>