docs: more docs fixes

Fix allocator design doc
Add beginning of allocation chapter in the pwg

diff --git a/docs/design/part-bufferpool.txt b/docs/design/part-bufferpool.txt
index 4999a2a..d337421 100644 (file)
--- a/docs/design/part-bufferpool.txt
+++ b/docs/design/part-bufferpool.txt
@@ -74,7 +74,7 @@ Negotiation
  Buffers are then allocated by the srcpad from the negotiated pool and pushed to
  the peer pad as usual.
 
- The allocation query can also return an allocator name when the buffers are of
+ The allocation query can also return an allocator object when the buffers are of
  different sizes and can't be allocated from a pool.
 
 

diff --git a/docs/design/part-memory.txt b/docs/design/part-memory.txt
index ea44cf9..681ac04 100644 (file)
--- a/docs/design/part-memory.txt
+++ b/docs/design/part-memory.txt
@@ -44,23 +44,34 @@ Memory layout
 Allocators
 ~~~~~~~~~~
 
- GstMemory objects are created by allocators. Allocators are created from
- a GstMemoryInfo structure.
+ GstMemory objects are created by allocators. Allocators are a subclass
+ of GstObject and can be subclassed to make custom allocators.
 
-  struct _GstMemoryInfo {
-    const gchar              *mem_type;
+  struct _GstAllocator {
+    GstObject                 object;
 
-    GstAllocatorAllocFunction alloc;
+    const gchar              *mem_type;
 
     GstMemoryMapFunction      mem_map;
     GstMemoryUnmapFunction    mem_unmap;
-    GstMemoryFreeFunction     mem_free;
 
     GstMemoryCopyFunction     mem_copy;
     GstMemoryShareFunction    mem_share;
     GstMemoryIsSpanFunction   mem_is_span;
   };
 
+ The allocator class has 2 virtual methods. One to create a GstMemory,
+ another to free it again.
+
+  struct _GstAllocatorClass {
+    GstObjectClass object_class;
+
+    GstMemory *  (*alloc)      (GstAllocator *allocator, gsize size,
+                                GstAllocationParams *params);
+    void         (*free)       (GstAllocator *allocator, GstMemory *memory);
+  };
+
+
  Allocators are refcounted. It is also possible to register the allocator to the
  GStreamer system. This way, the allocator can be retrieved by name.
 
@@ -76,6 +87,11 @@ Allocators
  The GstMemory object is a refcounted object that must be freed with
  gst_memory_unref ().
 
+ The GstMemory keeps a ref to the allocator that allocated it. Inside the
+ allocator are the most common GstMemory operations listed. Custom
+ GstAllocator implementations must implement the various operations on
+ the memory they allocate.
+
  It is also possible to create a new GstMemory object that wraps existing
  memory with:
   

diff --git a/docs/pwg/advanced-allocation.xml b/docs/pwg/advanced-allocation.xml
new file mode 100644 (file)
index 0000000..e571351
--- /dev/null
+++ b/docs/pwg/advanced-allocation.xml
@@ -0,0 +1,64 @@
+<chapter id="chapter-allocation" xreflabel="Memory allocation">
+  <title>Memory allocation</title>
+  <para>
+    Memory allocation and management is a very important topic in
+    multimedia. High definition video uses many magabytes to store
+    one single frame of video. It is important to reuse the memory
+    when possible instead of constantly allocating and freeing
+    the memory.
+  </para>
+  <para>
+    Multimedia systems usually use special purpose chips, such as
+    DSPs or GPUs to perform the heavy lifting (especially for video).
+    These special purpose chips have usually strict requirements
+    for the memory that they can operate on and how the memory
+    is accessed.
+  </para>
+  <para>
+    This chapter talks about the memory management features that
+    &GStreamer; plugins can use. We will first talk about the
+    lowlevel <classname>GstMemory</classname> object that manages
+    access to a piece of memory. We then continue with
+    <classname>GstBuffer</classname> that is used to exchange data
+    between plugins (and the application) and that uses
+    <classname>GstMemory</classname>. We talk about
+    <classname>GstMeta</classname> that can be placed on buffers to
+    give extra info about the buffer and its memory.
+    For efficiently managing buffers of the same size, we take a
+    look at <classname>GstBufferPool</classname>. To conclude this
+    chapter we take a look at the GST_QUERY_ALLOCATION query that
+    is used to negotiate memory management options between elements.
+  </para>
+
+  <sect1 id="section-allocation-memory" xreflabel="GstMemory">
+    <title>GstMemory</title>
+    <para>
+      
+    </para>
+  </sect1>
+
+  <sect1 id="section-allocation-buffer" xreflabel="GstBuffer">
+    <title>GstBuffer</title>
+    <para>
+    </para>
+  </sect1>
+
+  <sect1 id="section-allocation-meta" xreflabel="GstMeta">
+    <title>GstMeta</title>
+    <para>
+    </para>
+  </sect1>
+
+  <sect1 id="section-allocation-bufferpool" xreflabel="GstBufferPool">
+    <title>GstBufferPool</title>
+    <para>
+    </para>
+  </sect1>
+
+  <sect1 id="section-allocation-query" xreflabel="GST_QUERY_ALLOCATION">
+    <title>GST_QUERY_ALLOCATION</title>
+    <para>
+    </para>
+  </sect1>
+
+</chapter>

diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml
index 7610d28..6d91f26 100644 (file)
--- a/docs/pwg/pwg.xml
+++ b/docs/pwg/pwg.xml
@@ -25,6 +25,7 @@
 
 <!-- Part 3: Advanced Filter Concepts -->
 <!ENTITY ADVANCED_NEGOTIATION SYSTEM "advanced-negotiation.xml">
+<!ENTITY ADVANCED_ALLOCATION  SYSTEM "advanced-allocation.xml">
 <!ENTITY ADVANCED_SCHEDULING  SYSTEM "advanced-scheduling.xml">
 <!ENTITY ADVANCED_TYPES       SYSTEM "advanced-types.xml">
 <!ENTITY ADVANCED_REQUEST     SYSTEM "advanced-request.xml">
@@ -140,6 +141,7 @@
     </partintro>
 
     &ADVANCED_NEGOTIATION;
+    &ADVANCED_ALLOCATION;
     &ADVANCED_SCHEDULING;
     &ADVANCED_TYPES;
     &ADVANCED_REQUEST;