markdown/additional/design/controller.md

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