| Top | |
|
|
|
| enum | GstMemoryFlags |
| struct | GstMemory |
| enum | GstMapFlags |
| #define | GST_MAP_READWRITE |
| GstMapInfo | |
| #define | GST_MAP_INFO_INIT |
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.
#define GST_MEMORY_FLAGS(mem) GST_MINI_OBJECT_FLAGS (mem)
A flags word containing GstMemoryFlags flags set on mem
#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
.
#define GST_MEMORY_FLAG_UNSET(mem,flag) GST_MINI_OBJECT_FLAG_UNSET (mem, flag)
Clear a specific flag on a mem
.
#define GST_MEMORY_IS_READONLY(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_READONLY)
Check if mem
is readonly.
#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
#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.
#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.
#define GST_MEMORY_IS_PHYSICALLY_CONTIGUOUS(mem) GST_MEMORY_FLAG_IS_SET(mem,GST_MEMORY_FLAG_PHYSICALLY_CONTIGUOUS)
Check if mem
is physically contiguous.
Since: 1.2
#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
Since: 1.2
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.
gpointer (*GstMemoryMapFullFunction) (GstMemory *mem,GstMapInfo *info,gsize maxsize);
Get the memory of mem
that can be accessed according to the mode specified
in info
's flags. The function should return a pointer that contains at least
maxsize
bytes.
void
(*GstMemoryUnmapFunction) (GstMemory *mem);
Return the pointer previously retrieved with gst_memory_map().
void (*GstMemoryUnmapFullFunction) (GstMemory *mem,GstMapInfo *info);
Return the pointer previously retrieved with gst_memory_map() with info
.
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
.
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.
[skip]
mem |
||
flags |
||
allocator |
the GstAllocator |
|
parent |
the parent of |
|
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 |
gboolean gst_memory_is_type (GstMemory *mem,const gchar *mem_type);
Check if mem
if allocated with an allocator for mem_type
.
Since: 1.2
GstMemory *
gst_memory_ref (GstMemory *memory);
Increase the refcount of this memory.
void
gst_memory_unref (GstMemory *memory);
Decrease the refcount of an memory, freeing it if the refcount reaches 0.
gsize gst_memory_get_sizes (GstMemory *mem,gsize *offset,gsize *maxsize);
Get the current size
, offset
and maxsize
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.
#define gst_memory_unlock(m,f) gst_mini_object_unlock (GST_MINI_OBJECT_CAST (m), (f))
#define gst_memory_is_writable(m) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (m))
#define gst_memory_make_writable(m) GST_MEMORY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (m)))
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()
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
from offset
to the end of the memory region.
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 non-writable. size
can be set to -1 to return a shared
copy from offset
to the end of the memory region.
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
.
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 |
||
|
the memory is physically contiguous. (Since 1.2) |
||
|
the memory can't be mapped via |
||
|
first flag that can be used for custom purposes |
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.
GstMiniObject |
parent structure |
|
GstAllocator * |
pointer to the GstAllocator |
|
GstMemory * |
parent memory block |
|
gsize |
the maximum size allocated |
|
gsize |
the alignment of the memory |
|
gsize |
the offset where valid data starts |
|
gsize |
the size of valid data |
#define GST_MAP_READWRITE (GST_MAP_READ | GST_MAP_WRITE)
GstMapFlags value alias for GST_MAP_READ | GST_MAP_WRITE
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. |
[array length=size] |
gsize |
the valid size in |
|
gsize |
the maximum bytes in |
#define GST_MAP_INFO_INIT { NULL, 0, NULL, 0, 0, {0, }, {0, }}
Initializer for GstMapInfo