Struct gstreamer_editing_services::Clip

source · [−]

#[repr(transparent)]
pub struct Clip { /* private fields */ }

Expand description

Clip-s are the core objects of a Layer. Each clip may exist in a single layer but may control several TrackElement-s that span several Track-s. A clip will ensure that all its children share the same property::TimelineElement::start and property::TimelineElement::duration in their tracks, which will match the property::TimelineElement::start and property::TimelineElement::duration of the clip itself. Therefore, changing the timing of the clip will change the timing of the children, and a change in the timing of a child will change the timing of the clip and subsequently all its siblings. As such, a clip can be treated as a singular object in its layer.

For most uses of a Timeline, it is often sufficient to only interact with Clip-s directly, which will take care of creating and organising the elements of the timeline’s tracks.

Core Children

In more detail, clips will usually have some core TrackElement children, which are created by the clip when it is added to a layer in a timeline. The type and form of these core children will depend on the clip’s subclass. You can use TrackElementExt::is_core() to determine whether a track element is considered such a core track element. Note, if a core track element is part of a clip, it will always be treated as a core child of the clip. You can connect to the signal::Container::child-added signal to be notified of their creation.

When a child is added to a clip, the timeline will select its tracks using signal::Timeline::select-tracks-for-object. Note that it may be the case that the child will still have no set property::TrackElement::track after this process. For example, if the timeline does not have a track of the corresponding property::Track::track-type. A clip can safely contain such children, which may have their track set later, although they will play no functioning role in the timeline in the meantime.

If a clip may create track elements with various property::TrackElement::track-type(s), such as a UriClip, but you only want it to create a subset of these types, you should set the property::Clip::supported-formats of the clip to the subset of types. This should be done before adding the clip to a layer.

If a clip will produce several core elements of the same property::TrackElement::track-type, you should connect to the timeline’s signal::Timeline::select-tracks-for-object signal to coordinate which tracks each element should land in. Note, no two core children within a clip can share the same Track, so you should not select the same track for two separate core children. Provided you stick to this rule, it is still safe to select several tracks for the same core child, the core child will be copied into the additional tracks. You can manually add the child to more tracks later using ClipExt::add_child_to_track(). If you do not wish to use a core child, you can always select no track.

The property::TimelineElement::in-point of the clip will control the property::TimelineElement::in-point of its core children to be the same value if their property::TrackElement::has-internal-source is set to true.

The property::TimelineElement::max-duration of the clip is the minimum property::TimelineElement::max-duration of its core children. If you set its value to anything other than its current value, this will also set the property::TimelineElement::max-duration of all its core children to the same value if their property::TrackElement::has-internal-source is set to true. As a special case, whilst a clip does not yet have any core children, its property::TimelineElement::max-duration may be set to indicate what its value will be once they are created.

Effects

Some subclasses (SourceClip and BaseEffectClip) may also allow their objects to have additional non-core BaseEffect-s elements as children. These are additional effects that are applied to the output data of the core elements. They can be added to the clip using ClipExt::add_top_effect(), which will take care of adding the effect to the timeline’s tracks. The new effect will be placed between the clip’s core track elements and its other effects. As such, the newly added effect will be applied to any source data before the other existing effects. You can change the ordering of effects using ClipExt::set_top_effect_index().

Tracks are selected for top effects in the same way as core children. If you add a top effect to a clip before it is part of a timeline, and later add the clip to a timeline, the track selection for the top effects will occur just after the track selection for the core children. If you add a top effect to a clip that is already part of a timeline, the track selection will occur immediately. Since a top effect must be applied on top of a core child, if you use signal::Timeline::select-tracks-for-object, you should ensure that the added effects are destined for a Track that already contains a core child.

In addition, if the core child in the track is not property::TrackElement::active, then neither can any of its effects be property::TrackElement::active. Therefore, if a core child is made in-active, all of the additional effects in the same track will also become in-active. Similarly, if an effect is set to be active, then the core child will also become active, but other effects will be left alone. Finally, if an active effect is added to the track of an in-active core child, it will become in-active as well. Note, in contrast, setting a core child to be active, or an effect to be in-active will not change the other children in the same track.

Time Effects

Some effects also change the timing of their data (see BaseEffect for what counts as a time effect). Note that a BaseEffectClip will refuse time effects, but a Source will allow them.

When added to a clip, time effects may adjust the timing of other children in the same track. Similarly, when changing the order of effects, making them (in)-active, setting their time property values or removing time effects. These can cause the property::Clip::duration-limit to change in value. However, if such an operation would ever cause the property::TimelineElement::duration to shrink such that a clip’s Source is totally overlapped in the timeline, the operation would be prevented. Note that the same can happen when adding non-time effects with a finite property::TimelineElement::max-duration.

