org.freedesktop.gstreamer

Class Element

java.lang.Object

org.freedesktop.gstreamer.glib.NativeObject

org.freedesktop.gstreamer.glib.RefCountedObject

org.freedesktop.gstreamer.glib.GObject

org.freedesktop.gstreamer.GstObject

org.freedesktop.gstreamer.Element

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

BaseSink, BaseSrc, BaseTransform, Bin

public class Element
extends GstObject

Abstract base class for all pipeline elements.

See upstream documentation at https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstElement.html

Element is the abstract base class needed to construct an element that can be used in a GStreamer pipeline. Please refer to the plugin writers guide for more information on creating Element subclasses.

The name of a Element can be retrieved with GstObject.getName() and set with GstObject.setName(java.lang.String).

All elements have pads (of the type Pad). These pads link to pads on other elements. Buffers flow between these linked pads. An Element has a list of Pad structures for all their input (or sink) and output (or source) pads. Core and plug-in writers can add and remove pads with addPad(org.freedesktop.gstreamer.Pad) and removePad(org.freedesktop.gstreamer.Pad).

A pad of an element can be retrieved by name with #getPad. An list of all pads can be retrieved with getPads().

Elements can be linked through their pads. If the link is straightforward, use the link(org.freedesktop.gstreamer.Element) convenience function to link two elements, or linkMany(org.freedesktop.gstreamer.Element...) for more elements in a row.

For finer control, use linkPads(org.freedesktop.gstreamer.Element, java.lang.String, org.freedesktop.gstreamer.Element, java.lang.String) and linkPadsFiltered(org.freedesktop.gstreamer.Element, java.lang.String, org.freedesktop.gstreamer.Element, java.lang.String, org.freedesktop.gstreamer.Caps) to specify the pads to link on each element by name.

Each element has a state (see State). You can get and set the state of an element with getState() and setState(org.freedesktop.gstreamer.State).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Element.NO_MORE_PADS Signal emitted when this Element ceases to generated dynamic pads.
static interface	Element.PAD_ADDED Signal emitted when an Pad is added to this Element
static interface	Element.PAD_REMOVED Signal emitted when an Pad is removed from this Element

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.glib.GObject

GObject.GCallback, GObject.GInterface

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.glib.NativeObject

NativeObject.Initializer, NativeObject.TypeProvider, NativeObject.TypeRegistration<T extends NativeObject>

Field Summary

Fields

Modifier and Type	Field and Description
static String	GTYPE_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Element(NativeObject.Initializer init) Creates a new instance of Element.

Method Summary

Modifier and Type	Method and Description
boolean	addPad(Pad pad) Adds a Pad (link point) to the Element.
void	connect(Element.NO_MORE_PADS listener) Add a listener for the no-more-pads signal
void	connect(Element.PAD_ADDED listener) Add a listener for the pad-added signal
void	connect(Element.PAD_REMOVED listener) Add a listener for the pad-added signal
void	disconnect(Element.NO_MORE_PADS listener) Remove a listener for the no-more-pads signal
void	disconnect(Element.PAD_ADDED listener) Remove a listener for the pad-added signal
void	disconnect(Element.PAD_REMOVED listener) Remove a listener for the pad-removed signal
long	getBaseTime() Returns the base time of the element.
Bus	getBus() Get the bus of the element.
Clock	getClock() Gets the currently configured clock of the element.
ElementFactory	getFactory() Retrieves the factory that was used to create this element.
List<Pad>	getPads() Retrieves a list of the element's pads.
Pad	getRequestPad(String name) Retrieves a pad from the element by name.
List<Pad>	getSinkPads() Retrieves a list of the element's sink pads.
List<Pad>	getSrcPads() Retrieves a list of the element's source pads.
long	getStartTime() Returns the start time of this element.
State	getState() Gets the state of the element.
State	getState(long timeout) Gets the state of the element.
void	getState(long timeout, State[] states) Gets the state of the element.
State	getState(long timeout, TimeUnit units) Gets the state of the element.
Pad	getStaticPad(String padname) Retrieves a pad from the element by name.
boolean	isPlaying() Tests if the Element is currently playing.
boolean	link(Element dest) Links this element to another element.
boolean	linkFiltered(Element dest, Caps filter) Links this element to another element using the given caps as filtercaps.
static boolean	linkMany(Element... elements) Link together a list of elements.
static boolean	linkPads(Element src, String srcPadName, Element dest, String destPadName) Link together source and destination pads of two elements.
static boolean	linkPadsFiltered(Element src, String srcPadName, Element dest, String destPadName, Caps caps) Link together source and destination pads of two elements.
protected static NativeObject.Initializer	makeRawElement(String factoryName, String elementName) Creates an instance of the required element type, but does not wrap it in a proxy.
StateChangeReturn	pause() Tells the Element to pause playing the media stream.
StateChangeReturn	play() Tells the Element to start playing the media stream.
boolean	postMessage(Message message) Posts a Message on the element's Bus.
boolean	query(Query query) Performs a query on the element.
StateChangeReturn	ready() Tells the Element to set ready the media stream.
void	releaseRequestPad(Pad pad) Frees the previously requested pad obtained via getRequestPad(java.lang.String).
boolean	removePad(Pad pad) Remove a Pad from the element.
boolean	sendEvent(Event ev) Sends an event to an element.
void	setBaseTime(long time) Set the base time of an element.
void	setCaps(Caps caps) Sets the Caps on this Element.
boolean	setLockedState(boolean locked_state) Locks the state of an element, so state changes of the parent don't affect this element anymore.
void	setStartTime(long time) Set the start time of an element.
StateChangeReturn	setState(State state) Sets the state of the element.
StateChangeReturn	stop() Tells the Element to pause playing the media stream.
boolean	syncStateWithParent() Tries to change the state of the element to the same as its parent.
void	unlink(Element dest) Unlinks all source pads of this source element with all sink pads of the sink element to which they are linked.
static void	unlinkMany(Element... elements) Unlink a list of elements.
static void	unlinkPads(Element src, String srcPadName, Element dest, String destPadName) Unlink source and destination pads of two elements.

