gstreamer/docs/gst/tmpl/gstpad.sgml
Andy Wingo c1d34b8acf tests/network-clock.scm: Commentary update.
Original commit message from CVS:
2005-07-01  Andy Wingo  <wingo@pobox.com>

* tests/network-clock.scm: Commentary update.

* gst/elements/gstidentity.c (PROP_DUPLICATE): Gone daddy gone.
Didn't really make sense, not implementable with basetransform,
etc.
(gst_identity_transform): Unref inbuf via make_writable. Feeble
attempt at implementing the sync property, needs an unlock method.

* gst/base/gstbasetransform.c (gst_base_transform_transform_caps):
New func, by default returns the same caps (the identity
transformation).
(gst_base_transform_getcaps): Uses transform_caps to return
something sensible.
(gst_base_transform_setcaps): Complicated logic to get caps on
both pads, even if they are different, and to call set_caps once
for every time both pads get their caps set.
(gst_base_transform_handle_buffer): Give the ref to the transform
function. Allows in-place modification of the buffer.

* gst/base/gstbasetransform.h (transform_caps): New class method.
Given caps on one side, what can I do on the other.
(set_caps): Take two caps, one for each side of the element.

* gst/gstpad.h:
* gst/gstpad.c (gst_pad_fixate_caps): Change prototype to modify
caps in place. This is safe because we can check the mutability of
the caps, and a good idea because fixate functions are just called
as a matter of last resort. (Not actually implemented.)
(gst_pad_set_caps): If the caps we're setting is actually the same
as the existing pad caps, just update the pointer without calling
setcaps. Assert that caps is either NULL or fixed, as per the
docs.

* gst/gstghostpad.c: Update for fixate changes.
2005-07-01 16:46:59 +00:00

876 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:
@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 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:
<!-- ##### FUNCTION gst_pad_load_and_link ##### -->
<para>
</para>
@self:
@parent:
<!-- ##### FUNCTION gst_pad_add_data_probe ##### -->
<para>
</para>
@pad:
@handler:
@data:
<!-- ##### FUNCTION gst_pad_add_buffer_probe ##### -->
<para>
</para>
@pad:
@handler:
@data:
<!-- ##### FUNCTION gst_pad_add_event_probe ##### -->
<para>
</para>
@pad:
@handler:
@data:
<!-- ##### 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: