gstreamer/docs/design/part-memory.txt

141 lines
4.4 KiB
Text
Raw Normal View History

GstMemory
---------
This document describes the design of the memory objects.
GstMemory objects are usually added to GstBuffer objects and contain the
multimedia data passed around in the pipeline.
Requirements
~~~~~~~~~~~~
- It must be possible to have different memory allocators
- It must be possible to efficiently share memory objects, copy, span
and trim.
Allocators
~~~~~~~~~~
GstMemory objects are created by allocators. Allocators are registered to the
memory system with a set of methods contained in a GstMemoryInfo structure.
struct _GstMemoryInfo {
GstMemoryAllocFunction alloc;
GstMemoryGetSizesFunction get_sizes;
GstMemoryResizeFunction resize;
GstMemoryMapFunction map;
GstMemoryUnmapFunction unmap;
GstMemoryFreeFunction free;
GstMemoryCopyFunction copy;
GstMemoryShareFunction share;
GstMemoryIsSpanFunction is_span;
gpointer user_data;
};
After an allocator is registerd, new GstMemory can be created with
GstMemory * gst_memory_allocator_alloc (const GstMemoryAllocator * allocator,
gsize maxsize, gsize align);
The GstMemory object is a refcounted object that must be freed with
gst_memory_unref ().
It is also possible to create a new GstMemory object that wraps existing
memory with:
GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
GFreeFunc free_func, gsize maxsize,
gsize offset, gsize size);
Lifecycle
~~~~~~~~~
GstMemory objects are refcounted. When the GstMemory object is first created, it
has a refcount of 1.
Each variable holding a reference to the GstMemory object is responsible for
updating the refcount.
The refcount determines the writability of the object. If the refcount > 1, it is
by definition used by multipled objects and thus cannot be safely written to.
When the refcount reaches 0, and thus no objects hold a reference anymore, we
can free the memory. The GstMemoryFreeFunction of the allocator will be called
to cleanup the memory.
Memory layout
~~~~~~~~~~~~~
GstMemory manages a memory region. The accesible part of the managed region is
defined by an offset relative to the start of the region and a size. This
means that the managed region can be larger than what is visible to the user of
GstMemory API.
Schematically, GstMemory has a pointer to a memory region of _maxsize_. The area
starting from _offset_ and _size_ is accessible.
memory
GstMemory ->*----------------------------------------------------*
^----------------------------------------------------^
maxsize
^--------------------------------------^
offset size
The current properties of the accessible memory can be retrieved with:
gsize gst_memory_get_sizes (GstMemory *mem, gsize *maxsize);
The offset and size can be changed with:
void gst_memory_resize (GstMemory *mem, gsize offset, gsize size);
The visible memory region can currently only be made smaller.
The memory object is always readable. The memory block is writable when:
- the refcount is exactly 1
- the memory object has no parent, or if it has a parent, the parent is
writable.
- the memory object is not marked as READONLY.
Data Access
~~~~~~~~~~~
Access to the memory region is always controlled with a map and unmap method
call. This allows the implementation to monitor the access patterns or set up
the required memory mappings when needed.
Mapping a memory region requires the caller to specify the access method: READ
and/or WRITE. For write access, the GstMemory object must be writable.
After the data has been accessed in the object, the unmap call must be
performed. The call will update the new memory size with the specified size.
Copy
~~~~
A GstMemory copy can be made with the gst_memory_copy() call. Normally,
allocators will implement a custom version of this function to make a copy of
the same kind of memory as the original one.
This is what the fallback version of the copy function will do, albeit slower
than what as custom implementation could do.
The copy operation is only required to copy the visible range of the memory
block.
Share
~~~~~
A memory region can be shared between GstMemory object with the
gst_memory_share() operation.