mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-14 13:21:28 +00:00
docs: more docs fixes
Fix allocator design doc Add beginning of allocation chapter in the pwg
This commit is contained in:
parent
153818f09f
commit
3f0d40b417
4 changed files with 89 additions and 7 deletions
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
||||
|
|
64
docs/pwg/advanced-allocation.xml
Normal file
64
docs/pwg/advanced-allocation.xml
Normal 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>
|
|
@ -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;
|
||||
|
|
Loading…
Reference in a new issue