gstreamer/auto/

functions.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, Bin, ClockTime, DebugGraphDetails, DebugLevel, Element, StackTraceFlags};
use glib::{prelude::*, translate::*};

/// Adds a memory ringbuffer based debug logger that stores up to
/// `max_size_per_thread` bytes of logs per thread and times out threads after
/// `thread_timeout` seconds of inactivity.
///
/// Logs can be fetched with [`debug_ring_buffer_logger_get_logs()`][crate::debug_ring_buffer_logger_get_logs()] and the
/// logger can be removed again with [`debug_remove_ring_buffer_logger()`][crate::debug_remove_ring_buffer_logger()].
/// Only one logger at a time is possible.
/// ## `max_size_per_thread`
/// Maximum size of log per thread in bytes
/// ## `thread_timeout`
/// Timeout for threads in seconds
#[doc(alias = "gst_debug_add_ring_buffer_logger")]
pub fn debug_add_ring_buffer_logger(max_size_per_thread: u32, thread_timeout: u32) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_add_ring_buffer_logger(max_size_per_thread, thread_timeout);
    }
}

/// To aid debugging applications one can use this method to obtain the whole
/// network of gstreamer elements that form the pipeline into a dot file.
/// This data can be processed with graphviz to get an image.
/// ## `bin`
/// the top-level pipeline that should be analyzed
/// ## `details`
/// type of [`DebugGraphDetails`][crate::DebugGraphDetails] to use
///
/// # Returns
///
/// a string containing the pipeline in graphviz
/// dot format.
#[doc(alias = "gst_debug_bin_to_dot_data")]
pub fn debug_bin_to_dot_data(bin: &impl IsA<Bin>, details: DebugGraphDetails) -> glib::GString {
    skip_assert_initialized!();
    unsafe {
        from_glib_full(ffi::gst_debug_bin_to_dot_data(
            bin.as_ref().to_glib_none().0,
            details.into_glib(),
        ))
    }
}

/// To aid debugging applications one can use this method to write out the whole
/// network of gstreamer elements that form the pipeline into a dot file.
/// This file can be processed with graphviz to get an image.
///
/// **⚠️ The following code is in  shell ⚠️**
///
/// ``` shell
///  dot -Tpng -oimage.png graph_lowlevel.dot
/// ```
/// ## `bin`
/// the top-level pipeline that should be analyzed
/// ## `details`
/// type of [`DebugGraphDetails`][crate::DebugGraphDetails] to use
/// ## `file_name`
/// output base filename (e.g. "myplayer")
#[doc(alias = "gst_debug_bin_to_dot_file")]
pub fn debug_bin_to_dot_file(
    bin: &impl IsA<Bin>,
    details: DebugGraphDetails,
    file_name: impl AsRef<std::path::Path>,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_bin_to_dot_file(
            bin.as_ref().to_glib_none().0,
            details.into_glib(),
            file_name.as_ref().to_glib_none().0,
        );
    }
}

/// This works like [`debug_bin_to_dot_file()`][crate::debug_bin_to_dot_file()], but adds the current timestamp
/// to the filename, so that it can be used to take multiple snapshots.
/// ## `bin`
/// the top-level pipeline that should be analyzed
/// ## `details`
/// type of [`DebugGraphDetails`][crate::DebugGraphDetails] to use
/// ## `file_name`
/// output base filename (e.g. "myplayer")
#[doc(alias = "gst_debug_bin_to_dot_file_with_ts")]
pub fn debug_bin_to_dot_file_with_ts(
    bin: &impl IsA<Bin>,
    details: DebugGraphDetails,
    file_name: impl AsRef<std::path::Path>,
) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_bin_to_dot_file_with_ts(
            bin.as_ref().to_glib_none().0,
            details.into_glib(),
            file_name.as_ref().to_glib_none().0,
        );
    }
}

/// Returns the default threshold that is used for new categories.
///
/// # Returns
///
/// the default threshold level
#[doc(alias = "gst_debug_get_default_threshold")]
pub fn debug_get_default_threshold() -> DebugLevel {
    skip_assert_initialized!();
    unsafe { from_glib(ffi::gst_debug_get_default_threshold()) }
}

