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 #include "config.h"
  33 #include "gstcontroller.h"
  34
  35 #define GST_CAT_DEFAULT gst_controller_debug
  36 GST_DEBUG_CATEGORY_EXTERN (GST_CAT_DEFAULT);
  37
  38 extern GQuark __gst_controller_key;
  39
  40 /**
  41  * gst_object_control_properties:
  42  * @object: the object of which some properties should be controlled
  43  * @...: %NULL terminated list of property names that should be controlled
  44  *
  45  * Convenience function for GObject
  46  *
  47  * Creates a GstController that allows you to dynamically control one, or more, GObject properties.
  48  * If the given GObject already has a GstController, it adds the given properties to the existing
  49  * controller and returns that controller.
  50  *
  51  * Returns: The GstController with which the user can control the given properties dynamically or NULL if
  52  * one or more of the given properties aren't available, or cannot be controlled, for the given element.
  53  * Since: 0.9
  54  */
  55 GstController *
  56 gst_object_control_properties (GObject * object, ...)
  57 {
  58   GstController *ctrl;
  59
  60   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
  61
  62   va_list var_args;
  63
  64   va_start (var_args, object);
  65   ctrl = gst_controller_new_valist (object, var_args);
  66   va_end (var_args);
  67   return (ctrl);
  68 }
  69
  70 /**
  71  * gst_object_uncontrol_properties:
  72  * @object: the object of which some properties should not be controlled anymore
  73  * @...: %NULL terminated list of property names that should be controlled
  74  *
  75  * Convenience function for GObject
  76  *
  77  * Removes the given element's properties from it's controller
  78  *
  79  * Returns: %FALSE if one of the given property names isn't handled by the
  80  * controller, %TRUE otherwise
  81  * Since: 0.9
  82  */
  83 gboolean
  84 gst_object_uncontrol_properties (GObject * object, ...)
  85 {
  86   gboolean res = FALSE;
  87   GstController *ctrl;
  88
  89   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
  90
  91   if ((ctrl = g_object_get_qdata (object, __gst_controller_key))) {
  92     va_list var_args;
  93
  94     va_start (var_args, object);
  95     res = gst_controller_remove_properties_valist (ctrl, var_args);
  96     va_end (var_args);
  97   }
  98   return (res);
  99 }
 100
 101 /**
 102  * gst_object_get_controller:
 103  * @object: the object that has controlled properties
 104  *
 105  * Returns: the controller handling some of the given element's properties, %NULL if no controller
 106  * Since: 0.9
 107  */
 108 GstController *
 109 gst_object_get_controller (GObject * object)
 110 {
 111   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 112
 113   return (g_object_get_qdata (object, __gst_controller_key));
 114 }
 115
 116 /**
 117  * gst_object_set_controller:
 118  * @object: the object that should get the controller
 119  * @controller: the controller object to plug in
 120  *
 121  * Sets the controller on the given GObject
 122  *
 123  * Returns: %FALSE if the GObject already has an controller, %TRUE otherwise
 124  * Since: 0.9
 125  */
 126 gboolean
 127 gst_object_set_controller (GObject * object, GstController * controller)
 128 {
 129   GstController *ctrl;
 130
 131   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 132   g_return_val_if_fail (controller, FALSE);
 133
 134   if (!(ctrl = g_object_get_qdata (object, __gst_controller_key))) {
 135     g_object_set_qdata (object, __gst_controller_key, controller);
 136     return (TRUE);
 137   }
 138   return (FALSE);
 139 }
 140
 141 /**
 142  * gst_object_sync_values:
 143  * @object: the object that has controlled properties
 144  * @timestamp: the time that should be processed
 145  *
 146  * Convenience function for GObject
 147  *
 148  * Returns: same thing as gst_controller_sync_values()
 149  * Since: 0.9
 150  */
 151 gboolean
 152 gst_object_sync_values (GObject * object, GstClockTime timestamp)
 153 {
 154   GstController *ctrl = NULL;
 155
 156   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 157   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 158
 159   if ((ctrl = g_object_get_qdata (object, __gst_controller_key))) {
 160     return gst_controller_sync_values (ctrl, timestamp);
 161   }
 162   return (FALSE);
 163 }
 164
 165 /**
 166  * gst_object_get_value_arrays:
 167  * @object: the object that has controlled properties
 168  * @timestamp: the time that should be processed
 169  * @value_arrays: list to return the control-values in
 170  *
 171  * Function to be able to get an array of values for one or more given element
 172  * properties.
 173  *
 174  * If the GstValueArray->values array in list nodes is NULL, it will be created
 175  * by the function.
 176  * The type of the values in the array are the same as the property's type.
 177  *
 178  * The g_object_* functions are just convenience functions for GObject
 179  *
 180  * Returns: %TRUE if the given array(s) could be filled, %FALSE otherwise
 181  * Since: 0.9
 182  */
 183 gboolean
 184 gst_object_get_value_arrays (GObject * object, GstClockTime timestamp,
 185     GSList * value_arrays)
 186 {
 187   GstController *ctrl;
 188
 189   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 190   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 191
 192   if ((ctrl = g_object_get_qdata (object, __gst_controller_key))) {
 193     return gst_controller_get_value_arrays (ctrl, timestamp, value_arrays);
 194   }
 195   return (FALSE);
 196 }
 197
 198 /**
 199  * gst_object_get_value_array:
 200  * @object: the object that has controlled properties
 201  * @timestamp: the time that should be processed
 202  * @value_array: array to put control-values in
 203  *
 204  * Function to be able to get an array of values for one element properties
 205  *
 206  * If the GstValueArray->values array is NULL, it will be created by the function.
 207  * The type of the values in the array are the same as the property's type.
 208  *
 209  * The g_object_* functions are just convenience functions for GObject
 210  *
 211  * Returns: %TRUE if the given array(s) could be filled, %FALSE otherwise
 212  * Since: 0.9
 213  */
 214 gboolean
 215 gst_object_get_value_array (GObject * object, GstClockTime timestamp,
 216     GstValueArray * value_array)
 217 {
 218   GstController *ctrl;
 219
 220   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
 221   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
 222
 223   if ((ctrl = g_object_get_qdata (object, __gst_controller_key))) {
 224     return gst_controller_get_value_array (ctrl, timestamp, value_array);
 225   }
 226   return (FALSE);
 227 }