libs/gst/controller/gsthelper.c

   1 /* GStreamer
   2  *
   3  * Copyright (C) <2005> Stefan Kost <ensonic at users dot sf dot net>
   4  *
   5  * gsthelper.c: GObject convenience methods for using dynamic properties
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstcontrollergobject
  25  * @short_description: #GObject convinience methods for using dynamic properties
  26  * @see_also: #GstController
  27  *
  28  * These methods allow to use some #GstController functionallity directly from
  29  * the #GObject class.
  30  */
  31
  32 #ifdef HAVE_CONFIG_H
  33 #  include "config.h"
  34 #endif
  35
  36 #include <stdarg.h>
  37
  38 #include "gstcontrollerprivate.h"
  39 #include "gstcontroller.h"
  40
  41 #define GST_CAT_DEFAULT controller_debug
  42 GST_DEBUG_CATEGORY_EXTERN (GST_CAT_DEFAULT);
  43
  44 /**
  45  * gst_object_control_properties:
  46  * @object: the object of which some properties should be controlled
  47  * @...: %NULL terminated list of property names that should be controlled
  48  *
  49  * Convenience function for GObject
  50  *
  51  * Creates a GstController that allows you to dynamically control one, or more, GObject properties.
  52  * If the given GObject already has a GstController, it adds the given properties to the existing
  53  * controller and returns that controller.
  54  *
  55  * Returns: The GstController with which the user can control the given properties dynamically or NULL if
  56  * one or more of the given properties aren't available, or cannot be controlled, for the given element.
  57  * Since: 0.9
  58  */
  59 GstController *
  60 gst_object_control_properties (GObject * object, ...)
  61 {
  62   GstController *ctrl;
  63   va_list var_args;
  64
  65   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
  66
  67   va_start (var_args, object);
  68   ctrl = gst_controller_new_valist (object, var_args);
  69   va_end (var_args);
  70   return (ctrl);
  71 }
  72
  73 /**
  74  * gst_object_uncontrol_properties:
  75  * @object: the object of which some properties should not be controlled anymore
  76  * @...: %NULL terminated list of property names that should be controlled
  77  *
  78  * Convenience function for GObject
  79  *
  80  * Removes the given element's properties from it's controller
  81  *
  82  * Returns: %FALSE if one of the given property names isn't handled by the
  83  * controller, %TRUE otherwise
  84  * Since: 0.9
  85  */
  86 gboolean
  87 gst_object_uncontrol_properties (GObject * object, ...)
  88 {
  89   gboolean res = FALSE;
  90   GstController *ctrl;
  91
  92   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
  93
  94   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
  95     va_list var_args;
  96
  97     va_start (var_args, object);
  98     res = gst_controller_remove_properties_valist (ctrl, var_args);
  99     va_end (var_args);
 100   }
 101   return (res);
 102 }
 103
 104 /**
 105  * gst_object_get_controller:
 106  * @object: the object that has controlled properties
 107  *
 108  * Gets the controller for the given GObject
 109  *
 110  * Returns: the controller handling some of the given element's properties, %NULL if no controller
 111  * Since: 0.9
 112  */
 113 GstController *
 114 gst_object_get_controller (GObject * object)
 115 {
 116   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
 117
 118   return (g_object_get_qdata (object, priv_gst_controller_key));
 119 }
 120
 121 /**
 122  * gst_object_set_controller:
 123  * @object: the object that should get the controller
 124  * @controller: the controller object to plug in
 125  *
 126  * Sets the controller on the given GObject
 127  *
 128  * Returns: %FALSE if the GObject already has an controller, %TRUE otherwise
 129  * Since: 0.9
 130  */
 131 gboolean
 132 gst_object_set_controller (GObject * object, GstController * controller)
 133 {
 134   GstController *ctrl;
 135
 136   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 137   g_return_val_if_fail (controller, FALSE);
 138
 139   if (!(ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 140     g_object_set_qdata (object, priv_gst_controller_key, controller);
 141     return (TRUE);
 142   }
 143   return (FALSE);
 144 }
 145
 146  /**
 147  * gst_object_suggest_next_sync:
 148  * @object: the object that has controlled properties
 149  *
 150  * Convenience function for GObject
 151  *
 152  * Returns: same thing as gst_controller_suggest_next_sync()
 153  * Since: 0.10.13
 154  */
 155 GstClockTime
 156 gst_object_suggest_next_sync (GObject * object)
 157 {
 158   GstController *ctrl = NULL;
 159
 160   g_return_val_if_fail (G_IS_OBJECT (object), GST_CLOCK_TIME_NONE);
 161
 162   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 163     return gst_controller_suggest_next_sync (ctrl);
 164   }
 165   return (GST_CLOCK_TIME_NONE);
 166 }
 167
 168 /**
 169  * gst_object_sync_values:
 170  * @object: the object that has controlled properties
 171  * @timestamp: the time that should be processed
 172  *
 173  * Convenience function for GObject
 174  *
 175  * Returns: same thing as gst_controller_sync_values()
 176  * Since: 0.9
 177  */
 178 gboolean
 179 gst_object_sync_values (GObject * object, GstClockTime timestamp)
 180 {
 181   GstController *ctrl = NULL;
 182
 183   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 184
 185   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 186     return gst_controller_sync_values (ctrl, timestamp);
 187   }
 188   /* this is no failure, its called by elements regardless if there is a
 189    * controller assigned or not
 190    */
 191   return (TRUE);
 192 }
 193
 194 /**
 195  * gst_object_set_control_source:
 196  * @object: the controller object
 197  * @property_name: name of the property for which the #GstControlSource should be set
 198  * @csource: the #GstControlSource that should be used for the property
 199  *
 200  * Sets the #GstControlSource for @property_name. If there already was a #GstControlSource
 201  * for this property it will be unreferenced.
 202  *
 203  * Returns: %FALSE if the given property isn't handled by the controller or the new #GstControlSource
 204  * couldn't be bound to the property, %TRUE if everything worked as expected.
 205  *
 206  * Since: 0.10.14
 207  */
 208 gboolean
 209 gst_object_set_control_source (GObject * object, gchar * property_name,
 210     GstControlSource * csource)
 211 {
 212   GstController *ctrl = NULL;
 213
 214   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 215   g_return_val_if_fail (GST_IS_CONTROL_SOURCE (csource), FALSE);
 216
 217   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 218     return gst_controller_set_control_source (ctrl, property_name, csource);
 219   }
 220   return FALSE;
 221 }
 222
 223 /**
 224  * gst_object_get_control_source:
 225  * @object: the object
 226  * @property_name: name of the property for which the #GstControlSource should be get
 227  *
 228  * Gets the corresponding #GstControlSource for the property. This should be unreferenced
 229  * again after use.
 230  *
 231  * Returns: the #GstControlSource for @property_name or NULL if the property is not
 232  * controlled by this controller or no #GstControlSource was assigned yet.
 233  *
 234  * Since: 0.10.14
 235  */
 236 GstControlSource *
 237 gst_object_get_control_source (GObject * object, gchar * property_name)
 238 {
 239   GstController *ctrl = NULL;
 240
 241   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
 242
 243   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 244     return gst_controller_get_control_source (ctrl, property_name);
 245   }
 246   return NULL;
 247 }
 248
 249 /**
 250  * gst_object_get_value_arrays:
 251  * @object: the object that has controlled properties
 252  * @timestamp: the time that should be processed
 253  * @value_arrays: list to return the control-values in
 254  *
 255  * Function to be able to get an array of values for one or more given element
 256  * properties.
 257  *
 258  * If the GstValueArray->values array in list nodes is NULL, it will be created
 259  * by the function.
 260  * The type of the values in the array are the same as the property's type.
 261  *
 262  * The g_object_* functions are just convenience functions for GObject
 263  *
 264  * Returns: %TRUE if the given array(s) could be filled, %FALSE otherwise
 265  * Since: 0.9
 266  */
 267 gboolean
 268 gst_object_get_value_arrays (GObject * object, GstClockTime timestamp,
 269     GSList * value_arrays)
 270 {
 271   GstController *ctrl;
 272
 273   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 274   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 275
 276   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 277     return gst_controller_get_value_arrays (ctrl, timestamp, value_arrays);
 278   }
 279   return (FALSE);
 280 }
 281
 282 /**
 283  * gst_object_get_value_array:
 284  * @object: the object that has controlled properties
 285  * @timestamp: the time that should be processed
 286  * @value_array: array to put control-values in
 287  *
 288  * Function to be able to get an array of values for one element properties
 289  *
 290  * If the GstValueArray->values array is NULL, it will be created by the function.
 291  * The type of the values in the array are the same as the property's type.
 292  *
 293  * The g_object_* functions are just convenience functions for GObject
 294  *
 295  * Returns: %TRUE if the given array(s) could be filled, %FALSE otherwise
 296  * Since: 0.9
 297  */
 298 gboolean
 299 gst_object_get_value_array (GObject * object, GstClockTime timestamp,
 300     GstValueArray * value_array)
 301 {
 302   GstController *ctrl;
 303
 304   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 305   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 306
 307   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 308     return gst_controller_get_value_array (ctrl, timestamp, value_array);
 309   }
 310   return (FALSE);
 311 }
 312
 313 /**
 314  * gst_object_get_control_rate:
 315  * @object: the object that has controlled properties
 316  *
 317  * Obtain the control-rate for this @object. Audio processing #GstElement
 318  * objects will use this rate to sub-divide their processing loop and call
 319  * gst_object_sync_values() inbetween. The length of the processing segment
 320  * should be up to @control-rate nanoseconds.
 321  *
 322  * If the @object is not under property control, this will return
 323  * %GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.
 324  *
 325  * The control-rate is not expected to change if the element is in
 326  * %GST_STATE_PAUSED or %GST_STATE_PLAYING.
 327  *
 328  * Returns: the control rate in nanoseconds
 329  * Since: 0.10.10
 330  */
 331 GstClockTime
 332 gst_object_get_control_rate (GObject * object)
 333 {
 334   GstController *ctrl;
 335   GstClockTime control_rate = GST_CLOCK_TIME_NONE;
 336
 337   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 338
 339   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 340     g_object_get (ctrl, "control-rate", &control_rate, NULL);
 341   }
 342   return (control_rate);
 343 }
 344
 345 /**
 346  * gst_object_set_control_rate:
 347  * @object: the object that has controlled properties
 348  * @control_rate: the new control-rate in nanoseconds.
 349  *
 350  * Change the control-rate for this @object. Audio processing #GstElement
 351  * objects will use this rate to sub-divide their processing loop and call
 352  * gst_object_sync_values() inbetween. The length of the processing segment
 353  * should be up to @control-rate nanoseconds.
 354  *
 355  * The control-rate should not change if the element is in %GST_STATE_PAUSED or
 356  * %GST_STATE_PLAYING.
 357  *
 358  * Since: 0.10.10
 359  */
 360 void
 361 gst_object_set_control_rate (GObject * object, GstClockTime control_rate)
 362 {
 363   GstController *ctrl;
 364
 365   g_return_if_fail (G_IS_OBJECT (object));
 366
 367   if ((ctrl = g_object_get_qdata (object, priv_gst_controller_key))) {
 368     g_object_set (ctrl, "control-rate", control_rate, NULL);
 369   }
 370 }