gstreamer/docs/gst/tmpl/gstpad.sgml

<!-- ##### SECTION Title ##### -->
GstPad

<!-- ##### SECTION Short_Description ##### -->
Object contained by elements that allows links to other elements

<!-- ##### SECTION Long_Description ##### -->
<para>
A #GstElement is linked to other elements via "pads", which are extremely 
light-weight generic link points. 
After two pads are retrieved from an element with gst_element_get_pad(), 
the pads can be link 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.)
</para>
<para>
Pads are typically created from a #GstPadTemplate with 
gst_pad_new_from_template().
</para>
<para>
Pads have #GstCaps attached to it to describe the media type they
are capable of dealing with. 
gst_pad_get_caps() and gst_pad_try_set_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.
</para>
<para>
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.
</para>
<para>
gst_pad_get_parent() will retrieve the #GstElement that owns the pad.
</para>
<para>
A #GstElement creating a pad will typically use the various 
gst_pad_set_*_function() calls to register callbacks for various events 
on the pads.
</para>
<para>
GstElements will use gst_pad_push() and gst_pad_pull() to push out 
or pull in a buffer. 
gst_pad_select() and gst_pad_selectv() are used by plugins to wait for the
first incoming buffer or event on any of the given set of pads.
</para>
<para>
To send a #GstEvent on a pad, use gst_pad_send_event().
</para>

<para>
Last reviewed on December 13th, 2002 (0.5.0.1)
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GstPadTemplate, #GstElement, #GstEvent
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GstPad ##### -->
<para>

</para>

@stream_rec_lock: 
@task: 
@preroll_lock: 
@preroll_cond: 
@block_cond: 
@block_callback: 
@block_data: 
@caps: 
@getcapsfunc: 
@setcapsfunc: 
@acceptcapsfunc: 
@fixatecapsfunc: 
@activatefunc: 
@activatepushfunc: 
@activatepullfunc: 
@linkfunc: 
@unlinkfunc: 
@peer: 
@sched_private: 
@chainfunc: 
@checkgetrangefunc: 
@getrangefunc: 
@eventfunc: 
@mode: 
@querytypefunc: 
@queryfunc: 
@intlinkfunc: 
@bufferallocfunc: 
@do_buffer_signals: 
@do_event_signals: 

<!-- ##### SIGNAL GstPad::have-data ##### -->
<para>

</para>

@gstpad: the object which received the signal.
@arg1: 
@Returns: 

<!-- ##### SIGNAL GstPad::linked ##### -->
<para>

</para>

@gstpad: the object which received the signal.
@arg1: 

<!-- ##### SIGNAL GstPad::request-link ##### -->
<para>

</para>

@gstpad: the object which received the signal.

<!-- ##### SIGNAL GstPad::unlinked ##### -->
<para>

</para>

@gstpad: the object which received the signal.
@arg1: 

<!-- ##### ARG GstPad:caps ##### -->
<para>

</para>

<!-- ##### ARG GstPad:direction ##### -->
<para>

</para>

<!-- ##### ARG GstPad:template ##### -->
<para>

</para>

<!-- ##### MACRO GST_PAD_LINK_FAILED ##### -->
<para>
Macro to test if the given #GstPadLinkReturn value indicates a
failed negotiation step (REFUSED/DELAYED).
</para>

@ret: the #GstPadLinkReturn value


<!-- ##### MACRO GST_PAD_LINK_SUCCESSFUL ##### -->
<para>
Macro to test if the given #GstPadLinkReturn value indicates a
successfull negotiation step (OK/DONE).
</para>

@ret: the #GstPadLinkReturn value


<!-- ##### USER_FUNCTION GstPadActivateFunction ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### USER_FUNCTION GstPadActivateModeFunction ##### -->
<para>

</para>

@pad: 
@active: 
@Returns: 


<!-- ##### USER_FUNCTION GstPadBlockCallback ##### -->
<para>

</para>

@pad: 
@blocked: 
@user_data: 


<!-- ##### USER_FUNCTION GstPadChainFunction ##### -->
<para>
A function that will be called when chaining buffers.
</para>

@pad: the #GstPad that performed the chain.
@buffer: 
@Returns: 
<!-- # Unused Parameters # -->
@data: 
@buf: the #GstBuffer that is chained.


<!-- ##### USER_FUNCTION GstPadEventFunction ##### -->
<para>
Function signature to handle an event for the pad.
</para>

@pad: the #GstPad to handle the event.
@event: the #GstEvent to handle.
@Returns: TRUE if the pad could handle the event.


<!-- ##### USER_FUNCTION GstPadCheckGetRangeFunction ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### USER_FUNCTION GstPadGetRangeFunction ##### -->
<para>

