: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` A :obj:`~gi.repository.Gst.BufferPool` is an object that can be used to pre-allocate and recycle buffers of the same size and with the same properties. A :obj:`~gi.repository.Gst.BufferPool` is created with :func:`~gi.repository.Gst.BufferPool.new`. Once a pool is created, it needs to be configured. A call to :func:`~gi.repository.Gst.BufferPool.get_config` returns the current configuration structure from the pool. With :func:`~gi.repository.Gst.BufferPool.config_set_params` and :func:`~gi.repository.Gst.BufferPool.config_set_allocator` the bufferpool parameters and allocator can be configured. Other properties can be configured in the pool depending on the pool implementation. A bufferpool can have extra options that can be enabled with :func:`~gi.repository.Gst.BufferPool.config_add_option`. The available options can be retrieved with :func:`~gi.repository.Gst.BufferPool.get_options`. Some options allow for additional configuration properties to be set. After the configuration structure has been configured, :func:`~gi.repository.Gst.BufferPool.set_config` updates the configuration in the pool. This can fail when the configuration structure is not accepted. After the pool has been configured, it can be activated with :func:`~gi.repository.Gst.BufferPool.set_active`. This will preallocate the configured resources in the pool. When the pool is active, :func:`~gi.repository.Gst.BufferPool.acquire_buffer` can be used to retrieve a buffer from the pool. Buffers allocated from a bufferpool will automatically be returned to the pool with :func:`~gi.repository.Gst.BufferPool.release_buffer` when their refcount drops to 0. The bufferpool can be deactivated again with :func:`~gi.repository.Gst.BufferPool.set_active`. All further :func:`~gi.repository.Gst.BufferPool.acquire_buffer` calls will return an error. When all buffers are returned to the pool they will be freed. 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) -> ~typing.Tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer | None] 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. .. classmethod:: config_add_option(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 option: an option to add .. classmethod:: config_get_allocator() -> ~typing.Tuple[bool, ~gi.repository.Gst.Allocator | None, ~gi.repository.Gst.AllocationParams] Gets the ``allocator`` and ``params`` from ``config``\. .. classmethod:: config_get_option(index: int) -> str | None Parses an available ``config`` and gets the option at ``index`` of the options API array. :param index: position in the option array to read .. classmethod:: config_get_params() -> ~typing.Tuple[bool, ~gi.repository.Gst.Caps | None, int, int, int] Gets the configuration values from ``config``\. .. classmethod:: config_has_option(option: str) -> bool Checks if ``config`` contains ``option``\. :param option: an option .. classmethod:: config_n_options() -> int Retrieves the number of values currently stored in the options array of the ``config`` structure. .. classmethod:: config_set_allocator(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 allocator: a :obj:`~gi.repository.Gst.Allocator` :param params: :obj:`~gi.repository.Gst.AllocationParams` .. classmethod:: config_set_params(caps: ~gi.repository.Gst.Caps | None, size: int, min_buffers: int, max_buffers: int) -> None Configures ``config`` with the given parameters. :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. .. classmethod:: config_validate_params(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 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:: do_acquire_buffer(self, params: ~gi.repository.Gst.BufferPoolAcquireParams | None = None) -> ~typing.Tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer | None] :param params: .. method:: do_alloc_buffer(self, params: ~gi.repository.Gst.BufferPoolAcquireParams | None = None) -> ~typing.Tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer | None] :param params: .. method:: do_flush_start(self) -> None .. method:: do_flush_stop(self) -> None .. method:: do_free_buffer(self, buffer: ~gi.repository.Gst.Buffer) -> None :param buffer: .. method:: do_get_options(self) -> list[str] .. method:: do_release_buffer(self, buffer: ~gi.repository.Gst.Buffer) -> None :param buffer: .. method:: do_reset_buffer(self, buffer: ~gi.repository.Gst.Buffer) -> None :param buffer: .. method:: do_set_config(self, config: ~gi.repository.Gst.Structure) -> bool :param config: .. method:: do_start(self) -> bool .. method:: do_stop(self) -> bool .. 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) -> ~typing.Tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer | None] 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) -> ~typing.Tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Buffer | None] The type of the None singleton. :param params: parameters. .. method:: do_flush_start() -> None The type of the None singleton. .. versionadded:: 1.4 .. method:: do_flush_stop() -> None The type of the None singleton. .. versionadded:: 1.4 .. method:: do_free_buffer(buffer: ~gi.repository.Gst.Buffer) -> None The type of the None singleton. :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 The type of the None singleton. :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 The type of the None singleton. .. method:: do_stop() -> bool The type of the None singleton. 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