GstMemory

GstMemory — refcounted wrapper for memory blocks

Synopsis

#include <gst/gst.h>

struct              GstMemory;
struct              GstMemoryInfo;
#define             GST_MEMORY_IS_WRITABLE              (mem)
enum                GstMemoryFlags;
enum                GstMapFlags;
#define             GST_MAP_READWRITE
GstMemory *         (*GstMemoryAllocFunction)           (const GstAllocator *allocator,
                                                         gsize maxsize,
                                                         gsize align,
                                                         gpointer user_data);
gsize               (*GstMemoryGetSizesFunction)        (GstMemory *mem,
                                                         gsize *offset,
                                                         gsize *maxsize);
void                (*GstMemoryResizeFunction)          (GstMemory *mem,
                                                         gssize offset,
                                                         gsize size);
gpointer            (*GstMemoryMapFunction)             (GstMemory *mem,
                                                         gsize *size,
                                                         gsize *maxsize,
                                                         GstMapFlags flags);
gboolean            (*GstMemoryUnmapFunction)           (GstMemory *mem,
                                                         gpointer data,
                                                         gsize size);
void                (*GstMemoryFreeFunction)            (GstMemory *mem);
GstMemory *         (*GstMemoryCopyFunction)            (GstMemory *mem,
                                                         gssize offset,
                                                         gsize size);
GstMemory *         (*GstMemoryShareFunction)           (GstMemory *mem,
                                                         gssize offset,
                                                         gsize size);
gboolean            (*GstMemoryIsSpanFunction)          (GstMemory *mem1,
                                                         GstMemory *mem2,
                                                         gsize *offset);
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);
gpointer            gst_memory_map                      (GstMemory *mem,
                                                         gsize *size,
                                                         gsize *maxsize,
                                                         GstMapFlags flags);
gboolean            gst_memory_unmap                    (GstMemory *mem,
                                                         gpointer data,
                                                         gsize size);
GstMemory *         gst_memory_copy                     (GstMemory *mem,
                                                         gssize offset,
                                                         gsize size);
GstMemory *         gst_memory_share                    (GstMemory *mem,
                                                         gssize offset,
                                                         gsize 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.

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(). 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 and with the function gst_memory_span().

Last reviewed on 2011-06-08 (0.11.0)

Details

struct GstMemory

struct GstMemory {
  const GstAllocator *allocator;

  GstMemoryFlags  flags;
  gint            refcount;
  GstMemory      *parent;
};

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

const GstAllocator *allocator;

pointer to the GstAllocator

GstMemoryFlags flags;

memory flags

gint refcount;

refcount

GstMemory *parent;

parent memory block

struct GstMemoryInfo

struct GstMemoryInfo {
  GstMemoryAllocFunction    alloc;
  GstMemoryGetSizesFunction get_sizes;
  GstMemoryResizeFunction   resize;
  GstMemoryMapFunction      map;
  GstMemoryUnmapFunction    unmap;
  GstMemoryFreeFunction     free;

  GstMemoryCopyFunction     copy;
  GstMemoryShareFunction    share;
  GstMemoryIsSpanFunction   is_span;

  gpointer user_data;
};

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

GstMemoryAllocFunction alloc;

the implementation of the GstMemoryAllocFunction

GstMemoryGetSizesFunction get_sizes;

the implementation of the GstMemoryGetSizesFunction

GstMemoryResizeFunction resize;

the implementation of the GstMemoryResizeFunction

GstMemoryMapFunction map;

the implementation of the GstMemoryMapFunction

GstMemoryUnmapFunction unmap;

the implementation of the GstMemoryUnmapFunction

GstMemoryFreeFunction free;

the implementation of the GstMemoryFreeFunction

GstMemoryCopyFunction copy;

the implementation of the GstMemoryCopyFunction

GstMemoryShareFunction share;

the implementation of the GstMemoryShareFunction

GstMemoryIsSpanFunction is_span;

the implementation of the GstMemoryIsSpanFunction

gpointer user_data;

generic user data for the allocator

GST_MEMORY_IS_WRITABLE()

#define             GST_MEMORY_IS_WRITABLE(mem)

Check if mem is writable.

mem :

a GstMemory

enum GstMemoryFlags

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

  GST_MEMORY_FLAG_LAST = (1 << 24)
} 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),
} GstMapFlags;

Flags used when mapping memory

GST_MAP_READ

map for read access

GST_MAP_WRITE

map for write access

GST_MAP_READWRITE

#define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)

Map for readwrite access


GstMemoryAllocFunction ()

GstMemory *         (*GstMemoryAllocFunction)           (const GstAllocator *allocator,
                                                         gsize maxsize,
                                                         gsize align,
                                                         gpointer user_data);

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

user_data is the data that was used when registering allocator.

allocator :

a GstAllocator

maxsize :

the maxsize

align :

the alignment

user_data :

user data

Returns :

a newly allocated GstMemory. Free with gst_memory_unref()

GstMemoryGetSizesFunction ()

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

Retrieve the size, offset and maxsize of mem.

mem :

a GstMemory

offset :

result pointer for offset

maxsize :

result pointer for maxsize

Returns :

the size of mem, the offset and the maximum allocated size in maxsize.

GstMemoryResizeFunction ()

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

Adjust the size and offset of mem. offset bytes will be adjusted from the current first byte in mem as retrieved with gst_memory_map() and the new size will be set to size.

size can be set to -1, which will only adjust the offset.

mem :

a GstMemory

offset :

the offset adjustement

size :

the new size

GstMemoryMapFunction ()

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

Get the memory of mem that can be accessed according to the mode specified in flags. size and maxsize will respectively contain the current amount of valid bytes in the returned memory and the maximum allocated memory. size and maxsize can optionally be set to NULL.

mem :

a GstMemory

size :

pointer for the size

maxsize :

pointer for the maxsize

flags :

access mode for the memory

Returns :

a pointer to memory. size bytes are currently used from the returned pointer and maxsize bytes can potentially be used.

GstMemoryUnmapFunction ()

gboolean            (*GstMemoryUnmapFunction)           (GstMemory *mem,
                                                         gpointer data,
                                                         gsize size);

Return the pointer previously retrieved with gst_memory_map() and adjust the size of the memory with size. size can optionally be set to -1 to not modify the size.

mem :

a GstMemory

data :

the data pointer

size :

the new size

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,
                                                         gsize 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

Returns :

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

GstMemoryShareFunction ()

GstMemory *         (*GstMemoryShareFunction)           (GstMemory *mem,
                                                         gssize offset,
                                                         gsize 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

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

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

Get a pointer to the memory of mem that can be accessed according to flags.

size and maxsize will contain the size of the memory and the maximum allocated memory of mem respectively. They can be set to NULL.

mem :

a GstMemory

size :

pointer for size

maxsize :

pointer for maxsize

flags :

mapping flags

Returns :

a pointer to the memory of mem.

gst_memory_unmap ()

gboolean            gst_memory_unmap                    (GstMemory *mem,
                                                         gpointer data,
                                                         gsize size);

Release the memory pointer obtained with gst_memory_map() and set the size of the memory to size. size can be set to -1 when the size should not be updated.

mem :

a GstMemory

data :

data to unmap

size :

new size of mem

Returns :

TRUE when the memory was release successfully.

gst_memory_copy ()

GstMemory *         gst_memory_copy                     (GstMemory *mem,
                                                         gssize offset,
                                                         gsize 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

Returns :

a new GstMemory.

gst_memory_share ()

GstMemory *         gst_memory_share                    (GstMemory *mem,
                                                         gssize offset,
                                                         gsize 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

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