## GstControlSource

GstControlSource — base class for control source sources

## Synopsis

    #include <libs/controller/gstcontrolsource.h>

    struct              GstControlSource;
    struct              GstControlSourceClass;
    gboolean            (*GstControlSourceBind)             (GstControlSource *self,
                                                             GParamSpec *pspec);
    gboolean            (*GstControlSourceGetValue)         (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GValue *value);
    gboolean            (*GstControlSourceGetValueArray)    (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GstValueArray *value_array);
    struct              GstTimedValue;
    struct              GstValueArray;
    gboolean            gst_control_source_bind             (GstControlSource *self,
                                                             GParamSpec *pspec);
    gboolean            gst_control_source_get_value        (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GValue *value);
    gboolean            gst_control_source_get_value_array  (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GstValueArray *value_array);

## Object Hierarchy

      GObject
       +----GstControlSource
             +----GstInterpolationControlSource
             +----GstLFOControlSource

## 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

### 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 {
      GObjectClass parent_class;

      GstControlSourceBind bind;  /* Binds the GstControlSource to a specific GParamSpec */
    };

The class structure of GstControlSource.

GObjectClass `parent_class`; | Parent class
GstControlSourceBind `bind`; | Class method for binding the GstControlSource to a specific GParamSpec

### GstControlSourceBind ()

    gboolean            (*GstControlSourceBind)             (GstControlSource *self,
                                                             GParamSpec *pspec);

Function for binding a GstControlSource to a GParamSpec.

`self` : | the GstControlSource instance
`pspec` : | GParamSpec that should be bound to
Returns : | `TRUE` if the property could be bound to the GstControlSource, `FALSE` otherwise.

### GstControlSourceGetValue ()

    gboolean            (*GstControlSourceGetValue)         (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GValue *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,
                                                             GstValueArray *value_array);

Function for returning a GstValueArray for a given timestamp.

`self` : | the GstControlSource instance
`timestamp` : | timestamp for which a value should be calculated
`value_array` : | array to put control-values in
Returns : | `TRUE` if the values were successfully calculated.

### struct GstTimedValue

    struct GstTimedValue {
      GstClockTime timestamp;
      GValue value;
    };

Structure for saving a timestamp and a value.

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

### struct GstValueArray

    struct GstValueArray {
      const gchar *property_name;
      gint nbsamples;
      GstClockTime sample_interval;
      gpointer *values;
    };

Structure to receive multiple values at once.

const gchar *`property_name`; | the name of the property this array belongs to
gint `nbsamples`; | number of samples requested
GstClockTime `sample_interval`; | interval between each sample
gpointer *`values`; | pointer to the array

### gst_control_source_bind ()

    gboolean            gst_control_source_bind             (GstControlSource *self,
                                                             GParamSpec *pspec);

Binds a GstControlSource to a specific property. This must be called only once for a GstControlSource.

`self` : | the GstControlSource object
`pspec` : | GParamSpec for the property for which this GstControlSource should generate values.
Returns : | `TRUE` if the GstControlSource was bound correctly, `FALSE` otherwise.

### gst_control_source_get_value ()

    gboolean            gst_control_source_get_value        (GstControlSource *self,
                                                             GstClockTime timestamp,
                                                             GValue *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,
                                                             GstValueArray *value_array);

Gets an array of values for one element property.

All fields of `value_array` must be filled correctly. Especially the `value_array->values` array must be big enough to keep the requested amount of values.

The type of the values in the array is the same as the property's type.

`self` : | the GstControlSource object
`timestamp` : | the time that should be processed
`value_array` : | array to put control-values in
Returns : | `TRUE` if the given array could be filled, `FALSE` otherwise