</para>

@pad: 
@offset: 
@length: 
@buffer: 
@Returns: 


<!-- ##### USER_FUNCTION GstPadQueryFunction ##### -->
<para>
The signature of the query function.
</para>

@pad: the #GstPad to query.
@query: 
@Returns: TRUE if the query could be performed.
<!-- # Unused Parameters # -->
@type: the #GstPadQueryType.
@format: a pointer to the target #GstFormat.
@value: a pointer to the target value.


<!-- ##### USER_FUNCTION GstPadIntLinkFunction ##### -->
<para>
The signature of the internal pad link function.
</para>

@pad: The #GstPad to query.
@Returns: a newly allocated #GList of pads that are linked to 
          the given pad on the inside of the parent element.  
          The caller must call g_list_free() on it after use.


<!-- ##### USER_FUNCTION GstPadQueryTypeFunction ##### -->
<para>
The signature of the query types function.
</para>

@pad: a #GstPad to query
@Returns: an array of query types


<!-- ##### USER_FUNCTION GstPadLinkFunction ##### -->
<para>
Function signature to handle a new link on the pad.
</para>

@pad: the #GstPad that is linked.
@peer: 
@Returns: the result of the link with the specified caps.
<!-- # Unused Parameters # -->
@caps: the peer's #GstCaps.


<!-- ##### USER_FUNCTION GstPadUnlinkFunction ##### -->
<para>

</para>

@pad: 


<!-- ##### USER_FUNCTION GstPadAcceptCapsFunction ##### -->
<para>

</para>

@pad: 
@caps: 
@Returns: 


<!-- ##### USER_FUNCTION GstPadFixateCapsFunction ##### -->
<para>

</para>

@pad: 
@caps: 


<!-- ##### USER_FUNCTION GstPadGetCapsFunction ##### -->
<para>
Returns a copy of the capabilities of the specified pad. By default this
function will return the pad template capabilities, but can optionally
be overridden.
</para>

@pad: the #GstPad to get the capabilities of.
@Returns: a newly allocated copy #GstCaps of the pad.
<!-- # Unused Parameters # -->
@caps: the peer's #GstCaps, can be used to filter the capabilities.


<!-- ##### USER_FUNCTION GstPadSetCapsFunction ##### -->
<para>

</para>

@pad: 
@caps: 
@Returns: 


<!-- ##### USER_FUNCTION GstPadBufferAllocFunction ##### -->
<para>

</para>

@pad: 
@offset: 
@size: 
@caps: 
@buf: 
@Returns: 


<!-- ##### USER_FUNCTION GstPadDispatcherFunction ##### -->
<para>
A dispatcher function is called for all internally linked pads, see 
gst_pad_dispatcher().
</para>

@pad: the #GstPad that is dispatched.
@data: the gpointer to optional user data.
@Returns: TRUE if the dispatching procedure has to be stopped.


<!-- ##### ENUM GstPadDirection ##### -->
<para>
The direction of a pad.
</para>

@GST_PAD_UNKNOWN: direction is unknown.
@GST_PAD_SRC: the pad is a source pad.
@GST_PAD_SINK: the pad is a sink pad.

<!-- ##### ENUM GstPadFlags ##### -->
<para>

</para>

@GST_PAD_BLOCKED: 
@GST_PAD_FLUSHING: 
@GST_PAD_IN_GETCAPS: 
@GST_PAD_IN_SETCAPS: 
@GST_PAD_FLAG_LAST: 

<!-- ##### ENUM GstPadLinkReturn ##### -->


@GST_PAD_LINK_OK: 
@GST_PAD_LINK_WRONG_HIERARCHY: 
@GST_PAD_LINK_WAS_LINKED: 
@GST_PAD_LINK_WRONG_DIRECTION: 
@GST_PAD_LINK_NOFORMAT: 
@GST_PAD_LINK_NOSCHED: 
@GST_PAD_LINK_REFUSED: 

<!-- ##### ENUM GstPadPresence ##### -->
<para>
Indicates when this pad will become available.
</para>

@GST_PAD_ALWAYS: the pad is always available
@GST_PAD_SOMETIMES: the pad will become available depending on the media stream
@GST_PAD_REQUEST: the pad is only available on request with 
gst_element_request_pad_by_name() or gst_element_request_compatible_pad().

<!-- ##### ENUM GstFlowReturn ##### -->
<para>

</para>

@GST_FLOW_RESEND: 
@GST_FLOW_OK: 
@GST_FLOW_NOT_LINKED: 
@GST_FLOW_WRONG_STATE: 
@GST_FLOW_UNEXPECTED: 
@GST_FLOW_NOT_NEGOTIATED: 
@GST_FLOW_ERROR: 
@GST_FLOW_NOT_SUPPORTED: 

