## GstDParamManager

GstDParamManager — dynamic parameter manager

## Synopsis

    #include <libs/control/control.h>

    struct      GstDParamManager;
    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);

## Object Hierarchy

      GObject
       +----GstObject
             +----GstDParamManager

## Signal Prototypes

    "new-required-dparam"
                void        user_function      (GstDParamManager *gstdparammanager,
                                                gchar *arg1,
                                                gpointer user_data);

## Description

The manager bings all functions to work with GstElements and their GstDParams. One can find out which dparams an element has, get the parameter specs and pick a control change rate.

Some functions are meant for dparam implementor (plugin writers), where others are for applications that use elements with dparams.

## Details

### struct GstDParamManager

    struct GstDParamManager;

### 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. Do not call `g_object_unref()` on it.

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

## Signals

### The "new-required-dparam" signal

    void        user_function                  (GstDParamManager *gstdparammanager,
                                                gchar *arg1,
                                                gpointer user_data);

`gstdparammanager` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.