GStreamer 1.0 Core Reference Manual: GstMemory

## GstMemory GstMemory — refcounted wrapper for memory blocks |

## Functions

#define | GST_MEMORY_FLAGS()
#define | GST_MEMORY_FLAG_IS_SET()
#define | GST_MEMORY_FLAG_UNSET()
#define | GST_MEMORY_IS_READONLY()
#define | GST_MEMORY_IS_NO_SHARE()
#define | GST_MEMORY_IS_ZERO_PADDED()
#define | GST_MEMORY_IS_ZERO_PREFIXED()
#define | GST_MEMORY_IS_PHYSICALLY_CONTIGUOUS()
#define | GST_MEMORY_IS_NOT_MAPPABLE()
#define | GST_MAP_READWRITE
gpointer | (*GstMemoryMapFunction) ()
void | (*GstMemoryUnmapFunction) ()
GstMemory * | (*GstMemoryCopyFunction) ()
GstMemory * | (*GstMemoryShareFunction) ()
gboolean | (*GstMemoryIsSpanFunction) ()
void | gst_memory_init ()
gboolean | gst_memory_is_type ()
GstMemory * | gst_memory_ref ()
void | gst_memory_unref ()
gsize | gst_memory_get_sizes ()
void | gst_memory_resize ()
#define | gst_memory_lock()
#define | gst_memory_unlock()
#define | gst_memory_is_writable()
#define | gst_memory_make_writable()
GstMemory * | gst_memory_make_mapped ()
gboolean | gst_memory_map ()
void | gst_memory_unmap ()
GstMemory * | gst_memory_copy ()
GstMemory * | gst_memory_share ()
gboolean | gst_memory_is_span ()

## Types and Values

enum | GstMemoryFlags
struct | GstMemory
enum | GstMapFlags
| GstMapInfo
#define | GST_MAP_INFO_INIT

## Object Hierarchy

        GBoxed
        ╰── GstMemory

## Includes

    #include <gst/gst.h>

## Description

GstMemory is a lightweight refcounted object that wraps a region of memory. They are typically used to manage the data of a GstBuffer.

A GstMemory object has an allocated region of memory of maxsize. The maximum size does not change during the lifetime of the memory object. The memory also has an offset and size property that specifies the valid range of memory in the allocated region.

Memory is usually created by allocators with a `gst_allocator_alloc()` method call. When `NULL` is used as the allocator, the default allocator will be used.

New allocators can be registered with `gst_allocator_register()`. Allocators are identified by name and can be retrieved with `gst_allocator_find()`. `gst_allocator_set_default()` can be used to change the default allocator.

New memory can be created with `gst_memory_new_wrapped()` that wraps the memory allocated elsewhere.

Refcounting of the memory block is performed with `gst_memory_ref()` and `gst_memory_unref()`.

The size of the memory can be retrieved and changed with `gst_memory_get_sizes()` and `gst_memory_resize()` respectively.

Getting access to the data of the memory is performed with `gst_memory_map()`. The call will return a pointer to offset bytes into the region of memory. After the memory access is completed, `gst_memory_unmap()` should be called.

Memory can be copied with `gst_memory_copy()`, which will return a writable copy. `gst_memory_share()` will create a new memory block that shares the memory with an existing memory block at a custom offset and with a custom size.

Memory can be efficiently merged when `gst_memory_is_span()` returns `TRUE`.

## Functions

### GST_MEMORY_FLAGS()

    #define GST_MEMORY_FLAGS(mem)  GST_MINI_OBJECT_FLAGS (mem)

A flags word containing GstMemoryFlags flags set on `mem`

#### Parameters

mem | a GstMemory. |

### GST_MEMORY_FLAG_IS_SET()

    #define GST_MEMORY_FLAG_IS_SET(mem,flag)   GST_MINI_OBJECT_FLAG_IS_SET (mem,flag)

Gives the status of a specific flag on a `mem` .

#### Parameters

mem | a GstMemory. |
flag | the GstMemoryFlags to check. |

### GST_MEMORY_FLAG_UNSET()

    #define GST_MEMORY_FLAG_UNSET(mem,flag)   GST_MINI_OBJECT_FLAG_UNSET (mem, flag)

Clear a specific flag on a `mem` .

#### Parameters

mem | a GstMemory. |
flag | the GstMemoryFlags to clear. |

