summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 6570aad)
raw | patch | inline | side by side (parent: 6570aad)
author | Stefan Kost <ensonic@users.sourceforge.net> | |
Fri, 23 Sep 2005 14:31:21 +0000 (14:31 +0000) | ||
committer | Stefan Kost <ensonic@users.sourceforge.net> | |
Fri, 23 Sep 2005 14:31:21 +0000 (14:31 +0000) |
Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* docs/gst/tmpl/.cvsignore:
* docs/gst/tmpl/gstelement.sgml:
* docs/gst/tmpl/gstinfo.sgml:
* docs/gst/tmpl/gstobject.sgml:
* gst/gstelement.c:
* gst/gstelement.h:
* gst/gstinfo.c:
* gst/gstinfo.h:
* gst/gstobject.c: (gst_object_class_init):
* gst/gstobject.h:
inlined 3 more biiiig doc files and added some missing docs on the fly
* docs/gst/gstreamer-sections.txt:
* docs/gst/tmpl/.cvsignore:
* docs/gst/tmpl/gstelement.sgml:
* docs/gst/tmpl/gstinfo.sgml:
* docs/gst/tmpl/gstobject.sgml:
* gst/gstelement.c:
* gst/gstelement.h:
* gst/gstinfo.c:
* gst/gstinfo.h:
* gst/gstobject.c: (gst_object_class_init):
* gst/gstobject.h:
inlined 3 more biiiig doc files and added some missing docs on the fly
13 files changed:
ChangeLog | patch | blob | history | |
common | patch | blob | history | |
docs/gst/gstreamer-sections.txt | patch | blob | history | |
docs/gst/tmpl/.gitignore | patch | blob | history | |
docs/gst/tmpl/gstelement.sgml | [deleted file] | patch | blob | history |
docs/gst/tmpl/gstinfo.sgml | [deleted file] | patch | blob | history |
docs/gst/tmpl/gstobject.sgml | [deleted file] | patch | blob | history |
gst/gstelement.c | patch | blob | history | |
gst/gstelement.h | patch | blob | history | |
gst/gstinfo.c | patch | blob | history | |
gst/gstinfo.h | patch | blob | history | |
gst/gstobject.c | patch | blob | history | |
gst/gstobject.h | patch | blob | history |
diff --git a/ChangeLog b/ChangeLog
index d98a90b0bed08072c9b767e9bf46e25237001ba1..feda752a5527231bb424b65a3e7e3075282845f7 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
+2005-09-23 Stefan Kost <ensonic@users.sf.net>
+
+ * docs/gst/gstreamer-sections.txt:
+ * docs/gst/tmpl/.cvsignore:
+ * docs/gst/tmpl/gstelement.sgml:
+ * docs/gst/tmpl/gstinfo.sgml:
+ * docs/gst/tmpl/gstobject.sgml:
+ * gst/gstelement.c:
+ * gst/gstelement.h:
+ * gst/gstinfo.c:
+ * gst/gstinfo.h:
+ * gst/gstobject.c: (gst_object_class_init):
+ * gst/gstobject.h:
+ inlined 3 more biiiig doc files and added some missing docs on the fly
+
2005-09-23 Thomas Vander Stichele <thomas at apestaart dot org>
* check/gst/.cvsignore:
index cd4da6a319d9f92d28f7b8a3b412577e6de50b64..345fd9851051274dd758a19bbe33dbb561b4d303 160000 (submodule)
--- a/common
+++ b/common
-Subproject commit cd4da6a319d9f92d28f7b8a3b412577e6de50b64
+Subproject commit 345fd9851051274dd758a19bbe33dbb561b4d303
index e28a3d3b1bf55957755beb4716550e58a637ea6d..cdfbca3b4be56930a13ec74dcb444fa790580df5 100644 (file)
GST_STATE_WAIT
GST_ELEMENT_NAME
GST_ELEMENT_PARENT
+GST_ELEMENT_BUS
GST_ELEMENT_CLOCK
GST_ELEMENT_PADS
GST_ELEMENT_ERROR
-GST_ELEMENT_BUS
GST_ELEMENT_WARNING
GST_ELEMENT_IS_LOCKED_STATE
index 158e81ec4de5dfb1cb4b310b83bf12ff9911fc9e..acf2fa0e7a0b9fc4358b1ed0d0de26895a12641b 100644 (file)
--- a/docs/gst/tmpl/.gitignore
+++ b/docs/gst/tmpl/.gitignore
gstcollectpads.sgml
gstcompat.sgml
gstconfig.sgml
+gstelement.sgml
gstelementdetails.sgml
gstelementfactory.sgml
gstenumtypes.sgml
gstimplementsinterface.sgml
gstindex.sgml
gstindexfactory.sgml
+gstinfo.sgml
gstiterator.sgml
gstmacros.sgml
gstmemchunk.sgml
gstmessage.sgml
gstminiobject.sgml
+gstobject.sgml
gstparse.sgml
gstpluginfeature.sgml
gstpushsrc.sgml
diff --git a/docs/gst/tmpl/gstelement.sgml b/docs/gst/tmpl/gstelement.sgml
+++ /dev/null
@@ -1,1057 +0,0 @@
-<!-- ##### 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 #GstState). 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 #GstState, 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 -->
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GstElement ##### -->
-<para>
-
-</para>
-
-@state_lock:
-@state_cond:
-@current_state:
-@pending_state:
-@final_state:
-@state_error:
-@no_preroll:
-@bus:
-@clock:
-@base_time:
-@numpads:
-@pads:
-@numsrcpads:
-@srcpads:
-@numsinkpads:
-@sinkpads:
-@pads_cookie:
-
-<!-- ##### SIGNAL GstElement::no-more-pads ##### -->
-<para>
-
-</para>
-
-@gstelement: the object which received the signal.
-
-<!-- ##### SIGNAL GstElement::pad-added ##### -->
-<para>
-
-</para>
-
-@gstelement: the object which received the signal.
-@arg1:
-
-<!-- ##### SIGNAL GstElement::pad-removed ##### -->
-<para>
-
-</para>
-
-@gstelement: the object which received the signal.
-@arg1:
-
-<!-- ##### SIGNAL GstElement::state-changed ##### -->
-<para>
-
-</para>
-
-@gstelement: the object which received the signal.
-@arg1:
-@arg2:
-
-<!-- ##### STRUCT GstElementClass ##### -->
-<para>
-
-</para>
-
-@parent_class:
-@details:
-@elementfactory:
-@padtemplates:
-@numpadtemplates:
-@pad_templ_cookie:
-@request_new_pad:
-@release_pad:
-@get_state:
-@change_state:
-@set_bus:
-@get_clock:
-@set_clock:
-@get_index:
-@set_index:
-@send_event:
-@get_query_types:
-@query:
-
-<!-- ##### ENUM GstElementFlags ##### -->
-<para>
-This enum defines the standard flags that an element may have.
-</para>
-
-@GST_ELEMENT_LOCKED_STATE:
-@GST_ELEMENT_IS_SINK:
-@GST_ELEMENT_UNPARENTING:
-@GST_ELEMENT_FLAG_LAST:
-
-<!-- ##### ENUM GstState ##### -->
-<para>
-
-</para>
-
-@GST_STATE_VOID_PENDING:
-@GST_STATE_NULL:
-@GST_STATE_READY:
-@GST_STATE_PAUSED:
-@GST_STATE_PLAYING:
-
-<!-- ##### ENUM GstStateChange ##### -->
-<para>
-
-</para>
-
-@GST_STATE_CHANGE_NULL_TO_READY:
-@GST_STATE_CHANGE_READY_TO_PAUSED:
-@GST_STATE_CHANGE_PAUSED_TO_PLAYING:
-@GST_STATE_CHANGE_PLAYING_TO_PAUSED:
-@GST_STATE_CHANGE_PAUSED_TO_READY:
-@GST_STATE_CHANGE_READY_TO_NULL:
-
-<!-- ##### ENUM GstStateChangeReturn ##### -->
-<para>
-
-</para>
-
-@GST_STATE_CHANGE_FAILURE:
-@GST_STATE_CHANGE_SUCCESS:
-@GST_STATE_CHANGE_ASYNC:
-@GST_STATE_CHANGE_NO_PREROLL:
-
-<!-- ##### 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_CHANGE ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_STATE_BROADCAST ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### MACRO GST_STATE_ERROR ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_STATE_FINAL ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_STATE_GET_COND ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### MACRO GST_STATE_GET_LOCK ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### MACRO GST_STATE_LOCK ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### MACRO GST_STATE_NO_PREROLL ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_STATE_SIGNAL ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### MACRO GST_STATE_TIMED_WAIT ##### -->
-<para>
-
-</para>
-
-@elem:
-@timeval:
-
-
-<!-- ##### MACRO GST_STATE_TRYLOCK ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### MACRO GST_STATE_UNLOCK ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### MACRO GST_STATE_WAIT ##### -->
-<para>
-
-</para>
-
-@elem:
-
-
-<!-- ##### 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:
-
-
-<!-- ##### MACRO GST_ELEMENT_BUS ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_ELEMENT_WARNING ##### -->
-<para>
-
-</para>
-
-@el:
-@domain:
-@code:
-@text:
-@debug:
-
-
-<!-- ##### MACRO GST_ELEMENT_IS_LOCKED_STATE ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### FUNCTION gst_element_abort_preroll ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_abort_state ##### -->
-<para>
-
-</para>
-
-@element:
-
-
-<!-- ##### FUNCTION gst_element_add_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@pad:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_class_add_pad_template ##### -->
-<para>
-
-</para>
-
-@klass:
-@templ:
-
-
-<!-- ##### 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_class_install_std_props ##### -->
-<para>
-
-</para>
-
-@klass:
-@first_name:
-@Varargs:
-
-
-<!-- ##### FUNCTION gst_element_class_set_details ##### -->
-<para>
-
-</para>
-
-@klass:
-@details:
-
-
-<!-- ##### FUNCTION gst_element_commit_state ##### -->
-<para>
-
-</para>
-
-@element:
-
-
-<!-- ##### FUNCTION gst_element_create_all_pads ##### -->
-<para>
-
-</para>
-
-@element:
-
-
-<!-- ##### FUNCTION gst_element_factory_can_sink_caps ##### -->
-<para>
-
-</para>
-
-@factory:
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_factory_can_src_caps ##### -->
-<para>
-
-</para>
-
-@factory:
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_factory_get_static_pad_templates ##### -->
-<para>
-
-</para>
-
-@factory:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_finish_preroll ##### -->
-<para>
-
-</para>
-
-@element:
-@pad:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_found_tags ##### -->
-<para>
-
-</para>
-
-@element:
-@list:
-
-
-<!-- ##### FUNCTION gst_element_found_tags_for_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@pad:
-@list:
-
-
-<!-- ##### FUNCTION gst_element_get_base_time ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_bus ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_clock ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_compatible_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@pad:
-@caps:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_compatible_pad_template ##### -->
-<para>
-
-</para>
-
-@element:
-@compattempl:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_factory ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_index ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### MACRO gst_element_get_name ##### -->
-<para>
-Gets the name of the element.
-</para>
-
-@elem:
-@Returns: the name of the element.
-
-
-<!-- link -->
-
-
-<!-- ##### FUNCTION gst_element_get_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@name:
-@Returns: GList of #GstPads
-
-
-<!-- ##### 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.
-
-
-<!-- ##### FUNCTION gst_element_get_query_types ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_request_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@name:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_state ##### -->
-<para>
-
-</para>
-
-@element:
-@state:
-@pending:
-@timeout:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_get_static_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@name:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_is_indexable ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_is_locked_state ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_iterate_pads ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_iterate_sink_pads ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_iterate_src_pads ##### -->
-<para>
-
-</para>
-
-@element:
-@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_link_filtered ##### -->
-<para>
-
-</para>
-
-@src:
-@dest:
-@filter:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_link_pads ##### -->
-<para>
-
-</para>
-
-@src:
-@srcpadname:
-@dest:
-@destpadname:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_link_pads_filtered ##### -->
-<para>
-
-</para>
-
-@src:
-@srcpadname:
-@dest:
-@destpadname:
-@filter:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_lost_state ##### -->
-<para>
-
-</para>
-
-@element:
-
-
-<!-- ##### FUNCTION gst_element_message_full ##### -->
-<para>
-
-</para>
-
-@element:
-@type:
-@domain:
-@code:
-@text:
-@debug:
-@file:
-@function:
-@line:
-
-
-<!-- ##### FUNCTION gst_element_no_more_pads ##### -->
-<para>
-
-</para>
-
-@element:
-
-
-<!-- ##### FUNCTION gst_element_post_message ##### -->
-<para>
-
-</para>
-
-@element:
-@message:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_provides_clock ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_query ##### -->
-<para>
-
-</para>
-
-@element:
-@query:
-@Returns:
-<!-- # Unused Parameters # -->
-@type:
-@format:
-@value:
-
-
-<!-- ##### FUNCTION gst_element_query_convert ##### -->
-<para>
-
-</para>
-
-@element:
-@src_format:
-@src_val:
-@dest_fmt:
-@dest_val:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_query_position ##### -->
-<para>
-
-</para>
-
-@element:
-@format:
-@cur:
-@end:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_release_request_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@pad:
-
-
-<!-- ##### FUNCTION gst_element_remove_pad ##### -->
-<para>
-
-</para>
-
-@element:
-@pad:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_requires_clock ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_seek ##### -->
-<para>
-
-</para>
-
-@element:
-@rate:
-@format:
-@flags:
-@cur_type:
-@cur:
-@stop_type:
-@stop:
-@Returns:
-<!-- # Unused Parameters # -->
-@seek_type:
-@offset:
-
-
-<!-- ##### FUNCTION gst_element_send_event ##### -->
-<para>
-
-</para>
-
-@element:
-@event:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_set_base_time ##### -->
-<para>
-
-</para>
-
-@element:
-@time:
-
-
-<!-- ##### FUNCTION gst_element_set_bus ##### -->
-<para>
-
-</para>
-
-@element:
-@bus:
-
-
-<!-- ##### FUNCTION gst_element_set_clock ##### -->
-<para>
-
-</para>
-
-@element:
-@clock:
-
-
-<!-- ##### FUNCTION gst_element_set_index ##### -->
-<para>
-
-</para>
-
-@element:
-@index:
-
-
-<!-- ##### FUNCTION gst_element_set_locked_state ##### -->
-<para>
-
-</para>
-
-@element:
-@locked_state:
-@Returns:
-
-
-<!-- ##### 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_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_set_state ##### -->
-<para>
-
-</para>
-
-@element:
-@state:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_set_state_async ##### -->
-<para>
-
-</para>
-
-@element:
-@state:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_state_get_name ##### -->
-<para>
-
-</para>
-
-@state:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_sync_state_with_parent ##### -->
-<para>
-
-</para>
-
-@element:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_element_unlink ##### -->
-<para>
-
-</para>
-
-@src:
-@dest:
-
-
-<!-- ##### FUNCTION gst_element_unlink_many ##### -->
-<para>
-
-</para>
-
-@element_1:
-@element_2:
-@Varargs:
-
-
-<!-- ##### FUNCTION gst_element_unlink_pads ##### -->
-<para>
-
-</para>
-
-@src:
-@srcpadname:
-@dest:
-@destpadname:
-
-
-<!-- pad manipulation -->
-
-
diff --git a/docs/gst/tmpl/gstinfo.sgml b/docs/gst/tmpl/gstinfo.sgml
+++ /dev/null
@@ -1,742 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GstInfo
-
-<!-- ##### SECTION Short_Description ##### -->
-Debugging and logging
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-This file describes the debugging subsystem. The debugging subsystem works
-only after GStreamer was initilized - for example by calling #gst_init.
-</para>
-
-<para>
-The debugging subsystem is used to send informational strings to the debugging
-developer. Each messages has some properties attached to it. These properties
-are the debugging category, the severity (called "level" here) and an obtional
-#GObject it belongs to. Each of these messages is sent to all registered
-debugging handlers, which then handle the messages. GStreamer attaches a
-default handler on startup, which outputs requested messages to stderr.
-</para>
-
-<para>
-Messages are output by using shortcut macros like #GST_DEBUG,
-#GST_CAT_ERROR_OBJECT or similar. These all expand to calling #gst_debug_log
-with the right parameters.
-The only thing a developer will probably want to do is define his own
-categories. This is easily done with 3 lines. At the top of your code, declare
-the variables and set the default category.
-<informalexample>
-<programlisting>
-GST_DEBUG_CATEGORY (my_category); /* define category */
-&hash;define GST_CAT_DEFAULT my_category /* set as default */
-</programlisting>
-</informalexample>
-After that you only need to initialize the category.
-<informalexample>
-<programlisting>
-GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
-</programlisting>
-</informalexample>
-Initialization must be done before the category is used first. Plugins do this
-in their plugin_init function, libraries and applications should do that
-during their initialization.
-</para>
-
-<para>
-The whole debugging subsystem can be disabled at build time with passing the
---disable-gst-debug switch to configure. If this is done, every function, macro
-and even structs described in this file evaluate to default values or nothing
-at all. So don't take addresses of these functions or use other tricks.
-If you must do that for some reason, there is still an option. If the debugging
-subsystem was compiled out, #GST_DISABLE_GST_DEBUG is defined in <gst/gst.h>,
-so you can check that before doing your trick.
-Disabling the debugging subsystem will give you a slight (read: unnoticable)
-speed increase and will reduce the size of your compiled code. The GStreamer
-library itself becomes around 10% smaller.
-</para>
-
-<para>
-Please note that there are naming conventions for the names of debugging
-categories. These are explained at GST_DEBUG_CATEGORY_INIT().
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-<link linkend="gstreamer-gstconfig">configuration</link>,
-<link linkend="gstreamer-gst">initialization</link> for command line parameters
-and environment variables that affect the debugging output.
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### ENUM GstDebugLevel ##### -->
-<para>
-The level defines the importance of a debugging message. The more important a
-message is, the greater the probability that the debugging system outputs it.
-</para>
-
-@GST_LEVEL_NONE: No debugging level specified or desired. Used to deactivate
-debugging output.
-@GST_LEVEL_ERROR: Error messages are to be used only when an error occured
-that stops the application from keeping working correctly.
-An examples is gst_element_error, which outputs a message with this priority.
-It does not mean that the application is terminating as with g_errror.
-@GST_LEVEL_WARNING: Warning messages are to inform about abnormal behaviour
-that could lead to problems or weird behaviour later on. An example of this
-would be clocking issues ("your computer is pretty slow") or broken input
-data ("Can't synchronize to stream.")
-@GST_LEVEL_INFO: Informational messages should be used to keep the developer
-updated about what is happening.
-Examples where this should be used are when a typefind function has
-successfully determined the type of the stream or when an mp3 plugin detects
-the format to be used. ("This file has mono sound.")
-@GST_LEVEL_DEBUG: Debugging messages should be used when something common
-happens that is not the expected default behavior.
-An example would be notifications about state changes or receiving/sending of
-events.
-@GST_LEVEL_LOG: Log messages are messages that are very common but might be
-useful to know. As a rule of thumb a pipeline that is iterating as expected
-should never output anzthing else but LOG messages.
-Examples for this are referencing/dereferencing of objects or cothread switches.
-@GST_LEVEL_COUNT: The number of defined debugging levels.
-
-<!-- ##### MACRO GST_LEVEL_DEFAULT ##### -->
-<para>
-Defines the default debugging level to be used with GStreamer. It is
-normally set to #GST_LEVEL_ERROR so only errors are printed. Developer
-builds may chose to override that though.
-You can use this as an argument to gst_debug_set_default_threshold() to
-reset the debugging output to default behaviour.
-</para>
-
-
-
-<!-- ##### ENUM GstDebugColorFlags ##### -->
-<para>
-These are some terminal-oriented flags you can use when creating your debugging
-categories to make them stand out in debugging output.
-</para>
-
-@GST_DEBUG_FG_BLACK: Use black as foreground color.
-@GST_DEBUG_FG_RED: Use red as foreground color.
-@GST_DEBUG_FG_GREEN: Use green as foreground color.
-@GST_DEBUG_FG_YELLOW: Use yellow as foreground color.
-@GST_DEBUG_FG_BLUE: Use blue as foreground color.
-@GST_DEBUG_FG_MAGENTA: Use magenta as foreground color.
-@GST_DEBUG_FG_CYAN: Use cyan as foreground color.
-@GST_DEBUG_FG_WHITE: Use white as foreground color.
-@GST_DEBUG_BG_BLACK: Use black as background color.
-@GST_DEBUG_BG_RED: Use red as background color.
-@GST_DEBUG_BG_GREEN: Use green as background color.
-@GST_DEBUG_BG_YELLOW: Use yellow as background color.
-@GST_DEBUG_BG_BLUE: Use blue as background color.
-@GST_DEBUG_BG_MAGENTA: Use magenta as background color.
-@GST_DEBUG_BG_CYAN: Use cyan as background color.
-@GST_DEBUG_BG_WHITE: Use white as background color.
-@GST_DEBUG_BOLD: Make the output bold.
-@GST_DEBUG_UNDERLINE: Underline the output.
-
-<!-- ##### STRUCT GstDebugCategory ##### -->
-<para>
-This is the struct that describes the categories. Once initialized with
-#GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.
-</para>
-
-
-<!-- ##### MACRO GST_STR_NULL ##### -->
-<para>
-Macro to use when a string must not be NULL, but may be NULL. If the string is
-NULL, "(NULL)" is printed instead.
-In GStreamer printf string arguments may not be NULL, because on some platforms
-(ie Solaris) the libc crashes in that case. This includes debugging strings.
-</para>
-
-@str: The string to check.
-@Returns: A string that is guaranteed to be not NULL.
-
-
-<!-- ##### MACRO GST_DEBUG_PAD_NAME ##### -->
-<para>
-Evaluates to 2 strings, that describe the pad. Often used in debugging
-statements.
-</para>
-
-@pad: The pad to debug.
-
-
-<!-- ##### MACRO GST_FUNCTION ##### -->
-<para>
-This macro should evaluate to the name of the current function and be should
-be defined when configuring your project, as it is compiler dependant. If it
-is not defined, some default value is used. It is used to provide debugging
-output with the function name of the message.
-</para>
-
-
-
-<!-- ##### STRUCT GstDebugMessage ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### USER_FUNCTION GstDebugFuncPtr ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### USER_FUNCTION GstLogFunction ##### -->
-<para>
-
-</para>
-
-@category:
-@level:
-@file:
-@function:
-@line:
-@object:
-@message:
-@data:
-
-
-<!-- ##### FUNCTION gst_debug_log ##### -->
-<para>
-
-</para>
-
-@category:
-@level:
-@file:
-@function:
-@line:
-@object:
-@format:
-@Varargs:
-
-
-<!-- ##### FUNCTION gst_debug_log_valist ##### -->
-<para>
-
-</para>
-
-@category:
-@level:
-@file:
-@function:
-@line:
-@object:
-@format:
-@args:
-
-
-<!-- ##### FUNCTION gst_debug_message_get ##### -->
-<para>
-
-</para>
-
-@message:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_log_default ##### -->
-<para>
-
-</para>
-
-@category:
-@level:
-@file:
-@function:
-@line:
-@object:
-@message:
-@unused:
-
-
-<!-- ##### FUNCTION gst_debug_level_get_name ##### -->
-<para>
-
-</para>
-
-@level:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_add_log_function ##### -->
-<para>
-
-</para>
-
-@func:
-@data:
-
-
-<!-- ##### FUNCTION gst_debug_remove_log_function ##### -->
-<para>
-
-</para>
-
-@func:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_remove_log_function_by_data ##### -->
-<para>
-
-</para>
-
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_set_active ##### -->
-<para>
-
-</para>
-
-@active:
-
-
-<!-- ##### FUNCTION gst_debug_is_active ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_set_colored ##### -->
-<para>
-
-</para>
-
-@colored:
-
-
-<!-- ##### FUNCTION gst_debug_is_colored ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_set_default_threshold ##### -->
-<para>
-
-</para>
-
-@level:
-
-
-<!-- ##### FUNCTION gst_debug_get_default_threshold ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_set_threshold_for_name ##### -->
-<para>
-
-</para>
-
-@name:
-@level:
-
-
-<!-- ##### FUNCTION gst_debug_unset_threshold_for_name ##### -->
-<para>
-
-</para>
-
-@name:
-
-
-<!-- ##### MACRO GST_DEBUG_CATEGORY ##### -->
-<para>
-
-</para>
-
-@cat:
-
-
-<!-- ##### MACRO GST_DEBUG_CATEGORY_EXTERN ##### -->
-<para>
-
-</para>
-
-@cat:
-
-
-<!-- ##### MACRO GST_DEBUG_CATEGORY_STATIC ##### -->
-<para>
-
-</para>
-
-@cat:
-
-
-<!-- ##### MACRO GST_DEBUG_CATEGORY_INIT ##### -->
-<para>
-
-</para>
-
-@cat:
-@name:
-@color:
-@description:
-
-
-<!-- ##### FUNCTION gst_debug_category_free ##### -->
-<para>
-
-</para>
-
-@category:
-
-
-<!-- ##### FUNCTION gst_debug_category_set_threshold ##### -->
-<para>
-
-</para>
-
-@category:
-@level:
-
-
-<!-- ##### FUNCTION gst_debug_category_reset_threshold ##### -->
-<para>
-
-</para>
-
-@category:
-
-
-<!-- ##### FUNCTION gst_debug_category_get_threshold ##### -->
-<para>
-
-</para>
-
-@category:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_category_get_name ##### -->
-<para>
-
-</para>
-
-@category:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_category_get_color ##### -->
-<para>
-
-</para>
-
-@category:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_category_get_description ##### -->
-<para>
-
-</para>
-
-@category:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_get_all_categories ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-
-<!-- ##### FUNCTION gst_debug_construct_term_color ##### -->
-<para>
-
-</para>
-
-@colorinfo:
-@Returns:
-
-
-<!-- ##### MACRO GST_CAT_DEFAULT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO GST_CAT_LEVEL_LOG ##### -->
-<para>
-GST_CAT_LEVEL_LOG:
-Outputs a debugging message. This is the most general macro for outputting
-debugging messages. You will probably want to use one of the ones described
-below.
-</para>
-
-@cat: category to use
-@level: the severity of the message
-@object: the #GObject the message belongs to or NULL if none
-@...: A printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_ERROR_OBJECT ##### -->
-<para>
-Output an error message belonging to the given object in the given category.
-</para>
-
-@cat: category to use
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_WARNING_OBJECT ##### -->
-<para>
-Output a warning message belonging to the given object in the given category.
-</para>
-
-@cat: category to use
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_INFO_OBJECT ##### -->
-<para>
-Output an informational message belonging to the given object in the given
-category.
-</para>
-
-@cat: category to use
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_DEBUG_OBJECT ##### -->
-<para>
-Output an debugging message belonging to the given object in the given category.
-</para>
-
-@cat: category to use
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_LOG_OBJECT ##### -->
-<para>
-Output an logging message belonging to the given object in the given category.
-</para>
-
-@cat: category to use
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_ERROR ##### -->
-<para>
-Output an error message in the given category.
-</para>
-
-@cat: category to use
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_WARNING ##### -->
-<para>
-Output a warning message in the given category.
-</para>
-
-@cat: category to use
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_INFO ##### -->
-<para>
-Output an informational message in the given category.
-</para>
-
-@cat: category to use
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_DEBUG ##### -->
-<para>
-Output a debuggign message in the given category.
-</para>
-
-@cat: category to use
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_CAT_LOG ##### -->
-<para>
-Output a logging message in the given category.
-</para>
-
-@cat: category to use
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_ERROR_OBJECT ##### -->
-<para>
-Output an error message belonging to the given object in the default category.
-</para>
-
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_WARNING_OBJECT ##### -->
-<para>
-Output a warning message belonging to the given object in the default category.
-</para>
-
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_INFO_OBJECT ##### -->
-<para>
-Output an informational message belonging to the given object in the default
-category.
-</para>
-
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_DEBUG_OBJECT ##### -->
-<para>
-Output a debugging message belonging to the given object in the default
-category.
-</para>
-
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_LOG_OBJECT ##### -->
-<para>
-Output a logging message belonging to the given object in the default category.
-</para>
-
-@obj: the #GObject the message belongs to
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_ERROR ##### -->
-<para>
-Output an error message in the default category.
-</para>
-
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_WARNING ##### -->
-<para>
-Output a warning message in the default category.
-</para>
-
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_INFO ##### -->
-<para>
-Output an informational message in the default category.
-</para>
-
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_DEBUG ##### -->
-<para>
-Output a debugging message in the default category.
-</para>
-
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_LOG ##### -->
-<para>
-Output a logging message in the default category.
-</para>
-
-@...: printf-style message to output
-
-
-<!-- ##### MACRO GST_DEBUG_FUNCPTR ##### -->
-<para>
-Register a pointer to a function with its name, so it can later be used by
-GST_DEBUG_FUNCPTR_NAME().
-</para>
-
-@ptr: The function to register
-Returns: The ptr to the function.
-
-
-<!-- ##### MACRO GST_DEBUG_FUNCPTR_NAME ##### -->
-<para>
-Retrieves the name of the function, if it was previously registered with
-GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer.
-<note>
-<para>
-Make sure you free the string after use.
-</para>
-</note>
-</para>
-
-@ptr: pointer to the function
-Returns: The name of the function
-
-
-<!-- ##### MACRO gst_debug_set_log_function ##### -->
-<para>
-
-</para>
-
-@func:
-@data:
-
-
-<!-- ##### MACRO gst_debug_reset_log_function ##### -->
-<para>
-
-</para>
-
-@void:
-
-
-<!-- ##### FUNCTION gst_debug_print_stack_trace ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO GST_TIME_FORMAT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO GST_TIME_ARGS ##### -->
-<para>
-
-</para>
-
-@t:
-
-
diff --git a/docs/gst/tmpl/gstobject.sgml b/docs/gst/tmpl/gstobject.sgml
+++ /dev/null
@@ -1,464 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GstObject
-
-<!-- ##### SECTION Short_Description ##### -->
-Base class for the GStreamer object hierarchy
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-GstObject provides a root for the object hierarchy tree filed in by the
-GST library. It is currently a thin wrapper on top of
-<classname>GObject</classname>. It is an abstract class that is not
-very usable on its own.
-</para>
-
-<para>
-GstObject gives us basic refcounting, parenting functionality and locking.
-Most of the function are just extended for special gstreamer needs and can be
-found under the same name in the base class of GstObject which is GObject
-(e.g. g_object_ref becomes gst_object_ref).
-</para>
-
-<para>
-The most interesting difference between GstObject and GObject is the "floating"
-reference count. A GObject is created with a reference count of 1, owned by the
-creator of the GObject. (The owner of a reference is the code section that has
-the right to call gst_object_unref() in order to remove that reference.)
-A GstObject is created with a reference count of 1 also, but it isn't owned by
-anyone; calling gst_object_unref() on the newly-created GtkObject is incorrect.
-Instead, the initial reference count of a GstObject is "floating". The floating
-reference can be removed by anyone at any time, by calling gst_object_sink().
-gst_object_sink() does nothing if an object is already sunk (has no floating
-reference).
-</para>
-<para>
-When you add a GstElement to its parent container, the parent container will do
-this:
-<programlisting>
- gst_object_ref (GST_OBJECT (child_element));
- gst_object_sink (GST_OBJECT (child_element));
-</programlisting>
-This means that the container now owns a reference to the child element (since
-it called gst_object_ref()), and the child element has no floating reference.
-</para>
-<para>
-The purpose of the floating reference is to keep the child element alive until
-you add it to a parent container:
-<programlisting>
- element = gst_element_factory_make (factoryname, name);
- /* element has one floating reference to keep it alive */
- gtk_bin_add (GTK_BIN (bin), element);
- /* element has one non-floating reference owned by the container */
-</programlisting>
-</para>
-<para>
-Another effect of this is, that calling gst_object_unref() on a bin object, will
-also destoy all the GstElement objects in it. The same is true for calling
-gst_bin_remove().
-</para>
-
-<para>
-gst_object_set_name() and gst_object_get_name() are used to set/get the name of the
-object.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GstObject ##### -->
-<para>
-
-</para>
-
-@refcount:
-@lock:
-@name:
-@name_prefix:
-@parent:
-@flags:
-
-<!-- ##### SIGNAL GstObject::deep-notify ##### -->
-<para>
-The deep notify signal is used to be notified of property changes.
-it is typically attached to the toplevel bin to receive notifications
-from all the elements contained in that bin.
-</para>
-
-@gstobject: the object which received the signal.
-@arg1: the object that originated the signal
-@arg2: the property that changed
-
-<!-- ##### SIGNAL GstObject::object-saved ##### -->
-<para>
-Is trigered whenever a new object is saved to XML. You can connect to
-this signal to insert custom XML tags into the core XML.
-</para>
-
-@gstobject: the object which received the signal.
-@arg1: the xmlNodePtr of the parent node
-
-<!-- ##### SIGNAL GstObject::parent-set ##### -->
-<para>
-Is emitted when the parent of an object is set.
-</para>
-
-@gstobject: the object which received the signal.
-@arg1: the new parent
-
-<!-- ##### SIGNAL GstObject::parent-unset ##### -->
-<para>
-Is emitted when the parent of an object is unset.
-</para>
-
-@gstobject: the object which received the signal.
-@arg1: the old parent
-
-<!-- ##### ARG GstObject:name ##### -->
-<para>
-The name of the object
-</para>
-
-<!-- ##### ENUM GstObjectFlags ##### -->
-<para>
-Flags for an object
-</para>
-
-@GST_OBJECT_DISPOSING:
-@GST_OBJECT_FLOATING:
-@GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
-
-<!-- ##### MACRO GST_FLAGS ##### -->
-<para>
-This macro returns the entire set of flags for the object.
-</para>
-
-@obj: Object to return flags for.
-
-
-<!-- ##### MACRO GST_FLAG_IS_SET ##### -->
-<para>
-This macro checks to see if the given flag is set.
-</para>
-
-@obj: GstSrc to check for flag in.
-@flag: Flag to check for, must be a single bit in guint32.
-
-
-<!-- ##### MACRO GST_FLAG_SET ##### -->
-<para>
-This macro sets the given bits.
-</para>
-
-@obj: Object to set flag in.
-@flag: Flag to set, can by any number of bits in guint32.
-
-
-<!-- ##### MACRO GST_FLAG_UNSET ##### -->
-<para>
-This macro usets the given bits.
-</para>
-
-@obj: Object to unset flag in.
-@flag: Flag to set, must be a single bit in guint32.
-
-
-<!-- ##### MACRO GST_OBJECT_NAME ##### -->
-<para>
-Get the name of this object
-</para>
-
-@obj: Object to get the name of.
-
-
-<!-- ##### MACRO GST_OBJECT_PARENT ##### -->
-<para>
-Get the parent of this object
-</para>
-
-@obj: Object to get the parent of.
-
-
-<!-- ##### MACRO GST_LOCK ##### -->
-<para>
-This macro will obtain a lock on the object, making serialization
-possible.
-</para>
-
-@obj: Object to lock.
-
-
-<!-- ##### MACRO GST_TRYLOCK ##### -->
-<para>
-This macro will try to obtain a lock on the object, but will return with
-FALSE if it can't get it immediately.
-</para>
-
-@obj: Object to try to get a lock on.
-
-
-<!-- ##### MACRO GST_UNLOCK ##### -->
-<para>
-This macro releases a lock on the object.
-</para>
-
-@obj: Object to unlock.
-
-
-<!-- ##### MACRO GST_GET_LOCK ##### -->
-<para>
-Acquire a reference to the mutex of this object.
-</para>
-
-@obj: Object to get the mutex of.
-
-
-<!-- ##### MACRO GST_OBJECT_IS_DISPOSING ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_OBJECT_IS_FLOATING ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_OBJECT_REFCOUNT ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_OBJECT_REFCOUNT_VALUE ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_CLASS_GET_LOCK ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_CLASS_LOCK ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_CLASS_TRYLOCK ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GST_CLASS_UNLOCK ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### FUNCTION gst_object_set_name ##### -->
-<para>
-
-</para>
-
-@object:
-@name:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_get_name ##### -->
-<para>
-
-</para>
-
-@object:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_set_parent ##### -->
-<para>
-
-</para>
-
-@object:
-@parent:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_get_parent ##### -->
-<para>
-
-</para>
-
-@object:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_unparent ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gst_object_get_name_prefix ##### -->
-<para>
-
-</para>
-
-@object:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_set_name_prefix ##### -->
-<para>
-
-</para>
-
-@object:
-@name_prefix:
-
-
-<!-- ##### FUNCTION gst_object_default_deep_notify ##### -->
-<para>
-
-</para>
-
-@object:
-@orig:
-@pspec:
-@excluded_props:
-
-
-<!-- ##### FUNCTION gst_object_default_error ##### -->
-<para>
-
-</para>
-
-@source:
-@error:
-@debug:
-
-
-<!-- ##### FUNCTION gst_object_check_uniqueness ##### -->
-<para>
-
-</para>
-
-@list:
-@name:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_save_thyself ##### -->
-<para>
-
-</para>
-
-@object:
-@parent:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_restore_thyself ##### -->
-<para>
-
-</para>
-
-@object:
-@self:
-
-
-<!-- ##### FUNCTION gst_object_ref ##### -->
-<para>
-
-</para>
-
-@object: the object
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_unref ##### -->
-<para>
-
-</para>
-
-@object: the object
-<!-- # Unused Parameters # -->
-@Returns:
-
-
-<!-- ##### FUNCTION gst_object_sink ##### -->
-<para>
-
-</para>
-
-@object: the object
-
-
-<!-- ##### FUNCTION gst_object_replace ##### -->
-<para>
-
-</para>
-
-@oldobj:
-@newobj:
-
-
-<!-- ##### FUNCTION gst_object_get_path_string ##### -->
-<para>
-
-</para>
-
-@object:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_class_signal_connect ##### -->
-<para>
-
-</para>
-
-@klass:
-@name:
-@func:
-@func_data:
-@Returns:
-
-
-<!-- ##### FUNCTION gst_class_signal_emit_by_name ##### -->
-<para>
-
-</para>
-
-@object:
-@name:
-@self:
-
-
diff --git a/gst/gstelement.c b/gst/gstelement.c
index 1e880234050810919e1925894fbe01e3a7831d75..0f64186a0be0c479e0888eeff15ac29f592993f0 100644 (file)
--- a/gst/gstelement.c
+++ b/gst/gstelement.c
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
-
+/**
+ * SECTION:gstelement
+ * @short_description: Abstract base class for all pipeline elements
+ * @see_also: #GstElementFactory, #GstPad
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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().
+ *
+ * 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.
+ *
+ * Each element has a state (see #GstState). 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 #GstState, use
+ * gst_element_state_get_name().
+ *
+ * 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().
+ *
+ */
#include "gst_private.h"
#include <glib.h>
#include <stdarg.h>
diff --git a/gst/gstelement.h b/gst/gstelement.h
index b0b38716147b8372c186316ee64338f0e05d4e9c..f9ca2613885754e4fbb1c84c922e549736c95d45 100644 (file)
--- a/gst/gstelement.h
+++ b/gst/gstelement.h
/* NOTE: this probably should be done with an #ifdef to decide
* whether to safe-cast or to just do the non-checking cast.
*/
+
+/**
+ * GST_STATE:
+ * @obj: Element to return state for.
+ *
+ * This macro returns the current state of the element.
+ */
#define GST_STATE(obj) (GST_ELEMENT(obj)->current_state)
+
+/**
+ * GST_STATE_PENDING:
+ * @obj: Element to return the pending state for.
+ *
+ * This macro returns the currently pending state of the element.
+ */
#define GST_STATE_PENDING(obj) (GST_ELEMENT(obj)->pending_state)
#define GST_STATE_FINAL(obj) (GST_ELEMENT(obj)->final_state)
#define GST_STATE_ERROR(obj) (GST_ELEMENT(obj)->state_error)
GST_STATE_CHANGE_READY_TO_NULL = 1<<(GST_STATE_READY+8) | 1<<GST_STATE_NULL
} GstStateChange;
+/**
+ * GstElementFlags:
+ * @GST_ELEMENT_LOCKED_STATE: ignore state changes from parent
+ * @GST_ELEMENT_IS_SINK: the element is a sink
+ * @GST_ELEMENT_UNPARENTING: Child is being removed from the parent bin.
+ * gst_bin_remove() on a child already being removed immediately returns FALSE
+ * @GST_ELEMENT_FLAG_LAST: offset to define more flags
+ *
+ * The standard flags that an element may have.
+ */
typedef enum
{
- /* ignore state changes from parent */
GST_ELEMENT_LOCKED_STATE = GST_OBJECT_FLAG_LAST,
-
- /* the element is a sink */
GST_ELEMENT_IS_SINK,
-
- /* Child is being removed from the parent bin. gst_bin_remove on a
- * child already being removed immediately returns FALSE */
GST_ELEMENT_UNPARENTING,
-
- /* use some padding for future expansion */
GST_ELEMENT_FLAG_LAST = GST_OBJECT_FLAG_LAST + 16
} GstElementFlags;
+/**
+ * GST_ELEMENT_IS_LOCKED_STATE:
+ * @obj: A #GstElement to query
+ *
+ * Check if the element is in the loacked state and therefore will ignore state
+ * changes from its parent object.
+ */
#define GST_ELEMENT_IS_LOCKED_STATE(obj) (GST_FLAG_IS_SET(obj,GST_ELEMENT_LOCKED_STATE))
+/**
+ * GST_ELEMENT_NAME:
+ * @obj: A #GstElement to query
+ *
+ * Gets the name of this element. Use only in core as this is not
+ * ABI-compatible. Others use gst_element_get_name()
+ */
#define GST_ELEMENT_NAME(obj) (GST_OBJECT_NAME(obj))
+
+/**
+ * GST_ELEMENT_PARENT:
+ * @obj: A #GstElement to query
+ *
+ * Get the parent object of this element.
+ */
#define GST_ELEMENT_PARENT(obj) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(obj)))
+
+/**
+ * GST_ELEMENT_BUS:
+ * @obj: A #GstElement to query
+ *
+ * Get the message bus of this element.
+ */
#define GST_ELEMENT_BUS(obj) (GST_ELEMENT_CAST(obj)->bus)
+
+/**
+ * GST_ELEMENT_CLOCK:
+ * @obj: A #GstElement to query
+ *
+ * Get the clock of this element
+ */
#define GST_ELEMENT_CLOCK(obj) (GST_ELEMENT_CAST(obj)->clock)
+
+/**
+ * GST_ELEMENT_PADS:
+ * @obj: A #GstElement to query
+ *
+ * Get the pads of this elements.
+ */
#define GST_ELEMENT_PADS(obj) (GST_ELEMENT_CAST(obj)->pads)
/**
__txt, __dbg, __FILE__, GST_FUNCTION, __LINE__); \
} G_STMT_END
-/* log a (non-fatal) warning message and post it on the bus */
+/**
+ * GST_ELEMENT_WARNING:
+ * @el: the element that throws the error
+ * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstError)
+ * @code: error code defined for that domain (see #GstError)
+ * @text: the message to display (format string and args enclosed in
+ parentheses)
+ * @debug: debugging information for the message (format string and args
+ enclosed in parentheses)
+ *
+ * Utility function that elements can use in case they encountered a non-fatal
+ * data processing problem. The pipeline will throw a warning signal and the
+ * application will be informed.
+ */
#define GST_ELEMENT_WARNING(el, domain, code, text, debug) \
G_STMT_START { \
gchar *__txt = _gst_element_error_printf text; \
GType gst_element_get_type (void);
/* basic name and parentage stuff from GstObject */
+
+/**
+ * gst_element_get_name:
+ * @elem: a #GstElement to set the name of.
+ * @name: the new name of the element.
+ *
+ * Gets the name of the element.
+ */
#define gst_element_get_name(elem) gst_object_get_name(GST_OBJECT(elem))
+
+/**
+ * gst_element_set_name:
+ * @elem: a #GstElement to set the name of.
+ *
+ * Sets the name of the element, getting rid of the old name if there was one.
+ *
+ * Returns: the name of the element.
+ */
#define gst_element_set_name(elem,name) gst_object_set_name(GST_OBJECT(elem),name)
+
+/**
+ * gst_element_get_parent:
+ * @elem: a #GstElement to get the parent of.
+ *
+ * Gets the parent of an element.
+ *
+ * Returns: the #GstObject parent of the element.
+ */
#define gst_element_get_parent(elem) gst_object_get_parent(GST_OBJECT(elem))
+
+/**
+ * gst_element_set_parent:
+ * @elem: a #GstElement to set the parent of.
+ * @name: the new parent #GstObject of the element.
+ *
+ * Sets the parent of an element.
+ */
#define gst_element_set_parent(elem,parent) gst_object_set_parent(GST_OBJECT(elem),parent)
/* clocking */
diff --git a/gst/gstinfo.c b/gst/gstinfo.c
index e777a293f11a0e00afddb789fd49bec70ca13072..70ffb70ad466c2b2039cdc60e16a4070ab7b39d6 100644 (file)
--- a/gst/gstinfo.c
+++ b/gst/gstinfo.c
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gstinfo
+ * @short_description: Debugging and logging facillities
+ * @see_also: #GstConfig, #Gst for command line parameters
+ * and environment variables that affect the debugging output.
+ *
+ * GStreamer's debugging subsystem is an easy way to get information about what
+ * the application is doing.
+ * It is not meant for programming errors. Use GLibs methods (g_warning and so
+ * on for that.
+ *
+ * The debugging subsystem works only after GStreamer has been initilized
+ * - for example by calling gst_init().
+ *
+ * The debugging subsystem is used to log informational messages while the
+ * application runs.
+ * Each messages has some properties attached to it. Among these properties
+ * are the debugging category, the severity (called "level" here) and an obtional
+ * #GObject it belongs to. Each of these messages is sent to all registered
+ * debugging handlers, which then handle the messages. GStreamer attaches a
+ * default handler on startup, which outputs requested messages to stderr.
+ *
+ * Messages are output by using shortcut macros like #GST_DEBUG,
+ * #GST_CAT_ERROR_OBJECT or similar. These all expand to calling gst_debug_log()
+ * with the right parameters.
+ * The only thing a developer will probably want to do is define his own
+ * categories. This is easily done with 3 lines. At the top of your code, declare
+ * the variables and set the default category.
+ * <informalexample>
+ * <programlisting>
+ * GST_DEBUG_CATEGORY (my_category); // define category
+ * &hash;define GST_CAT_DEFAULT my_category // set as default
+ * </programlisting>
+ * </informalexample>
+ * After that you only need to initialize the category.
+ * <informalexample>
+ * <programlisting>
+ * GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
+ * </programlisting>
+ * </informalexample>
+ * Initialization must be done before the category is used first. Plugins do this
+ * in their plugin_init function, libraries and applications should do that
+ * during their initialization.
+ *
+ * The whole debugging subsystem can be disabled at build time with passing the
+ * --disable-gst-debug switch to configure. If this is done, every function, macro
+ * and even structs described in this file evaluate to default values or nothing
+ * at all. So don't take addresses of these functions or use other tricks.
+ * If you must do that for some reason, there is still an option. If the debugging
+ * subsystem was compiled out, #GST_DISABLE_GST_DEBUG is defined in <gst/gst.h>,
+ * so you can check that before doing your trick.
+ * Disabling the debugging subsystem will give you a slight (read: unnoticable)
+ * speed increase and will reduce the size of your compiled code. The GStreamer
+ * library itself becomes around 10% smaller.
+ *
+ * Please note that there are naming conventions for the names of debugging
+ * categories. These are explained at GST_DEBUG_CATEGORY_INIT().
+ */
#include "gst_private.h"
#include "gstinfo.h"
diff --git a/gst/gstinfo.h b/gst/gstinfo.h
index d9c15ca286737c028e1a5b9ece11fb60172f5656..1b31d8c12c0c07024cb93685ff126e5706ce78a2 100644 (file)
--- a/gst/gstinfo.h
+++ b/gst/gstinfo.h
G_BEGIN_DECLS
-/*
- * GStreamer's debugging subsystem is an easy way to get information about what
- * the application is doing.
- * It is not meant for programming errors. Use GLibs methods (g_warning and so
- * on for that.
+/**
+ * GstDebugLevel:
+ * @GST_LEVEL_NONE: No debugging level specified or desired. Used to deactivate
+ * debugging output.
+ * @GST_LEVEL_ERROR: Error messages are to be used only when an error occured
+ * that stops the application from keeping working correctly.
+ * An examples is gst_element_error, which outputs a message with this priority.
+ * It does not mean that the application is terminating as with g_errror.
+ * @GST_LEVEL_WARNING: Warning messages are to inform about abnormal behaviour
+ * that could lead to problems or weird behaviour later on. An example of this
+ * would be clocking issues ("your computer is pretty slow") or broken input
+ * data ("Can't synchronize to stream.")
+ * @GST_LEVEL_INFO: Informational messages should be used to keep the developer
+ * updated about what is happening.
+ * Examples where this should be used are when a typefind function has
+ * successfully determined the type of the stream or when an mp3 plugin detects
+ * the format to be used. ("This file has mono sound.")
+ * @GST_LEVEL_DEBUG: Debugging messages should be used when something common
+ * happens that is not the expected default behavior.
+ * An example would be notifications about state changes or receiving/sending of
+ * events.
+ * @GST_LEVEL_LOG: Log messages are messages that are very common but might be
+ * useful to know. As a rule of thumb a pipeline that is iterating as expected
+ * should never output anzthing else but LOG messages.
+ * Examples for this are referencing/dereferencing of objects or cothread switches.
+ * @GST_LEVEL_COUNT: The number of defined debugging levels.
+ *
+ * The level defines the importance of a debugging message. The more important a
+ * message is, the greater the probability that the debugging system outputs it.
*/
-
-/* log levels */
typedef enum {
GST_LEVEL_NONE = 0,
GST_LEVEL_ERROR,
GST_LEVEL_COUNT
} GstDebugLevel;
-/* we can now override this to be more general in maintainer builds
- * or cvs checkouts */
+/**
+ * GST_LEVEL_DEFAULT:
+ *
+ * Defines the default debugging level to be used with GStreamer. It is normally
+ * set to #GST_LEVEL_NONE so nothing get printed.
+ * As it can be configured at compile time, developer builds may chose to
+ * override that though.
+ * You can use this as an argument to gst_debug_set_default_threshold() to
+ * reset the debugging output to default behaviour.
+ */
#ifndef GST_LEVEL_DEFAULT
#define GST_LEVEL_DEFAULT GST_LEVEL_NONE
#endif
* Background color codes:
* 40=black 41=red 42=green 43=yellow 44=blue 45=magenta 46=cyan 47=white
*/
+/**
+ * GstDebugColorFlags:
+ * @GST_DEBUG_FG_BLACK: Use black as foreground color.
+ * @GST_DEBUG_FG_RED: Use red as foreground color.
+ * @GST_DEBUG_FG_GREEN: Use green as foreground color.
+ * @GST_DEBUG_FG_YELLOW: Use yellow as foreground color.
+ * @GST_DEBUG_FG_BLUE: Use blue as foreground color.
+ * @GST_DEBUG_FG_MAGENTA: Use magenta as foreground color.
+ * @GST_DEBUG_FG_CYAN: Use cyan as foreground color.
+ * @GST_DEBUG_FG_WHITE: Use white as foreground color.
+ * @GST_DEBUG_BG_BLACK: Use black as background color.
+ * @GST_DEBUG_BG_RED: Use red as background color.
+ * @GST_DEBUG_BG_GREEN: Use green as background color.
+ * @GST_DEBUG_BG_YELLOW: Use yellow as background color.
+ * @GST_DEBUG_BG_BLUE: Use blue as background color.
+ * @GST_DEBUG_BG_MAGENTA: Use magenta as background color.
+ * @GST_DEBUG_BG_CYAN: Use cyan as background color.
+ * @GST_DEBUG_BG_WHITE: Use white as background color.
+ * @GST_DEBUG_BOLD: Make the output bold.
+ * @GST_DEBUG_UNDERLINE: Underline the output.
+ *
+ * These are some terminal style flags you can use when creating your
+ * debugging categories to make them stand out in debugging output.
+ */
typedef enum {
/* colors */
GST_DEBUG_FG_BLACK = 0x0000,
#define GST_DEBUG_FORMAT_MASK (0xFF00)
typedef struct _GstDebugCategory GstDebugCategory;
+/**
+ * GstDebugCategory:
+ *
+ * This is the struct that describes the categories. Once initialized with
+ * #GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.
+ */
struct _GstDebugCategory {
/*< private >*/
gint threshold;
/********** some convenience macros for debugging **********/
-/* This is needed in printf's if a char* might be NULL. Solaris crashes then. */
+/**
+ * GST_STR_NULL:
+ * @str: The string to check.
+ *
+ * Macro to use when a string must not be NULL, but may be NULL. If the string
+ * is NULL, "(NULL)" is printed instead.
+ * In GStreamer printf string arguments may not be NULL, because on some
+ * platforms (ie Solaris) the libc crashes in that case. This includes debugging
+ * strings.
+ */
#define GST_STR_NULL(str) ((str) ? (str) : "(NULL)")
-/* easier debugging for pad names */
/* FIXME, not MT safe */
+/**
+ * GST_DEBUG_PAD_NAME:
+ * @pad: The pad to debug.
+ *
+ * Evaluates to 2 strings, that describe the pad. Often used in debugging
+ * statements.
+ */
#define GST_DEBUG_PAD_NAME(pad) \
(GST_OBJECT_PARENT(pad) != NULL) ? \
GST_STR_NULL (GST_OBJECT_NAME (GST_OBJECT_PARENT(pad))) : \
"''", GST_OBJECT_NAME (pad)
-/* You might want to define GST_FUNCTION in apps' configure script. */
+/**
+ * GST_FUNCTION:
+ *
+ * This macro should evaluate to the name of the current function and be should
+ * be defined when configuring your project, as it is compiler dependant. If it
+ * is not defined, some default value is used. It is used to provide debugging
+ * output with the function name of the message.
+ */
#ifndef GST_FUNCTION
#if defined (__GNUC__)
# define GST_FUNCTION ((const char*) (__PRETTY_FUNCTION__))
gchar * gst_debug_construct_term_color (guint colorinfo);
+/**
+ * GST_CAT_DEFAULT:
+ *
+ * Default gstreamer core debug log category. Please define your own.
+ */
GST_EXPORT GstDebugCategory * GST_CAT_DEFAULT;
/* this symbol may not be used */
extern gboolean __gst_debug_enabled;
+/**
+ * GST_CAT_LEVEL_LOG:
+ * @cat: category to use
+ * @level: the severity of the message
+ * @object: the #GObject the message belongs to or NULL if none
+ * @...: A printf-style message to output
+ *
+ * Outputs a debugging message. This is the most general macro for outputting
+ * debugging messages. You will probably want to use one of the ones described
+ * below.
+ */
#ifdef G_HAVE_ISO_VARARGS
#define GST_CAT_LEVEL_LOG(cat,level,object,...) G_STMT_START{ \
if (__gst_debug_enabled) { \
#endif
#endif /* G_HAVE_ISO_VARARGS */
+/**
+ * GST_CAT_ERROR_OBJECT:
+ * @cat: category to use
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output an error message belonging to the given object in the given category.
+ */
+/**
+ * GST_CAT_WARNING_OBJECT:
+ * @cat: category to use
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output a warning message belonging to the given object in the given category.
+ */
+/**
+ * GST_CAT_INFO_OBJECT:
+ * @cat: category to use
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output an informational message belonging to the given object in the given
+ * category.
+ */
+/**
+ * GST_CAT_DEBUG_OBJECT:
+ * @cat: category to use
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output an debugging message belonging to the given object in the given category.
+ */
+/**
+ * GST_CAT_LOG_OBJECT:
+ * @cat: category to use
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output an logging message belonging to the given object in the given category.
+ */
+
+
+/**
+ * GST_CAT_ERROR:
+ * @cat: category to use
+ * @...: printf-style message to output
+ *
+ * Output an error message in the given category.
+ */
+/**
+ * GST_CAT_WARNING:
+ * @cat: category to use
+ * @...: printf-style message to output
+ *
+ * Output an warning message in the given category.
+ */
+/**
+ * GST_CAT_INFO:
+ * @cat: category to use
+ * @...: printf-style message to output
+ *
+ * Output an informational message in the given category.
+ */
+/**
+ * GST_CAT_DEBUG:
+ * @cat: category to use
+ * @...: printf-style message to output
+ *
+ * Output an debugging message in the given category.
+ */
+/**
+ * GST_CAT_LOG:
+ * @cat: category to use
+ * @...: printf-style message to output
+ *
+ * Output an logging message in the given category.
+ */
+
+
+/**
+ * GST_ERROR_OBJECT:
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output an error message belonging to the given object in the default category.
+ */
+/**
+ * GST_WARNING_OBJECT:
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output a warning message belonging to the given object in the default category.
+ */
+/**
+ * GST_INFO_OBJECT:
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output an informational message belonging to the given object in the default
+ * category.
+ */
+/**
+ * GST_DEBUG_OBJECT:
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output a debugging message belonging to the given object in the default
+ * category.
+ */
+/**
+ * GST_LOG_OBJECT:
+ * @obj: the #GObject the message belongs to
+ * @...: printf-style message to output
+ *
+ * Output a logging message belonging to the given object in the default category.
+ */
+
+
+/**
+ * GST_ERROR:
+ * @...: printf-style message to output
+ *
+ * Output an error message in the default category.
+ */
+/**
+ * GST_WARNING:
+ * @...: printf-style message to output
+ *
+ * Output a warning message in the default category.
+ */
+/**
+ * GST_INFO:
+ * @...: printf-style message to output
+ *
+ * Output an informational message in the default category.
+ */
+/**
+ * GST_DEBUG:
+ * @...: printf-style message to output
+ *
+ * Output a debugging message in the default category.
+ */
+/**
+ * GST_LOG:
+ * @...: printf-style message to output
+ *
+ * Output a logging message in the default category.
+ */
+
#ifdef G_HAVE_ISO_VARARGS
#define GST_CAT_ERROR_OBJECT(cat,obj,...) GST_CAT_LEVEL_LOG (cat, GST_LEVEL_ERROR, obj, __VA_ARGS__)
/********** function pointer stuff **********/
+
typedef void (* GstDebugFuncPtr) (void);
void _gst_debug_register_funcptr (GstDebugFuncPtr func,
gchar * ptrname);
G_CONST_RETURN gchar *
_gst_debug_nameof_funcptr (GstDebugFuncPtr func);
+/**
+ * GST_DEBUG_FUNCPTR:
+ * @ptr: pointer to the function to register
+ *
+ * Register a pointer to a function with its name, so it can later be used by
+ * GST_DEBUG_FUNCPTR_NAME().
+ *
+ * Returns: The ptr to the function
+ */
#define GST_DEBUG_FUNCPTR(ptr) \
(_gst_debug_register_funcptr((GstDebugFuncPtr)(ptr), #ptr) , ptr)
+
+/**
+ * GST_DEBUG_FUNCPTR_NAME:
+ * @ptr: pointer to the function to look up the name
+ *
+ * Retrieves the name of the function, if it was previously registered with
+ * GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer.
+ *
+ * Make sure you free the string after use.
+ *
+ * Returns: The name of the function
+ */
#define GST_DEBUG_FUNCPTR_NAME(ptr) \
_gst_debug_nameof_funcptr((GstDebugFuncPtr)ptr)
diff --git a/gst/gstobject.c b/gst/gstobject.c
index 79cc89945b0355758f6258ab19343d72b6899e51..11f50868e136d6db2939c8db9bea489e399233c0 100644 (file)
--- a/gst/gstobject.c
+++ b/gst/gstobject.c
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gstobject
+ * @short_description: Base class for the GStreamer object hierarchy
+ *
+ * GstObject provides a root for the object hierarchy tree filed in by the
+ * GST library. It is currently a thin wrapper on top of
+ * #GObject. It is an abstract class that is not very usable on its own.
+ *
+ * GstObject gives us basic refcounting, parenting functionality and locking.
+ * Most of the function are just extended for special gstreamer needs and can be
+ * found under the same name in the base class of GstObject which is GObject
+ * (e.g. g_object_ref() becomes gst_object_ref()).
+ *
+ * The most interesting difference between GstObject and GObject is the "floating"
+ * reference count. A GObject is created with a reference count of 1, owned by the
+ * creator of the GObject. (The owner of a reference is the code section that has
+ * the right to call gst_object_unref() in order to remove that reference.)
+ * A GstObject is created with a reference count of 1 also, but it isn't owned by
+ * anyone; calling gst_object_unref() on the newly-created GtkObject is incorrect.
+ * Instead, the initial reference count of a GstObject is "floating". The floating
+ * reference can be removed by anyone at any time, by calling gst_object_sink().
+ * gst_object_sink() does nothing if an object is already sunk (has no floating
+ * reference).
+ *
+ * When you add a GstElement to its parent container, the parent container will do
+ * this:
+ * <informalexample>
+ * <programlisting>
+ * gst_object_ref (GST_OBJECT (child_element));
+ * gst_object_sink (GST_OBJECT (child_element));
+ * </programlisting>
+ * </informalexample>
+ * This means that the container now owns a reference to the child element (since
+ * it called gst_object_ref()), and the child element has no floating reference.
+ *
+ * The purpose of the floating reference is to keep the child element alive until
+ * you add it to a parent container:
+ * <informalexample>
+ * <programlisting>
+ * element = gst_element_factory_make (factoryname, name);
+ * // element has one floating reference to keep it alive
+ * gst_bin_add (GST_BIN (bin), element);
+ * // element has one non-floating reference owned by the container
+ * </programlisting>
+ * </informalexample>
+ *
+ * Another effect of this is, that calling gst_object_unref() on a bin object, will
+ * also destoy all the GstElement objects in it. The same is true for calling
+ * gst_bin_remove().
+ *
+ * In contrast to GObject instances GstObject add a name property. The functions
+ * gst_object_set_name() and gst_object_get_name() are used to set/get the name
+ * of the object.
+ */
#include "gst_private.h"
* we use our own atomic refcounting to do proper MT safe refcounting.
*
* The hack has several side-effect. At first you should use
- * gst_object_ref/unref() whenever you can. Next When using g_value_set/get_object();
+ * gst_object_ref/unref() whenever you can. Next when using g_value_set/get_object();
* you need to manually fix the refcount.
*
* A proper fix is of course to make the glib refcounting threadsafe which is
g_param_spec_string ("name", "Name", "The name of the object",
NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
+ /**
+ * GstObject::parent-set:
+ * @gstobject: the object which received the signal.
+ * @parent: the new parent
+ *
+ * Is emitted when the parent of an object is set.
+ */
gst_object_signals[PARENT_SET] =
g_signal_new ("parent-set", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstObjectClass, parent_set), NULL, NULL,
g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
+
+ /**
+ * GstObject::parent-unset:
+ * @gstobject: the object which received the signal.
+ * @parent: the old parent
+ *
+ * Is emitted when the parent of an object is unset.
+ */
gst_object_signals[PARENT_UNSET] =
g_signal_new ("parent-unset", G_TYPE_FROM_CLASS (klass),
G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, parent_unset), NULL,
NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
+
#ifndef GST_DISABLE_LOADSAVE_REGISTRY
- /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER */
+ /**
+ * GstObject::object-saved:
+ * @gstobject: the object which received the signal.
+ * @xml_node: the xmlNodePtr of the parent node
+ *
+ * Is trigered whenever a new object is saved to XML. You can connect to this
+ * signal to insert custom XML tags into the core XML.
+ */
+ /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER
+ * (if libxml would use GObject)
+ */
gst_object_signals[OBJECT_SAVED] =
g_signal_new ("object-saved", G_TYPE_FROM_CLASS (klass),
G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, object_saved), NULL,
klass->restore_thyself = gst_object_real_restore_thyself;
#endif
+
+ /**
+ * GstObject::deep-notify:
+ * @gstobject: the object which received the signal.
+ * @prop_object: the object that originated the signal
+ * @prop: the property that changed
+ *
+ * The deep notify signal is used to be notified of property changes. It is
+ * typically attached to the toplevel bin to receive notifications from all
+ * the elements contained in that bin.
+ */
gst_object_signals[DEEP_NOTIFY] =
g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),
G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |
diff --git a/gst/gstobject.h b/gst/gstobject.h
index 31e2645d341ab4d538b80bc6f607c87a18ff5ab3..28ffaff7b22b05dd6b74f5f4b75821f74b8cb319 100644 (file)
--- a/gst/gstobject.h
+++ b/gst/gstobject.h
#define GST_OBJECT_CAST(obj) ((GstObject*)(obj))
#define GST_OBJECT_CLASS_CAST(klass) ((GstObjectClass*)(klass))
-/* make sure we don't change the object size but stil make it compile
+/* make sure we don't change the object size but still make it compile
* without libxml */
#ifdef GST_DISABLE_LOADSAVE_REGISTRY
#define xmlNodePtr gpointer
#endif
+/**
+ * GstObjectFlags:
+ * @GST_OBJECT_DISPOSING: the object is been destroyed, do use it anymore
+ * @GST_OBJECT_FLOATING: the object has a floating reference count (e.g. its
+ * not assigned to a bin)
+ * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
+ *
+ */
typedef enum
{
GST_OBJECT_DISPOSING = 0,
/* we do a GST_OBJECT_CAST to avoid type checking, better call these
* function with a valid object! */
+
+/**
+ * GST_LOCK:
+ * @obj: Object to lock.
+ *
+ * This macro will obtain a lock on the object, making serialization possible.
+ * It block until the lock can be obtained.
+ */
#define GST_LOCK(obj) g_mutex_lock(GST_OBJECT_CAST(obj)->lock)
+/**
+ * GST_TRYLOCK:
+ * @obj: Object to try to get a lock on.
+ *
+ * This macro will try to obtain a lock on the object, but will return with
+ * FALSE if it can't get it immediately.
+ */
#define GST_TRYLOCK(obj) g_mutex_trylock(GST_OBJECT_CAST(obj)->lock)
+/**
+ * GST_LOCK:
+ * @obj: Object to unlock.
+ *
+ * This macro releases a lock on the object.
+ */
#define GST_UNLOCK(obj) g_mutex_unlock(GST_OBJECT_CAST(obj)->lock)
+/**
+ * GST_LOCK:
+ * @obj: Object to get the mutex of.
+ *
+ * Acquire a reference to the mutex of this object.
+ */
#define GST_GET_LOCK(obj) (GST_OBJECT_CAST(obj)->lock)
+
+/**
+ * GST_OBJECT_NAME:
+ * @obj: Object to get the name of.
+ *
+ * Get the name of this object
+ */
#define GST_OBJECT_NAME(obj) (GST_OBJECT_CAST(obj)->name)
+/**
+ * GST_OBJECT_PARENT:
+ * @obj: Object to get the parent of.
+ *
+ * Get the parent of this object
+ */
#define GST_OBJECT_PARENT(obj) (GST_OBJECT_CAST(obj)->parent)
-/* for the flags we double-not to make them comparable to TRUE and FALSE */
+
+/**
+ * GST_FLAGS:
+ * @obj: Object to return flags for.
+ *
+ * This macro returns the entire set of flags for the object.
+ */
#define GST_FLAGS(obj) (GST_OBJECT_CAST (obj)->flags)
+/* for the flags we double-not to make them comparable to TRUE and FALSE */
+/**
+ * GST_FLAG_IS_SET:
+ * @obj: Object to check for flags.
+ * @flag: Flag to check for, must be a single bit in guint32.
+ *
+ * This macro checks to see if the given flag is set.
+ */
#define GST_FLAG_IS_SET(obj,flag) (!!(GST_FLAGS (obj) & (1<<(flag))))
+/**
+ * GST_FLAG_SET:
+ * @obj: Object to set flag in.
+ * @flag: Flag to set, can by any number of bits in guint32.
+ *
+ * This macro sets the given bits.
+ */
#define GST_FLAG_SET(obj,flag) G_STMT_START{ (GST_FLAGS (obj) |= (1<<(flag))); }G_STMT_END
+/**
+ * GST_FLAG_UNSET:
+ * @obj: Object to unset flag in.
+ * @flag: Flag to set, must be a single bit in guint32.
+ *
+ * This macro usets the given bits.
+ */
#define GST_FLAG_UNSET(obj,flag) G_STMT_START{ (GST_FLAGS (obj) &= ~(1<<(flag))); }G_STMT_END
+
+/**
+ * GST_OBJECT_IS_DISPOSING:
+ * @obj: Object to check
+ *
+ * Check if the given object is beeing destroyed.
+ */
#define GST_OBJECT_IS_DISPOSING(obj) (GST_FLAG_IS_SET (obj, GST_OBJECT_DISPOSING))
+/**
+ * GST_OBJECT_IS_FLOATING:
+ * @obj:Object to check
+ *
+ * Check if the given object is floating (has no owner).
+ */
#define GST_OBJECT_IS_FLOATING(obj) (GST_FLAG_IS_SET (obj, GST_OBJECT_FLOATING))
typedef struct _GstObject GstObject;
typedef struct _GstObjectClass GstObjectClass;
+/**
+ * GstObject:
+ * @name: The name of the object
+ *
+ */
struct _GstObject {
GObject object;