Top |
Functions
Properties
GstCaps * | caps | Read |
GstPadDirection | direction | Read / Write / Construct Only |
gint64 | offset | Read / Write |
GstPadTemplate * | template | Read / Write |
Types and Values
struct | GstPad |
enum | GstPadDirection |
enum | GstPadFlags |
enum | GstPadLinkReturn |
enum | GstPadLinkCheck |
enum | GstFlowReturn |
enum | GstPadMode |
enum | GstPadProbeReturn |
enum | GstPadProbeType |
struct | GstPadProbeInfo |
Description
A GstElement is linked to other elements via "pads", which are extremely light-weight generic link points.
Pads have a GstPadDirection, source pads produce data, sink pads consume data.
Pads are typically created from a GstPadTemplate with
gst_pad_new_from_template()
and are then added to a GstElement. This usually
happens when the element is created but it can also happen dynamically based
on the data that the element is processing or based on the pads that the
application requests.
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.
A GstElement creating a pad will typically use the various gst_pad_set_*_function() calls to register callbacks for events, queries or dataflow on the pads.
gst_pad_get_parent() will retrieve the GstElement that owns the pad.
After two pads are retrieved from an element by gst_element_get_static_pad()
,
the pads can be linked with gst_pad_link()
. (For quick links,
you can also use gst_element_link()
, which will make the obvious
link for you if it's straightforward.). Pads can be unlinked again with
gst_pad_unlink()
. gst_pad_get_peer()
can be used to check what the pad is
linked to.
Before dataflow is possible on the pads, they need to be activated with
gst_pad_set_active()
.
gst_pad_query() and gst_pad_peer_query()
can be used to query various
properties of the pad and the stream.
To send a GstEvent on a pad, use gst_pad_send_event()
and
gst_pad_push_event()
. Some events will be sticky on the pad, meaning that
after they pass on the pad they can be queried later with
gst_pad_get_sticky_event()
and gst_pad_sticky_events_foreach()
.
gst_pad_get_current_caps()
and gst_pad_has_current_caps()
are convenience
functions to query the current sticky CAPS event on a pad.
GstElements will use gst_pad_push()
and gst_pad_pull_range()
to push out
or pull in a buffer.
The dataflow, events and queries that happen on a pad can be monitored with
probes that can be installed with gst_pad_add_probe()
. gst_pad_is_blocked()
can be used to check if a block probe is installed on the pad.
gst_pad_is_blocking()
checks if the blocking probe is currently blocking the
pad. gst_pad_remove_probe()
is used to remove a previously installed probe
and unblock blocking probes if any.
Pad have an offset that can be retrieved with gst_pad_get_offset()
. This
offset will be applied to the running_time of all data passing over the pad.
gst_pad_set_offset()
can be used to change the offset.
Convenience functions exist to start, pause and stop the task on a pad with
gst_pad_start_task()
, gst_pad_pause_task()
and gst_pad_stop_task()
respectively.
Functions
gst_pad_link_get_name ()
const gchar *
gst_pad_link_get_name (GstPadLinkReturn ret
);
Gets a string representing the given pad-link return.
Since: 1.4
GST_PAD_LINK_FAILED()
#define GST_PAD_LINK_FAILED(ret) ((ret) < GST_PAD_LINK_OK)
Macro to test if the given GstPadLinkReturn value indicates a failed link step.
GST_PAD_LINK_SUCCESSFUL()
#define GST_PAD_LINK_SUCCESSFUL(ret) ((ret) >= GST_PAD_LINK_OK)
Macro to test if the given GstPadLinkReturn value indicates a successful link step.
gst_flow_get_name ()
const gchar *
gst_flow_get_name (GstFlowReturn ret
);
Gets a string representing the given flow return.
gst_flow_to_quark ()
GQuark
gst_flow_to_quark (GstFlowReturn ret
);
Get the unique quark for the given GstFlowReturn.
gst_pad_mode_get_name ()
const gchar *
gst_pad_mode_get_name (GstPadMode mode
);
Return the name of a pad mode, for use in debug messages mostly.
gst_pad_store_sticky_event ()
GstFlowReturn gst_pad_store_sticky_event (GstPad *pad
,GstEvent *event
);
Store the sticky event
on pad
Returns
GST_FLOW_OK on success, GST_FLOW_FLUSHING when the pad was flushing or GST_FLOW_EOS when the pad was EOS.
Since: 1.2
gst_pad_get_name()
#define gst_pad_get_name(pad) gst_object_get_name (GST_OBJECT_CAST (pad))
Get a copy of the name of the pad. g_free()
after usage.
MT safe.
gst_pad_get_direction ()
GstPadDirection
gst_pad_get_direction (GstPad *pad
);
Gets the direction of the pad. The direction of the pad is decided at construction time so this function does not take the LOCK.
gst_pad_get_parent()
#define gst_pad_get_parent(pad) gst_object_get_parent (GST_OBJECT_CAST (pad))
Get the parent of pad
. This function increases the refcount
of the parent object so you should gst_object_unref()
it after usage.
Can return NULL
if the pad did not have a parent.
MT safe.
gst_pad_get_parent_element ()
GstElement *
gst_pad_get_parent_element (GstPad *pad
);
Gets the parent of pad
, cast to a GstElement. If a pad
has no parent or
its parent is not an element, return NULL
.
gst_pad_get_pad_template ()
GstPadTemplate *
gst_pad_get_pad_template (GstPad *pad
);
Gets the template for pad
.
Returns
the GstPadTemplate from which
this pad was instantiated, or NULL
if this pad has no
template. Unref after usage.
[transfer full][nullable]
gst_pad_link ()
GstPadLinkReturn gst_pad_link (GstPad *srcpad
,GstPad *sinkpad
);
Links the source pad and the sink pad.
gst_pad_link_full ()
GstPadLinkReturn gst_pad_link_full (GstPad *srcpad
,GstPad *sinkpad
,GstPadLinkCheck flags
);
Links the source pad and the sink pad.
This variant of gst_pad_link provides a more granular control on the checks being done when linking. While providing some considerable speedups the caller of this method must be aware that wrong usage of those flags can cause severe issues. Refer to the documentation of GstPadLinkCheck for more information.
MT Safe.
gst_pad_link_maybe_ghosting ()
gboolean gst_pad_link_maybe_ghosting (GstPad *src
,GstPad *sink
);
Links src
to sink
, creating any GstGhostPad's in between as necessary.
This is a convenience function to save having to create and add intermediate GstGhostPad's as required for linking across GstBin boundaries.
If src
or sink
pads don't have parent elements or do not share a common
ancestor, the link will fail.
Since: 1.10
gst_pad_link_maybe_ghosting_full ()
gboolean gst_pad_link_maybe_ghosting_full (GstPad *src
,GstPad *sink
,GstPadLinkCheck flags
);
Links src
to sink
, creating any GstGhostPad's in between as necessary.
This is a convenience function to save having to create and add intermediate GstGhostPad's as required for linking across GstBin boundaries.
If src
or sink
pads don't have parent elements or do not share a common
ancestor, the link will fail.
Calling gst_pad_link_maybe_ghosting_full()
with
flags
== GST_PAD_LINK_CHECK_DEFAULT
is the recommended way of linking
pads with safety checks applied.
Since: 1.10
gst_pad_unlink ()
gboolean gst_pad_unlink (GstPad *srcpad
,GstPad *sinkpad
);
Unlinks the source pad from the sink pad. Will emit the “unlinked” signal on both pads.
gst_pad_is_linked ()
gboolean
gst_pad_is_linked (GstPad *pad
);
Checks if a pad
is linked to another pad or not.
gst_pad_can_link ()
gboolean gst_pad_can_link (GstPad *srcpad
,GstPad *sinkpad
);
Checks if the source pad and the sink pad are compatible so they can be linked.
gst_pad_get_allowed_caps ()
GstCaps *
gst_pad_get_allowed_caps (GstPad *pad
);
Gets the capabilities of the allowed media types that can flow through
pad
and its peer.
The allowed capabilities is calculated as the intersection of the results of
calling gst_pad_query_caps()
on pad
and its peer. The caller owns a reference
on the resulting caps.
gst_pad_get_current_caps ()
GstCaps *
gst_pad_get_current_caps (GstPad *pad
);
Gets the capabilities currently configured on pad
with the last
GST_EVENT_CAPS event.
Returns
the current caps of the pad with
incremented ref-count or NULL
when pad has no caps. Unref after usage.
[transfer full][nullable]
gst_pad_get_pad_template_caps ()
GstCaps *
gst_pad_get_pad_template_caps (GstPad *pad
);
Gets the capabilities for pad
's template.
gst_pad_get_peer ()
GstPad *
gst_pad_get_peer (GstPad *pad
);
Gets the peer of pad
. This function refs the peer pad so
you need to unref it after use.
gst_pad_use_fixed_caps ()
void
gst_pad_use_fixed_caps (GstPad *pad
);
A helper function you can use that sets the FIXED_CAPS flag This way the default CAPS query will always return the negotiated caps or in case the pad is not negotiated, the padtemplate caps.
The negotiated caps are the caps of the last CAPS event that passed on the pad. Use this function on a pad that, once it negotiated to a CAPS, cannot be renegotiated to something else.
gst_pad_has_current_caps ()
gboolean
gst_pad_has_current_caps (GstPad *pad
);
Check if pad
has caps set on it with a GST_EVENT_CAPS event.
gst_pad_get_sticky_event ()
GstEvent * gst_pad_get_sticky_event (GstPad *pad
,GstEventType event_type
,guint idx
);
Returns a new reference of the sticky event of type event_type
from the event.
Parameters
pad |
the GstPad to get the event from. |
|
event_type |
the GstEventType that should be retrieved. |
|
idx |
the index of the event |
GstPadStickyEventsForeachFunction ()
gboolean (*GstPadStickyEventsForeachFunction) (GstPad *pad
,GstEvent **event
,gpointer user_data
);
Callback used by gst_pad_sticky_events_foreach()
.
When this function returns TRUE
, the next event will be
returned. When FALSE
is returned, gst_pad_sticky_events_foreach()
will return.
When event
is set to NULL
, the item will be removed from the list of sticky events.
event
can be replaced by assigning a new reference to it.
This function is responsible for unreffing the old event when
removing or modifying.
gst_pad_sticky_events_foreach ()
void gst_pad_sticky_events_foreach (GstPad *pad
,GstPadStickyEventsForeachFunction foreach_func
,gpointer user_data
);
Iterates all sticky events on pad
and calls foreach_func
for every
event. If foreach_func
returns FALSE
the iteration is immediately stopped.
Parameters
pad |
the GstPad that should be used for iteration. |
|
foreach_func |
the GstPadStickyEventsForeachFunction that should be called for every event. |
[scope call] |
user_data |
the optional user data. |
[closure] |
gst_pad_get_last_flow_return ()
GstFlowReturn
gst_pad_get_last_flow_return (GstPad *pad
);
Gets the GstFlowReturn return from the last data passed by this pad.
Since: 1.4
GST_PAD_PROBE_INFO_BUFFER()
#define GST_PAD_PROBE_INFO_BUFFER(d) GST_BUFFER_CAST(GST_PAD_PROBE_INFO_DATA(d))
GST_PAD_PROBE_INFO_BUFFER_LIST()
#define GST_PAD_PROBE_INFO_BUFFER_LIST(d) GST_BUFFER_LIST_CAST(GST_PAD_PROBE_INFO_DATA(d))
GST_PAD_PROBE_INFO_EVENT()
#define GST_PAD_PROBE_INFO_EVENT(d) GST_EVENT_CAST(GST_PAD_PROBE_INFO_DATA(d))
GST_PAD_PROBE_INFO_QUERY()
#define GST_PAD_PROBE_INFO_QUERY(d) GST_QUERY_CAST(GST_PAD_PROBE_INFO_DATA(d))
gst_pad_probe_info_get_buffer_list ()
GstBufferList *
gst_pad_probe_info_get_buffer_list (GstPadProbeInfo *info
);
GstPadProbeCallback ()
GstPadProbeReturn (*GstPadProbeCallback) (GstPad *pad
,GstPadProbeInfo *info
,gpointer user_data
);
Callback used by gst_pad_add_probe()
. Gets called to notify about the current
blocking type.
The callback is allowed to modify the data pointer in info
.
gst_pad_add_probe ()
gulong gst_pad_add_probe (GstPad *pad
,GstPadProbeType mask
,GstPadProbeCallback callback
,gpointer user_data
,GDestroyNotify destroy_data
);
Be notified of different states of pads. The provided callback is called for
every state that matches mask
.
Probes are called in groups: First GST_PAD_PROBE_TYPE_BLOCK probes are
called, then others, then finally GST_PAD_PROBE_TYPE_IDLE. The only
exception here are GST_PAD_PROBE_TYPE_IDLE probes that are called
immediately if the pad is already idle while calling gst_pad_add_probe()
.
In each of the groups, probes are called in the order in which they were
added.
Parameters
pad |
the GstPad to add the probe to |
|
mask |
the probe mask |
|
callback |
GstPadProbeCallback that will be called with notifications of the pad state |
|
user_data |
user data passed to the callback. |
[closure] |
destroy_data |
GDestroyNotify for user_data |
Returns
an id or 0 if no probe is pending. The id can be used to remove the
probe with gst_pad_remove_probe()
. When using GST_PAD_PROBE_TYPE_IDLE it can
happen that the probe can be run immediately and if the probe returns
GST_PAD_PROBE_REMOVE this functions returns 0.
MT safe.
gst_pad_remove_probe ()
void gst_pad_remove_probe (GstPad *pad
,gulong id
);
Remove the probe with id
from pad
.
MT safe.
gst_pad_is_blocked ()
gboolean
gst_pad_is_blocked (GstPad *pad
);
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 gst_pad_is_blocking()
).
gst_pad_is_blocking ()
gboolean
gst_pad_is_blocking (GstPad *pad
);
Checks if the pad is blocking or not. This is a guaranteed state of whether the pad is actually blocking on a GstBuffer or a GstEvent.
gst_pad_get_offset ()
gint64
gst_pad_get_offset (GstPad *pad
);
Get the offset applied to the running time of pad
. pad
has to be a source
pad.
gst_pad_set_offset ()
void gst_pad_set_offset (GstPad *pad
,gint64 offset
);
Set the offset that will be applied to the running time of pad
.
gst_pad_new ()
GstPad * gst_pad_new (const gchar *name
,GstPadDirection 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.
This function makes a copy of the name so you can safely free the name.
gst_pad_new_from_template ()
GstPad * gst_pad_new_from_template (GstPadTemplate *templ
,const gchar *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.
This function makes a copy of the name so you can safely free the name.
gst_pad_new_from_static_template ()
GstPad * gst_pad_new_from_static_template (GstStaticPadTemplate *templ
,const gchar *name
);
Creates a new pad with the given name from the given static template.
If name is NULL
, a guaranteed unique name (across all pads)
will be assigned.
This function makes a copy of the name so you can safely free the name.
gst_pad_set_chain_function()
#define gst_pad_set_chain_function(p,f) gst_pad_set_chain_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_chain_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_chain_function_full ()
void gst_pad_set_chain_function_full (GstPad *pad
,GstPadChainFunction chain
,gpointer user_data
,GDestroyNotify notify
);
Sets the given chain function for the pad. The chain function is called to process a GstBuffer input buffer. see GstPadChainFunction for more details.
Parameters
pad |
a sink GstPad. |
|
chain |
the GstPadChainFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadChainFunction ()
GstFlowReturn (*GstPadChainFunction) (GstPad *pad
,GstObject *parent
,GstBuffer *buffer
);
A function that will be called on sinkpads when chaining buffers. The function typically processes the data contained in the buffer and either consumes the data or passes it on to the internally linked pad(s).
The implementer of this function receives a refcount to buffer
and should
gst_buffer_unref()
when the buffer is no longer needed.
When a chain function detects an error in the data stream, it must post an error on the bus and return an appropriate GstFlowReturn value.
Parameters
pad |
the sink GstPad that performed the chain. |
|
parent |
the parent of |
[allow-none] |
buffer |
[transfer full] |
gst_pad_set_chain_list_function()
#define gst_pad_set_chain_list_function(p,f) gst_pad_set_chain_list_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_chain_list_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_chain_list_function_full ()
void gst_pad_set_chain_list_function_full (GstPad *pad
,GstPadChainListFunction chainlist
,gpointer user_data
,GDestroyNotify notify
);
Sets the given chain list function for the pad. The chainlist function is called to process a GstBufferList input buffer list. See GstPadChainListFunction for more details.
Parameters
pad |
a sink GstPad. |
|
chainlist |
the GstPadChainListFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadChainListFunction ()
GstFlowReturn (*GstPadChainListFunction) (GstPad *pad
,GstObject *parent
,GstBufferList *list
);
A function that will be called on sinkpads when chaining buffer lists. The function typically processes the data contained in the buffer list and either consumes the data or passes it on to the internally linked pad(s).
The implementer of this function receives a refcount to list
and
should gst_buffer_list_unref()
when the list is no longer needed.
When a chainlist function detects an error in the data stream, it must post an error on the bus and return an appropriate GstFlowReturn value.
Parameters
pad |
the sink GstPad that performed the chain. |
|
parent |
the parent of |
[allow-none] |
list |
the GstBufferList that is chained, not |
[transfer full] |
gst_pad_get_range ()
GstFlowReturn gst_pad_get_range (GstPad *pad
,guint64 offset
,guint size
,GstBuffer **buffer
);
When pad
is flushing this function returns GST_FLOW_FLUSHING
immediately and buffer
is NULL
.
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
GST_FLOW_NOT_SUPPORTED.
If buffer
points to a variable holding NULL
, a valid new GstBuffer will be
placed in buffer
when this function returns GST_FLOW_OK. The new buffer
must be freed with gst_buffer_unref()
after usage.
When buffer
points to a variable that points to a valid GstBuffer, the
buffer will be filled with the result data when this function returns
GST_FLOW_OK. If the provided buffer is larger than size
, only
size
bytes will be filled in the result buffer and its size will be updated
accordingly.
Note that less than size
bytes can be returned in buffer
when, for example,
an EOS condition is near or when buffer
is not large enough to hold size
bytes. The caller should check the result buffer size to get the result size.
When this function returns any other result value than GST_FLOW_OK, buffer
will be unchanged.
This is a lowlevel function. Usually gst_pad_pull_range()
is used.
Parameters
pad |
a src GstPad, returns GST_FLOW_ERROR if not. |
|
offset |
The start offset of the buffer |
|
size |
The length of the buffer |
|
buffer |
a pointer to hold the GstBuffer,
returns GST_FLOW_ERROR if |
[out callee-allocates] |
gst_pad_set_getrange_function()
#define gst_pad_set_getrange_function(p,f) gst_pad_set_getrange_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_getrange_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_getrange_function_full ()
void gst_pad_set_getrange_function_full (GstPad *pad
,GstPadGetRangeFunction get
,gpointer user_data
,GDestroyNotify notify
);
Sets the given getrange function for the pad. The getrange function is called to produce a new GstBuffer to start the processing pipeline. see GstPadGetRangeFunction for a description of the getrange function.
Parameters
pad |
a source GstPad. |
|
get |
the GstPadGetRangeFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadGetRangeFunction ()
GstFlowReturn (*GstPadGetRangeFunction) (GstPad *pad
,GstObject *parent
,guint64 offset
,guint length
,GstBuffer **buffer
);
This function will be called on source pads when a peer element
request a buffer at the specified offset
and length
. If this function
returns GST_FLOW_OK, the result buffer will be stored in buffer
. The
contents of buffer
is invalid for any other return value.
This function is installed on a source pad with
gst_pad_set_getrange_function()
and can only be called on source pads after
they are successfully activated with gst_pad_activate_mode()
with the
GST_PAD_MODE_PULL.
offset
and length
are always given in byte units. offset
must normally be a value
between 0 and the length in bytes of the data available on pad
. The
length (duration in bytes) can be retrieved with a GST_QUERY_DURATION or with a
GST_QUERY_SEEKING.
Any offset
larger or equal than the length will make the function return
GST_FLOW_EOS, which corresponds to EOS. In this case buffer
does not
contain a valid buffer.
The buffer size of buffer
will only be smaller than length
when offset
is
near the end of the stream. In all other cases, the size of buffer
must be
exactly the requested size.
It is allowed to call this function with a 0 length
and valid offset
, in
which case buffer
will contain a 0-sized buffer and the function returns
GST_FLOW_OK.
When this function is called with a -1 offset
, the sequentially next buffer
of length length
in the stream is returned.
When this function is called with a -1 length
, a buffer with a default
optimal length is returned in buffer
. The length might depend on the value
of offset
.
Parameters
pad |
the src GstPad to perform the getrange on. |
|
parent |
the parent of |
[allow-none] |
offset |
the offset of the range |
|
length |
the length of the range |
|
buffer |
a memory location to hold the result buffer, cannot be |
Returns
GST_FLOW_OK for success and a valid buffer in buffer
. Any other
return value leaves buffer
undefined.
gst_pad_set_event_function()
#define gst_pad_set_event_function(p,f) gst_pad_set_event_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_event_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_event_function_full ()
void gst_pad_set_event_function_full (GstPad *pad
,GstPadEventFunction event
,gpointer user_data
,GDestroyNotify notify
);
Sets the given event handler for the pad.
Parameters
pad |
a GstPad of either direction. |
|
event |
the GstPadEventFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadEventFunction ()
gboolean (*GstPadEventFunction) (GstPad *pad
,GstObject *parent
,GstEvent *event
);
Function signature to handle an event for the pad.
Parameters
pad |
the GstPad to handle the event. |
|
parent |
the parent of |
[allow-none] |
event |
the GstEvent to handle. |
[transfer full] |
gst_pad_set_event_full_function()
#define gst_pad_set_event_full_function(p,f) gst_pad_set_event_full_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_event_full_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_event_full_function_full ()
void gst_pad_set_event_full_function_full (GstPad *pad
,GstPadEventFullFunction event
,gpointer user_data
,GDestroyNotify notify
);
Sets the given event handler for the pad.
Parameters
pad |
a GstPad of either direction. |
|
event |
the GstPadEventFullFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
Since: 1.8
GstPadEventFullFunction ()
GstFlowReturn (*GstPadEventFullFunction) (GstPad *pad
,GstObject *parent
,GstEvent *event
);
Function signature to handle an event for the pad.
This variant is for specific elements that will take into account the last downstream flow return (from a pad push), in which case they can return it.
Parameters
pad |
the GstPad to handle the event. |
|
parent |
the parent of |
[allow-none] |
event |
the GstEvent to handle. |
[transfer full] |
Returns
GST_FLOW_OK
if the event was handled properly, or any other
GstFlowReturn dependent on downstream state.
Since: 1.8
gst_pad_set_link_function()
#define gst_pad_set_link_function(p,f) gst_pad_set_link_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_link_function_full()
with NULL
for the user_data and notify.
gst_pad_set_link_function_full ()
void gst_pad_set_link_function_full (GstPad *pad
,GstPadLinkFunction link
,gpointer user_data
,GDestroyNotify notify
);
Sets the given link function for the pad. It will be called when the pad is linked with another pad.
The return value GST_PAD_LINK_OK should be used when the connection can be made.
The return value GST_PAD_LINK_REFUSED should be used when the connection cannot be made for some reason.
If link
is installed on a source pad, it should call the GstPadLinkFunction
of the peer sink pad, if present.
Parameters
pad |
a GstPad. |
|
link |
the GstPadLinkFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadLinkFunction ()
GstPadLinkReturn (*GstPadLinkFunction) (GstPad *pad
,GstObject *parent
,GstPad *peer
);
Function signature to handle a new link on the pad.
Parameters
pad |
the GstPad that is linked. |
|
parent |
the parent of |
[allow-none] |
peer |
the peer GstPad of the link |
gst_pad_set_unlink_function()
#define gst_pad_set_unlink_function(p,f) gst_pad_set_unlink_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_unlink_function_full()
with NULL
for the user_data and notify.
gst_pad_set_unlink_function_full ()
void gst_pad_set_unlink_function_full (GstPad *pad
,GstPadUnlinkFunction unlink
,gpointer user_data
,GDestroyNotify notify
);
Sets the given unlink function for the pad. It will be called when the pad is unlinked.
Parameters
pad |
a GstPad. |
|
unlink |
the GstPadUnlinkFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadUnlinkFunction ()
void (*GstPadUnlinkFunction) (GstPad *pad
,GstObject *parent
);
Function signature to handle a unlinking the pad prom its peer.
Parameters
pad |
the GstPad that is linked. |
|
parent |
the parent of |
[allow-none] |
gst_pad_proxy_query_caps ()
gboolean gst_pad_proxy_query_caps (GstPad *pad
,GstQuery *query
);
Calls gst_pad_query_caps()
for all internally linked pads of pad
and returns
the intersection of the results.
This function is useful as a default caps query function for an element that can handle any stream format, but requires all its pads to have the same caps. Two such elements are tee and adder.
gst_pad_proxy_query_accept_caps ()
gboolean gst_pad_proxy_query_accept_caps (GstPad *pad
,GstQuery *query
);
Checks if all internally linked pads of pad
accepts the caps in query
and
returns the intersection of the results.
This function is useful as a default accept caps query function for an element that can handle any stream format, but requires caps that are acceptable for all opposite pads.
gst_pad_set_activate_function()
#define gst_pad_set_activate_function(p,f) gst_pad_set_activate_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_activate_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_activate_function_full ()
void gst_pad_set_activate_function_full (GstPad *pad
,GstPadActivateFunction activate
,gpointer user_data
,GDestroyNotify notify
);
Sets the given activate function for pad
. The activate function will
dispatch to gst_pad_activate_mode()
to perform the actual activation.
Only makes sense to set on sink pads.
Call this function if your sink pad can start a pull-based task.
Parameters
pad |
a GstPad. |
|
activate |
the GstPadActivateFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadActivateFunction ()
gboolean (*GstPadActivateFunction) (GstPad *pad
,GstObject *parent
);
This function is called when the pad is activated during the element READY to PAUSED state change. By default this function will call the activate function that puts the pad in push mode but elements can override this function to activate the pad in pull mode if they wish.
gst_pad_set_activatemode_function()
#define gst_pad_set_activatemode_function(p,f) gst_pad_set_activatemode_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_activatemode_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_activatemode_function_full ()
void gst_pad_set_activatemode_function_full (GstPad *pad
,GstPadActivateModeFunction activatemode
,gpointer user_data
,GDestroyNotify notify
);
Sets the given activate_mode function for the pad. An activate_mode function prepares the element for data passing.
Parameters
pad |
a GstPad. |
|
activatemode |
the GstPadActivateModeFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadActivateModeFunction ()
gboolean (*GstPadActivateModeFunction) (GstPad *pad
,GstObject *parent
,GstPadMode mode
,gboolean active
);
The prototype of the push and pull activate functions.
Parameters
pad |
a GstPad |
|
parent |
the parent of |
|
mode |
the requested activation mode of |
|
active |
activate or deactivate the pad. |
gst_pad_needs_reconfigure ()
gboolean
gst_pad_needs_reconfigure (GstPad *pad
);
Check the GST_PAD_FLAG_NEED_RECONFIGURE flag on pad
and return TRUE
if the flag was set.
gst_pad_check_reconfigure ()
gboolean
gst_pad_check_reconfigure (GstPad *pad
);
Check and clear the GST_PAD_FLAG_NEED_RECONFIGURE flag on pad
and return TRUE
if the flag was set.
gst_pad_mark_reconfigure ()
void
gst_pad_mark_reconfigure (GstPad *pad
);
Mark a pad for needing reconfiguration. The next call to
gst_pad_check_reconfigure()
will return TRUE
after this call.
gst_pad_push ()
GstFlowReturn gst_pad_push (GstPad *pad
,GstBuffer *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, GST_FLOW_NOT_LINKED will
be returned.
In all cases, success or failure, the caller loses its reference to buffer
after calling this function.
Parameters
pad |
a source GstPad, returns GST_FLOW_ERROR if not. |
|
buffer |
the GstBuffer to push returns GST_FLOW_ERROR if not. |
[transfer full] |
gst_pad_push_event ()
gboolean gst_pad_push_event (GstPad *pad
,GstEvent *event
);
Sends the event to the peer of the given pad. This function is mainly used by elements to send events to their peer elements.
This function takes ownership of the provided event so you should
gst_event_ref()
it if you want to reuse the event after this call.
gst_pad_push_list ()
GstFlowReturn gst_pad_push_list (GstPad *pad
,GstBufferList *list
);
Pushes a buffer list to the peer of pad
.
This function will call installed block probes before triggering any installed data probes.
The function proceeds calling the chain function on the peer pad and returns
the value from that function. If pad
has no peer, GST_FLOW_NOT_LINKED will
be returned. If the peer pad does not have any installed chainlist function
every group buffer of the list will be merged into a normal GstBuffer and
chained via gst_pad_chain()
.
In all cases, success or failure, the caller loses its reference to list
after calling this function.
Parameters
pad |
a source GstPad, returns GST_FLOW_ERROR if not. |
|
list |
the GstBufferList to push returns GST_FLOW_ERROR if not. |
[transfer full] |
gst_pad_pull_range ()
GstFlowReturn gst_pad_pull_range (GstPad *pad
,guint64 offset
,guint size
,GstBuffer **buffer
);
Pulls a buffer
from the peer pad or fills up a provided buffer.
This function will first trigger the pad block signal if it was installed.
When pad
is not linked GST_FLOW_NOT_LINKED is returned else this
function returns the result of gst_pad_get_range()
on the peer pad.
See gst_pad_get_range()
for a list of return values and for the
semantics of the arguments of this function.
If buffer
points to a variable holding NULL
, a valid new GstBuffer will be
placed in buffer
when this function returns GST_FLOW_OK. The new buffer
must be freed with gst_buffer_unref()
after usage. When this function
returns any other result value, buffer
will still point to NULL
.
When buffer
points to a variable that points to a valid GstBuffer, the
buffer will be filled with the result data when this function returns
GST_FLOW_OK. When this function returns any other result value,
buffer
will be unchanged. If the provided buffer is larger than size
, only
size
bytes will be filled in the result buffer and its size will be updated
accordingly.
Note that less than size
bytes can be returned in buffer
when, for example,
an EOS condition is near or when buffer
is not large enough to hold size
bytes. The caller should check the result buffer size to get the result size.
gst_pad_activate_mode ()
gboolean gst_pad_activate_mode (GstPad *pad
,GstPadMode mode
,gboolean active
);
Activates or deactivates the given pad in mode
via dispatching to the
pad's activatemodefunc. For use from within pad activation functions only.
If you don't know what this is, you probably don't want to call it.
Parameters
pad |
the GstPad to activate or deactivate. |
|
mode |
the requested activation mode |
|
active |
whether or not the pad should be active. |
gst_pad_send_event ()
gboolean gst_pad_send_event (GstPad *pad
,GstEvent *event
);
Sends the event to the pad. This function can be used by applications to send events in the pipeline.
If pad
is a source pad, event
should be an upstream event. If pad
is a
sink pad, event
should be a downstream event. For example, you would not
send a GST_EVENT_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 GST_EVENT_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.
To find out whether an event type is upstream, downstream, or downstream and
serialized, see GstEventTypeFlags, gst_event_type_get_flags()
,
GST_EVENT_IS_UPSTREAM, GST_EVENT_IS_DOWNSTREAM, and
GST_EVENT_IS_SERIALIZED. Note that in practice that an application or
plugin doesn't need to bother itself with this information; the core handles
all necessary locks and checks.
This function takes ownership of the provided event so you should
gst_event_ref()
it if you want to reuse the event after this call.
gst_pad_event_default ()
gboolean gst_pad_event_default (GstPad *pad
,GstObject *parent
,GstEvent *event
);
Invokes the default event handler for the given pad.
The EOS event will pause the task associated with pad
before it is forwarded
to all internally linked pads,
The event is sent to all pads internally linked to pad
. This function
takes ownership of event
.
gst_pad_query ()
gboolean gst_pad_query (GstPad *pad
,GstQuery *query
);
Dispatches a query to a pad. The query should have been allocated by the caller via one of the type-specific allocation functions. The element that the pad belongs to is responsible for filling the query with an appropriate response, which should then be parsed with a type-specific query parsing function.
Again, the caller is responsible for both the allocation and deallocation of the query structure.
Please also note that some queries might need a running pipeline to work.
gst_pad_peer_query ()
gboolean gst_pad_peer_query (GstPad *pad
,GstQuery *query
);
Performs gst_pad_query()
on the peer of pad
.
The caller is responsible for both the allocation and deallocation of the query structure.
gst_pad_query_default ()
gboolean gst_pad_query_default (GstPad *pad
,GstObject *parent
,GstQuery *query
);
Invokes the default query handler for the given pad.
The query is sent to all pads internally linked to pad
. Note that
if there are many possible sink pads that are internally linked to
pad
, only one will be sent the query.
Multi-sinkpad elements should implement custom query handlers.
gst_pad_query_position ()
gboolean gst_pad_query_position (GstPad *pad
,GstFormat format
,gint64 *cur
);
Queries a pad for the stream position.
gst_pad_query_duration ()
gboolean gst_pad_query_duration (GstPad *pad
,GstFormat format
,gint64 *duration
);
Queries a pad for the total stream duration.
gst_pad_query_convert ()
gboolean gst_pad_query_convert (GstPad *pad
,GstFormat src_format
,gint64 src_val
,GstFormat dest_format
,gint64 *dest_val
);
Queries a pad to convert src_val
in src_format
to dest_format
.
gst_pad_query_accept_caps ()
gboolean gst_pad_query_accept_caps (GstPad *pad
,GstCaps *caps
);
Check if the given pad accepts the caps.
gst_pad_query_caps ()
GstCaps * gst_pad_query_caps (GstPad *pad
,GstCaps *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 gst_pad_get_current_caps()
for that instead.
gst_pad_query_caps 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 GstCaps, use
gst_caps_make_writable()
before modifying the caps.
gst_pad_peer_query_position ()
gboolean gst_pad_peer_query_position (GstPad *pad
,GstFormat format
,gint64 *cur
);
Queries the peer of a given sink pad for the stream position.
gst_pad_peer_query_duration ()
gboolean gst_pad_peer_query_duration (GstPad *pad
,GstFormat format
,gint64 *duration
);
Queries the peer pad of a given sink pad for the total stream duration.
gst_pad_peer_query_convert ()
gboolean gst_pad_peer_query_convert (GstPad *pad
,GstFormat src_format
,gint64 src_val
,GstFormat dest_format
,gint64 *dest_val
);
Queries the peer pad of a given sink pad to convert src_val
in src_format
to dest_format
.
gst_pad_peer_query_accept_caps ()
gboolean gst_pad_peer_query_accept_caps (GstPad *pad
,GstCaps *caps
);
Check if the peer of pad
accepts caps
. If pad
has no peer, this function
returns TRUE
.
gst_pad_peer_query_caps ()
GstCaps * gst_pad_peer_query_caps (GstPad *pad
,GstCaps *filter
);
Gets the capabilities of the peer connected to this pad. Similar to
gst_pad_query_caps()
.
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
.
Returns
the caps of the peer pad with incremented
ref-count. When there is no peer pad, this function returns filter
or,
when filter
is NULL
, ANY caps.
[transfer full]
gst_pad_set_query_function()
#define gst_pad_set_query_function(p,f) gst_pad_set_query_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_query_function_full()
with NULL
for the user_data and
notify.
gst_pad_set_query_function_full ()
void gst_pad_set_query_function_full (GstPad *pad
,GstPadQueryFunction query
,gpointer user_data
,GDestroyNotify notify
);
Set the given query function for the pad.
Parameters
pad |
a GstPad of either direction. |
|
query |
the GstPadQueryFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadQueryFunction ()
gboolean (*GstPadQueryFunction) (GstPad *pad
,GstObject *parent
,GstQuery *query
);
The signature of the query function.
Parameters
pad |
the GstPad to query. |
|
parent |
the parent of |
[allow-none] |
query |
the GstQuery object to execute |
gst_pad_set_iterate_internal_links_function()
#define gst_pad_set_iterate_internal_links_function(p,f) gst_pad_set_iterate_internal_links_function_full((p),(f),NULL,NULL)
Calls gst_pad_set_iterate_internal_links_function_full()
with NULL
for the user_data and notify.
gst_pad_set_iterate_internal_links_function_full ()
void gst_pad_set_iterate_internal_links_function_full (GstPad *pad
,GstPadIterIntLinkFunction iterintlink
,gpointer user_data
,GDestroyNotify notify
);
Sets the given internal link iterator function for the pad.
Parameters
pad |
a GstPad of either direction. |
|
iterintlink |
the GstPadIterIntLinkFunction to set. |
|
user_data |
user_data passed to |
|
notify |
notify called when |
GstPadIterIntLinkFunction ()
GstIterator * (*GstPadIterIntLinkFunction) (GstPad *pad
,GstObject *parent
);
The signature of the internal pad link iterator function.
Parameters
pad |
The GstPad to query. |
|
parent |
the parent of |
[allow-none] |
Returns
a new GstIterator that will iterate over all pads that are linked to the given pad on the inside of the parent element.
the caller must call gst_iterator_free()
after usage.
gst_pad_iterate_internal_links ()
GstIterator *
gst_pad_iterate_internal_links (GstPad *pad
);
Gets an iterator for the pads to which the given pad is linked to inside of the parent element.
Each GstPad element yielded by the iterator will have its refcount increased, so unref after use.
Free-function: gst_iterator_free
Returns
a new GstIterator of GstPad
or NULL
when the pad does not have an iterator function
configured. Use gst_iterator_free()
after usage.
[transfer full][nullable]
gst_pad_iterate_internal_links_default ()
GstIterator * gst_pad_iterate_internal_links_default (GstPad *pad
,GstObject *parent
);
Iterate the list of pads to which the given pad is linked to inside of the parent element. This is the default handler, and thus returns an iterator of all of the pads inside the parent element with opposite direction.
The caller must free this iterator after use with gst_iterator_free()
.
Returns
a GstIterator of GstPad, or NULL
if pad
has no parent. Unref each returned pad with gst_object_unref()
.
[nullable]
gst_pad_set_element_private ()
void gst_pad_set_element_private (GstPad *pad
,gpointer priv
);
Set the given private data gpointer on the pad. This function can only be used by the element that owns the pad. No locking is performed in this function.
gst_pad_get_element_private ()
gpointer
gst_pad_get_element_private (GstPad *pad
);
Gets the private data of a pad. No locking is performed in this function.
gst_pad_create_stream_id ()
gchar * gst_pad_create_stream_id (GstPad *pad
,GstElement *parent
,const gchar *stream_id
);
Creates a stream-id for the source GstPad pad
by combining the
upstream information with the optional stream_id
of the stream
of pad
. pad
must have a parent GstElement and which must have zero
or one sinkpad. stream_id
can only be NULL
if the parent element
of pad
has only a single source pad.
This function generates an unique stream-id by getting the upstream
stream-start event stream ID and appending stream_id
to it. If the
element has no sinkpad it will generate an upstream stream-id by
doing an URI query on the element and in the worst case just uses
a random number. Source elements that don't implement the URI
handler interface should ideally generate a unique, deterministic
stream-id manually instead.
Since stream IDs are sorted alphabetically, any numbers in the stream ID should be printed with a fixed number of characters, preceded by 0's, such as by using the format %03u instead of %u.
Parameters
pad |
A source GstPad |
|
parent |
Parent GstElement of |
|
stream_id |
The stream-id. |
[allow-none] |
gst_pad_create_stream_id_printf ()
gchar * gst_pad_create_stream_id_printf (GstPad *pad
,GstElement *parent
,const gchar *stream_id
,...
);
Creates a stream-id for the source GstPad pad
by combining the
upstream information with the optional stream_id
of the stream
of pad
. pad
must have a parent GstElement and which must have zero
or one sinkpad. stream_id
can only be NULL
if the parent element
of pad
has only a single source pad.
This function generates an unique stream-id by getting the upstream
stream-start event stream ID and appending stream_id
to it. If the
element has no sinkpad it will generate an upstream stream-id by
doing an URI query on the element and in the worst case just uses
a random number. Source elements that don't implement the URI
handler interface should ideally generate a unique, deterministic
stream-id manually instead.
Parameters
pad |
A source GstPad |
|
parent |
Parent GstElement of |
|
stream_id |
The stream-id. |
[allow-none] |
... |
parameters for the |
gst_pad_create_stream_id_printf_valist ()
gchar * gst_pad_create_stream_id_printf_valist (GstPad *pad
,GstElement *parent
,const gchar *stream_id
,va_list var_args
);
Creates a stream-id for the source GstPad pad
by combining the
upstream information with the optional stream_id
of the stream
of pad
. pad
must have a parent GstElement and which must have zero
or one sinkpad. stream_id
can only be NULL
if the parent element
of pad
has only a single source pad.
This function generates an unique stream-id by getting the upstream
stream-start event stream ID and appending stream_id
to it. If the
element has no sinkpad it will generate an upstream stream-id by
doing an URI query on the element and in the worst case just uses
a random number. Source elements that don't implement the URI
handler interface should ideally generate a unique, deterministic
stream-id manually instead.
Parameters
pad |
A source GstPad |
|
parent |
Parent GstElement of |
|
stream_id |
The stream-id. |
[allow-none] |
var_args |
parameters for the |
gst_pad_get_stream_id ()
gchar *
gst_pad_get_stream_id (GstPad *pad
);
Returns the current stream-id for the pad
, or NULL
if none has been
set yet, i.e. the pad has not received a stream-start event yet.
This is a convenience wrapper around gst_pad_get_sticky_event()
and
gst_event_parse_stream_start()
.
The returned stream-id string should be treated as an opaque string, its contents should not be interpreted.
Returns
a newly-allocated copy of the stream-id for
pad
, or NULL
. g_free()
the returned string when no longer
needed.
[nullable]
Since: 1.2
gst_pad_get_stream ()
GstStream *
gst_pad_get_stream (GstPad *pad
);
Returns the current GstStream for the pad
, or NULL
if none has been
set yet, i.e. the pad has not received a stream-start event yet.
This is a convenience wrapper around gst_pad_get_sticky_event()
and
gst_event_parse_stream()
.
Returns
the current GstStream for pad
, or NULL
.
unref the returned stream when no longer needed.
[nullable][transfer full]
Since: 1.10
GstPadForwardFunction ()
gboolean (*GstPadForwardFunction) (GstPad *pad
,gpointer user_data
);
A forward function is called for all internally linked pads, see
gst_pad_forward()
.
gst_pad_forward ()
gboolean gst_pad_forward (GstPad *pad
,GstPadForwardFunction forward
,gpointer user_data
);
Calls forward
for all internally linked pads of pad
. This function deals with
dynamically changing internal pads and will make sure that the forward
function is only called once for each pad.
When forward
returns TRUE
, no further pads will be processed.
gst_pad_chain ()
GstFlowReturn gst_pad_chain (GstPad *pad
,GstBuffer *buffer
);
Chain a buffer to pad
.
The function returns GST_FLOW_FLUSHING if the pad was flushing.
If the buffer type is not acceptable for pad
(as negotiated with a
preceding GST_EVENT_CAPS event), this function returns
GST_FLOW_NOT_NEGOTIATED.
The function proceeds calling the chain function installed on pad
(see
gst_pad_set_chain_function()
) and the return value of that function is
returned to the caller. GST_FLOW_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.
gst_pad_chain_list ()
GstFlowReturn gst_pad_chain_list (GstPad *pad
,GstBufferList *list
);
Chain a bufferlist to pad
.
The function returns GST_FLOW_FLUSHING if the pad was flushing.
If pad
was not negotiated properly with a CAPS event, this function
returns GST_FLOW_NOT_NEGOTIATED.
The function proceeds calling the chainlist function installed on pad
(see
gst_pad_set_chain_list_function()
) and the return value of that function is
returned to the caller. GST_FLOW_NOT_SUPPORTED is returned if pad
has no
chainlist function.
In all cases, success or failure, the caller loses its reference to list
after calling this function.
MT safe.
Parameters
pad |
a sink GstPad, returns GST_FLOW_ERROR if not. |
|
list |
the GstBufferList to send, return GST_FLOW_ERROR if not. |
[transfer full] |
gst_pad_start_task ()
gboolean gst_pad_start_task (GstPad *pad
,GstTaskFunction func
,gpointer user_data
,GDestroyNotify notify
);
Starts a task that repeatedly calls func
with user_data
. This function
is mostly used in pad activation functions to start the dataflow.
The GST_PAD_STREAM_LOCK of pad
will automatically be acquired
before func
is called.
Parameters
pad |
the GstPad to start the task of |
|
func |
the task function to call |
|
user_data |
user data passed to the task function |
|
notify |
called when |
gst_pad_pause_task ()
gboolean
gst_pad_pause_task (GstPad *pad
);
Pause the task of pad
. This function will also wait until the
function executed by the task is finished if this function is not
called from the task function.
gst_pad_stop_task ()
gboolean
gst_pad_stop_task (GstPad *pad
);
Stop the task of pad
. This function will also make sure that the
function executed by the task will effectively stop if not called
from the GstTaskFunction.
This function will deadlock if called from the GstTaskFunction of
the task. Use gst_task_pause()
instead.
Regardless of whether the pad has a task, the stream lock is acquired and released so as to ensure that streaming through this pad has finished.
gst_pad_get_task_state ()
GstTaskState
gst_pad_get_task_state (GstPad *pad
);
Get pad
task state. If no task is currently
set, GST_TASK_STOPPED is returned.
Since: 1.12
gst_pad_set_active ()
gboolean gst_pad_set_active (GstPad *pad
,gboolean active
);
Activates or deactivates the given pad. Normally called from within core state change functions.
If active
, 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
, calls gst_pad_activate_mode()
with the pad's current mode
and a FALSE
argument.
Parameters
pad |
the GstPad to activate or deactivate. |
|
active |
whether or not the pad should be active. |
GST_PAD_GET_STREAM_LOCK()
#define GST_PAD_GET_STREAM_LOCK(pad) (&(GST_PAD_CAST(pad)->stream_rec_lock))
Get the stream lock of pad
. The stream lock is protecting the
resources used in the data processing functions of pad
. Accessor
macro, use GST_PAD_STREAM_LOCK()
and GST_PAD_STREAM_UNLOCK()
instead
to take/release the pad's stream lock.
GST_PAD_STREAM_LOCK()
#define GST_PAD_STREAM_LOCK(pad) g_rec_mutex_lock(GST_PAD_GET_STREAM_LOCK(pad))
Take the pad's stream lock. The stream lock is recursive and will be taken when buffers or serialized downstream events are pushed on a pad.
GST_PAD_STREAM_TRYLOCK()
#define GST_PAD_STREAM_TRYLOCK(pad) g_rec_mutex_trylock(GST_PAD_GET_STREAM_LOCK(pad))
Try to take the pad's stream lock, and return TRUE
if the lock could be
taken, and otherwise FALSE
.
GST_PAD_STREAM_UNLOCK()
#define GST_PAD_STREAM_UNLOCK(pad) g_rec_mutex_unlock(GST_PAD_GET_STREAM_LOCK(pad))
Release the pad's stream lock.
GST_PAD_NAME()
#define GST_PAD_NAME(pad) (GST_OBJECT_NAME(pad))
Get name of the given pad.
No locking is performed in this function, use gst_pad_get_name()
instead.
GST_PAD_PARENT()
#define GST_PAD_PARENT(pad) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(pad)))
Get the pad
parent.
No locking is performed in this function, use gst_pad_get_parent()
instead.
GST_PAD_ELEMENT_PRIVATE()
#define GST_PAD_ELEMENT_PRIVATE(pad) (GST_PAD_CAST(pad)->element_private)
Get the private data of pad
, which is usually some pad- or stream-specific
structure created by the element and set on the pad when creating it.
No locking is performed in this function.
GST_PAD_PAD_TEMPLATE()
#define GST_PAD_PAD_TEMPLATE(pad) (GST_PAD_CAST(pad)->padtemplate)
Get the pad
GstPadTemplate. It describes the possible media types
a pad
or an element factory can handle.
GST_PAD_DIRECTION()
#define GST_PAD_DIRECTION(pad) (GST_PAD_CAST(pad)->direction)
Get the GstPadDirection of the given pad
. Accessor macro, use
gst_pad_get_direction()
instead.
GST_PAD_LAST_FLOW_RETURN()
#define GST_PAD_LAST_FLOW_RETURN(pad) (GST_PAD_CAST(pad)->ABI.abi.last_flowret)
Gets the last flow return on this pad
Since: 1.4
GST_PAD_TASK()
#define GST_PAD_TASK(pad) (GST_PAD_CAST(pad)->task)
Get the GstTask of pad
. Accessor macro used by GStreamer. Use the
gst_pad_start_task()
, gst_pad_stop_task()
and gst_pad_pause_task()
functions instead.
GST_PAD_MODE()
#define GST_PAD_MODE(pad) (GST_PAD_CAST(pad)->mode)
Get the GstPadMode of pad, which will be GST_PAD_MODE_NONE if the pad has not been activated yet, and otherwise either GST_PAD_MODE_PUSH or GST_PAD_MODE_PULL depending on which mode the pad was activated in.
GST_PAD_ACTIVATEFUNC()
#define GST_PAD_ACTIVATEFUNC(pad) (GST_PAD_CAST(pad)->activatefunc)
Get the GstPadActivateFunction from pad
.
GST_PAD_ACTIVATEMODEFUNC()
#define GST_PAD_ACTIVATEMODEFUNC(pad) (GST_PAD_CAST(pad)->activatemodefunc)
Get the GstPadActivateModeFunction from the given pad
.
GST_PAD_CHAINFUNC()
#define GST_PAD_CHAINFUNC(pad) (GST_PAD_CAST(pad)->chainfunc)
Get the GstPadChainFunction from the given pad
.
GST_PAD_CHAINLISTFUNC()
#define GST_PAD_CHAINLISTFUNC(pad) (GST_PAD_CAST(pad)->chainlistfunc)
Get the GstPadChainListFunction from the given pad
.
GST_PAD_EVENTFUNC()
#define GST_PAD_EVENTFUNC(pad) (GST_PAD_CAST(pad)->eventfunc)
Get the GstPadEventFunction from the given pad
, which
is the function that handles events on the pad. You can
use this to set your own event handling function on a pad
after you create it. If your element derives from a base
class, use the base class's virtual functions instead.
GST_PAD_EVENTFULLFUNC()
#define GST_PAD_EVENTFULLFUNC(pad) (GST_PAD_CAST(pad)->ABI.abi.eventfullfunc)
Get the GstPadEventFullFunction from the given pad
, which
is the function that handles events on the pad. You can
use this to set your own event handling function on a pad
after you create it. If your element derives from a base
class, use the base class's virtual functions instead.
Since: 1.8
GST_PAD_GETRANGEFUNC()
#define GST_PAD_GETRANGEFUNC(pad) (GST_PAD_CAST(pad)->getrangefunc)
Get the GstPadGetRangeFunction from the given pad
.
GST_PAD_QUERYFUNC()
#define GST_PAD_QUERYFUNC(pad) (GST_PAD_CAST(pad)->queryfunc)
Get the GstPadQueryFunction from pad
, which is the function
that handles queries on the pad. You can use this to set your
own query handling function on a pad after you create it. If your
element derives from a base class, use the base class's virtual
functions instead.
GST_PAD_ITERINTLINKFUNC()
#define GST_PAD_ITERINTLINKFUNC(pad) (GST_PAD_CAST(pad)->iterintlinkfunc)
Get the GstPadIterIntLinkFunction from the given pad
.
GST_PAD_PEER()
#define GST_PAD_PEER(pad) (GST_PAD_CAST(pad)->peer)
Return the pad's peer member. This member is a pointer to the linked pad
.
No locking is performed in this function, use gst_pad_get_peer()
instead.
GST_PAD_LINKFUNC()
#define GST_PAD_LINKFUNC(pad) (GST_PAD_CAST(pad)->linkfunc)
Get the GstPadLinkFunction for the given pad
.
GST_PAD_UNLINKFUNC()
#define GST_PAD_UNLINKFUNC(pad) (GST_PAD_CAST(pad)->unlinkfunc)
Get the GstPadUnlinkFunction from the given pad
.
GST_PAD_IS_BLOCKED()
#define GST_PAD_IS_BLOCKED(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_BLOCKED))
Check if the dataflow on a pad
is blocked. Use gst_pad_is_blocked()
instead.
GST_PAD_IS_BLOCKING()
#define GST_PAD_IS_BLOCKING(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_BLOCKING))
Check if the pad
is currently blocking on a buffer or event. Use
gst_pad_is_blocking()
instead.
GST_PAD_IS_FLUSHING()
#define GST_PAD_IS_FLUSHING(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_FLUSHING))
Check if the given pad
is flushing.
GST_PAD_SET_FLUSHING()
#define GST_PAD_SET_FLUSHING(pad) (GST_OBJECT_FLAG_SET (pad, GST_PAD_FLAG_FLUSHING))
Set the given pad
to flushing state, which means it will not accept any
more events, queries or buffers, and return GST_FLOW_FLUSHING if any buffers
are pushed on it. This usually happens when the pad is shut down or when
a flushing seek happens. This is used inside GStreamer when flush start/stop
events pass through pads, or when an element state is changed and pads are
activated or deactivated.
GST_PAD_UNSET_FLUSHING()
#define GST_PAD_UNSET_FLUSHING(pad) (GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_FLUSHING))
Unset the flushing flag.
GST_PAD_IS_EOS()
#define GST_PAD_IS_EOS(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_EOS))
Check if the pad
is in EOS state.
GST_PAD_NEEDS_RECONFIGURE()
#define GST_PAD_NEEDS_RECONFIGURE(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_NEED_RECONFIGURE))
Check if the pad
should be reconfigured/renegotiated.
The flag has to be unset manually after reconfiguration happened.
Use gst_pad_needs_reconfigure()
or gst_pad_check_reconfigure()
instead.
GST_PAD_HAS_PENDING_EVENTS()
#define GST_PAD_HAS_PENDING_EVENTS(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_PENDING_EVENTS))
Check if the given pad
has pending events. This is used internally by
GStreamer.
GST_PAD_IS_FIXED_CAPS()
#define GST_PAD_IS_FIXED_CAPS(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_FIXED_CAPS))
Check if the given pad
is using fixed caps, which means that
once the caps are set on the pad
, the caps query function will
only return those caps. See gst_pad_use_fixed_caps()
.
GST_PAD_NEEDS_PARENT()
#define GST_PAD_NEEDS_PARENT(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_NEED_PARENT))
Check if there is a parent object before calling into the pad
callbacks.
This is used internally by GStreamer.
GST_PAD_IS_PROXY_CAPS()
#define GST_PAD_IS_PROXY_CAPS(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_PROXY_CAPS))
Check if the given pad
is set to proxy caps. This means that the default
event and query handler will forward all events and queries to the
internally linked pads
instead of discarding them.
GST_PAD_SET_PROXY_CAPS()
#define GST_PAD_SET_PROXY_CAPS(pad) (GST_OBJECT_FLAG_SET (pad, GST_PAD_FLAG_PROXY_CAPS))
Set pad
to proxy caps, so that all caps-related events and queries are
proxied down- or upstream to the other side of the element automatically.
Set this if the element always outputs data in the exact same format as it
receives as input. This is just for convenience to avoid implementing some
standard event and query handling code in an element.
GST_PAD_UNSET_PROXY_CAPS()
#define GST_PAD_UNSET_PROXY_CAPS(pad) (GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_PROXY_CAPS))
Unset proxy caps flag.
GST_PAD_IS_PROXY_ALLOCATION()
#define GST_PAD_IS_PROXY_ALLOCATION(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_PROXY_ALLOCATION))
Check if the given pad
is set as proxy allocation which means
that the default query handler will forward allocation queries to the
internally linked pads
instead of discarding them.
GST_PAD_SET_PROXY_ALLOCATION()
#define GST_PAD_SET_PROXY_ALLOCATION(pad) (GST_OBJECT_FLAG_SET (pad, GST_PAD_FLAG_PROXY_ALLOCATION))
Set pad
to proxy allocation queries, which means that the default query
handler will forward allocation queries to the internally linked pads
instead of discarding them.
Set this if the element always outputs data in the exact same format as it
receives as input. This is just for convenience to avoid implementing some
standard query handling code in an element.
GST_PAD_UNSET_PROXY_ALLOCATION()
#define GST_PAD_UNSET_PROXY_ALLOCATION(pad) (GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_PROXY_ALLOCATION))
Unset proxy allocation flag.
GST_PAD_SET_PROXY_SCHEDULING()
#define GST_PAD_SET_PROXY_SCHEDULING(pad) (GST_OBJECT_FLAG_SET (pad, GST_PAD_FLAG_PROXY_SCHEDULING))
Set pad
to proxy scheduling queries, which means that the default query
handler will forward scheduling queries to the internally linked pads
instead of discarding them. You will usually want to handle scheduling
queries explicitly if your element supports multiple scheduling modes.
GST_PAD_UNSET_PROXY_SCHEDULING()
#define GST_PAD_UNSET_PROXY_SCHEDULING(pad) (GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_PROXY_SCHEDULING))
Unset proxy scheduling flag.
GST_PAD_IS_PROXY_SCHEDULING()
#define GST_PAD_IS_PROXY_SCHEDULING(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_PROXY_SCHEDULING))
Check if the given pad
is set to proxy scheduling queries, which means that
the default query handler will forward scheduling queries to the internally
linked pads
instead of discarding them.
GST_PAD_IS_ACCEPT_INTERSECT()
#define GST_PAD_IS_ACCEPT_INTERSECT(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_ACCEPT_INTERSECT))
Check if the pad's accept intersect flag is set. The default accept-caps handler will check if the caps intersect the query-caps result instead of checking for a subset. This is interesting for parser elements that can accept incompletely specified caps.
GST_PAD_SET_ACCEPT_INTERSECT()
#define GST_PAD_SET_ACCEPT_INTERSECT(pad) (GST_OBJECT_FLAG_SET (pad, GST_PAD_FLAG_ACCEPT_INTERSECT))
Set pad
to by default accept caps by intersecting the result instead of
checking for a subset. This is interesting for parser elements that can
accept incompletely specified caps.
GST_PAD_UNSET_ACCEPT_INTERSECT()
#define GST_PAD_UNSET_ACCEPT_INTERSECT(pad) (GST_OBJECT_FLAG_UNSET (pad, GST_PAD_FLAG_ACCEPT_INTERSECT))
Unset accept intersect flag.
GST_PAD_IS_ACCEPT_TEMPLATE()
#define GST_PAD_IS_ACCEPT_TEMPLATE(pad) (GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLAG_ACCEPT_TEMPLATE))
Check if the pad's accept caps operation will use the pad template caps. The default accept-caps will do a query caps to get the caps, which might be querying downstream causing unnecessary overhead. It is recommended to implement a proper accept-caps query handler or to use this flag to prevent recursive accept-caps handling.
Since: 1.6
GST_PAD_SET_ACCEPT_TEMPLATE()
#define GST_PAD_SET_ACCEPT_TEMPLATE(pad) (GST_OBJECT_FLAG_SET (pad, GST_PAD_FLAG_ACCEPT_TEMPLATE))
Set pad
to by default use the pad template caps to compare with
the accept caps instead of using a caps query result.
Since: 1.6
Types and Values
struct GstPad
struct GstPad { gpointer element_private; GstPadTemplate *padtemplate; GstPadDirection direction; };
The GstPad structure. Use the functions to update the variables.
Members
gpointer |
private data owned by the parent element |
|
GstPadTemplate * |
padtemplate for this pad |
|
GstPadDirection |
the direction of the pad, cannot change after creating the pad. |
enum GstPadFlags
Pad state flags
Members
is dataflow on a pad blocked |
||
is pad flushing |
||
is pad in EOS state |
||
is pad currently blocking on a buffer or event |
||
ensure that there is a parent object before calling into the pad callbacks. |
||
the pad should be reconfigured/renegotiated. The flag has to be unset manually after reconfiguration happened. |
||
the pad has pending events |
||
the pad is using fixed caps. This means that once the caps are set on the pad, the default caps query function will only return those caps. |
||
the default event and query handler will forward all events and queries to the internally linked pads instead of discarding them. |
||
the default query handler will forward allocation queries to the internally linked pads instead of discarding them. |
||
the default query handler will forward scheduling queries to the internally linked pads instead of discarding them. |
||
the default accept-caps handler will check it the caps intersect the query-caps result instead of checking for a subset. This is interesting for parsers that can accept incompletely specified caps. |
||
the default accept-caps handler will use
the template pad caps instead of query caps to
compare with the accept caps. Use this in combination
with |
||
offset to define more flags |
enum GstPadLinkReturn
Result values from gst_pad_link and friends.
enum GstPadLinkCheck
The amount of checking to be done when linking pads. GST_PAD_LINK_CHECK_CAPS
and GST_PAD_LINK_CHECK_TEMPLATE_CAPS
are mutually exclusive. If both are
specified, expensive but safe GST_PAD_LINK_CHECK_CAPS
are performed.
Only disable some of the checks if you are 100% certain you know the link will not fail because of hierarchy/caps compatibility failures. If uncertain, use the default checks (
GST_PAD_LINK_CHECK_DEFAULT
) or the regular methods for linking the pads.
Members
Don't check hierarchy or caps compatibility. |
||
Check the pads have same parents/grandparents. Could be omitted if it is already known that the two elements that own the pads are in the same bin. |
||
Check if the pads are compatible by using
their template caps. This is much faster than |
||
Check if the pads are compatible by comparing the
caps returned by |
||
Disables pushing a reconfigure event when pads are linked. |
||
The default checks done when linking
pads (i.e. the ones used by |
enum GstFlowReturn
The result of passing data to a pad.
Note that the custom return values should not be exposed outside of the element scope.
Members
Pre-defined custom success code. |
||
Pre-defined custom success code (define your custom success code to this to avoid compiler warnings). |
||
Elements can use values starting from this (and higher) to define custom success codes. |
||
Data passing was ok. |
||
Pad is not linked. |
||
Pad is flushing. |
||
Pad is EOS. |
||
Pad is not negotiated. |
||
Some (fatal) error occurred. Element generating this error should post an error message with more details. |
||
This operation is not supported. |
||
Elements can use values starting from this (and lower) to define custom error codes. |
||
Pre-defined custom error code (define your custom error code to this to avoid compiler warnings). |
||
Pre-defined custom error code. |
enum GstPadMode
The status of a GstPad. After activating a pad, which usually happens when the parent element goes from READY to PAUSED, the GstPadMode defines if the pad operates in push or pull mode.
enum GstPadProbeReturn
Different return values for the GstPadProbeCallback.
Members
drop data in data probes. For push mode this means that
the data item is not sent downstream. For pull mode, it means that
the data item is not passed upstream. In both cases, no other probes
are called for this item and |
||
normal probe return value. This leaves the probe in place, and defers decisions about dropping or passing data to other probes, if any. If there are no other probes, the default behaviour for the probe type applies ('block' for blocking probes, and 'pass' for non-blocking probes). |
||
remove this probe. |
||
pass the data item in the block probe and block on the next item. |
||
Data has been handled in the probe and will not be
forwarded further. For events and buffers this is the same behaviour as
|
enum GstPadProbeType
The different probing types that can occur. When either one of
GST_PAD_PROBE_TYPE_IDLE
or GST_PAD_PROBE_TYPE_BLOCK
is used, the probe will be a
blocking probe.
Members
invalid probe type |
||
probe idle pads and block while the callback is called |
||
probe and block pads |
||
probe buffers |
||
probe buffer lists |
||
probe downstream events |
||
probe upstream events |
||
probe flush events. This probe has to be
explicitly enabled and is not included in the
@ |
||
probe downstream queries |
||
probe upstream queries |
||
probe push |
||
probe pull |
||
probe and block at the next opportunity, at data flow or when idle |
||
probe downstream data (buffers, buffer lists, and events) |
||
probe upstream data (events) |
||
probe upstream and downstream data (buffers, buffer lists, and events) |
||
probe and block downstream data (buffers, buffer lists, and events) |
||
probe and block upstream data (events) |
||
probe upstream and downstream events |
||
probe upstream and downstream queries |
||
probe upstream events and queries and downstream buffers, buffer lists, events and queries |
||
probe push and pull |
struct GstPadProbeInfo
struct GstPadProbeInfo { GstPadProbeType type; gulong id; gpointer data; guint64 offset; guint size; };
Info passed in the GstPadProbeCallback.
Members
GstPadProbeType |
the current probe type |
|
gulong |
the id of the probe |
|
gpointer |
type specific data, check the |
[allow-none] |
guint64 |
offset of pull probe, this field is valid when |
|
guint |
size of pull probe, this field is valid when |
Property Details
The “direction”
property
“direction” GstPadDirection
The direction of the pad.
Flags: Read / Write / Construct Only
Default value: GST_PAD_UNKNOWN
The “offset”
property
“offset” gint64
The offset that will be applied to the running time of the pad.
Flags: Read / Write
Allowed values: >= 0
Default value: 0
Since: 1.6
The “template”
property
“template” GstPadTemplate *
The GstPadTemplate of this pad.
Flags: Read / Write
Signal Details
The “linked”
signal
void user_function (GstPad *pad, GstPad *peer, gpointer user_data)
Signals that a pad has been linked to the peer pad.
Parameters
pad |
the pad that emitted the signal |
|
peer |
the peer pad that has been connected |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “unlinked”
signal
void user_function (GstPad *pad, GstPad *peer, gpointer user_data)
Signals that a pad has been unlinked from the peer pad.
Parameters
pad |
the pad that emitted the signal |
|
peer |
the peer pad that has been disconnected |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last