:right-sidebar: True BufferPool =================================================================== .. currentmodule:: gi.repository.Gst .. class:: BufferPool(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gst.Object`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` :Constructors: :: BufferPool(**properties) new() -> Gst.BufferPool Constructors ------------ .. rst-class:: interim-class .. class:: BufferPool :no-index: .. classmethod:: new() -> ~gi.repository.Gst.BufferPool Creates a new :obj:`~gi.repository.Gst.BufferPool` instance. Methods ------- .. rst-class:: interim-class .. class:: BufferPool :no-index: .. method:: acquire_buffer(params: ~gi.repository.Gst.BufferPoolAcquireParams | None = None) -> tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer] Acquires a buffer from ``pool``. ``buffer`` should point to a memory location that can hold a pointer to the new buffer. When the pool is empty, this function will by default block until a buffer is released into the pool again or when the pool is set to flushing or deactivated. ``params`` can contain optional parameters to influence the allocation. :param params: parameters. .. method:: config_add_option(config: ~gi.repository.Gst.Structure, option: str) -> None Enables the option in ``config``. This will instruct the ``bufferpool`` to enable the specified option on the buffers that it allocates. The options supported by ``pool`` can be retrieved with :func:`~gi.repository.Gst.BufferPool.get_options`. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration :param option: an option to add .. method:: config_get_allocator(config: ~gi.repository.Gst.Structure) -> tuple[bool, ~gi.repository.Gst.Allocator, ~gi.repository.Gst.AllocationParams] Gets the ``allocator`` and ``params`` from ``config``. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration .. method:: config_get_option(config: ~gi.repository.Gst.Structure, index: int) -> str | None Parses an available ``config`` and gets the option at ``index`` of the options API array. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration :param index: position in the option array to read .. method:: config_get_params(config: ~gi.repository.Gst.Structure) -> tuple[bool, ~gi.repository.Gst.Caps, int, int, int] Gets the configuration values from ``config``. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration .. method:: config_has_option(config: ~gi.repository.Gst.Structure, option: str) -> bool Checks if ``config`` contains ``option``. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration :param option: an option .. method:: config_n_options(config: ~gi.repository.Gst.Structure) -> int Retrieves the number of values currently stored in the options array of the ``config`` structure. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration .. method:: config_set_allocator(config: ~gi.repository.Gst.Structure, allocator: ~gi.repository.Gst.Allocator | None = None, params: ~gi.repository.Gst.AllocationParams | None = None) -> None Sets the ``allocator`` and ``params`` on ``config``. One of ``allocator`` and ``params`` can be :const:`None`, but not both. When ``allocator`` is :const:`None`, the default allocator of the pool will use the values in ``param`` to perform its allocation. When ``param`` is :const:`None`, the pool will use the provided ``allocator`` with its default :obj:`~gi.repository.Gst.AllocationParams`. A call to :func:`~gi.repository.Gst.BufferPool.set_config` can update the allocator and params with the values that it is able to do. Some pools are, for example, not able to operate with different allocators or cannot allocate with the values specified in ``params``. Use :func:`~gi.repository.Gst.BufferPool.get_config` to get the currently used values. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration :param allocator: a :obj:`~gi.repository.Gst.Allocator` :param params: :obj:`~gi.repository.Gst.AllocationParams` .. method:: config_set_params(config: ~gi.repository.Gst.Structure, caps: ~gi.repository.Gst.Caps | None, size: int, min_buffers: int, max_buffers: int) -> None Configures ``config`` with the given parameters. :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration :param caps: caps for the buffers :param size: the size of each buffer, not including prefix and padding :param min_buffers: the minimum amount of buffers to allocate. :param max_buffers: the maximum amount of buffers to allocate or 0 for unlimited. .. method:: config_validate_params(config: ~gi.repository.Gst.Structure, caps: ~gi.repository.Gst.Caps | None, size: int, min_buffers: int, max_buffers: int) -> bool Validates that changes made to ``config`` are still valid in the context of the expected parameters. This function is a helper that can be used to validate changes made by a pool to a config when :func:`~gi.repository.Gst.BufferPool.set_config` returns :const:`False`. This expects that ``caps`` haven't changed and that ``min_buffers`` aren't lower then what we initially expected. This does not check if options or allocator parameters are still valid, won't check if size have changed, since changing the size is valid to adapt padding. .. versionadded:: 1.4 :param config: a :obj:`~gi.repository.Gst.BufferPool` configuration :param caps: the excepted caps of buffers :param size: the expected size of each buffer, not including prefix and padding :param min_buffers: the expected minimum amount of buffers to allocate. :param max_buffers: the expect maximum amount of buffers to allocate or 0 for unlimited. .. method:: get_config() -> ~gi.repository.Gst.Structure Gets a copy of the current configuration of the pool. This configuration can be modified and used for the :func:`~gi.repository.Gst.BufferPool.set_config` call. .. method:: get_options() -> list[str] Gets a :const:`None` terminated array of string with supported bufferpool options for ``pool``. An option would typically be enabled with :func:`~gi.repository.Gst.BufferPool.config_add_option`. .. method:: has_option(option: str) -> bool Checks if the bufferpool supports ``option``. :param option: an option .. method:: is_active() -> bool Checks if ``pool`` is active. A pool can be activated with the :func:`~gi.repository.Gst.BufferPool.set_active` call. .. method:: release_buffer(buffer: ~gi.repository.Gst.Buffer) -> None Releases ``buffer`` to ``pool``. ``buffer`` should have previously been allocated from ``pool`` with :func:`~gi.repository.Gst.BufferPool.acquire_buffer`. This function is usually called automatically when the last ref on ``buffer`` disappears. :param buffer: a :obj:`~gi.repository.Gst.Buffer` .. method:: set_active(active: bool) -> bool Controls the active state of ``pool``. When the pool is inactive, new calls to :func:`~gi.repository.Gst.BufferPool.acquire_buffer` will return with :const:`~gi.repository.Gst.FlowReturn.FLUSHING`. Activating the bufferpool will preallocate all resources in the pool based on the configuration of the pool. Deactivating will free the resources again when there are no outstanding buffers. When there are outstanding buffers, they will be freed as soon as they are all returned to the pool. :param active: the new active state .. method:: set_config(config: ~gi.repository.Gst.Structure) -> bool Sets the configuration of the pool. If the pool is already configured, and the configuration hasn't changed, this function will return :const:`True`. If the pool is active, this method will return :const:`False` and active configuration will remain. Buffers allocated from this pool must be returned or else this function will do nothing and return :const:`False`. ``config`` is a :obj:`~gi.repository.Gst.Structure` that contains the configuration parameters for the pool. A default and mandatory set of parameters can be configured with :func:`~gi.repository.Gst.BufferPool.config_set_params`, :func:`~gi.repository.Gst.BufferPool.config_set_allocator` and :func:`~gi.repository.Gst.BufferPool.config_add_option`. If the parameters in ``config`` can not be set exactly, this function returns :const:`False` and will try to update as much state as possible. The new state can then be retrieved and refined with :func:`~gi.repository.Gst.BufferPool.get_config`. This function takes ownership of ``config``. :param config: a :obj:`~gi.repository.Gst.Structure` .. method:: set_flushing(flushing: bool) -> None Enables or disables the flushing state of a ``pool`` without freeing or allocating buffers. .. versionadded:: 1.4 :param flushing: whether to start or stop flushing Virtual Methods --------------- .. rst-class:: interim-class .. class:: BufferPool :no-index: .. method:: do_acquire_buffer(params: ~gi.repository.Gst.BufferPoolAcquireParams | None = None) -> tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer] Acquires a buffer from ``pool``. ``buffer`` should point to a memory location that can hold a pointer to the new buffer. When the pool is empty, this function will by default block until a buffer is released into the pool again or when the pool is set to flushing or deactivated. ``params`` can contain optional parameters to influence the allocation. :param params: parameters. .. method:: do_alloc_buffer(params: ~gi.repository.Gst.BufferPoolAcquireParams | None = None) -> tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer] Allocate a buffer. the default implementation allocates buffers from the configured memory allocator and with the configured parameters. All metadata that is present on the allocated buffer will be marked as ``GST_META_FLAG_POOLED`` and ``GST_META_FLAG_LOCKED`` and will not be removed from the buffer in ``GstBufferPoolClass``::reset_buffer. The buffer should have the ``GST_BUFFER_FLAG_TAG_MEMORY`` cleared. :param params: parameters. .. method:: do_flush_start() -> None Enter the flushing state. .. versionadded:: 1.4 .. method:: do_flush_stop() -> None Leave the flushing state. .. versionadded:: 1.4 .. method:: do_free_buffer(buffer: ~gi.repository.Gst.Buffer) -> None Free a buffer. The default implementation unrefs the buffer. :param buffer: the :obj:`~gi.repository.Gst.Buffer` to free .. method:: do_get_options() -> list[str] Gets a :const:`None` terminated array of string with supported bufferpool options for ``pool``. An option would typically be enabled with :func:`~gi.repository.Gst.BufferPool.config_add_option`. .. method:: do_release_buffer(buffer: ~gi.repository.Gst.Buffer) -> None Releases ``buffer`` to ``pool``. ``buffer`` should have previously been allocated from ``pool`` with :func:`~gi.repository.Gst.BufferPool.acquire_buffer`. This function is usually called automatically when the last ref on ``buffer`` disappears. :param buffer: a :obj:`~gi.repository.Gst.Buffer` .. method:: do_reset_buffer(buffer: ~gi.repository.Gst.Buffer) -> None Reset the buffer to its state when it was freshly allocated. The default implementation will clear the flags, timestamps and will remove the metadata without the ``GST_META_FLAG_POOLED`` flag (even the metadata with ``GST_META_FLAG_LOCKED``). If the ``GST_BUFFER_FLAG_TAG_MEMORY`` was set, this function can also try to restore the memory and clear the ``GST_BUFFER_FLAG_TAG_MEMORY`` again. :param buffer: the :obj:`~gi.repository.Gst.Buffer` to reset .. method:: do_set_config(config: ~gi.repository.Gst.Structure) -> bool Sets the configuration of the pool. If the pool is already configured, and the configuration hasn't changed, this function will return :const:`True`. If the pool is active, this method will return :const:`False` and active configuration will remain. Buffers allocated from this pool must be returned or else this function will do nothing and return :const:`False`. ``config`` is a :obj:`~gi.repository.Gst.Structure` that contains the configuration parameters for the pool. A default and mandatory set of parameters can be configured with :func:`~gi.repository.Gst.BufferPool.config_set_params`, :func:`~gi.repository.Gst.BufferPool.config_set_allocator` and :func:`~gi.repository.Gst.BufferPool.config_add_option`. If the parameters in ``config`` can not be set exactly, this function returns :const:`False` and will try to update as much state as possible. The new state can then be retrieved and refined with :func:`~gi.repository.Gst.BufferPool.get_config`. This function takes ownership of ``config``. :param config: a :obj:`~gi.repository.Gst.Structure` .. method:: do_start() -> bool Start the bufferpool. The default implementation will preallocate min-buffers buffers and put them in the queue. .. method:: do_stop() -> bool Stop the bufferpool. the default implementation will free the preallocated buffers. This function is called when all the buffers are returned to the pool. Fields ------ .. rst-class:: interim-class .. class:: BufferPool :no-index: .. attribute:: flushing Whether the pool is currently gathering back outstanding buffers .. attribute:: object The parent structure .. attribute:: priv