mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-07 23:25:52 +00:00
b84fff07ea
Require the memory implementations to implement a share operation. This allows us to remove the fallback share implementation which uses a different allocator implementation and complicates things too much. Update design doc a bit.
141 lines
4.4 KiB
Plaintext
141 lines
4.4 KiB
Plaintext
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.
|
|
|
|
|