:right-sidebar: True

BufferList
===================================================================

.. currentmodule:: gi.repository.Gst





.. class:: BufferList(**kwargs)
   :no-contents-entry:






Buffer lists are an object containing a list of buffers.

Buffer lists are created with :func:`~gi.repository.Gst.BufferList.new` and filled with data
using :func:`~gi.repository.Gst.BufferList.insert`.

Buffer lists can be pushed on a srcpad with :func:`~gi.repository.Gst.Pad.push_list`. This is
interesting when multiple buffers need to be pushed in one go because it
can reduce the amount of overhead for pushing each buffer individually.


Constructors
------------

.. rst-class:: interim-class

.. class:: BufferList
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gst.BufferList

      Creates a new, empty :obj:`~gi.repository.Gst.BufferList`\.









   .. classmethod:: new_sized(size: int) -> ~gi.repository.Gst.BufferList

      Creates a new, empty :obj:`~gi.repository.Gst.BufferList`\. The list will have ``size`` space
      preallocated so that memory reallocations can be avoided.






      :param size: an initial reserved size








Methods
-------

.. rst-class:: interim-class

.. class:: BufferList
   :no-index:


   .. method:: calculate_size() -> int

      Calculates the size of the data contained in ``list`` by adding the
      size of all buffers.



      .. versionadded:: 1.14








   .. method:: foreach(func: ~collections.abc.Callable[[~gi.repository.Gst.Buffer | None, int, ~typing.Any], tuple[bool, ~gi.repository.Gst.Buffer | None]], user_data: ~typing.Any = None) -> bool

      Calls ``func`` with ``data`` for each buffer in ``list``\.

      ``func`` can modify the passed buffer pointer or its contents. The return value
      of ``func`` defines if this function returns or if the remaining buffers in
      the list should be skipped.







      :param func: a :obj:`~gi.repository.Gst.BufferListFunc` to call

      :param user_data: user data passed to ``func``




   .. method:: get(idx: int) -> ~gi.repository.Gst.Buffer

      Gets the buffer at ``idx``\.

      You must make sure that ``idx`` does not exceed the number of
      buffers available.







      :param idx: the index




   .. method:: get_writable(idx: int) -> ~gi.repository.Gst.Buffer

      Gets the buffer at ``idx``\, ensuring it is a writable buffer.

      You must make sure that ``idx`` does not exceed the number of
      buffers available.



      .. versionadded:: 1.14





      :param idx: the index




   .. method:: insert(idx: int, buffer: ~gi.repository.Gst.Buffer) -> None

      Inserts ``buffer`` at ``idx`` in ``list``\. Other buffers are moved to make room for
      this new buffer.

      A -1 value for ``idx`` will append the buffer at the end.







      :param idx: the index

      :param buffer: a :obj:`~gi.repository.Gst.Buffer`




   .. method:: is_writable() -> bool

      Tests if you can safely modify ``list``\. It is only safe to modify buffer list when
      there is only one owner of the buffer list - ie, the object is writable.










   .. method:: length() -> int

      Returns the number of buffers in ``list``\.










   .. method:: make_writable() -> ~gi.repository.Gst.BufferList

      Returns a writable copy of ``list``\.

      If there is only one reference count on ``list``\, the caller must be the owner,
      and so this function will return the buffer list object unchanged. If on the other
      hand there is more than one reference on the object, a new buffer list object will
      be returned. The caller's reference on ``list`` will be removed, and instead the
      caller will own a reference to the returned object.

      In short, this function unrefs the buffer_list in the argument and refs the buffer list
      that it returns. Don't access the argument after calling this function. See
      also: :func:`~gi.repository.Gst.BufferList.ref`.










   .. method:: remove(idx: int, length: int) -> None

      Removes ``length`` buffers starting from ``idx`` in ``list``\. The following buffers
      are moved to close the gap.







      :param idx: the index

      :param length: the amount to remove




   .. classmethod:: replace(old_list: ~gi.repository.Gst.BufferList | None = None, new_list: ~gi.repository.Gst.BufferList | None = None) -> tuple[bool, ~gi.repository.Gst.BufferList | None]

      Modifies a pointer to a :obj:`~gi.repository.Gst.BufferList` to point to a different
      :obj:`~gi.repository.Gst.BufferList`\. The modification is done atomically (so this is useful for
      ensuring thread safety in some cases), and the reference counts are updated
      appropriately (the old buffer list is unreffed, the new is reffed).

      Either ``new_list`` or the :obj:`~gi.repository.Gst.BufferList` pointed to by ``old_list`` may be :const:`None`.



      .. versionadded:: 1.16





      :param old_list: pointer to a pointer to a
         :obj:`~gi.repository.Gst.BufferList` to be replaced.

      :param new_list: pointer to a :obj:`~gi.repository.Gst.BufferList` that
         will replace the buffer list pointed to by ``old_list``\.




   .. classmethod:: take(old_list: ~gi.repository.Gst.BufferList, new_list: ~gi.repository.Gst.BufferList | None = None) -> tuple[bool, ~gi.repository.Gst.BufferList]

      Modifies a pointer to a :obj:`~gi.repository.Gst.BufferList` to point to a different
      :obj:`~gi.repository.Gst.BufferList`\. This function is similar to :func:`~gi.repository.Gst.BufferList.replace` except
      that it takes ownership of ``new_list``\.



      .. versionadded:: 1.16





      :param old_list: pointer to a pointer to a :obj:`~gi.repository.Gst.BufferList`
         to be replaced.

      :param new_list: pointer to a :obj:`~gi.repository.Gst.BufferList`
         that will replace the bufferlist pointed to by ``old_list``\.