/// ## `flags`
/// A set of [`StackTraceFlags`][crate::StackTraceFlags] to determine how the stack trace should
/// look like. Pass `GST_STACK_TRACE_SHOW_NONE` to retrieve a minimal backtrace.
///
/// # Returns
///
/// a stack trace, if libunwind or glibc backtrace are
/// present, else [`None`].
#[doc(alias = "gst_debug_get_stack_trace")]
pub fn debug_get_stack_trace(flags: StackTraceFlags) -> Result<glib::GString, glib::BoolError> {
    skip_assert_initialized!();
    unsafe {
        Option::<_>::from_glib_full(ffi::gst_debug_get_stack_trace(flags.into_glib()))
            .ok_or_else(|| glib::bool_error!("Failed to get stack trace"))
    }
}

/// Checks if debugging output is activated.
///
/// # Returns
///
/// [`true`], if debugging is activated
#[doc(alias = "gst_debug_is_active")]
pub fn debug_is_active() -> bool {
    skip_assert_initialized!();
    unsafe { from_glib(ffi::gst_debug_is_active()) }
}

/// Checks if the debugging output should be colored.
///
/// # Returns
///
/// [`true`], if the debug output should be colored.
#[doc(alias = "gst_debug_is_colored")]
pub fn debug_is_colored() -> bool {
    skip_assert_initialized!();
    unsafe { from_glib(ffi::gst_debug_is_colored()) }
}

/// If libunwind, glibc backtrace or DbgHelp are present
/// a stack trace is printed.
#[doc(alias = "gst_debug_print_stack_trace")]
pub fn debug_print_stack_trace() {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_print_stack_trace();
    }
}

/// Removes any previously added ring buffer logger with
/// [`debug_add_ring_buffer_logger()`][crate::debug_add_ring_buffer_logger()].
#[doc(alias = "gst_debug_remove_ring_buffer_logger")]
pub fn debug_remove_ring_buffer_logger() {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_remove_ring_buffer_logger();
    }
}

/// Fetches the current logs per thread from the ring buffer logger. See
/// [`debug_add_ring_buffer_logger()`][crate::debug_add_ring_buffer_logger()] for details.
///
/// # Returns
///
/// NULL-terminated array of
/// strings with the debug output per thread
#[doc(alias = "gst_debug_ring_buffer_logger_get_logs")]
pub fn debug_ring_buffer_logger_get_logs() -> Vec<glib::GString> {
    skip_assert_initialized!();
    unsafe { FromGlibPtrContainer::from_glib_full(ffi::gst_debug_ring_buffer_logger_get_logs()) }
}

/// If activated, debugging messages are sent to the debugging
/// handlers.
/// It makes sense to deactivate it for speed issues.
/// > This function is not threadsafe. It makes sense to only call it
/// during initialization.
/// ## `active`
/// Whether to use debugging output or not
#[doc(alias = "gst_debug_set_active")]
pub fn debug_set_active(active: bool) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_set_active(active.into_glib());
    }
}

/// Sets or unsets the use of coloured debugging output.
/// Same as gst_debug_set_color_mode () with the argument being
/// being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF.
///
/// This function may be called before `gst_init()`.
/// ## `colored`
/// Whether to use colored output or not
#[doc(alias = "gst_debug_set_colored")]
pub fn debug_set_colored(colored: bool) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_set_colored(colored.into_glib());
    }
}

/// Sets the default threshold to the given level and updates all categories to
/// use this threshold.
///
/// This function may be called before `gst_init()`.
/// ## `level`
/// level to set
#[doc(alias = "gst_debug_set_default_threshold")]
pub fn debug_set_default_threshold(level: DebugLevel) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_set_default_threshold(level.into_glib());
    }
}

/// Sets all categories which match the given glob style pattern to the given
/// level.
/// ## `name`
/// name of the categories to set
/// ## `level`
/// level to set them to
#[doc(alias = "gst_debug_set_threshold_for_name")]
pub fn debug_set_threshold_for_name(name: &str, level: DebugLevel) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_set_threshold_for_name(name.to_glib_none().0, level.into_glib());
    }
}

