X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gst%2Fgstobject.c;h=3aa20c44351ad0924ba840c6028c6b94009b8358;hb=ce43de86902c4e9c8ed4e9682602664cb9bce2ee;hp=f830402c38086c6e85d1b3aa14f7a61f0d8fcb9a;hpb=4348851cd98d50013f341e067c06f4176ff41fce;p=platform%2Fupstream%2Fgstreamer.git diff --git a/gst/gstobject.c b/gst/gstobject.c index f830402..3aa20c4 100644 --- a/gst/gstobject.c +++ b/gst/gstobject.c @@ -17,12 +17,13 @@ * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, + * Boston, MA 02110-1301, USA. */ /** * SECTION:gstobject + * @title: GstObject * @short_description: Base class for the GStreamer object hierarchy * * #GstObject provides a root for the object hierarchy tree filed in by the @@ -30,11 +31,11 @@ * #GInitiallyUnowned. 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 + * Most of the functions 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()). * - * Since #GstObject dereives from #GInitiallyUnowned, it also inherits the + * Since #GstObject derives from #GInitiallyUnowned, it also inherits the * floating reference. Be aware that functions such as gst_bin_add() and * gst_element_add_pad() take ownership of the floating reference. * @@ -42,58 +43,38 @@ * gst_object_set_name() and gst_object_get_name() are used to set/get the name * of the object. * - * - * controlled properties - * - * Controlled properties offers a lightweight way to adjust gobject - * properties over stream-time. It works by using time-stamped value pairs that - * are queued for element-properties. At run-time the elements continously pull - * values changes for the current stream-time. + * ## controlled properties + * + * Controlled properties offers a lightweight way to adjust gobject properties + * over stream-time. It works by using time-stamped value pairs that are queued + * for element-properties. At run-time the elements continuously pull value + * changes for the current stream-time. * * What needs to be changed in a #GstElement? * Very little - it is just two steps to make a plugin controllable! - * - * - * mark gobject-properties paramspecs that make sense to be controlled, + * + * * mark gobject-properties paramspecs that make sense to be controlled, * by GST_PARAM_CONTROLLABLE. - * - * - * when processing data (get, chain, loop function) at the beginning call + * + * * when processing data (get, chain, loop function) at the beginning call * gst_object_sync_values(element,timestamp). - * This will made the controller to update all gobject properties that are under - * control with the current values based on timestamp. - * - * - * - * What needs to be done in applications? - * Again its not a lot to change. - * - * - * first put some properties under control, by calling - * gst_object_control_properties (object, "prop1", "prop2",...); - * - * - * create a #GstControlSource. + * This will make the controller update all GObject properties that are + * under its control with the current values based on the timestamp. + * + * What needs to be done in applications? Again it's not a lot to change. + * + * * create a #GstControlSource. * csource = gst_interpolation_control_source_new (); * g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); - * - * - * Attach the #GstControlSource on the controller to a property. - * gst_object_add_control_binding (object, gst_direct_control_binding_new (objetct, "prop1", csource)); - * - * - * Set the control values + * + * * Attach the #GstControlSource on the controller to a property. + * gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); + * + * * Set the control values * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); - * - * - * start your pipeline - * - * - * - * - * - * Last reviewed on 2012-03-29 (0.11.3) + * + * * start your pipeline */ #include "gst_private.h" @@ -107,11 +88,6 @@ #include "gstparamspecs.h" #include "gstutils.h" -#ifndef GST_DISABLE_TRACE -#include "gsttrace.h" -static GstAllocTrace *_gst_object_trace; -#endif - #define DEBUG_REFCOUNT /* Object signals and args */ @@ -160,15 +136,18 @@ static GParamSpec *properties[PROP_LAST]; G_DEFINE_ABSTRACT_TYPE (GstObject, gst_object, G_TYPE_INITIALLY_UNOWNED); static void +gst_object_constructed (GObject * object) +{ + GST_TRACER_OBJECT_CREATED (GST_OBJECT_CAST (object)); + + ((GObjectClass *) gst_object_parent_class)->constructed (object); +} + +static void gst_object_class_init (GstObjectClass * klass) { GObjectClass *gobject_class = G_OBJECT_CLASS (klass); -#ifndef GST_DISABLE_TRACE - _gst_object_trace = - _gst_alloc_trace_register (g_type_name (GST_TYPE_OBJECT), -2); -#endif - gobject_class->set_property = gst_object_set_property; gobject_class->get_property = gst_object_get_property; @@ -176,6 +155,15 @@ gst_object_class_init (GstObjectClass * klass) g_param_spec_string ("name", "Name", "The name of the object", NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS); + /** + * GstObject:parent: + * + * The parent of the object. Please note, that when changing the 'parent' + * property, we don't emit #GObject::notify and #GstObject::deep-notify + * signals due to locking issues. In some cases one can use + * #GstBin::element-added or #GstBin::element-removed signals on the parent to + * achieve a similar effect. + */ properties[PROP_PARENT] = g_param_spec_object ("parent", "Parent", "The parent of the object", GST_TYPE_OBJECT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); @@ -205,6 +193,7 @@ gst_object_class_init (GstObjectClass * klass) gobject_class->dispatch_properties_changed = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed); + gobject_class->constructed = gst_object_constructed; gobject_class->dispose = gst_object_dispose; gobject_class->finalize = gst_object_finalize; } @@ -217,10 +206,6 @@ gst_object_init (GstObject * object) object->name = NULL; GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object); -#ifndef GST_DISABLE_TRACE - _gst_alloc_trace_new (_gst_object_trace, object); -#endif - object->flags = 0; object->control_rate = 100 * GST_MSECOND; @@ -229,7 +214,7 @@ gst_object_init (GstObject * object) /** * gst_object_ref: - * @object: a #GstObject to reference + * @object: (type Gst.Object): a #GstObject to reference * * Increments the reference count on @object. This function * does not take the lock on @object because it relies on @@ -239,13 +224,14 @@ gst_object_init (GstObject * object) * constructs like : * result = gst_object_ref (object->parent); * - * Returns: (transfer full): A pointer to @object + * Returns: (transfer full) (type Gst.Object): A pointer to @object */ gpointer gst_object_ref (gpointer object) { g_return_val_if_fail (object != NULL, NULL); + GST_TRACER_OBJECT_REFFED (object, ((GObject *) object)->ref_count + 1); #ifdef DEBUG_REFCOUNT GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d", object, ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1); @@ -257,7 +243,7 @@ gst_object_ref (gpointer object) /** * gst_object_unref: - * @object: a #GstObject to unreference + * @object: (type Gst.Object): a #GstObject to unreference * * Decrements the reference count on @object. If reference count hits * zero, destroy @object. This function does not take the lock @@ -272,6 +258,7 @@ gst_object_unref (gpointer object) g_return_if_fail (object != NULL); g_return_if_fail (((GObject *) object)->ref_count > 0); + GST_TRACER_OBJECT_UNREFFED (object, ((GObject *) object)->ref_count - 1); #ifdef DEBUG_REFCOUNT GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d", object, ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1); @@ -291,6 +278,9 @@ gst_object_unref (gpointer object) * the floating flag while leaving the reference count unchanged. If the object * is not floating, then this call adds a new normal reference increasing the * reference count by one. + * + * For more background on "floating references" please see the #GObject + * documentation. */ gpointer gst_object_ref_sink (gpointer object) @@ -306,18 +296,42 @@ gst_object_ref_sink (gpointer object) } /** + * gst_clear_object: (skip) + * @object_ptr: a pointer to a #GstObject reference + * + * Clears a reference to a #GstObject. + * + * @object_ptr must not be %NULL. + * + * If the reference is %NULL then this function does nothing. + * Otherwise, the reference count of the object is decreased using + * gst_object_unref() and the pointer is set to %NULL. + * + * A macro is also included that allows this function to be used without + * pointer casts. + * + * Since: 1.16 + **/ +#undef gst_clear_object +void +gst_clear_object (GstObject ** object_ptr) +{ + g_clear_pointer (object_ptr, gst_object_unref); +} + +/** * gst_object_replace: - * @oldobj: (inout) (transfer full): pointer to a place of a #GstObject to - * replace - * @newobj: (transfer none): a new #GstObject + * @oldobj: (inout) (transfer full) (nullable): pointer to a place of + * a #GstObject to replace + * @newobj: (transfer none) (allow-none): a new #GstObject * * Atomically modifies a pointer to point to a new object. * The reference count of @oldobj is decreased and the reference count of * @newobj is increased. * - * Either @newobj and the value pointed to by @oldobj may be NULL. + * Either @newobj and the value pointed to by @oldobj may be %NULL. * - * Returns: TRUE if @newobj was different from @oldobj + * Returns: %TRUE if @newobj was different from @oldobj */ gboolean gst_object_replace (GstObject ** oldobj, GstObject * newobj) @@ -340,7 +354,7 @@ gst_object_replace (GstObject ** oldobj, GstObject * newobj) return FALSE; if (newobj) - g_object_ref (newobj); + gst_object_ref (newobj); while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *) oldobj, oldptr, newobj))) { @@ -350,7 +364,7 @@ gst_object_replace (GstObject ** oldobj, GstObject * newobj) } if (oldptr) - g_object_unref (oldptr); + gst_object_unref (oldptr); return oldptr != newobj; } @@ -363,7 +377,7 @@ gst_object_dispose (GObject * object) GstObject *self = (GstObject *) object; GstObject *parent; - GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "dispose"); + GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p dispose", object); GST_OBJECT_LOCK (object); if ((parent = GST_OBJECT_PARENT (object))) @@ -405,16 +419,14 @@ gst_object_finalize (GObject * object) { GstObject *gstobject = GST_OBJECT_CAST (object); - GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "finalize"); + GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p finalize", object); g_signal_handlers_destroy (object); g_free (gstobject->name); g_mutex_clear (&gstobject->lock); -#ifndef GST_DISABLE_TRACE - _gst_alloc_trace_free (_gst_object_trace, object); -#endif + GST_TRACER_OBJECT_DESTROYED (gstobject); ((GObjectClass *) gst_object_parent_class)->finalize (object); } @@ -477,9 +489,9 @@ gst_object_dispatch_properties_changed (GObject * object, * @object: the #GObject that signalled the notify. * @orig: a #GstObject that initiated the notify. * @pspec: a #GParamSpec of the property. - * @excluded_props: (array zero-terminated=1) (element-type gchar*) - * (allow-none):a set of user-specified properties to exclude or - * NULL to show all changes. + * @excluded_props: (array zero-terminated=1) (element-type gchar*) (allow-none): + * a set of user-specified properties to exclude or %NULL to show + * all changes. * * A default deep_notify signal callback for an object. The user data * should contain a pointer to an array of strings that should be excluded @@ -507,19 +519,10 @@ gst_object_default_deep_notify (GObject * object, GstObject * orig, g_value_init (&value, pspec->value_type); g_object_get_property (G_OBJECT (orig), pspec->name, &value); - /* FIXME: handle flags */ - if (G_IS_PARAM_SPEC_ENUM (pspec)) { - GEnumValue *enum_value; - GEnumClass *klass = G_ENUM_CLASS (g_type_class_ref (pspec->value_type)); - - enum_value = g_enum_get_value (klass, g_value_get_enum (&value)); - - str = g_strdup_printf ("%s (%d)", enum_value->value_nick, - enum_value->value); - g_type_class_unref (klass); - } else { - str = g_strdup_value_contents (&value); - } + if (G_VALUE_HOLDS_STRING (&value)) + str = g_value_dup_string (&value); + else + str = gst_value_serialize (&value); name = gst_object_get_path_string (orig); g_print ("%s: %s = %s\n", name, pspec->name, str); g_free (name); @@ -559,7 +562,14 @@ gst_object_set_name_default (GstObject * object) type_name = g_quark_to_string (q); if (strncmp (type_name, "Gst", 3) == 0) type_name += 3; - name = g_strdup_printf ("%s%d", type_name, count); + /* give the 20th "queue" element and the first "queue2" different names */ + l = strlen (type_name); + if (l > 0 && g_ascii_isdigit (type_name[l - 1])) { + name = g_strdup_printf ("%s-%d", type_name, count); + } else { + name = g_strdup_printf ("%s%d", type_name, count); + } + l = strlen (name); for (i = 0; i < l; i++) name[i] = g_ascii_tolower (name[i]); @@ -587,15 +597,15 @@ had_parent: /** * gst_object_set_name: * @object: a #GstObject - * @name: new name of object + * @name: (allow-none): new name of object * * Sets the name of @object, or gives @object a guaranteed unique - * name (if @name is NULL). + * name (if @name is %NULL). * This function makes a copy of the provided name, so the caller * retains ownership of the name it sent. * - * Returns: TRUE if the name could be set. Since Objects that have - * a parent cannot be renamed, this function returns FALSE in those + * Returns: %TRUE if the name could be set. Since Objects that have + * a parent cannot be renamed, this function returns %FALSE in those * cases. * * MT safe. This function grabs and releases @object's LOCK. @@ -622,10 +632,8 @@ gst_object_set_name (GstObject * object, const gchar * name) GST_OBJECT_UNLOCK (object); result = gst_object_set_name_default (object); } - /* FIXME-0.11: this misses a g_object_notify (object, "name"); unless called - * from gst_object_set_property. - * Ideally remove such custom setters (or make it static). - */ + + g_object_notify (G_OBJECT (object), "name"); return result; /* error */ @@ -643,12 +651,13 @@ had_parent: * * Returns a copy of the name of @object. * Caller should g_free() the return value after usage. - * For a nameless object, this returns NULL, which you can safely g_free() + * For a nameless object, this returns %NULL, which you can safely g_free() * as well. * * Free-function: g_free * - * Returns: (transfer full): the name of @object. g_free() after usage. + * Returns: (transfer full) (nullable): the name of @object. g_free() + * after usage. * * MT safe. This function grabs and releases @object's LOCK. */ @@ -668,13 +677,13 @@ gst_object_get_name (GstObject * object) /** * gst_object_set_parent: - * @object: a #GstObject + * @object: (transfer floating): a #GstObject * @parent: new parent of object * * Sets the parent of @object to @parent. The object's reference count will * be incremented, and any floating reference will be removed (see gst_object_ref_sink()). * - * Returns: TRUE if @parent could be set or FALSE when @object + * Returns: %TRUE if @parent could be set or %FALSE when @object * already had a parent or @object and @parent are the same. * * MT safe. Grabs and releases @object's LOCK. @@ -697,9 +706,11 @@ gst_object_set_parent (GstObject * object, GstObject * parent) gst_object_ref_sink (object); GST_OBJECT_UNLOCK (object); - /* FIXME, this does not work, the deep notify takes the lock from the parent - * object and deadlocks when the parent holds its lock when calling this - * function (like _element_add_pad()) */ + /* FIXME-2.0: this does not work, the deep notify takes the lock from the + * parent object and deadlocks when the parent holds its lock when calling + * this function (like _element_add_pad()), we need to use a GRecMutex + * for locking the parent instead. + */ /* g_object_notify_by_pspec ((GObject *)object, properties[PROP_PARENT]); */ return TRUE; @@ -709,6 +720,8 @@ had_parent: { GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object, "set parent failed, object already had a parent"); + gst_object_ref_sink (object); + gst_object_unref (object); GST_OBJECT_UNLOCK (object); return FALSE; } @@ -721,8 +734,8 @@ had_parent: * Returns the parent of @object. This function increases the refcount * of the parent object so you should gst_object_unref() it after usage. * - * Returns: (transfer full): parent of @object, this can be NULL if @object - * has no parent. unref after usage. + * Returns: (transfer full) (nullable): parent of @object, this can be + * %NULL if @object has no parent. unref after usage. * * MT safe. Grabs and releases @object's LOCK. */ @@ -775,19 +788,47 @@ gst_object_unparent (GstObject * object) } /** - * gst_object_has_ancestor: + * gst_object_has_as_parent: + * @object: a #GstObject to check + * @parent: a #GstObject to check as parent + * + * Check if @parent is the parent of @object. + * E.g. a #GstElement can check if it owns a given #GstPad. + * + * Returns: %FALSE if either @object or @parent is %NULL. %TRUE if @parent is + * the parent of @object. Otherwise %FALSE. + * + * MT safe. Grabs and releases @object's locks. + * Since: 1.6 + */ +gboolean +gst_object_has_as_parent (GstObject * object, GstObject * parent) +{ + gboolean result = FALSE; + + if (G_LIKELY (GST_IS_OBJECT (object) && GST_IS_OBJECT (parent))) { + GST_OBJECT_LOCK (object); + result = GST_OBJECT_PARENT (object) == parent; + GST_OBJECT_UNLOCK (object); + } + + return result; +} + +/** + * gst_object_has_as_ancestor: * @object: a #GstObject to check * @ancestor: a #GstObject to check as ancestor * * Check if @object has an ancestor @ancestor somewhere up in * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. * - * Returns: TRUE if @ancestor is an ancestor of @object. + * Returns: %TRUE if @ancestor is an ancestor of @object. * * MT safe. Grabs and releases @object's locks. */ gboolean -gst_object_has_ancestor (GstObject * object, GstObject * ancestor) +gst_object_has_as_ancestor (GstObject * object, GstObject * ancestor) { GstObject *parent, *tmp; @@ -810,6 +851,28 @@ gst_object_has_ancestor (GstObject * object, GstObject * ancestor) } /** + * gst_object_has_ancestor: + * @object: a #GstObject to check + * @ancestor: a #GstObject to check as ancestor + * + * Check if @object has an ancestor @ancestor somewhere up in + * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. + * + * Returns: %TRUE if @ancestor is an ancestor of @object. + * + * Deprecated: Use gst_object_has_as_ancestor() instead. + * + * MT safe. Grabs and releases @object's locks. + */ +#ifndef GST_REMOVE_DEPRECATED +gboolean +gst_object_has_ancestor (GstObject * object, GstObject * ancestor) +{ + return gst_object_has_as_ancestor (object, ancestor); +} +#endif + +/** * gst_object_check_uniqueness: * @list: (transfer none) (element-type Gst.Object): a list of #GstObject to * check through @@ -819,10 +882,10 @@ gst_object_has_ancestor (GstObject * object, GstObject * ancestor) * does not do any locking of any kind. You might want to protect the * provided list with the lock of the owner of the list. This function * will lock each #GstObject in the list to compare the name, so be - * carefull when passing a list with a locked object. + * careful when passing a list with a locked object. * - * Returns: TRUE if a #GstObject named @name does not appear in @list, - * FALSE if it does. + * Returns: %TRUE if a #GstObject named @name does not appear in @list, + * %FALSE if it does. * * MT safe. Grabs and releases the LOCK of each object in the list. */ @@ -927,7 +990,7 @@ gst_object_get_path_string (GstObject * object) path = g_strdup (""); /* first walk the object hierarchy to build a list of the parents, - * be carefull here with refcounting. */ + * be careful here with refcounting. */ do { if (GST_IS_OBJECT (object)) { parent = gst_object_get_parent (object); @@ -989,8 +1052,8 @@ gst_object_get_path_string (GstObject * object) * * Searches the list of properties under control. * - * Returns: a #GstControlBinding or %NULL if the property is not being - * controlled. + * Returns: (nullable): a #GstControlBinding or %NULL if the property + * is not being controlled. */ static GstControlBinding * gst_object_find_control_binding (GstObject * self, const gchar * name) @@ -1091,7 +1154,7 @@ gst_object_sync_values (GstObject * object, GstClockTime timestamp) * gst_object_has_active_control_bindings: * @object: the object that has controlled properties * - * Check if the @object has an active controlled properties. + * Check if the @object has active controlled properties. * * Returns: %TRUE if the object has active controlled properties */ @@ -1142,8 +1205,8 @@ gst_object_set_control_bindings_disabled (GstObject * object, gboolean disabled) * @disabled: boolean that specifies whether to disable the controller * or not. * - * This function is used to disable the #GstController on a property for - * some time, i.e. gst_controller_sync_values() will do nothing for the + * This function is used to disable the control bindings on a property for + * some time, i.e. gst_object_sync_values() will do nothing for the * property. */ void @@ -1166,14 +1229,16 @@ gst_object_set_control_binding_disabled (GstObject * object, /** * gst_object_add_control_binding: * @object: the controller object - * @binding: (transfer full): the #GstControlBinding that should be used + * @binding: (transfer floating): the #GstControlBinding that should be used + * + * Attach the #GstControlBinding to the object. If there already was a + * #GstControlBinding for this property it will be replaced. * - * Sets the #GstControlBinding. If there already was a #GstControlBinding - * for this property it will be replaced. - * The @object will take ownership of the @binding. + * The object's reference count will be incremented, and any floating + * reference will be removed (see gst_object_ref_sink()) * - * Returns: %FALSE if the given @binding has not been setup for this object or - * %TRUE otherwise. + * Returns: %FALSE if the given @binding has not been setup for this object or + * has been setup for a non suitable property, %TRUE otherwise. */ gboolean gst_object_add_control_binding (GstObject * object, GstControlBinding * binding) @@ -1182,8 +1247,7 @@ gst_object_add_control_binding (GstObject * object, GstControlBinding * binding) g_return_val_if_fail (GST_IS_OBJECT (object), FALSE); g_return_val_if_fail (GST_IS_CONTROL_BINDING (binding), FALSE); - //g_return_val_if_fail (g_type_is_a (binding->pspec->owner_type, - // G_OBJECT_TYPE (object)), FALSE); + g_return_val_if_fail (binding->pspec, FALSE); GST_OBJECT_LOCK (object); if ((old = gst_object_find_control_binding (object, binding->name))) { @@ -1207,8 +1271,8 @@ gst_object_add_control_binding (GstObject * object, GstControlBinding * binding) * Gets the corresponding #GstControlBinding for the property. This should be * unreferenced again after use. * - * Returns: (transfer full): the #GstControlBinding for @property_name or %NULL if - * the property is not controlled. + * Returns: (transfer full) (nullable): the #GstControlBinding for + * @property_name or %NULL if the property is not controlled. */ GstControlBinding * gst_object_get_control_binding (GstObject * object, const gchar * property_name) @@ -1220,7 +1284,7 @@ gst_object_get_control_binding (GstObject * object, const gchar * property_name) GST_OBJECT_LOCK (object); if ((binding = gst_object_find_control_binding (object, property_name))) { - g_object_ref (binding); + gst_object_ref (binding); } GST_OBJECT_UNLOCK (object); @@ -1233,7 +1297,7 @@ gst_object_get_control_binding (GstObject * object, const gchar * property_name) * @binding: the binding * * Removes the corresponding #GstControlBinding. If it was the - * last ref of the binding, it will be disposed. + * last ref of the binding, it will be disposed. * * Returns: %TRUE if the binding could be removed. */ @@ -1268,8 +1332,8 @@ gst_object_remove_control_binding (GstObject * object, * * Gets the value for the given controlled property at the requested time. * - * Returns: the GValue of the property at the given time, or %NULL if the - * property isn't controlled. + * Returns: (nullable): the GValue of the property at the given time, + * or %NULL if the property isn't controlled. */ GValue * gst_object_get_value (GstObject * object, const gchar * property_name, @@ -1292,7 +1356,7 @@ gst_object_get_value (GstObject * object, const gchar * property_name, } /** - * gst_object_get_value_array: + * gst_object_get_value_array: (skip) * @object: the object that has controlled properties * @property_name: the name of the property to get * @timestamp: the time that should be processed @@ -1300,19 +1364,23 @@ gst_object_get_value (GstObject * object, const gchar * property_name, * @n_values: the number of values * @values: array to put control-values in * - * Gets a number of values for the given controllered property starting at the + * Gets a number of values for the given controlled property starting at the * requested time. The array @values need to hold enough space for @n_values of * the same type as the objects property's type. * * This function is useful if one wants to e.g. draw a graph of the control * curve or apply a control curve sample by sample. * + * The values are unboxed and ready to be used. The similar function + * gst_object_get_g_value_array() returns the array as #GValues and is + * better suites for bindings. + * * Returns: %TRUE if the given array could be filled, %FALSE otherwise */ gboolean gst_object_get_value_array (GstObject * object, const gchar * property_name, GstClockTime timestamp, GstClockTime interval, guint n_values, - GValue * values) + gpointer values) { gboolean res = FALSE; GstControlBinding *binding; @@ -1332,6 +1400,47 @@ gst_object_get_value_array (GstObject * object, const gchar * property_name, return res; } +/** + * gst_object_get_g_value_array: + * @object: the object that has controlled properties + * @property_name: the name of the property to get + * @timestamp: the time that should be processed + * @interval: the time spacing between subsequent values + * @n_values: the number of values + * @values: (array length=n_values): array to put control-values in + * + * Gets a number of #GValues for the given controlled property starting at the + * requested time. The array @values need to hold enough space for @n_values of + * #GValue. + * + * This function is useful if one wants to e.g. draw a graph of the control + * curve or apply a control curve sample by sample. + * + * Returns: %TRUE if the given array could be filled, %FALSE otherwise + */ +gboolean +gst_object_get_g_value_array (GstObject * object, const gchar * property_name, + GstClockTime timestamp, GstClockTime interval, guint n_values, + GValue * values) +{ + gboolean res = FALSE; + GstControlBinding *binding; + + g_return_val_if_fail (GST_IS_OBJECT (object), FALSE); + g_return_val_if_fail (property_name, FALSE); + g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE); + g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), FALSE); + g_return_val_if_fail (values, FALSE); + + GST_OBJECT_LOCK (object); + if ((binding = gst_object_find_control_binding (object, property_name))) { + res = gst_control_binding_get_g_value_array (binding, timestamp, interval, + n_values, values); + } + GST_OBJECT_UNLOCK (object); + return res; +} + /** * gst_object_get_control_rate: @@ -1339,7 +1448,7 @@ gst_object_get_value_array (GstObject * object, const gchar * property_name, * * Obtain the control-rate for this @object. Audio processing #GstElement * objects will use this rate to sub-divide their processing loop and call - * gst_object_sync_values() inbetween. The length of the processing segment + * gst_object_sync_values() in between. The length of the processing segment * should be up to @control-rate nanoseconds. * * If the @object is not under property control, this will return @@ -1365,7 +1474,7 @@ gst_object_get_control_rate (GstObject * object) * * Change the control-rate for this @object. Audio processing #GstElement * objects will use this rate to sub-divide their processing loop and call - * gst_object_sync_values() inbetween. The length of the processing segment + * gst_object_sync_values() in between. The length of the processing segment * should be up to @control-rate nanoseconds. * * The control-rate should not change if the element is in %GST_STATE_PAUSED or