gstreamer/docs/design/part-memory.txt

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.