Methods inherited from class org.freedesktop.gstreamer.GstObject

addControlBinding, getControlBinding, getName, getParent, hasActiveControlBindings, removeControlBinding, setControlBindingDisabled, setControlBindingsDisabled, setName, suggestNextSync, syncValues, toString

Methods inherited from class org.freedesktop.gstreamer.glib.GObject

addCallback, connect, connect, disconnect, dispose, emit, emit, get, getPropertyDefaultValue, getPropertyMaximumValue, getPropertyMinimumValue, getRefCount, getTypeName, invalidate, listPropertyNames, removeCallback, set

Methods inherited from class org.freedesktop.gstreamer.glib.NativeObject

close, disown, equals, getPointer, getRawPointer, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

GTYPE_NAME

public static final String GTYPE_NAME

See Also:

Constant Field Values

Constructor Detail

Element

protected Element(NativeObject.Initializer init)

Creates a new instance of Element. This constructor is used internally.

Parameters:

init - internal initialization data.

Method Detail

makeRawElement

protected static NativeObject.Initializer makeRawElement(String factoryName,
                                                         String elementName)

Creates an instance of the required element type, but does not wrap it in a proxy.

Parameters:

factoryName - The name of the factory to use to produce the Element

elementName - The name to assign to the created Element

Returns:

a raw element.

link

public boolean link(Element dest)

Links this element to another element. The link must be from source to destination; the other direction will not be tried.

The function looks for existing pads that aren't linked yet. It will request new pads if necessary. Such pads need to be released manualy when unlinking. If multiple links are possible, only one is established.

Make sure you have added your elements to a bin or pipeline with Bin.add(org.freedesktop.gstreamer.Element) or Bin.addMany(org.freedesktop.gstreamer.Element...) before trying to link them.

See linkPadsFiltered(org.freedesktop.gstreamer.Element, java.lang.String, org.freedesktop.gstreamer.Element, java.lang.String, org.freedesktop.gstreamer.Caps) if you need more control about which pads are selected for linking.

Parameters:

dest - The Element containing the destination pad.

Returns:

true if the elements could be linked, false otherwise.

linkFiltered

public boolean linkFiltered(Element dest,
                            Caps filter)

Links this element to another element using the given caps as filtercaps. The link must be from source to destination; the other direction will not be tried.

The function looks for existing pads that aren't linked yet. It will request new pads if necessary. Such pads need to be released manualy when unlinking. If multiple links are possible, only one is established.

Make sure you have added your elements to a bin or pipeline with Bin.add(org.freedesktop.gstreamer.Element) or Bin.addMany(org.freedesktop.gstreamer.Element...) before trying to link them.

See linkPadsFiltered(org.freedesktop.gstreamer.Element, java.lang.String, org.freedesktop.gstreamer.Element, java.lang.String, org.freedesktop.gstreamer.Caps) if you need more control about which pads are selected for linking.

Parameters:

dest - The Element containing the destination pad.

filter - The Caps to filter the link, or Null for no filter.

