## gstcontrol

gstcontrol — dynamic parameter functionality.

## Synopsis

    #include <libs/control/control.h>

    void        gst_control_init                (int *argc,
                                                 char **argv[]);

    GstDParamManager* gst_dpman_new             (gchar *name,
                                                 GstElement *parent);
    gboolean    gst_dpman_add_required_dparam_callback
                                                (GstDParamManager *dpman,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name,
                                                 GstDPMUpdateFunction update_func,
                                                 gpointer update_data);
    gboolean    gst_dpman_add_required_dparam_direct
                                                (GstDParamManager *dpman,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name,
                                                 gpointer update_data);
    gboolean    gst_dpman_add_required_dparam_array
                                                (GstDParamManager *dpman,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name,
                                                 gpointer update_data);
    void        gst_dpman_remove_required_dparam
                                                (GstDParamManager *dpman,
                                                 const gchar *dparam_name);
    gboolean    gst_dpman_attach_dparam         (GstDParamManager *dpman,
                                                 const gchar *dparam_name,
                                                 GstDParam *dparam);
    void        gst_dpman_detach_dparam         (GstDParamManager *dpman,
                                                 const gchar *dparam_name);
    GstDParam*  gst_dpman_get_dparam            (GstDParamManager *dpman,
                                                 const gchar *dparam_name);
    GType       gst_dpman_get_dparam_type       (GstDParamManager *dpman,
                                                 const gchar *dparam_name);
    GParamSpec** gst_dpman_list_dparam_specs    (GstDParamManager *dpman);
    GParamSpec* gst_dpman_get_param_spec        (GstDParamManager *dpman,
                                                 const gchar *dparam_name);
    void        gst_dpman_set_rate              (GstDParamManager *dpman,
                                                 gint rate);
    void        gst_dpman_register_mode         (GstDParamManagerClass *klass,
                                                 gchar *modename,
                                                 GstDPMModePreProcessFunction preprocessfunc,
                                                 GstDPMModeProcessFunction processfunc,
                                                 GstDPMModeSetupFunction setupfunc,
                                                 GstDPMModeTeardownFunction teardownfunc);
    gboolean    gst_dpman_set_mode              (GstDParamManager *dpman,
                                                 gchar *modename);
    void        gst_dpman_set_parent            (GstDParamManager *dpman,
                                                 GstElement *parent);
    GstDParamManager* gst_dpman_get_manager     (GstElement *parent);
    void        gst_dpman_bypass_dparam         (GstDParamManager *dpman,
                                                 const gchar *dparam_name);

    GstDParam*  gst_dparam_new                  (GType type);
    void        gst_dparam_attach               (GstDParam *dparam,
                                                 GstDParamManager *manager,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name);
    void        gst_dparam_detach               (GstDParam *dparam);
    void        gst_dparam_do_update_default    (GstDParam *dparam,
                                                 gint64 timestamp,
                                                 GValue *value,
                                                 GstDParamUpdateInfo update_info);
    GstDParam*  gst_dpsmooth_new                (GType type);

## Description

This library provides a Manager that maintains a list of dynamically controlable parameters for a GstElement. Just think of a volume slider in a mixer.

To use this library one needs to add some code to initialize it.

Example 1. Adding the control library to a project

    ...
    #include <gst/gst.h>
    #include <gst/control/control.h>
    ...
    gst_init(&argc,&argv);
    gst_control_init(&argc,&argv);
    ...

The next step is to get hold of the GstDParamManager instance of a GstElement.

## Details

### gst_control_init ()

    void        gst_control_init                (int *argc,
                                                 char **argv[]);

Initializes the GStreamer control library, registering modes and units

`argc` : | pointer to application's argc
`argv` : | pointer to application's argv

### gst_dpman_new ()

    GstDParamManager* gst_dpman_new             (gchar *name,
                                                 GstElement *parent);

Creates a new instance of a dynamic parameter manager.

`name` : | name of the new GstDParamManager instance to create
`parent` : | GstElement which creates this instance
Returns : | a new instance of GstDParamManager.

