+2004-10-13 Stefan Kost <ensonic@users.sf.net>
+
+ * docs/gst/tmpl/gstobject.sgml:
+ * docs/gst/tmpl/gstplugin.sgml:
+ * docs/gst/tmpl/gstpluginfeature.sgml:
+ * docs/gst/tmpl/gstregistry.sgml:
+ * docs/gst/tmpl/gstversion.sgml:
+ * gst/gstbin.c:
+ more api documentation
+ * gst/gstplugin.c: (gst_plugin_register_func),
+ (gst_plugin_check_file), (gst_plugin_load_file):
+ better error signaling and logging
+
2004-10-11 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
* gst/gstqueue.c: (gst_queue_init), (gst_queue_handle_src_query):
</para>
<para>
-GstObject gives us basic refcounting, parenting functionality and locking.
+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.
<!-- ##### USER_FUNCTION GstPluginFilter ##### -->
<para>
-
+A function that can be used with e.g. gst_registry_plugin_filter()
+to get a list of plugins that match certain criteria.
</para>
-@plugin:
-@user_data:
-@Returns:
+@plugin: the plugin to check
+@user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
+@Returns: TRUE for a positive match, FALSE otherwise
<!-- ##### FUNCTION gst_plugin_get_name ##### -->
<!-- ##### USER_FUNCTION GstPluginFeatureFilter ##### -->
<para>
-
+A function that can be used with e.g. gst_registry_feature_filter()
+to get a list of pluginfeature that match certain criteria.
</para>
-@feature:
-@user_data:
-@Returns:
+@feature: the pluginfeature to check
+@user_data: the user_data that has been passed on e.g. gst_registry_feature_filter()
+@Returns: TRUE for a positive match, FALSE otherwise
<!-- ##### FUNCTION gst_plugin_feature_ensure_loaded ##### -->
GstRegistry
<!-- ##### SECTION Short_Description ##### -->
-Abstract base class for management of #GstPlugin objects
+Abstract base class for management of #GstPlugin objects.
<!-- ##### SECTION Long_Description ##### -->
<para>
-The registry holds the available plugins in the system.
+One registry holds the metadata of a set of plugins.
+All registries build the #GstRegistryPool.
</para>
<!-- ##### SECTION See_Also ##### -->
GstVersion
<!-- ##### SECTION Short_Description ##### -->
-GStreamer version macros
+GStreamer version macros.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Use these macros e.g. when defining own plugins.
+The version macros get defined by including "gst/gst.h".
</para>
<!-- ##### SECTION See_Also ##### -->
* @element: #GstElement to add to bin
*
* Adds the given element to the bin. Sets the element's parent, and thus
- * adds a reference.
+ * takes ownership of the element. An element can only be added to one bin.
*/
void
gst_bin_add (GstBin * bin, GstElement * element)
return FALSE;
}
+ if (GST_CAT_DEFAULT)
+ GST_LOG ("plugin \"%s\" looks good", GST_STR_NULL (plugin->filename));
+
gst_plugin_desc_copy (&plugin->desc, desc);
plugin->module = module;
plugin, filename);
if (g_module_symbol (module, "plugin_init", &ptr)) {
- g_print
+ GST_WARNING
("plugin %p from file \"%s\" exports a symbol named plugin_init\n",
plugin, plugin->filename);
g_set_error (error, GST_PLUGIN_ERROR, GST_PLUGIN_ERROR_NAME_MISMATCH,
_gst_plugin_fault_handler_setup ();
_gst_plugin_fault_handler_filename = plugin->filename;
+ GST_LOG ("Plugin %p for file \"%s\" prepared, registering...",
+ plugin, filename);
+
if (gst_plugin_register_func (plugin, module, desc)) {
/* remove signal handler */
_gst_plugin_fault_handler_restore ();