GstControlSource

## 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 control source essentially is a function over time, returning gloat values between 0.0 and 1.0.

A GstControlSource is used by first getting an instance of a specific control-source, creating a binding for the control-source to the target property of the element and then adding the binding to the element. The binding will convert the data types and value range to fit to the bound property.

For implementing a new GstControlSource one has to implement GstControlSourceGetValue and GstControlSourceGetValueArray functions. These are then used by `gst_control_source_get_value()` and `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