gstreamer_base/auto/

base_parse.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 parser elements that process data and splits it
    /// into separate audio/video/whatever frames.
    ///
    /// It provides for:
    ///
    ///  * provides one sink pad and one source pad
    ///  * handles state changes
    ///  * can operate in pull mode or push mode
    ///  * handles seeking in both modes
    ///  * handles events (SEGMENT/EOS/FLUSH)
    ///  * handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT)
    ///  * handles flushing
    ///
    /// The purpose of this base class is to provide the basic functionality of
    /// a parser and share a lot of rather complex code.
    ///
    /// # Description of the parsing mechanism:
    ///
    /// ## Set-up phase
    ///
    ///  * [`BaseParse`][crate::BaseParse] calls `GstBaseParseClass::start` to inform subclass
    ///  that data processing is about to start now.
    ///
    ///  * [`BaseParse`][crate::BaseParse] class calls `GstBaseParseClass::set_sink_caps` to
    ///  inform the subclass about incoming sinkpad caps. Subclass could
    ///  already set the srcpad caps accordingly, but this might be delayed
    ///  until calling [`BaseParseExtManual::finish_frame()`][crate::prelude::BaseParseExtManual::finish_frame()] with a non-queued frame.
    ///
    ///  * At least at this point subclass needs to tell the [`BaseParse`][crate::BaseParse] class
    ///  how big data chunks it wants to receive (minimum frame size ). It can
    ///  do this with [`BaseParseExt::set_min_frame_size()`][crate::prelude::BaseParseExt::set_min_frame_size()].
    ///
    ///  * [`BaseParse`][crate::BaseParse] class sets up appropriate data passing mode (pull/push)
    ///  and starts to process the data.
    ///
    /// ## Parsing phase
    ///
    ///  * [`BaseParse`][crate::BaseParse] gathers at least min_frame_size bytes of data either
    ///  by pulling it from upstream or collecting buffers in an internal
    ///  [`Adapter`][crate::Adapter].
    ///
    ///  * A buffer of (at least) min_frame_size bytes is passed to subclass
    ///  with `GstBaseParseClass::handle_frame`. Subclass checks the contents
    ///  and can optionally return [`gst::FlowReturn::Ok`][crate::gst::FlowReturn::Ok] along with an amount of data
    ///  to be skipped to find a valid frame (which will result in a
    ///  subsequent DISCONT). If, otherwise, the buffer does not hold a
    ///  complete frame, `GstBaseParseClass::handle_frame` can merely return
    ///  and will be called again when additional data is available. In push
    ///  mode this amounts to an additional input buffer (thus minimal
    ///  additional latency), in pull mode this amounts to some arbitrary
    ///  reasonable buffer size increase.
    ///
    ///  Of course, [`BaseParseExt::set_min_frame_size()`][crate::prelude::BaseParseExt::set_min_frame_size()] could also be used if
    ///  a very specific known amount of additional data is required. If,
    ///  however, the buffer holds a complete valid frame, it can pass the
    ///  size of this frame to [`BaseParseExtManual::finish_frame()`][crate::prelude::BaseParseExtManual::finish_frame()].
    ///
    ///  If acting as a converter, it can also merely indicate consumed input
    ///  data while simultaneously providing custom output data. Note that
    ///  baseclass performs some processing (such as tracking overall consumed
    ///  data rate versus duration) for each finished frame, but other state
    ///  is only updated upon each call to `GstBaseParseClass::handle_frame`
    ///  (such as tracking upstream input timestamp).
    ///
    ///  Subclass is also responsible for setting the buffer metadata
    ///  (e.g. buffer timestamp and duration, or keyframe if applicable).
    ///  (although the latter can also be done by [`BaseParse`][crate::BaseParse] if it is
    ///  appropriately configured, see below). Frame is provided with
    ///  timestamp derived from upstream (as much as generally possible),
    ///  duration obtained from configuration (see below), and offset
    ///  if meaningful (in pull mode).
    ///
    ///  Note that `GstBaseParseClass::handle_frame` might receive any small
    ///  amount of input data when leftover data is being drained (e.g. at
    ///  EOS).
    ///
    ///  * As part of finish frame processing, just prior to actually pushing
    ///  the buffer in question, it is passed to
    ///  `GstBaseParseClass::pre_push_frame` which gives subclass yet one last
    ///  chance to examine buffer metadata, or to send some custom (tag)
    ///  events, or to perform custom (segment) filtering.
    ///
    ///  * During the parsing process `GstBaseParseClass` will handle both srcpad
    ///  and sinkpad events. They will be passed to subclass if
    ///  `GstBaseParseClass::sink_event` or `GstBaseParseClass::src_event`
    ///  implementations have been provided.
    ///
    /// ## Shutdown phase
    ///
    /// * [`BaseParse`][crate::BaseParse] class calls `GstBaseParseClass::stop` to inform the
    ///  subclass that data parsing will be stopped.
    ///
    /// Subclass is responsible for providing pad template caps for source and
    /// sink pads. The pads need to be named "sink" and "src". It also needs to
    /// set the fixed caps on srcpad, when the format is ensured (e.g. when
    /// base class calls subclass' `GstBaseParseClass::set_sink_caps` function).
    ///
    /// This base class uses [`gst::Format::Default`][crate::gst::Format::Default] as a meaning of frames. So,
    /// subclass conversion routine needs to know that conversion from
    /// [`gst::Format::Time`][crate::gst::Format::Time] to [`gst::Format::Default`][crate::gst::Format::Default] must return the
    /// frame number that can be found from the given byte position.
    ///
    /// [`BaseParse`][crate::BaseParse] uses subclasses conversion methods also for seeking (or
    /// otherwise uses its own default one, see also below).
    ///
    /// Subclass `start` and `stop` functions will be called to inform the beginning
    /// and end of data processing.
    ///
    /// Things that subclass need to take care of:
    ///
    /// * Provide pad templates
    /// * Fixate the source pad caps when appropriate
    /// * Inform base class how big data chunks should be retrieved. This is
    ///  done with [`BaseParseExt::set_min_frame_size()`][crate::prelude::BaseParseExt::set_min_frame_size()] function.
    /// * Examine data chunks passed to subclass with
    ///  `GstBaseParseClass::handle_frame` and pass proper frame(s) to
    ///  [`BaseParseExtManual::finish_frame()`][crate::prelude::BaseParseExtManual::finish_frame()], and setting src pad caps and timestamps
    ///  on frame.
    /// * Provide conversion functions
    /// * Update the duration information with [`BaseParseExtManual::set_duration()`][crate::prelude::BaseParseExtManual::set_duration()]
    /// * Optionally passthrough using [`BaseParseExt::set_passthrough()`][crate::prelude::BaseParseExt::set_passthrough()]
    /// * Configure various baseparse parameters using
    ///  [`BaseParseExt::set_average_bitrate()`][crate::prelude::BaseParseExt::set_average_bitrate()], [`BaseParseExt::set_syncable()`][crate::prelude::BaseParseExt::set_syncable()]
    ///  and [`BaseParseExtManual::set_frame_rate()`][crate::prelude::BaseParseExtManual::set_frame_rate()].
    ///
    /// * In particular, if subclass is unable to determine a duration, but
    ///  parsing (or specs) yields a frames per seconds rate, then this can be
    ///  provided to [`BaseParse`][crate::BaseParse] to enable it to cater for buffer time
    ///  metadata (which will be taken from upstream as much as
    ///  possible). Internally keeping track of frame durations and respective
    ///  sizes that have been pushed provides [`BaseParse`][crate::BaseParse] with an estimated
    ///  bitrate. A default `GstBaseParseClass::convert` (used if not
    ///  overridden) will then use these rates to perform obvious conversions.
    ///  These rates are also used to update (estimated) duration at regular
    ///  frame intervals.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `disable-passthrough`
    ///  If set to [`true`], baseparse will unconditionally force parsing of the
    /// incoming data. This can be required in the rare cases where the incoming
    /// side-data (caps, pts, dts, ...) is not trusted by the user and wants to
    /// force validation and parsing of the incoming data.
    /// If set to [`false`], decision of whether to parse the data or not is up to
    /// the implementation (standard behaviour).
    ///
    /// 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
    ///
    /// [`BaseParseExt`][trait@crate::prelude::BaseParseExt], [`trait@gst::prelude::ElementExt`], [`trait@gst::prelude::ObjectExt`], [`trait@glib::ObjectExt`], [`BaseParseExtManual`][trait@crate::prelude::BaseParseExtManual]
    #[doc(alias = "GstBaseParse")]
    pub struct BaseParse(Object<ffi::GstBaseParse, ffi::GstBaseParseClass>) @extends gst::Element, gst::Object;

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

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

