Gst.Memory

Fields

Name

Type

Access

Description

align

int

r/w

the alignment of the memory

allocator

Gst.Allocator

r/w

pointer to the Gst.Allocator

maxsize

int

r/w

the maximum size allocated

mini_object

Gst.MiniObject

r/w

parent structure

offset

int

r/w

the offset where valid data starts

parent

Gst.Memory

r/w

parent memory block

size

int

r/w

the size of valid data

Methods

class

new_wrapped (flags, data, maxsize, offset, user_data, notify)

copy (offset, size)

get_sizes ()

is_span (mem2)

is_type (mem_type)

make_mapped (flags)

map (flags)

resize (offset, size)

share (offset, size)

unmap (info)

Details

class Gst.Memory

Gst.Memory is a lightweight refcounted object that wraps a region of memory. They are typically used to manage the data of a Gst.Buffer.

A Gst.Memory 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 None 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.

classmethod new_wrapped(flags, data, maxsize, offset, user_data, notify)[source]
Parameters:
Returns:

a new Gst.Memory.

Return type:

Gst.Memory or None

Allocate a new memory block that wraps the given data.

The prefix/padding must be filled with 0 if flags contains Gst.MemoryFlags.ZERO_PREFIXED and Gst.MemoryFlags.ZERO_PADDED respectively.

copy(offset, size)[source]
Parameters:
  • offset (int) – offset to copy from

  • size (int) – size to copy, or -1 to copy to the end of the memory region

Returns:

a new copy of self if the copy succeeded, None otherwise.

Return type:

Gst.Memory or None

Return a copy of size bytes from self 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.

get_sizes()[source]
Returns:

the current size of self

offset:

pointer to offset

maxsize:

pointer to maxsize

Return type:

(int, offset: int, maxsize: int)

Get the current size, offset and maxsize of self.

is_span(mem2)[source]
Parameters:

mem2 (Gst.Memory) – a Gst.Memory

Returns:

True if the memory is contiguous and of a common parent.

offset:

a pointer to a result offset

Return type:

(bool, offset: int)

Check if self 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 self and mem2 can be merged efficiently by performing Gst.Memory.share() on the parent object from the returned offset.

is_type(mem_type)[source]
Parameters:

mem_type (str) – a memory type

Returns:

True if self was allocated from an allocator for mem_type.

Return type:

bool

Check if self if allocated with an allocator for mem_type.

New in version 1.2.

make_mapped(flags)[source]
Parameters:

flags (Gst.MapFlags) – mapping flags

Returns:

a Gst.Memory object mapped with flags or None when a mapping is not possible.

info:

pointer for info

Return type:

(Gst.Memory or None, info: Gst.MapInfo)

Create a Gst.Memory object that is mapped with flags. If self is mappable with flags, this function returns the mapped self directly. Otherwise a mapped copy of self is returned.

This function takes ownership of old self and returns a reference to a new Gst.Memory.

map(flags)[source]
Parameters:

flags (Gst.MapFlags) – mapping flags

Returns:

True if the map operation was successful.

info:

pointer for info

Return type:

(bool, info: Gst.MapInfo)

Fill info with the pointer and sizes of the memory in self that can be accessed according to flags.

This function can return False for various reasons:

  • the memory backed by self 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 self is valid and until Gst.Memory.unmap() is called.

For each Gst.Memory.map() call, a corresponding Gst.Memory.unmap() call should be done.

resize(offset, size)[source]
Parameters:
  • offset (int) – a new offset

  • size (int) – a new size

Resize the memory region. self should be writable and offset + size should be less than the maxsize of self.

Gst.MemoryFlags.ZERO_PREFIXED and Gst.MemoryFlags.ZERO_PADDED will be cleared when offset or padding is increased respectively.

share(offset, size)[source]
Parameters:
  • offset (int) – offset to share from

  • size (int) – size to share, or -1 to share to the end of the memory region

Returns:

a new Gst.Memory.

Return type:

Gst.Memory

Return a shared copy of size bytes from self 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.

unmap(info)[source]
Parameters:

info (Gst.MapInfo) – a Gst.MapInfo

Release the memory obtained with Gst.Memory.map()