:right-sidebar: True Buffer =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Buffer(**kwargs) :no-contents-entry: Buffers are the basic unit of data transfer in GStreamer. They contain the timing and offset along with other arbitrary metadata that is associated with the :obj:`~gi.repository.Gst.Memory` blocks that the buffer contains. Buffers are usually created with :func:`~gi.repository.Gst.Buffer.new`. After a buffer has been created one will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane. .. code-block:: C :dedent: GstBuffer *buffer; GstMemory *memory; gint size, width, height, bpp; ... size = width * height * bpp; buffer = gst_buffer_new (); memory = gst_allocator_alloc (NULL, size, NULL); gst_buffer_insert_memory (buffer, -1, memory); ... Alternatively, use :func:`~gi.repository.Gst.Buffer.new_allocate` to create a buffer with preallocated data of a given size. Buffers can contain a list of :obj:`~gi.repository.Gst.Memory` objects. You can retrieve how many memory objects with :func:`~gi.repository.Gst.Buffer.n_memory` and you can get a pointer to memory with :func:`~gi.repository.Gst.Buffer.peek_memory` A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to ``GST_CLOCK_TIME_NONE``). Whenever a meaningful value can be given for these, they should be set. The timestamps and duration are measured in nanoseconds (they are :obj:`~gi.repository.Gst.ClockTime` values). The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing. A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the preceding CAPS event). Either or both can be set to ``GST_BUFFER_OFFSET_NONE``. gst_buffer_ref() is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller has the only reference to the buffer. To efficiently create a smaller buffer out of an existing one, you can use :func:`~gi.repository.Gst.Buffer.copy_region`. This method tries to share the memory objects between the two buffers. If a plug-in wants to modify the buffer data or metadata in-place, it should first obtain a buffer that is safe to modify by using :func:`~gi.repository.Gst.buffer_make_writable`. This function is optimized so that a copy will only be made when it is necessary. Several flags of the buffer can be set and unset with the :func:`~gi.repository.Gst.BUFFER_FLAG_SET` and :func:`~gi.repository.Gst.BUFFER_FLAG_UNSET` macros. Use :func:`~gi.repository.Gst.BUFFER_FLAG_IS_SET` to test if a certain :obj:`~gi.repository.Gst.BufferFlags` flag is set. Buffers can be efficiently merged into a larger buffer with :func:`~gi.repository.Gst.Buffer.append`. Copying of memory will only be done when absolutely needed. Arbitrary extra metadata can be set on a buffer with :func:`~gi.repository.Gst.Buffer.add_meta`. Metadata can be retrieved with :func:`~gi.repository.Gst.Buffer.get_meta`. See also :obj:`~gi.repository.Gst.Meta`\. An element should either unref the buffer or push it out on a src pad using :func:`~gi.repository.Gst.Pad.push` (see :obj:`~gi.repository.Gst.Pad`\). Buffers are usually freed by unreffing them with gst_buffer_unref(). When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a :obj:`~gi.repository.Gst.BufferPool` will be returned to the pool when the refcount drops to 0. The :obj:`~gi.repository.Gst.ParentBufferMeta` is a meta which can be attached to a :obj:`~gi.repository.Gst.Buffer` to hold a reference to another buffer that is only released when the child :obj:`~gi.repository.Gst.Buffer` is released. Typically, :obj:`~gi.repository.Gst.ParentBufferMeta` is used when the child buffer is directly using the :obj:`~gi.repository.Gst.Memory` of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the :obj:`~gi.repository.Gst.Memory` is available for re-use. (Since: 1.6) Constructors ------------ .. rst-class:: interim-class .. class:: Buffer :no-index: .. classmethod:: new() -> ~gi.repository.Gst.Buffer Creates a newly allocated buffer without any data. .. classmethod:: new_allocate(allocator: ~gi.repository.Gst.Allocator | None, size: int, params: ~gi.repository.Gst.AllocationParams | None = None) -> ~gi.repository.Gst.Buffer | None Tries to create a newly allocated buffer with data of the given size and extra parameters from ``allocator``\. If the requested amount of memory can't be allocated, :const:`None` will be returned. The allocated buffer memory is not cleared. When ``allocator`` is :const:`None`, the default memory allocator will be used. Note that when ``size`` == 0, the buffer will not have memory associated with it. :param allocator: the :obj:`~gi.repository.Gst.Allocator` to use, or :const:`None` to use the default allocator :param size: the size in bytes of the new buffer's data. :param params: optional parameters .. classmethod:: new_memdup(data: list[int]) -> ~gi.repository.Gst.Buffer Creates a new buffer of size ``size`` and fills it with a copy of ``data``\. .. versionadded:: 1.20 :param data: data to copy into new buffer .. classmethod:: new_wrapped(data: list[int]) -> ~gi.repository.Gst.Buffer Creates a new buffer that wraps the given ``data``\. The memory will be freed with :func:`~gi.repository.GLib.free` and will be marked writable. :param data: data to wrap .. classmethod:: new_wrapped_bytes(bytes: ~gi.repository.GLib.Bytes) -> ~gi.repository.Gst.Buffer Creates a new :obj:`~gi.repository.Gst.Buffer` that wraps the given ``bytes``\. The data inside ``bytes`` cannot be :const:`None` and the resulting buffer will be marked as read only. .. versionadded:: 1.16 :param bytes: a :obj:`~gi.repository.GLib.Bytes` to wrap .. classmethod:: new_wrapped_full(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.Buffer Allocates a new buffer that wraps the given memory. ``data`` must point to ``maxsize`` of memory, the wrapped buffer will have the region from ``offset`` and ``size`` visible. When the buffer is destroyed, ``notify`` will be called with ``user_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:: Buffer :no-index: .. method:: add_custom_meta(name: str) -> ~gi.repository.Gst.CustomMeta | None Creates and adds a :obj:`~gi.repository.Gst.CustomMeta` for the desired ``name``\. ``name`` must have been successfully registered with :func:`~gi.repository.Gst.Meta.register_custom`. .. versionadded:: 1.20 :param name: the registered name of the desired custom meta .. method:: add_meta(info: ~gi.repository.Gst.MetaInfo, params: ~typing.Any = None) -> ~gi.repository.Gst.Meta | None Adds metadata for ``info`` to ``buffer`` using the parameters in ``params``\. :param info: a :obj:`~gi.repository.Gst.MetaInfo` :param params: params for ``info`` .. method:: add_parent_buffer_meta(ref: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.ParentBufferMeta | None Adds a :obj:`~gi.repository.Gst.ParentBufferMeta` to ``buffer`` that holds a reference on ``ref`` until the buffer is freed. .. versionadded:: 1.6 :param ref: a :obj:`~gi.repository.Gst.Buffer` to ref .. method:: add_protection_meta(info: ~gi.repository.Gst.Structure) -> ~gi.repository.Gst.ProtectionMeta Attaches protection metadata to a :obj:`~gi.repository.Gst.Buffer`\. .. versionadded:: 1.6 :param info: a :obj:`~gi.repository.Gst.Structure` holding cryptographic information relating to the sample contained in ``buffer``\. This function takes ownership of ``info``\. .. method:: add_reference_timestamp_meta(reference: ~gi.repository.Gst.Caps, timestamp: int, duration: int) -> ~gi.repository.Gst.ReferenceTimestampMeta | None Adds a :obj:`~gi.repository.Gst.ReferenceTimestampMeta` to ``buffer`` that holds a ``timestamp`` and optionally ``duration`` based on a specific timestamp ``reference``\. See the documentation of :obj:`~gi.repository.Gst.ReferenceTimestampMeta` for details. .. versionadded:: 1.14 :param reference: identifier for the timestamp reference. :param timestamp: timestamp :param duration: duration, or :const:`~gi.repository.Gst.CLOCK_TIME_NONE` .. method:: append(buf2: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.Buffer Appends all the memory from ``buf2`` to ``buf1``\. The result buffer will contain a concatenation of the memory of ``buf1`` and ``buf2``\. :param buf2: the second source :obj:`~gi.repository.Gst.Buffer` to append. .. method:: append_memory(mem: ~gi.repository.Gst.Memory) -> None Appends the memory block ``mem`` to ``buffer``\. This function takes ownership of ``mem`` and thus doesn't increase its refcount. This function is identical to :func:`~gi.repository.Gst.Buffer.insert_memory` with an index of -1. See :func:`~gi.repository.Gst.Buffer.insert_memory` for more details. :param mem: a :obj:`~gi.repository.Gst.Memory`\. .. method:: append_region(buf2: ~gi.repository.Gst.Buffer, offset: int, size: int) -> ~gi.repository.Gst.Buffer Appends ``size`` bytes at ``offset`` from ``buf2`` to ``buf1``\. The result buffer will contain a concatenation of the memory of ``buf1`` and the requested region of ``buf2``\. :param buf2: the second source :obj:`~gi.repository.Gst.Buffer` to append. :param offset: the offset in ``buf2`` :param size: the size or -1 of ``buf2`` .. method:: extract(offset: int) -> ~typing.Tuple[int, list[int]] Copies ``size`` bytes starting from ``offset`` in ``buffer`` to ``dest``\. :param offset: the offset to extract .. method:: extract_dup(offset: int, size: int) -> list[int] Extracts a copy of at most ``size`` bytes the data at ``offset`` into newly-allocated memory. ``dest`` must be freed using :func:`~gi.repository.GLib.free` when done. .. versionadded:: 1.0.10 :param offset: the offset to extract :param size: the size to extract .. method:: fill(offset: int, src: list[int]) -> int Copies ``size`` bytes from ``src`` to ``buffer`` at ``offset``\. :param offset: the offset to fill :param src: the source address .. method:: find_memory(offset: int, size: int) -> ~typing.Tuple[bool, int, int, int] Finds the memory blocks that span ``size`` bytes starting from ``offset`` in ``buffer``\. When this function returns :const:`True`, ``idx`` will contain the index of the first memory block where the byte for ``offset`` can be found and ``length`` contains the number of memory blocks containing the ``size`` remaining bytes. ``skip`` contains the number of bytes to skip in the memory block at ``idx`` to get to the byte for ``offset``\. ``size`` can be -1 to get all the memory blocks after ``idx``\. :param offset: an offset :param size: a size .. method:: foreach_meta(func: ~typing.Callable[[~gi.repository.Gst.Buffer, ~typing.Any], ~typing.Tuple[bool, ~gi.repository.Gst.Meta | None]], user_data: ~typing.Any = None) -> bool Calls ``func`` with ``user_data`` for each meta in ``buffer``\. ``func`` can modify the passed meta pointer or its contents. The return value of ``func`` defines if this function returns or if the remaining metadata items in the buffer should be skipped. :param func: a :obj:`~gi.repository.Gst.BufferForeachMetaFunc` to call :param user_data: user data passed to ``func`` .. method:: get_all_memory() -> ~gi.repository.Gst.Memory | None Gets all the memory blocks in ``buffer``\. The memory blocks will be merged into one large :obj:`~gi.repository.Gst.Memory`\. .. method:: get_custom_meta(name: str) -> ~gi.repository.Gst.CustomMeta | None Finds the first :obj:`~gi.repository.Gst.CustomMeta` on ``buffer`` for the desired ``name``\. .. versionadded:: 1.20 :param name: the registered name of the custom meta to retrieve. .. method:: get_flags() -> ~gi.repository.Gst.BufferFlags Gets the :obj:`~gi.repository.Gst.BufferFlags` flags set on this buffer. .. versionadded:: 1.10 .. classmethod:: get_max_memory() -> int Gets the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function. When more memory blocks are added, existing memory blocks will be merged together to make room for the new block. .. versionadded:: 1.2 .. method:: get_memory(idx: int) -> ~gi.repository.Gst.Memory | None Gets the memory block at index ``idx`` in ``buffer``\. :param idx: an index .. method:: get_memory_range(idx: int, length: int) -> ~gi.repository.Gst.Memory | None Gets ``length`` memory blocks in ``buffer`` starting at ``idx``\. The memory blocks will be merged into one large :obj:`~gi.repository.Gst.Memory`\. If ``length`` is -1, all memory starting from ``idx`` is merged. :param idx: an index :param length: a length .. method:: get_meta(api: ~gobject.GType) -> ~gi.repository.Gst.Meta | None Gets the metadata for ``api`` on buffer. When there is no such metadata, :const:`None` is returned. If multiple metadata with the given ``api`` are attached to this buffer only the first one is returned. To handle multiple metadata with a given API use :func:`~gi.repository.Gst.Buffer.iterate_meta` or :func:`~gi.repository.Gst.Buffer.foreach_meta` instead and check the ``meta->info.api`` member for the API type. :param api: the :obj:`~gi.repository.GObject.Type` of an API .. method:: get_n_meta(api_type: ~gobject.GType) -> int .. versionadded:: 1.14 :param api_type: the :obj:`~gi.repository.GObject.Type` of an API .. method:: get_reference_timestamp_meta(reference: ~gi.repository.Gst.Caps | None = None) -> ~gi.repository.Gst.ReferenceTimestampMeta | None Finds the first :obj:`~gi.repository.Gst.ReferenceTimestampMeta` on ``buffer`` that conforms to ``reference``\. Conformance is tested by checking if the meta's reference is a subset of ``reference``\. Buffers can contain multiple :obj:`~gi.repository.Gst.ReferenceTimestampMeta` metadata items. .. versionadded:: 1.14 :param reference: a reference :obj:`~gi.repository.Gst.Caps` .. method:: get_size() -> int Gets the total size of the memory blocks in ``buffer``\. .. method:: get_sizes() -> ~typing.Tuple[int, int, int] Gets the total size of the memory blocks in ``buffer``\. When not :const:`None`, ``offset`` will contain the offset of the data in the first memory block in ``buffer`` and ``maxsize`` will contain the sum of the size and ``offset`` and the amount of extra padding on the last memory block. ``offset`` and ``maxsize`` can be used to resize the buffer memory blocks with :func:`~gi.repository.Gst.Buffer.resize`. .. method:: get_sizes_range(idx: int, length: int) -> ~typing.Tuple[int, int, int] Gets the total size of ``length`` memory blocks stating from ``idx`` in ``buffer``\. When not :const:`None`, ``offset`` will contain the offset of the data in the memory block in ``buffer`` at ``idx`` and ``maxsize`` will contain the sum of the size and ``offset`` and the amount of extra padding on the memory block at ``idx`` + ``length`` -1. ``offset`` and ``maxsize`` can be used to resize the buffer memory blocks with :func:`~gi.repository.Gst.Buffer.resize_range`. :param idx: an index :param length: a length .. method:: has_flags(flags: ~gi.repository.Gst.BufferFlags) -> bool Gives the status of a specific flag on a buffer. .. versionadded:: 1.10 :param flags: the :obj:`~gi.repository.Gst.BufferFlags` flag to check. .. method:: insert_memory(idx: int, mem: ~gi.repository.Gst.Memory) -> None Inserts the memory block ``mem`` into ``buffer`` at ``idx``\. This function takes ownership of ``mem`` and thus doesn't increase its refcount. Only :func:`~gi.repository.Gst.Buffer.get_max_memory` can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory. :param idx: the index to add the memory at, or -1 to append it to the end :param mem: a :obj:`~gi.repository.Gst.Memory`\. .. method:: is_all_memory_writable() -> bool Checks if all memory blocks in ``buffer`` are writable. Note that this function does not check if ``buffer`` is writable, use :func:`~gi.repository.Gst.buffer_is_writable` to check that if needed. .. versionadded:: 1.4 .. method:: is_memory_range_writable(idx: int, length: int) -> bool Checks if ``length`` memory blocks in ``buffer`` starting from ``idx`` are writable. ``length`` can be -1 to check all the memory blocks after ``idx``\. Note that this function does not check if ``buffer`` is writable, use :func:`~gi.repository.Gst.buffer_is_writable` to check that if needed. .. versionadded:: 1.4 :param idx: an index :param length: a length, should not be 0 .. method:: map(flags: ~gi.repository.Gst.MapFlags) -> ~typing.Tuple[bool, ~gi.repository.Gst.MapInfo] Fills ``info`` with the :obj:`~gi.repository.Gst.MapInfo` of all merged memory blocks in ``buffer``\. ``flags`` describe the desired access of the memory. When ``flags`` is ``GST_MAP_WRITE``, ``buffer`` should be writable (as returned from :func:`~gi.repository.Gst.buffer_is_writable`). When ``buffer`` is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy. The memory in ``info`` should be unmapped with :func:`~gi.repository.Gst.Buffer.unmap` after usage. :param flags: flags for the mapping .. method:: map_range(idx: int, length: int, flags: ~gi.repository.Gst.MapFlags) -> ~typing.Tuple[bool, ~gi.repository.Gst.MapInfo] Fills ``info`` with the :obj:`~gi.repository.Gst.MapInfo` of ``length`` merged memory blocks starting at ``idx`` in ``buffer``\. When ``length`` is -1, all memory blocks starting from ``idx`` are merged and mapped. ``flags`` describe the desired access of the memory. When ``flags`` is ``GST_MAP_WRITE``, ``buffer`` should be writable (as returned from :func:`~gi.repository.Gst.buffer_is_writable`). When ``buffer`` is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy. The memory in ``info`` should be unmapped with :func:`~gi.repository.Gst.Buffer.unmap` after usage. :param idx: an index :param length: a length :param flags: flags for the mapping .. method:: memcmp(offset: int, mem: list[int]) -> int Compares ``size`` bytes starting from ``offset`` in ``buffer`` with the memory in ``mem``\. :param offset: the offset in ``buffer`` :param mem: the memory to compare .. method:: memset(offset: int, val: int, size: int) -> int Fills ``buf`` with ``size`` bytes with ``val`` starting from ``offset``\. :param offset: the offset in ``buffer`` :param val: the value to set :param size: the size to set .. method:: n_memory() -> int Gets the amount of memory blocks that this buffer has. This amount is never larger than what :func:`~gi.repository.Gst.Buffer.get_max_memory` returns. .. method:: peek_memory(idx: int) -> ~gi.repository.Gst.Memory | None Gets the memory block at ``idx`` in ``buffer``\. The memory block stays valid until the memory block in ``buffer`` is removed, replaced or merged, typically with any call that modifies the memory in ``buffer``\. :param idx: an index .. method:: prepend_memory(mem: ~gi.repository.Gst.Memory) -> None Prepends the memory block ``mem`` to ``buffer``\. This function takes ownership of ``mem`` and thus doesn't increase its refcount. This function is identical to :func:`~gi.repository.Gst.Buffer.insert_memory` with an index of 0. See :func:`~gi.repository.Gst.Buffer.insert_memory` for more details. :param mem: a :obj:`~gi.repository.Gst.Memory`\. .. method:: remove_all_memory() -> None Removes all the memory blocks in ``buffer``\. .. method:: remove_memory(idx: int) -> None Removes the memory block in ``b`` at index ``i``\. :param idx: an index .. method:: remove_memory_range(idx: int, length: int) -> None Removes ``length`` memory blocks in ``buffer`` starting from ``idx``\. ``length`` can be -1, in which case all memory starting from ``idx`` is removed. :param idx: an index :param length: a length .. method:: remove_meta(meta: ~gi.repository.Gst.Meta) -> bool Removes the metadata for ``meta`` on ``buffer``\. :param meta: a :obj:`~gi.repository.Gst.Meta` .. method:: replace_all_memory(mem: ~gi.repository.Gst.Memory) -> None Replaces all memory in ``buffer`` with ``mem``\. :param mem: a :obj:`~gi.repository.Gst.Memory` .. method:: replace_memory(idx: int, mem: ~gi.repository.Gst.Memory) -> None Replaces the memory block at index ``idx`` in ``buffer`` with ``mem``\. :param idx: an index :param mem: a :obj:`~gi.repository.Gst.Memory` .. method:: replace_memory_range(idx: int, length: int, mem: ~gi.repository.Gst.Memory) -> None Replaces ``length`` memory blocks in ``buffer`` starting at ``idx`` with ``mem``\. If ``length`` is -1, all memory starting from ``idx`` will be removed and replaced with ``mem``\. ``buffer`` should be writable. :param idx: an index :param length: a length, should not be 0 :param mem: a :obj:`~gi.repository.Gst.Memory` .. method:: resize(offset: int, size: int) -> None Sets the offset and total size of the memory blocks in ``buffer``\. :param offset: the offset adjustment :param size: the new size or -1 to just adjust the offset .. method:: resize_range(idx: int, length: int, offset: int, size: int) -> bool Sets the total size of the ``length`` memory blocks starting at ``idx`` in ``buffer`` :param idx: an index :param length: a length :param offset: the offset adjustment :param size: the new size or -1 to just adjust the offset .. method:: set_flags(flags: ~gi.repository.Gst.BufferFlags) -> bool Sets one or more buffer flags on a buffer. .. versionadded:: 1.10 :param flags: the :obj:`~gi.repository.Gst.BufferFlags` to set. .. method:: set_size(size: int) -> None Sets the total size of the memory blocks in ``buffer``\. :param size: the new size .. method:: unmap(info: ~gi.repository.Gst.MapInfo) -> None Releases the memory previously mapped with :func:`~gi.repository.Gst.Buffer.map`. :param info: a :obj:`~gi.repository.Gst.MapInfo` .. method:: unset_flags(flags: ~gi.repository.Gst.BufferFlags) -> bool Clears one or more buffer flags. .. versionadded:: 1.10 :param flags: the :obj:`~gi.repository.Gst.BufferFlags` to clear Fields ------ .. rst-class:: interim-class .. class:: Buffer :no-index: .. attribute:: dts Decoding timestamp of the buffer, can be ``GST_CLOCK_TIME_NONE`` when the dts is not known or relevant. The dts contains the timestamp when the media should be processed. .. attribute:: duration Duration in time of the buffer data, can be ``GST_CLOCK_TIME_NONE`` when the duration is not known or relevant. .. attribute:: mini_object The parent structure .. attribute:: offset A media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer. .. attribute:: offset_end The last offset contained in this buffer. It has the same format as ``offset``\. .. attribute:: pool Pointer to the pool owner of the buffer .. attribute:: pts Presentation timestamp of the buffer, can be ``GST_CLOCK_TIME_NONE`` when the pts is not known or relevant. The pts contains the timestamp when the media should be presented to the user.