gstreamer/docs/gst/tmpl/gstelement.sgml
Andy Wingo 4b908e33e0 gst/gstutils.c: RPAD fixes all around.
Original commit message from CVS:
2005-06-08  Andy Wingo  <wingo@pobox.com>

* gst/gstutils.c: RPAD fixes all around.
(gst_element_link_pads): Refcounting fixes.

* tools/gst-inspect.c:
* tools/gst-xmlinspect.c:
* parse/grammar.y:
* gst/base/gsttypefindhelper.c:
* gst/base/gstbasesink.c:
* gst/gstqueue.c: RPAD fixes.

* gst/gstghostpad.h:
* gst/gstghostpad.c: New ghost pad implementation as full proxy
pads. The tricky thing is they provide both source and sink
interfaces, since they proxy the internal pad for the external
pad, and vice versa. Implement with lower-level ProxyPad objects,
with the interior proxy pad as a child of the exterior ghost pad.
Should write a doc on this.

* gst/gstpad.h: s/RPAD/PAD/, s/RealPad/Pad/.
(gst_pad_set_name, gst_pad_set_parent): Macros removed, use
gst_object API.

* gst/gstpad.c: Big changes. No more stub base GstPad, now all
pads are real pads. No ghost pads in this file. Not documenting
the myriad s/RPAD/PAD/ and REALIZE fixes.
(gst_pad_class_init): Add properties for "direction" and
"template". Both are construct-only, so they can't change during
the life of the pad. Fixes properly deriving from GstPad.
(gst_pad_custom_new, gst_pad_custom_new_from_template): Gone. For
derived objects, just set properties when creating the objects via
g_object_new.
(gst_pad_get_parent): Implement as a function, return NULL if the
parent is not an element.
(gst_pad_get_real_parent, gst_pad_add_ghost_pad)
(gst_pad_remove_ghost_pad, gst_pad_realize): Removed.

* gst/gstobject.c (gst_object_class_init): Make name a construct
property. Don't set it in the object init.

* gst/gstelement.c (gst_element_add_pad): Don't allow adding pads
with UNKNOWN direction.
(gst_element_add_ghost_pad): Remove non-orthogonal API. Replace
with gst_element_add_pad (e, gst_ghost_pad_new (name, pad)).
(gst_element_remove_pad): Remove ghost-pad special cases.
(gst_element_pads_activate): Remove rpad cruft.

* gst/gstbin.c (gst_bin_change_state): Use gst_pad_get_parent to
catch the pad's-parent-not-an-element case.

* gst/gst.h: Include gstghostpad.h.

* gst/gst.c (init_post): No more real, ghost pads.

* gst/Makefile.am: Add gstghostpad.[ch].

* check/Makefile.am:
* check/gst/gstbin.c:
* check/gst/gstghostpad.c (test_ghost_pads): Check that linking
into a bin creates ghost pads, and that the refcounts are right.
Partly moved from gstbin.c.
2005-06-08 22:16:27 +00:00

712 lines
11 KiB
Text

