GstController

GstController — dynamic parameter control subsystem

Synopsis

#include <gst/controller/gstcontroller.h>

struct              GstController;
gboolean            gst_controller_init                 (int *argc,
                                                         char ***argv);
GstController *     gst_controller_new                  (GObject *object,
                                                         ...);
GstController *     gst_controller_new_list             (GObject *object,
                                                         GList *list);
GstController *     gst_controller_new_valist           (GObject *object,
                                                         va_list var_args);
gboolean            gst_controller_remove_properties    (GstController *self,
                                                         ...);
gboolean            gst_controller_remove_properties_list
                                                        (GstController *self,
                                                         GList *list);
gboolean            gst_controller_remove_properties_valist
                                                        (GstController *self,
                                                         va_list var_args);
void                gst_controller_set_disabled         (GstController *self,
                                                         gboolean disabled);
void                gst_controller_set_property_disabled
                                                        (GstController *self,
                                                         const gchar *property_name,
                                                         gboolean disabled);
GstClockTime        gst_controller_suggest_next_sync    (GstController *self);
gboolean            gst_controller_sync_values          (GstController *self,
                                                         GstClockTime timestamp);
GstControlSource *  gst_controller_get_control_source   (GstController *self,
                                                         const gchar *property_name);
gboolean            gst_controller_set_control_source   (GstController *self,
                                                         const gchar *property_name,
                                                         GstControlSource *csource);
GValue *            gst_controller_get                  (GstController *self,
                                                         const gchar *property_name,
                                                         GstClockTime timestamp);
gboolean            gst_controller_get_value_arrays     (GstController *self,
                                                         GstClockTime timestamp,
                                                         GSList *value_arrays);
gboolean            gst_controller_get_value_array      (GstController *self,
                                                         GstClockTime timestamp,
                                                         GstValueArray *value_array);
gboolean            gst_controller_set                  (GstController *self,
                                                         const gchar *property_name,
                                                         GstClockTime timestamp,
                                                         GValue *value);
gboolean            gst_controller_set_from_list        (GstController *self,
                                                         const gchar *property_name,
                                                         GSList *timedvalues);
gboolean            gst_controller_unset                (GstController *self,
                                                         const gchar *property_name,
                                                         GstClockTime timestamp);
gboolean            gst_controller_unset_all            (GstController *self,
                                                         const gchar *property_name);
const GList *       gst_controller_get_all              (GstController *self,
                                                         const gchar *property_name);
gboolean            gst_controller_set_interpolation_mode
                                                        (GstController *self,
                                                         const gchar *property_name,
                                                         GstInterpolateMode mode);

Object Hierarchy

  GObject
   +----GstController

Properties

  "control-rate"             guint64               : Read / Write

Description

The controller subsystem offers a lightweight way to adjust gobject properties over stream-time. It works by using time-stamped value pairs that are queued for element-properties. At run-time the elements continously pull values changes for the current stream-time.

What needs to be changed in a GstElement? Very little - it is just two steps to make a plugin controllable!

mark gobject-properties paramspecs that make sense to be controlled, by GST_PARAM_CONTROLLABLE.
when processing data (get, chain, loop function) at the beginning call gst_object_sync_values(element,timestamp). This will made the controller to update all gobject properties that are under control with the current values based on timestamp.

What needs to be done in applications? Again its not a lot to change.

first put some properties under control, by calling controller = gst_object_control_properties (object, "prop1", "prop2",...);
Get a GstControlSource for the property and set it up. csource = gst_interpolation_control_source_new(); gst_interpolation_control_source_set_interpolation_mode(csource, mode); gst_interpolation_control_source_set (csource,0 * GST_SECOND, value1); gst_interpolation_control_source_set (csource,1 * GST_SECOND, value2);
Set the GstControlSource in the controller. gst_controller_set_control_source (controller, "prop1", csource);
start your pipeline

Details

struct GstController

struct GstController;

The instance structure of GstController

gst_controller_init ()

gboolean            gst_controller_init                 (int *argc,
                                                         char ***argv);

Initializes the use of the controller library. Suggested to be called right after gst_init().

`argc` :	pointer to the commandline argument count
`argv` :	pointer to the commandline argument values
Returns :	the `TRUE` for success.

gst_controller_new ()

GstController *     gst_controller_new                  (GObject *object,
                                                         ...);

Creates a new GstController for the given object's properties

`object` :	the object of which some properties should be controlled
`...` :	`NULL` terminated list of property names that should be controlled
Returns :	the new controller.

gst_controller_new_list ()

GstController *     gst_controller_new_list             (GObject *object,
                                                         GList *list);

Creates a new GstController for the given object's properties

`object` :	the object of which some properties should be controlled
`list` :	list of property names that should be controlled
Returns :	the new controller.

gst_controller_new_valist ()

GstController *     gst_controller_new_valist           (GObject *object,
                                                         va_list var_args);

Creates a new GstController for the given object's properties

`object` :	the object of which some properties should be controlled
`var_args` :	`NULL` terminated list of property names that should be controlled
Returns :	the new controller.