### GST_MEMORY_IS_READONLY()

    #define GST_MEMORY_IS_READONLY(mem)        GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_READONLY)

Check if `mem` is readonly.

#### Parameters

mem | a GstMemory. |

### GST_MEMORY_IS_NO_SHARE()

    #define GST_MEMORY_IS_NO_SHARE(mem)        GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_NO_SHARE)

Check if `mem` cannot be shared between buffers

#### Parameters

mem | a GstMemory. |

### GST_MEMORY_IS_ZERO_PADDED()

    #define GST_MEMORY_IS_ZERO_PADDED(mem)     GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_ZERO_PADDED)

Check if the padding in `mem` is 0 filled.

#### Parameters

mem | a GstMemory. |

### GST_MEMORY_IS_ZERO_PREFIXED()

    #define GST_MEMORY_IS_ZERO_PREFIXED(mem)   GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_ZERO_PREFIXED)

Check if the prefix in `mem` is 0 filled.

#### Parameters

mem | a GstMemory. |

### GST_MEMORY_IS_PHYSICALLY_CONTIGUOUS()

    #define GST_MEMORY_IS_PHYSICALLY_CONTIGUOUS(mem)     GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_PHYSICALLY_CONTIGUOUS)

Check if `mem` is physically contiguous.

#### Parameters

mem | a GstMemory. |

Since 1.2

### GST_MEMORY_IS_NOT_MAPPABLE()

    #define GST_MEMORY_IS_NOT_MAPPABLE(mem)     GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_NOT_MAPPABLE)

Check if `mem` can't be mapped via `gst_memory_map()` without any preconditions

#### Parameters

mem | a GstMemory. |

Since 1.2

### GST_MAP_READWRITE

    #define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)

GstMapFlags value alias for GST_MAP_READ | GST_MAP_WRITE

### GstMemoryMapFunction ()

    gpointer
    (*GstMemoryMapFunction) (GstMemory *mem,
                             gsize maxsize,
                             GstMapFlags flags);

Get the memory of `mem` that can be accessed according to the mode specified in `flags` . The function should return a pointer that contains at least `maxsize` bytes.

#### Parameters

mem | a GstMemory |
maxsize | size to map |
flags | access mode for the memory |

#### Returns

a pointer to memory of which at least `maxsize` bytes can be accessed according to the access pattern in `flags` .

### GstMemoryUnmapFunction ()

    void
    (*GstMemoryUnmapFunction) (GstMemory *mem);

Return the pointer previously retrieved with `gst_memory_map()`.

#### Parameters

mem | a GstMemory |

#### Returns

`TRUE` on success.

### GstMemoryCopyFunction ()

    GstMemory *
    (*GstMemoryCopyFunction) (GstMemory *mem,
                              gssize offset,
                              gssize size);

Copy `size` bytes from `mem` starting at `offset` and return them wrapped in a new GstMemory object. If `size` is set to -1, all bytes starting at `offset` are copied.

#### Parameters

mem | a GstMemory |
offset | an offset |
size | a size or -1 |

#### Returns

a new GstMemory object wrapping a copy of the requested region in `mem` .

### GstMemoryShareFunction ()

    GstMemory *
    (*GstMemoryShareFunction) (GstMemory *mem,
                               gssize offset,
                               gssize size);

Share `size` bytes from `mem` starting at `offset` and return them wrapped in a new GstMemory object. If `size` is set to -1, all bytes starting at `offset` are shared. This function does not make a copy of the bytes in `mem` .

#### Parameters

mem | a GstMemory |
offset | an offset |
size | a size or -1 |

#### Returns

a new GstMemory object sharing the requested region in `mem` .

### GstMemoryIsSpanFunction ()

    gboolean
    (*GstMemoryIsSpanFunction) (GstMemory *mem1,
                                GstMemory *mem2,
                                gsize *offset);

Check if `mem1` and `mem2` occupy contiguous memory and return the offset of `mem1` in the parent buffer in `offset` .

#### Parameters

mem1 | a GstMemory |
mem2 | a GstMemory |
offset | a result offset |

#### Returns

`TRUE` if `mem1` and `mem2` are in contiguous memory.

