GstObject
<!-- ##### SECTION Short_Description ##### -->
-Basis for the GST object hierarchy.
+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> but it can be compiled against GTK+ with
-a shim provided by the GStreamer library. It is an abstract class that is not
+<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.
+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>
-<!-- ##### ENUM GstObjectFlags ##### -->
+<!-- ##### STRUCT GstObject ##### -->
<para>
</para>
-@GST_DESTROYED:
-@GST_FLOATING:
-@GST_OBJECT_FLAG_LAST:
+@refcount:
+@lock:
+@name:
+@name_prefix:
+@parent:
+@flags:
-<!-- ##### STRUCT GstObject ##### -->
+<!-- ##### 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_DESTROYED:
+@GST_OBJECT_FLOATING:
+@GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
<!-- ##### MACRO GST_FLAGS ##### -->
<para>
@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
@obj: Object to get the mutex of.
-<!-- ##### MACRO GST_OBJECT_PARENT ##### -->
-<para>
-Get the parent of this object
-</para>
-
-@obj: Object to get the parent of.
-
-
-<!-- ##### MACRO GST_OBJECT_NAME ##### -->
-<para>
-Get the name of this object
-</para>
-
-@obj: Object to get the name of.
-
-
-<!-- ##### MACRO GST_OBJECT_FLOATING ##### -->
+<!-- ##### FUNCTION gst_object_set_name ##### -->
<para>
-Check if the object is floating.
-</para>
-
-@obj: The Object to check
-
-<!-- ##### MACRO GST_OBJECT_DESTROYED ##### -->
-<para>
-Check if the object has been destroyed.
</para>
-@obj: The Object to check
+@object:
+@name:
+@Returns:
-<!-- ##### FUNCTION gst_object_check_uniqueness ##### -->
+<!-- ##### FUNCTION gst_object_get_name ##### -->
<para>
</para>
-@list:
-@name:
+@object:
@Returns:
@object:
@parent:
+@Returns:
<!-- ##### FUNCTION gst_object_get_parent ##### -->
@Returns:
-<!-- ##### FUNCTION gst_object_set_name ##### -->
+<!-- ##### FUNCTION gst_object_unparent ##### -->
<para>
</para>
@object:
-@name:
-<!-- ##### FUNCTION gst_object_get_name ##### -->
+<!-- ##### FUNCTION gst_object_default_deep_notify ##### -->
<para>
</para>
@object:
-@Returns:
+@orig:
+@pspec:
+@excluded_props:
-<!-- ##### FUNCTION gst_object_unparent ##### -->
+<!-- ##### FUNCTION gst_object_check_uniqueness ##### -->
<para>
</para>
-@object:
+@list:
+@name:
+@Returns:
-<!-- ##### FUNCTION gst_object_ref ##### -->
+<!-- ##### FUNCTION gst_object_save_thyself ##### -->
<para>
</para>
-@object: the object
+@object:
+@parent:
@Returns:
-<!-- ##### FUNCTION gst_object_unref ##### -->
+<!-- ##### FUNCTION gst_object_restore_thyself ##### -->
<para>
</para>
-@object: the object
+@object:
+@self:
-<!-- ##### FUNCTION gst_object_sink ##### -->
+<!-- ##### FUNCTION gst_object_ref ##### -->
<para>
</para>
@object: the object
+@Returns:
-<!-- ##### FUNCTION gst_object_destroy ##### -->
+<!-- ##### FUNCTION gst_object_unref ##### -->
<para>
</para>
@object: the object
+@Returns:
-<!-- ##### FUNCTION gst_object_save_thyself ##### -->
+<!-- ##### FUNCTION gst_object_sink ##### -->
<para>
</para>
-@object:
-@parent:
-@Returns:
+@object: the object
-<!-- ##### FUNCTION gst_object_restore_thyself ##### -->
+<!-- ##### FUNCTION gst_object_replace ##### -->
<para>
</para>
-@object:
-@parent:
+@oldobj:
+@newobj:
<!-- ##### FUNCTION gst_object_get_path_string ##### -->
@Returns:
-<!-- ##### FUNCTION gst_class_signal_emit_by_name ##### -->
-<para>
-
-</para>
-
-@object:
-@name:
-@self:
-
-
<!-- ##### FUNCTION gst_class_signal_connect ##### -->
<para>
@Returns:
-<!-- ##### SIGNAL GstObject::parent-set ##### -->
+<!-- ##### FUNCTION gst_class_signal_emit_by_name ##### -->
<para>
</para>
-@gstobject: the object which received the signal.
-@arg1: the new parent
-
-<!-- ##### 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
-
-<!-- ##### ARG GstObject:name ##### -->
-<para>
+@object:
+@name:
+@self:
-</para>
projects / platform / upstream / gstreamer.git / blobdiff