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 } GstTimedValue;
  55
  56
  57 /**
  58  * GstValueArray:
  59  * @property_name: the name of the property this array belongs to
  60  * @nbsamples: number of samples requested
  61  * @sample_interval: interval between each sample
  62  * @values: pointer to the array
  63  *
  64  * Structure to receive multiple values at once.
  65  */
  66 typedef struct _GstValueArray
  67 {
  68   gchar *property_name;
  69   gint nbsamples;
  70   GstClockTime sample_interval;
  71   gpointer *values;
  72 } GstValueArray;
  73
  74
  75 /**
  76  * GstInterpolateMode:
  77  * @GST_INTERPOLATE_NONE: steps-like interpolation, default
  78  * @GST_INTERPOLATE_TRIGGER: returns the default value of the property,
  79  * except for times with specific values
  80  * @GST_INTERPOLATE_LINEAR: linear interpolation
  81  * @GST_INTERPOLATE_QUADRATIC: square interpolation (not yet available)
  82  * @GST_INTERPOLATE_CUBIC: cubic interpolation (not yet available)
  83  * @GST_INTERPOLATE_USER: user-provided interpolation (not yet available)
  84  *
  85  * The various interpolation modes available.
  86  */
  87 typedef enum
  88 {
  89   GST_INTERPOLATE_NONE,
  90   GST_INTERPOLATE_TRIGGER,
  91   GST_INTERPOLATE_LINEAR,
  92   GST_INTERPOLATE_QUADRATIC,
  93   GST_INTERPOLATE_CUBIC,
  94   GST_INTERPOLATE_USER
  95 } GstInterpolateMode;
  96
  97 /* type macros */
  98
  99 #define GST_TYPE_CONTROLLER            (gst_controller_get_type ())
 100 #define GST_CONTROLLER(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_CONTROLLER, GstController))
 101 #define GST_CONTROLLER_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_CONTROLLER, GstControllerClass))
 102 #define GST_IS_CONTROLLER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_CONTROLLER))
 103 #define GST_IS_CONTROLLER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_CONTROLLERE))
 104 #define GST_CONTROLLER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_CONTROLLER, GstControllerClass))
 105
 106 typedef struct _GstController GstController;
 107 typedef struct _GstControllerClass GstControllerClass;
 108 typedef struct _GstControllerPrivate GstControllerPrivate;
 109
 110
 111 /**
 112  * GstController:
 113  *
 114  * The instance structure of GstController
 115  */
 116
 117 struct _GstController
 118 {
 119   GObject parent;
 120
 121   GList *properties;  /* List of GstControlledProperty */
 122   GMutex *lock;       /* Secure property access, elements will access from threads */
 123   GObject *object;    /* the object we control */
 124
 125   /*< private >*/
 126   GstControllerPrivate *priv;
 127   gpointer       _gst_reserved[GST_PADDING - 1];
 128 };
 129
 130 struct _GstControllerClass
 131 {
 132   GObjectClass parent_class;
 133
 134   /*< private >*/
 135   gpointer       _gst_reserved[GST_PADDING];
 136 };
 137
 138 GType gst_controller_get_type (void);
 139
 140 /* GstController functions */
 141
 142 GstController *gst_controller_new_valist (GObject * object, va_list var_args);
 143 GstController *gst_controller_new_list (GObject * object, GList *list);
 144 GstController *gst_controller_new (GObject * object, ...) G_GNUC_NULL_TERMINATED;
 145
 146 gboolean gst_controller_remove_properties_valist (GstController * self,
 147     va_list var_args);
 148 gboolean gst_controller_remove_properties_list (GstController * self,
 149                                                 GList *list);
 150 gboolean gst_controller_remove_properties (GstController * self, ...) G_GNUC_NULL_TERMINATED;
 151
 152 gboolean gst_controller_set (GstController * self, gchar * property_name,
 153     GstClockTime timestamp, GValue * value);
 154 gboolean gst_controller_set_from_list (GstController * self,
 155     gchar * property_name, GSList * timedvalues);
 156
 157 gboolean gst_controller_unset (GstController * self, gchar * property_name,
 158     GstClockTime timestamp);
 159 gboolean gst_controller_unset_all (GstController * self, gchar * property_name);
 160
 161 GValue *gst_controller_get (GstController * self, gchar * property_name,
 162     GstClockTime timestamp);
 163 const GList *gst_controller_get_all (GstController * self,
 164     gchar * property_name);
 165
 166 GstClockTime gst_controller_suggest_next_sync (GstController *self);
 167 gboolean gst_controller_sync_values (GstController * self,
 168     GstClockTime timestamp);
 169
 170 gboolean gst_controller_get_value_arrays (GstController * self,
 171     GstClockTime timestamp, GSList * value_arrays);
 172 gboolean gst_controller_get_value_array (GstController * self,
 173     GstClockTime timestamp, GstValueArray * value_array);
 174
 175 gboolean gst_controller_set_interpolation_mode (GstController * self,
 176     gchar * property_name, GstInterpolateMode mode);
 177
 178
 179 /* GObject convenience functions */
 180
 181 GstController *gst_object_control_properties (GObject * object, ...) G_GNUC_NULL_TERMINATED;
 182 gboolean gst_object_uncontrol_properties (GObject * object, ...) G_GNUC_NULL_TERMINATED;
 183
 184 GstController *gst_object_get_controller (GObject * object);
 185 gboolean gst_object_set_controller (GObject * object, GstController * controller);
 186
 187 GstClockTime gst_object_suggest_next_sync (GObject * object);
 188 gboolean gst_object_sync_values (GObject * object, GstClockTime timestamp);
 189
 190 gboolean gst_object_get_value_arrays (GObject * object,
 191     GstClockTime timestamp, GSList * value_arrays);
 192 gboolean gst_object_get_value_array (GObject * object,
 193     GstClockTime timestamp, GstValueArray * value_array);
 194
 195 GstClockTime gst_object_get_control_rate (GObject * object);
 196 void gst_object_set_control_rate (GObject * object, GstClockTime control_rate);
 197
 198 /* lib init/done */
 199
 200 gboolean gst_controller_init (int * argc, char ***argv);
 201
 202 G_END_DECLS
 203 #endif /* __GST_CONTROLLER_H__ */