gstreamer_base/

flow_combiner.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use crate::ffi;
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// s.
    ///
    /// Aside from reducing the user's code size, the main advantage of using this
    /// helper struct is to follow the standard rules for [`gst::FlowReturn`][crate::gst::FlowReturn] combination.
    /// These rules are:
    ///
    /// * [`gst::FlowReturn::Eos`][crate::gst::FlowReturn::Eos]: only if all returns are EOS too
    /// * [`gst::FlowReturn::NotLinked`][crate::gst::FlowReturn::NotLinked]: only if all returns are NOT_LINKED too
    /// * [`gst::FlowReturn::Error`][crate::gst::FlowReturn::Error] or below: if at least one returns an error return
    /// * [`gst::FlowReturn::NotNegotiated`][crate::gst::FlowReturn::NotNegotiated]: if at least one returns a not-negotiated return
    /// * [`gst::FlowReturn::Flushing`][crate::gst::FlowReturn::Flushing]: if at least one returns flushing
    /// * [`gst::FlowReturn::Ok`][crate::gst::FlowReturn::Ok]: otherwise
    ///
    /// [`gst::FlowReturn::Error`][crate::gst::FlowReturn::Error] or below, GST_FLOW_NOT_NEGOTIATED and GST_FLOW_FLUSHING are
    /// returned immediately from the [`update_flow()`][Self::update_flow()] function.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    #[doc(alias = "GstFlowCombiner")]
    pub struct FlowCombiner(Shared<ffi::GstFlowCombiner>);

    match fn {
        ref => |ptr| ffi::gst_flow_combiner_ref(ptr),
        unref => |ptr| ffi::gst_flow_combiner_unref(ptr),
        type_ => || ffi::gst_flow_combiner_get_type(),
    }
}

