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