gst/gstcontroller.c

   1 /* GStreamer
   2  *
   3  * Copyright (C) 2005 Stefan Kost <ensonic at users dot sf dot net>
   4  *               2007 Sebastian Dröge <slomo@circular-chaos.org>
   5  *               2011 Stefan Sauer <ensonic at users dot sf dot net>
   6  *
   7  * gstcontroller.c: dynamic parameter control subsystem
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Library General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Library General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Library General Public
  20  * License along with this library; if not, write to the
  21  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  22  * Boston, MA 02111-1307, USA.
  23  */
  24
  25 /**
  26  * SECTION:gstcontroller
  27  * @short_description: dynamic parameter control subsystem
  28  *
  29  * The controller subsystem offers a lightweight way to adjust gobject
  30  * properties over stream-time. It works by using time-stamped value pairs that
  31  * are queued for element-properties. At run-time the elements continously pull
  32  * values changes for the current stream-time.
  33  *
  34  * What needs to be changed in a #GstElement?
  35  * Very little - it is just two steps to make a plugin controllable!
  36  * <orderedlist>
  37  *   <listitem><para>
  38  *     mark gobject-properties paramspecs that make sense to be controlled,
  39  *     by GST_PARAM_CONTROLLABLE.
  40  *   </para></listitem>
  41  *   <listitem><para>
  42  *     when processing data (get, chain, loop function) at the beginning call
  43  *     gst_object_sync_values(element,timestamp).
  44  *     This will made the controller to update all gobject properties that are under
  45  *     control with the current values based on timestamp.
  46  *   </para></listitem>
  47  * </orderedlist>
  48  *
  49  * What needs to be done in applications?
  50  * Again its not a lot to change.
  51  * <orderedlist>
  52  *   <listitem><para>
  53  *     first put some properties under control, by calling
  54  *     controller = gst_object_control_properties (object, "prop1", "prop2",...);
  55  *   </para></listitem>
  56  *   <listitem><para>
  57  *     create a #GstControlSource.
  58  *     csource = gst_interpolation_control_source_new ();
  59  *     gst_interpolation_control_source_set_interpolation_mode(csource, mode);
  60  *   </para></listitem>
  61  *   <listitem><para>
  62  *     Attach the #GstControlSource on the controller to a property.
  63  *     gst_controller_set_control_source (controller, "prop1", csource);
  64  *   </para></listitem>
  65  *   <listitem><para>
  66  *     Set the control values
  67  *     gst_interpolation_control_source_set (csource,0 * GST_SECOND, value1);
  68  *     gst_interpolation_control_source_set (csource,1 * GST_SECOND, value2);
  69  *   </para></listitem>
  70  *   <listitem><para>
  71  *     start your pipeline
  72  *   </para></listitem>
  73  * </orderedlist>
  74  */
  75
  76 #include "gst_private.h"
  77
  78 #include "gstobject.h"
  79 #include "gstclock.h"
  80 #include "gstinfo.h"
  81 #include "gstcontroller.h"
  82 #include "gstcontrolsource.h"
  83 #include "gstparamspecs.h"
  84
  85 #define GST_CAT_DEFAULT controller_debug
  86 GST_DEBUG_CATEGORY (GST_CAT_DEFAULT);
  87
  88 static GObjectClass *parent_class = NULL;
  89
  90 /* property ids */
  91 enum
  92 {
  93   PROP_CONTROL_RATE = 1
  94 };
  95
  96 struct _GstControllerPrivate
  97 {
  98   GstClockTime control_rate;
  99   GstClockTime last_sync;
 100 };
 101
 102 /* helper */
 103
 104 /*
 105  * GstControlledProperty:
 106  */
 107 typedef struct _GstControlledProperty
 108 {
 109   GParamSpec *pspec;            /* GParamSpec for this property */
 110   const gchar *name;            /* name of the property */
 111   GstControlSource *csource;    /* GstControlSource for this property */
 112   gboolean disabled;
 113   GValue last_value;
 114 } GstControlledProperty;
 115
 116 #define GST_CONTROLLED_PROPERTY(obj)    ((GstControlledProperty *)(obj))
 117
 118 /*
 119  * gst_controlled_property_new:
 120  * @object: for which object the controlled property should be set up
 121  * @name: the name of the property to be controlled
 122  *
 123  * Private method which initializes the fields of a new controlled property
 124  * structure.
 125  *
 126  * Returns: a freshly allocated structure or %NULL
 127  */
 128 static GstControlledProperty *
 129 gst_controlled_property_new (GstObject * object, const gchar * name)
 130 {
 131   GstControlledProperty *prop = NULL;
 132   GParamSpec *pspec;
 133
 134   GST_INFO ("trying to put property '%s' under control", name);
 135
 136   /* check if the object has a property of that name */
 137   if ((pspec =
 138           g_object_class_find_property (G_OBJECT_GET_CLASS (object), name))) {
 139     GST_DEBUG ("  psec->flags : 0x%08x", pspec->flags);
 140
 141     /* check if this param is witable && controlable && !construct-only */
 142     g_return_val_if_fail ((pspec->flags & (G_PARAM_WRITABLE |
 143                 GST_PARAM_CONTROLLABLE | G_PARAM_CONSTRUCT_ONLY)) ==
 144         (G_PARAM_WRITABLE | GST_PARAM_CONTROLLABLE), NULL);
 145
 146     if ((prop = g_slice_new (GstControlledProperty))) {
 147       prop->pspec = pspec;
 148       prop->name = pspec->name;
 149       prop->csource = NULL;
 150       prop->disabled = FALSE;
 151       memset (&prop->last_value, 0, sizeof (GValue));
 152       g_value_init (&prop->last_value, G_PARAM_SPEC_VALUE_TYPE (prop->pspec));
 153     }
 154   } else {
 155     GST_WARNING ("class '%s' has no property '%s'", G_OBJECT_TYPE_NAME (object),
 156         name);
 157   }
 158   return prop;
 159 }
 160
 161 /*
 162  * gst_controlled_property_free:
 163  * @prop: the object to free
 164  *
 165  * Private method which frees all data allocated by a #GstControlledProperty
 166  * instance.
 167  */
 168 static void
 169 gst_controlled_property_free (GstControlledProperty * prop)
 170 {
 171   if (prop->csource)
 172     g_object_unref (prop->csource);
 173   g_value_unset (&prop->last_value);
 174   g_slice_free (GstControlledProperty, prop);
 175 }
 176
 177 /*
 178  * gst_controller_find_controlled_property:
 179  * @self: the controller object to search for a property in
 180  * @name: the gobject property name to look for
 181  *
 182  * Searches the list of properties under control.
 183  *
 184  * Returns: a #GstControlledProperty object of %NULL if the property is not
 185  * being controlled.
 186  */
 187 static GstControlledProperty *
 188 gst_controller_find_controlled_property (GstController * self,
 189     const gchar * name)
 190 {
 191   GstControlledProperty *prop;
 192   GList *node;
 193
 194   for (node = self->properties; node; node = g_list_next (node)) {
 195     prop = node->data;
 196     /* FIXME: eventually use GQuark to speed it up */
 197     if (!strcmp (prop->name, name)) {
 198       return prop;
 199     }
 200   }
 201   GST_DEBUG ("controller does not (yet) manage property '%s'", name);
 202
 203   return NULL;
 204 }
 205
 206 /*
 207  * gst_controller_add_property:
 208  * @self: the controller object
 209  * @name: name of projecty in @object
 210  *
 211  * Creates a new #GstControlledProperty if there is none for property @name yet.
 212  *
 213  * Returns: %TRUE if the property has been added to the controller
 214  */
 215 static gboolean
 216 gst_controller_add_property (GstController * self, const gchar * name)
 217 {
 218   gboolean res = TRUE;
 219
 220   /* test if this property isn't yet controlled */
 221   if (!gst_controller_find_controlled_property (self, name)) {
 222     GstControlledProperty *prop;
 223
 224     /* create GstControlledProperty and add to self->properties list */
 225     if ((prop = gst_controlled_property_new (self->object, name))) {
 226       self->properties = g_list_prepend (self->properties, prop);
 227       GST_DEBUG_OBJECT (self->object, "property %s added", name);
 228     } else
 229       res = FALSE;
 230   } else {
 231     GST_WARNING_OBJECT (self->object, "trying to control property %s again",
 232         name);
 233   }
 234   return res;
 235 }
 236
 237 /*
 238  * gst_controller_remove_property:
 239  * @self: the controller object
 240  * @name: name of projecty in @object
 241  *
 242  * Removes a #GstControlledProperty for property @name.
 243  *
 244  * Returns: %TRUE if the property has been removed from the controller
 245  */
 246 static gboolean
 247 gst_controller_remove_property (GstController * self, const gchar * name)
 248 {
 249   gboolean res = TRUE;
 250   GstControlledProperty *prop;
 251
 252   if ((prop = gst_controller_find_controlled_property (self, name))) {
 253     self->properties = g_list_remove (self->properties, prop);
 254     //g_signal_handler_disconnect (self->object, prop->notify_handler_id);
 255     gst_controlled_property_free (prop);
 256     GST_DEBUG_OBJECT (self->object, "property %s removed", name);
 257   } else {
 258     res = FALSE;
 259   }
 260   return res;
 261 }
 262
 263 /* methods */
 264
 265 /**
 266  * gst_controller_new_valist:
 267  * @object: the object of which some properties should be controlled
 268  * @var_args: %NULL terminated list of property names that should be controlled
 269  *
 270  * Creates a new GstController for the given object's properties
 271  *
 272  * Returns: the new controller.
 273  */
 274 GstController *
 275 gst_controller_new_valist (GstObject * object, va_list var_args)
 276 {
 277   GstController *self;
 278   gchar *name;
 279
 280   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
 281
 282   /* FIXME: storing the controller into the object is ugly
 283    * we'd like to make the controller object completely internal
 284    */
 285   self = g_object_newv (GST_TYPE_CONTROLLER, 0, NULL);
 286   self->object = g_object_ref (object);
 287   object->ctrl = g_object_ref (self);
 288
 289   /* create GstControlledProperty for each property */
 290   while ((name = va_arg (var_args, gchar *))) {
 291     gst_controller_add_property (self, name);
 292   }
 293   va_end (var_args);
 294
 295   return self;
 296 }
 297
 298 /**
 299  * gst_controller_new_list:
 300  * @object: the object of which some properties should be controlled
 301  * @list: (transfer none) (element-type utf8): list of property names
 302  *   that should be controlled
 303  *
 304  * Creates a new GstController for the given object's properties
 305  *
 306  * Rename to: gst_controller_new
 307  *
 308  * Returns: the new controller.
 309  */
 310 GstController *
 311 gst_controller_new_list (GstObject * object, GList * list)
 312 {
 313   GstController *self;
 314   gchar *name;
 315   GList *node;
 316
 317   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
 318
 319   self = g_object_newv (GST_TYPE_CONTROLLER, 0, NULL);
 320   self->object = g_object_ref (object);
 321   object->ctrl = g_object_ref (self);
 322
 323   /* create GstControlledProperty for each property */
 324   for (node = list; node; node = g_list_next (node)) {
 325     name = (gchar *) node->data;
 326     gst_controller_add_property (self, name);
 327   }
 328
 329   return self;
 330 }
 331
 332 /**
 333  * gst_controller_new:
 334  * @object: the object of which some properties should be controlled
 335  * @...: %NULL terminated list of property names that should be controlled
 336  *
 337  * Creates a new GstController for the given object's properties
 338  *
 339  * Returns: the new controller.
 340  */
 341 GstController *
 342 gst_controller_new (GstObject * object, ...)
 343 {
 344   GstController *self;
 345   va_list var_args;
 346
 347   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
 348
 349   va_start (var_args, object);
 350   self = gst_controller_new_valist (object, var_args);
 351   va_end (var_args);
 352
 353   return self;
 354 }
 355
 356 // FIXME: docs
 357 gboolean
 358 gst_controller_add_properties_valist (GstController * self, va_list var_args)
 359 {
 360   gboolean res = TRUE;
 361   gchar *name;
 362
 363   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 364
 365   while ((name = va_arg (var_args, gchar *))) {
 366     /* find the property in the properties list of the controller, remove and free it */
 367     g_mutex_lock (self->lock);
 368     res &= gst_controller_add_property (self, name);
 369     g_mutex_unlock (self->lock);
 370   }
 371
 372   return res;
 373 }
 374
 375 // FIXME: docs
 376 gboolean
 377 gst_controller_add_properties_list (GstController * self, GList * list)
 378 {
 379   gboolean res = TRUE;
 380   gchar *name;
 381   GList *tmp;
 382
 383   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 384
 385   for (tmp = list; tmp; tmp = g_list_next (tmp)) {
 386     name = (gchar *) tmp->data;
 387
 388     /* find the property in the properties list of the controller, remove and free it */
 389     g_mutex_lock (self->lock);
 390     res &= gst_controller_add_property (self, name);
 391     g_mutex_unlock (self->lock);
 392   }
 393
 394   return res;
 395 }
 396
 397 // FIXME: docs
 398 gboolean
 399 gst_controller_add_properties (GstController * self, ...)
 400 {
 401   gboolean res;
 402   va_list var_args;
 403
 404   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 405
 406   va_start (var_args, self);
 407   res = gst_controller_add_properties_valist (self, var_args);
 408   va_end (var_args);
 409
 410   return res;
 411 }
 412
 413 /**
 414  * gst_controller_remove_properties_valist:
 415  * @self: the controller object from which some properties should be removed
 416  * @var_args: %NULL terminated list of property names that should be removed
 417  *
 418  * Removes the given object properties from the controller
 419  *
 420  * Returns: %FALSE if one of the given property isn't handled by the controller, %TRUE otherwise
 421  */
 422 gboolean
 423 gst_controller_remove_properties_valist (GstController * self, va_list var_args)
 424 {
 425   gboolean res = TRUE;
 426   gchar *name;
 427
 428   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 429
 430   while ((name = va_arg (var_args, gchar *))) {
 431     /* find the property in the properties list of the controller, remove and free it */
 432     g_mutex_lock (self->lock);
 433     res &= gst_controller_remove_property (self, name);
 434     g_mutex_unlock (self->lock);
 435   }
 436
 437   return res;
 438 }
 439
 440 /**
 441  * gst_controller_remove_properties_list:
 442  * @self: the controller object from which some properties should be removed
 443  * @list: (transfer none) (element-type utf8): #GList of property names that
 444  *   should be removed
 445  *
 446  * Removes the given object properties from the controller
 447  *
 448  * Rename to: gst_controller_remove_properties
 449  *
 450  * Returns: %FALSE if one of the given property isn't handled by the controller, %TRUE otherwise
 451  */
 452 gboolean
 453 gst_controller_remove_properties_list (GstController * self, GList * list)
 454 {
 455   gboolean res = TRUE;
 456   gchar *name;
 457   GList *tmp;
 458
 459   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 460
 461   for (tmp = list; tmp; tmp = g_list_next (tmp)) {
 462     name = (gchar *) tmp->data;
 463
 464     /* find the property in the properties list of the controller, remove and free it */
 465     g_mutex_lock (self->lock);
 466     res &= gst_controller_remove_property (self, name);
 467     g_mutex_unlock (self->lock);
 468   }
 469
 470   return res;
 471 }
 472
 473 /**
 474  * gst_controller_remove_properties:
 475  * @self: the controller object from which some properties should be removed
 476  * @...: %NULL terminated list of property names that should be removed
 477  *
 478  * Removes the given object properties from the controller
 479  *
 480  * Returns: %FALSE if one of the given property isn't handled by the controller, %TRUE otherwise
 481  */
 482 gboolean
 483 gst_controller_remove_properties (GstController * self, ...)
 484 {
 485   gboolean res;
 486   va_list var_args;
 487
 488   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 489
 490   va_start (var_args, self);
 491   res = gst_controller_remove_properties_valist (self, var_args);
 492   va_end (var_args);
 493
 494   return res;
 495 }
 496
 497 /**
 498  * gst_controller_is_active:
 499  * @self: the #GstController which should be disabled
 500  *
 501  * Check if the controller is active. It is active if it has at least one
 502  * controlled property that is not disabled.
 503  *
 504  * Returns: %TRUE if the controller is active
 505  */
 506 gboolean
 507 gst_controller_is_active (GstController * self)
 508 {
 509   gboolean active = FALSE;
 510   GList *node;
 511   GstControlledProperty *prop;
 512
 513   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 514
 515   g_mutex_lock (self->lock);
 516   for (node = self->properties; node; node = node->next) {
 517     prop = node->data;
 518     active |= !prop->disabled;
 519   }
 520   g_mutex_unlock (self->lock);
 521
 522   return active;
 523 }
 524
 525 /**
 526  * gst_controller_set_property_disabled:
 527  * @self: the #GstController which should be disabled
 528  * @property_name: property to disable
 529  * @disabled: boolean that specifies whether to disable the controller
 530  * or not.
 531  *
 532  * This function is used to disable the #GstController on a property for
 533  * some time, i.e. gst_controller_sync_values() will do nothing for the
 534  * property.
 535  */
 536 void
 537 gst_controller_set_property_disabled (GstController * self,
 538     const gchar * property_name, gboolean disabled)
 539 {
 540   GstControlledProperty *prop;
 541
 542   g_return_if_fail (GST_IS_CONTROLLER (self));
 543   g_return_if_fail (property_name);
 544
 545   g_mutex_lock (self->lock);
 546   if ((prop = gst_controller_find_controlled_property (self, property_name))) {
 547     prop->disabled = disabled;
 548   }
 549   g_mutex_unlock (self->lock);
 550 }
 551
 552 /**
 553  * gst_controller_set_disabled:
 554  * @self: the #GstController which should be disabled
 555  * @disabled: boolean that specifies whether to disable the controller
 556  * or not.
 557  *
 558  * This function is used to disable all properties of the #GstController
 559  * for some time, i.e. gst_controller_sync_values() will do nothing.
 560  */
 561
 562 void
 563 gst_controller_set_disabled (GstController * self, gboolean disabled)
 564 {
 565   GList *node;
 566   GstControlledProperty *prop;
 567
 568   g_return_if_fail (GST_IS_CONTROLLER (self));
 569
 570   g_mutex_lock (self->lock);
 571   for (node = self->properties; node; node = node->next) {
 572     prop = node->data;
 573     prop->disabled = disabled;
 574   }
 575   g_mutex_unlock (self->lock);
 576 }
 577
 578 /**
 579  * gst_controller_set_control_source:
 580  * @self: the controller object
 581  * @property_name: name of the property for which the #GstControlSource should be set
 582  * @csource: the #GstControlSource that should be used for the property
 583  *
 584  * Sets the #GstControlSource for @property_name. If there already was a #GstControlSource
 585  * for this property it will be unreferenced.
 586  *
 587  * Returns: %FALSE if the given property isn't handled by the controller or the new #GstControlSource
 588  * couldn't be bound to the property, %TRUE if everything worked as expected.
 589  */
 590 gboolean
 591 gst_controller_set_control_source (GstController * self,
 592     const gchar * property_name, GstControlSource * csource)
 593 {
 594   GstControlledProperty *prop;
 595   gboolean ret = FALSE;
 596
 597   g_mutex_lock (self->lock);
 598   if ((prop = gst_controller_find_controlled_property (self, property_name))) {
 599     GstControlSource *old = prop->csource;
 600
 601     if (csource && (ret = gst_control_source_bind (csource, prop->pspec))) {
 602       g_object_ref (csource);
 603       prop->csource = csource;
 604     } else if (!csource) {
 605       ret = TRUE;
 606       prop->csource = NULL;
 607     }
 608
 609     if (ret && old)
 610       g_object_unref (old);
 611   }
 612   g_mutex_unlock (self->lock);
 613
 614   return ret;
 615 }
 616
 617 /**
 618  * gst_controller_get_control_source:
 619  * @self: the controller object
 620  * @property_name: name of the property for which the #GstControlSource should be get
 621  *
 622  * Gets the corresponding #GstControlSource for the property. This should be unreferenced
 623  * again after use.
 624  *
 625  * Returns: (transfer full): the #GstControlSource for @property_name or NULL if
 626  * the property is not controlled by this controller or no #GstControlSource was
 627  * assigned yet.
 628  */
 629 GstControlSource *
 630 gst_controller_get_control_source (GstController * self,
 631     const gchar * property_name)
 632 {
 633   GstControlledProperty *prop;
 634   GstControlSource *ret = NULL;
 635
 636   g_return_val_if_fail (GST_IS_CONTROLLER (self), NULL);
 637   g_return_val_if_fail (property_name, NULL);
 638
 639   g_mutex_lock (self->lock);
 640   if ((prop = gst_controller_find_controlled_property (self, property_name))) {
 641     ret = prop->csource;
 642   }
 643   g_mutex_unlock (self->lock);
 644
 645   if (ret)
 646     g_object_ref (ret);
 647
 648   return ret;
 649 }
 650
 651 /**
 652  * gst_controller_get:
 653  * @self: the controller object which handles the properties
 654  * @property_name: the name of the property to get
 655  * @timestamp: the time the control-change should be read from
 656  *
 657  * Gets the value for the given controller-handled property at the requested
 658  * time.
 659  *
 660  * Returns: the GValue of the property at the given time, or %NULL if the
 661  * property isn't handled by the controller
 662  */
 663 GValue *
 664 gst_controller_get (GstController * self, const gchar * property_name,
 665     GstClockTime timestamp)
 666 {
 667   GstControlledProperty *prop;
 668   GValue *val = NULL;
 669
 670   g_return_val_if_fail (GST_IS_CONTROLLER (self), NULL);
 671   g_return_val_if_fail (property_name, NULL);
 672   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), NULL);
 673
 674   g_mutex_lock (self->lock);
 675   if ((prop = gst_controller_find_controlled_property (self, property_name))) {
 676     val = g_new0 (GValue, 1);
 677     g_value_init (val, G_PARAM_SPEC_VALUE_TYPE (prop->pspec));
 678     if (prop->csource) {
 679       gboolean res;
 680
 681       /* get current value via control source */
 682       res = gst_control_source_get_value (prop->csource, timestamp, val);
 683       if (!res) {
 684         g_free (val);
 685         val = NULL;
 686       }
 687     } else {
 688       g_object_get_property ((GObject *) self->object, prop->name, val);
 689     }
 690   }
 691   g_mutex_unlock (self->lock);
 692
 693   return val;
 694 }
 695
 696 /**
 697  * gst_controller_suggest_next_sync:
 698  * @self: the controller that handles the values
 699  *
 700  * Returns a suggestion for timestamps where buffers should be split
 701  * to get best controller results.
 702  *
 703  * Returns: Returns the suggested timestamp or %GST_CLOCK_TIME_NONE
 704  * if no control-rate was set.
 705  */
 706 GstClockTime
 707 gst_controller_suggest_next_sync (GstController * self)
 708 {
 709   GstClockTime ret;
 710
 711   g_return_val_if_fail (GST_IS_CONTROLLER (self), GST_CLOCK_TIME_NONE);
 712   g_return_val_if_fail (self->priv->control_rate != GST_CLOCK_TIME_NONE,
 713       GST_CLOCK_TIME_NONE);
 714
 715   g_mutex_lock (self->lock);
 716
 717   /* TODO: Implement more logic, depending on interpolation mode
 718    * and control points
 719    * FIXME: we need playback direction
 720    */
 721   ret = self->priv->last_sync + self->priv->control_rate;
 722
 723   g_mutex_unlock (self->lock);
 724
 725   return ret;
 726 }
 727
 728 /**
 729  * gst_controller_sync_values:
 730  * @self: the controller that handles the values
 731  * @timestamp: the time that should be processed
 732  *
 733  * Sets the properties of the element, according to the controller that (maybe)
 734  * handles them and for the given timestamp.
 735  *
 736  * If this function fails, it is most likely the application developers fault.
 737  * Most probably the control sources are not setup correctly.
 738  *
 739  * Returns: %TRUE if the controller values could be applied to the object
 740  * properties, %FALSE otherwise
 741  */
 742 gboolean
 743 gst_controller_sync_values (GstController * self, GstClockTime timestamp)
 744 {
 745   GstControlledProperty *prop;
 746   GList *node;
 747   gboolean ret = TRUE, val_ret;
 748   GValue value = { 0, };
 749
 750   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 751   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 752
 753   GST_LOG ("sync_values");
 754
 755   g_mutex_lock (self->lock);
 756   g_object_freeze_notify ((GObject *) self->object);
 757   /* go over the controlled properties of the controller */
 758   for (node = self->properties; node; node = g_list_next (node)) {
 759     prop = node->data;
 760
 761     if (!prop->csource || prop->disabled)
 762       continue;
 763
 764     GST_LOG ("property '%s' at ts=%" G_GUINT64_FORMAT, prop->name, timestamp);
 765
 766     /* we can make this faster
 767      * http://bugzilla.gnome.org/show_bug.cgi?id=536939
 768      */
 769     g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (prop->pspec));
 770     val_ret = gst_control_source_get_value (prop->csource, timestamp, &value);
 771     if (G_LIKELY (val_ret)) {
 772       /* always set the value for first time, but then only if it changed
 773        * this should limit g_object_notify invocations.
 774        * FIXME: can we detect negative playback rates?
 775        */
 776       if ((timestamp < self->priv->last_sync) ||
 777           gst_value_compare (&value, &prop->last_value) != GST_VALUE_EQUAL) {
 778         g_object_set_property ((GObject *) self->object, prop->name, &value);
 779         g_value_copy (&value, &prop->last_value);
 780       }
 781     } else {
 782       GST_DEBUG ("no control value for param %s", prop->name);
 783     }
 784     g_value_unset (&value);
 785     ret &= val_ret;
 786   }
 787   self->priv->last_sync = timestamp;
 788   g_object_thaw_notify ((GObject *) self->object);
 789
 790   g_mutex_unlock (self->lock);
 791
 792   return ret;
 793 }
 794
 795 /**
 796  * gst_controller_get_value_arrays:
 797  * @self: the controller that handles the values
 798  * @timestamp: the time that should be processed
 799  * @value_arrays: list to return the control-values in
 800  *
 801  * Function to be able to get an array of values for one or more given element
 802  * properties.
 803  *
 804  * All fields of the %GstValueArray in the list must be filled correctly.
 805  * Especially the GstValueArray->values arrays must be big enough to keep
 806  * the requested amount of values.
 807  *
 808  * The types of the values in the array are the same as the property's type.
 809  *
 810  * <note><para>This doesn't modify the controlled GObject properties!</para></note>
 811  *
 812  * Returns: %TRUE if the given array(s) could be filled, %FALSE otherwise
 813  */
 814 gboolean
 815 gst_controller_get_value_arrays (GstController * self,
 816     GstClockTime timestamp, GSList * value_arrays)
 817 {
 818   gboolean res = TRUE;
 819   GSList *node;
 820
 821   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 822   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 823   g_return_val_if_fail (value_arrays, FALSE);
 824
 825   for (node = value_arrays; (res && node); node = g_slist_next (node)) {
 826     res = gst_controller_get_value_array (self, timestamp, node->data);
 827   }
 828
 829   return (res);
 830 }
 831
 832 /**
 833  * gst_controller_get_value_array:
 834  * @self: the controller that handles the values
 835  * @timestamp: the time that should be processed
 836  * @value_array: array to put control-values in
 837  *
 838  * Function to be able to get an array of values for one element property.
 839  *
 840  * All fields of @value_array must be filled correctly. Especially the
 841  * @value_array->values array must be big enough to keep the requested amount
 842  * of values (as indicated by the nbsamples field).
 843  *
 844  * The type of the values in the array is the same as the property's type.
 845  *
 846  * <note><para>This doesn't modify the controlled GObject property!</para></note>
 847  *
 848  * Returns: %TRUE if the given array could be filled, %FALSE otherwise
 849  */
 850 gboolean
 851 gst_controller_get_value_array (GstController * self, GstClockTime timestamp,
 852     GstValueArray * value_array)
 853 {
 854   gboolean res = FALSE;
 855   GstControlledProperty *prop;
 856
 857   g_return_val_if_fail (GST_IS_CONTROLLER (self), FALSE);
 858   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 859   g_return_val_if_fail (value_array, FALSE);
 860   g_return_val_if_fail (value_array->property_name, FALSE);
 861   g_return_val_if_fail (value_array->values, FALSE);
 862
 863   g_mutex_lock (self->lock);
 864
 865   if ((prop =
 866           gst_controller_find_controlled_property (self,
 867               value_array->property_name))) {
 868     /* get current value_array via control source */
 869
 870     if (!prop->csource)
 871       goto out;
 872
 873     res =
 874         gst_control_source_get_value_array (prop->csource, timestamp,
 875         value_array);
 876   }
 877
 878 out:
 879   g_mutex_unlock (self->lock);
 880   return res;
 881 }
 882
 883 /* gobject handling */
 884
 885 static void
 886 _gst_controller_get_property (GObject * object, guint property_id,
 887     GValue * value, GParamSpec * pspec)
 888 {
 889   GstController *self = GST_CONTROLLER (object);
 890
 891   switch (property_id) {
 892     case PROP_CONTROL_RATE:{
 893       /* FIXME: don't change if element is playing, controller works for GObject
 894          so this wont work
 895
 896          GstState c_state, p_state;
 897          GstStateChangeReturn ret;
 898
 899          ret = gst_element_get_state (self->object, &c_state, &p_state, 0);
 900          if ((ret == GST_STATE_CHANGE_SUCCESS &&
 901          (c_state == GST_STATE_NULL || c_state == GST_STATE_READY)) ||
 902          (ret == GST_STATE_CHANGE_ASYNC &&
 903          (p_state == GST_STATE_NULL || p_state == GST_STATE_READY))) {
 904        */
 905       g_value_set_uint64 (value, self->priv->control_rate);
 906       /*
 907          }
 908          else {
 909          GST_WARNING ("Changing the control rate is only allowed if the elemnt"
 910          " is in NULL or READY");
 911          }
 912        */
 913     }
 914       break;
 915     default:{
 916       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 917     }
 918       break;
 919   }
 920 }
 921
 922 /* sets the given properties for this object */
 923 static void
 924 _gst_controller_set_property (GObject * object, guint property_id,
 925     const GValue * value, GParamSpec * pspec)
 926 {
 927   GstController *self = GST_CONTROLLER (object);
 928
 929   switch (property_id) {
 930     case PROP_CONTROL_RATE:{
 931       self->priv->control_rate = g_value_get_uint64 (value);
 932     }
 933       break;
 934     default:{
 935       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 936     }
 937       break;
 938   }
 939 }
 940
 941 static void
 942 _gst_controller_dispose (GObject * object)
 943 {
 944   GstController *self = GST_CONTROLLER (object);
 945
 946   if (self->object != NULL) {
 947     g_mutex_lock (self->lock);
 948     /* free list of properties */
 949     if (self->properties) {
 950       GList *node;
 951
 952       for (node = self->properties; node; node = g_list_next (node)) {
 953         GstControlledProperty *prop = node->data;
 954
 955         gst_controlled_property_free (prop);
 956       }
 957       g_list_free (self->properties);
 958       self->properties = NULL;
 959     }
 960
 961     g_object_unref (self->object);
 962     self->object = NULL;
 963     g_mutex_unlock (self->lock);
 964   }
 965
 966   if (G_OBJECT_CLASS (parent_class)->dispose)
 967     (G_OBJECT_CLASS (parent_class)->dispose) (object);
 968 }
 969
 970 static void
 971 _gst_controller_finalize (GObject * object)
 972 {
 973   GstController *self = GST_CONTROLLER (object);
 974
 975   g_mutex_free (self->lock);
 976
 977   if (G_OBJECT_CLASS (parent_class)->finalize)
 978     (G_OBJECT_CLASS (parent_class)->finalize) (object);
 979 }
 980
 981 static void
 982 _gst_controller_init (GTypeInstance * instance, gpointer g_class)
 983 {
 984   GstController *self = GST_CONTROLLER (instance);
 985
 986   self->lock = g_mutex_new ();
 987   self->priv =
 988       G_TYPE_INSTANCE_GET_PRIVATE (self, GST_TYPE_CONTROLLER,
 989       GstControllerPrivate);
 990   self->priv->last_sync = GST_CLOCK_TIME_NONE;
 991   self->priv->control_rate = 100 * GST_MSECOND;
 992 }
 993
 994 static void
 995 _gst_controller_class_init (GstControllerClass * klass)
 996 {
 997   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 998
 999   parent_class = g_type_class_peek_parent (klass);
1000   g_type_class_add_private (klass, sizeof (GstControllerPrivate));
1001
1002   gobject_class->set_property = _gst_controller_set_property;
1003   gobject_class->get_property = _gst_controller_get_property;
1004   gobject_class->dispose = _gst_controller_dispose;
1005   gobject_class->finalize = _gst_controller_finalize;
1006
1007   /* register properties */
1008   g_object_class_install_property (gobject_class, PROP_CONTROL_RATE,
1009       g_param_spec_uint64 ("control-rate",
1010           "control rate",
1011           "Controlled properties will be updated at least every control-rate nanoseconds",
1012           1, G_MAXUINT, 100 * GST_MSECOND,
1013           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
1014
1015   GST_DEBUG_CATEGORY_INIT (GST_CAT_DEFAULT, "gstcontroller", 0,
1016       "dynamic parameter control for gstreamer elements");
1017 }
1018
1019 GType
1020 gst_controller_get_type (void)
1021 {
1022   static volatile gsize type = 0;
1023
1024   if (g_once_init_enter (&type)) {
1025     GType _type;
1026     static const GTypeInfo info = {
1027       sizeof (GstControllerClass),
1028       NULL,                     /* base_init */
1029       NULL,                     /* base_finalize */
1030       (GClassInitFunc) _gst_controller_class_init,      /* class_init */
1031       NULL,                     /* class_finalize */
1032       NULL,                     /* class_data */
1033       sizeof (GstController),
1034       0,                        /* n_preallocs */
1035       (GInstanceInitFunc) _gst_controller_init, /* instance_init */
1036       NULL                      /* value_table */
1037     };
1038     _type = g_type_register_static (G_TYPE_OBJECT, "GstController", &info, 0);
1039     g_once_init_leave (&type, _type);
1040   }
1041   return type;
1042 }