Therefore, when working with time effects, you should – more so than usual – not assume that setting the properties of the clip’s children will succeed. In particular, you should use TimelineElementExt::set_child_property_full() when setting the time properties.

If you wish to preserve the internal duration of a source in a clip during these time effect operations, you can do something like the following.

⚠️ The following code is in c ⚠️

void
do_time_effect_change (GESClip * clip)
{
  GList *tmp, *children;
  GESTrackElement *source;
  GstClockTime source_outpoint;
  GstClockTime new_end;
  GError *error = NULL;

  // choose some active source in a track to preserve the internal
  // duration of
  source = ges_clip_get_track_element (clip, NULL, GES_TYPE_SOURCE);

  // note its current internal end time
  source_outpoint = ges_clip_get_internal_time_from_timeline_time (
        clip, source, GES_TIMELINE_ELEMENT_END (clip), NULL);

  // handle invalid out-point

  // stop the children's control sources from clamping when their
  // out-point changes with a change in the time effects
  children = ges_container_get_children (GES_CONTAINER (clip), FALSE);

  for (tmp = children; tmp; tmp = tmp->next)
    ges_track_element_set_auto_clamp_control_source (tmp->data, FALSE);

  // add time effect, or set their children properties, or move them around
  ...
  // user can make sure that if a time effect changes one source, we should
  // also change the time effect for another source. E.g. if
  // "GstVideorate::rate" is set to 2.0, we also set "GstPitch::rate" to
  // 2.0

  // Note the duration of the clip may have already changed if the
  // duration-limit of the clip dropped below its current value

  new_end = ges_clip_get_timeline_time_from_internal_time (
        clip, source, source_outpoint, &error);
  // handle error

  if (!ges_timeline_elemnet_edit_full (GES_TIMELINE_ELEMENT (clip),
        -1, GES_EDIT_MODE_TRIM, GES_EDGE_END, new_end, &error))
    // handle error

  for (tmp = children; tmp; tmp = tmp->next)
    ges_track_element_set_auto_clamp_control_source (tmp->data, TRUE);

  g_list_free_full (children, gst_object_unref);
  gst_object_unref (source);
}

This is an Abstract Base Class, you cannot instantiate it.

Implements

ClipExt, GESContainerExt, TimelineElementExt, glib::ObjectExt, ExtractableExt, MetaContainerExt, [TimelineElementExtManual][trait@crate::prelude::TimelineElementExtManual]

Struct gstreamer_editing_services::Clip

Implementations

impl Clip

pub const NONE: Option<&'static Clip>

Trait Implementations

impl Clone for Clip

fn clone(&self) -> Self

fn clone_from(&mut self, source: &Self)

impl Debug for Clip

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl Hash for Clip

fn hash<H>(&self, state: &mut H) where H: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,

impl Ord for Clip

fn cmp(&self, other: &Self) -> Ordering

fn max(self, other: Self) -> Self

fn min(self, other: Self) -> Self

fn clamp(self, min: Self, max: Self) -> Self

impl ParentClassIs for Clip

type Parent = Container

impl<OT: ObjectType> PartialEq<OT> for Clip

fn eq(&self, other: &OT) -> bool

fn ne(&self, other: &Rhs) -> bool

impl<OT: ObjectType> PartialOrd<OT> for Clip

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

fn lt(&self, other: &Rhs) -> bool

fn le(&self, other: &Rhs) -> bool

fn gt(&self, other: &Rhs) -> bool

fn ge(&self, other: &Rhs) -> bool

impl StaticType for Clip

fn static_type() -> Type

impl Eq for Clip

impl IsA<Clip> for BaseEffectClip

impl IsA<Clip> for BaseTransitionClip

impl IsA<Clip> for UriClip

impl IsA<Clip> for EffectClip

impl IsA<Clip> for OperationClip

impl IsA<Clip> for OverlayClip

impl IsA<Clip> for SourceClip

impl IsA<Clip> for TestClip

impl IsA<Clip> for TextOverlayClip

impl IsA<Clip> for TitleClip

impl IsA<Clip> for TransitionClip

impl IsA<Container> for Clip

impl IsA<Extractable> for Clip

impl IsA<MetaContainer> for Clip

impl IsA<TimelineElement> for Clip

Auto Trait Implementations

impl RefUnwindSafe for Clip

impl !Send for Clip

impl !Sync for Clip

impl Unpin for Clip

impl UnwindSafe for Clip

Blanket Implementations

impl<T> Any for T where T: 'static + ?Sized,

pub fn type_id(&self) -> TypeId

impl<T> Borrow<T> for T where T: ?Sized,

pub fn borrow(&self) -> &T

impl<T> BorrowMut<T> for T where T: ?Sized,

pub fn borrow_mut(&mut self) -> &mut T

