GstMemory

GstMemory — refcounted wrapper for memory blocks

Functions

Types and Values

Object Hierarchy


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.

Last reviewed on 2012-03-28 (0.11.3)

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