Chapter 15. Memory allocation

Table of Contents

GstMemory
GstAllocator
GstMemory API example
Implementing a GstAllocator
GstBuffer
GstBuffer writability
GstBuffer API examples
GstMeta
GstMeta API example
Implementing new GstMeta
GstBufferPool
GstBufferPool API example
Implementing a new GstBufferPool
GST_QUERY_ALLOCATION
ALLOCATION query example
The ALLOCATION query in base classes

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

GstMemory is an object that manages a region of memory. The memory object points to a region of memory of maxsize. The area in this memory starting at offset and for size bytes is the accessible region in the memory. the maxsize of the memory can never be changed after the object is created, however, the offset and size can be changed.

GstAllocator

GstMemory objects are created by a GstAllocator object. Most allocators implement the default gst_allocator_alloc() method but some allocator might implement a different method, for example when additional parameters are needed to allocate the specific memory.

Different allocators exist for, for example, system memory, shared memory and memory backed by a DMAbuf file descriptor. To implement support for a new kind of memory type, you must implement a new allocator object as shown below.

GstMemory API example

Data access to the memory wrapped by the GstMemory object is always protected with a gst_memory_map() and gst_memory_unmap() pair. An access mode (read/write) must be given when mapping memory. The map function returns a pointer to the valid memory region that can then be accessed according to the requested access mode.

Below is an example of making a GstMemory object and using the gst_memory_map() to access the memory region.


[...]

  GstMemory *mem;
  GstMapInfo info;
  gint i;

  /* allocate 100 bytes */
  mem = gst_allocator_alloc (NULL, 100, NULL);

  /* get access to the memory in write mode */
  gst_memory_map (mem, &info, GST_MAP_WRITE);

  /* fill with pattern */
  for (i = 0; i < info.size; i++)
    info.data[i] = i;

  /* release memory */
  gst_memory_unmap (mem, &info);

[...]

      

Implementing a GstAllocator

WRITEME