|  |  |  | GStreamer Library 0.8 API Reference (0.8.3.3) |  | 
|---|
gstcontrol — Dynamic parameter functionality
#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);
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.
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. | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 : | |
| unit_name : | 
void gst_dparam_detach (GstDParam *dparam);
Removes a previousely added parameter controller.
| dparam : | GstDParam instance | 
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 : | 
| << gstgetbits | gstdataprotocol >> |