docs/design/part-memory.txt

   1 GstMemory
   2 ---------
   3
   4 This document describes the design of the memory objects.
   5
   6 GstMemory objects are usually added to GstBuffer objects and contain the
   7 multimedia data passed around in the pipeline.
   8
   9 Requirements
  10 ~~~~~~~~~~~~
  11
  12  - It must be possible to have different memory allocators
  13  - It must be possible to efficiently share memory objects, copy, span
  14    and trim.
  15
  16
  17 Allocators
  18 ~~~~~~~~~~
  19
  20  GstMemory objects are created by allocators. Allocators are created from
  21  a GstMemoryInfo structure.
  22
  23   struct _GstMemoryInfo {
  24     const gchar              *mem_type;
  25
  26     GstAllocatorAllocFunction alloc;
  27
  28     GstMemoryMapFunction      mem_map;
  29     GstMemoryUnmapFunction    mem_unmap;
  30     GstMemoryFreeFunction     mem_free;
  31
  32     GstMemoryCopyFunction     mem_copy;
  33     GstMemoryShareFunction    mem_share;
  34     GstMemoryIsSpanFunction   mem_is_span;
  35   };
  36
  37  Allocators are refcounted. It is also possible to register the allocator to the
  38  GStreamer system. This way, the allocator can be retrieved by name.
  39
  40  After an allocator is created, new GstMemory can be created with
  41
  42    GstMemory * gst_allocator_alloc (const GstAllocator * allocator,
  43                                     gsize maxsize, gsize align);
  44
  45  The GstMemory object is a refcounted object that must be freed with
  46  gst_memory_unref ().
  47
  48  It is also possible to create a new GstMemory object that wraps existing
  49  memory with:
  50
  51    GstMemory * gst_memory_new_wrapped  (GstMemoryFlags flags,
  52                                         gpointer data, gsize maxsize,
  53                                         gsize offset, gsize size,
  54                                         gpointer user_data,
  55                                         GDestroyNotify notify);
  56
  57 Lifecycle
  58 ~~~~~~~~~
  59
  60 GstMemory objects are refcounted. When the GstMemory object is first created, it
  61 has a refcount of 1.
  62
  63 Each variable holding a reference to the GstMemory object is responsible for
  64 updating the refcount.
  65
  66 When the refcount reaches 0, and thus no objects hold a reference anymore, we
  67 can free the memory. The GstMemoryFreeFunction of the allocator will be called
  68 to cleanup the memory.
  69
  70
  71 Memory layout
  72 ~~~~~~~~~~~~~
  73
  74  GstMemory manages a memory region. The accesible part of the managed region is
  75  defined by an offset relative to the start of the region and a size. This
  76  means that the managed region can be larger than what is visible to the user of
  77  GstMemory API.
  78
  79  Schematically, GstMemory has a pointer to a memory region of _maxsize_. The area
  80  starting from _offset_ and _size_ is accessible.
  81
  82                memory
  83     GstMemory  ->*----------------------------------------------------*
  84                  ^----------------------------------------------------^
  85                                    maxsize
  86                       ^--------------------------------------^
  87                      offset            size
  88
  89  The current properties of the accessible memory can be retrieved with:
  90
  91    gsize       gst_memory_get_sizes  (GstMemory *mem, gsize *offset, gsize *maxsize);
  92
  93  The offset and size can be changed with:
  94
  95    void        gst_memory_resize     (GstMemory *mem, gssize offset, gsize size);
  96
  97
  98 Data Access
  99 ~~~~~~~~~~~
 100
 101  Access to the memory region is always controlled with a map and unmap method
 102  call. This allows the implementation to monitor the access patterns or set up
 103  the required memory mappings when needed.
 104
 105  Mapping a memory region requires the caller to specify the access method: READ
 106  and/or WRITE.
 107
 108  After the data has been accessed in the object, the unmap call must be
 109  performed.
 110
 111  It is allowed to map multiple times with different access modes. for each of
 112  the map calls, an corresponding unmap call needs to be made. WRITE-only memory
 113  cannot be mapped in READ mode and READ-only memory cannot be mapped in WRITE
 114  mode.
 115
 116  The memory pointer returned from the map call is guaranteed to remain valid in
 117  the requested mapping mode until the corresponding unmap call is performed on
 118  the pointer.
 119
 120  When multiple map operations are nested and return the same pointer, the pointer
 121  is valid until the last unmap call is done.
 122
 123  When the final reference on a memory object is dropped, all outstanding
 124  mappings should have been unmapped.
 125
 126  Resizing a GstMemory does not influence any current mappings an any way.
 127
 128 Copy
 129 ~~~~
 130
 131  A GstMemory copy can be made with the gst_memory_copy() call. Normally,
 132  allocators will implement a custom version of this function to make a copy of
 133  the same kind of memory as the original one.
 134
 135  This is what the fallback version of the copy function will do, albeit slower
 136  than what as custom implementation could do.
 137
 138  The copy operation is only required to copy the visible range of the memory
 139  block.
 140
 141
 142 Share
 143 ~~~~~
 144
 145  A memory region can be shared between GstMemory object with the
 146  gst_memory_share() operation.
 147
 148