![]() |
![]() |
![]() |
GStreamer 0.11 Core Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <gst/gst.h> struct GstMemory; struct GstMemoryInfo; GstAllocator; #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
); extern gsize gst_memory_alignment; GstMemory * gst_allocator_alloc (const 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
); 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
); #define GST_ALLOCATOR_SYSMEM const GstAllocator * gst_allocator_find (const gchar *name
); const GstAllocator * gst_allocator_register (const gchar *name
,const GstMemoryInfo *info
); void gst_allocator_set_default (const GstAllocator *allocator
);
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.
Last reviewed on 2011-06-08 (0.11.0)
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 * |
pointer to the GstAllocator |
GstMemoryFlags |
memory flags |
gint |
refcount |
GstMemory * |
parent memory block |
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 |
the implementation of the GstMemoryAllocFunction |
GstMemoryGetSizesFunction |
the implementation of the GstMemoryGetSizesFunction |
GstMemoryResizeFunction |
the implementation of the GstMemoryResizeFunction |
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 |
gpointer |
generic user data for the allocator |
#define GST_MEMORY_IS_WRITABLE(mem)
Check if mem
is writable.
|
a GstMemory |
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.
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. | |
first flag that can be used for custom purposes |
typedef enum { GST_MAP_READ = (1 << 0), GST_MAP_WRITE = (1 << 1), } GstMapFlags;
Flags used when mapping memory
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
.
|
a GstAllocator |
|
the maxsize |
|
the alignment |
|
user data |
Returns : |
a newly allocated GstMemory. Free with gst_memory_unref()
|
gsize (*GstMemoryGetSizesFunction) (GstMemory *mem
,gsize *offset
,gsize *maxsize
);
Retrieve the size, offset and maxsize of mem
.
|
a GstMemory |
|
result pointer for offset |
|
result pointer for maxsize |
Returns : |
the size of mem , the offset and the maximum allocated size in maxsize . |
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.
|
a GstMemory |
|
the offset adjustement |
|
the new size |
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.
|
a GstMemory |
|
pointer for the size |
|
pointer for the maxsize |
|
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. |
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.
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
,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.
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
.
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
.
GstMemory * gst_allocator_alloc (const 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.
|
a GstAllocator to use |
|
allocated size of data
|
|
alignment for the data |
Returns : |
a new GstMemory. |
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
.
|
GstMemoryFlags |
|
data to wrap |
|
function to free data
|
|
allocated size of data
|
|
offset in data
|
|
size of valid data |
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 |
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
.
|
a GstMemory |
|
a new offset |
|
a new size |
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.
|
a GstMemory |
|
pointer for size |
|
pointer for maxsize |
|
mapping flags |
Returns : |
a pointer to the memory of mem . |
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.
|
a GstMemory |
|
data to unmap |
|
new size of mem
|
Returns : |
TRUE when the memory was release successfully. |
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
.
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
.
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
.
#define GST_ALLOCATOR_SYSMEM "SystemMemory"
The allocator name for the default system memory allocator
const 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. |
const GstAllocator * gst_allocator_register (const gchar *name
,const GstMemoryInfo *info
);
Registers the memory allocator with name
and implementation functions
info
.
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 field in info
will be passed to all calls of the alloc
function.
|
the name of the allocator |
|
GstMemoryInfo |
Returns : |
a new GstAllocator. |
void gst_allocator_set_default (const GstAllocator *allocator
);
Set the default allocator.
|
a GstAllocator |