/// Sets the debug logging wanted in the same form as with the GST_DEBUG
/// environment variable. You can use wildcards such as `*`, but note that
/// the order matters when you use wild cards, e.g. `foosrc:6,*src:3,*:2` sets
/// everything to log level 2.
/// ## `list`
/// comma-separated list of "category:level" pairs to be used
///  as debug logging levels
/// ## `reset`
/// [`true`] to clear all previously-set debug levels before setting
///  new thresholds
/// [`false`] if adding the threshold described by `list` to the one already set.
#[doc(alias = "gst_debug_set_threshold_from_string")]
pub fn debug_set_threshold_from_string(list: &str, reset: bool) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_set_threshold_from_string(list.to_glib_none().0, reset.into_glib());
    }
}

/// Resets all categories with the given name back to the default level.
/// ## `name`
/// name of the categories to set
#[doc(alias = "gst_debug_unset_threshold_for_name")]
pub fn debug_unset_threshold_for_name(name: &str) {
    skip_assert_initialized!();
    unsafe {
        ffi::gst_debug_unset_threshold_for_name(name.to_glib_none().0);
    }
}

/// This helper is mostly helpful for plugins that need to
/// inspect the folder of the main executable to determine
/// their set of features.
///
/// When a plugin is initialized from the gst-plugin-scanner
/// external process, the returned path will be the same as from the
/// parent process.
///
/// # Returns
///
/// The path of the executable that
///  initialized GStreamer, or [`None`] if it could not be determined.
#[doc(alias = "gst_get_main_executable_path")]
#[doc(alias = "get_main_executable_path")]
pub fn main_executable_path() -> Result<glib::GString, glib::BoolError> {
    assert_initialized_main_thread!();
    unsafe {
        Option::<_>::from_glib_none(ffi::gst_get_main_executable_path())
            .ok_or_else(|| glib::bool_error!("Failed to get main executable path"))
    }
}