gst_controller_remove_properties ()

gboolean            gst_controller_remove_properties    (GstController *self,
                                                         ...);

Removes the given object properties from the controller

`self` :	the controller object from which some properties should be removed
`...` :	`NULL` terminated list of property names that should be removed
Returns :	`FALSE` if one of the given property isn't handled by the controller, `TRUE` otherwise

gst_controller_remove_properties_list ()

gboolean            gst_controller_remove_properties_list
                                                        (GstController *self,
                                                         GList *list);

Removes the given object properties from the controller

`self` :	the controller object from which some properties should be removed
`list` :	GList of property names that should be removed
Returns :	`FALSE` if one of the given property isn't handled by the controller, `TRUE` otherwise

gst_controller_remove_properties_valist ()

gboolean            gst_controller_remove_properties_valist
                                                        (GstController *self,
                                                         va_list var_args);

Removes the given object properties from the controller

`self` :	the controller object from which some properties should be removed
`var_args` :	`NULL` terminated list of property names that should be removed
Returns :	`FALSE` if one of the given property isn't handled by the controller, `TRUE` otherwise

gst_controller_set_disabled ()

void                gst_controller_set_disabled         (GstController *self,
                                                         gboolean disabled);

This function is used to disable all properties of the GstController for some time, i.e. gst_controller_sync_values() will do nothing.

`self` :	the GstController which should be disabled
`disabled` :	boolean that specifies whether to disable the controller or not.

Since 0.10.14

gst_controller_set_property_disabled ()

void                gst_controller_set_property_disabled
                                                        (GstController *self,
                                                         const gchar *property_name,
                                                         gboolean disabled);

This function is used to disable the GstController on a property for some time, i.e. gst_controller_sync_values() will do nothing for the property.

`self` :	the GstController which should be disabled
`property_name` :	property to disable
`disabled` :	boolean that specifies whether to disable the controller or not.

Since 0.10.14

gst_controller_suggest_next_sync ()

GstClockTime        gst_controller_suggest_next_sync    (GstController *self);

Returns a suggestion for timestamps where buffers should be split to get best controller results.

`self` :	the controller that handles the values
Returns :	Returns the suggested timestamp or `GST_CLOCK_TIME_NONE` if no control-rate was set.

Since 0.10.13

gst_controller_sync_values ()

gboolean            gst_controller_sync_values          (GstController *self,
                                                         GstClockTime timestamp);

Sets the properties of the element, according to the controller that (maybe) handles them and for the given timestamp.

If this function fails, it is most likely the application developers fault. Most probably the control sources are not setup correctly.

`self` :	the controller that handles the values
`timestamp` :	the time that should be processed
Returns :	`TRUE` if the controller values could be applied to the object properties, `FALSE` otherwise

gst_controller_get_control_source ()

GstControlSource *  gst_controller_get_control_source   (GstController *self,
                                                         const gchar *property_name);

Gets the corresponding GstControlSource for the property. This should be unreferenced again after use.

`self` :	the controller object
`property_name` :	name of the property for which the GstControlSource should be get
Returns :	the GstControlSource for `property_name` or NULL if the property is not controlled by this controller or no GstControlSource was assigned yet.

Since 0.10.14

gst_controller_set_control_source ()

gboolean            gst_controller_set_control_source   (GstController *self,
                                                         const gchar *property_name,
                                                         GstControlSource *csource);

Sets the GstControlSource for property_name. If there already was a GstControlSource for this property it will be unreferenced.

`self` :	the controller object
`property_name` :	name of the property for which the GstControlSource should be set
`csource` :	the GstControlSource that should be used for the property
Returns :	`FALSE` if the given property isn't handled by the controller or the new GstControlSource couldn't be bound to the property, `TRUE` if everything worked as expected.

Since 0.10.14

gst_controller_get ()

GValue *            gst_controller_get                  (GstController *self,
                                                         const gchar *property_name,
                                                         GstClockTime timestamp);

Gets the value for the given controller-handled property at the requested time.

`self` :	the controller object which handles the properties
`property_name` :	the name of the property to get
`timestamp` :	the time the control-change should be read from
Returns :	the GValue of the property at the given time, or `NULL` if the property isn't handled by the controller

gst_controller_get_value_arrays ()

gboolean            gst_controller_get_value_arrays     (GstController *self,
                                                         GstClockTime timestamp,
                                                         GSList *value_arrays);

Function to be able to get an array of values for one or more given element properties.

All fields of the GstValueArray in the list must be filled correctly. Especially the GstValueArray->values arrays must be big enough to keep the requested amount of values.

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

Note

This doesn't modify the controlled GObject properties!

`self` :	the controller that handles the values
`timestamp` :	the time that should be processed
`value_arrays` :	list to return the control-values in
Returns :	`TRUE` if the given array(s) could be filled, `FALSE` otherwise

gst_controller_get_value_array ()

gboolean            gst_controller_get_value_array      (GstController *self,
                                                         GstClockTime timestamp,
                                                         GstValueArray *value_array);