### gst_dpman_add_required_dparam_callback ()

    gboolean    gst_dpman_add_required_dparam_callback
                                                (GstDParamManager *dpman,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name,
                                                 GstDPMUpdateFunction update_func,
                                                 gpointer update_data);

Add a mandatory dynamic parameter to the manager, where the value can be updated by calling the supplied callback function.

`dpman` : | GstDParamManager instance
`param_spec` : | the spacification of the new dparam
`unit_name` : | the unit name of the dparam
`update_func` : | callback to update the element with the new value
`update_data` : | will be included in the call to update_func
Returns : | true if it was successfully added

### gst_dpman_add_required_dparam_direct ()

    gboolean    gst_dpman_add_required_dparam_direct
                                                (GstDParamManager *dpman,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name,
                                                 gpointer update_data);

Add a mandatory dynamic parameter to the manager, where the value can be updated by directly storing it into the provided memory location.

`dpman` : | GstDParamManager instance
`param_spec` : | the spacification of the new dparam
`unit_name` : | the unit name of the dparam
`update_data` : | pointer to the member to be updated
Returns : | true if it was successfully added

### gst_dpman_add_required_dparam_array ()

    gboolean    gst_dpman_add_required_dparam_array
                                                (GstDParamManager *dpman,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name,
                                                 gpointer update_data);

Add a mandatory dynamic parameter to the manager, where the values can be updated by storing them into the provided memory location.

`dpman` : | GstDParamManager instance
`param_spec` : | the spacification of the new dparam
`unit_name` : | the unit name of the dparam
`update_data` : | pointer to where the array will be stored
Returns : | true if it was successfully added

### gst_dpman_remove_required_dparam ()

    void        gst_dpman_remove_required_dparam
                                                (GstDParamManager *dpman,
                                                 const gchar *dparam_name);

Removes the named dynamic parameter from the manager.

`dpman` : | GstDParamManager instance
`dparam_name` : | the name of an existing parameter

### gst_dpman_attach_dparam ()

    gboolean    gst_dpman_attach_dparam         (GstDParamManager *dpman,
                                                 const gchar *dparam_name,
                                                 GstDParam *dparam);

Adding a parameter controller to a dynamic parameter. Whenever the controller changes, the dynamic parameter of the GstElement will follow.

`dpman` : | GstDParamManager instance
`dparam_name` : | a name previously added with gst_dpman_add_required_dparam
`dparam` : | GstDParam instance to attach
Returns : | true if it was successfully attached

### gst_dpman_detach_dparam ()

    void        gst_dpman_detach_dparam         (GstDParamManager *dpman,
                                                 const gchar *dparam_name);

Removing a parameter controller from a dynamic parameter.

`dpman` : | GstDParamManager instance
`dparam_name` : | the name of a parameter with a previously attached GstDParam

### gst_dpman_get_dparam ()

    GstDParam*  gst_dpman_get_dparam            (GstDParamManager *dpman,
                                                 const gchar *dparam_name);

Fetches a dparam object that is registered by manager under the given name.

`dpman` : | GstDParamManager instance
`dparam_name` : | the name of an existing dparam instance
Returns : | the dparam with the given name - or NULL otherwise

### gst_dpman_get_dparam_type ()

    GType       gst_dpman_get_dparam_type       (GstDParamManager *dpman,
                                                 const gchar *dparam_name);

Fetches the type of the supplied dynamic parameter.

`dpman` : | GstDParamManager instance
`dparam_name` : | the name of dparam
Returns : | the type that this dparam requires/uses

### gst_dpman_list_dparam_specs ()

    GParamSpec** gst_dpman_list_dparam_specs    (GstDParamManager *dpman);

Fetches the list of parameter specifications, that this manager maintains.

`dpman` : | GstDParamManager instance
Returns : | the the parameter specifications as a NULL terminated array

### gst_dpman_get_param_spec ()

    GParamSpec* gst_dpman_get_param_spec        (GstDParamManager *dpman,
                                                 const gchar *dparam_name);

Fetches a single parameter specification by its dparam name.

`dpman` : | GstDParamManager instance
`dparam_name` : | the name of dparam
Returns : | the the parameter specifications for a given name

