GstController

GstController — dynamic parameter control subsystem

Synopsis


#include <gst/controller/gstcontroller.h>


            GstController;
enum        GstInterpolateMode;
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);
gboolean    gst_controller_set              (GstController *self,
                                             gchar *property_name,
                                             GstClockTime timestamp,
                                             GValue *value);
gboolean    gst_controller_set_from_list    (GstController *self,
                                             gchar *property_name,
                                             GSList *timedvalues);
gboolean    gst_controller_unset            (GstController *self,
                                             gchar *property_name,
                                             GstClockTime timestamp);
gboolean    gst_controller_unset_all        (GstController *self,
                                             gchar *property_name);
GValue*     gst_controller_get              (GstController *self,
                                             gchar *property_name,
                                             GstClockTime timestamp);
const GList* gst_controller_get_all         (GstController *self,
                                             gchar *property_name);
gboolean    gst_controller_sync_values      (GstController *self,
                                             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_interpolation_mode
                                            (GstController *self,
                                             gchar *property_name,
                                             GstInterpolateMode mode);
#define     GST_PARAM_CONTROLLABLE


Object Hierarchy


  GObject
   +----GstController

Properties


  "control-rate"         guint                 : 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!

  1. mark gobject-properties paramspecs that make sense to be controlled, by GST_PARAM_CONTROLLABLE.

  2. 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.

  1. first put some properties under control, by calling controller = g_object_control_properties(object, "prop1", "prop2",...);

  2. set how the controller will smooth inbetween values. gst_controller_set_interpolation_mode(controller,"prop1",mode);

  3. set key values gst_controller_set (controller, "prop1" ,0 * GST_SECOND, value1); gst_controller_set (controller, "prop1" ,1 * GST_SECOND, value2);

  4. start your pipeline

Details

GstController

typedef struct _GstController GstController;

The instance structure of GstController


enum GstInterpolateMode

typedef enum
{
  GST_INTERPOLATE_NONE,
  GST_INTERPOLATE_TRIGGER,
  GST_INTERPOLATE_LINEAR,
  GST_INTERPOLATE_QUADRATIC,
  GST_INTERPOLATE_CUBIC,
  GST_INTERPOLATE_USER
} GstInterpolateMode;

The various interpolation modes available.

GST_INTERPOLATE_NONEGST_INTERPOLATE_NONE steps-like interpolation, default steps-like interpolation, default GST_INTERPOLATE_TRIGGERGST_INTERPOLATE_TRIGGER returns the default value of the property, except for times with specific values returns the default value of the property, except for times with specific values GST_INTERPOLATE_LINEARGST_INTERPOLATE_LINEAR linear interpolation linear interpolation GST_INTERPOLATE_QUADRATICGST_INTERPOLATE_QUADRATIC square interpolation square interpolation GST_INTERPOLATE_CUBICGST_INTERPOLATE_CUBIC cubic interpolation cubic interpolation GST_INTERPOLATE_USERGST_INTERPOLATE_USER user-provided interpolation user-provided interpolation
GST_INTERPOLATE_NONE steps-like interpolation, default
GST_INTERPOLATE_TRIGGER returns the default value of the property, except for times with specific values
GST_INTERPOLATE_LINEAR linear interpolation
GST_INTERPOLATE_QUADRATIC square interpolation
GST_INTERPOLATE_CUBIC cubic interpolation
GST_INTERPOLATE_USER user-provided interpolation

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 :argc pointer to the commandline argument count pointer to the commandline argument count argv :argv pointer to the commandline argument values pointer to the commandline argument values Returns :Returns the TRUE for success. the TRUE for success. TRUETRUE
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 :object the object of which some properties should be controlled the object of which some properties should be controlled ... :... NULL terminated list of property names that should be controlled NULL terminated list of property names that should be controlled NULLNULLReturns :Returns the new controller. the new controller.
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 :object the object of which some properties should be controlled the object of which some properties should be controlled list :list list of property names that should be controlled list of property names that should be controlled Returns :Returns the new controller. the new controller.
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 :object the object of which some properties should be controlled the object of which some properties should be controlled var_args :var_args NULL terminated list of property names that should be controlled NULL terminated list of property names that should be controlled NULLNULLReturns :Returns the new controller. the new controller.
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 :self the controller object from which some properties should be removed the controller object from which some properties should be removed ... :... NULL terminated list of property names that should be removed NULL terminated list of property names that should be removed NULLNULLReturns :Returns FALSE if one of the given property isn't handled by the controller, TRUE otherwise FALSE if one of the given property isn't handled by the controller, TRUE otherwise FALSEFALSETRUETRUE
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 :self the controller object from which some properties should be removed the controller object from which some properties should be removed list :list GList of property names that should be removed GList of property names that should be removed GListGListReturns :Returns FALSE if one of the given property isn't handled by the controller, TRUE otherwise FALSE if one of the given property isn't handled by the controller, TRUE otherwise FALSEFALSETRUETRUE
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 :self the controller object from which some properties should be removed the controller object from which some properties should be removed var_args :var_args NULL terminated list of property names that should be removed NULL terminated list of property names that should be removed NULLNULLReturns :Returns FALSE if one of the given property isn't handled by the controller, TRUE otherwise FALSE if one of the given property isn't handled by the controller, TRUE otherwise FALSEFALSETRUETRUE
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 ()

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

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

self :self the controller object which handles the properties the controller object which handles the properties property_name :property_name the name of the property to set the name of the property to set timestamp :timestamp the time the control-change is schedules for the time the control-change is schedules for value :value the control-value the control-value Returns :Returns FALSE if the values couldn't be set (ex : properties not handled by controller), TRUE otherwise FALSE if the values couldn't be set (ex : properties not handled by controller), TRUE otherwise
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,
                                             gchar *property_name,
                                             GSList *timedvalues);

