:right-sidebar: True Memory =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Memory(*args, **kwargs) :no-contents-entry: GstMemory is a lightweight refcounted object that wraps a region of memory. They are typically used to manage the data of a :obj:`~gi.repository.Gst.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 :func:`~gi.repository.Gst.Allocator.alloc` method call. When :const:`None` is used as the allocator, the default allocator will be used. New allocators can be registered with :func:`~gi.repository.Gst.Allocator.register`. Allocators are identified by name and can be retrieved with :func:`~gi.repository.Gst.Allocator.find`. :func:`~gi.repository.Gst.Allocator.set_default` can be used to change the default allocator. New memory can be created with :func:`~gi.repository.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 :func:`~gi.repository.Gst.Memory.get_sizes` and :func:`~gi.repository.Gst.Memory.resize` respectively. Getting access to the data of the memory is performed with :func:`~gi.repository.Gst.Memory.map`. The call will return a pointer to offset bytes into the region of memory. After the memory access is completed, :func:`~gi.repository.Gst.Memory.unmap` should be called. Memory can be copied with :func:`~gi.repository.Gst.Memory.copy`, which will return a writable copy. :func:`~gi.repository.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 :func:`~gi.repository.Gst.Memory.is_span` returns :const:`True`. Constructors ------------ .. rst-class:: interim-class .. class:: Memory :no-index: .. classmethod:: new_wrapped(flags: ~gi.repository.Gst.MemoryFlags, data: list[int], maxsize: int, offset: int, user_data: ~typing.Any = None, notify: ~typing.Callable[[~typing.Any], None] | None = None) -> ~gi.repository.Gst.Memory | None Allocate a new memory block that wraps the given ``data``\. The prefix/padding must be filled with 0 if ``flags`` contains ``GST_MEMORY_FLAG_ZERO_PREFIXED`` and ``GST_MEMORY_FLAG_ZERO_PADDED`` respectively. :param flags: :obj:`~gi.repository.Gst.MemoryFlags` :param data: data to wrap :param maxsize: allocated size of ``data`` :param offset: offset in ``data`` :param user_data: user_data :param notify: called with ``user_data`` when the memory is freed Methods ------- .. rst-class:: interim-class .. class:: Memory :no-index: .. method:: get_sizes() -> tuple[int, int, int] Get the current ``size``\, ``offset`` and ``maxsize`` of ``mem``\. .. method:: is_span(mem2: ~gi.repository.Gst.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`` and ``mem2`` can be merged efficiently by performing :func:`~gi.repository.Gst.Memory.share` on the parent object from the returned ``offset``\. :param mem2: a :obj:`~gi.repository.Gst.Memory` .. method:: is_type(mem_type: str) -> bool Check if ``mem`` if allocated with an allocator for ``mem_type``\. .. versionadded:: 1.2 :param mem_type: a memory type .. method:: make_mapped(flags: ~gi.repository.Gst.MapFlags) -> tuple[~gi.repository.Gst.Memory | None, ~gi.repository.Gst.MapInfo] Create a :obj:`~gi.repository.Gst.Memory` 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 :obj:`~gi.repository.Gst.Memory`\. :param flags: mapping flags .. method:: map(flags: ~gi.repository.Gst.MapFlags) -> tuple[bool, ~gi.repository.Gst.MapInfo] Fill ``info`` with the pointer and sizes of the memory in ``mem`` that can be accessed according to ``flags``\. This function can return :const:`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 :func:`~gi.repository.Gst.Memory.unmap` is called. For each :func:`~gi.repository.Gst.Memory.map` call, a corresponding :func:`~gi.repository.Gst.Memory.unmap` call should be done. :param flags: mapping flags .. method:: resize(offset: int, size: int) -> None 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. :param offset: a new offset :param size: a new size .. method:: share(offset: int, size: int) -> ~gi.repository.Gst.Memory 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. :param offset: offset to share from :param size: size to share, or -1 to share to the end of the memory region .. method:: unmap(info: ~gi.repository.Gst.MapInfo) -> None Release the memory obtained with :func:`~gi.repository.Gst.Memory.map` :param info: a :obj:`~gi.repository.Gst.MapInfo` Fields ------ .. rst-class:: interim-class .. class:: Memory :no-index: .. attribute:: align The alignment of the memory .. attribute:: allocator Pointer to the :obj:`~gi.repository.Gst.Allocator` .. attribute:: maxsize The maximum size allocated .. attribute:: mini_object Parent structure .. attribute:: offset The offset where valid data starts .. attribute:: parent Parent memory block .. attribute:: size The size of valid data