From a768c44689b08a0129f37ef866113015f5a8dfa5 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Mon, 30 Jan 2006 21:11:38 +0000 Subject: [PATCH] docs/manual/advanced-dparams.xml: describe controller Original commit message from CVS: * docs/manual/advanced-dparams.xml: describe controller * docs/manual/advanced-position.xml: * docs/manual/basics-init.xml: * docs/manual/manual.xml: * docs/manual/titlepage.xml: * docs/pwg/pwg.xml: * docs/pwg/titlepage.xml: cleanup xml (more to come) * libs/gst/controller/gstcontroller.c: fix typo --- ChangeLog | 14 ++ docs/manual/advanced-dparams.xml | 195 ++++++---------------------- docs/manual/advanced-position.xml | 6 +- docs/manual/basics-init.xml | 14 +- docs/manual/manual.xml | 170 +++++++++--------------- docs/manual/titlepage.xml | 69 ++++++++++ docs/pwg/pwg.xml | 15 ++- docs/pwg/titlepage.xml | 132 ++++++++++--------- libs/gst/controller/gstcontroller.c | 4 +- 9 files changed, 278 insertions(+), 341 deletions(-) create mode 100644 docs/manual/titlepage.xml diff --git a/ChangeLog b/ChangeLog index ba4507c53f..e701debbd6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2006-01-30 Stefan Kost + + * docs/manual/advanced-dparams.xml: + describe controller + * docs/manual/advanced-position.xml: + * docs/manual/basics-init.xml: + * docs/manual/manual.xml: + * docs/manual/titlepage.xml: + * docs/pwg/pwg.xml: + * docs/pwg/titlepage.xml: + cleanup xml (more to come) + * libs/gst/controller/gstcontroller.c: + fix typo + 2006-01-30 Sebastien Moutte * win32/vs6/grammar.dsp: diff --git a/docs/manual/advanced-dparams.xml b/docs/manual/advanced-dparams.xml index 577b02172b..fc88098144 100644 --- a/docs/manual/advanced-dparams.xml +++ b/docs/manual/advanced-dparams.xml @@ -1,198 +1,81 @@ - Dynamic Parameters + Dynamic Controllable Parameters Getting Started - The Dynamic Parameters subsystem is contained within the + The controller subsystem offers a lightweight way to adjust gobject + properties over stream-time. + It works by using time-stamped value pairs that are queued for + element-properties. + At run-time the elements continously pull values changes for the + current stream-time. + + + This subsystem is contained within the gstcontrol library. - You need to include the header in your application's source file: ... #include <gst/gst.h> -#include <gst/control/control.h> +#include <gst/controller/gstcontroller.h> ... - Your application should link to the shared library gstcontrol. + Your application should link to the shared library gstreamer-controller. - The gstcontrol library needs to be initialized + The gstreamer-controller library needs to be initialized when your application is run. This can be done after the the GStreamer library has been initialized. ... gst_init(&argc,&argv); - gst_control_init(&argc,&argv); + gst_controller_init(&argc,&argv); ... - - - Creating and Attaching Dynamic Parameters + + + Setting up 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. + It makes not sense for all GObject parameter to be real-time controlled. + Therefore the first step is to mark controllable parameters. - GstElement *audiotestsrc; - GstDParamManager *dpman; - ... - audiotestsrc = gst_element_factory_make("audiotestsrc", NULL); - ... - dpman = gst_dpman_get_manager (audiotestsrc); - gst_dpman_set_mode(dpman, "synchronous"); + controller = g_object_control_properties(object, "prop1", "prop2",...); - 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. + Next we can select an interpolation mode. This mode controls how inbetween + values are determined. + The controller subsystem can e.g. fill gaps by smoothing parameter changes. + Each controllable GObject property can be + interpolated differently. - GstDParam *volume; - ... - volume = gst_dparam_new(G_TYPE_DOUBLE); - if (gst_dpman_attach_dparam (dpman, "volume", volume)){ - /* the dparam was successfully attached */ - ... - } + gst_controller_set_interpolation_mode(controller,"prop1",mode); - - - - 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_double", "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. + Finally one needs to set control points. These are time-stamped GValues. + The values become active when the timestamp is reached. They still stay + in the list. If e.g. the pipeline runs a loop (using a segmented seek), + the control-curve gets repeated as well. -#define ZERO(mem) memset(&mem, 0, sizeof(mem)) -... - - gdouble set_to_value; - GstDParam *volume; - GValue set_val; - ZERO(set_val); - g_value_init(&set_val, G_TYPE_DOUBLE); - ... - g_value_set_double(&set_val, set_to_value); - g_object_set_property(G_OBJECT(volume), "value_double", &set_val); + gst_controller_set (controller, "prop1" ,0 * GST_SECOND, value1); + gst_controller_set (controller, "prop1" ,1 * GST_SECOND, value2); - Or if you create an actual GValue instance: - - gdouble set_to_value; - GstDParam *volume; - GValue *set_val; - set_val = g_new0(GValue,1); - g_value_init(set_val, G_TYPE_DOUBLE); - ... - g_value_set_double(set_val, set_to_value); - g_object_set_property(G_OBJECT(volume), "value_double", 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. + The controller subsystem has a builtin live-mode. Even though a parameter + has timestamped control-values assigned one can change the GObject + property through g_object_set(). + This is highly useful when binding the GObject properties to GUI widgets. + When the user adjusts the value with the widget, one can set the GOBject + property and this remains active until the next timestamped value overrides. + This also works with smoothed parameters. - - 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_double" - - the property to set and get if it is a double dparam - - "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 double and 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_double" - - a double specifying the amount a double value can change in the given slope_time. - - "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/advanced-position.xml b/docs/manual/advanced-position.xml index f072840e68..7bab808c8e 100644 --- a/docs/manual/advanced-position.xml +++ b/docs/manual/advanced-position.xml @@ -39,7 +39,8 @@ source itself. - + + #include <gst/gst.h> +--> + static gboolean cb_print_position (GstElement *pipeline) diff --git a/docs/manual/basics-init.xml b/docs/manual/basics-init.xml index 2d048a9ec9..125cbca055 100644 --- a/docs/manual/basics-init.xml +++ b/docs/manual/basics-init.xml @@ -20,7 +20,9 @@ A typical program &EXAFOOT; would have code to initialize &GStreamer; that looks like this: - + + Initializing GStreamer + #include <gst/gst.h> @@ -39,7 +41,8 @@ main (int argc, return 0; } - + + Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO @@ -62,7 +65,9 @@ main (int argc, You can also use a GOption table to initialize your own parameters as shown in the next example: - + + Initialisation using the GOption interface + #include <gst/gst.h> @@ -96,7 +101,8 @@ main (int argc, return 0; } - + + As shown in this fragment, you can use a "> + + - - - + + + - - - - - - - + + + + + + + - - - - - - - - + + + + + + + + - - + + - - - - - - + + + + + + GStreamer"> ]> - - - - - Wim - Taymans - - - wim.taymans@chello.be - - - - - Steve - Baker - - - stevebaker_org@yahoo.co.uk - - - - - Andy - Wingo - - - wingo@pobox.com - - - - - Ronald - S. - Bultje - - - rbultje@ronald.bitfreak.net - - - - - - - - This material may be distributed only subject to the terms and - conditions set forth in the Open Publication License, v1.0 or later (the - latest version is presently available at http://www.opencontent.org/opl.shtml). - - - - &GStreamer; Application Development Manual (&GST_VERSION;) - - - + &TITLEPAGE; + @@ -261,35 +209,35 @@ - + &CHECKLIST; &PORTING; diff --git a/docs/manual/titlepage.xml b/docs/manual/titlepage.xml new file mode 100644 index 0000000000..3883384a4e --- /dev/null +++ b/docs/manual/titlepage.xml @@ -0,0 +1,69 @@ + + + + + Wim + Taymans + + + wim.taymans@chello.be + + + + + + Steve + Baker + + + stevebaker_org@yahoo.co.uk + + + + + + Andy + Wingo + + + wingo@pobox.com + + + + + + Ronald + S. + Bultje + + + rbultje@ronald.bitfreak.net + + + + + + Stefan + Kost + + + ensonic@users.sf.net + + + + + + + + This material may be distributed only subject to the terms and + conditions set forth in the Open Publication License, v1.0 or later (the + latest version is presently available at http://www.opencontent.org/opl.shtml). + + + + &GStreamer; Application Development Manual (&GST_VERSION;) + + + diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml index 8674170f3c..dccfbe097a 100644 --- a/docs/pwg/pwg.xml +++ b/docs/pwg/pwg.xml @@ -8,9 +8,11 @@ + + @@ -20,6 +22,7 @@ + @@ -31,11 +34,13 @@ + + @@ -49,7 +54,7 @@ &TITLEPAGE; - + Introduction @@ -78,7 +83,7 @@ &INTRO_BASICS; - + Building a Plugin @@ -118,7 +123,7 @@ &BUILDING_TESTAPP; - + Advanced Filter Concepts @@ -148,7 +153,7 @@ - + Creating special element types @@ -173,7 +178,7 @@ &OTHER_MANAGER; - + Appendices diff --git a/docs/pwg/titlepage.xml b/docs/pwg/titlepage.xml index 680ede057b..dabdf54894 100644 --- a/docs/pwg/titlepage.xml +++ b/docs/pwg/titlepage.xml @@ -1,69 +1,79 @@ - + - - - Richard - John - Boulton - - - richard-gst@tartarus.org - - - + + + Richard + John + Boulton + + + richard-gst@tartarus.org + + + - - Erik - Walthinsen - - - omega@temple-baptist.com - - - + + Erik + Walthinsen + + + omega@temple-baptist.com + + + - - Steve - Baker - - - stevebaker_org@yahoo.co.uk - - - + + Steve + Baker + + + stevebaker_org@yahoo.co.uk + + + - - Leif - Johnson - - - leif@ambient.2y.net - - - + + Leif + Johnson + + + leif@ambient.2y.net + + + - - Ronald - S. - Bultje - - - rbultje@ronald.bitfreak.net - - - - + + Ronald + S. + Bultje + + + rbultje@ronald.bitfreak.net + + + - - - This material may be distributed only subject to the terms and - conditions set forth in the Open Publication License, v1.0 or later (the - latest version is presently available at http://www.opencontent.org/openpub/). - - + + Stefan + Kost + + + ensonic@users.sf.net + + + + - &GStreamer; Plugin Writer's Guide (&GST_VERSION;) + + + This material may be distributed only subject to the terms and + conditions set forth in the Open Publication License, v1.0 or later (the + latest version is presently available at http://www.opencontent.org/openpub/). + + - + &GStreamer; Plugin Writer's Guide (&GST_VERSION;) + + diff --git a/libs/gst/controller/gstcontroller.c b/libs/gst/controller/gstcontroller.c index 377823fa6b..c70991cbae 100644 --- a/libs/gst/controller/gstcontroller.c +++ b/libs/gst/controller/gstcontroller.c @@ -25,8 +25,8 @@ * @short_description: dynamic parameter control subsystem * * The controller subsystem offers a lightweight way to adjust gobject - * properties over stream-time. It works by using time-stampled value pairs that - * are queued for element-properties. At run-time the elements continously pulls + * properties over stream-time. It works by using time-stamped value pairs that + * are queued for element-properties. At run-time the elements continously pull * values changes for the current stream-time. * * What needs to be changed in a #GstElement?