<!-- ##### ENUM GstActivateMode ##### -->
<para>

</para>

@GST_ACTIVATE_NONE: 
@GST_ACTIVATE_PUSH: 
@GST_ACTIVATE_PULL: 

<!-- ##### MACRO GST_PREROLL_BROADCAST ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_PREROLL_GET_COND ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_PREROLL_GET_LOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_PREROLL_LOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_PREROLL_SIGNAL ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_PREROLL_TIMED_WAIT ##### -->
<para>

</para>

@pad: 
@timeval: 


<!-- ##### MACRO GST_PREROLL_TRYLOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_PREROLL_UNLOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_PREROLL_WAIT ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_STREAM_GET_LOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_STREAM_LOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_STREAM_LOCK_FULL ##### -->
<para>

</para>

@pad: 
@t: 


<!-- ##### MACRO GST_STREAM_TRYLOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_STREAM_UNLOCK ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_STREAM_UNLOCK_FULL ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_FLOW_IS_FATAL ##### -->
<para>

</para>

@ret: 


<!-- ##### FUNCTION gst_pad_new ##### -->
<para>

</para>

@name: 
@direction: 
@Returns: 


<!-- ##### FUNCTION gst_pad_new_from_template ##### -->
<para>

</para>

@templ: 
@name: 
@Returns: 


<!-- ##### MACRO gst_pad_get_name ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_direction ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### MACRO gst_pad_get_parent ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_parent_element ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_active ##### -->
<para>

</para>

@pad: 
@active: 
@Returns: 
<!-- # Unused Parameters # -->
@mode: 


<!-- ##### FUNCTION gst_pad_is_active ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_blocked ##### -->
<para>

</para>

@pad: 
@blocked: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_blocked_async ##### -->
<para>

</para>

@pad: 
@blocked: 
@callback: 
@user_data: 
@Returns: 


<!-- ##### FUNCTION gst_pad_is_blocked ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_element_private ##### -->
<para>

</para>

@pad: 
@priv: 


<!-- ##### FUNCTION gst_pad_get_element_private ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_pad_template ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_bufferalloc_function ##### -->
<para>

</para>

@pad: 
@bufalloc: 
<!-- # Unused Parameters # -->
@bufferalloc: 


<!-- ##### FUNCTION gst_pad_alloc_buffer ##### -->
<para>

</para>

@pad: 
@offset: 
@size: 
@caps: 
@buf: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
<para>

</para>

@pad: 
@chain: 


<!-- ##### FUNCTION gst_pad_chain ##### -->
<para>

</para>

@pad: 
@buffer: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_checkgetrange_function ##### -->
<para>

</para>

@pad: 
@check: 


<!-- ##### FUNCTION gst_pad_set_getrange_function ##### -->
<para>

</para>

@pad: 
@get: 


<!-- ##### FUNCTION gst_pad_get_range ##### -->
<para>

</para>

@pad: 
@offset: 
@size: 
@buffer: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_event_function ##### -->
<para>

</para>

@pad: 
@event: 


<!-- ##### FUNCTION gst_pad_set_unlink_function ##### -->
<para>

</para>

@pad: 
@unlink: 


<!-- ##### FUNCTION gst_pad_set_activate_function ##### -->
<para>

</para>

@pad: 
@activate: 


<!-- ##### FUNCTION gst_pad_set_activatepull_function ##### -->
<para>

</para>

@pad: 
@activatepull: 


<!-- ##### FUNCTION gst_pad_start_task ##### -->
<para>

</para>

@pad: 
@func: 
@data: 
@Returns: 


<!-- ##### FUNCTION gst_pad_pause_task ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_stop_task ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_link ##### -->
<para>

</para>

@srcpad: 
@sinkpad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_unlink ##### -->
<para>

</para>

@srcpad: 
@sinkpad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_is_linked ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_link_function ##### -->
<para>

</para>

@pad: 
@link: 


<!-- ##### FUNCTION gst_pad_can_link ##### -->
<para>

</para>

@srcpad: 
@sinkpad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_accept_caps ##### -->
<para>

</para>

@pad: 
@caps: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_negotiated_caps ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_caps ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_caps ##### -->
<para>

</para>

@pad: 
@caps: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_pad_template_caps ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_acceptcaps_function ##### -->
<para>

</para>

@pad: 
@acceptcaps: 


<!-- ##### FUNCTION gst_pad_set_getcaps_function ##### -->
<para>

</para>

@pad: 
@getcaps: 


<!-- ##### FUNCTION gst_pad_set_setcaps_function ##### -->
<para>

