Trait gstreamer::prelude::ElementExt

pub trait ElementExt: IsA<Element> + Sealed + 'static {
    // Provided methods
    fn abort_state(&self) { ... }
    fn add_pad(&self, pad: &impl IsA<Pad>) -> Result<(), BoolError> { ... }
    fn change_state(
        &self,
        transition: StateChange,
    ) -> Result<StateChangeSuccess, StateChangeError> { ... }
    fn continue_state(
        &self,
        ret: impl Into<StateChangeReturn>,
    ) -> Result<StateChangeSuccess, StateChangeError> { ... }
    fn create_all_pads(&self) { ... }
    fn decorate_stream_id(&self, stream_id: &str) -> GString { ... }
    fn foreach_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool { ... }
    fn foreach_sink_pad<P: FnMut(&Element, &Pad) -> bool>(
        &self,
        func: P,
    ) -> bool { ... }
    fn foreach_src_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool { ... }
    fn base_time(&self) -> Option<ClockTime> { ... }
    fn bus(&self) -> Option<Bus> { ... }
    fn clock(&self) -> Option<Clock> { ... }
    fn compatible_pad(
        &self,
        pad: &impl IsA<Pad>,
        caps: Option<&Caps>,
    ) -> Option<Pad> { ... }
    fn compatible_pad_template(
        &self,
        compattempl: &PadTemplate,
    ) -> Option<PadTemplate> { ... }
    fn context(&self, context_type: &str) -> Option<Context> { ... }
    fn contexts(&self) -> Vec<Context> { ... }
    fn factory(&self) -> Option<ElementFactory> { ... }
    fn start_time(&self) -> Option<ClockTime> { ... }
    fn state(
        &self,
        timeout: impl Into<Option<ClockTime>>,
    ) -> (Result<StateChangeSuccess, StateChangeError>, State, State) { ... }
    fn static_pad(&self, name: &str) -> Option<Pad> { ... }
    fn is_locked_state(&self) -> bool { ... }
    fn lost_state(&self) { ... }
    fn no_more_pads(&self) { ... }
    fn post_message(&self, message: Message) -> Result<(), BoolError> { ... }
    fn provide_clock(&self) -> Option<Clock> { ... }
    fn release_request_pad(&self, pad: &impl IsA<Pad>) { ... }
    fn remove_pad(&self, pad: &impl IsA<Pad>) -> Result<(), BoolError> { ... }
    fn request_pad(
        &self,
        templ: &PadTemplate,
        name: Option<&str>,
        caps: Option<&Caps>,
    ) -> Option<Pad> { ... }
    fn set_base_time(&self, time: ClockTime) { ... }
    fn set_bus(&self, bus: Option<&Bus>) { ... }
    fn set_clock(
        &self,
        clock: Option<&impl IsA<Clock>>,
    ) -> Result<(), BoolError> { ... }
    fn set_context(&self, context: &Context) { ... }
    fn set_locked_state(&self, locked_state: bool) -> bool { ... }
    fn set_start_time(&self, time: impl Into<Option<ClockTime>>) { ... }
    fn set_state(
        &self,
        state: State,
    ) -> Result<StateChangeSuccess, StateChangeError> { ... }
    fn sync_state_with_parent(&self) -> Result<(), BoolError> { ... }
    fn unlink(&self, dest: &impl IsA<Element>) { ... }
    fn unlink_pads(
        &self,
        srcpadname: &str,
        dest: &impl IsA<Element>,
        destpadname: &str,
    ) { ... }
    fn connect_no_more_pads<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_pad_added<F: Fn(&Self, &Pad) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_pad_removed<F: Fn(&Self, &Pad) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
}

Trait containing all Element methods.

Implementors

Bin, Element, TagSetter, TocSetter

Provided Methods

fn abort_state(&self)

Abort the state change of the element. This function is used by elements that do asynchronous state changes and find out something is wrong.

This function should be called with the STATE_LOCK held.

MT safe.

fn add_pad(&self, pad: &impl IsA<Pad>) -> Result<(), BoolError>

Adds a pad (link point) to self. pad’s parent will be set to self; see GstObjectExt::set_parent() for refcounting information.

Pads are automatically activated when added in the PAUSED or PLAYING state.

The pad and the element should be unlocked when calling this function.

This function will emit the pad-added signal on the element.

pad

the Pad to add to the element.

Returns

true if the pad could be added. This function can fail when a pad with the same name already existed or the pad already had another parent.

MT safe.

fn change_state( &self, transition: StateChange, ) -> Result<StateChangeSuccess, StateChangeError>

Perform transition on self.

This function must be called with STATE_LOCK held and is mainly used internally.

transition

