Memory
- class Memory(*args, **kwargs)
GstMemory is a lightweight refcounted object that wraps a region of memory.
They are typically used to manage the data of a Buffer
.
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 alloc()
method call. When None
is used as the allocator, the default allocator will
be used.
New allocators can be registered with register()
.
Allocators are identified by name and can be retrieved with
find()
. set_default()
can be used to change the
default allocator.
New memory can be created with 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
get_sizes()
and resize()
respectively.
Getting access to the data of the memory is performed with map()
.
The call will return a pointer to offset bytes into the region of memory.
After the memory access is completed, unmap()
should be called.
Memory can be copied with copy()
, which will return a writable
copy. 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 is_span()
returns True
.
Constructors
- class Memory
- classmethod new_wrapped(flags: MemoryFlags, data: Sequence[int], maxsize: int, offset: int, user_data: None, notify: Callable[[...], None] | None = None) Memory | None
Allocate a new memory block that wraps the given
data
.The prefix/padding must be filled with 0 if
flags
containsGST_MEMORY_FLAG_ZERO_PREFIXED
andGST_MEMORY_FLAG_ZERO_PADDED
respectively.- Parameters:
flags –
MemoryFlags
data – data to wrap
maxsize – allocated size of
data
offset – offset in
data
user_data – user_data
notify – called with
user_data
when the memory is freed
Methods
- class Memory
-
- is_span(mem2: Memory) tuple[bool, int]
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
andmem2
can be merged efficiently by performingshare()
on the parent object from the returnedoffset
.- Parameters:
mem2 – a
Memory
- is_type(mem_type: str) bool
Check if
mem
if allocated with an allocator formem_type
.Added in version 1.2.
- Parameters:
mem_type – a memory type
- make_mapped(flags: MapFlags) tuple[Memory | None, MapInfo]
Create a
Memory
object that is mapped withflags
. Ifmem
is mappable withflags
, this function returns the mappedmem
directly. Otherwise a mapped copy ofmem
is returned.This function takes ownership of old
mem
and returns a reference to a newMemory
.- Parameters:
flags – mapping flags
- map(flags: MapFlags) tuple[bool, MapInfo]
Fill
info
with the pointer and sizes of the memory inmem
that can be accessed according toflags
.This function can return
False
for various reasons:the memory backed by
mem
is not accessible with the givenflags
.the memory was already mapped with a different mapping.
info
and its contents remain valid for as long asmem
is valid and untilunmap()
is called.For each
map()
call, a correspondingunmap()
call should be done.- Parameters:
flags – mapping flags
- resize(offset: int, size: int) None
Resize the memory region.
mem
should be writable and offset + size should be less than the maxsize ofmem
.GST_MEMORY_FLAG_ZERO_PREFIXED
andGST_MEMORY_FLAG_ZERO_PADDED
will be cleared when offset or padding is increased respectively.- Parameters:
offset – a new offset
size – a new size
Return a shared copy of
size
bytes frommem
starting fromoffset
. 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 fromoffset
to the end of the memory region.- Parameters:
offset – offset to share from
size – size to share, or -1 to share to the end of the memory region