gstreamer_editing_services/auto/

layer.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
#![allow(deprecated)]

#[cfg(feature = "v1_18")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
use crate::Track;
use crate::{ffi, Asset, Clip, Extractable, MetaContainer, Timeline, TrackType};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// [`Layer`][crate::Layer]-s are responsible for collecting and ordering [`Clip`][crate::Clip]-s.
    ///
    /// A layer within a timeline will have an associated priority,
    /// corresponding to their index within the timeline. A layer with the
    /// index/priority 0 will have the highest priority and the layer with the
    /// largest index will have the lowest priority (the order of priorities,
    /// in this sense, is the _reverse_ of the numerical ordering of the
    /// indices). [`TimelineExt::move_layer()`][crate::prelude::TimelineExt::move_layer()] should be used if you wish to
    /// change how layers are prioritised in a timeline.
    ///
    /// Layers with higher priorities will have their content priorities
    /// over content from lower priority layers, similar to how layers are
    /// used in image editing. For example, if two separate layers both
    /// display video content, then the layer with the higher priority will
    /// have its images shown first. The other layer will only have its image
    /// shown if the higher priority layer has no content at the given
    /// playtime, or is transparent in some way. Audio content in separate
    /// layers will simply play in addition.
    ///
    /// ## Properties
    ///
    ///
    /// #### `auto-transition`
    ///  Whether to automatically create a [`TransitionClip`][crate::TransitionClip] whenever two
    /// [`Source`][crate::Source]-s that both belong to a [`Clip`][crate::Clip] in the layer overlap.
    /// See [`Timeline`][crate::Timeline] for what counts as an overlap.
    ///
    /// When a layer is added to a [`Timeline`][crate::Timeline], if this property is left as
    /// [`false`], but the timeline's [`auto-transition`][struct@crate::Timeline#auto-transition] is [`true`], it
    /// will be set to [`true`] as well.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `priority`
    ///  The priority of the layer in the [`Timeline`][crate::Timeline]. 0 is the highest
    /// priority. Conceptually, a timeline is a stack of layers,
    /// and the priority of the layer represents its position in the stack. Two
    /// layers should not have the same priority within a given GESTimeline.
    ///
    /// Note that the timeline needs to be committed (with `ges_timeline_commit`)
    /// for the change to be taken into account.
    ///
    /// Readable | Writeable
    ///
    /// ## Signals
    ///
    ///
    /// #### `active-changed`
    ///  Will be emitted whenever the layer is activated or deactivated
    /// for some [`Track`][crate::Track]. See [`LayerExt::set_active_for_tracks()`][crate::prelude::LayerExt::set_active_for_tracks()].
    ///
    ///
    ///
    ///
    /// #### `clip-added`
    ///  Will be emitted after the clip is added to the layer.
    ///
    ///
    ///
    ///
    /// #### `clip-removed`
    ///  Will be emitted after the clip is removed from the layer.
    ///
    ///
    /// <details><summary><h4>MetaContainer</h4></summary>
    ///
    ///
    /// #### `notify-meta`
    ///  This is emitted for a meta container whenever the metadata under one
    /// of its fields changes, is set for the first time, or is removed. In
    /// the latter case, `value` will be [`None`].
    ///
    /// Detailed
    /// </details>
    ///
    /// # Implements
    ///
    /// [`LayerExt`][trait@crate::prelude::LayerExt], [`trait@glib::ObjectExt`], [`ExtractableExt`][trait@crate::prelude::ExtractableExt], [`MetaContainerExt`][trait@crate::prelude::MetaContainerExt]
    #[doc(alias = "GESLayer")]
    pub struct Layer(Object<ffi::GESLayer, ffi::GESLayerClass>) @implements Extractable, MetaContainer;

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

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

    /// Creates a new layer.
    ///
    /// # Returns
    ///
    /// A new layer.
    #[doc(alias = "ges_layer_new")]
    pub fn new() -> Layer {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::ges_layer_new()) }
    }
}

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

