| GStreamer 0.8 Library API Reference |
|---|
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 >> |