impl FlowCombiner {
    /// Creates a new [`FlowCombiner`][crate::FlowCombiner], use `gst_flow_combiner_free()` to free it.
    ///
    /// # Returns
    ///
    /// A new [`FlowCombiner`][crate::FlowCombiner]
    #[doc(alias = "gst_flow_combiner_new")]
    pub fn new() -> Self {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gst_flow_combiner_new()) }
    }

    /// Adds a new [`gst::Pad`][crate::gst::Pad] to the [`FlowCombiner`][crate::FlowCombiner].
    /// ## `pad`
    /// the [`gst::Pad`][crate::gst::Pad] that is being added
    #[doc(alias = "gst_flow_combiner_add_pad")]
    pub fn add_pad<P: IsA<gst::Pad>>(&self, pad: &P) {
        unsafe {
            ffi::gst_flow_combiner_add_pad(self.to_glib_none().0, pad.as_ref().to_glib_none().0);
        }
    }

    /// Removes all pads from a [`FlowCombiner`][crate::FlowCombiner] and resets it to its initial state.
    #[doc(alias = "gst_flow_combiner_clear")]
    pub fn clear(&self) {
        unsafe {
            ffi::gst_flow_combiner_clear(self.to_glib_none().0);
        }
    }

    /// Removes a [`gst::Pad`][crate::gst::Pad] from the [`FlowCombiner`][crate::FlowCombiner].
    /// ## `pad`
    /// the [`gst::Pad`][crate::gst::Pad] to remove
    #[doc(alias = "gst_flow_combiner_remove_pad")]
    pub fn remove_pad<P: IsA<gst::Pad>>(&self, pad: &P) {
        unsafe {
            ffi::gst_flow_combiner_remove_pad(self.to_glib_none().0, pad.as_ref().to_glib_none().0);
        }
    }

    /// Reset flow combiner and all pads to their initial state without removing pads.
    #[doc(alias = "gst_flow_combiner_reset")]
    pub fn reset(&self) {
        unsafe {
            ffi::gst_flow_combiner_reset(self.to_glib_none().0);
        }
    }

    /// Computes the combined flow return for the pads in it.
    ///
    /// The [`gst::FlowReturn`][crate::gst::FlowReturn] parameter should be the last flow return update for a pad
    /// in this [`FlowCombiner`][crate::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 [`gst::FlowReturn`][crate::gst::FlowReturn].
    /// ## `fret`
    /// the latest [`gst::FlowReturn`][crate::gst::FlowReturn] received for a pad in this [`FlowCombiner`][crate::FlowCombiner]
    ///
    /// # Returns
    ///
    /// The combined [`gst::FlowReturn`][crate::gst::FlowReturn]
    #[doc(alias = "gst_flow_combiner_update_flow")]
    pub fn update_flow<FRet: Into<gst::FlowReturn>>(
        &self,
        fret: FRet,
    ) -> Result<gst::FlowSuccess, gst::FlowError> {
        let fret: gst::FlowReturn = fret.into();
        unsafe {
            try_from_glib(ffi::gst_flow_combiner_update_flow(
                self.to_glib_none().0,
                fret.into_glib(),
            ))
        }
    }

    /// Sets the provided pad's last flow return to provided value and computes
    /// the combined flow return for the pads in it.
    ///
    /// The [`gst::FlowReturn`][crate::gst::FlowReturn] parameter should be the last flow return update for a pad
    /// in this [`FlowCombiner`][crate::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 [`gst::FlowReturn`][crate::gst::FlowReturn].
    /// ## `pad`
    /// the [`gst::Pad`][crate::gst::Pad] whose [`gst::FlowReturn`][crate::gst::FlowReturn] to update
    /// ## `fret`
    /// the latest [`gst::FlowReturn`][crate::gst::FlowReturn] received for a pad in this [`FlowCombiner`][crate::FlowCombiner]
    ///
    /// # Returns
    ///
    /// The combined [`gst::FlowReturn`][crate::gst::FlowReturn]
    #[doc(alias = "gst_flow_combiner_update_pad_flow")]
    pub fn update_pad_flow<P: IsA<gst::Pad>, FRet: Into<gst::FlowReturn>>(
        &self,
        pad: &P,
        fret: FRet,
    ) -> Result<gst::FlowSuccess, gst::FlowError> {
        let fret: gst::FlowReturn = fret.into();
        unsafe {
            try_from_glib(ffi::gst_flow_combiner_update_pad_flow(
                self.to_glib_none().0,
                pad.as_ref().to_glib_none().0,
                fret.into_glib(),
            ))
        }
    }
}

impl Default for FlowCombiner {
    fn default() -> Self {
        Self::new()
    }
}

#[derive(Debug)]
pub struct UniqueFlowCombiner(FlowCombiner);

unsafe impl Sync for UniqueFlowCombiner {}
unsafe impl Send for UniqueFlowCombiner {}

impl UniqueFlowCombiner {
    pub fn new() -> Self {
        Self(FlowCombiner::new())
    }

    pub fn add_pad<P: IsA<gst::Pad>>(&mut self, pad: &P) {
        self.0.add_pad(pad);
    }

    pub fn clear(&mut self) {
        self.0.clear();
    }

    pub fn remove_pad<P: IsA<gst::Pad>>(&mut self, pad: &P) {
        self.0.remove_pad(pad);
    }

    pub fn reset(&mut self) {
        self.0.reset();
    }

    pub fn update_flow(
        &mut self,
        fret: Result<gst::FlowSuccess, gst::FlowError>,
    ) -> Result<gst::FlowSuccess, gst::FlowError> {
        self.0.update_flow(fret)
    }

    pub fn update_pad_flow<P: IsA<gst::Pad>>(
        &mut self,
        pad: &P,
        fret: Result<gst::FlowSuccess, gst::FlowError>,
    ) -> Result<gst::FlowSuccess, gst::FlowError> {
        self.0.update_pad_flow(pad, fret)
    }
}

impl Default for UniqueFlowCombiner {
    fn default() -> Self {
        Self::new()
    }
}