impl<T> Cast for T where T: ObjectType,

fn upcast<T>(self) -> T where T: ObjectType, Self: IsA<T>,

fn upcast_ref<T>(&self) -> &T where T: ObjectType, Self: IsA<T>,

fn downcast<T>(self) -> Result<T, Self> where T: ObjectType, Self: CanDowncast<T>,

fn downcast_ref<T>(&self) -> Option<&T> where T: ObjectType, Self: CanDowncast<T>,

fn dynamic_cast<T>(self) -> Result<T, Self> where T: ObjectType,

fn dynamic_cast_ref<T>(&self) -> Option<&T> where T: ObjectType,

unsafe fn unsafe_cast<T>(self) -> T where T: ObjectType,

unsafe fn unsafe_cast_ref<T>(&self) -> &T where T: ObjectType,

impl<T> From<T> for T

pub fn from(t: T) -> T

impl<O> GObjectExtManualGst for O where O: IsA<Object>,

pub fn try_set_property_from_str( &self, name: &str, value: &str) -> Result<(), BoolError>

pub fn set_property_from_str(&self, name: &str, value: &str)

impl<T, U> Into<U> for T where U: From<T>,

pub fn into(self) -> U

impl<U> IsSubclassableExt for U where U: IsClass + ParentClassIs,

pub fn parent_class_init<T>(class: &mut Class<U>) where T: ObjectSubclass, <U as ParentClassIs>::Parent: IsSubclassable<T>,

pub fn parent_instance_init<T>(instance: &mut InitializingObject<T>) where T: ObjectSubclass, <U as ParentClassIs>::Parent: IsSubclassable<T>,

impl<T> ObjectExt for T where T: ObjectType,

fn hash<H>(&self, state: &mut H) where
H: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,

impl<T> Any for T where
T: 'static + ?Sized,

impl<T> Borrow<T> for T where
T: ?Sized,

impl<T> BorrowMut<T> for T where
T: ?Sized,

impl<T> Cast for T where
T: ObjectType,

fn upcast<T>(self) -> T where
T: ObjectType,
Self: IsA<T>,

fn upcast_ref<T>(&self) -> &T where
T: ObjectType,
Self: IsA<T>,

fn downcast<T>(self) -> Result<T, Self> where
T: ObjectType,
Self: CanDowncast<T>,

fn downcast_ref<T>(&self) -> Option<&T> where
T: ObjectType,
Self: CanDowncast<T>,

fn dynamic_cast<T>(self) -> Result<T, Self> where
T: ObjectType,

fn dynamic_cast_ref<T>(&self) -> Option<&T> where
T: ObjectType,

unsafe fn unsafe_cast<T>(self) -> T where
T: ObjectType,

unsafe fn unsafe_cast_ref<T>(&self) -> &T where
T: ObjectType,

impl<O> GObjectExtManualGst for O where
O: IsA<Object>,

pub fn try_set_property_from_str(
&self,
name: &str,
value: &str
) -> Result<(), BoolError>

impl<T, U> Into<U> for T where
U: From<T>,

impl<U> IsSubclassableExt for U where
U: IsClass + ParentClassIs,

pub fn parent_class_init<T>(class: &mut Class<U>) where
T: ObjectSubclass,
<U as ParentClassIs>::Parent: IsSubclassable<T>,

pub fn parent_instance_init<T>(instance: &mut InitializingObject<T>) where
T: ObjectSubclass,
<U as ParentClassIs>::Parent: IsSubclassable<T>,

impl<T> ObjectExt for T where
T: ObjectType,

pub fn is<U>(&self) -> bool where
U: StaticType,

pub fn class(&self) -> &Class<T> where
T: IsClass,

pub fn class_of<U>(&self) -> Option<&Class<U>> where
U: IsClass,

pub fn interface<U>(&self) -> Option<InterfaceRef<'_, U>> where
U: IsInterface,

pub fn try_set_property<V>(
&self,
property_name: &str,
value: V
) -> Result<(), BoolError> where
V: ToValue,

pub fn set_property<V>(&self, property_name: &str, value: V) where
V: ToValue,

pub fn try_set_property_from_value(
&self,
property_name: &str,
value: &Value
) -> Result<(), BoolError>

pub fn try_set_properties(
&self,
property_values: &[(&str, &dyn ToValue )]
) -> Result<(), BoolError>

pub fn set_properties(&self, property_values: &[(&str, &dyn ToValue )])

pub fn try_set_properties_from_value(
&self,
property_values: &[(&str, Value )]
) -> Result<(), BoolError>

pub fn set_properties_from_value(&self, property_values: &[(&str, Value )])

pub fn try_property<V>(&self, property_name: &str) -> Result<V, BoolError> where
V: 'static + for<'b> FromValue<'b>,

