public class Element extends GstObject
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. Buffer
s 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.gstreamer.Pad)
and removePad(org.gstreamer.Pad)
.
A pad of an element can be retrieved by name with getPad(java.lang.String)
.
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.gstreamer.Element)
convenience function to link two elements, or linkMany(org.gstreamer.Element...)
for more elements in a row.
For finer control, use linkPads(org.gstreamer.Element, java.lang.String, org.gstreamer.Element, java.lang.String)
and linkPadsFiltered(org.gstreamer.Element, java.lang.String, org.gstreamer.Element, java.lang.String, org.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.gstreamer.State)
.
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
|
static interface |
Element.PAD_REMOVED
|
GObject.GCallback
NativeObject.Initializer
defaultInit, ownsHandle
Constructor and Description |
---|
Element(NativeObject.Initializer init)
Creates a new instance of Element.
|
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 |
ClockTime |
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.
|
Pad |
getPad(java.lang.String padname)
Deprecated.
|
java.util.List<Pad> |
getPads()
Retrieves a list of the element's pads.
|
Pad |
getRequestPad(java.lang.String name)
Retrieves a pad from the element by name.
|
java.util.List<Pad> |
getSinkPads()
Retrieves a list of the element's sink pads.
|
java.util.List<Pad> |
getSrcPads()
Retrieves a list of the element's source pads.
|
ClockTime |
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,
java.util.concurrent.TimeUnit units)
Gets the state of the element.
|
Pad |
getStaticPad(java.lang.String padname)
Retrieves a pad from the element by name.
|
boolean |
isPlaying()
Tests if the Element is currently playing.
|
boolean |
link(Element... elems)
Chain together a series of elements, with this element as the first in the list.
|
boolean |
link(Element dest)
Links this element to another element.
|
static boolean |
linkMany(Element... elements)
Link together a list of elements.
|
static boolean |
linkPads(Element src,
java.lang.String srcPadName,
Element dest,
java.lang.String destPadName)
Link together source and destination pads of two elements.
|
static boolean |
linkPadsFiltered(Element src,
java.lang.String srcPadName,
Element dest,
java.lang.String destPadName,
Caps caps)
Link together source and destination pads of two elements.
|
protected static NativeObject.Initializer |
makeRawElement(java.lang.String factoryName,
java.lang.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)
|
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(ClockTime 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(ClockTime 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,
java.lang.String srcPadName,
Element dest,
java.lang.String destPadName)
Unlink source and destination pads of two elements.
|
addListenerProxy, getName, getParent, initializer, initializer, ref, removeListenerProxy, setName, steal, toString, unref
addCallback, connect, connect, connect, disconnect, disconnect, disposeNativeHandle, emit, emit, g_signal_connect, get, getPointer, getPropertyDefaultValue, getPropertyMaximumValue, getPropertyMinimumValue, getType, invalidate, objectForX, removeCallback, set
classFor, disown, dispose, equals, finalize, getNativeAddress, handle, hashCode, initializer, instanceFor, isDisposed, nativeValue, objectFor, objectFor, objectFor, objectFor
public Element(NativeObject.Initializer init)
init
- internal initialization data.protected static NativeObject.Initializer makeRawElement(java.lang.String factoryName, java.lang.String elementName)
factoryName
- The name of the factory to use to produce the ElementelementName
- The name to assign to the created Elementpublic boolean link(Element dest)
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.gstreamer.Element)
or Bin.addMany(org.gstreamer.Element...)
before trying to link them.
dest
- The Element
containing the destination pad.public boolean link(Element... elems)
Make sure you have added your elements to a bin or pipeline with
Bin.add(org.gstreamer.Element)
or Bin.addMany(org.gstreamer.Element...)
before trying to link them.
elems
- The list of elements to be linked.public void unlink(Element dest)
If the link has been made using link(org.gstreamer.Element)
, it could have created an
requestpad, which has to be released using gst_element_release_request_pad().
dest
- The sink Element to unlink.public boolean isPlaying()
public StateChangeReturn play()
public StateChangeReturn ready()
public StateChangeReturn pause()
public StateChangeReturn stop()
public StateChangeReturn setState(State state)
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.
state
- the element's new State
.public boolean setLockedState(boolean locked_state)
locked_state
- true to lock the element's State
.public State getState()
This method will wait until any async state change has completed.
State
the Element is currently in.public State getState(long timeout, java.util.concurrent.TimeUnit units)
For elements that performed an ASYNC state change, as reported by
setState(org.gstreamer.State)
, this function will block up to the
specified timeout value for the state change to complete.
timeout
- the amount of time to wait.units
- the units of the timeout.State
the Element is currently in.public State getState(long timeout)
For elements that performed an ASYNC state change, as reported by
setState(org.gstreamer.State)
, this function will block up to the
specified timeout value for the state change to complete.
timeout
- The amount of time in nanoseconds to wait.State
the Element is currently in.public void getState(long timeout, State[] states)
For elements that performed an ASYNC state change, as reported by
setState(org.gstreamer.State)
, this function will block up to the
specified timeout value for the state change to complete.
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.public boolean syncStateWithParent()
public void setCaps(Caps caps)
Caps
on this Element.caps
- the new Caps to set.@Deprecated public Pad getPad(java.lang.String padname)
getStaticPad(java.lang.String)
public Pad getStaticPad(java.lang.String padname)
public java.util.List<Pad> getPads()
Pad
s.public java.util.List<Pad> getSrcPads()
Pad
s.public java.util.List<Pad> getSinkPads()
Pad
s.public boolean addPad(Pad pad)
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.
pad
- The Pad
to add.public Pad getRequestPad(java.lang.String name)
releaseRequestPad(org.gstreamer.Pad)
.name
- the name of the request Pad
to retrieve.releaseRequestPad(org.gstreamer.Pad)
after usage.public void releaseRequestPad(Pad pad)
getRequestPad(java.lang.String)
.pad
- the pad to release.public boolean removePad(Pad pad)
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.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.
pad
- The Pad
to remove.public ElementFactory getFactory()
ElementFactory
used for creating this element.public Bus getBus()
Pipeline
will provide a
bus for the application.Bus
public boolean sendEvent(Event ev)
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.
ev
- The Event
to send.public void connect(Element.PAD_ADDED listener)
pad-added
signalpublic void disconnect(Element.PAD_ADDED listener)
pad-added
signallistener
- The listener that was previously added.public void connect(Element.PAD_REMOVED listener)
pad-added
signalpublic void disconnect(Element.PAD_REMOVED listener)
pad-removed
signallistener
- The listener that was previously added.public void connect(Element.NO_MORE_PADS listener)
no-more-pads
signallistener
- Listener to be called when the Element
will has
finished generating dynamic pads.public void disconnect(Element.NO_MORE_PADS listener)
no-more-pads
signallistener
- The listener that was previously added.public static boolean linkMany(Element... elements)
Make sure you have added your elements to a bin or pipeline with
Bin.add(org.gstreamer.Element)
or Bin.addMany(org.gstreamer.Element...)
before trying to link them.
elements
- The list of elements to link together.public static void unlinkMany(Element... elements)
elements
- The list of elements to link togetherpublic static boolean linkPads(Element src, java.lang.String srcPadName, Element dest, java.lang.String destPadName)
public static boolean linkPadsFiltered(Element src, java.lang.String srcPadName, Element dest, java.lang.String destPadName, Caps caps)
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.public static void unlinkPads(Element src, java.lang.String srcPadName, Element dest, java.lang.String destPadName)
public boolean postMessage(Message message)
message
- the Message to post.Bus
.public Clock getClock()
public ClockTime getBaseTime()
public void setBaseTime(ClockTime time)
time
- the base time to setgetBaseTime()
public ClockTime getStartTime()
State.PAUSED
. Usually the start_time is managed by a toplevel element such as Pipeline
.
MT safe.public void setStartTime(ClockTime time)
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 ClockTime.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 start time to setgetStartTime()