libs/gst/controller/gsthelper.c

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