### gst_dpman_set_rate ()

    void        gst_dpman_set_rate              (GstDParamManager *dpman,
                                                 gint rate);

Sets the frame or sampling rate used by the machine.

`dpman` : | GstDParamManager instance
`rate` : | the new the frame/sample rate

### gst_dpman_register_mode ()

    void        gst_dpman_register_mode         (GstDParamManagerClass *klass,
                                                 gchar *modename,
                                                 GstDPMModePreProcessFunction preprocessfunc,
                                                 GstDPMModeProcessFunction processfunc,
                                                 GstDPMModeSetupFunction setupfunc,
                                                 GstDPMModeTeardownFunction teardownfunc);

Registers a run-mode for the dparam manager. Each such mode has a defined run-time behaviour - that is, they differ in the way dynamic parameter changes are pushed into the underlying GstElements.

`klass` : | GstDParamManagerClass class instance
`modename` : | the unique name of the new mode
`preprocessfunc` : | the function which will be called before each buffer is processed
`processfunc` : | the function which may be called throughout the processing of a buffer
`setupfunc` : | the function which initialises the mode when activated
`teardownfunc` : | the function which frees any resources the mode uses

### gst_dpman_set_mode ()

    gboolean    gst_dpman_set_mode              (GstDParamManager *dpman,
                                                 gchar *modename);

Activate one of the registered modes.

`dpman` : | GstDParamManager instance
`modename` : | the name of the mode to use
Returns : | TRUE if the mode was set, FALSE otherwise

### gst_dpman_set_parent ()

    void        gst_dpman_set_parent            (GstDParamManager *dpman,
                                                 GstElement *parent);

Set a GstElement that parameters this manager should handle.

`dpman` : | GstDParamManager instance
`parent` : | the element that this GstDParamManager belongs to

### gst_dpman_get_manager ()

    GstDParamManager* gst_dpman_get_manager     (GstElement *parent);

Fetch the GstElement that parameters are handled by this manager.

`parent` : | the element that the desired GstDParamManager belongs to
Returns : | the GstDParamManager which belongs to this element or NULL if it doesn't exist

### gst_dpman_bypass_dparam ()

    void        gst_dpman_bypass_dparam         (GstDParamManager *dpman,
                                                 const gchar *dparam_name);

If a dparam is attached to this dparam_name, it will be detached and a warning will be issued. This should be called in the _set_property function of an element if the value it changes is also changed by a dparam.

`dpman` : | GstDParamManager instance
`dparam_name` : | the name of dparam

### gst_dparam_new ()

    GstDParam*  gst_dparam_new                  (GType type);

Create a new dynamic parameter controller.

`type` : | the type that this dparam will store
Returns : | a new instance of GstDParam

### gst_dparam_attach ()

    void        gst_dparam_attach               (GstDParam *dparam,
                                                 GstDParamManager *manager,
                                                 GParamSpec *param_spec,
                                                 gchar *unit_name);

Adding the parameter controller to the manager using the supplied specs and unit. See also `gst_dpman_attach_dparam()`.

`dparam` : | GstDParam instance
`manager` : | the GstDParamManager that this dparam belongs to
`param_spec` : | the specification for the parameter
`unit_name` : | the name of the unit

### gst_dparam_detach ()

    void        gst_dparam_detach               (GstDParam *dparam);

Removes a previousely added parameter controller.

`dparam` : | GstDParam instance

### gst_dparam_do_update_default ()

    void        gst_dparam_do_update_default    (GstDParam *dparam,
                                                 gint64 timestamp,
                                                 GValue *value,
                                                 GstDParamUpdateInfo update_info);

Default implementation for changing a dynamic parameter. Subclasses might overwrite the behaviour of this.

`dparam` : |
`timestamp` : |
`value` : |
`update_info` : |

### gst_dpsmooth_new ()

    GstDParam*  gst_dpsmooth_new                (GType type);

Create a new dynamic parameter controller which smoothes control changes.

`type` : | the type that this dparam will store
Returns : | a new instance of GstDParam