org.freedesktop.gstreamer

Class Pad

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

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

GhostPad

public class Pad
extends GstObject

Object contained by elements that allows links to other elements.

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

An 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, the pads can be link with link(org.freedesktop.gstreamer.Pad). (For quick links, you can also use Element.link(org.freedesktop.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. queryCaps(org.freedesktop.gstreamer.Caps) and #setCaps 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.freedesktop.gstreamer.event.Event) and pushEvent(org.freedesktop.gstreamer.event.Event).

See Also:

PadTemplate, Element, Event

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Pad.DATA_PROBE Probe for listening when new data is available on the Pad.
static interface	Pad.EVENT_PROBE Probe for listening when an event passes through this Pad.
static interface	Pad.LINKED Signal emitted when new this Pad is linked to another Pad
static interface	Pad.PROBE Callback used by #addProbe(java.util.EnumSet, org.freedesktop.gstreamer.Pad.PROBE)
static interface	Pad.UNLINKED Signal emitted when new this Pad is disconnected from a peer Pad

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

Constructor and Description
Pad(PadTemplate template, String name) Creates a new pad with the given name from the given template.
Pad(String name, PadDirection direction) Creates a new pad with the given name in the given direction.

Method Summary

Modifier and Type	Method and Description
void	addDataProbe(Pad.DATA_PROBE listener)
void	addEventProbe(Pad.EVENT_PROBE listener)
void	addProbe(PadProbeType mask, Pad.PROBE callback) Be notified of different states of pads.
void	addProbe(Set<PadProbeType> mask, Pad.PROBE callback) Be notified of different states of pads.
void	block(Runnable callback) Run a runnable under a blocked state
FlowReturn	chain(Buffer buffer) Chain a buffer to pad.
void	connect(Pad.LINKED listener) Add a listener for the linked signal on this Pad
void	connect(Pad.UNLINKED listener) Add a listener for the unlinked signal on this Pad
void	disconnect(Pad.LINKED listener) Remove a listener for the linked 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	getCurrentCaps() Gets the capabilities currently configured on pad with the last GST_EVENT_CAPS event.
PadDirection	getDirection() Get the direction of the pad.
Element	getParentElement() Get the parent of this pad, cast to an Element.
Pad	getPeer() Get the peer of this pad.
FlowReturn	getRange(long offset, int size, Buffer[] buffer) When pad is flushing this function returns FlowReturn.FLUSHING immediately.
PadTemplate	getTemplate() Gets the template for pad.
boolean	hasCurrentCaps() Check if the pad has caps set on it with a GST_EVENT_CAPS events
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.
void	link(Pad sink) Links this source pad and a sink pad.
boolean	peerQueryAcceptCaps(Caps caps) Check if the peer of this pad accepts the caps.
Caps	peerQueryCaps(Caps filter) Get the capabilities of the peer connected to this pad.
FlowReturn	pullRange(long offset, int size, Buffer[] buffer) Pulls a buffer from the peer pad.
FlowReturn	push(Buffer buffer) Pushes a buffer to the peer of pad .
boolean	pushEvent(Event event) Sends the event to the peer of this pad.
boolean	queryAcceptCaps(Caps caps) Check if the pad accepts the given caps.
Caps	queryCaps(Caps filter) Gets the capabilities this pad can produce or consume.
void	removeDataProbe(Pad.DATA_PROBE listener)
void	removeEventProbe(Pad.EVENT_PROBE listener)
void	removeProbe(Pad.PROBE callback) Remove the provided probe callback from the Pad.
boolean	sendEvent(Event event) Sends the event to this pad.
boolean	setActive(boolean active) Activates or deactivates the given pad.
boolean	unlink(Pad pad) Unlinks the source pad from the sink pad.

Methods inherited from class org.freedesktop.gstreamer.GstObject

addControlBinding, getAsString, getControlBinding, getName, getParent, hasActiveControlBindings, removeControlBinding, setAsString, 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

Pad

public Pad(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,
           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

queryCaps

public Caps queryCaps(Caps filter)

Gets the capabilities this pad can produce or consume. Note that this method doesn't necessarily return the caps set by sending a gst_event_new_caps() - use getCurrentCaps() for that instead. queryCaps returns all possible caps a pad can operate with, using the pad's CAPS query function, If the query fails, this function will return filter, if not NULL, otherwise ANY.

When called on sinkpads filter contains the caps that upstream could produce in the order preferred by upstream. When called on srcpads filter contains the caps accepted by downstream in the preferred order. filter might be NULL but if it is not NULL the returned caps will be a subset of filter .

Note that this function does not return writable Caps.

Parameters:

filter - suggested Caps or null

Returns:

a newly allocated copy of the Caps of this pad.

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 queryCaps(org.freedesktop.gstreamer.Caps) on this pad and its peer.

MT safe.

Returns:

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

getCurrentCaps

public Caps getCurrentCaps()

Gets the capabilities currently configured on pad with the last GST_EVENT_CAPS event.

Returns:

the negotiated #GstCaps or null if this pad has no current caps

getPeer

public Pad getPeer()

Get the peer of this pad. MT safe.

Returns:

The peer Pad of this Pad.

peerQueryCaps

public Caps peerQueryCaps(Caps filter)

Get the capabilities of the peer connected to this pad.

When called on srcpads filter contains the caps that upstream could produce in the order preferred by upstream. When called on sinkpads filter contains the caps accepted by downstream in the preferred order. filter might be NULL but if it is not NULL the returned caps will be a subset of filter .

Parameters:

filter - Caps to filter by, or null

Returns:

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

queryAcceptCaps

public boolean queryAcceptCaps(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.

peerQueryAcceptCaps

public boolean peerQueryAcceptCaps(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 void link(Pad sink)
          throws PadLinkException

Links this source pad and a sink pad. MT Safe.

Parameters:

sink - the sink Pad to link.

Throws:

PadLinkException - if pads cannot be linked.

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

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.

block

public void block(Runnable callback)

Run a runnable under a blocked state

Parameters:

callback - The code to run when pad is blocked

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

Returns:

true if the pad is blocking.

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.

addProbe

public void addProbe(Set<PadProbeType> mask,
                     Pad.PROBE callback)

Be notified of different states of pads. The provided callback is called for every state that matches mask.

Probes are called in groups: First PadProbeType.BLOCK probes are called, then others, then finally PadProbeType.IDLE. The only exception here are IDLE probes that are called immediately if the pad is already idle while calling addProbe(). In each of the groups, probes are called in the order in which they were added.

Parameters:

mask - set of mask flags for probe - common options are fields of PadProbeType

callback - callback that will be called with notifications of the pad state

addProbe

public void addProbe(PadProbeType mask,
                     Pad.PROBE callback)

Be notified of different states of pads. The provided callback is called for every state that matches mask.

Probes are called in groups: First PadProbeType.BLOCK probes are called, then others, then finally PadProbeType.IDLE. The only exception here are IDLE probes that are called immediately if the pad is already idle while calling addProbe(). In each of the groups, probes are called in the order in which they were added.

Parameters:

mask - mask flag for probe

callback - callback that will be called with notifications of the pad state

removeProbe

public void removeProbe(Pad.PROBE callback)

Remove the provided probe callback from the Pad.

Parameters:

callback - callback to remove

addEventProbe

public void addEventProbe(Pad.EVENT_PROBE listener)

removeEventProbe

public void removeEventProbe(Pad.EVENT_PROBE listener)

addDataProbe

public void addDataProbe(Pad.DATA_PROBE listener)

removeDataProbe

public void removeDataProbe(Pad.DATA_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.FLUSHING 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.FLUSHING immediately.

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.freedesktop.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.freedesktop.gstreamer.Buffer[]) on the peer pad. See getRange(long, int, org.freedesktop.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.

push

public FlowReturn push(Buffer buffer)

Pushes a buffer to the peer of pad . This function will call installed block probes before triggering any installed data probes.

The function proceeds calling gst_pad_chain() on the peer pad and returns the value from that function. If pad has no peer, FlowReturn.NOT_LINKED will be returned.

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

Parameters:

buffer - the GstBuffer to push returns GST_FLOW_ERROR if not. [transfer full]

Returns:

a GstFlowReturn from the peer pad. MT safe.

getTemplate

public PadTemplate getTemplate()

Gets the template for pad.

Returns:

the GstPadTemplate from which this pad was instantiated, or NULL if this pad has no template.

hasCurrentCaps

public boolean hasCurrentCaps()

Check if the pad has caps set on it with a GST_EVENT_CAPS events

Returns:

true if the pad has caps set