gstreamer_base/auto/

base_transform.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT

use crate::ffi;
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// This base class is for filter elements that process data. Elements
    /// that are suitable for implementation using [`BaseTransform`][crate::BaseTransform] are ones
    /// where the size and caps of the output is known entirely from the input
    /// caps and buffer sizes. These include elements that directly transform
    /// one buffer into another, modify the contents of a buffer in-place, as
    /// well as elements that collate multiple input buffers into one output buffer,
    /// or that expand one input buffer into multiple output buffers. See below
    /// for more concrete use cases.
    ///
    /// It provides for:
    ///
    /// * one sinkpad and one srcpad
    /// * Possible formats on sink and source pad implemented
    ///  with custom transform_caps function. By default uses
    ///  same format on sink and source.
    ///
    /// * Handles state changes
    /// * Does flushing
    /// * Push mode
    /// * Pull mode if the sub-class transform can operate on arbitrary data
    ///
    /// # Use Cases
    ///
    /// ## Passthrough mode
    ///
    ///  * Element has no interest in modifying the buffer. It may want to inspect it,
    ///  in which case the element should have a transform_ip function. If there
    ///  is no transform_ip function in passthrough mode, the buffer is pushed
    ///  intact.
    ///
    ///  * The `GstBaseTransformClass.passthrough_on_same_caps` variable
    ///  will automatically set/unset passthrough based on whether the
    ///  element negotiates the same caps on both pads.
    ///
    ///  * `GstBaseTransformClass.passthrough_on_same_caps` on an element that
    ///  doesn't implement a transform_caps function is useful for elements that
    ///  only inspect data (such as level)
    ///
    ///  * Example elements
    ///
    ///  * Level
    ///  * Videoscale, audioconvert, videoconvert, audioresample in certain modes.
    ///
    /// ## Modifications in-place - input buffer and output buffer are the same thing.
    ///
    /// * The element must implement a transform_ip function.
    /// * Output buffer size must <= input buffer size
    /// * If the always_in_place flag is set, non-writable buffers will be copied
    ///  and passed to the transform_ip function, otherwise a new buffer will be
    ///  created and the transform function called.
    ///
    /// * Incoming writable buffers will be passed to the transform_ip function
    ///  immediately.
    /// * only implementing transform_ip and not transform implies always_in_place = [`true`]
    ///
    ///  * Example elements:
    ///  * Volume
    ///  * Audioconvert in certain modes (signed/unsigned conversion)
    ///  * videoconvert in certain modes (endianness swapping)
    ///
    /// ## Modifications only to the caps/metadata of a buffer
    ///
    /// * The element does not require writable data, but non-writable buffers
    ///  should be subbuffered so that the meta-information can be replaced.
    ///
    /// * Elements wishing to operate in this mode should replace the
    ///  prepare_output_buffer method to create subbuffers of the input buffer
    ///  and set always_in_place to [`true`]
    ///
    /// * Example elements
    ///  * Capsfilter when setting caps on outgoing buffers that have
    ///  none.
    ///  * identity when it is going to re-timestamp buffers by
    ///  datarate.
    ///
    /// ## Normal mode
    ///  * always_in_place flag is not set, or there is no transform_ip function
    ///  * Element will receive an input buffer and output buffer to operate on.
    ///  * Output buffer is allocated by calling the prepare_output_buffer function.
    ///  * Example elements:
    ///  * Videoscale, videoconvert, audioconvert when doing
    ///  scaling/conversions
    ///
    /// ## Special output buffer allocations
    ///  * Elements which need to do special allocation of their output buffers
    ///  beyond allocating output buffers via the negotiated allocator or
    ///  buffer pool should implement the prepare_output_buffer method.
    ///
    ///  * Example elements:
    ///  * efence
    ///
    /// # Sub-class settable flags on GstBaseTransform
    ///
    /// * passthrough
    ///
    ///  * Implies that in the current configuration, the sub-class is not interested in modifying the buffers.
    ///  * Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically.
    ///
    /// * always_in_place
    ///  * Determines whether a non-writable buffer will be copied before passing
    ///  to the transform_ip function.
    ///
    ///  * Implied [`true`] if no transform function is implemented.
    ///  * Implied [`false`] if ONLY transform function is implemented.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `qos`
    ///  Readable | Writeable
    /// <details><summary><h4>Object</h4></summary>
    ///
    ///
    /// #### `name`
    ///  Readable | Writeable | Construct
    ///
    ///
    /// #### `parent`
    ///  The parent of the object. Please note, that when changing the 'parent'
    /// property, we don't emit [`notify`][struct@crate::glib::Object#notify] and [`deep-notify`][struct@crate::gst::Object#deep-notify]
    /// signals due to locking issues. In some cases one can use
    /// `GstBin::element-added` or `GstBin::element-removed` signals on the parent to
    /// achieve a similar effect.
    ///
    /// Readable | Writeable
    /// </details>
    ///
    /// # Implements
    ///
    /// [`BaseTransformExt`][trait@crate::prelude::BaseTransformExt], [`trait@gst::prelude::ElementExt`], [`trait@gst::prelude::ObjectExt`], [`trait@glib::ObjectExt`], [`BaseTransformExtManual`][trait@crate::prelude::BaseTransformExtManual]
    #[doc(alias = "GstBaseTransform")]
    pub struct BaseTransform(Object<ffi::GstBaseTransform, ffi::GstBaseTransformClass>) @extends gst::Element, gst::Object;

    match fn {
        type_ => || ffi::gst_base_transform_get_type(),
    }
}

