![]() | ![]() | ![]() | GStreamer 0.8 Library Reference Manual | ![]() |
---|
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.
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 |
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 : | the specification for the parameter |
unit_name : | the name of the unit |
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 : |
<< gstbytestream | gstdataprotocol >> |