parts of the patch submitted in bug #113913
[platform/upstream/gstreamer.git] / docs / gst / tmpl / gstelement.sgml
index 60c9d1d..9165014 100644 (file)
@@ -7,280 +7,458 @@ 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 GST pipeline.  As such, it is not a functional entity, and
+used in a GStreamer pipeline.  As such, it is not a functional entity, and
 cannot do anything when placed in a pipeline.
 </para>
 
 <para>
-All GstElements have a list containing the #GstPad structure for all their
-inputs and outputs.  These can be added with gst_element_add_pad() or
-gst_element_add_ghost_pad(), and retrieved by name with
-gst_element_get_pad(), or in a list form by gst_element_get_pad_list().
+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>
-gst_element_connect() is a convenience function provided to make it
-simpler to connect pads of two elements together.
+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>
+The element object
 </para>
 
-<!-- ##### ENUM GstElementState ##### -->
+
+<!-- ##### SIGNAL GstElement::eos ##### -->
 <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.
+Signal emited when the element goes to PAUSED due to an end-of-stream
+condition.
+</para>
+
+@gstelement: the object which received the signal.
+
+<!-- ##### SIGNAL GstElement::error ##### -->
+<para>
+Is triggered whenever an error occured.
 
 </para>
 
-@GST_STATE_NONE_PENDING: The element is in the desired state.
-@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_PLAYING: means there really is data flowing through the graph.
-@GST_STATE_PAUSED: means there really is data flowing temporary stops the data flow.
+@gstelement: the object which received the signal.
+@arg1: the error message
+@arg2: 
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@:
+@: 
+
+<!-- ##### SIGNAL GstElement::found-tag ##### -->
+<para>
 
-<!-- ##### ENUM GstElementStateReturn ##### -->
+</para>
+
+@gstelement: the object which received the signal.
+@arg1: 
+@arg2: 
+
+<!-- ##### SIGNAL GstElement::new-pad ##### -->
 <para>
-This enum defines the standard return values that an element
-can return after a state change.
+Is triggered 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>
+Is triggered whenever a pad has been removed from the element.
 </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
+@gstelement: the object which received the signal.
+@arg1: The pad that was removed.
 
-<!-- ##### MACRO GST_STATE ##### -->
+<!-- ##### SIGNAL GstElement::state-change ##### -->
 <para>
-This macro returns the current state of the element.
+Is triggered whenever the state of an element changes.
 </para>
 
-@obj: Element to return state for.
+@gstelement: the object which received the signal.
+@arg1: the new state of the object
+@arg2: 
+
+<!-- ##### MACRO gst_element_get_name ##### -->
+<para>
+Gets the name of the element.
+</para>
 
+@elem: 
+@Returns: the name of the element.
 
-<!-- ##### MACRO GST_STATE_PENDING ##### -->
+
+<!-- link -->
+
+
+<!-- ##### MACRO gst_element_set_name ##### -->
 <para>
-This macro returns the currently pending state of the element.
+Sets the name of the element, getting rid of the old name if there was one.
 </para>
 
-@obj: Element to return the pending state for.
+@elem: a #GstElement to set the name of.
+@name: the new name of the element.
 
 
-<!-- ##### MACRO GST_STATE_TRANSITION ##### -->
+<!-- ##### FUNCTION gst_element_get_factory ##### -->
 <para>
-Returns the state transition this object is going through.
+
 </para>
 
-@obj: the Element to return the state transition for
+@element: 
+@Returns: 
 
 
-<!-- ##### MACRO GST_STATE_NULL_TO_READY ##### -->
+<!-- ##### FUNCTION gst_element_add_pad ##### -->
 <para>
-The Element is going from the NULL state to the READY state.
+
 </para>
 
+@element: 
+@pad: 
 
 
-<!-- ##### MACRO GST_STATE_READY_TO_PLAYING ##### -->
+<!-- ##### FUNCTION gst_element_remove_pad ##### -->
 <para>
-The Element is going from the READY state to the PLAYING state.
+
 </para>
 
+@element: 
+@pad: 
 
 
-<!-- ##### MACRO GST_STATE_PLAYING_TO_PAUSED ##### -->
+<!-- ##### FUNCTION gst_element_add_ghost_pad ##### -->
 <para>
-The Element is going from the PLAYING state to the PAUSED state.
+
 </para>
 
+@element: 
+@pad: 
+@name: 
+@Returns: 
 
 
-<!-- ##### MACRO GST_STATE_PAUSED_TO_PLAYING ##### -->
+<!-- ##### FUNCTION gst_element_remove_ghost_pad ##### -->
 <para>
-The Element is going from the PAUSED state to the PLAYING state.
+
 </para>
 
+@element: 
+@pad: 
+
+
+<!-- pad template manipulation -->
 
 
-<!-- ##### MACRO GST_STATE_PLAYING_TO_READY ##### -->
+<!-- ##### FUNCTION gst_element_get_pad ##### -->
 <para>
-The Element is going from the PLAYING state to the READY state.
+
 </para>
 
+@element: 
+@name: 
+@Returns: GList of #GstPads
 
 
-<!-- ##### MACRO GST_STATE_READY_TO_NULL ##### -->
+<!-- ##### FUNCTION gst_element_get_static_pad ##### -->
 <para>
-The Element is going from the READY state to the NULL state.
+
 </para>
 
+@element: 
+@name: 
+@Returns: 
 
 
-<!-- ##### ENUM GstElementFlags ##### -->
+<!-- ##### FUNCTION gst_element_get_request_pad ##### -->
 <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_NO_SEEK: 
-@GST_ELEMENT_NEW_LOOPFUNC: 
-@GST_ELEMENT_COTHREAD_STOPPING: 
-@GST_ELEMENT_USE_COTHREAD: 
-@GST_ELEMENT_FLAG_LAST: 
+@element: 
+@name: 
+@Returns: 
 
-<!-- ##### MACRO GST_ELEMENT_IS_THREAD_SUGGESTED ##### -->
+
+<!-- ##### FUNCTION gst_element_release_request_pad ##### -->
 <para>
-Queries whether the Element should be placed in a thread.
+
 </para>
 
-@obj: The element to query
+@element: 
+@pad: 
 
 
-<!-- ##### MACRO GST_ELEMENT_IS_COTHREAD_STOPPING ##### -->
+<!-- ##### FUNCTION gst_element_get_pad_list ##### -->
 <para>
-Queries whether the cothread holding this element needs to be stopped.
+
 </para>
 
-@obj: The element to query
+@element: 
+@Returns: 
 
 
-<!-- ##### STRUCT GstElement ##### -->
+<!-- ##### FUNCTION gst_element_get_pad_template ##### -->
 <para>
 
 </para>
 
+@element: 
+@name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gst_element_get_pad_template_list ##### -->
+<para>
+
+</para>
 
-<!-- ##### STRUCT GstElementDetails ##### -->
+@element: 
+@Returns: 
+
+
+
+<!-- scheduling -->
+
+
+<!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
 <para>
-This struct is used to define public information about the element.  It
-describes the element, mostly for the benefit of editors.
+
 </para>
 
-@longname: 
 @klass: 
-@description: 
-@version: 
-@author: 
-@copyright: 
+@templ: 
 
-<!-- ##### STRUCT GstElementFactory ##### -->
+
+<!-- ##### FUNCTION gst_element_link ##### -->
 <para>
-This factory is used when registering the element, and contains the name
-of the element, the GtkType value for it, as well as a pointer to the
-GstElementDetails struct for the element.
+
 </para>
 
-@name: 
-@type: 
-@details: 
-@padtemplates: 
-@numpadtemplates: 
+@src: 
+@dest: 
+@Returns: 
 
-<!-- ##### USER_FUNCTION GstElementLoopFunction ##### -->
+
+<!-- ##### FUNCTION gst_element_link_many ##### -->
 <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.
+@element_1: 
+@element_2: 
+@Varargs: 
+@Returns: 
+
 
+<!-- ##### FUNCTION gst_element_link_filtered ##### -->
+<para>
+
+</para>
+
+@src: 
+@dest: 
+@filtercaps: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gst_element_link_pads ##### -->
+<para>
+
+</para>
+
+@src: 
+@srcpadname: 
+@dest: 
+@destpadname: 
+@Returns: 
 
-<!-- ##### FUNCTION gst_element_new ##### -->
+
+<!-- ##### FUNCTION gst_element_link_pads_filtered ##### -->
 <para>
 
 </para>
 
+@src: 
+@srcpadname: 
+@dest: 
+@destpadname: 
+@filtercaps: 
 @Returns: 
 
 
-<!-- ##### MACRO gst_element_destroy ##### -->
+<!-- ##### FUNCTION gst_element_unlink ##### -->
 <para>
 
 </para>
 
-@element: the element to destroy
+@src: 
+@dest: 
 
 
-<!-- ##### FUNCTION gst_element_set_loop_function ##### -->
+<!-- ##### FUNCTION gst_element_unlink_many ##### -->
 <para>
 
 </para>
 
-@element: 
-@loop: 
+@element_1: 
+@element_2: 
+@Varargs: 
 
 
-<!-- ##### FUNCTION gst_element_set_name ##### -->
+<!-- ##### FUNCTION gst_element_unlink_pads ##### -->
+<para>
+
+</para>
+
+@src: 
+@srcpadname: 
+@dest: 
+@destpadname: 
+
+
+<!-- pad manipulation -->
+
+
+<!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
 <para>
 
 </para>
 
 @element: 
-@name: 
+@pad: 
+@Returns: 
 
 
-<!-- ##### FUNCTION gst_element_get_name ##### -->
+<!-- ##### FUNCTION gst_element_get_compatible_pad_filtered ##### -->
 <para>
 
 </para>
 
 @element: 
+@pad: 
+@filtercaps: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_element_set_manager ##### -->
+<!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
 <para>
 
 </para>
 
 @element: 
-@manager: 
+@compattempl: 
+@Returns: 
 
 
-<!-- ##### FUNCTION gst_element_get_manager ##### -->
+<!-- ##### FUNCTION gst_element_set_state ##### -->
 <para>
 
 </para>
 
 @element: 
+@state: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_element_add_pad ##### -->
+<!-- ##### FUNCTION gst_element_get_state ##### -->
 <para>
 
 </para>
 
 @element: 
-@pad
+@Returns
 
 
-<!-- ##### FUNCTION gst_element_get_pad ##### -->
+<!-- ##### FUNCTION gst_element_state_get_name ##### -->
+<para>
+
+</para>
+
+@state: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gst_element_wait_state_change ##### -->
 <para>
 
 </para>
 
 @element: 
-@name: 
-@Returns: GList of pads
 
 
-<!-- ##### FUNCTION gst_element_get_pad_list ##### -->
+<!-- ##### FUNCTION gst_element_set_eos ##### -->
 <para>
 
 </para>
 
 @element: 
-@Returns: 
 
 
-<!-- ##### FUNCTION gst_element_get_padtemplate_list ##### -->
+<!-- ##### FUNCTION gst_element_interrupt ##### -->
 <para>
 
 </para>
@@ -289,66 +467,65 @@ circumstances.
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_element_add_ghost_pad ##### -->
+<!-- ##### FUNCTION gst_element_yield ##### -->
 <para>
 
 </para>
 
 @element: 
-@pad: 
 
 
-<!-- ##### FUNCTION gst_element_remove_ghost_pad ##### -->
+<!-- ##### FUNCTION gst_element_release_locks ##### -->
 <para>
 
 </para>
 
 @element: 
-@pad
+@Returns
 
 
-<!-- ##### FUNCTION gst_element_connect ##### -->
+<!-- ##### FUNCTION gst_element_get_clock ##### -->
 <para>
 
 </para>
 
-@src: 
-@srcpadname: 
-@dest: 
-@destpadname: 
+@element: 
+@Returns: 
 
 
-<!-- ##### FUNCTION gst_element_disconnect ##### -->
+<!-- ##### FUNCTION gst_element_set_clock ##### -->
 <para>
 
 </para>
 
-@src: 
-@srcpadname: 
-@dest: 
-@destpadname: 
+@element: 
+@clock: 
 
 
-<!-- ##### FUNCTION gst_element_set_state ##### -->
+<!-- ##### FUNCTION gst_element_clock_wait ##### -->
 <para>
 
 </para>
 
 @element: 
-@state: 
+@id: 
+@jitter: 
 @Returns: 
+<!-- # Unused Parameters # -->
+@clock: 
+@time: 
 
 
-<!-- ##### FUNCTION gst_element_error ##### -->
+<!-- ##### FUNCTION gst_element_provides_clock ##### -->
 <para>
 
 </para>
 
 @element: 
-@error
+@Returns
 
 
-<!-- ##### FUNCTION gst_element_get_factory ##### -->
+<!-- ##### FUNCTION gst_element_requires_clock ##### -->
 <para>
 
 </para>
@@ -357,198 +534,494 @@ circumstances.
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_element_signal_eos ##### -->
+<!-- ##### FUNCTION gst_element_set_index ##### -->
 <para>
 
 </para>
 
 @element: 
+@index: 
 
 
-<!-- ##### FUNCTION gst_element_save_thyself ##### -->
+<!-- ##### FUNCTION gst_element_get_index ##### -->
 <para>
 
 </para>
 
 @element: 
-@parent: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_element_load_thyself ##### -->
+<!-- ##### FUNCTION gst_element_is_indexable ##### -->
 <para>
 
 </para>
 
-@parent: 
-@elements: 
+@element: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_elementfactory_new ##### -->
+<!-- ##### FUNCTION gst_element_set_loop_function ##### -->
 <para>
 
 </para>
 
-@name: 
-@type: 
-@details: 
+@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_elementfactory_destroy ##### -->
+<!-- ##### FUNCTION gst_element_set_scheduler ##### -->
 <para>
 
 </para>
 
-@elementfactory: 
+@element: 
+@sched: 
 
 
-<!-- ##### FUNCTION gst_elementfactory_add_padtemplate ##### -->
+<!-- ##### 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>
 
-@elementfactory: 
-@temp: 
-<!-- # Unused Parameters # -->
-@pad: 
+@elem: a #GstElement to set the parent of.
+@parent:  the new #GstObject parent of the object.
 
 
-<!-- ##### FUNCTION gst_elementfactory_find ##### -->
+<!-- ##### FUNCTION gst_element_get_managing_bin ##### -->
 <para>
 
 </para>
 
-@name
+@element
 @Returns: 
 
+<!-- clocking -->
+
 
-<!-- ##### FUNCTION gst_elementfactory_get_list ##### -->
+<!-- ##### 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>
 
-@Returns: 
+@element: The element
 
 
-<!-- ##### FUNCTION gst_elementfactory_can_src_caps ##### -->
+<!-- ##### FUNCTION gst_element_disable_threadsafe_properties ##### -->
 <para>
 
 </para>
 
-@factory: 
-@caps: 
-@Returns: 
+@element: 
 
 
-<!-- ##### FUNCTION gst_elementfactory_can_sink_caps ##### -->
+<!-- ##### FUNCTION gst_element_enable_threadsafe_properties ##### -->
 <para>
 
 </para>
 
-@factory: 
-@caps: 
-@Returns: 
+@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>
 
-<!-- ##### FUNCTION gst_elementfactory_can_src_caps_list ##### -->
+@element: 
+@first_property_name: 
+@Varargs: 
+
+
+<!-- ##### FUNCTION gst_element_set_pending_properties ##### -->
 <para>
 
 </para>
 
-@factory: 
-@caps: 
+@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_elementfactory_can_sink_caps_list ##### -->
+<!-- ##### FUNCTION gst_element_send_event ##### -->
 <para>
 
 </para>
 
-@factory
-@caps
+@element
+@event
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_elementfactory_create ##### -->
+<!-- ##### FUNCTION gst_element_get_event_masks ##### -->
 <para>
 
 </para>
 
-@factory: 
-@name: 
+@element: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_elementfactory_make ##### -->
+<!-- ##### FUNCTION gst_element_get_formats ##### -->
 <para>
 
 </para>
 
-@factoryname: 
-@name: 
+@element: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_elementfactory_save_thyself ##### -->
+<!-- ##### FUNCTION gst_element_get_query_types ##### -->
 <para>
 
 </para>
 
-@factory: 
-@parent: 
+@element: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_elementfactory_load_thyself ##### -->
+<!-- ##### FUNCTION gst_element_convert ##### -->
 <para>
 
 </para>
 
-@parent: 
+@element: 
+@src_format: 
+@src_value: 
+@dest_format: 
+@dest_value: 
 @Returns: 
 
 
-<!-- ##### SIGNAL GstElement::state-change ##### -->
+<!-- ##### MACRO gst_element_default_deep_notify ##### -->
 <para>
-Is trigered whenever the state of an element changes
+The default deep notify handler that prints out the property change
+notifications to stdout.
 </para>
 
-@gstelement: the object which received the signal.
-@arg1: the new state of the object
 
-<!-- ##### SIGNAL GstElement::new-pad ##### -->
+
+<!-- ##### FUNCTION gst_element_default_error ##### -->
 <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
+@object: 
+@orig: 
+@error: 
+@debug: 
 
-<!-- ##### SIGNAL GstElement::new-ghost-pad ##### -->
+
+<!-- ##### 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.
 
-Is trigered whenever a new ghost pad is added to an element
 </para>
 
-@gstelement: the object which received the signal.
-@arg1: the new ghost pad that was added
+@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.
 
-<!-- ##### SIGNAL GstElement::error ##### -->
+<!-- ##### ENUM GstElementStateReturn ##### -->
 <para>
-Is trigered whenever an error occured
+This enum defines the standard return values that an element
+can return after a state change.
 
 </para>
 
-@gstelement: the object which received the signal.
-@arg1: the error message
+@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
 
-<!-- ##### SIGNAL GstElement::eos ##### -->
+<!-- ##### 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>
 
-@gstelement: the object which received the signal.
+@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_LOCKED_STATE: 
+@GST_ELEMENT_IN_ERROR: 
+@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_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
+
+
+<!-- ##### MACRO GST_ELEMENT_EVENT_MASK_FUNCTION ##### -->
+<para>
+A helper macro to create a mask function
+</para>
+
+@functionname: the name of the mask function
+@...: Masks
+
+
+<!-- ##### MACRO GST_ELEMENT_FORMATS_FUNCTION ##### -->
+<para>
+Halper macro to create element format functions
+</para>
+
+@functionname: The function name
+@...: formats
+
+
+<!-- ##### MACRO GST_ELEMENT_QUERY_TYPE_FUNCTION ##### -->
+<para>
+Helper macro to create query type functions
+</para>
+
+@functionname: The function name
+@...: list of query types.
+