Returns:

true if the elements could be linked, false otherwise.

unlink

public void unlink(Element dest)

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

If the link has been made using link(org.freedesktop.gstreamer.Element), it could have created an requestpad, which has to be released using gst_element_release_request_pad().

Parameters:

dest - The sink Element to unlink.

isPlaying

public boolean isPlaying()

Tests if the Element is currently playing.

Returns:

true if the Element is currently playing

play

public StateChangeReturn play()

Tells the Element to start playing the media stream.

ready

public StateChangeReturn ready()

Tells the Element to set ready the media stream.

pause

public StateChangeReturn pause()

Tells the Element to pause playing the media stream.

stop

public StateChangeReturn stop()

Tells the Element to pause playing the media stream.

setState

public StateChangeReturn setState(State state)

Sets the state of the element.

This method will try to set the requested state by going through all the intermediary states.

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 getState() to wait for the completion of the state change or it can wait for a state change message on the bus.

Parameters:

state - the element's new State.

Returns:

the status of the element's state change.

setLockedState

public boolean setLockedState(boolean locked_state)

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

Parameters:

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.

getState

public State getState()

Gets the state of the element.

This method will wait until any async state change has completed.

Returns:

The State the Element is currently in.

getState

public State getState(long timeout,
                      TimeUnit units)

Gets the state of the element.

For elements that performed an ASYNC state change, as reported by setState(org.freedesktop.gstreamer.State), this function will block up to the specified timeout value for the state change to complete.

Parameters:

timeout - the amount of time to wait.

units - the units of the timeout.

Returns:

The State the Element is currently in.

getState

public State getState(long timeout)

Gets the state of the element.

For elements that performed an ASYNC state change, as reported by setState(org.freedesktop.gstreamer.State), this function will block up to the specified timeout value for the state change to complete.

Parameters:

timeout - The amount of time in nanoseconds to wait.

Returns:

The State the Element is currently in.

getState

public void getState(long timeout,
                     State[] states)

Gets the state of the element.

For elements that performed an ASYNC state change, as reported by setState(org.freedesktop.gstreamer.State), this function will block up to the specified timeout value for the state change to complete.

Parameters:

timeout - The amount of time in nanoseconds to wait.

states - an array to store the states in. Must be of sufficient size to hold two elements.

syncStateWithParent

public boolean syncStateWithParent()

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.

setCaps

public void setCaps(Caps caps)

Sets the Caps on this Element.

Parameters:

caps - the new Caps to set.

getStaticPad

public Pad getStaticPad(String padname)

Retrieves a pad from the element by name. This version only retrieves already-existing (i.e. 'static') pads.

Parameters:

padname - The name of the Pad to get.

Returns:

The requested Pad if found, otherwise null.

getPads

public List<Pad> getPads()

Retrieves a list of the element's pads.

Returns:

the List of Pads.

getSrcPads

public List<Pad> getSrcPads()

Retrieves a list of the element's source pads.

Returns:

the List of Pads.

getSinkPads

public List<Pad> getSinkPads()

Retrieves a list of the element's sink pads.

Returns:

the List of Pads.

addPad

public boolean addPad(Pad pad)

Adds a Pad (link point) to the Element. The Pad's parent will be set to this element.

Pads are not automatically activated so elements should perform the needed steps to activate the pad in case this pad is added in the PAUSED or PLAYING state. See Pad.setActive(boolean) for more information about activating pads.

This function will emit the Element.PAD_ADDED signal on the element.

Parameters:

pad - The Pad to add.

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.

getRequestPad

public Pad getRequestPad(String name)

Retrieves a pad from the element by name. This version only retrieves request pads. The pad must be released with releaseRequestPad(org.freedesktop.gstreamer.Pad).

Parameters:

name - the name of the request Pad to retrieve.

Returns:

the requested Pad if found, otherwise null. Release using releaseRequestPad(org.freedesktop.gstreamer.Pad) after usage.

releaseRequestPad

public void releaseRequestPad(Pad pad)

Frees the previously requested pad obtained via getRequestPad(java.lang.String).

Parameters:

pad - the pad to release.

removePad

public boolean removePad(Pad pad)

Remove a Pad from the element.