</para>

@pad: 
@setcaps: 


<!-- ##### FUNCTION gst_pad_proxy_getcaps ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_proxy_setcaps ##### -->
<para>

</para>

@pad: 
@caps: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_allowed_caps ##### -->
<para>

</para>

@srcpad: 
@Returns: 
<!-- # Unused Parameters # -->
@pad: 


<!-- ##### FUNCTION gst_pad_get_fixed_caps_func ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_peer ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_peer_get_caps ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_peer_accept_caps ##### -->
<para>

</para>

@pad: 
@caps: 
@Returns: 


<!-- ##### FUNCTION gst_pad_use_fixed_caps ##### -->
<para>

</para>

@pad: 


<!-- ##### FUNCTION gst_pad_fixate_caps ##### -->
<para>

</para>

@pad: 
@caps: 


<!-- ##### FUNCTION gst_pad_set_fixatecaps_function ##### -->
<para>

</para>

@pad: 
@fixatecaps: 


<!-- ##### FUNCTION gst_pad_set_activatepush_function ##### -->
<para>

</para>

@pad: 
@activatepush: 


<!-- ##### FUNCTION gst_pad_push ##### -->
<para>

</para>

@pad: 
@buffer: 
@Returns: 
<!-- # Unused Parameters # -->
@data: 
@buf: 


<!-- ##### FUNCTION gst_pad_push_event ##### -->
<para>

</para>

@pad: 
@event: 
@Returns: 


<!-- ##### FUNCTION gst_pad_check_pull_range ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_pull_range ##### -->
<para>

</para>

@pad: 
@offset: 
@size: 
@buffer: 
@Returns: 


<!-- ##### FUNCTION gst_pad_activate_pull ##### -->
<para>

</para>

@pad: 
@active: 
@Returns: 


<!-- ##### FUNCTION gst_pad_activate_push ##### -->
<para>

</para>

@pad: 
@active: 
@Returns: 


<!-- ##### FUNCTION gst_pad_send_event ##### -->
<para>

</para>

@pad: 
@event: 
@Returns: 


<!-- ##### FUNCTION gst_pad_event_default ##### -->
<para>

</para>

@pad: 
@event: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_query_function ##### -->
<para>

</para>

@pad: 
@query: 


<!-- ##### FUNCTION gst_pad_set_query_type_function ##### -->
<para>

</para>

@pad: 
@type_func: 


<!-- ##### FUNCTION gst_pad_get_query_types ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_query_types_default ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_query ##### -->
<para>

</para>

@pad: 
@query: 
@Returns: 
<!-- # Unused Parameters # -->
@type: 
@format: 
@value: 


<!-- ##### FUNCTION gst_pad_query_default ##### -->
<para>

</para>

@pad: 
@query: 
@Returns: 
<!-- # Unused Parameters # -->
@type: 
@format: 
@value: 


<!-- ##### FUNCTION gst_pad_query_position ##### -->
<para>

</para>

@pad: 
@format: 
@cur: 
@end: 
@Returns: 


<!-- ##### FUNCTION gst_pad_query_convert ##### -->
<para>

</para>

@pad: 
@src_format: 
@src_val: 
@dest_format: 
@dest_val: 
@Returns: 
<!-- # Unused Parameters # -->
@dest_fmt: 


<!-- ##### FUNCTION gst_pad_set_internal_link_function ##### -->
<para>

</para>

@pad: 
@intlink: 


<!-- ##### FUNCTION gst_pad_get_internal_links ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_internal_links_default ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_dispatcher ##### -->
<para>

</para>

@pad: 
@dispatch: 
@data: 
@Returns: 


<!-- ##### FUNCTION gst_pad_load_and_link ##### -->
<para>

</para>

@self: 
@parent: 


<!-- ##### FUNCTION gst_pad_add_data_probe ##### -->
<para>

</para>

@pad: 
@handler: 
@data: 
@Returns: 


<!-- ##### FUNCTION gst_pad_add_buffer_probe ##### -->
<para>

</para>

@pad: 
@handler: 
@data: 
@Returns: 


<!-- ##### FUNCTION gst_pad_add_event_probe ##### -->
<para>

</para>

@pad: 
@handler: 
@data: 
@Returns: 


<!-- ##### FUNCTION gst_pad_remove_data_probe ##### -->
<para>

</para>

@pad: 
@handler: 
@data: 


<!-- ##### FUNCTION gst_pad_remove_buffer_probe ##### -->
<para>

</para>

@pad: 
@handler: 
@data: 


<!-- ##### FUNCTION gst_pad_remove_event_probe ##### -->
<para>

</para>

@pad: 
@handler: 
@data: