GstMemory

## GstMemory GstMemory — refcounted wrapper for memory blocks |

## Synopsis

    #include <gst/gst.h>

    enum                GstMemoryFlags;
    #define             GST_MEMORY_FLAGS                    (mem)
    #define             GST_MEMORY_FLAG_IS_SET              (mem,
                                                             flag)
    #define             GST_MEMORY_FLAG_UNSET               (mem,
                                                             flag)
    #define             GST_MEMORY_IS_READONLY              (mem)
    #define             GST_MEMORY_IS_NO_SHARE              (mem)
    #define             GST_MEMORY_IS_ZERO_PADDED           (mem)
    #define             GST_MEMORY_IS_ZERO_PREFIXED         (mem)
    struct              GstMemory;
    enum                GstMapFlags;
    #define             GST_MAP_READWRITE
                        GstMapInfo;
    #define             GST_MAP_INFO_INIT
    gpointer            (*GstMemoryMapFunction)             (GstMemory *mem,
                                                             gsize maxsize,
                                                             GstMapFlags flags);
    void                (*GstMemoryUnmapFunction)           (GstMemory *mem);
    GstMemory *         (*GstMemoryCopyFunction)            (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    GstMemory *         (*GstMemoryShareFunction)           (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    gboolean            (*GstMemoryIsSpanFunction)          (GstMemory *mem1,
                                                             GstMemory *mem2,
                                                             gsize *offset);
    void                gst_memory_init                     (GstMemory *mem,
                                                             GstMemoryFlags flags,
                                                             GstAllocator *allocator,
                                                             GstMemory *parent,
                                                             gsize maxsize,
                                                             gsize align,
                                                             gsize offset,
                                                             gsize size);
    GstMemory *         gst_memory_ref                      (GstMemory *memory);
    void                gst_memory_unref                    (GstMemory *memory);
    gsize               gst_memory_get_sizes                (GstMemory *mem,
                                                             gsize *offset,
                                                             gsize *maxsize);
    void                gst_memory_resize                   (GstMemory *mem,
                                                             gssize offset,
                                                             gsize size);
    #define             gst_memory_lock                     (m,
                                                             f)
    #define             gst_memory_unlock                   (m,
                                                             f)
    #define             gst_memory_is_writable              (m)
    GstMemory *         gst_memory_make_mapped              (GstMemory *mem,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);
    gboolean            gst_memory_map                      (GstMemory *mem,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);
    void                gst_memory_unmap                    (GstMemory *mem,
                                                             GstMapInfo *info);
    GstMemory *         gst_memory_copy                     (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    GstMemory *         gst_memory_share                    (GstMemory *mem,
                                                             gssize offset,
                                                             gssize size);
    gboolean            gst_memory_is_span                  (GstMemory *mem1,
                                                             GstMemory *mem2,
                                                             gsize *offset);

## 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.

Last reviewed on 2012-03-28 (0.11.3)

## Details

### enum GstMemoryFlags

    typedef enum {
      GST_MEMORY_FLAG_READONLY      = GST_MINI_OBJECT_FLAG_LOCK_READONLY,
      GST_MEMORY_FLAG_NO_SHARE      = (GST_MINI_OBJECT_FLAG_LAST << 0),
      GST_MEMORY_FLAG_ZERO_PREFIXED = (GST_MINI_OBJECT_FLAG_LAST << 1),
      GST_MEMORY_FLAG_ZERO_PADDED   = (GST_MINI_OBJECT_FLAG_LAST << 2),

      GST_MEMORY_FLAG_LAST          = (GST_MINI_OBJECT_FLAG_LAST << 16)
    } GstMemoryFlags;

Flags for wrapped memory.

`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_LAST` | first flag that can be used for custom purposes

### GST_MEMORY_FLAGS()

    #define GST_MEMORY_FLAGS(mem)  GST_MINI_OBJECT_FLAGS (mem)

A flags word containing GstMemoryFlags flags set on `mem`

`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`.

`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`.

`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.

`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

`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.

`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.

`mem` : | a GstMemory.

### 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.

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

    typedef enum {
      GST_MAP_READ      = GST_LOCK_FLAG_READ,
      GST_MAP_WRITE     = GST_LOCK_FLAG_WRITE,

      GST_MAP_FLAG_LAST = (1 << 16)
    } GstMapFlags;

Flags used when mapping memory

`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

### GST_MAP_READWRITE

    #define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)

GstMapFlags value alias for GST_MAP_READ | GST_MAP_WRITE

### 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.

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

### 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.

`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()`.

`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.

`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`.

`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`.

`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.

`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_ref ()

    GstMemory *         gst_memory_ref                      (GstMemory *memory);

Increase the refcount of this memory.

`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.

`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`.

`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.

`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_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.

`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.

`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()`

`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`.

`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`.

`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`.

`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.

## See Also

GstBuffer