diff --git a/docs/manual/advanced-dparams.xml b/docs/manual/advanced-dparams.xml new file mode 100644 index 0000000000..ef3e52e00f --- /dev/null +++ b/docs/manual/advanced-dparams.xml @@ -0,0 +1,190 @@ + + Dynamic Parameters + + + Getting Started + + The dparams subsystem is contained within the gstcontrol library. + + You need to include the header in your applications's source file: + + +... +#include <gst/gst.h> +#include <gst/control/control.h> +... + + + Your application should link to the shared library gstcontrol. + + + The gstcontrol library needs to be initialised when your application is run. + This can be done after the the GStreamer library has been initialised. + + + ... + gst_init(&argc,&argv); + gst_control_init(&argc,&argv); + ... + + + + + Creating and Attaching Dynamic Parameters + + Once you have created your elements you can create and attach dparams to them. + First you need to get the element's dparams manager. If you know exactly what kind of element + you have, you may be able to get the dparams manager directly. However if this is not possible, + you can get the dparams manager by calling gst_dpman_get_manager. + + + Once you have the dparams manager, you must set the mode that the manager will run in. + There is currently only one mode implemented called "synchronous" - this is used for real-time + applications where the dparam value cannot be known ahead of time (such as a slider in a GUI). + The mode is called "synchronous" because the dparams are polled by the element for changes before + each buffer is processed. Another yet-to-be-implemented mode is "asynchronous". This is used when + parameter changes are known ahead of time - such as with a timelined editor. The mode is called + "asynchronous" because parameter changes may happen in the middle of a buffer being processed. + + + GstElement *sinesrc; + GstDParamManager *dpman; + ... + sinesrc = gst_elementfactory_make("sinesrc","sine-source"); + ... + dpman = gst_dpman_get_manager (sinesrc); + gst_dpman_set_mode(dpman, "synchronous"); + + + If you don't know the names of the required dparams for your element you can call + gst_dpman_list_dparam_specs(dpman) to get a NULL terminated array of param specs. + This array should be freed after use. You can find the name of the required dparam by calling + g_param_spec_get_name on each param spec in the array. In our example, + "volume" will be the name of our required dparam. + + + Each type of dparam currently has its own new function. This may eventually + be replaced by a factory method for creating new instances. A default dparam instance can be created + with the gst_dparam_new function. Once it is created it can be attached to a + required dparam in the element. + + + GstDParam *volume; + ... + volume = gst_dparam_new(G_TYPE_FLOAT); + if (gst_dpman_attach_dparam (dpman, "volume", volume)){ + /* the dparam was successfully attached */ + ... + } + + + + + Changing Dynamic Parameter Values + + All interaction with dparams to actually set the dparam value is done through simple GObject properties. + There is a property value for each type that dparams supports - these currently being + "value_float", "value_int" and "value_int64". + To set the value of a dparam, simply set the property which matches the type of your dparam instance. + + +#define ZERO(mem) memset(&mem, 0, sizeof(mem)) +... + + gfloat set_to_value; + GstDParam *volume; + GValue set_val; + ZERO(set_val); + g_value_init(&set_val, G_TYPE_FLOAT); + ... + g_value_set_float(&set_val, set_to_value); + g_object_set_property(G_OBJECT(volume), "value_float", &set_val); + + Or if you create an actual GValue instance: + + gfloat set_to_value; + GstDParam *volume; + GValue *set_val; + set_val = g_new0(GValue,1); + g_value_init(set_val, G_TYPE_FLOAT); + ... + g_value_set_float(set_val, set_to_value); + g_object_set_property(G_OBJECT(volume), "value_float", set_val); + + + + + + Different Types of Dynamic Parameter + + There are currently only two implementations of dparams so far. They are both for real-time use so + should be run in the "synchronous" mode. + + + GstDParam - the base dparam type + + All dparam implementations will subclass from this type. It provides a basic implementation which simply + propagates any value changes as soon as it can. + A new instance can be created with the function GstDParam* gst_dparam_new (GType type). + It has the following object properties: + + + "value_float" + - the property to set and get if it is a float dparam + + "value_int" + - the property to set and get if it is an integer dparam + + "value_int64" + - the property to set and get if it is a 64 bit integer dparam + + "is_log" + - readonly boolean which is TRUE if the param should be displayed on a log scale + + "is_rate" + - readonly boolean which is TRUE if the value is a proportion of the sample rate. + For example with a sample rate of 44100, 0.5 would be 22050 Hz and 0.25 would be 11025 Hz. + + + + + GstDParamSmooth - smoothing real-time dparam + + Some parameter changes can create audible artifacts if they change too rapidly. The GstDParamSmooth + implementation can greatly reduce these artifacts by limiting the rate at which the value can change. + This is currently only supported for float dparams - the other types fall back to the default implementation. + A new instance can be created with the function GstDParam* gst_dpsmooth_new (GType type). + It has the following object properties: + + + "update_period" + - an int64 value specifying the number nanoseconds between updates. This will be ignored in + "synchronous" mode since the buffer size dictates the update period. + + "slope_time" + - an int64 value specifying the time period to use in the maximum slope calculation + + "slope_delta_float" + - a float specifying the amount a float value can change in the given slope_time. + + + + Audible artifacts may not be completely eliminated by using this dparam. The only way to eliminate + artifacts such as "zipper noise" would be for the element to implement its required dparams using the + array method. This would allow dparams to change parameters at the sample rate which should eliminate + any artifacts. + + + + + Timelined dparams + + A yet-to-be-implemented subclass of GstDParam will add an API which allows the creation and manipulation + of points on a timeline. This subclass will also provide a dparam implementation which uses linear + interpolation between these points to find the dparam value at any given time. Further subclasses can + extend this functionality to implement more exotic interpolation algorithms such as splines. + + + + + diff --git a/docs/manual/dparams-app.xml b/docs/manual/dparams-app.xml new file mode 100644 index 0000000000..ef3e52e00f --- /dev/null +++ b/docs/manual/dparams-app.xml @@ -0,0 +1,190 @@ + + Dynamic Parameters + + + Getting Started + + The dparams subsystem is contained within the gstcontrol library. + + You need to include the header in your applications's source file: + + +... +#include <gst/gst.h> +#include <gst/control/control.h> +... + + + Your application should link to the shared library gstcontrol. + + + The gstcontrol library needs to be initialised when your application is run. + This can be done after the the GStreamer library has been initialised. + + + ... + gst_init(&argc,&argv); + gst_control_init(&argc,&argv); + ... + + + + + Creating and Attaching Dynamic Parameters + + Once you have created your elements you can create and attach dparams to them. + First you need to get the element's dparams manager. If you know exactly what kind of element + you have, you may be able to get the dparams manager directly. However if this is not possible, + you can get the dparams manager by calling gst_dpman_get_manager. + + + Once you have the dparams manager, you must set the mode that the manager will run in. + There is currently only one mode implemented called "synchronous" - this is used for real-time + applications where the dparam value cannot be known ahead of time (such as a slider in a GUI). + The mode is called "synchronous" because the dparams are polled by the element for changes before + each buffer is processed. Another yet-to-be-implemented mode is "asynchronous". This is used when + parameter changes are known ahead of time - such as with a timelined editor. The mode is called + "asynchronous" because parameter changes may happen in the middle of a buffer being processed. + + + GstElement *sinesrc; + GstDParamManager *dpman; + ... + sinesrc = gst_elementfactory_make("sinesrc","sine-source"); + ... + dpman = gst_dpman_get_manager (sinesrc); + gst_dpman_set_mode(dpman, "synchronous"); + + + If you don't know the names of the required dparams for your element you can call + gst_dpman_list_dparam_specs(dpman) to get a NULL terminated array of param specs. + This array should be freed after use. You can find the name of the required dparam by calling + g_param_spec_get_name on each param spec in the array. In our example, + "volume" will be the name of our required dparam. + + + Each type of dparam currently has its own new function. This may eventually + be replaced by a factory method for creating new instances. A default dparam instance can be created + with the gst_dparam_new function. Once it is created it can be attached to a + required dparam in the element. + + + GstDParam *volume; + ... + volume = gst_dparam_new(G_TYPE_FLOAT); + if (gst_dpman_attach_dparam (dpman, "volume", volume)){ + /* the dparam was successfully attached */ + ... + } + + + + + Changing Dynamic Parameter Values + + All interaction with dparams to actually set the dparam value is done through simple GObject properties. + There is a property value for each type that dparams supports - these currently being + "value_float", "value_int" and "value_int64". + To set the value of a dparam, simply set the property which matches the type of your dparam instance. + + +#define ZERO(mem) memset(&mem, 0, sizeof(mem)) +... + + gfloat set_to_value; + GstDParam *volume; + GValue set_val; + ZERO(set_val); + g_value_init(&set_val, G_TYPE_FLOAT); + ... + g_value_set_float(&set_val, set_to_value); + g_object_set_property(G_OBJECT(volume), "value_float", &set_val); + + Or if you create an actual GValue instance: + + gfloat set_to_value; + GstDParam *volume; + GValue *set_val; + set_val = g_new0(GValue,1); + g_value_init(set_val, G_TYPE_FLOAT); + ... + g_value_set_float(set_val, set_to_value); + g_object_set_property(G_OBJECT(volume), "value_float", set_val); + + + + + + Different Types of Dynamic Parameter + + There are currently only two implementations of dparams so far. They are both for real-time use so + should be run in the "synchronous" mode. + + + GstDParam - the base dparam type + + All dparam implementations will subclass from this type. It provides a basic implementation which simply + propagates any value changes as soon as it can. + A new instance can be created with the function GstDParam* gst_dparam_new (GType type). + It has the following object properties: + + + "value_float" + - the property to set and get if it is a float dparam + + "value_int" + - the property to set and get if it is an integer dparam + + "value_int64" + - the property to set and get if it is a 64 bit integer dparam + + "is_log" + - readonly boolean which is TRUE if the param should be displayed on a log scale + + "is_rate" + - readonly boolean which is TRUE if the value is a proportion of the sample rate. + For example with a sample rate of 44100, 0.5 would be 22050 Hz and 0.25 would be 11025 Hz. + + + + + GstDParamSmooth - smoothing real-time dparam + + Some parameter changes can create audible artifacts if they change too rapidly. The GstDParamSmooth + implementation can greatly reduce these artifacts by limiting the rate at which the value can change. + This is currently only supported for float dparams - the other types fall back to the default implementation. + A new instance can be created with the function GstDParam* gst_dpsmooth_new (GType type). + It has the following object properties: + + + "update_period" + - an int64 value specifying the number nanoseconds between updates. This will be ignored in + "synchronous" mode since the buffer size dictates the update period. + + "slope_time" + - an int64 value specifying the time period to use in the maximum slope calculation + + "slope_delta_float" + - a float specifying the amount a float value can change in the given slope_time. + + + + Audible artifacts may not be completely eliminated by using this dparam. The only way to eliminate + artifacts such as "zipper noise" would be for the element to implement its required dparams using the + array method. This would allow dparams to change parameters at the sample rate which should eliminate + any artifacts. + + + + + Timelined dparams + + A yet-to-be-implemented subclass of GstDParam will add an API which allows the creation and manipulation + of points on a timeline. This subclass will also provide a dparam implementation which uses linear + interpolation between these points to find the dparam value at any given time. Further subclasses can + extend this functionality to implement more exotic interpolation algorithms such as splines. + + + + + diff --git a/docs/manual/gstreamer-manual.xml b/docs/manual/gstreamer-manual.xml index c4ff01b260..56821c4bdc 100644 --- a/docs/manual/gstreamer-manual.xml +++ b/docs/manual/gstreamer-manual.xml @@ -27,6 +27,7 @@ + @@ -49,6 +50,15 @@ + + Steve + Baker + + + stevebaker_org@yahoo.co.uk + + + @@ -168,6 +178,8 @@ &AUTOPLUGGING; &HELLOWORLD2; + + &DPARAMS; &UTILITY;