unsafe impl Send for BaseParse {}
unsafe impl Sync for BaseParse {}

/// Trait containing all [`struct@BaseParse`] methods.
///
/// # Implementors
///
/// [`BaseParse`][struct@crate::BaseParse]
pub trait BaseParseExt: IsA<BaseParse> + 'static {
    /// Adds an entry to the index associating `offset` to `ts`. It is recommended
    /// to only add keyframe entries. `force` allows to bypass checks, such as
    /// whether the stream is (upstream) seekable, another entry is already "close"
    /// to the new entry, etc.
    /// ## `offset`
    /// offset of entry
    /// ## `ts`
    /// timestamp associated with offset
    /// ## `key`
    /// whether entry refers to keyframe
    /// ## `force`
    /// add entry disregarding sanity checks
    ///
    /// # Returns
    ///
    /// `gboolean` indicating whether entry was added
    #[doc(alias = "gst_base_parse_add_index_entry")]
    fn add_index_entry(&self, offset: u64, ts: gst::ClockTime, key: bool, force: bool) -> bool {
        unsafe {
            from_glib(ffi::gst_base_parse_add_index_entry(
                self.as_ref().to_glib_none().0,
                offset,
                ts.into_glib(),
                key.into_glib(),
                force.into_glib(),
            ))
        }
    }

    /// Drains the adapter until it is empty. It decreases the min_frame_size to
    /// match the current adapter size and calls chain method until the adapter
    /// is emptied or chain returns with error.
    #[doc(alias = "gst_base_parse_drain")]
    fn drain(&self) {
        unsafe {
            ffi::gst_base_parse_drain(self.as_ref().to_glib_none().0);
        }
    }

    /// Sets the parser subclass's tags and how they should be merged with any
    /// upstream stream tags. This will override any tags previously-set
    /// with [`merge_tags()`][Self::merge_tags()].
    ///
    /// Note that this is provided for convenience, and the subclass is
    /// not required to use this and can still do tag handling on its own.
    /// ## `tags`
    /// a [`gst::TagList`][crate::gst::TagList] to merge, or NULL to unset
    ///  previously-set tags
    /// ## `mode`
    /// the [`gst::TagMergeMode`][crate::gst::TagMergeMode] to use, usually [`gst::TagMergeMode::Replace`][crate::gst::TagMergeMode::Replace]
    #[doc(alias = "gst_base_parse_merge_tags")]
    fn merge_tags(&self, tags: Option<&gst::TagList>, mode: gst::TagMergeMode) {
        unsafe {
            ffi::gst_base_parse_merge_tags(
                self.as_ref().to_glib_none().0,
                tags.to_glib_none().0,
                mode.into_glib(),
            );
        }
    }

    /// Optionally sets the average bitrate detected in media (if non-zero),
    /// e.g. based on metadata, as it will be posted to the application.
    ///
    /// By default, announced average bitrate is estimated. The average bitrate
    /// is used to estimate the total duration of the stream and to estimate
    /// a seek position, if there's no index and the format is syncable
    /// (see [`set_syncable()`][Self::set_syncable()]).
    /// ## `bitrate`
    /// average bitrate in bits/second
    #[doc(alias = "gst_base_parse_set_average_bitrate")]
    fn set_average_bitrate(&self, bitrate: u32) {
        unsafe {
            ffi::gst_base_parse_set_average_bitrate(self.as_ref().to_glib_none().0, bitrate);
        }
    }

    /// Set if frames carry timing information which the subclass can (generally)
    /// parse and provide. In particular, intrinsic (rather than estimated) time
    /// can be obtained following a seek.
    /// ## `has_timing`
    /// whether frames carry timing information
    #[doc(alias = "gst_base_parse_set_has_timing_info")]
    fn set_has_timing_info(&self, has_timing: bool) {
        unsafe {
            ffi::gst_base_parse_set_has_timing_info(
                self.as_ref().to_glib_none().0,
                has_timing.into_glib(),
            );
        }
    }

    /// By default, the base class might try to infer PTS from DTS and vice
    /// versa. While this is generally correct for audio data, it may not
    /// be otherwise. Sub-classes implementing such formats should disable
    /// timestamp inferring.
    /// ## `infer_ts`
    /// [`true`] if parser should infer DTS/PTS from each other
    #[doc(alias = "gst_base_parse_set_infer_ts")]
    fn set_infer_ts(&self, infer_ts: bool) {
        unsafe {
            ffi::gst_base_parse_set_infer_ts(self.as_ref().to_glib_none().0, infer_ts.into_glib());
        }
    }

    /// Sets the minimum and maximum (which may likely be equal) latency introduced
    /// by the parsing process. If there is such a latency, which depends on the
    /// particular parsing of the format, it typically corresponds to 1 frame duration.
    ///
    /// If the provided values changed from previously provided ones, this will
    /// also post a LATENCY message on the bus so the pipeline can reconfigure its
    /// global latency.
    /// ## `min_latency`
    /// minimum parse latency
    /// ## `max_latency`
    /// maximum parse latency
    #[doc(alias = "gst_base_parse_set_latency")]
    fn set_latency(
        &self,
        min_latency: gst::ClockTime,
        max_latency: impl Into<Option<gst::ClockTime>>,
    ) {
        unsafe {
            ffi::gst_base_parse_set_latency(
                self.as_ref().to_glib_none().0,
                min_latency.into_glib(),
                max_latency.into().into_glib(),
            );
        }
    }

    /// Subclass can use this function to tell the base class that it needs to
    /// be given buffers of at least `min_size` bytes.
    /// ## `min_size`
    /// Minimum size in bytes of the data that this base class should
    ///  give to subclass.
    #[doc(alias = "gst_base_parse_set_min_frame_size")]
    fn set_min_frame_size(&self, min_size: u32) {
        unsafe {
            ffi::gst_base_parse_set_min_frame_size(self.as_ref().to_glib_none().0, min_size);
        }
    }

    /// Set if the nature of the format or configuration does not allow (much)
    /// parsing, and the parser should operate in passthrough mode (which only
    /// applies when operating in push mode). That is, incoming buffers are
    /// pushed through unmodified, i.e. no `GstBaseParseClass::handle_frame`
    /// will be invoked, but `GstBaseParseClass::pre_push_frame` will still be
    /// invoked, so subclass can perform as much or as little is appropriate for
    /// passthrough semantics in `GstBaseParseClass::pre_push_frame`.
    /// ## `passthrough`
    /// [`true`] if parser should run in passthrough mode
    #[doc(alias = "gst_base_parse_set_passthrough")]
    fn set_passthrough(&self, passthrough: bool) {
        unsafe {
            ffi::gst_base_parse_set_passthrough(
                self.as_ref().to_glib_none().0,
                passthrough.into_glib(),
            );
        }
    }

    /// By default, the base class will guess PTS timestamps using a simple
    /// interpolation (previous timestamp + duration), which is incorrect for
    /// data streams with reordering, where PTS can go backward. Sub-classes
    /// implementing such formats should disable PTS interpolation.
    /// ## `pts_interpolate`
    /// [`true`] if parser should interpolate PTS timestamps
    #[doc(alias = "gst_base_parse_set_pts_interpolation")]
    fn set_pts_interpolation(&self, pts_interpolate: bool) {
        unsafe {
            ffi::gst_base_parse_set_pts_interpolation(
                self.as_ref().to_glib_none().0,
                pts_interpolate.into_glib(),
            );
        }
    }

    /// Set if frame starts can be identified. This is set by default and
    /// determines whether seeking based on bitrate averages
    /// is possible for a format/stream.
    /// ## `syncable`
    /// set if frame starts can be identified
    #[doc(alias = "gst_base_parse_set_syncable")]
    fn set_syncable(&self, syncable: bool) {
        unsafe {
            ffi::gst_base_parse_set_syncable(self.as_ref().to_glib_none().0, syncable.into_glib());
        }
    }

    /// This function should only be called from a `handle_frame` implementation.
    ///
    /// [`BaseParse`][crate::BaseParse] creates initial timestamps for frames by using the last
    /// timestamp seen in the stream before the frame starts. In certain
    /// cases, the correct timestamps will occur in the stream after the
    /// start of the frame, but before the start of the actual picture data.
    /// This function can be used to set the timestamps based on the offset
    /// into the frame data that the picture starts.
    /// ## `offset`
    /// offset into current buffer
    #[doc(alias = "gst_base_parse_set_ts_at_offset")]
    fn set_ts_at_offset(&self, offset: usize) {
        unsafe {
            ffi::gst_base_parse_set_ts_at_offset(self.as_ref().to_glib_none().0, offset);
        }
    }

    /// If set to [`true`], baseparse will unconditionally force parsing of the
    /// incoming data. This can be required in the rare cases where the incoming
    /// side-data (caps, pts, dts, ...) is not trusted by the user and wants to
    /// force validation and parsing of the incoming data.
    /// If set to [`false`], decision of whether to parse the data or not is up to
    /// the implementation (standard behaviour).
    #[doc(alias = "disable-passthrough")]
    fn is_disable_passthrough(&self) -> bool {
        ObjectExt::property(self.as_ref(), "disable-passthrough")
    }

    /// If set to [`true`], baseparse will unconditionally force parsing of the
    /// incoming data. This can be required in the rare cases where the incoming
    /// side-data (caps, pts, dts, ...) is not trusted by the user and wants to
    /// force validation and parsing of the incoming data.
    /// If set to [`false`], decision of whether to parse the data or not is up to
    /// the implementation (standard behaviour).
    #[doc(alias = "disable-passthrough")]
    fn set_disable_passthrough(&self, disable_passthrough: bool) {
        ObjectExt::set_property(self.as_ref(), "disable-passthrough", disable_passthrough)
    }

    #[doc(alias = "disable-passthrough")]
    fn connect_disable_passthrough_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_disable_passthrough_trampoline<
            P: IsA<BaseParse>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstBaseParse,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(BaseParse::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::disable-passthrough".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_disable_passthrough_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<BaseParse>> BaseParseExt for O {}