![]() |
![]() |
![]() |
GStreamer 1.0 Core Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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
);
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)
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.
memory is readonly. It is not allowed to map the memory with GST_MAP_WRITE. | |
memory must not be shared. Copies will have to be made when this memory needs to be shared between buffers. | |
the memory prefix is filled with 0 bytes | |
the memory padding is filled with 0 bytes | |
first flag that can be used for custom purposes |
#define GST_MEMORY_FLAGS(mem) (GST_MEMORY_CAST (mem)->flags)
A flags word containing GstMemoryFlags flags set on mem
|
a GstMemory. |
#define GST_MEMORY_FLAG_IS_SET(mem,flag) !!(GST_MEMORY_FLAGS (mem) & (flag))
Gives the status of a specific flag on a mem
.
|
a GstMemory. |
|
the GstMemoryFlags to check. |
#define GST_MEMORY_FLAG_UNSET(mem,flag) (GST_MEMORY_FLAGS (mem) &= ~(flag))
Clear a specific flag on a mem
.
|
a GstMemory. |
|
the GstMemoryFlags to clear. |
#define GST_MEMORY_IS_READONLY(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_READONLY)
Check if mem
is readonly.
|
a GstMemory. |
#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.
|
a GstMemory. |
#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.
|
a 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 * |
pointer to the GstAllocator |
GstMemoryFlags |
memory flags |
gint |
refcount |
GstMemory * |
parent memory block |
volatile gint |
private state |
gsize |
the maximum size allocated |
gsize |
the alignment of the memory |
gsize |
the offset where valid data starts |
gsize |
the size of valid data |
typedef enum { GST_MAP_READ = (1 << 0), GST_MAP_WRITE = (1 << 1), GST_MAP_FLAG_LAST = (1 << 16) } GstMapFlags;
Flags used when mapping memory
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 * |
a pointer to the mapped memory |
GstMapFlags |
flags used when mapping the memory |
guint8 * |
a pointer to the mapped data |
gsize |
the valid size in data
|
gsize |
the maximum bytes in data
|
struct GstAllocationParams { GstMemoryFlags flags; gsize align; gsize prefix; gsize padding; };
Parameters to control the allocation of memory
GstMemoryFlags |
flags to control allocation |
gsize |
the desired alignment of the memory |
gsize |
the disired prefix |
gsize |
the desired padding |
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
.
|
a GstAllocator |
|
the size |
|
allocator params |
|
user data |
Returns : |
a newly allocated GstMemory. Free with gst_memory_unref()
|
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.
|
a GstMemory |
|
size to map |
|
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 . |
void (*GstMemoryUnmapFunction) (GstMemory *mem
);
Return the pointer previously retrieved with gst_memory_map()
.
void (*GstMemoryFreeFunction) (GstMemory *mem
);
Free the memory used by mem
. This function is usually called when the
refcount of the mem
has reached 0.
|
a GstMemory |
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.
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
.
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
.
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 * |
the memory type this allocator provides |
GstAllocatorAllocFunction |
the implementation of the GstAllocatorAllocFunction |
GstMemoryMapFunction |
the implementation of the GstMemoryMapFunction |
GstMemoryUnmapFunction |
the implementation of the GstMemoryUnmapFunction |
GstMemoryFreeFunction |
the implementation of the GstMemoryFreeFunction |
GstMemoryCopyFunction |
the implementation of the GstMemoryCopyFunction |
GstMemoryShareFunction |
the implementation of the GstMemoryShareFunction |
GstMemoryIsSpanFunction |
the implementation of the GstMemoryIsSpanFunction |
typedef struct _GstAllocator GstAllocator;
An opaque type returned from gst_allocator_new()
or gst_allocator_find()
that can be used to allocator memory.
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.
|
a GstMemoryInfo |
|
user data |
|
a GDestroyNotify for user_data
|
Returns : |
a new GstAllocator. |
const gchar * gst_allocator_get_memory_type (GstAllocator *allocator
);
Get the memory type allocated by this allocator
|
a GstAllocator |
Returns : |
the memory type provided by allocator
|
GstAllocator * gst_allocator_ref (GstAllocator *allocator
);
Increases the refcount of allocator
.
|
a GstAllocator |
Returns : |
allocator with increased refcount |
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.
|
a GstAllocator |
#define GST_ALLOCATOR_SYSMEM "SystemMemory"
The allocator name for the default system memory allocator
GstAllocator * gst_allocator_find (const gchar *name
);
Find a previously registered allocator with name
. When name
is NULL, the
default allocator will be returned.
|
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]
|
void gst_allocator_register (const gchar *name
,GstAllocator *allocator
);
Registers the memory allocator
with name
. This function takes ownership of
allocator
.
|
the name of the allocator |
|
GstAllocator. [transfer full] |
void gst_allocator_set_default (GstAllocator *allocator
);
Set the default allocator. This function takes ownership of allocator
.
|
a GstAllocator. [transfer full] |
void gst_allocation_params_init (GstAllocationParams *params
);
Initialize params
to its default values
|
a GstAllocationParams |
GstAllocationParams * gst_allocation_params_copy (const GstAllocationParams *params
);
Create a copy of params
.
Free-function: gst_allocation_params_free
|
a GstAllocationParams. [transfer none] |
Returns : |
a new #GstAllocationParams, free with
gst_allocation_params_free() . [transfer full]
|
void gst_allocation_params_free (GstAllocationParams *params
);
Free params
|
a GstAllocationParams. [in][transfer full] |
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.
|
a GstAllocator to use. [transfer none][allow-none] |
|
size of the visible memory area |
|
optional parameters. [transfer none][allow-none] |
Returns : |
a new GstMemory. [transfer full] |
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.
|
GstMemoryFlags |
|
data to wrap |
|
allocated size of data
|
|
offset in data
|
|
size of valid data |
|
user_data |
|
called with user_data when the memory is freed |
Returns : |
a new GstMemory. |
GstMemory * gst_memory_ref (GstMemory *mem
);
Increases the refcount of mem
.
|
a GstMemory |
Returns : |
mem with increased refcount |
void gst_memory_unref (GstMemory *mem
);
Decreases the refcount of mem
. When the refcount reaches 0, the free
function of mem
will be called.
|
a GstMemory |
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
.
|
a GstMemory |
gsize gst_memory_get_sizes (GstMemory *mem
,gsize *offset
,gsize *maxsize
);
Get the current size
, offset
and maxsize
of mem
.
|
a GstMemory |
|
pointer to offset |
|
pointer to maxsize |
Returns : |
the current sizes of mem
|
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.
|
a GstMemory |
|
a new offset |
|
a new size |
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.
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.
void gst_memory_unmap (GstMemory *mem
,GstMapInfo *info
);
Release the memory obtained with gst_memory_map()
|
a GstMemory |
|
a GstMapInfo |
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
.
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
.
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
.