mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-13 20:06:35 +00:00
375 lines
7.2 KiB
Text
375 lines
7.2 KiB
Text
<!-- ##### 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>
|
|
|
|
|
|
<!-- ##### 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_DESTROYED: The object is flagged for destruction
|
|
@GST_FLOATING: The object is created but has no parent yet to manage it
|
|
@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_OBJECT_DESTROYED ##### -->
|
|
<para>
|
|
Check if the object has been destroyed.
|
|
</para>
|
|
|
|
@obj: The Object to check
|
|
|
|
|
|
<!-- ##### MACRO GST_OBJECT_FLOATING ##### -->
|
|
<para>
|
|
Check if the object is floating.
|
|
</para>
|
|
|
|
@obj: The Object to check
|
|
|
|
|
|
<!-- ##### 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:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_object_get_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_object_set_parent ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@parent:
|
|
|
|
|
|
<!-- ##### 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
|
|
|
|
|
|
<!-- ##### 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:
|
|
|
|
|