libs/gst/controller/gstcontroller.h

   1 /* GStreamer
   2  *
   3  * Copyright (C) <2005> Stefan Kost <ensonic at users dot sf dot net>
   4  *
   5  * gst-controller.h: dynamic parameter control subsystem
   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 #ifndef __GST_CONTROLLER_H__
  24 #define __GST_CONTROLLER_H__
  25
  26 #include <string.h>
  27
  28 #include <glib.h>
  29 #include <glib-object.h>
  30 #include <glib/gprintf.h>
  31 #include <gst/gst.h>
  32
  33 G_BEGIN_DECLS
  34
  35 /**
  36  * GST_PARAM_CONTROLLABLE:
  37  *
  38  * Use this flag on GstElement properties you wish to be (eventually) handled
  39  * by a GstController.
  40  * TODO: needs to go to gstelemnt.h (to avoid clashes on G_PARAM_USER_SHIFT)
  41  */
  42 #define GST_PARAM_CONTROLLABLE  (1 << (G_PARAM_USER_SHIFT + 1))
  43
  44
  45 /**
  46  * GstTimedValue:
  47  *
  48  * a structure for value+time
  49  */
  50 typedef struct _GstTimedValue
  51 {
  52   GstClockTime timestamp;       /* timestamp of the value change */
  53   GValue value;                 /* the new value */
  54   /* TODO what about storing the difference to next timestamp and value here
  55      + make calculations slightly easier and faster
  56      - determining the GType for the value_dif is not simple
  57      e.g. if value is G_TYPE_UCHAR value_diff needs to be G_TYPE_INT
  58    */
  59 } GstTimedValue;
  60
  61
  62 /**
  63  * GstValueArray:
  64  * @property_name: the name of the property this array belongs to
  65  * @nbsamples: number of samples requested
  66  * @sample_interval: interval between each sample
  67  * @values: pointer to the array
  68  *
  69  * Structure to receive multiple values at once.
  70  * If the pointer to the values array is NULL, it will be allocated (CHECKME).
  71  */
  72 typedef struct _GstValueArray
  73 {
  74   gchar *property_name;
  75   gint nbsamples;
  76   GstClockTime sample_interval;
  77   gpointer *values;
  78 } GstValueArray;
  79
  80
  81 /**
  82  * GstInterpolateMode:
  83  * @GST_INTERPOLATE_NONE: steps-like interpolation, default
  84  * @GST_INTERPOLATE_TRIGGER: returns the default value of the property,
  85  * except for times with specific values
  86  * @GST_INTERPOLATE_LINEAR: linear interpolation
  87  * @GST_INTERPOLATE_QUADRATIC: square interpolation
  88  * @GST_INTERPOLATE_CUBIC: cubic interpolation
  89  * @GST_INTERPOLATE_USER: user-provided interpolation
  90  *
  91  * The various interpolation modes available.
  92  */
  93 typedef enum
  94 {
  95   GST_INTERPOLATE_NONE,
  96   GST_INTERPOLATE_TRIGGER,
  97   GST_INTERPOLATE_LINEAR,
  98   GST_INTERPOLATE_QUADRATIC,
  99   GST_INTERPOLATE_CUBIC,
 100   GST_INTERPOLATE_USER
 101 } GstInterpolateMode;
 102
 103
 104 struct _GstControlledProperty;
 105
 106 typedef GValue *(*InterpolateGet) (struct _GstControlledProperty * prop,
 107         GstClockTime timestamp);
 108 typedef gboolean (*InterpolateGetValueArray) (struct _GstControlledProperty * prop,
 109         GstClockTime timestamp, GstValueArray * value_array);
 110
 111 /**
 112  * GstInterpolateMethod:
 113  *
 114  * Function pointer structure to do user-defined interpolation methods
 115  */
 116 typedef struct _GstInterpolateMethod
 117 {
 118   InterpolateGet get_int;
 119   InterpolateGetValueArray get_int_value_array;
 120   InterpolateGet get_uint;
 121   InterpolateGetValueArray get_uint_value_array;
 122   InterpolateGet get_long;
 123   InterpolateGetValueArray get_long_value_array;
 124   InterpolateGet get_ulong;
 125   InterpolateGetValueArray get_ulong_value_array;
 126   InterpolateGet get_float;
 127   InterpolateGetValueArray get_float_value_array;
 128   InterpolateGet get_double;
 129   InterpolateGetValueArray get_double_value_array;
 130   InterpolateGet get_boolean;
 131   InterpolateGetValueArray get_boolean_value_array;
 132 } GstInterpolateMethod;
 133
 134 /**
 135  * GstControlledProperty:
 136  */
 137 typedef struct _GstControlledProperty
 138 {
 139   gchar *name;                  /* name of the property */
 140   GType type;                   /* type of the handled property */
 141   GValue default_value;         /* default value for the handled property */
 142   GValue result_value;          /* result value location for the interpolation method */
 143   GstTimedValue last_value;     /* the last value a _sink call wrote */
 144   GstTimedValue live_value;     /* temporary value override for live input */
 145   gulong notify_handler_id;     /* id of the notify::<name> signal handler */
 146   GstInterpolateMode interpolation;     /* Interpolation mode */
 147   /* TODO instead of *method, have pointers to get() and get_value_array() here
 148      gst_controller_set_interpolation_mode() will pick the right ones for the
 149      properties value type
 150      GstInterpolateMethod *method; // User-implemented handler (if interpolation == GST_INTERPOLATE_USER)
 151   */
 152   InterpolateGet get;
 153   InterpolateGetValueArray get_value_array;
 154
 155   GList *values;                /* List of GstTimedValue */
 156   /* TODO keep the last search result to be able to continue
 157      GList      *last_value;     // last search result, can be used for incremental searches
 158    */
 159
 160   /*< private >*/
 161   gpointer       _gst_reserved[GST_PADDING];
 162 } GstControlledProperty;
 163
 164 #define GST_CONTROLLED_PROPERTY(obj)    ((GstControlledProperty *)(obj))
 165
 166 /* type macros */
 167
 168 #define GST_TYPE_CONTROLLER            (gst_controller_get_type ())
 169 #define GST_CONTROLLER(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_CONTROLLER, GstController))
 170 #define GST_CONTROLLER_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_CONTROLLER, GstControllerClass))
 171 #define GST_IS_CONTROLLER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_CONTROLLER))
 172 #define GST_IS_CONTROLLER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_CONTROLLERE))
 173 #define GST_CONTROLLER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_CONTROLLER, GstControllerClass))
 174
 175 typedef struct _GstController GstController;
 176 typedef struct _GstControllerClass GstControllerClass;
 177
 178 /**
 179  * GstController:
 180  *
 181  * The instance structure of GstController
 182  */
 183
 184 struct _GstController
 185 {
 186   GObject parent;
 187
 188   GList *properties;  /* List of GstControlledProperty */
 189   GMutex *lock;       /* Secure property access, elements will access from threads */
 190   GObject *object;    /* the object we control */
 191
 192   /*< private >*/
 193   gpointer       _gst_reserved[GST_PADDING];
 194 };
 195
 196 struct _GstControllerClass
 197 {
 198   GObjectClass parent_class;
 199
 200   /*< private >*/
 201   gpointer       _gst_reserved[GST_PADDING];
 202 };
 203
 204 GType gst_controller_get_type (void);
 205
 206 /* GstController functions */
 207
 208 GstController *gst_controller_new_valist (GObject * object, va_list var_args);
 209 GstController *gst_controller_new_list (GObject * object, GList *list);
 210 GstController *gst_controller_new (GObject * object, ...) G_GNUC_NULL_TERMINATED;
 211
 212 gboolean gst_controller_remove_properties_valist (GstController * self,
 213     va_list var_args);
 214 gboolean gst_controller_remove_properties_list (GstController * self,
 215                                                 GList *list);
 216 gboolean gst_controller_remove_properties (GstController * self, ...) G_GNUC_NULL_TERMINATED;
 217
 218 gboolean gst_controller_set (GstController * self, gchar * property_name,
 219     GstClockTime timestamp, GValue * value);
 220 gboolean gst_controller_set_from_list (GstController * self,
 221     gchar * property_name, GSList * timedvalues);
 222
 223 gboolean gst_controller_unset (GstController * self, gchar * property_name,
 224     GstClockTime timestamp);
 225
 226
 227 GValue *gst_controller_get (GstController * self, gchar * property_name,
 228     GstClockTime timestamp);
 229 const GList *gst_controller_get_all (GstController * self,
 230     gchar * property_name);
 231
 232
 233 gboolean gst_controller_sync_values (GstController * self,
 234     GstClockTime timestamp);
 235
 236 gboolean gst_controller_get_value_arrays (GstController * self,
 237     GstClockTime timestamp, GSList * value_arrays);
 238 gboolean gst_controller_get_value_array (GstController * self,
 239     GstClockTime timestamp, GstValueArray * value_array);
 240
 241 gboolean gst_controller_set_interpolation_mode (GstController * self,
 242     gchar * property_name, GstInterpolateMode mode);
 243
 244
 245 /* GObject convenience functions */
 246
 247 GstController *gst_object_control_properties (GObject * object, ...) G_GNUC_NULL_TERMINATED;
 248 gboolean gst_object_uncontrol_properties (GObject * object, ...) G_GNUC_NULL_TERMINATED;
 249
 250 GstController *gst_object_get_controller (GObject * object);
 251 gboolean gst_object_set_controller (GObject * object, GstController * controller);
 252
 253 gboolean gst_object_sync_values (GObject * object, GstClockTime timestamp);
 254
 255 gboolean gst_object_get_value_arrays (GObject * object,
 256     GstClockTime timestamp, GSList * value_arrays);
 257 gboolean gst_object_get_value_array (GObject * object,
 258     GstClockTime timestamp, GstValueArray * value_array);
 259
 260 /* lib init/done */
 261
 262 gboolean gst_controller_init (int * argc, char ***argv);
 263
 264 G_END_DECLS
 265 #endif /* __GST_CONTROLLER_H__ */