<!-- ##### SECTION Title ##### -->
GstElement
<!-- ##### SECTION Short_Description ##### -->
Abstract base class for all pipeline elements
<!-- ##### SECTION Long_Description ##### -->
<para>
GstElement is the base class needed to construct an element that can be
used in a GStreamer pipeline. As such, it is not a functional entity, and
cannot do anything when placed in a pipeline.
</para>
<para>
The name of a GstElement can be get with gst_element_get_name() and set with
gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the
core.
Do not use this in plug-ins or applications in order to retain ABI
compatibility.
</para>
<para>
All elements have pads (of the type #GstPad). These pads link to pads on
other elements. Buffers flow between these linked pads.
A GstElement has a GList of #GstPad structures for all their input (or sink)
and output (or source) pads.
Core and plug-in writers can add and remove pads with gst_element_add_pad()
and gst_element_remove_pad().
Application writers can manipulate ghost pads (copies of real pads inside a bin)
with gst_element_add_ghost_pad() and gst_element_remove_ghost_pad().
A pad of an element can be retrieved by name with gst_element_get_pad().
A GList of all pads can be retrieved with gst_element_get_pad_list().
</para>
<para>
Elements can be linked through their pads.
If the link is straightforward, use the gst_element_link()
convenience function to link two elements, or gst_element_link_many()
for more elements in a row.
Use gst_element_link_filtered() to link two elements constrained by
a specified set of #GstCaps.
For finer control, use gst_element_link_pads() and
gst_element_link_pads_filtered() to specify the pads to link on
each element by name.
</para>
<para>
Each element has a state (see #GstElementState). You can get and set the state
of an element with gst_element_get_state() and gst_element_set_state().
You can wait for an element to change it's state with gst_element_wait_state_change().
To get a string representation of a #GstElementState, use
gst_element_state_get_name().
</para>
<para>
You can get and set a #GstClock on an element using gst_element_get_clock()
and gst_element_set_clock(). You can wait for the clock to reach a given
#GstClockTime using gst_element_clock_wait().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstElementFactory, #GstPad
</para>
<!-- basic object functions -->
<!-- ##### STRUCT GstElement ##### -->
<para>
</para>
@state_lock:
@state_cond:
@current_state:
@pending_state:
@state_error:
@manager:
@bus:
@scheduler:
@clock:
@base_time:
@numpads:
@pads:
@numsrcpads:
@srcpads:
@numsinkpads:
@sinkpads:
@pads_cookie:
<!-- ##### SIGNAL GstElement::new-pad ##### -->
<para>
</para>
@gstelement: the object which received the signal.
@arg1:
<!-- ##### SIGNAL GstElement::no-more-pads ##### -->
<para>
</para>
@gstelement: the object which received the signal.
<!-- ##### SIGNAL GstElement::pad-removed ##### -->
<para>
</para>
@gstelement: the object which received the signal.
@arg1:
<!-- ##### SIGNAL GstElement::state-change ##### -->
<para>
</para>
@gstelement: the object which received the signal.
@arg1:
@arg2:
<!-- ##### MACRO GST_NUM_STATES ##### -->
<para>
The maximun number of states.
</para>
<!-- ##### MACRO GST_STATE ##### -->
<para>
This macro returns the current state of the element.
</para>
@obj: Element to return state for.
<!-- ##### MACRO GST_STATE_PENDING ##### -->
<para>
This macro returns the currently pending state of the element.
</para>
@obj: Element to return the pending state for.
<!-- ##### MACRO GST_STATE_TRANSITION ##### -->
<para>
Returns the state transition this object is going through.
</para>
@obj: the Element to return the state transition for
<!-- ##### MACRO GST_STATE_NULL_TO_READY ##### -->
<para>
The Element is going from the NULL state to the READY state.
</para>
<!-- ##### MACRO GST_STATE_READY_TO_PAUSED ##### -->
<para>
The Element is going from the READY state to the PAUSED state.
</para>
<!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### -->
<para>
The Element is going from the PAUSED state to the PLAYING state.
</para>
<!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### -->
<para>
The Element is going from the PLAYING state to the PAUSED state.
</para>
<!-- ##### MACRO GST_STATE_PAUSED_TO_READY ##### -->
<para>
The Element is going from the PAUSED state to the READY state.
</para>
<!-- ##### MACRO GST_STATE_READY_TO_NULL ##### -->
<para>
The Element is going from the READY state to the NULL state.
</para>
<!-- ##### MACRO GST_ELEMENT_QUERY_TYPE_FUNCTION ##### -->
<para>
Helper macro to create query type functions
</para>
@functionname: The function name
@...: list of query types.
<!-- ##### MACRO GST_ELEMENT_FORMATS_FUNCTION ##### -->
<para>
Halper macro to create element format functions
</para>
@functionname: The function name
@...: formats
<!-- ##### MACRO GST_ELEMENT_EVENT_MASK_FUNCTION ##### -->
<para>
A helper macro to create a mask function
</para>
@functionname: the name of the mask function
@...: Masks
<!-- ##### ENUM GstElementFlags ##### -->
<para>
This enum defines the standard flags that an element may have.
</para>
@GST_ELEMENT_SCHEDULER_PRIVATE1:
@GST_ELEMENT_SCHEDULER_PRIVATE2:
@GST_ELEMENT_LOCKED_STATE:
@GST_ELEMENT_IS_SINK:
@GST_ELEMENT_FLAG_LAST:
<!-- ##### MACRO GST_ELEMENT_NAME ##### -->
<para>
Gets the name of this element. Used in the core. Not ABI-compatible.
</para>
@obj: A #GstElement to query
<!-- ##### MACRO GST_ELEMENT_PARENT ##### -->
<para>
Get the parent object of this element.
</para>
@obj: a #GstElement to query
<!-- ##### MACRO GST_ELEMENT_CLOCK ##### -->
<para>
Get the clock of this element
</para>
@obj: a #GstElement to query
<!-- ##### MACRO GST_ELEMENT_PADS ##### -->
<para>
Get the pads of this elements.
</para>
@obj: a #GstElement to query
<!-- ##### MACRO GST_ELEMENT_ERROR ##### -->
<para>
</para>
@el:
@domain:
@code:
@text:
@debug:
<!-- # Unused Parameters # -->
@message:
<!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
<para>
</para>
@klass:
@templ:
<!-- ##### FUNCTION gst_element_class_install_std_props ##### -->
<para>
</para>
@klass:
@first_name:
@Varargs:
<!-- ##### FUNCTION gst_element_class_set_details ##### -->
<para>
</para>
@klass:
@details:
<!-- ##### MACRO gst_element_get_name ##### -->
<para>
Gets the name of the element.
</para>
@elem:
@Returns: the name of the element.
<!-- link -->
<!-- ##### MACRO gst_element_set_name ##### -->
<para>
Sets the name of the element, getting rid of the old name if there was one.
</para>
@elem: a #GstElement to set the name of.
@name: the new name of the element.
<!-- ##### MACRO gst_element_get_parent ##### -->
<para>
Gets the parent of an element.
</para>
@elem: a #GstElement to get the parent of.
@Returns: the #GstObject parent of the element.
<!-- ##### MACRO gst_element_set_parent ##### -->
<para>
Sets the parent of an element.
</para>
@elem: a #GstElement to set the parent of.
@parent: the new #GstObject parent of the object.
<!-- ##### FUNCTION gst_element_requires_clock ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_provides_clock ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_get_clock ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_set_clock ##### -->
<para>
</para>
@element:
@clock:
<!-- ##### FUNCTION gst_element_is_indexable ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_set_index ##### -->
<para>
</para>
@element:
@index:
<!-- ##### FUNCTION gst_element_get_index ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_set_scheduler ##### -->
<para>
</para>
@element:
@sched:
<!-- ##### FUNCTION gst_element_get_scheduler ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_add_pad ##### -->
<para>
</para>
@element:
@pad:
@Returns:
<!-- ##### FUNCTION gst_element_remove_pad ##### -->
<para>
</para>
@element:
@pad:
@Returns:
<!-- ##### FUNCTION gst_element_get_pad ##### -->
<para>
</para>
@element:
@name:
@Returns: GList of #GstPads
<!-- ##### FUNCTION gst_element_get_static_pad ##### -->
<para>
</para>
@element:
@name:
@Returns:
<!-- ##### FUNCTION gst_element_get_request_pad ##### -->
<para>
</para>
@element:
@name:
@Returns:
<!-- ##### FUNCTION gst_element_release_request_pad ##### -->
<para>
</para>
@element:
@pad:
<!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
<para>
</para>
@element:
@pad:
@caps:
@Returns:
<!-- ##### FUNCTION gst_element_class_get_pad_template ##### -->
<para>
</para>
@element_class:
@name:
@Returns:
<!-- ##### FUNCTION gst_element_class_get_pad_template_list ##### -->
<para>
</para>
@element_class:
@Returns:
<!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
<para>
</para>
@element:
@compattempl:
@Returns:
<!-- ##### FUNCTION gst_element_link ##### -->
<para>
</para>
@src:
@dest:
@Returns:
<!-- ##### FUNCTION gst_element_link_many ##### -->
<para>
</para>
@element_1:
@element_2:
@Varargs:
@Returns:
<!-- ##### FUNCTION gst_element_unlink ##### -->
<para>
</para>
@src:
@dest:
<!-- ##### FUNCTION gst_element_unlink_many ##### -->
<para>
</para>
@element_1:
@element_2:
@Varargs:
<!-- ##### FUNCTION gst_element_link_pads ##### -->
<para>
</para>
@src:
@srcpadname:
@dest:
@destpadname:
@Returns:
<!-- ##### FUNCTION gst_element_unlink_pads ##### -->
<para>
</para>
@src:
@srcpadname:
@dest:
@destpadname:
<!-- pad manipulation -->
<!-- ##### FUNCTION gst_element_send_event ##### -->
<para>
</para>
@element:
@event:
@Returns:
<!-- ##### FUNCTION gst_element_seek ##### -->
<para>
</para>
@element:
@seek_type:
@offset:
@Returns:
<!-- ##### FUNCTION gst_element_get_query_types ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_query ##### -->
<para>
</para>
@element:
@query:
@Returns:
<!-- # Unused Parameters # -->
@type:
@format:
@value:
<!-- ##### FUNCTION gst_element_is_locked_state ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_set_locked_state ##### -->
<para>
</para>
@element:
@locked_state:
@Returns:
<!-- ##### FUNCTION gst_element_sync_state_with_parent ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_get_state ##### -->
<para>
</para>
@element:
@state:
@pending:
@timeout:
@Returns:
<!-- ##### FUNCTION gst_element_set_state ##### -->
<para>
</para>
@element:
@state:
@Returns:
<!-- ##### FUNCTION gst_element_state_get_name ##### -->
<para>
</para>
@state:
@Returns:
<!-- ##### FUNCTION gst_element_get_factory ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_no_more_pads ##### -->
<para>
</para>
@element: