GstMemory

GstMemory — refcounted wrapper for memory blocks

Synopsis

#include <gst/gst.h>

struct              GstMemory;
struct              GstMemoryInfo;
                    GstAllocator;
enum                GstMemoryFlags;
enum                GstMapFlags;
#define             GST_MAP_READWRITE
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);
GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                         gsize maxsize,
                                                         gsize align);
GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                         gpointer data,
                                                         GFreeFunc free_func,
                                                         gsize maxsize,
                                                         gsize offset,
                                                         gsize size);
GstMemory *         gst_memory_ref                      (GstMemory *mem);
void                gst_memory_unref                    (GstMemory *mem);
gsize               gst_memory_get_sizes                (GstMemory *mem,
                                                         gsize *offset,
                                                         gsize *maxsize);
void                gst_memory_resize                   (GstMemory *mem,
                                                         gssize offset,
                                                         gsize size);
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);
#define             GST_ALLOCATOR_SYSMEM
GstAllocator *      gst_allocator_find                  (const gchar *name);
void                gst_allocator_register              (const gchar *name,
                                                         GstAllocator *alloc);
void                gst_allocator_set_default           (GstAllocator *allocator);

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

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 returnn 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 2011-06-08 (0.11.0)

Details

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

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;

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;

enum GstMemoryFlags

typedef enum {
  GST_MEMORY_FLAG_READONLY = (1 << 0),
  GST_MEMORY_FLAG_NO_SHARE = (1 << 1),

  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_LAST

first flag that can be used for custom purposes

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

GST_MAP_READWRITE

#define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)

Map for readwrite access


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.

gst_allocator_alloc ()

GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                         gsize maxsize,
                                                         gsize align);

Use allocator to allocate a new memory block with memory that is at least maxsize big and has the given alignment.

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

align 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]

maxsize :

allocated size of data

align :

alignment for the data

Returns :

a new GstMemory. [transfer full]

gst_memory_new_wrapped ()

GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                         gpointer data,
                                                         GFreeFunc free_func,
                                                         gsize maxsize,
                                                         gsize offset,
                                                         gsize size);

Allocate a new memory block that wraps the given data.

flags :

GstMemoryFlags

data :

data to wrap

free_func :

function to free data

maxsize :

allocated size of data

offset :

offset in data

size :

size of valid data

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

mem :

a GstMemory

offset :

a new offset

size :

a new size

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.

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 *alloc);

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]

See Also

GstBuffer