### gst_memory_init ()

    void
    gst_memory_init (GstMemory *mem,
                     GstMemoryFlags flags,
                     GstAllocator *allocator,
                     GstMemory *parent,
                     gsize maxsize,
                     gsize align,
                     gsize offset,
                     gsize size);

Initializes a newly allocated `mem` with the given parameters. This function will call `gst_mini_object_init()` with the default memory parameters.

#### Parameters

mem | a GstMemory |
flags | GstMemoryFlags |
allocator | the GstAllocator |
parent | the parent of `mem` |
maxsize | the total size of the memory |
align | the alignment of the memory |
offset | The offset in the memory |
size | the size of valid data in the memory |

### gst_memory_is_type ()

    gboolean
    gst_memory_is_type (GstMemory *mem,
                        const gchar *mem_type);

Check if `mem` if allocated with an allocator for `mem_type` .

#### Parameters

mem | a GstMemory |
mem_type | a memory type |

#### Returns

`TRUE` if `mem` was allocated from an allocator for `mem_type` .

Since 1.2

### gst_memory_ref ()

    GstMemory *
    gst_memory_ref (GstMemory *memory);

Increase the refcount of this memory.

#### Parameters

memory | The memory to refcount |

#### Returns

`memory` (for convenience when doing assignments).

[transfer full]

### gst_memory_unref ()

    void
    gst_memory_unref (GstMemory *memory);

Decrease the refcount of an memory, freeing it if the refcount reaches 0.

#### Parameters

memory | the memory to refcount. | [transfer full]

### gst_memory_get_sizes ()

    gsize
    gst_memory_get_sizes (GstMemory *mem,
                          gsize *offset,
                          gsize *maxsize);

Get the current `size` , `offset` and `maxsize` of `mem` .

#### Parameters

mem | a GstMemory |
offset | pointer to offset |
maxsize | pointer to maxsize |

#### Returns

the current sizes of `mem`

### gst_memory_resize ()

    void
    gst_memory_resize (GstMemory *mem,
                       gssize offset,
                       gsize size);

Resize the memory region. `mem` should be writable and offset + size should be less than the maxsize of `mem` .

GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED will be cleared when offset or padding is increased respectively.

#### Parameters

mem | a GstMemory |
offset | a new offset |
size | a new size |

### gst_memory_lock()

    #define        gst_memory_lock(m,f)        gst_mini_object_lock (GST_MINI_OBJECT_CAST (m), (f))

### gst_memory_unlock()

    #define        gst_memory_unlock(m,f)      gst_mini_object_unlock (GST_MINI_OBJECT_CAST (m), (f))

### gst_memory_is_writable()

    #define        gst_memory_is_writable(m)   gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (m))

### gst_memory_make_writable()

    #define        gst_memory_make_writable(m) GST_MEMORY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (m)))

### gst_memory_make_mapped ()

    GstMemory *
    gst_memory_make_mapped (GstMemory *mem,
                            GstMapInfo *info,
                            GstMapFlags flags);

Create a GstMemory object that is mapped with `flags` . If `mem` is mappable with `flags` , this function returns the mapped `mem` directly. Otherwise a mapped copy of `mem` is returned.

This function takes ownership of old `mem` and returns a reference to a new GstMemory.

#### Parameters

mem | a GstMemory. | [transfer full]
info | pointer for info. | [out]
flags | mapping flags |

#### Returns

a GstMemory object mapped with `flags` or `NULL` when a mapping is not possible.

[transfer full]

### gst_memory_map ()

    gboolean
    gst_memory_map (GstMemory *mem,
                    GstMapInfo *info,
                    GstMapFlags flags);

Fill `info` with the pointer and sizes of the memory in `mem` that can be accessed according to `flags` .

This function can return `FALSE` for various reasons:

- the memory backed by `mem` is not accessible with the given `flags` .

- the memory was already mapped with a different mapping.

`info` and its contents remain valid for as long as `mem` is valid and until `gst_memory_unmap()` is called.

For each `gst_memory_map()` call, a corresponding `gst_memory_unmap()` call should be done.

#### Parameters

mem | a GstMemory |
info | pointer for info. | [out]
flags | mapping flags |

#### Returns

`TRUE` if the map operation was successful.

### gst_memory_unmap ()

    void
    gst_memory_unmap (GstMemory *mem,
                      GstMapInfo *info);

Release the memory obtained with `gst_memory_map()`

#### Parameters

