docs/design/part-controller.txt

   1 Controller
   2 ----------
   3
   4 The controller subsystem allows to automate element property changes. It works
   5 so that all parameter changes are time based and elements request property
   6 updates at processing time.
   7
   8 Element view
   9 ~~~~~~~~~~~~
  10 Elements don't need to do much. They need to:
  11 - mark object properties that can be changed while processing with
  12   GST_PARAM_CONTROLLABLE
  13 - call gst_object_sync_values (self, timestamp) in the processing function
  14   before accessing the parameters.
  15
  16 All ordered property types can be automated (int, double, boolean, enum). Other
  17 property types can also be automated by using special control bindings. One can
  18 e.g. write a control-binding that updates a text property based on timestamps.
  19
  20 Application view
  21 ~~~~~~~~~~~~~~~~
  22 Applications need to setup the property automation. For that they need to create
  23 a GstControlSource and attach it to a property using GstControlBinding. Various
  24 control-sources and control-bindings exist. All control sources produce control
  25 value sequences in the form of gdouble values. The control bindings map them to
  26 the value range and type of the bound property.
  27
  28 One control-source can be attached to one or more properties at the same time.
  29 If it is attached multiple times, then each control-binding will scale and
  30 convert the control values to the target property type and range.
  31
  32 One can create complex control-curves by using a GstInterpolationControlSource.
  33 This allows the classic user editable control-curve (often seen in audio/video
  34 editors). Another way is to use computed control curves. GstLFOControlSource can
  35 generate various repetitive signals. Those can be made more complex by chaining
  36 the control sources. One can attach another control-source to e.g. modulate the
  37 frequency of the first GstLFOControlSource.
  38
  39 In most cases GstControlBindingDirect will be the binding to be used. Other
  40 control bindings are there to handle special cases, such as having 1-4 control-
  41 sources and combine their values into a single guint to control a rgba-color
  42 property.
  43
  44
  45 TODO
  46 ~~~~
  47 control-source value ranges
  48 - control sources should ideally emit values between [0.0 and 1.0]
  49 - right now lfo-control-sources emits values between [-1.0 and 1.0]
  50 - we can make control-sources announce that or fix it in a lfo2-control-source
  51
  52 ranged-control-binding
  53 - it might be a nice thing to have a control-binding that has scale and offset
  54   properties
  55 - when attaching a control-source to e.g. volume, one needs to be aware that
  56   the values go from [0.0 to 4.0]
  57 - we can also have a "mapping-mode"={AS_IS, TRANSFORMED} on direct-control-binding
  58   and two extra properties that are used in TRANSFORMED mode
  59
  60 control-setup descriptions
  61 - it would be nice to have a way to parse a textual control-setup description. This
  62   could be used in gst-launch and in presets. It needs to be complemented with a
  63   formatter (for the preset storage or e.g. for debug logging).
  64 - this could be function-style:
  65   direct(control-source=lfo(waveform='sine',offset=0.5))
  66   or gst-launch style (looks weird)
  67   lfo wave=sine offset=0.5 ! direct .control-source