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