/// This is a convenience wrapper around [`parse_launch()`][crate::parse_launch()] to create a
/// [`Bin`][crate::Bin] from a gst-launch-style pipeline description. See
/// [`parse_launch()`][crate::parse_launch()] and the gst-launch man page for details about the
/// syntax. Ghost pads on the bin for unlinked source or sink pads
/// within the bin can automatically be created (but only a maximum of
/// one ghost pad for each direction will be created; if you expect
/// multiple unlinked source pads or multiple unlinked sink pads
/// and want them all ghosted, you will have to create the ghost pads
/// yourself).
/// ## `bin_description`
/// command line describing the bin
/// ## `ghost_unlinked_pads`
/// whether to automatically create ghost pads
///  for unlinked source or sink pads within the bin
///
/// # Returns
///
/// a
///  newly-created bin, or [`None`] if an error occurred.
#[doc(alias = "gst_parse_bin_from_description")]
pub fn parse_bin_from_description(
    bin_description: &str,
    ghost_unlinked_pads: bool,
) -> Result<Bin, glib::Error> {
    assert_initialized_main_thread!();
    unsafe {
        let mut error = std::ptr::null_mut();
        let ret = ffi::gst_parse_bin_from_description(
            bin_description.to_glib_none().0,
            ghost_unlinked_pads.into_glib(),
            &mut error,
        );
        if error.is_null() {
            Ok(from_glib_none(ret))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Create a new pipeline based on command line syntax.
/// Please note that you might get a return value that is not [`None`] even though
/// the `error` is set. In this case there was a recoverable parsing error and you
/// can try to play the pipeline.
///
/// To create a sub-pipeline (bin) for embedding into an existing pipeline
/// use [`parse_bin_from_description()`][crate::parse_bin_from_description()].
/// ## `pipeline_description`
/// the command line describing the pipeline
///
/// # Returns
///
/// a new element on success, [`None`] on
///  failure. If more than one toplevel element is specified by the
///  `pipeline_description`, all elements are put into a [`Pipeline`][crate::Pipeline], which
///  than is returned.
#[doc(alias = "gst_parse_launch")]
pub fn parse_launch(pipeline_description: &str) -> Result<Element, glib::Error> {
    assert_initialized_main_thread!();
    unsafe {
        let mut error = std::ptr::null_mut();
        let ret = ffi::gst_parse_launch(pipeline_description.to_glib_none().0, &mut error);
        if error.is_null() {
            Ok(from_glib_none(ret))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Create a new element based on command line syntax.
/// `error` will contain an error message if an erroneous pipeline is specified.
/// An error does not mean that the pipeline could not be constructed.
/// ## `argv`
/// null-terminated array of arguments
///
/// # Returns
///
/// a new element on success and [`None`]
/// on failure.
#[doc(alias = "gst_parse_launchv")]
pub fn parse_launchv(argv: &[&str]) -> Result<Element, glib::Error> {
    assert_initialized_main_thread!();
    unsafe {
        let mut error = std::ptr::null_mut();
        let ret = ffi::gst_parse_launchv(argv.to_glib_none().0, &mut error);
        if error.is_null() {
            Ok(from_glib_none(ret))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Forces GStreamer to re-scan its plugin paths and update the default
/// plugin registry.
///
/// Applications will almost never need to call this function, it is only
/// useful if the application knows new plugins have been installed (or old
/// ones removed) since the start of the application (or, to be precise, the
/// first call to `gst_init()`) and the application wants to make use of any
/// newly-installed plugins without restarting the application.
///
/// Applications should assume that the registry update is neither atomic nor
/// thread-safe and should therefore not have any dynamic pipelines running
/// (including the playbin and decodebin elements) and should also not create
/// any elements or access the GStreamer registry while the update is in
/// progress.
///
/// Note that this function may block for a significant amount of time.
///
/// # Returns
///
/// [`true`] if the registry has been updated successfully (does not
///  imply that there were changes), otherwise [`false`].
#[doc(alias = "gst_update_registry")]
pub fn update_registry() -> Result<(), glib::error::BoolError> {
    assert_initialized_main_thread!();
    unsafe {
        glib::result_from_gboolean!(ffi::gst_update_registry(), "Failed to update the registry")
    }
}

/// Get a timestamp as GstClockTime to be used for interval measurements.
/// The timestamp should not be interpreted in any other way.
///
/// # Returns
///
/// the timestamp
#[doc(alias = "gst_util_get_timestamp")]
pub fn util_get_timestamp() -> ClockTime {
    skip_assert_initialized!();
    unsafe { try_from_glib(ffi::gst_util_get_timestamp()).expect("mandatory glib value is None") }
}

/// Gets the version number of the GStreamer library.
///
/// # Returns
///
///
/// ## `major`
/// pointer to a guint to store the major version number
///
/// ## `minor`
/// pointer to a guint to store the minor version number
///
/// ## `micro`
/// pointer to a guint to store the micro version number
///
/// ## `nano`
/// pointer to a guint to store the nano version number
#[doc(alias = "gst_version")]
pub fn version() -> (u32, u32, u32, u32) {
    skip_assert_initialized!();
    unsafe {
        let mut major = std::mem::MaybeUninit::uninit();
        let mut minor = std::mem::MaybeUninit::uninit();
        let mut micro = std::mem::MaybeUninit::uninit();
        let mut nano = std::mem::MaybeUninit::uninit();
        ffi::gst_version(
            major.as_mut_ptr(),
            minor.as_mut_ptr(),
            micro.as_mut_ptr(),
            nano.as_mut_ptr(),
        );
        (
            major.assume_init(),
            minor.assume_init(),
            micro.assume_init(),
            nano.assume_init(),
        )
    }
}

/// This function returns a string that is useful for describing this version
/// of GStreamer to the outside world: user agent strings, logging, ...
///
/// # Returns
///
/// a newly allocated string describing this version
///  of GStreamer.
#[doc(alias = "gst_version_string")]
pub fn version_string() -> glib::GString {
    skip_assert_initialized!();
    unsafe { from_glib_full(ffi::gst_version_string()) }
}