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_ZERO_PADDED           (mem)
#define             GST_MEMORY_IS_ZERO_PREFIXED         (mem)
struct              GstMemory;
enum                GstMapFlags;
                    GstMapInfo;
#define             GST_MAP_INFO_INIT
#define             GST_MAP_READWRITE
struct              GstAllocationParams;
GstMemory *         (*GstAllocatorAllocFunction)        (GstAllocator *allocator,
                                                         gsize size,
                                                         GstAllocationParams *params,
                                                         gpointer user_data);
gpointer            (*GstMemoryMapFunction)             (GstMemory *mem,
                                                         gsize maxsize,
                                                         GstMapFlags flags);
void                (*GstMemoryUnmapFunction)           (GstMemory *mem);
void                (*GstMemoryFreeFunction)            (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);
struct              GstMemoryInfo;
                    GstAllocator;
GstAllocator *      gst_allocator_new                   (const GstMemoryInfo *info,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
const gchar *       gst_allocator_get_memory_type       (GstAllocator *allocator);
GstAllocator *      gst_allocator_ref                   (GstAllocator *allocator);
void                gst_allocator_unref                 (GstAllocator *allocator);
#define             GST_ALLOCATOR_SYSMEM
GstAllocator *      gst_allocator_find                  (const gchar *name);
void                gst_allocator_register              (const gchar *name,
                                                         GstAllocator *allocator);
void                gst_allocator_set_default           (GstAllocator *allocator);
void                gst_allocation_params_init          (GstAllocationParams *params);
GstAllocationParams * gst_allocation_params_copy        (const GstAllocationParams *params);
void                gst_allocation_params_free          (GstAllocationParams *params);
GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                         gsize size,
                                                         GstAllocationParams *params);
GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                         gpointer data,
                                                         gsize maxsize,
                                                         gsize offset,
                                                         gsize size,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
GstMemory *         gst_memory_ref                      (GstMemory *mem);
void                gst_memory_unref                    (GstMemory *mem);
gboolean            gst_memory_is_exclusive             (GstMemory *mem);
gsize               gst_memory_get_sizes                (GstMemory *mem,
                                                         gsize *offset,
                                                         gsize *maxsize);
