## GstControlSource

GstControlSource — base class for control source sources

## Synopsis

    #include <gst/gst.h>

                        GstValueArray;
    struct              GstControlSource;
    struct              GstControlSourceClass;
    gboolean            (*GstControlSourceGetValue)         (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             gdouble *value);
    gboolean            (*GstControlSourceGetValueArray)    (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GstClockTime interval,
                                                             guint n_values,
                                                             gdouble *values);
    struct              GstTimedValue;
    gboolean            gst_control_source_get_value        (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             gdouble *value);
    gboolean            gst_control_source_get_value_array  (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GstClockTime interval,
                                                             guint n_values,
                                                             gdouble *values);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GstObject
                   +----GstControlSource

## Description

The GstControlSource is a base class for control value sources that could be used by GstController to get timestamp-value pairs.

A GstControlSource is used by first getting an instance, binding it to a GParamSpec (for example by using `gst_controller_set_control_source()`) and then by having it used by the GstController or calling `gst_control_source_get_value()` or `gst_control_source_get_value_array()`.

For implementing a new GstControlSource one has to implement a GstControlSourceBind method, which will depending on the GParamSpec set up the control source for use and sets the GstControlSourceGetValue and GstControlSourceGetValueArray functions. These are then used by `gst_control_source_get_value()` or `gst_control_source_get_value_array()` to get values for specific timestamps.

## Details

### GstValueArray

    typedef struct _GstValueArray GstValueArray;

### struct GstControlSource

    struct GstControlSource {
      GstControlSourceGetValue get_value;             /* Returns the value for a property at a given timestamp */
      GstControlSourceGetValueArray get_value_array;  /* Returns values for a property in a given timespan */
    };

The instance structure of GstControlSource.

GstControlSourceGetValue `get_value`; | Function for returning a value for a given timestamp
GstControlSourceGetValueArray `get_value_array`; | Function for returning a GstValueArray for a given timestamp

### struct GstControlSourceClass

    struct GstControlSourceClass {
      GstObjectClass parent_class;
    };

The class structure of GstControlSource.

GstObjectClass `parent_class`; | Parent class

### GstControlSourceGetValue ()

    gboolean            (*GstControlSourceGetValue)         (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             gdouble *value);

Function for returning a value for a given timestamp.

`self` : | the GstControlSource instance
`timestamp` : | timestamp for which a value should be calculated
`value` : | a GValue which will be set to the result. It must be initialized to the correct type.
Returns : | `TRUE` if the value was successfully calculated.

### GstControlSourceGetValueArray ()

    gboolean            (*GstControlSourceGetValueArray)    (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GstClockTime interval,
                                                             guint n_values,
                                                             gdouble *values);

Function for returning an array of values for starting at a given timestamp.

`self` : | the GstControlSource instance
`timestamp` : | timestamp for which a value should be calculated
`interval` : | the time spacing between subsequent values
`n_values` : | the number of values
`values` : | array to put control-values in
Returns : | `TRUE` if the values were successfully calculated.

### struct GstTimedValue

    struct GstTimedValue {
      GstClockTime timestamp;
      gdouble      value;
    };

Structure for saving a timestamp and a value.

GstClockTime `timestamp`; | timestamp of the value change
gdouble `value`; | the corresponding value

### gst_control_source_get_value ()

    gboolean            gst_control_source_get_value        (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             gdouble *value);

Gets the value for this GstControlSource at a given timestamp.

`self` : | the GstControlSource object
`timestamp` : | the time for which the value should be returned
`value` : | the value
Returns : | FALSE if the value couldn't be returned, TRUE otherwise.

### gst_control_source_get_value_array ()

    gboolean            gst_control_source_get_value_array  (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GstClockTime interval,
                                                             guint n_values,
                                                             gdouble *values);

Gets an array of values for for this GstControlSource. Values that are undefined contain NANs.

`self` : | the GstControlSource object
`timestamp` : | the first timestamp
`interval` : | the time steps
`n_values` : | the number of values to fetch
`values` : | array to put control-values in
Returns : | `TRUE` if the given array could be filled, `FALSE` otherwise