gstreamer/docs/gst/tmpl/gstpad.sgml
Andy Wingo f2cf753b17 gst/base/gsttypefindhelper.c (gst_type_find_helper): Unref any remaining buffer.
Original commit message from CVS:
2005-06-27  Andy Wingo  <wingo@pobox.com>

* gst/base/gsttypefindhelper.c (gst_type_find_helper): Unref any
remaining buffer.

* gst/gsttrace.c (gst_alloc_trace_list_sorted): New helper,
returns a sorted copy of the trace list.
(gst_alloc_trace_print_live): New API, only prints traces with
live objects. Sort the list.
(gst_alloc_trace_print_all): Sort the list.
(gst_alloc_trace_print): Align columns.

* gst/elements/gstttypefindelement.c:
* gst/elements/gsttee.c:
* gst/base/gstbasesrc.c:
* gst/base/gstbasesink.c:
* gst/base/gstbasetransform.c:
* gst/gstqueue.c: Adapt for pad activation changes.

* gst/gstpipeline.c (gst_pipeline_init): Unref after parenting
sched.
(gst_pipeline_dispose): Drop ref on sched.

* gst/gstpad.c (gst_pad_init): Set the default activate func.
(gst_pad_activate_default): Push mode by default.
(pre_activate_switch, post_activate_switch): New stubs, things to
do before and after switching activation modes on pads.
(gst_pad_set_active): Take a boolean and not a mode, dispatch to
the pad's activate function to choose which mode to activate.
Shortcut on deactivation and call the right function directly.
(gst_pad_activate_pull): New API, (de)activates a pad in pull
mode.
(gst_pad_activate_push): New API, same for push mode.
(gst_pad_set_activate_function)
(gst_pad_set_activatepull_function)
(gst_pad_set_activatepush_function): Setters for new API.

* gst/gstminiobject.c (gst_mini_object_new, gst_mini_object_free):
Trace all miniobjects.
(gst_mini_object_make_writable): Unref the arg if we copy, like
gst_caps_make_writable.

* gst/gstmessage.c (_gst_message_initialize): No trace init.

* gst/gstghostpad.c (gst_proxy_pad_do_activate)
(gst_proxy_pad_do_activatepull, gst_proxy_pad_do_activatepush):
Adapt for new pad API.

* gst/gstevent.c (_gst_event_initialize): Don't initialize trace.

* gst/gstelement.h:
* gst/gstelement.c (gst_element_iterate_src_pads)
(gst_element_iterate_sink_pads): New API functions.

* gst/gstelement.c (iterator_fold_with_resync): New utility,
should fold into gstiterator.c in some form.
(gst_element_pads_activate): Simplified via use of fold and
delegation of decisions to gstpad->activate.

* gst/gstbus.c (gst_bus_source_finalize): Set the bus to NULL,
help in debugging.

* gst/gstbuffer.c (_gst_buffer_initialize): Ref the buffer type
class once in init, like gstmessage. Didn't run into this issue
but it seems correct. Don't initialize a trace, gstminiobject does
that.

* check/pipelines/simple_launch_lines.c (test_stop_from_app): New
test, runs fakesrc ! fakesink, stopping on ::handoff via a message
to the bus.
(assert_live_count): New util function, uses alloc traces to check
cleanup.

* check/gst/gstghostpad.c (test_ghost_pads): More refcount checks.
To be modified when unlink drops the internal pad.
2005-06-27 18:35:05 +00:00

825 lines
13 KiB
Text