void                gst_memory_resize                   (GstMemory *mem,
                                                         gssize offset,
                                                         gsize size);
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      = (1 << 0),
  GST_MEMORY_FLAG_NO_SHARE      = (1 << 1),
  GST_MEMORY_FLAG_ZERO_PREFIXED = (1 << 2),
  GST_MEMORY_FLAG_ZERO_PADDED   = (1 << 3),

  GST_MEMORY_FLAG_LAST          = (1 << 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_MEMORY_CAST (mem)->flags)

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_MEMORY_FLAGS (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_MEMORY_FLAGS (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_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 {
  GstAllocator   *allocator;

  GstMemoryFlags  flags;
  gint            refcount;
  GstMemory      *parent;
  volatile gint   state;
  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.

GstAllocator *allocator;

pointer to the GstAllocator

GstMemoryFlags flags;

memory flags

gint refcount;

refcount

GstMemory *parent;

parent memory block

volatile gint state;

private state

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      = (1 << 0),
  GST_MAP_WRITE     = (1 << 1),

  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

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

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


GST_MAP_READWRITE

#define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)

Map for readwrite access


struct GstAllocationParams

struct GstAllocationParams {
  GstMemoryFlags flags;
  gsize          align;
  gsize          prefix;
  gsize          padding;
};

Parameters to control the allocation of memory

GstMemoryFlags flags;

flags to control allocation

gsize align;

the desired alignment of the memory

gsize prefix;

the disired prefix

gsize padding;

the desired padding

GstAllocatorAllocFunction ()

GstMemory *         (*GstAllocatorAllocFunction)        (GstAllocator *allocator,
                                                         gsize size,
                                                         GstAllocationParams *params,
                                                         gpointer user_data);

Allocate a new GstMemory from allocator that can hold at least size bytes (+ padding) and is aligned to (align + 1) bytes.

The offset and size of the memory should be set and the prefix/padding must be filled with 0 if params flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

user_data is the data that was used when creating allocator.

allocator :

a GstAllocator

size :

the size

params :

allocator params

user_data :

user data

Returns :

a newly allocated GstMemory. Free with gst_memory_unref()

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.

GstMemoryFreeFunction ()

void                (*GstMemoryFreeFunction)            (GstMemory *mem);

Free the memory used by mem. This function is usually called when the refcount of the mem has reached 0.

mem :

a GstMemory

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.

struct GstMemoryInfo

struct GstMemoryInfo {
  const gchar              *mem_type;

  GstAllocatorAllocFunction alloc;

  GstMemoryMapFunction      mem_map;
  GstMemoryUnmapFunction    mem_unmap;
  GstMemoryFreeFunction     mem_free;

  GstMemoryCopyFunction     mem_copy;
  GstMemoryShareFunction    mem_share;
  GstMemoryIsSpanFunction   mem_is_span;
};

The GstMemoryInfo is used to register new memory allocators and contain the implementations for various memory operations.

const gchar *mem_type;

the memory type this allocator provides

GstAllocatorAllocFunction alloc;

the implementation of the GstAllocatorAllocFunction

GstMemoryMapFunction mem_map;

the implementation of the GstMemoryMapFunction

GstMemoryUnmapFunction mem_unmap;

the implementation of the GstMemoryUnmapFunction

GstMemoryFreeFunction mem_free;

the implementation of the GstMemoryFreeFunction

GstMemoryCopyFunction mem_copy;

the implementation of the GstMemoryCopyFunction

GstMemoryShareFunction mem_share;

the implementation of the GstMemoryShareFunction

GstMemoryIsSpanFunction mem_is_span;

the implementation of the GstMemoryIsSpanFunction

GstAllocator

typedef struct _GstAllocator GstAllocator;

An opaque type returned from gst_allocator_new() or gst_allocator_find() that can be used to allocator memory.


gst_allocator_new ()

GstAllocator *      gst_allocator_new                   (const GstMemoryInfo *info,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Create a new memory allocator with info and user_data.

All functions in info are mandatory exept the copy and is_span functions, which will have a default implementation when left NULL.

The user_data will be passed to all calls of the alloc function. notify will be called with user_data when the allocator is freed.

info :

a GstMemoryInfo

user_data :

user data

notify :

a GDestroyNotify for user_data

Returns :

a new GstAllocator.

gst_allocator_get_memory_type ()

const gchar *       gst_allocator_get_memory_type       (GstAllocator *allocator);

Get the memory type allocated by this allocator

allocator :

a GstAllocator

Returns :

the memory type provided by allocator

gst_allocator_ref ()

GstAllocator *      gst_allocator_ref                   (GstAllocator *allocator);

Increases the refcount of allocator.

allocator :

a GstAllocator

Returns :

allocator with increased refcount

gst_allocator_unref ()

void                gst_allocator_unref                 (GstAllocator *allocator);

Decreases the refcount of allocator. When the refcount reaches 0, the notify function of allocator will be called and the allocator will be freed.

allocator :

a GstAllocator

GST_ALLOCATOR_SYSMEM

#define GST_ALLOCATOR_SYSMEM   "SystemMemory"

The allocator name for the default system memory allocator


gst_allocator_find ()

GstAllocator *      gst_allocator_find                  (const gchar *name);

Find a previously registered allocator with name. When name is NULL, the default allocator will be returned.

name :

the name of the allocator

Returns :

a GstAllocator or NULL when the allocator with name was not registered. Use gst_allocator_unref() to release the allocator after usage. [transfer full]

gst_allocator_register ()

void                gst_allocator_register              (const gchar *name,
                                                         GstAllocator *allocator);

Registers the memory allocator with name. This function takes ownership of allocator.

name :

the name of the allocator

allocator :

GstAllocator. [transfer full]

gst_allocator_set_default ()

void                gst_allocator_set_default           (GstAllocator *allocator);

Set the default allocator. This function takes ownership of allocator.

allocator :

a GstAllocator. [transfer full]

gst_allocation_params_init ()

void                gst_allocation_params_init          (GstAllocationParams *params);

Initialize params to its default values

params :

a GstAllocationParams

gst_allocation_params_copy ()

GstAllocationParams * gst_allocation_params_copy        (const GstAllocationParams *params);

Create a copy of params.

Free-function: gst_allocation_params_free

params :

a GstAllocationParams. [transfer none]

Returns :

a new #GstAllocationParams, free with gst_allocation_params_free(). [transfer full]

gst_allocation_params_free ()

void                gst_allocation_params_free          (GstAllocationParams *params);

Free params

params :

a GstAllocationParams. [in][transfer full]

gst_allocator_alloc ()

GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                         gsize size,
                                                         GstAllocationParams *params);

Use allocator to allocate a new memory block with memory that is at least size big.

The optional params can specify the prefix and padding for the memory. If NULL is passed, no flags, no extra prefix/padding and a default alignment is used.

The prefix/padding will be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

When allocator is NULL, the default allocator will be used.

The alignment in params is given as a bitmask so that align + 1 equals the amount of bytes to align to. For example, to align to 8 bytes, use an alignment of 7.

allocator :

a GstAllocator to use. [transfer none][allow-none]

size :

size of the visible memory area

params :

optional parameters. [transfer none][allow-none]

Returns :

a new GstMemory. [transfer full]

gst_memory_new_wrapped ()

GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                         gpointer data,
                                                         gsize maxsize,
                                                         gsize offset,
                                                         gsize size,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Allocate a new memory block that wraps the given data.

The prefix/padding must be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

flags :

GstMemoryFlags

data :

data to wrap

maxsize :

allocated size of data

offset :

offset in data

size :

size of valid data

user_data :

user_data

notify :

called with user_data when the memory is freed

Returns :

a new GstMemory.

gst_memory_ref ()

GstMemory *         gst_memory_ref                      (GstMemory *mem);

Increases the refcount of mem.

mem :

a GstMemory

Returns :

mem with increased refcount

gst_memory_unref ()

void                gst_memory_unref                    (GstMemory *mem);

Decreases the refcount of mem. When the refcount reaches 0, the free function of mem will be called.

mem :

a GstMemory

gst_memory_is_exclusive ()

gboolean            gst_memory_is_exclusive             (GstMemory *mem);

Check if the current ref to mem is exclusive, this means that no other references exist other than mem.

mem :

a GstMemory

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