*
* 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.
*/
/**
* #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.
*
* <refsect2>
* <title>controlled properties</title>
* <para>
- * 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 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!
* <listitem><para>
* 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.
+ * This will make the controller update all GObject properties that are
+ * under its control with the current values based on the timestamp.
* </para></listitem>
* </orderedlist>
*
* What needs to be done in applications?
- * Again its not a lot to change.
+ * Again it's not a lot to change.
* <orderedlist>
* <listitem><para>
- * first put some properties under control, by calling
- * gst_object_control_properties (object, "prop1", "prop2",...);
- * </para></listitem>
- * <listitem><para>
* create a #GstControlSource.
* csource = gst_interpolation_control_source_new ();
* g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
* </para></listitem>
* <listitem><para>
* Attach the #GstControlSource on the controller to a property.
- * gst_object_add_control_binding (object, gst_direct_control_binding_new (objetct, "prop1", csource));
+ * gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
* </para></listitem>
* <listitem><para>
* Set the control values
* </orderedlist>
* </para>
* </refsect2>
- *
- * Last reviewed on 2012-03-29 (0.11.3)
*/
#include "gst_private.h"
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);
/**
* 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
* 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)
/**
* 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
* 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)
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))) {
}
if (oldptr)
- g_object_unref (oldptr);
+ gst_object_unref (oldptr);
return oldptr != newobj;
}
* @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
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);
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]);
* @name: 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.
*
* 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
* 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.
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;
* 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
+ * Returns: (transfer full): parent of @object, this can be %NULL if @object
* has no parent. unref after usage.
*
* MT safe. Grabs and releases @object's LOCK.
* 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.
*/
* 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.
*/
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);
* @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
* @object: the controller object
* @binding: (transfer full): the #GstControlBinding that should be used
*
- * Sets the #GstControlBinding. If there already was a #GstControlBinding
- * for this property it will be replaced.
+ * Attach the #GstControlBinding to the object. If there already was a
+ * #GstControlBinding for this property it will be replaced.
+ *
* The @object will take ownership of the @binding.
*
- * 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)
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))) {
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);
* @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;
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 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:
projects / platform / upstream / gstreamer.git / blobdiff