mem | a GstMemory |
info | a GstMapInfo |

### gst_memory_copy ()

    GstMemory *
    gst_memory_copy (GstMemory *mem,
                     gssize offset,
                     gssize size);

Return a copy of `size` bytes from `mem` starting from `offset` . This copy is guaranteed to be writable. `size` can be set to -1 to return a copy all bytes from `offset` .

#### Parameters

mem | a GstMemory |
offset | an offset to copy |
size | size to copy or -1 to copy all bytes from offset |

#### Returns

a new GstMemory.

### gst_memory_share ()

    GstMemory *
    gst_memory_share (GstMemory *mem,
                      gssize offset,
                      gssize size);

Return a shared copy of `size` bytes from `mem` starting from `offset` . No memory copy is performed and the memory region is simply shared. The result is guaranteed to be not-writable. `size` can be set to -1 to return a share all bytes from `offset` .

#### Parameters

mem | a GstMemory |
offset | an offset to share |
size | size to share or -1 to share bytes from offset |

#### Returns

a new GstMemory.

### gst_memory_is_span ()

    gboolean
    gst_memory_is_span (GstMemory *mem1,
                        GstMemory *mem2,
                        gsize *offset);

Check if `mem1` and mem2 share the memory with a common parent memory object and that the memory is contiguous.

If this is the case, the memory of `mem1` and `mem2` can be merged efficiently by performing `gst_memory_share()` on the parent object from the returned `offset` .

#### Parameters

mem1 | a GstMemory |
mem2 | a GstMemory |
offset | a pointer to a result offset |

#### Returns

`TRUE` if the memory is contiguous and of a common parent.

## Types and Values

### enum GstMemoryFlags

Flags for wrapped memory.

#### Members

GST_MEMORY_FLAG_READONLY | memory is readonly. It is not allowed to map the memory with GST_MAP_WRITE. |
GST_MEMORY_FLAG_NO_SHARE | memory must not be shared. Copies will have to be made when this memory needs to be shared between buffers. |
GST_MEMORY_FLAG_ZERO_PREFIXED | the memory prefix is filled with 0 bytes |
GST_MEMORY_FLAG_ZERO_PADDED | the memory padding is filled with 0 bytes |
GST_MEMORY_FLAG_PHYSICALLY_CONTIGUOUS | the memory is physically contiguous. Since 1.2 |
GST_MEMORY_FLAG_NOT_MAPPABLE | the memory can't be mapped via `gst_memory_map()` without any preconditions. Since 1.2 |
GST_MEMORY_FLAG_LAST | first flag that can be used for custom purposes |

### struct GstMemory

    struct GstMemory {
      GstMiniObject   mini_object;

      GstAllocator   *allocator;

      GstMemory      *parent;
      gsize           maxsize;
      gsize           align;
      gsize           offset;
      gsize           size;
    };

Base structure for memory implementations. Custom memory will put this structure as the first member of their structure.

#### Members

GstMiniObject `mini_object`; | parent structure |
GstAllocator *`allocator`; | pointer to the GstAllocator |
GstMemory *`parent`; | parent memory block |
gsize `maxsize`; | the maximum size allocated |
gsize `align`; | the alignment of the memory |
gsize `offset`; | the offset where valid data starts |
gsize `size`; | the size of valid data |

### enum GstMapFlags

Flags used when mapping memory

#### Members

GST_MAP_READ | map for read access |
GST_MAP_WRITE | map for write access |
GST_MAP_FLAG_LAST | first flag that can be used for custom purposes |

### GstMapInfo

    typedef struct {
      GstMemory *memory;
      GstMapFlags flags;
      guint8 *data;
      gsize size;
      gsize maxsize;
    } GstMapInfo;

A structure containing the result of a map operation such as `gst_memory_map()`. It contains the data and size.

#### Members

GstMemory *`memory`; | a pointer to the mapped memory |
GstMapFlags `flags`; | flags used when mapping the memory |
guint8 *`data`; | a pointer to the mapped data. | [array length=size]
gsize `size`; | the valid size in `data` |
gsize `maxsize`; | the maximum bytes in `data` |

### GST_MAP_INFO_INIT

    #define GST_MAP_INFO_INIT { NULL, 0, NULL, 0, 0, }

Initializer for GstMapInfo

## See Also

GstBuffer