<!-- ##### 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>
<!-- ##### 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:
@loopfunc:
@chainfunc:
@checkgetrangefunc:
@getrangefunc:
@eventfunc:
@mode:
@querytypefunc:
@queryfunc:
@intlinkfunc:
@bufferallocfunc:
@probedisp:
<!-- ##### 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 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 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 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 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 ##### -->
<para>
The result of a pad link.
</para>
@GST_PAD_LINK_NOSCHED:
@GST_PAD_LINK_NOFORMAT:
@GST_PAD_LINK_REFUSED: the link was refused.
@GST_PAD_LINK_WRONG_DIRECTION:
@GST_PAD_LINK_WAS_LINKED:
@GST_PAD_LINK_OK: the link succeeded.
<!-- ##### 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().
<!-- ##### MACRO GST_PAD_NAME ##### -->
<para>
Gets the name of the pad.
</para>
@pad: a #GstPad to get the name of.
@Returns: the pad's name.
<!-- ##### MACRO GST_PAD_PARENT ##### -->
<para>
Gets the parent element of this pad.
</para>
@pad: a #GstPad to get the parent of.
@Returns: the parent #GstElement of this pad.
<!-- ##### MACRO GST_PAD_ELEMENT_PRIVATE ##### -->
<para>
Gets the private data set by the element that owns the pad.
</para>
@pad: a #GstPad to get the private data of.
#Returns: a gpointer to the private data.
<!-- ##### MACRO GST_PAD_PAD_TEMPLATE ##### -->
<para>
Gets the pad template that was used to create this pad.
</para>
@pad: a #GstPad to get the pad template of.
#Returns: the #GstPadTemplate used to create the pad, or NULL if none was
used.
<!-- ##### MACRO GST_PAD_DIRECTION ##### -->
<para>
Gets the pad's direction.
</para>
@pad: a #GstPad to get the direction of.
@Returns: the #GstPadDirection of the pad.
<!-- ##### MACRO GST_PAD_CAPS ##### -->
<para>
Gets the capabilities of a pad.
</para>
@pad: a #GstPad to get the capabilities of.
@Returns: the #GstCaps of the pad.
<!-- ##### MACRO GST_PAD_PEER ##### -->
<para>
Gets the peer pad of this pad. The peer pad is the pad on to which the parent
element is linked through this pad.
</para>
@pad: a #GstPad to get the peer pad of.
@Returns: the peer #GstPad.
<!-- ##### MACRO GST_PAD_IS_LINKED ##### -->
<para>
Checks if the pad is linked.
</para>
@pad: a #GstPad to check.
<!-- ##### MACRO GST_PAD_IS_USABLE ##### -->
<para>
Checks if a pad is usable. A usable pad is both linked and active.
</para>
@pad: a #GstPad to check
<!-- ##### MACRO GST_PAD_IS_SRC ##### -->
<para>
Checks if the pad is a source pad.
</para>
@pad: a #GstPad to check.
<!-- ##### MACRO GST_PAD_IS_SINK ##### -->
<para>
Checks if the pad is a sink pad.
</para>
@pad: a #GstPad to check.
<!-- ##### 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:
<!-- ##### 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_element_private ##### -->
<para>
</para>
@pad:
@priv:
<!-- ##### FUNCTION gst_pad_get_element_private ##### -->
<para>
</para>
@pad:
@Returns:
<!-- ##### FUNCTION gst_pad_get_parent ##### -->
<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_set_event_function ##### -->
<para>
</para>
@pad:
@event:
<!-- ##### FUNCTION gst_pad_set_link_function ##### -->
<para>
</para>
@pad:
@link:
<!-- ##### FUNCTION gst_pad_can_link ##### -->
<para>
</para>
@srcpad:
@sinkpad:
@Returns:
<!-- ##### FUNCTION gst_pad_set_unlink_function ##### -->
<para>
</para>
@pad:
@unlink:
<!-- ##### 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_get_peer ##### -->
<para>
</para>
@pad:
@Returns:
<!-- ##### FUNCTION gst_pad_get_negotiated_caps ##### -->
<para>
</para>
@pad:
@Returns:
<!-- ##### FUNCTION gst_pad_get_caps ##### -->
<para>
</para>
@pad:
@Returns:
<!-- ##### FUNCTION gst_pad_get_pad_template_caps ##### -->
<para>
</para>
@pad:
@Returns:
<!-- ##### FUNCTION gst_pad_set_getcaps_function ##### -->
<para>
</para>
@pad:
@getcaps:
<!-- ##### FUNCTION gst_pad_proxy_getcaps ##### -->
<para>
</para>
@pad:
@Returns:
<!-- ##### FUNCTION gst_pad_get_allowed_caps ##### -->
<para>
</para>
@srcpad:
@Returns:
<!-- # Unused Parameters # -->
@pad:
<!-- ##### FUNCTION gst_pad_push ##### -->
<para>
</para>
@pad:
@buffer:
@Returns:
<!-- # Unused Parameters # -->
@data:
@buf:
<!-- ##### 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_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:
<!-- ##### MACRO gst_pad_add_probe ##### -->
<para>
Adds the probe to the given pad
</para>
@pad: The pad to add the probe to
@probe: The probe to add to the pad
<!-- ##### MACRO gst_pad_remove_probe ##### -->
<para>
Remove the probe from the pad
</para>
@pad: The pad to remove the probe of
@probe: The probe to remove
<!-- ##### FUNCTION gst_pad_load_and_link ##### -->
<para>
</para>
@self:
@parent: