docs: more docs fixes

Fix allocator design doc
Add beginning of allocation chapter in the pwg
This commit is contained in:
Wim Taymans 2012-10-01 13:28:54 +02:00
parent 153818f09f
commit 3f0d40b417
4 changed files with 89 additions and 7 deletions

View file

@ -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.

View file

@ -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 _GstAllocator {
GstObject object;
struct _GstMemoryInfo {
const gchar *mem_type;
GstAllocatorAllocFunction alloc;
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:

View file

@ -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>

View file

@ -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;