org.gstreamer
Class Pad

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.Pad
Direct Known Subclasses:
GhostPad

public class Pad
extends GstObject

Object contained by elements that allows links to other elements.

A Element is linked to other elements via "pads", which are extremely light-weight generic link points. After two pads are retrieved from an element with Element.getPad(java.lang.String), the pads can be link with link(org.gstreamer.Pad). (For quick links, you can also use Element.link(org.gstreamer.Element), which will make the obvious link for you if it's straightforward.)

Pads are typically created from a PadTemplate with Pad(PadTemplate, String).

Pads have Caps attached to it to describe the media type they are capable of dealing with. getCaps() and setCaps(org.gstreamer.Caps) are used to manipulate the caps of the pads. Pads created from a pad template cannot set capabilities that are incompatible with the pad template capabilities.

Pads without pad templates can be created with gst_pad_new(), which takes a direction and a name as an argument. If the name is NULL, then a guaranteed unique name will be assigned to it.

getParentElement() will retrieve the Element that owns the pad.

An Element creating a pad will typically use the various gst_pad_set_*_function() calls to register callbacks for various events on the pads.

GstElements will use gst_pad_push() and gst_pad_pull_range() to push out or pull in a buffer.

To send an Event on a pad, use sendEvent(org.gstreamer.Event) and pushEvent(org.gstreamer.Event).

See Also:
PadTemplate, Element, Event

Nested Class Summary
static interface Pad.EVENT_PROBE
          Signal emitted when an event passes through this Pad.
static interface Pad.HAVE_DATA
          Signal emitted when new data is available on the Pad
static interface Pad.LINKED
          Signal emitted when new this Pad is linked to another Pad
static interface Pad.REQUEST_LINK
          Signal emitted when a connection to a peer Pad is requested.
static interface Pad.UNLINKED
          Signal emitted when new this Pad is disconnected from a peer Pad
 
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
Pad(NativeObject.Initializer init)
          Creates a new instance of Pad
Pad(PadTemplate template, java.lang.String name)
          Creates a new pad with the given name from the given template.
Pad(java.lang.String name, PadDirection direction)
          Creates a new pad with the given name in the given direction.
 
Method Summary
 boolean acceptCaps(Caps caps)
          Check if the pad accepts the given caps.
 void addEventProbe(Pad.EVENT_PROBE listener)
           
 FlowReturn chain(Buffer buffer)
          Chain a buffer to pad.
 void connect(Pad.HAVE_DATA listener)
          Add a listener for the have-data signal on this Pad
 void connect(Pad.LINKED listener)
          Add a listener for the linked signal on this Pad
 void connect(Pad.REQUEST_LINK listener)
          Add a listener for the request-link signal on this Pad
 void connect(Pad.UNLINKED listener)
          Add a listener for the unlinked signal on this Pad
 void disconnect(Pad.HAVE_DATA listener)
          Remove a listener for the have-data signal on this Pad
 void disconnect(Pad.LINKED listener)
          Remove a listener for the linked signal on this Pad
 void disconnect(Pad.REQUEST_LINK listener)
          Remove a listener for the request-link signal on this Pad
 void disconnect(Pad.UNLINKED listener)
          Remove a listener for the unlinked signal on this Pad
 Caps getAllowedCaps()
          Gets the capabilities of the allowed media types that can flow through this pad and its peer.
 Caps getCaps()
          Get the capabilities this pad can produce or consume.
 PadDirection getDirection()
          Get the direction of the pad.
 Caps getNegotiatedCaps()
          Get the capabilities of the media type that currently flows through this pad and its peer.
 Element getParentElement()
          Get the parent of this pad, cast to a Element.
 Pad getPeer()
          Get the peer of this pad.
 Caps getPeerCaps()
          Get the capabilities of the peer connected to this pad.
 FlowReturn getRange(long offset, int size, Buffer[] buffer)
          When pad is flushing this function returns FlowReturn.WRONG_STATE immediatly.
 boolean isBlocked()
          Checks if the pad is blocked or not.
 boolean isBlocking()
          Checks if the pad is blocking or not.
 boolean isLinked()
          Check if this pad is linked to another pad or not.
 PadLinkReturn link(Pad pad)
          Links this pad and a sink pad.
 boolean peerAcceptCaps(Caps caps)
          Check if the peer of this pad accepts the caps.
 FlowReturn pullRange(long offset, int size, Buffer[] buffer)
          Pulls a buffer from the peer pad.
 boolean pushEvent(Event event)
          Sends the event to the peer of this pad.
 void removeEventProbe(Pad.EVENT_PROBE listener)
           
 boolean sendEvent(Event event)
          Sends the event to this pad.
 boolean setActive(boolean active)
          Activates or deactivates the given pad.
 boolean setBlocked(boolean blocked)
          Blocks or unblocks the dataflow on a pad.
 boolean setBlockedAsync(boolean blocked, GstPadAPI.PadBlockCallback callback)
           
 boolean setCaps(Caps caps)
          Sets the capabilities of this pad.
 boolean unlink(Pad pad)
          Unlinks the source pad from the sink pad.
 
Methods inherited from class org.gstreamer.GstObject
addListenerProxy, getName, getParent, 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, getPropertyDefaultValue, getPropertyMaximumValue, getPropertyMinimumValue, 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

Pad

public Pad(NativeObject.Initializer init)
Creates a new instance of Pad


Pad

public Pad(java.lang.String name,
           PadDirection direction)
Creates a new pad with the given name in the given direction. If name is null, a guaranteed unique name (across all pads) will be assigned.

Parameters:
name - The name of the new pad.
direction - The direction of the new pad.

Pad

public Pad(PadTemplate template,
           java.lang.String name)
Creates a new pad with the given name from the given template. If name is null, a guaranteed unique name (across all pads) will be assigned.

Parameters:
template - The pad template to use.
name - The name of the new pad.
Method Detail

getCaps

public Caps getCaps()
Get the capabilities this pad can produce or consume. This method returns all possible caps a pad can operate with, using the pad's get_caps function; not just the Caps as set by setCaps(org.gstreamer.Caps). This returns the pad template caps if not explicitly set. MT safe.

Returns:
a newly allocated copy of the Caps of this pad.

setCaps

public boolean setCaps(Caps caps)
Sets the capabilities of this pad. The caps must be fixed. Any previous caps on the pad will be destroyed. It is possible to set null caps, which will make the pad unnegotiated again. MT safe.

Parameters:
caps - The Caps to set.
Returns:
true if the caps could be set. false if the caps were not fixed or bad parameters were provided to this function.

getAllowedCaps

public Caps getAllowedCaps()
Gets the capabilities of the allowed media types that can flow through this pad and its peer. The allowed capabilities is calculated as the intersection of the results of calling getCaps() on this pad and its peer. MT safe.

Returns:
The allowed Caps of the pad link, or null if this pad has no peer.

getNegotiatedCaps

public Caps getNegotiatedCaps()
Get the capabilities of the media type that currently flows through this pad and its peer. This function can be used on both src and sink pads. Note that srcpads are always negotiated before sinkpads so it is possible that the negotiated caps on the srcpad do not match the negotiated caps of the peer. MT safe.

Returns:
the negotiated #GstCaps of the pad link, or null if this pad has no peer, or is not negotiated yet

getPeer

public Pad getPeer()
Get the peer of this pad. MT safe.

Returns:
The peer Pad of this Pad.

getPeerCaps

public Caps getPeerCaps()
Get the capabilities of the peer connected to this pad.

Returns:
the Caps of the peer pad, or null if there is no peer pad.

acceptCaps

public boolean acceptCaps(Caps caps)
Check if the pad accepts the given caps.

Parameters:
caps - a Caps to check on the pad.
Returns:
true if the pad can accept the caps.

peerAcceptCaps

public boolean peerAcceptCaps(Caps caps)
Check if the peer of this pad accepts the caps. If this pad has no peer, this method returns true.

Parameters:
caps - Caps to check on the pad
Returns:
true if the peer pad can accept the caps or this pad no peer.

link

public PadLinkReturn link(Pad pad)
Links this pad and a sink pad. MT Safe.

Parameters:
pad - the sink Pad to link.
Returns:
A result code indicating if the connection worked or what went wrong.

unlink

public boolean unlink(Pad pad)
Unlinks the source pad from the sink pad. Will emit the "unlinked" signal on both pads. MT safe.

Parameters:
pad - the sink Pad to unlink.
Returns:
true if the pads were unlinked. This function returns false if the pads were not linked together.

isLinked

public boolean isLinked()
Check if this pad is linked to another pad or not.

Returns:
true if the pad is linked, else false.

getDirection

public PadDirection getDirection()
Get the direction of the pad. The direction of the pad is decided at construction time so this function does not take the LOCK.

Returns:
The PadDirection of the pad.

getParentElement

public Element getParentElement()
Get the parent of this pad, cast to a Element. If this pad has no parent or its parent is not an element, returns null.

Returns:
The parent of the pad.

setActive

public boolean setActive(boolean active)
Activates or deactivates the given pad. Normally called from within core state change functions. If active is true, makes sure the pad is active. If it is already active, either in push or pull mode, just return. Otherwise dispatches to the pad's activate function to perform the actual activation. If not @active, checks the pad's current mode and calls gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a FALSE argument.

Parameters:
active - whether or not the pad should be active.
Returns:
true if the operation was successful.

setBlocked

public boolean setBlocked(boolean blocked)
Blocks or unblocks the dataflow on a pad. MT safe.

Parameters:
blocked - boolean indicating we should block or unblock
Returns:
true if the pad could be blocked. This function can fail if the wrong parameters were passed or the pad was already in the requested state.

isBlocked

public boolean isBlocked()
Checks if the pad is blocked or not. This function returns the last requested state of the pad. It is not certain that the pad is actually blocking at this point (see isBlocking()).

Returns:
true if the pad is blocked.

setBlockedAsync

public boolean setBlockedAsync(boolean blocked,
                               GstPadAPI.PadBlockCallback callback)

isBlocking

public boolean isBlocking()
Checks if the pad is blocking or not. This is a guaranteed state of whether the pad is actually blocking on a Buffer or a Event.

Returns:
true if the pad is blocking.

connect

public void connect(Pad.HAVE_DATA listener)
Add a listener for the have-data signal on this Pad

Parameters:
listener - The listener to be called when data is available.

disconnect

public void disconnect(Pad.HAVE_DATA listener)
Remove a listener for the have-data signal on this Pad

Parameters:
listener - The listener previously added for this signal.

connect

public void connect(Pad.LINKED listener)
Add a listener for the linked signal on this Pad

Parameters:
listener - The listener to be called when a peer Pad is linked.

disconnect

public void disconnect(Pad.LINKED listener)
Remove a listener for the linked signal on this Pad

Parameters:
listener - The listener previously added for this signal.

connect

public void connect(Pad.UNLINKED listener)
Add a listener for the unlinked signal on this Pad

Parameters:
listener - The listener to be called when when a peer Pad is unlinked.

disconnect

public void disconnect(Pad.UNLINKED listener)
Remove a listener for the unlinked signal on this Pad

Parameters:
listener - The listener previously added for this signal.

connect

public void connect(Pad.REQUEST_LINK listener)
Add a listener for the request-link signal on this Pad

Parameters:
listener - The listener to be called when a peer Pad requests to be linked to this one.

disconnect

public void disconnect(Pad.REQUEST_LINK listener)
Remove a listener for the request-link signal on this Pad

Parameters:
listener - The listener previously added for this signal.

addEventProbe

public void addEventProbe(Pad.EVENT_PROBE listener)

removeEventProbe

public void removeEventProbe(Pad.EVENT_PROBE listener)

sendEvent

public boolean sendEvent(Event event)
Sends the event to this pad.

This function can be used by applications to send events in the pipeline.

If this pad is a source pad, event should be an upstream event. If this pad is a sink pad, event should be a downstream event.

For example, you would not send a EventType.EOS on a src pad; EOS events only propagate downstream.

Furthermore, some downstream events have to be serialized with data flow, like EOS, while some can travel out-of-band, like EventType.FLUSH_START. If the event needs to be serialized with data flow, this function will take the pad's stream lock while calling its event function.

Parameters:
event - the event to send.
Returns:
true if the event was handled.

pushEvent

public boolean pushEvent(Event event)
Sends the event to the peer of this pad.

This function is mainly used by elements to send events to their peer elements.

Parameters:
event - the event to send
Returns:
true if the event was handled

chain

public FlowReturn chain(Buffer buffer)
Chain a buffer to pad.

The function returns FlowReturn.WRONG_STATE if the pad was flushing.

If the caps on buffer are different from the current caps on pad, this function will call any function installed on pad (see gst_pad_set_setcaps_function()). If the new caps are not acceptable for pad, this function returns FlowReturn.NOT_NEGOTIATED.

The function proceeds calling the chain function installed on pad and the return value of that function is returned to the caller. FlowReturn.NOT_SUPPORTED is returned if pad has no chain function.

In all cases, success or failure, the caller loses its reference to buffer after calling this function.

Parameters:
buffer - the Buffer, returns FlowReturn.ERROR if NULL.
Returns:
a org.gstreamer.FlowReturn

getRange

public FlowReturn getRange(long offset,
                           int size,
                           Buffer[] buffer)
When pad is flushing this function returns FlowReturn.WRONG_STATE immediatly.

Calls the getRange function of pad, see GstPadGetRangeFunction for a description of a getRange function. If pad has no getRange function installed (see gst_pad_set_getrange_function()) this function returns FlowReturn.NOT_SUPPORTED. This is a lowlevel function. Usualy pullRange(long, int, org.gstreamer.Buffer[]) is used.

Parameters:
offset - The start offset of the buffer
size - The length of the buffer
buffer - the Buffer, returns FlowReturn.ERROR if NULL.
Returns:
a FlowReturn from the peer pad. When this function returns OK, buffer will contain a valid Buffer.

pullRange

public FlowReturn pullRange(long offset,
                            int size,
                            Buffer[] buffer)
Pulls a buffer from the peer pad.

This function will first trigger the pad block signal if it was installed.

When pad is not linked FlowReturn.NOT_LINKED is returned else this function returns the result of getRange(long, int, org.gstreamer.Buffer[]) on the peer pad. See getRange(long, int, org.gstreamer.Buffer[]) for a list of return values and for the semantics of the arguments of this function.

buffer's caps must either be unset or the same as what is already configured on pad. Renegotiation within a running pull-mode pipeline is not supported.

Parameters:
offset - The start offset of the buffer
size - The length of the buffer
buffer - the Buffer, returns FlowReturn.ERROR if NULL.
Returns:
a FlowReturn from the peer pad. When this function returns OK, buffer will contain a valid Buffer. MT safe.