This method is used by plugin developers and should not be used by applications. Pads that were dynamically requested from elements with getRequestPad(java.lang.String) should be released with the releaseRequestPad(org.freedesktop.gstreamer.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 Pad.setActive(boolean) for more information about deactivating pads.

This function will emit the Element.PAD_REMOVED signal on the element.

Parameters:

pad - The Pad to remove.

Returns:

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

getFactory

public ElementFactory getFactory()

Retrieves the factory that was used to create this element.

Returns:

the ElementFactory used for creating this element.

getBus

public Bus getBus()

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

Returns:

the element's Bus

sendEvent

public boolean sendEvent(Event ev)

Sends an event to an element.

If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for upstream events or a random linked source pad for downstream events.

Parameters:

ev - The Event to send.

Returns:

true if the event was handled.

connect

public void connect(Element.PAD_ADDED listener)

Add a listener for the pad-added signal

Parameters:

listener - Listener to be called when a Pad is added to the Element.

disconnect

public void disconnect(Element.PAD_ADDED listener)

Remove a listener for the pad-added signal

Parameters:

listener - The listener that was previously added.

connect

public void connect(Element.PAD_REMOVED listener)

Add a listener for the pad-added signal

Parameters:

listener - Listener to be called when a Pad is removed from the Element.

disconnect

public void disconnect(Element.PAD_REMOVED listener)

Remove a listener for the pad-removed signal

Parameters:

listener - The listener that was previously added.

connect

public void connect(Element.NO_MORE_PADS listener)

Add a listener for the no-more-pads signal

Parameters:

listener - Listener to be called when the Element will has finished generating dynamic pads.

disconnect

public void disconnect(Element.NO_MORE_PADS listener)

Remove a listener for the no-more-pads signal

Parameters:

listener - The listener that was previously added.

linkMany

public static boolean linkMany(Element... elements)

Link together a list of elements.

Make sure you have added your elements to a bin or pipeline with Bin.add(org.freedesktop.gstreamer.Element) or Bin.addMany(org.freedesktop.gstreamer.Element...) before trying to link them.

Parameters:

elements - The list of elements to link together.

Returns:

true if all elements successfully linked.

unlinkMany

public static void unlinkMany(Element... elements)

Unlink a list of elements.

Parameters:

elements - The list of elements to link together

linkPads

public static boolean linkPads(Element src,
                               String srcPadName,
                               Element dest,
                               String destPadName)

Link together source and destination pads of two elements. A side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails.

Parameters:

src - The Element containing the source Pad.

srcPadName - The name of the source Pad. Can be null for any pad.

dest - The Element containing the destination Pad.

destPadName - The name of the destination Pad. Can be null for any pad.

Returns:

true if the pads were successfully linked.

linkPadsFiltered

public static boolean linkPadsFiltered(Element src,
                                       String srcPadName,
                                       Element dest,
                                       String destPadName,
                                       Caps caps)

Link together source and destination pads of two elements. A side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. If caps is not null, makes sure that the caps of the link is a subset of caps.

Parameters:

src - The Element containing the source Pad.

srcPadName - The name of the source Pad. Can be null for any pad.

dest - The Element containing the destination Pad.

destPadName - The name of the destination Pad. Can be null for any pad.

caps - The Caps to use to filter the link.

Returns:

true if the pads were successfully linked.

unlinkPads

public static void unlinkPads(Element src,
                              String srcPadName,
                              Element dest,
                              String destPadName)

Unlink source and destination pads of two elements.

Parameters:

src - The Element containing the source Pad.

srcPadName - The name of the source Pad.

dest - The Element containing the destination Pad.

destPadName - The name of the destination Pad.

postMessage

public boolean postMessage(Message message)

Posts a Message on the element's Bus.

Parameters:

message - the Message to post.

Returns:

true if the message was posted, false if the element does not have a Bus.

getClock

public Clock getClock()

Gets the currently configured clock of the element.

Returns:

the clock of the element.

getBaseTime

public long getBaseTime()

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 stream time of the element.

Returns:

the base time of the element

setBaseTime

public void setBaseTime(long time)

Set the base time of an element.

Parameters:

time - the base time to set

See Also:

getBaseTime()

getStartTime

public long getStartTime()

Returns the start time of this element. The start time is the running time of the clock when this element was last put to State.PAUSED. Usually the start_time is managed by a toplevel element such as Pipeline. MT safe.

Returns:

the start time of this element.

setStartTime

public void setStartTime(long time)

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 State.PAUSED state. In State.READY or after a flushing seek, it is set to 0. Toplevel elements like GstPipeline will manage the start_time and base_time on its children. Setting the start_time to long#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.

Parameters:

time - the start time to set

See Also:

getStartTime()

query

public boolean query(Query query)

Performs a query on the element. For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a random linked sinkpad of this element. Please note that some queries might need a running pipeline to work.

Parameters:

query - the Query to perform

Returns:

true if the query could be performed