gstreamer_video/auto/

video_encoder.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::{VideoCodecFrame, ffi};
use glib::{
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// This base class is for video encoders turning raw video into
    /// encoded video data.
    ///
    /// GstVideoEncoder and subclass should cooperate as follows.
    ///
    /// ## Configuration
    ///
    ///  * Initially, GstVideoEncoder calls `start` when the encoder element
    ///  is activated, which allows subclass to perform any global setup.
    ///  * GstVideoEncoder calls `set_format` to inform subclass of the format
    ///  of input video data that it is about to receive. Subclass should
    ///  setup for encoding and configure base class as appropriate
    ///  (e.g. latency). While unlikely, it might be called more than once,
    ///  if changing input parameters require reconfiguration. Baseclass
    ///  will ensure that processing of current configuration is finished.
    ///  * GstVideoEncoder calls `stop` at end of all processing.
    ///
    /// ## Data processing
    ///
    ///  * Base class collects input data and metadata into a frame and hands
    ///  this to subclass' `handle_frame`.
    ///
    ///  * If codec processing results in encoded data, subclass should call
    ///  [`VideoEncoderExt::finish_frame()`][crate::prelude::VideoEncoderExt::finish_frame()] to have encoded data pushed
    ///  downstream.
    ///
    ///  * If implemented, baseclass calls subclass `pre_push` just prior to
    ///  pushing to allow subclasses to modify some metadata on the buffer.
    ///  If it returns GST_FLOW_OK, the buffer is pushed downstream.
    ///
    ///  * GstVideoEncoderClass will handle both srcpad and sinkpad events.
    ///  Sink events will be passed to subclass if `event` callback has been
    ///  provided.
    ///
    /// ## Shutdown phase
    ///
    ///  * GstVideoEncoder class calls `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 should
    /// also be able to provide fixed src pad caps in `getcaps` by the time it calls
    /// [`VideoEncoderExt::finish_frame()`][crate::prelude::VideoEncoderExt::finish_frame()].
    ///
    /// Things that subclass need to take care of:
    ///
    ///  * Provide pad templates
    ///  * Provide source pad caps before pushing the first buffer
    ///  * Accept data in `handle_frame` and provide encoded results to
    ///  [`VideoEncoderExt::finish_frame()`][crate::prelude::VideoEncoderExt::finish_frame()].
    ///
    ///
    /// ## Adaptive Presets
    ///
    /// [`VideoEncoder`][crate::VideoEncoder] supports adaptive presets, where property values in a
    /// preset file can vary based on the input video resolution and framerate.
    /// This is done using GKeyFile's locale string syntax to define alternative
    /// values for properties.
    ///
    /// For example, a preset file can specify different bitrates for different
    /// resolutions:
    ///
    /// **⚠️ The following code is in  ini ⚠️**
    ///
    /// ``` ini
    /// [Profile YouTube]
    /// bitrate=2500
    /// bitrate[1920x1080]=8000
    /// bitrate[1920x1080@48]=12000
    /// bitrate[3840x2160]=40000
    /// bitrate[3840x2160@48]=60000
    /// ```
    ///
    /// When a preset with alternatives is loaded, the best matching
    /// alternative is applied each time the input format changes, before
    /// the subclass `set_format` method runs.
    ///
    /// Alternative keys use the format `WxH` (matches when the actual pixel
    /// count >= W*H) or `WxH`FPS`` (additionally requires actual fps >= FPS).
    /// The most specific match wins (highest pixel count, then highest fps
    /// threshold). If no alternative matches, the base property value set by
    /// `gst_preset_load_preset()` remains.
    ///
    /// The [`qos`][struct@crate::VideoEncoder#qos] property will enable the Quality-of-Service
    /// features of the encoder which gather statistics about the real-time
    /// performance of the downstream elements. If enabled, subclasses can
    /// use [`VideoEncoderExt::max_encode_time()`][crate::prelude::VideoEncoderExt::max_encode_time()] to check if input frames
    /// are already late and drop them right away to give a chance to the
    /// pipeline to catch up.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `min-force-key-unit-interval`
    ///  Minimum interval between force-keyunit requests in nanoseconds. See
    /// [`VideoEncoderExt::set_min_force_key_unit_interval()`][crate::prelude::VideoEncoderExt::set_min_force_key_unit_interval()] for more details.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `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
    ///
    /// [`VideoEncoderExt`][trait@crate::prelude::VideoEncoderExt], [`trait@gst::prelude::ElementExt`], [`trait@gst::prelude::ObjectExt`], [`trait@glib::ObjectExt`], [`VideoEncoderExtManual`][trait@crate::prelude::VideoEncoderExtManual]
    #[doc(alias = "GstVideoEncoder")]
    pub struct VideoEncoder(Object<ffi::GstVideoEncoder, ffi::GstVideoEncoderClass>) @extends gst::Element, gst::Object;

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

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

unsafe impl Send for VideoEncoder {}
unsafe impl Sync for VideoEncoder {}

/// Trait containing all [`struct@VideoEncoder`] methods.
///
/// # Implementors
///
/// [`VideoEncoder`][struct@crate::VideoEncoder]
pub trait VideoEncoderExt: IsA<VideoEncoder> + 'static {
    /// Helper function that allocates a buffer to hold an encoded video frame
    /// for `self`'s current [`VideoCodecState`][crate::VideoCodecState].
    /// ## `size`
    /// size of the buffer
    ///
    /// # Returns
    ///
    /// allocated buffer
    #[doc(alias = "gst_video_encoder_allocate_output_buffer")]
    fn allocate_output_buffer(&self, size: usize) -> gst::Buffer {
        unsafe {
            from_glib_full(ffi::gst_video_encoder_allocate_output_buffer(
                self.as_ref().to_glib_none().0,
                size,
            ))
        }
    }

    /// Removes `frame` from the list of pending frames, releases it
    /// and posts a QoS message with the frame's details on the bus.
    /// Similar to calling [`finish_frame()`][Self::finish_frame()] without a buffer
    /// attached to `frame`, but this function additionally stores events
    /// from `frame` as pending, to be pushed out alongside the next frame
    /// submitted via [`finish_frame()`][Self::finish_frame()].
    /// ## `frame`
    /// a [`VideoCodecFrame`][crate::VideoCodecFrame]
    #[cfg(feature = "v1_26")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_26")))]
    #[doc(alias = "gst_video_encoder_drop_frame")]
    fn drop_frame(&self, frame: VideoCodecFrame) {
        unsafe {
            ffi::gst_video_encoder_drop_frame(
                self.as_ref().to_glib_none().0,
                frame.into_glib_ptr(),
            );
        }
    }

    /// `frame` must have a valid encoded data buffer, whose metadata fields
    /// are then appropriately set according to frame data or no buffer at
    /// all if the frame should be dropped.
    /// It is subsequently pushed downstream or provided to `pre_push`.
    /// In any case, the frame is considered finished and released.
    ///
    /// If `frame` does not have a buffer attached, it will be dropped, and
    /// a QoS message will be posted on the bus. Events from `frame` will be
    /// pushed out immediately.
    ///
    /// After calling this function the output buffer of the frame is to be
    /// considered read-only. This function will also change the metadata
    /// of the buffer.
    /// ## `frame`
    /// an encoded [`VideoCodecFrame`][crate::VideoCodecFrame]
    ///
    /// # Returns
    ///
    /// a [`gst::FlowReturn`][crate::gst::FlowReturn] resulting from sending data downstream
    #[doc(alias = "gst_video_encoder_finish_frame")]
    fn finish_frame(&self, frame: VideoCodecFrame) -> Result<gst::FlowSuccess, gst::FlowError> {
        unsafe {
            try_from_glib(ffi::gst_video_encoder_finish_frame(
                self.as_ref().to_glib_none().0,
                frame.into_glib_ptr(),
            ))
        }
    }

    /// Determines maximum possible encoding time for `frame` that will
    /// allow it to encode and arrive in time (as determined by QoS events).
    /// In particular, a negative result means encoding in time is no longer possible
    /// and should therefore occur as soon/skippy as possible.
    ///
    /// If no QoS events have been received from downstream, or if
    /// [`qos`][struct@crate::VideoEncoder#qos] is disabled this function returns `G_MAXINT64`.
    /// ## `frame`
    /// a [`VideoCodecFrame`][crate::VideoCodecFrame]
    ///
    /// # Returns
    ///
    /// max decoding time.
    #[doc(alias = "gst_video_encoder_get_max_encode_time")]
    #[doc(alias = "get_max_encode_time")]
    fn max_encode_time(&self, frame: &VideoCodecFrame) -> gst::ClockTimeDiff {
        unsafe {
            ffi::gst_video_encoder_get_max_encode_time(
                self.as_ref().to_glib_none().0,
                frame.to_glib_none().0,
            )
        }
    }

    /// Returns the minimum force-keyunit interval, see [`set_min_force_key_unit_interval()`][Self::set_min_force_key_unit_interval()]
    /// for more details.
    ///
    /// # Returns
    ///
    /// the minimum force-keyunit interval
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "gst_video_encoder_get_min_force_key_unit_interval")]
    #[doc(alias = "get_min_force_key_unit_interval")]
    #[doc(alias = "min-force-key-unit-interval")]
    fn min_force_key_unit_interval(&self) -> Option<gst::ClockTime> {
        unsafe {
            from_glib(ffi::gst_video_encoder_get_min_force_key_unit_interval(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks if `self` is currently configured to handle Quality-of-Service
    /// events from downstream.
    ///
    /// # Returns
    ///
    /// [`true`] if the encoder is configured to perform Quality-of-Service.
    #[doc(alias = "gst_video_encoder_is_qos_enabled")]
    fn is_qos_enabled(&self) -> bool {
        unsafe {
            from_glib(ffi::gst_video_encoder_is_qos_enabled(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Sets the video encoder 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.
    ///
    /// MT safe.
    /// ## `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_video_encoder_merge_tags")]
    fn merge_tags(&self, tags: Option<&gst::TagList>, mode: gst::TagMergeMode) {
        unsafe {
            ffi::gst_video_encoder_merge_tags(
                self.as_ref().to_glib_none().0,
                tags.to_glib_none().0,
                mode.into_glib(),
            );
        }
    }

    /// Returns caps that express `caps` (or sink template caps if `caps` == NULL)
    /// restricted to resolution/format/... combinations supported by downstream
    /// elements (e.g. muxers).
    /// ## `caps`
    /// initial caps
    /// ## `filter`
    /// filter caps
    ///
    /// # Returns
    ///
    /// a [`gst::Caps`][crate::gst::Caps] owned by caller
    #[doc(alias = "gst_video_encoder_proxy_getcaps")]
    fn proxy_getcaps(&self, caps: Option<&gst::Caps>, filter: Option<&gst::Caps>) -> gst::Caps {
        unsafe {
            from_glib_full(ffi::gst_video_encoder_proxy_getcaps(
                self.as_ref().to_glib_none().0,
                caps.to_glib_none().0,
                filter.to_glib_none().0,
            ))
        }
    }

    /// Removes `frame` from list of pending frames and releases it, similar
    /// to calling [`finish_frame()`][Self::finish_frame()] without a buffer attached
    /// to the frame, but does not post a QoS message or do any additional
    /// processing. Events from `frame` are moved to the pending events list.
    /// ## `frame`
    /// a [`VideoCodecFrame`][crate::VideoCodecFrame]
    #[cfg(feature = "v1_26")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_26")))]
    #[doc(alias = "gst_video_encoder_release_frame")]
    fn release_frame(&self, frame: VideoCodecFrame) {
        unsafe {
            ffi::gst_video_encoder_release_frame(
                self.as_ref().to_glib_none().0,
                frame.into_glib_ptr(),
            );
        }
    }

    /// Allows [`VideoEncoder`][crate::VideoEncoder] sub-classes to set the memory `allocator` and
    /// its `params`.
    /// ## `allocator`
    /// the [`gst::Allocator`][crate::gst::Allocator]
    /// ## `params`
    /// the [`gst::AllocationParams`][crate::gst::AllocationParams] of `allocator`
    #[cfg(feature = "v1_30")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_30")))]
    #[doc(alias = "gst_video_encoder_set_allocator")]
    fn set_allocator(
        &self,
        allocator: Option<impl IsA<gst::Allocator>>,
        params: Option<&gst::AllocationParams>,
    ) {
        unsafe {
            ffi::gst_video_encoder_set_allocator(
                self.as_ref().to_glib_none().0,
                allocator.map(|p| p.upcast()).into_glib_ptr(),
                params.to_glib_none().0,
            );
        }
    }

    /// Sets the minimum interval for requesting keyframes based on force-keyunit
    /// events. Setting this to 0 will allow to handle every event, setting this to
    /// `GST_CLOCK_TIME_NONE` causes force-keyunit events to be ignored.
    /// ## `interval`
    /// minimum interval
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "gst_video_encoder_set_min_force_key_unit_interval")]
    #[doc(alias = "min-force-key-unit-interval")]
    fn set_min_force_key_unit_interval(&self, interval: impl Into<Option<gst::ClockTime>>) {
        unsafe {
            ffi::gst_video_encoder_set_min_force_key_unit_interval(
                self.as_ref().to_glib_none().0,
                interval.into().into_glib(),
            );
        }
    }

    /// Request minimal value for PTS passed to handle_frame.
    ///
    /// For streams with reordered frames this can be used to ensure that there
    /// is enough time to accommodate first DTS, which may be less than first PTS
    /// ## `min_pts`
    /// minimal PTS that will be passed to handle_frame
    #[doc(alias = "gst_video_encoder_set_min_pts")]
    fn set_min_pts(&self, min_pts: impl Into<Option<gst::ClockTime>>) {
        unsafe {
            ffi::gst_video_encoder_set_min_pts(
                self.as_ref().to_glib_none().0,
                min_pts.into().into_glib(),
            );
        }
    }

    /// Configures `self` to handle Quality-of-Service events from downstream.
    /// ## `enabled`
    /// the new qos value.
    #[doc(alias = "gst_video_encoder_set_qos_enabled")]
    fn set_qos_enabled(&self, enabled: bool) {
        unsafe {
            ffi::gst_video_encoder_set_qos_enabled(
                self.as_ref().to_glib_none().0,
                enabled.into_glib(),
            );
        }
    }

    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)
    }

    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "min-force-key-unit-interval")]
    fn connect_min_force_key_unit_interval_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_min_force_key_unit_interval_trampoline<
            P: IsA<VideoEncoder>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstVideoEncoder,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(VideoEncoder::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::min-force-key-unit-interval".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_min_force_key_unit_interval_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[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<VideoEncoder>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstVideoEncoder,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(VideoEncoder::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::qos".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_qos_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<VideoEncoder>> VideoEncoderExt for O {}