the requested transition

Returns

the StateChangeReturn of the state transition.

fn continue_state( &self, ret: impl Into<StateChangeReturn>, ) -> Result<StateChangeSuccess, StateChangeError>

Commit the state change of the element and proceed to the next pending state if any. This function is used by elements that do asynchronous state changes. The core will normally call this method automatically when an element returned StateChangeReturn::Success from the state change function.

If after calling this method the element still has not reached the pending state, the next state change is performed.

This method is used internally and should normally not be called by plugins or applications.

This function must be called with STATE_LOCK held.

ret

The previous state return value

Returns

The result of the commit state change.

MT safe.

fn create_all_pads(&self)

Creates a pad for each pad template that is always available. This function is only useful during object initialization of subclasses of Element.

fn decorate_stream_id(&self, stream_id: &str) -> GString

Creates a stream-id for self by combining the upstream information with the stream_id.

This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending stream_id to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don’t implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead.

Since stream IDs are sorted alphabetically, any numbers in the stream ID should be printed with a fixed number of characters, preceded by 0’s, such as by using the format `03u instead of \u`.

stream_id

The stream-id

Returns

A stream-id for self.

fn foreach_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool

Call func with user_data for each of self’s pads. func will be called exactly once for each pad that exists at the time of this call, unless one of the calls to func returns false in which case we will stop iterating pads and return early. If new pads are added or pads are removed while pads are being iterated, this will not be taken into account until next time this function is used.

func

function to call for each pad

Returns

false if self had no pads or if one of the calls to func returned false.

fn foreach_sink_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool

Call func with user_data for each of self’s sink pads. func will be called exactly once for each sink pad that exists at the time of this call, unless one of the calls to func returns false in which case we will stop iterating pads and return early. If new sink pads are added or sink pads are removed while the sink pads are being iterated, this will not be taken into account until next time this function is used.

func

function to call for each sink pad

Returns

false if self had no sink pads or if one of the calls to func returned false.

fn foreach_src_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool

Call func with user_data for each of self’s source pads. func will be called exactly once for each source pad that exists at the time of this call, unless one of the calls to func returns false in which case we will stop iterating pads and return early. If new source pads are added or source pads are removed while the source pads are being iterated, this will not be taken into account until next time this function is used.

func

function to call for each source pad

Returns

false if self had no source pads or if one of the calls to func returned false.

fn base_time(&self) -> Option<ClockTime>

Returns the base time of the element. The base time is the absolute time of the clock when this element was last put to PLAYING. Subtracting the base time from the clock time gives the running time of the element.

Returns

the base time of the element.

MT safe.

fn bus(&self) -> Option<Bus>

Returns the bus of the element. Note that only a Pipeline will provide a bus for the application.

Returns

the element’s Bus. unref after usage.

MT safe.

fn clock(&self) -> Option<Clock>

Gets the currently configured clock of the element. This is the clock as was last set with set_clock().

Elements in a pipeline will only have their clock set when the pipeline is in the PLAYING state.

Returns

the Clock of the element. unref after usage.

MT safe.

fn compatible_pad( &self, pad: &impl IsA<Pad>, caps: Option<&Caps>, ) -> Option<Pad>

Looks for an unlinked pad to which the given pad can link. It is not guaranteed that linking the pads will work, though it should work in most cases.

This function will first attempt to find a compatible unlinked ALWAYS pad, and if none can be found, it will request a compatible REQUEST pad by looking at the templates of self.

pad

the Pad to find a compatible one for.

caps

the Caps to use as a filter.

Returns

the Pad to which a link can be made, or None if one cannot be found. gst_object_unref() after usage.

fn compatible_pad_template( &self, compattempl: &PadTemplate, ) -> Option<PadTemplate>

Retrieves a pad template from self that is compatible with compattempl. Pads from compatible templates can be linked together.

compattempl

the PadTemplate to find a compatible template for

Returns

a compatible PadTemplate, or None if none was found. No unreferencing is necessary.

fn context(&self, context_type: &str) -> Option<Context>

Gets the context with context_type set on the element or NULL.

MT safe.

context_type

a name of a context to retrieve

Returns

A Context or NULL

fn contexts(&self) -> Vec<Context>

Gets the contexts set on the element.

MT safe.

Returns

List of Context

fn factory(&self) -> Option<ElementFactory>

Retrieves the factory that was used to create this element.

Returns

the ElementFactory used for creating this element or None if element has not been registered (static element). no refcounting is needed.

fn start_time(&self) -> Option<ClockTime>

Returns the start time of the element. The start time is the running time of the clock when this element was last put to PAUSED.

Usually the start_time is managed by a toplevel element such as Pipeline.

