:right-sidebar: True

FlowCombiner
===================================================================

.. currentmodule:: gi.repository.GstBase


.. versionadded:: 1.4




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






Utility struct to help handling :obj:`~gi.repository.Gst.FlowReturn` combination. Useful for
:obj:`~gi.repository.Gst.Element`\<!-- -->s that have multiple source pads and need to combine
the different :obj:`~gi.repository.Gst.FlowReturn` for those pads.

:obj:`~gi.repository.GstBase.FlowCombiner` works by using the last :obj:`~gi.repository.Gst.FlowReturn` for all :obj:`~gi.repository.Gst.Pad`
it has in its list and computes the combined return value and provides
it to the caller.

To add a new pad to the :obj:`~gi.repository.GstBase.FlowCombiner` use :func:`~gi.repository.GstBase.FlowCombiner.add_pad`.
The new :obj:`~gi.repository.Gst.Pad` is stored with a default value of %GST_FLOW_OK.

In case you want a :obj:`~gi.repository.Gst.Pad` to be removed, use :func:`~gi.repository.GstBase.FlowCombiner.remove_pad`.

Please be aware that this struct isn't thread safe as its designed to be
 used by demuxers, those usually will have a single thread operating it.

These functions will take refs on the passed :obj:`~gi.repository.Gst.Pad`\<!-- -->s.

Aside from reducing the user's code size, the main advantage of using this
helper struct is to follow the standard rules for :obj:`~gi.repository.Gst.FlowReturn` combination.
These rules are:

- %GST_FLOW_EOS: only if all returns are EOS too
- %GST_FLOW_NOT_LINKED: only if all returns are NOT_LINKED too
- %GST_FLOW_ERROR or below: if at least one returns an error return
- %GST_FLOW_NOT_NEGOTIATED: if at least one returns a not-negotiated return
- %GST_FLOW_FLUSHING: if at least one returns flushing
- %GST_FLOW_OK: otherwise


%GST_FLOW_ERROR or below, GST_FLOW_NOT_NEGOTIATED and GST_FLOW_FLUSHING are
returned immediately from the :func:`~gi.repository.GstBase.FlowCombiner.update_flow` function.


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

.. rst-class:: interim-class

.. class:: FlowCombiner
   :no-index:


   .. classmethod:: new() -> ~gi.repository.GstBase.FlowCombiner

      Creates a new :obj:`~gi.repository.GstBase.FlowCombiner`\, use :func:`~gi.repository.GstBase.FlowCombiner.free` to free it.


      .. versionadded:: 1.4












Methods
-------

.. rst-class:: interim-class

.. class:: FlowCombiner
   :no-index:


   .. method:: add_pad(pad: ~gi.repository.Gst.Pad) -> None

      Adds a new :obj:`~gi.repository.Gst.Pad` to the :obj:`~gi.repository.GstBase.FlowCombiner`\.


      .. versionadded:: 1.4





      :param pad: the :obj:`~gi.repository.Gst.Pad` that is being added




   .. method:: clear() -> None

      Removes all pads from a :obj:`~gi.repository.GstBase.FlowCombiner` and resets it to its initial state.


      .. versionadded:: 1.6








   .. method:: free() -> None

      Frees a :obj:`~gi.repository.GstBase.FlowCombiner` struct and all its internal data.


      .. versionadded:: 1.4








   .. method:: remove_pad(pad: ~gi.repository.Gst.Pad) -> None

      Removes a :obj:`~gi.repository.Gst.Pad` from the :obj:`~gi.repository.GstBase.FlowCombiner`\.


      .. versionadded:: 1.4





      :param pad: the :obj:`~gi.repository.Gst.Pad` to remove




   .. method:: reset() -> None

      Reset flow combiner and all pads to their initial state without removing pads.


      .. versionadded:: 1.6








   .. method:: update_flow(fret: ~gi.repository.Gst.FlowReturn) -> ~gi.repository.Gst.FlowReturn

      Computes the combined flow return for the pads in it.

      The :obj:`~gi.repository.Gst.FlowReturn` parameter should be the last flow return update for a pad
      in this :obj:`~gi.repository.GstBase.FlowCombiner`\. It will use this value to be able to shortcut some
      combinations and avoid looking over all pads again. e.g. The last combined
      return is the same as the latest obtained :obj:`~gi.repository.Gst.FlowReturn`\.


      .. versionadded:: 1.4





      :param fret: the latest :obj:`~gi.repository.Gst.FlowReturn` received for a pad in this :obj:`~gi.repository.GstBase.FlowCombiner`




   .. method:: update_pad_flow(pad: ~gi.repository.Gst.Pad, fret: ~gi.repository.Gst.FlowReturn) -> ~gi.repository.Gst.FlowReturn

      Sets the provided pad's last flow return to provided value and computes
      the combined flow return for the pads in it.

      The :obj:`~gi.repository.Gst.FlowReturn` parameter should be the last flow return update for a pad
      in this :obj:`~gi.repository.GstBase.FlowCombiner`\. It will use this value to be able to shortcut some
      combinations and avoid looking over all pads again. e.g. The last combined
      return is the same as the latest obtained :obj:`~gi.repository.Gst.FlowReturn`\.


      .. versionadded:: 1.6





      :param pad: the :obj:`~gi.repository.Gst.Pad` whose :obj:`~gi.repository.Gst.FlowReturn` to update

      :param fret: the latest :obj:`~gi.repository.Gst.FlowReturn` received for a pad in this :obj:`~gi.repository.GstBase.FlowCombiner`