Function to be able to get 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 (as indicated by the nbsamples field).

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

Note

This doesn't modify the controlled GObject property!

`self` :	the controller that handles the values
`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

gst_controller_set ()

gboolean            gst_controller_set                  (GstController *self,
                                                         const gchar *property_name,
                                                         GstClockTime timestamp,
                                                         GValue *value);

Warning

gst_controller_set is deprecated and should not be used in newly-written code. Use GstControlSource, for example GstInterpolationControlSource directly.

Set the value of given controller-handled property at a certain time.

`self` :	the controller object which handles the properties
`property_name` :	the name of the property to set
`timestamp` :	the time the control-change is schedules for
`value` :	the control-value
Returns :	FALSE if the values couldn't be set (ex : properties not handled by controller), TRUE otherwise

gst_controller_set_from_list ()

gboolean            gst_controller_set_from_list        (GstController *self,
                                                         const gchar *property_name,
                                                         GSList *timedvalues);

Warning

gst_controller_set_from_list is deprecated and should not be used in newly-written code. Use GstControlSource, for example GstInterpolationControlSource directly.

Sets multiple timed values at once.

`self` :	the controller object which handles the properties
`property_name` :	the name of the property to set
`timedvalues` :	a list with GstTimedValue items
Returns :	`FALSE` if the values couldn't be set (ex : properties not handled by controller), `TRUE` otherwise

gst_controller_unset ()

gboolean            gst_controller_unset                (GstController *self,
                                                         const gchar *property_name,
                                                         GstClockTime timestamp);

Warning

gst_controller_unset is deprecated and should not be used in newly-written code. Use GstControlSource, for example GstInterpolationControlSource directly.

Used to remove the value of given controller-handled property at a certain time.

`self` :	the controller object which handles the properties
`property_name` :	the name of the property to unset
`timestamp` :	the time the control-change should be removed from
Returns :	`FALSE` if the values couldn't be unset (ex : properties not handled by controller), `TRUE` otherwise

gst_controller_unset_all ()

gboolean            gst_controller_unset_all            (GstController *self,
                                                         const gchar *property_name);

Warning

gst_controller_unset_all is deprecated and should not be used in newly-written code. Use GstControlSource, for example GstInterpolationControlSource directly.

Used to remove all time-stamped values of given controller-handled property

`self` :	the controller object which handles the properties
`property_name` :	the name of the property to unset
Returns :	`FALSE` if the values couldn't be unset (ex : properties not handled by controller), `TRUE` otherwise

Since 0.10.5

gst_controller_get_all ()

const GList *       gst_controller_get_all              (GstController *self,
                                                         const gchar *property_name);

Warning

gst_controller_get_all is deprecated and should not be used in newly-written code. Use GstControlSource, for example GstInterpolationControlSource directly.

Returns a read-only copy of the list of GstTimedValue for the given property. Free the list after done with it.

Note

This doesn't modify the controlled GObject property!

`self` :	the controller to get the list from
`property_name` :	the name of the property to get the list for
Returns :	a copy of the list, or `NULL` if the property isn't handled by the controller

gst_controller_set_interpolation_mode ()

gboolean            gst_controller_set_interpolation_mode
                                                        (GstController *self,
                                                         const gchar *property_name,
                                                         GstInterpolateMode mode);

Warning

gst_controller_set_interpolation_mode is deprecated and should not be used in newly-written code. Use GstControlSource, for example GstInterpolationControlSource directly.

Sets the given interpolation mode on the given property.

Note

User interpolation is not yet available and quadratic interpolation is deprecated and maps to cubic interpolation.

`self` :	the controller object
`property_name` :	the name of the property for which to change the interpolation
`mode` :	interpolation mode
Returns :	`TRUE` if the property is handled by the controller, `FALSE` otherwise

Property Details

The `"control-rate"` property

  "control-rate"             guint64               : Read / Write

Controlled properties will be updated at least every control-rate nanoseconds.

Allowed values: [1,4294967295]

Default value: 100000000

			GStreamer 0.10 Library Reference Manual
Top \| Description \| Object Hierarchy \| Properties

GstController

Synopsis

Object Hierarchy

Properties

Description

Details

struct GstController

gst_controller_init ()

gst_controller_new ()

gst_controller_new_list ()

gst_controller_new_valist ()

gst_controller_remove_properties ()

gst_controller_remove_properties_list ()

gst_controller_remove_properties_valist ()

gst_controller_set_disabled ()

gst_controller_set_property_disabled ()

gst_controller_suggest_next_sync ()

gst_controller_sync_values ()

gst_controller_get_control_source ()

gst_controller_set_control_source ()

gst_controller_get ()

gst_controller_get_value_arrays ()

Note

gst_controller_get_value_array ()

Note

gst_controller_set ()

Warning

gst_controller_set_from_list ()

Warning

gst_controller_unset ()

Warning

gst_controller_unset_all ()

Warning

gst_controller_get_all ()

Warning

Note

gst_controller_set_interpolation_mode ()

Warning

Note

Property Details

The "control-rate" property

The `"control-rate"` property