MT safe.

Returns

the start time of the element.

fn state( &self, timeout: impl Into<Option<ClockTime>>, ) -> (Result<StateChangeSuccess, StateChangeError>, State, State)

Gets the state of the element.

For elements that performed an ASYNC state change, as reported by set_state(), this function will block up to the specified timeout value for the state change to complete. If the element completes the state change or goes into an error, this function returns immediately with a return value of StateChangeReturn::Success or StateChangeReturn::Failure respectively.

For elements that did not return StateChangeReturn::Async, this function returns the current and pending state immediately.

This function returns StateChangeReturn::NoPreroll if the element successfully changed its state but is not able to provide data yet. This mostly happens for live sources that only produce data in State::Playing. While the state change return is equivalent to StateChangeReturn::Success, it is returned to the application to signal that some sink elements might not be able to complete their state change because an element is not producing data to complete the preroll. When setting the element to playing, the preroll will complete and playback will start.

timeout

a GstClockTime to specify the timeout for an async state change or GST_CLOCK_TIME_NONE for infinite timeout.

Returns

StateChangeReturn::Success if the element has no more pending state and the last state change succeeded, StateChangeReturn::Async if the element is still performing a state change or StateChangeReturn::Failure if the last state change failed.

MT safe.

state

a pointer to State to hold the state. Can be None.

pending

a pointer to State to hold the pending state. Can be None.

fn static_pad(&self, name: &str) -> Option<Pad>

Retrieves a pad from self by name. This version only retrieves already-existing (i.e. ‘static’) pads.

name

the name of the static Pad to retrieve.

Returns

the requested Pad if found, otherwise None. unref after usage.

MT safe.

fn is_locked_state(&self) -> bool

Checks if the state of an element is locked. If the state of an element is locked, state changes of the parent don’t affect the element. This way you can leave currently unused elements inside bins. Just lock their state before changing the state from State::Null.

MT safe.

Returns

true, if the element’s state is locked.

fn lost_state(&self)

Brings the element to the lost state. The current state of the element is copied to the pending state so that any call to state() will return StateChangeReturn::Async.

An ASYNC_START message is posted. If the element was PLAYING, it will go to PAUSED. The element will be restored to its PLAYING state by the parent pipeline when it prerolls again.

This is mostly used for elements that lost their preroll buffer in the State::Paused or State::Playing state after a flush, they will go to their pending state again when a new preroll buffer is queued. This function can only be called when the element is currently not in error or an async state change.

This function is used internally and should normally not be called from plugins or applications.

fn no_more_pads(&self)

Use this function to signal that the element does not expect any more pads to show up in the current pipeline. This function should be called whenever pads have been added by the element itself. Elements with PadPresence::Sometimes pad templates use this in combination with autopluggers to figure out that the element is done initializing its pads.

This function emits the no-more-pads signal.

MT safe.

fn post_message(&self, message: Message) -> Result<(), BoolError>

Post a message on the element’s Bus. This function takes ownership of the message; if you want to access the message after this call, you should add an additional reference before calling.

message

a Message to post

Returns

true if the message was successfully posted. The function returns false if the element did not have a bus.

MT safe.

fn provide_clock(&self) -> Option<Clock>

Get the clock provided by the given element.

An element is only required to provide a clock in the PAUSED state. Some elements can provide a clock in other states.

Returns

the GstClock provided by the element or None if no clock could be provided. Unref after usage.

MT safe.

fn release_request_pad(&self, pad: &impl IsA<Pad>)

Makes the element free the previously requested pad as obtained with request_pad().

This does not unref the pad. If the pad was created by using request_pad(), release_request_pad() needs to be followed by gst_object_unref() to free the pad.

MT safe.

pad

the Pad to release.

fn remove_pad(&self, pad: &impl IsA<Pad>) -> Result<(), BoolError>

Removes pad from self. pad will be destroyed if it has not been referenced elsewhere using GstObjectExt::unparent().

This function is used by plugin developers and should not be used by applications. Pads that were dynamically requested from elements with request_pad() should be released with the release_request_pad() function instead.

Pads are not automatically deactivated so elements should perform the needed steps to deactivate the pad in case this pad is removed in the PAUSED or PLAYING state. See PadExt::set_active() for more information about deactivating pads.

The pad and the element should be unlocked when calling this function.

This function will emit the pad-removed signal on the element.

pad

the Pad to remove from the element.

Returns

true if the pad could be removed. Can return false if the pad does not belong to the provided element.

MT safe.

fn request_pad( &self, templ: &PadTemplate, name: Option<&str>, caps: Option<&Caps>, ) -> Option<Pad>