impl BaseTransform {
    pub const NONE: Option<&'static BaseTransform> = None;
}

unsafe impl Send for BaseTransform {}
unsafe impl Sync for BaseTransform {}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::BaseTransform>> Sealed for T {}
}

/// Trait containing all [`struct@BaseTransform`] methods.
///
/// # Implementors
///
/// [`BaseTransform`][struct@crate::BaseTransform]
pub trait BaseTransformExt: IsA<BaseTransform> + sealed::Sealed + 'static {
    ///
    /// # Returns
    ///
    /// the instance of the [`gst::BufferPool`][crate::gst::BufferPool] used
    /// by `self`; free it after use
    #[doc(alias = "gst_base_transform_get_buffer_pool")]
    #[doc(alias = "get_buffer_pool")]
    fn buffer_pool(&self) -> Option<gst::BufferPool> {
        unsafe {
            from_glib_full(ffi::gst_base_transform_get_buffer_pool(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// See if `self` is configured as a in_place transform.
    ///
    /// # Returns
    ///
    /// [`true`] if the transform is configured in in_place mode.
    ///
    /// MT safe.
    #[doc(alias = "gst_base_transform_is_in_place")]
    fn is_in_place(&self) -> bool {
        unsafe {
            from_glib(ffi::gst_base_transform_is_in_place(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// See if `self` is configured as a passthrough transform.
    ///
    /// # Returns
    ///
    /// [`true`] if the transform is configured in passthrough mode.
    ///
    /// MT safe.
    #[doc(alias = "gst_base_transform_is_passthrough")]
    fn is_passthrough(&self) -> bool {
        unsafe {
            from_glib(ffi::gst_base_transform_is_passthrough(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Negotiates src pad caps with downstream elements if the source pad is
    /// marked as needing reconfiguring. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in
    /// any case. But marks it again if negotiation fails.
    ///
    /// Do not call this in the `GstBaseTransformClass::transform` or
    /// `GstBaseTransformClass::transform_ip` vmethod. Call this in
    /// `GstBaseTransformClass::submit_input_buffer`,
    /// `GstBaseTransformClass::prepare_output_buffer` or in
    /// `GstBaseTransformClass::generate_output` _before_ any output buffer is
    /// allocated.
    ///
    /// It will be default be called when handling an ALLOCATION query or at the
    /// very beginning of the default `GstBaseTransformClass::submit_input_buffer`
    /// implementation.
    ///
    /// # Returns
    ///
    /// [`true`] if the negotiation succeeded, else [`false`].
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "gst_base_transform_reconfigure")]
    fn reconfigure(&self) -> bool {
        unsafe {
            from_glib(ffi::gst_base_transform_reconfigure(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Instructs `self` to request renegotiation upstream. This function is
    /// typically called after properties on the transform were set that
    /// influence the input format.
    #[doc(alias = "gst_base_transform_reconfigure_sink")]
    fn reconfigure_sink(&self) {
        unsafe {
            ffi::gst_base_transform_reconfigure_sink(self.as_ref().to_glib_none().0);
        }
    }

    /// Instructs `self` to renegotiate a new downstream transform on the next
    /// buffer. This function is typically called after properties on the transform
    /// were set that influence the output format.
    #[doc(alias = "gst_base_transform_reconfigure_src")]
    fn reconfigure_src(&self) {
        unsafe {
            ffi::gst_base_transform_reconfigure_src(self.as_ref().to_glib_none().0);
        }
    }

    /// If `gap_aware` is [`false`] (the default), output buffers will have the
    /// [`gst::BufferFlags::GAP`][crate::gst::BufferFlags::GAP] flag unset.
    ///
    /// If set to [`true`], the element must handle output buffers with this flag set
    /// correctly, i.e. it can assume that the buffer contains neutral data but must
    /// unset the flag if the output is no neutral data.
    ///
    /// MT safe.
    /// ## `gap_aware`
    /// New state
    #[doc(alias = "gst_base_transform_set_gap_aware")]
    fn set_gap_aware(&self, gap_aware: bool) {
        unsafe {
            ffi::gst_base_transform_set_gap_aware(
                self.as_ref().to_glib_none().0,
                gap_aware.into_glib(),
            );
        }
    }

    /// Determines whether a non-writable buffer will be copied before passing
    /// to the transform_ip function.
    ///
    ///  * Always [`true`] if no transform function is implemented.
    ///  * Always [`false`] if ONLY transform function is implemented.
    ///
    /// MT safe.
    /// ## `in_place`
    /// Boolean value indicating that we would like to operate
    /// on in_place buffers.
    #[doc(alias = "gst_base_transform_set_in_place")]
    fn set_in_place(&self, in_place: bool) {
        unsafe {
            ffi::gst_base_transform_set_in_place(
                self.as_ref().to_glib_none().0,
                in_place.into_glib(),
            );
        }
    }

    /// Set passthrough mode for this filter by default. This is mostly
    /// useful for filters that do not care about negotiation.
    ///
    /// Always [`true`] for filters which don't implement either a transform
    /// or transform_ip or generate_output method.
    ///
    /// MT safe.
    /// ## `passthrough`
    /// boolean indicating passthrough mode.
    #[doc(alias = "gst_base_transform_set_passthrough")]
    fn set_passthrough(&self, passthrough: bool) {
        unsafe {
            ffi::gst_base_transform_set_passthrough(
                self.as_ref().to_glib_none().0,
                passthrough.into_glib(),
            );
        }
    }

    /// If `prefer_passthrough` is [`true`] (the default), `self` will check and
    /// prefer passthrough caps from the list of caps returned by the
    /// transform_caps vmethod.
    ///
    /// If set to [`false`], the element must order the caps returned from the
    /// transform_caps function in such a way that the preferred format is
    /// first in the list. This can be interesting for transforms that can do
    /// passthrough transforms but prefer to do something else, like a
    /// capsfilter.
    ///
    /// MT safe.
    /// ## `prefer_passthrough`
    /// New state
    #[doc(alias = "gst_base_transform_set_prefer_passthrough")]
    fn set_prefer_passthrough(&self, prefer_passthrough: bool) {
        unsafe {
            ffi::gst_base_transform_set_prefer_passthrough(
                self.as_ref().to_glib_none().0,
                prefer_passthrough.into_glib(),
            );
        }
    }

    /// Set the QoS parameters in the transform. This function is called internally
    /// when a QOS event is received but subclasses can provide custom information
    /// when needed.
    ///
    /// MT safe.
    /// ## `proportion`
    /// the proportion
    /// ## `diff`
    /// the diff against the clock
    /// ## `timestamp`
    /// the timestamp of the buffer generating the QoS expressed in
    /// running_time.
    #[doc(alias = "gst_base_transform_update_qos")]
    fn update_qos(&self, proportion: f64, diff: gst::ClockTimeDiff, timestamp: gst::ClockTime) {
        unsafe {
            ffi::gst_base_transform_update_qos(
                self.as_ref().to_glib_none().0,
                proportion,
                diff,
                timestamp.into_glib(),
            );
        }
    }

    /// Updates the srcpad caps and sends the caps downstream. This function
    /// can be used by subclasses when they have already negotiated their caps
    /// but found a change in them (or computed new information). This way,
    /// they can notify downstream about that change without losing any
    /// buffer.
    /// ## `updated_caps`
    /// An updated version of the srcpad caps to be pushed
    /// downstream
    ///
    /// # Returns
    ///
    /// [`true`] if the caps could be sent downstream [`false`] otherwise
    #[doc(alias = "gst_base_transform_update_src_caps")]
    fn update_src_caps(&self, updated_caps: &gst::Caps) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_base_transform_update_src_caps(
                    self.as_ref().to_glib_none().0,
                    updated_caps.to_glib_none().0
                ),
                "Failed to update src caps"
            )
        }
    }

    fn is_qos(&self) -> bool {
        ObjectExt::property(self.as_ref(), "qos")
    }

    fn set_qos(&self, qos: bool) {
        ObjectExt::set_property(self.as_ref(), "qos", qos)
    }

    #[doc(alias = "qos")]
    fn connect_qos_notify<F: Fn(&Self) + Send + Sync + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_qos_trampoline<
            P: IsA<BaseTransform>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstBaseTransform,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(BaseTransform::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::qos\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_qos_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<BaseTransform>> BaseTransformExt for O {}