pub fn property<V>(&self, property_name: &str) -> V where
V: 'static + for<'b> FromValue<'b>,

pub fn try_property_value(
&self,
property_name: &str
) -> Result<Value, BoolError>

pub unsafe fn set_qdata<QD>(&self, key: Quark, value: QD) where
QD: 'static,

pub unsafe fn qdata<QD>(&self, key: Quark) -> Option<NonNull<QD>> where
QD: 'static,

pub unsafe fn steal_qdata<QD>(&self, key: Quark) -> Option<QD> where
QD: 'static,

pub unsafe fn set_data<QD>(&self, key: &str, value: QD) where
QD: 'static,

pub unsafe fn data<QD>(&self, key: &str) -> Option<NonNull<QD>> where
QD: 'static,

pub unsafe fn steal_data<QD>(&self, key: &str) -> Option<QD> where
QD: 'static,

pub fn try_connect<F>(
&self,
signal_name: &str,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: 'static + Fn(&[Value ]) -> Option<Value> + Send + Sync,

pub fn connect<F>(
&self,
signal_name: &str,
after: bool,
callback: F
) -> SignalHandlerId where
F: 'static + Fn(&[Value ]) -> Option<Value> + Send + Sync,

pub fn try_connect_id<F>(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: 'static + Fn(&[Value ]) -> Option<Value> + Send + Sync,

pub fn connect_id<F>(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
callback: F
) -> SignalHandlerId where
F: 'static + Fn(&[Value ]) -> Option<Value> + Send + Sync,

pub fn try_connect_local<F>(
&self,
signal_name: &str,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: 'static + Fn(&[Value ]) -> Option<Value>,

pub fn connect_local<F>(
&self,
signal_name: &str,
after: bool,
callback: F
) -> SignalHandlerId where
F: 'static + Fn(&[Value ]) -> Option<Value>,

pub fn try_connect_local_id<F>(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: 'static + Fn(&[Value ]) -> Option<Value>,

pub fn connect_local_id<F>(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
callback: F
) -> SignalHandlerId where
F: 'static + Fn(&[Value ]) -> Option<Value>,

pub unsafe fn try_connect_unsafe<F>(
&self,
signal_name: &str,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: Fn(&[Value ]) -> Option<Value>,

pub unsafe fn connect_unsafe<F>(
&self,
signal_name: &str,
after: bool,
callback: F
) -> SignalHandlerId where
F: Fn(&[Value ]) -> Option<Value>,

pub unsafe fn try_connect_unsafe_id<F>(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: Fn(&[Value ]) -> Option<Value>,

pub fn try_connect_closure(
&self,
signal_name: &str,
after: bool,
closure: RustClosure
) -> Result<SignalHandlerId, BoolError>

pub fn connect_closure(
&self,
signal_name: &str,
after: bool,
closure: RustClosure
) -> SignalHandlerId

pub fn try_connect_closure_id(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
closure: RustClosure
) -> Result<SignalHandlerId, BoolError>

pub fn connect_closure_id(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
closure: RustClosure
) -> SignalHandlerId

pub unsafe fn connect_unsafe_id<F>(
&self,
signal_id: SignalId,
details: Option<Quark>,
after: bool,
callback: F
) -> SignalHandlerId where
F: Fn(&[Value ]) -> Option<Value>,

pub fn try_emit<R>(
&self,
signal_id: SignalId,
args: &[&dyn ToValue ]
) -> Result<R, BoolError> where
R: TryFromClosureReturnValue,

pub fn emit<R>(&self, signal_id: SignalId, args: &[&dyn ToValue ]) -> R where
R: TryFromClosureReturnValue,

pub fn try_emit_with_values(
&self,
signal_id: SignalId,
args: &[Value ]
) -> Result<Option<Value>, BoolError>

pub fn emit_with_values(
&self,
signal_id: SignalId,
args: &[Value ]
) -> Option<Value>

pub fn try_emit_by_name<R>(
&self,
signal_name: &str,
args: &[&dyn ToValue ]
) -> Result<R, BoolError> where
R: TryFromClosureReturnValue,

pub fn emit_by_name<R>(&self, signal_name: &str, args: &[&dyn ToValue ]) -> R where
R: TryFromClosureReturnValue,

pub fn try_emit_by_name_with_values(
&self,
signal_name: &str,
args: &[Value ]
) -> Result<Option<Value>, BoolError>

pub fn emit_by_name_with_values(
&self,
signal_name: &str,
args: &[Value ]
) -> Option<Value>

pub fn try_emit_by_name_with_details<R>(
&self,
signal_name: &str,
details: Quark,
args: &[&dyn ToValue ]
) -> Result<R, BoolError> where
R: TryFromClosureReturnValue,