/// Trait containing all [`struct@Layer`] methods.
///
/// # Implementors
///
/// [`Layer`][struct@crate::Layer]
pub trait LayerExt: IsA<Layer> + 'static {
    /// See [`add_asset_full()`][Self::add_asset_full()], which also gives an error.
    /// ## `asset`
    /// The asset to extract the new clip from
    /// ## `start`
    /// The [`start`][struct@crate::TimelineElement#start] value to set on the new clip
    /// If `start == `GST_CLOCK_TIME_NONE``, it will be added to the end
    /// of `self`, i.e. it will be set to `self`'s duration
    /// ## `inpoint`
    /// The [`in-point`][struct@crate::TimelineElement#in-point] value to set on the new
    /// clip
    /// ## `duration`
    /// The [`duration`][struct@crate::TimelineElement#duration] value to set on the new
    /// clip
    /// ## `track_types`
    /// The [`supported-formats`][struct@crate::Clip#supported-formats] to set on the the new
    /// clip, or [`TrackType::UNKNOWN`][crate::TrackType::UNKNOWN] to use the default
    ///
    /// # Returns
    ///
    /// The newly created clip.
    #[doc(alias = "ges_layer_add_asset")]
    fn add_asset(
        &self,
        asset: &impl IsA<Asset>,
        start: impl Into<Option<gst::ClockTime>>,
        inpoint: impl Into<Option<gst::ClockTime>>,
        duration: impl Into<Option<gst::ClockTime>>,
        track_types: TrackType,
    ) -> Result<Clip, glib::BoolError> {
        unsafe {
            Option::<_>::from_glib_none(ffi::ges_layer_add_asset(
                self.as_ref().to_glib_none().0,
                asset.as_ref().to_glib_none().0,
                start.into().into_glib(),
                inpoint.into().into_glib(),
                duration.into().into_glib(),
                track_types.into_glib(),
            ))
            .ok_or_else(|| glib::bool_error!("Failed to add asset"))
        }
    }

    /// Extracts a new clip from an asset and adds it to the layer with
    /// the given properties.
    /// ## `asset`
    /// The asset to extract the new clip from
    /// ## `start`
    /// The [`start`][struct@crate::TimelineElement#start] value to set on the new clip
    /// If `start == `GST_CLOCK_TIME_NONE``, it will be added to the end
    /// of `self`, i.e. it will be set to `self`'s duration
    /// ## `inpoint`
    /// The [`in-point`][struct@crate::TimelineElement#in-point] value to set on the new
    /// clip
    /// ## `duration`
    /// The [`duration`][struct@crate::TimelineElement#duration] value to set on the new
    /// clip
    /// ## `track_types`
    /// The [`supported-formats`][struct@crate::Clip#supported-formats] to set on the the new
    /// clip, or [`TrackType::UNKNOWN`][crate::TrackType::UNKNOWN] to use the default
    ///
    /// # Returns
    ///
    /// The newly created clip.
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "ges_layer_add_asset_full")]
    fn add_asset_full(
        &self,
        asset: &impl IsA<Asset>,
        start: impl Into<Option<gst::ClockTime>>,
        inpoint: impl Into<Option<gst::ClockTime>>,
        duration: impl Into<Option<gst::ClockTime>>,
        track_types: TrackType,
    ) -> Result<Clip, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::ges_layer_add_asset_full(
                self.as_ref().to_glib_none().0,
                asset.as_ref().to_glib_none().0,
                start.into().into_glib(),
                inpoint.into().into_glib(),
                duration.into().into_glib(),
                track_types.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_none(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// See [`add_clip_full()`][Self::add_clip_full()], which also gives an error.
    /// ## `clip`
    /// The clip to add
    ///
    /// # Returns
    ///
    /// [`true`] if `clip` was properly added to `self`, or [`false`]
    /// if `self` refused to add `clip`.
    #[doc(alias = "ges_layer_add_clip")]
    fn add_clip(&self, clip: &impl IsA<Clip>) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::ges_layer_add_clip(
                    self.as_ref().to_glib_none().0,
                    clip.as_ref().to_glib_none().0
                ),
                "Failed to add clip"
            )
        }
    }

    /// Adds the given clip to the layer. If the method succeeds, the layer
    /// will take ownership of the clip.
    ///
    /// This method will fail and return [`false`] if `clip` already resides in
    /// some layer. It can also fail if the additional clip breaks some
    /// compositional rules (see [`TimelineElement`][crate::TimelineElement]).
    /// ## `clip`
    /// The clip to add
    ///
    /// # Returns
    ///
    /// [`true`] if `clip` was properly added to `self`, or [`false`]
    /// if `self` refused to add `clip`.
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "ges_layer_add_clip_full")]
    fn add_clip_full(&self, clip: &impl IsA<Clip>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::ges_layer_add_clip_full(
                self.as_ref().to_glib_none().0,
                clip.as_ref().to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Gets whether the layer is active for the given track. See
    /// [`set_active_for_tracks()`][Self::set_active_for_tracks()].
    /// ## `track`
    /// The [`Track`][crate::Track] to check if `self` is currently active for
    ///
    /// # Returns
    ///
    /// [`true`] if `self` is active for `track`, or [`false`] otherwise.
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "ges_layer_get_active_for_track")]
    #[doc(alias = "get_active_for_track")]
    fn is_active_for_track(&self, track: &impl IsA<Track>) -> bool {
        unsafe {
            from_glib(ffi::ges_layer_get_active_for_track(
                self.as_ref().to_glib_none().0,
                track.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the [`auto-transition`][struct@crate::Layer#auto-transition] of the layer.
    ///
    /// # Returns
    ///
    /// [`true`] if transitions are automatically added to `self`.
    #[doc(alias = "ges_layer_get_auto_transition")]
    #[doc(alias = "get_auto_transition")]
    #[doc(alias = "auto-transition")]
    fn is_auto_transition(&self) -> bool {
        unsafe {
            from_glib(ffi::ges_layer_get_auto_transition(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Get the [`Clip`][crate::Clip]-s contained in this layer.
    ///
    /// # Returns
    ///
    /// A list of clips in
    /// `self`.
    #[doc(alias = "ges_layer_get_clips")]
    #[doc(alias = "get_clips")]
    fn clips(&self) -> Vec<Clip> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::ges_layer_get_clips(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the clips within the layer that appear between `start` and `end`.
    /// ## `start`
    /// Start of the interval
    /// ## `end`
    /// End of the interval
    ///
    /// # Returns
    ///
    /// A list of [`Clip`][crate::Clip]-s
    /// that intersect the interval `[start, end)` in `self`.
    #[doc(alias = "ges_layer_get_clips_in_interval")]
    #[doc(alias = "get_clips_in_interval")]
    fn clips_in_interval(
        &self,
        start: impl Into<Option<gst::ClockTime>>,
        end: impl Into<Option<gst::ClockTime>>,
    ) -> Vec<Clip> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::ges_layer_get_clips_in_interval(
                self.as_ref().to_glib_none().0,
                start.into().into_glib(),
                end.into().into_glib(),
            ))
        }
    }

    /// Retrieves the duration of the layer, which is the difference
    /// between the start of the layer (always time 0) and the end (which will
    /// be the end time of the final clip).
    ///
    /// # Returns
    ///
    /// The duration of `self`.
    #[doc(alias = "ges_layer_get_duration")]
    #[doc(alias = "get_duration")]
    fn duration(&self) -> gst::ClockTime {
        unsafe {
            try_from_glib(ffi::ges_layer_get_duration(self.as_ref().to_glib_none().0))
                .expect("mandatory glib value is None")
        }
    }

    /// Get the priority of the layer. When inside a timeline, this is its
    /// index in the timeline. See [`TimelineExt::move_layer()`][crate::prelude::TimelineExt::move_layer()].
    ///
    /// # Returns
    ///
    /// The priority of `self` within its timeline.
    #[doc(alias = "ges_layer_get_priority")]
    #[doc(alias = "get_priority")]
    fn priority(&self) -> u32 {
        unsafe { ffi::ges_layer_get_priority(self.as_ref().to_glib_none().0) }
    }

    /// Gets the timeline that the layer is a part of.
    ///
    /// # Returns
    ///
    /// The timeline that `self`
    /// is currently part of, or [`None`] if it is not associated with any
    /// timeline.
    #[doc(alias = "ges_layer_get_timeline")]
    #[doc(alias = "get_timeline")]
    fn timeline(&self) -> Option<Timeline> {
        unsafe { from_glib_none(ffi::ges_layer_get_timeline(self.as_ref().to_glib_none().0)) }
    }

    /// Convenience method to check if the layer is empty (doesn't contain
    /// any [`Clip`][crate::Clip]), or not.
    ///
    /// # Returns
    ///
    /// [`true`] if `self` is empty, [`false`] if it contains at least
    /// one clip.
    #[doc(alias = "ges_layer_is_empty")]
    fn is_empty(&self) -> bool {
        unsafe { from_glib(ffi::ges_layer_is_empty(self.as_ref().to_glib_none().0)) }
    }

    /// Removes the given clip from the layer.
    /// ## `clip`
    /// The clip to remove
    ///
    /// # Returns
    ///
    /// [`true`] if `clip` was removed from `self`, or [`false`] if the
    /// operation failed.
    #[doc(alias = "ges_layer_remove_clip")]
    fn remove_clip(&self, clip: &impl IsA<Clip>) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::ges_layer_remove_clip(
                    self.as_ref().to_glib_none().0,
                    clip.as_ref().to_glib_none().0
                ),
                "Failed to remove clip"
            )
        }
    }

    /// Activate or deactivate track elements in `tracks` (or in all tracks if `tracks`
    /// is [`None`]).
    ///
    /// When a layer is deactivated for a track, all the [`TrackElement`][crate::TrackElement]-s in
    /// the track that belong to a [`Clip`][crate::Clip] in the layer will no longer be
    /// active in the track, regardless of their individual
    /// [`active`][struct@crate::TrackElement#active] value.
    ///
    /// Note that by default a layer will be active for all of its
    /// timeline's tracks.
    /// ## `active`
    /// Whether elements in `tracks` should be active or not
    /// ## `tracks`
    /// The list of
    /// tracks `self` should be (de-)active in, or [`None`] to include all the tracks
    /// in the `self`'s timeline
    ///
    /// # Returns
    ///
    /// [`true`] if the operation worked [`false`] otherwise.
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "ges_layer_set_active_for_tracks")]
    fn set_active_for_tracks(&self, active: bool, tracks: &[Track]) -> bool {
        unsafe {
            from_glib(ffi::ges_layer_set_active_for_tracks(
                self.as_ref().to_glib_none().0,
                active.into_glib(),
                tracks.to_glib_none().0,
            ))
        }
    }

    /// Sets [`auto-transition`][struct@crate::Layer#auto-transition] for the layer. Use
    /// [`TimelineExt::set_auto_transition()`][crate::prelude::TimelineExt::set_auto_transition()] if you want all layers within a
    /// [`Timeline`][crate::Timeline] to have [`auto-transition`][struct@crate::Layer#auto-transition] set to [`true`]. Use this
    /// method if you want different values for different layers (and make sure
    /// to keep [`auto-transition`][struct@crate::Timeline#auto-transition] as [`false`] for the corresponding
    /// timeline).
    /// ## `auto_transition`
    /// Whether transitions should be automatically added to
    /// the layer
    #[doc(alias = "ges_layer_set_auto_transition")]
    #[doc(alias = "auto-transition")]
    fn set_auto_transition(&self, auto_transition: bool) {
        unsafe {
            ffi::ges_layer_set_auto_transition(
                self.as_ref().to_glib_none().0,
                auto_transition.into_glib(),
            );
        }
    }

    /// Sets the layer to the given priority. See [`priority`][struct@crate::Layer#priority].
    ///
    /// # Deprecated since 1.16
    ///
    /// use `ges_timeline_move_layer` instead. This deprecation means
    /// that you will not need to handle layer priorities at all yourself, GES
    /// will make sure there is never 'gaps' between layer priorities.
    /// ## `priority`
    /// The priority to set
    #[cfg_attr(feature = "v1_16", deprecated = "Since 1.16")]
    #[allow(deprecated)]
    #[doc(alias = "ges_layer_set_priority")]
    #[doc(alias = "priority")]
    fn set_priority(&self, priority: u32) {
        unsafe {
            ffi::ges_layer_set_priority(self.as_ref().to_glib_none().0, priority);
        }
    }

    #[doc(alias = "ges_layer_set_timeline")]
    fn set_timeline(&self, timeline: &impl IsA<Timeline>) {
        unsafe {
            ffi::ges_layer_set_timeline(
                self.as_ref().to_glib_none().0,
                timeline.as_ref().to_glib_none().0,
            );
        }
    }

    //#[cfg(feature = "v1_18")]
    //#[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    //#[doc(alias = "active-changed")]
    //fn connect_active_changed<Unsupported or ignored types>(&self, f: F) -> SignalHandlerId {
    //    Empty ctype tracks: *.PtrArray TypeId { ns_id: 1, id: 17 }
    //}

    /// Will be emitted after the clip is added to the layer.
    /// ## `clip`
    /// The clip that was added
    #[doc(alias = "clip-added")]
    fn connect_clip_added<F: Fn(&Self, &Clip) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn clip_added_trampoline<P: IsA<Layer>, F: Fn(&P, &Clip) + 'static>(
            this: *mut ffi::GESLayer,
            clip: *mut ffi::GESClip,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Layer::from_glib_borrow(this).unsafe_cast_ref(),
                &from_glib_borrow(clip),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"clip-added".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    clip_added_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Will be emitted after the clip is removed from the layer.
    /// ## `clip`
    /// The clip that was removed
    #[doc(alias = "clip-removed")]
    fn connect_clip_removed<F: Fn(&Self, &Clip) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn clip_removed_trampoline<P: IsA<Layer>, F: Fn(&P, &Clip) + 'static>(
            this: *mut ffi::GESLayer,
            clip: *mut ffi::GESClip,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Layer::from_glib_borrow(this).unsafe_cast_ref(),
                &from_glib_borrow(clip),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"clip-removed".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    clip_removed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

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

    #[cfg_attr(feature = "v1_16", deprecated = "Since 1.16")]
    #[doc(alias = "priority")]
    fn connect_priority_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_priority_trampoline<P: IsA<Layer>, F: Fn(&P) + 'static>(
            this: *mut ffi::GESLayer,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Layer::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::priority".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_priority_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Layer>> LayerExt for O {}