gstreamer/docs/gst/tmpl/gstelement.sgml
Wim Taymans b5c170f42a API docs updates
Original commit message from CVS:
API docs updates
2002-07-12 23:21:20 +00:00

925 lines
15 KiB
Text

<!-- ##### SECTION Title ##### -->
GstElement
<!-- ##### SECTION Short_Description ##### -->
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 connect to pads on
other elements. Buffers flow between these connected 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 connected through their pads.
If the connection is straightforward, use the gst_element_connect()
convenience function to connect two elements, or gst_element_connect_many()
for more elements in a row.
Use gst_element_connect_filtered() to connect two elements constrained by
a specified set of #GstCaps.
For finer control, use gst_element_connect_pads() and
gst_element_connect_pads_filtered() to specify the pads to connect 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>
<!-- ##### MACRO gst_element_destroy ##### -->
<para>
Destroys the element (without taking the refcount into account).
An application programmer should use #gst_object_unref instead to dispose
of an element he doesn't need anymore.
</para>
@element: a #GstElement to destroy
<!-- ##### FUNCTION gst_element_get_name ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_set_name ##### -->
<para>
</para>
@element:
@name:
<!-- connection -->
<!-- ##### FUNCTION gst_element_get_factory ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_add_pad ##### -->
<para>
</para>
@element:
@pad:
<!-- ##### FUNCTION gst_element_remove_pad ##### -->
<para>
</para>
@element:
@pad:
<!-- ##### FUNCTION gst_element_add_ghost_pad ##### -->
<para>
</para>
@element:
@pad:
@name:
@Returns:
<!-- ##### FUNCTION gst_element_remove_ghost_pad ##### -->
<para>
</para>
@element:
@pad:
<!-- pad template manipulation -->
<!-- ##### 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_pad_list ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_get_pad_template ##### -->
<para>
</para>
@element:
@name:
@Returns:
<!-- ##### FUNCTION gst_element_get_pad_template_list ##### -->
<para>
</para>
@element:
@Returns:
<!-- scheduling -->
<!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
<para>
</para>
@klass:
@templ:
<!-- # Unused Parameters # -->
@element:
<!-- ##### FUNCTION gst_element_connect ##### -->
<para>
</para>
@src:
@dest:
@Returns:
<!-- ##### FUNCTION gst_element_connect_many ##### -->
<para>
</para>
@element_1:
@element_2:
@Varargs:
@Returns:
<!-- ##### FUNCTION gst_element_connect_filtered ##### -->
<para>
</para>
@src:
@dest:
@filtercaps:
@Returns:
<!-- ##### FUNCTION gst_element_connect_pads ##### -->
<para>
</para>
@src:
@srcpadname:
@dest:
@destpadname:
@Returns:
<!-- ##### FUNCTION gst_element_connect_pads_filtered ##### -->
<para>
</para>
@src:
@srcpadname:
@dest:
@destpadname:
@filtercaps:
@Returns:
<!-- ##### FUNCTION gst_element_disconnect ##### -->
<para>
</para>
@src:
@dest:
<!-- # Unused Parameters # -->
@srcpadname:
@destpadname:
<!-- ##### FUNCTION gst_element_disconnect_many ##### -->
<para>
</para>
@element_1:
@element_2:
@Varargs:
<!-- ##### FUNCTION gst_element_disconnect_pads ##### -->
<para>
</para>
@src:
@srcpadname:
@dest:
@destpadname:
<!-- pad manipulation -->
<!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
<para>
</para>
@element:
@pad:
@Returns:
<!-- ##### FUNCTION gst_element_get_compatible_pad_filtered ##### -->
<para>
</para>
@element:
@pad:
@filtercaps:
@Returns:
<!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
<para>
</para>
@element:
@compattempl:
@Returns:
<!-- ##### FUNCTION gst_element_set_state ##### -->
<para>
</para>
@element:
@state:
@Returns:
<!-- ##### FUNCTION gst_element_get_state ##### -->
<para>
</para>
@element:
@Returns:
<!-- # Unused Parameters # -->
@elem:
<!-- ##### FUNCTION gst_element_state_get_name ##### -->
<para>
</para>
@state:
@Returns:
<!-- ##### FUNCTION gst_element_wait_state_change ##### -->
<para>
</para>
@element:
<!-- ##### FUNCTION gst_element_error ##### -->
<para>
</para>
@element:
@error:
@Varargs:
<!-- ##### FUNCTION gst_element_set_eos ##### -->
<para>
</para>
@element:
<!-- ##### FUNCTION gst_element_interrupt ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_yield ##### -->
<para>
</para>
@element:
<!-- ##### FUNCTION gst_element_release_locks ##### -->
<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_clock_wait ##### -->
<para>
</para>
@element:
@clock:
@time:
@jitter:
@Returns:
<!-- ##### USER_FUNCTION GstElementGetClockFunction ##### -->
<para>
The function to get the clock from a clock providing element
</para>
@element: The element to get the clock of
@Returns: The clock provided by the element
<!-- ##### USER_FUNCTION GstElementSetClockFunction ##### -->
<para>
The function to set the clock on a clock receiving element.
</para>
@element: The element to set the clock on
@clock: The clock to set on the element
<!-- ##### FUNCTION gst_element_set_loop_function ##### -->
<para>
</para>
@element:
@loop:
<!-- ##### USER_FUNCTION GstElementLoopFunction ##### -->
<para>
This function type is used to specify a loop function for the element. It
is passed the element in question, and is expect to return only in error
circumstances.
</para>
@element: The element in question.
<!-- ##### FUNCTION gst_element_get_scheduler ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_set_scheduler ##### -->
<para>
</para>
@element:
@sched:
<!-- ##### FUNCTION gst_element_get_parent ##### -->
<para>
</para>
@element:
@Returns:
<!-- ##### FUNCTION gst_element_set_parent ##### -->
<para>
</para>
@element:
@parent:
<!-- ##### FUNCTION gst_element_get_managing_bin ##### -->
<para>
</para>
@element:
@Returns:
<!-- clocking -->
<!-- ##### USER_FUNCTION GstElementPostRunFunction ##### -->
<para>
The signature of the function to execute before this element
is scheduled.
</para>
@element: The element
<!-- ##### USER_FUNCTION GstElementPreRunFunction ##### -->
<para>
The signature of the function to execute after this element
is scheduled.
</para>
@element: The element
<!-- ##### FUNCTION gst_element_disable_threadsafe_properties ##### -->
<para>
</para>
@element:
<!-- ##### FUNCTION gst_element_enable_threadsafe_properties ##### -->
<para>
</para>
@element:
<!-- ##### FUNCTION gst_element_get ##### -->
<para>
</para>
@element:
@first_property_name:
@Varargs:
<!-- ##### FUNCTION gst_element_get_property ##### -->
<para>
</para>
@element:
@property_name:
@value:
<!-- ##### FUNCTION gst_element_get_valist ##### -->
<para>
</para>
@element:
@first_property_name:
@var_args:
<!-- ##### FUNCTION gst_element_set ##### -->
<para>
</para>
@element:
@first_property_name:
@Varargs:
<!-- ##### FUNCTION gst_element_set_pending_properties ##### -->
<para>
</para>
@element:
<!-- ##### FUNCTION gst_element_set_property ##### -->
<para>
</para>
@element:
@property_name:
@value:
<!-- ##### FUNCTION gst_element_set_valist ##### -->
<para>
</para>
@element:
@first_property_name:
@var_args:
<!-- ##### FUNCTION gst_element_query ##### -->
<para>
</para>
@element:
@type:
@format:
@value:
@Returns:
<!-- ##### FUNCTION gst_element_send_event ##### -->
<para>
</para>
@element:
@event:
@Returns:
<!-- ##### ENUM GstElementState ##### -->
<para>
This enum defines the standard states an element may be in. You will normally
use gst_element_set_state() to change the state of an element.
</para>
@GST_STATE_VOID_PENDING:
@GST_STATE_NULL: Reset the state of an element.
@GST_STATE_READY: will make the element ready to start processing data. some
elements might have a non trivial way to initialize themselves.
@GST_STATE_PAUSED: means there really is data flowing temporary stops the data flow.
@GST_STATE_PLAYING: means there really is data flowing through the graph.
<!-- ##### ENUM GstElementStateReturn ##### -->
<para>
This enum defines the standard return values that an element
can return after a state change.
</para>
@GST_STATE_FAILURE: the element could not perform the state change
@GST_STATE_SUCCESS: the element successfully changed its state
@GST_STATE_ASYNC: the element will asynchronously change its state as soon as possible
<!-- ##### 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_READY ##### -->
<para>
The Element is going from the PAUSED state to the READY 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_PLAYING ##### -->
<para>
The Element is going from the PAUSED state to the PLAYING state.
</para>
<!-- ##### MACRO GST_STATE_READY_TO_NULL ##### -->
<para>
The Element is going from the READY state to the NULL state.
</para>
<!-- ##### ENUM GstElementFlags ##### -->
<para>
This enum defines the standard flags that an element may have.
</para>
@GST_ELEMENT_COMPLEX:
@GST_ELEMENT_DECOUPLED:
@GST_ELEMENT_THREAD_SUGGESTED:
@GST_ELEMENT_INFINITE_LOOP:
@GST_ELEMENT_NEW_LOOPFUNC:
@GST_ELEMENT_EVENT_AWARE:
@GST_ELEMENT_USE_THREADSAFE_PROPERTIES:
@GST_ELEMENT_SCHEDULER_PRIVATE1:
@GST_ELEMENT_SCHEDULER_PRIVATE2:
@GST_ELEMENT_FLAG_LAST:
<!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### -->
<para>
Queries whether the Element should be placed in a thread.
</para>
@obj: a #GstElement to query
<!-- ##### MACRO GST_ELEMENT_IS_DECOUPLED ##### -->
<para>
Queries if the Element is decoupled.
</para>
@obj: a #GstElement to query
<!-- ##### MACRO GST_ELEMENT_IS_EOS ##### -->
<para>
Query wether this element is in the End Of Stream state.
</para>
@obj: a #GstElement to query
<!-- ##### MACRO GST_ELEMENT_IS_EVENT_AWARE ##### -->
<para>
Query wether this element can handle events.
</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_NAME ##### -->
<para>
Gets the name of this element. Used in the core. Not ABI-compatible.
</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_SCHED ##### -->
<para>
Get the scheduler of this element.
</para>
@obj: a #GstElement to query
<!-- ##### MACRO GST_ELEMENT_MANAGER ##### -->
<para>
Get the manager 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
<!-- ##### SIGNAL GstElement::deep-notify ##### -->
<para>
</para>
@gstelement: the object which received the signal.
@arg1:
@arg2:
<!-- ##### SIGNAL GstElement::eos ##### -->
<para>
</para>
@gstelement: the object which received the signal.
<!-- ##### SIGNAL GstElement::error ##### -->
<para>
Is trigered whenever an error occured
</para>
@gstelement: the object which received the signal.
@arg1: the error message
@arg2:
<!-- ##### SIGNAL GstElement::new-pad ##### -->
<para>
Is trigered whenever a new pad is added to an element
</para>
@gstelement: the object which received the signal.
@arg1: the new pad that was added
<!-- ##### SIGNAL GstElement::pad-removed ##### -->
<para>
</para>
@gstelement: the object which received the signal.
@arg1: The pad that was removed.
<!-- ##### SIGNAL GstElement::state-change ##### -->
<para>
Is trigered whenever the state of an element changes
</para>
@gstelement: the object which received the signal.
@arg1: the new state of the object
@arg2: