org.gstreamer
Class Element

java.lang.Object
  extended by org.gstreamer.lowlevel.NativeValue
      extended by org.gstreamer.lowlevel.Handle
          extended by org.gstreamer.lowlevel.NativeObject
              extended by org.gstreamer.lowlevel.RefCountedObject
                  extended by org.gstreamer.GObject
                      extended by org.gstreamer.GstObject
                          extended by org.gstreamer.Element
Direct Known Subclasses:
BaseSink, BaseSrc, Bin, TypeFind

public class Element
extends GstObject

Abstract base class for all pipeline elements.

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.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).


Nested Class Summary
static interface Element.HANDOFF
          Signal emitted when this Element has a Buffer ready.
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.gstreamer.GObject
GObject.GCallback
 
Nested classes/interfaces inherited from class org.gstreamer.lowlevel.NativeObject
NativeObject.Initializer
 
Field Summary
 
Fields inherited from class org.gstreamer.lowlevel.NativeObject
defaultInit, ownsHandle
 
Constructor Summary
Element(NativeObject.Initializer init)
          Creates a new instance of Element.
 
Method Summary
 boolean addPad(Pad pad)
          Adds a Pad (link point) to the Element.
 void connect(Element.HANDOFF listener)
          Add a listener for the handoff signal on this Bin
 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.HANDOFF listener)
          Remove a listener for the handoff 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. Use getStaticPad(java.lang.String)
 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.
 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 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.
 boolean postMessage(Message message)
          Posts a Message on the element's Bus.
 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 setCaps(Caps caps)
          Sets the Caps on this Element.
 StateChangeReturn setState(State state)
          Sets the state of the element.
 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.
 
Methods inherited from class org.gstreamer.GstObject
addListenerProxy, getName, initializer, initializer, objectFor, objectFor, ref, removeListenerProxy, setName, steal, toString, unref
 
Methods inherited from class org.gstreamer.GObject
addCallback, connect, connect, connect, disconnect, disconnect, disposeNativeHandle, g_signal_connect, get, getPointer, invalidate, objectFor, removeCallback, set
 
Methods inherited from class org.gstreamer.lowlevel.NativeObject
classFor, disown, dispose, equals, finalize, getNativeAddress, handle, hashCode, initializer, instanceFor, isDisposed, nativeValue, objectFor, objectFor
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Element

public 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(java.lang.String factoryName,
                                                         java.lang.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.gstreamer.Element) or Bin.addMany(org.gstreamer.Element...) before trying to link them.

Parameters:
dest - The Element containing the destination pad.
Returns:
true if the elements could be linked, false otherwise.

link

public boolean link(Element... elems)
Chain together a series of elements, with this element as the first in the list.

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.

Parameters:
elems - The list of elements to be linked.
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.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.

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.

setCaps

public void setCaps(Caps caps)
Sets the Caps on this Element.

Parameters:
caps - the new Caps to set.

getPad

@Deprecated
public Pad getPad(java.lang.String padname)
Deprecated. Use getStaticPad(java.lang.String)


getStaticPad

public Pad getStaticPad(java.lang.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 java.util.List<Pad> getPads()
Retrieves a list of the element's pads.

Returns:
the List of Pads.

getSrcPads

public java.util.List<Pad> getSrcPads()
Retrieves a list of the element's source pads.

Returns:
the List of Pads.

getSinkPads

public java.util.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(java.lang.String name)
Retrieves a pad from the element by name. This version only retrieves request pads. The pad must be released with releaseRequestPad(org.gstreamer.Pad).

Parameters:
name - the name of the request Pad to retrieve.
Returns:
the requested Pad if found, otherwise null. Release using releaseRequestPad(org.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.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.

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,
                      java.util.concurrent.TimeUnit units)
Gets the state of the element.

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.

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.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.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.

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.

connect

public void connect(Element.HANDOFF listener)
Add a listener for the handoff signal on this Bin

Parameters:
listener - The listener to be called when a Buffer is ready.

disconnect

public void disconnect(Element.HANDOFF listener)
Remove a listener for the handoff 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.gstreamer.Element) or Bin.addMany(org.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,
                               java.lang.String srcPadName,
                               Element dest,
                               java.lang.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,
                                       java.lang.String srcPadName,
                                       Element dest,
                                       java.lang.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,
                              java.lang.String srcPadName,
                              Element dest,
                              java.lang.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 ClockTime 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