Sets multiple timed values at once.

self :self the controller object which handles the properties the controller object which handles the properties property_name :property_name the name of the property to set the name of the property to set timedvalues :timedvalues a list with GstTimedValue items a list with GstTimedValue items GstTimedValueGstTimedValueReturns :Returns FALSE if the values couldn't be set (ex : properties not handled by controller), TRUE otherwise FALSE if the values couldn't be set (ex : properties not handled by controller), TRUE otherwise FALSEFALSETRUETRUE
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,
                                             gchar *property_name,
                                             GstClockTime timestamp);

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

self :self the controller object which handles the properties the controller object which handles the properties property_name :property_name the name of the property to unset the name of the property to unset timestamp :timestamp the time the control-change should be removed from the time the control-change should be removed from Returns :Returns FALSE if the values couldn't be unset (ex : properties not handled by controller), TRUE otherwise FALSE if the values couldn't be unset (ex : properties not handled by controller), TRUE otherwise FALSEFALSETRUETRUE
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,
                                             gchar *property_name);

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

self :self the controller object which handles the properties the controller object which handles the properties property_name :property_name the name of the property to unset the name of the property to unset Returns :Returns FALSE if the values couldn't be unset (ex : properties not handled by controller), TRUE otherwise FALSE if the values couldn't be unset (ex : properties not handled by controller), TRUE otherwise FALSEFALSETRUETRUE
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 ()

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

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

self :self the controller object which handles the properties the controller object which handles the properties property_name :property_name the name of the property to get the name of the property to get timestamp :timestamp the time the control-change should be read from the time the control-change should be read from Returns :Returns the GValue of the property at the given time, or NULL if the property isn't handled by the controller the GValue of the property at the given time, or NULL if the property isn't handled by the controller NULLNULL
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_all ()

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

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

self :self the controller to get the list from the controller to get the list from property_name :property_name the name of the property to get the list for the name of the property to get the list for Returns :Returns a copy of the list, or NULL if the property isn't handled by the controller a copy of the list, or NULL if the property isn't handled by the controller NULLNULL
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_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.

self :self the controller that handles the values the controller that handles the values timestamp :timestamp the time that should be processed the time that should be processed Returns :Returns TRUE if the controller values could be applied to the object properties, FALSE otherwise TRUE if the controller values could be applied to the object properties, FALSE otherwise TRUETRUEFALSEFALSE
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_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.

If the GstValueArray->values array in list nodes is NULL, it will be created by the function. The type of the values in the array are the same as the property's type.

self :self the controller that handles the values the controller that handles the values timestamp :timestamp the time that should be processed the time that should be processed value_arrays :value_arrays list to return the control-values in list to return the control-values in Returns :Returns TRUE if the given array(s) could be filled, FALSE otherwise TRUE if the given array(s) could be filled, FALSE otherwise TRUETRUEFALSEFALSE
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 properties

If the GstValueArray->values array is NULL, it will be created by the function. The type of the values in the array are the same as the property's type.

self :self the controller that handles the values the controller that handles the values timestamp :timestamp the time that should be processed the time that should be processed value_array :value_array array to put control-values in array to put control-values in Returns :Returns TRUE if the given array(s) could be filled, FALSE otherwise TRUE if the given array(s) could be filled, FALSE otherwise TRUETRUEFALSEFALSE
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(s) could be filled, FALSE otherwise

gst_controller_set_interpolation_mode ()

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

Sets the given interpolation mode on the given property.

self :self the controller object the controller object property_name :property_name the name of the property for which to change the interpolation the name of the property for which to change the interpolation mode :mode interpolation mode interpolation mode Returns :Returns TRUE if the property is handled by the controller, FALSE otherwise TRUE if the property is handled by the controller, FALSE otherwise TRUETRUEFALSEFALSE
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

GST_PARAM_CONTROLLABLE

#define	GST_PARAM_CONTROLLABLE	(1 << (G_PARAM_USER_SHIFT + 1))

Use this flag on GstElement properties you wish to be (eventually) handled by a GstController. TODO: needs to go to gstelemnt.h (to avoid clashes on G_PARAM_USER_SHIFT)

Property Details

The "control-rate" property

  "control-rate"         guint                 : Read / Write

Controlled properties will be updated this many times per second.

Allowed values: >= 1

Default value: 10