From 3f0d40b4171c06c6031be3130efd0e0615c3e6c9 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Mon, 1 Oct 2012 13:28:54 +0200 Subject: [PATCH] docs: more docs fixes Fix allocator design doc Add beginning of allocation chapter in the pwg --- docs/design/part-bufferpool.txt | 2 +- docs/design/part-memory.txt | 28 ++++++++++++++---- docs/pwg/advanced-allocation.xml | 64 ++++++++++++++++++++++++++++++++++++++++ docs/pwg/pwg.xml | 2 ++ 4 files changed, 89 insertions(+), 7 deletions(-) create mode 100644 docs/pwg/advanced-allocation.xml diff --git a/docs/design/part-bufferpool.txt b/docs/design/part-bufferpool.txt index 4999a2a..d337421 100644 --- 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 --- 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 index 0000000..e571351 --- /dev/null +++ b/docs/pwg/advanced-allocation.xml @@ -0,0 +1,64 @@ + + Memory allocation + + 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. + + + 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. + + + This chapter talks about the memory management features that + &GStreamer; plugins can use. We will first talk about the + lowlevel GstMemory object that manages + access to a piece of memory. We then continue with + GstBuffer that is used to exchange data + between plugins (and the application) and that uses + GstMemory. We talk about + GstMeta 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 GstBufferPool. To conclude this + chapter we take a look at the GST_QUERY_ALLOCATION query that + is used to negotiate memory management options between elements. + + + + GstMemory + + + + + + + GstBuffer + + + + + + GstMeta + + + + + + GstBufferPool + + + + + + GST_QUERY_ALLOCATION + + + + + diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml index 7610d28..6d91f26 100644 --- a/docs/pwg/pwg.xml +++ b/docs/pwg/pwg.xml @@ -25,6 +25,7 @@ + @@ -140,6 +141,7 @@ &ADVANCED_NEGOTIATION; + &ADVANCED_ALLOCATION; &ADVANCED_SCHEDULING; &ADVANCED_TYPES; &ADVANCED_REQUEST; -- 2.7.4