Retrieves a request pad from the element according to the provided template. Pad templates can be looked up using ElementFactory::static_pad_templates().

The pad should be released with release_request_pad().

templ

a PadTemplate of which we want a pad of.

name

the name of the request Pad to retrieve. Can be None.

caps

the caps of the pad we want to request. Can be None.

Returns

requested Pad if found, otherwise None. Release after usage.

fn set_base_time(&self, time: ClockTime)

Set the base time of an element. See base_time().

MT safe.

time

the base time to set.

fn set_bus(&self, bus: Option<&Bus>)

Sets the bus of the element. Increases the refcount on the bus. For internal use only, unless you’re testing elements.

MT safe.

bus

the Bus to set.

fn set_clock(&self, clock: Option<&impl IsA<Clock>>) -> Result<(), BoolError>

Sets the clock for the element. This function increases the refcount on the clock. Any previously set clock on the object is unreffed.

clock

the Clock to set for the element.

Returns

true if the element accepted the clock. An element can refuse a clock when it, for example, is not able to slave its internal clock to the clock or when it requires a specific clock to operate.

MT safe.

fn set_context(&self, context: &Context)

Sets the context of the element. Increases the refcount of the context.

MT safe.

context

the Context to set.

fn set_locked_state(&self, locked_state: bool) -> bool

Locks the state of an element, so state changes of the parent don’t affect this element anymore.

Note that this is racy if the state lock of the parent bin is not taken. The parent bin might’ve just checked the flag in another thread and as the next step proceed to change the child element’s state.

MT safe.

locked_state

true to lock the element’s state

Returns

true if the state was changed, false if bad parameters were given or the elements state-locking needed no change.

fn set_start_time(&self, time: impl Into<Option<ClockTime>>)

Set the start time of an element. The start time of the element is the running time of the element when it last went to the PAUSED state. In READY or after a flushing seek, it is set to 0.

Toplevel elements like Pipeline will manage the start_time and base_time on its children. Setting the start_time to GST_CLOCK_TIME_NONE on such a toplevel element will disable the distribution of the base_time to the children and can be useful if the application manages the base_time itself, for example if you want to synchronize capture from multiple pipelines, and you can also ensure that the pipelines have the same clock.

MT safe.

time

the base time to set.

fn set_state( &self, state: State, ) -> Result<StateChangeSuccess, StateChangeError>

Sets the state of the element. This function will try to set the requested state by going through all the intermediary states and calling the class’s state change function for each.

This function can return StateChangeReturn::Async, in which case the element will perform the remainder of the state change asynchronously in another thread. An application can use state() to wait for the completion of the state change or it can wait for a GST_MESSAGE_ASYNC_DONE or GST_MESSAGE_STATE_CHANGED on the bus.

State changes to State::Ready or State::Null never return StateChangeReturn::Async.

state

the element’s new State.

Returns

Result of the state change using StateChangeReturn.

MT safe.

fn sync_state_with_parent(&self) -> Result<(), BoolError>

Tries to change the state of the element to the same as its parent. If this function returns false, the state of element is undefined.

Returns

true, if the element’s state could be synced to the parent’s state.

MT safe.

fn unlink(&self, dest: &impl IsA<Element>)

Unlinks all source pads of the source element with all sink pads of the sink element to which they are linked.

If the link has been made using ElementExtManual::link(), it could have created an requestpad, which has to be released using release_request_pad().

dest

the sink Element to unlink.

fn unlink_pads( &self, srcpadname: &str, dest: &impl IsA<Element>, destpadname: &str, )

Unlinks the two named pads of the source and destination elements.

This is a convenience function for PadExt::unlink().

srcpadname

the name of the Pad in source element.

dest

a Element containing the destination pad.

destpadname

the name of the Pad in destination element.

fn connect_no_more_pads<F: Fn(&Self) + Send + Sync + 'static>( &self, f: F, ) -> SignalHandlerId

This signals that the element will not generate more dynamic pads. Note that this signal will usually be emitted from the context of the streaming thread.

fn connect_pad_added<F: Fn(&Self, &Pad) + Send + Sync + 'static>( &self, f: F, ) -> SignalHandlerId

a new Pad has been added to the element. Note that this signal will usually be emitted from the context of the streaming thread. Also keep in mind that if you add new elements to the pipeline in the signal handler you will need to set them to the desired target state with set_state() or sync_state_with_parent().

new_pad

the pad that has been added

fn connect_pad_removed<F: Fn(&Self, &Pad) + Send + Sync + 'static>( &self, f: F, ) -> SignalHandlerId

a Pad has been removed from the element

old_pad

the pad that has been removed

Object Safety

This trait is not object safe.

Implementors

impl<O: IsA<Element>> ElementExt for O