| <!-- ##### 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> |
| |
| <!-- ##### 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_DESTROYED: |
| @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. |
| |
| |
| <!-- ##### 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_default_deep_notify ##### --> |
| <para> |
| |
| </para> |
| |
| @object: |
| @orig: |
| @pspec: |
| @excluded_props: |
| |
| |
| <!-- ##### 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: |
| |
| |