pwg-dparams.md

   1 ---
   2 title: Supporting Dynamic Parameters
   3 ...
   4
   5 # Supporting Dynamic Parameters
   6
   7 Warning, this part describes 0.10 and is outdated.
   8
   9 Sometimes object properties are not powerful enough to control the
  10 parameters that affect the behaviour of your element. When this is the
  11 case you can mark these parameters as being Controllable. Aware
  12 applications can use the controller subsystem to dynamically adjust the
  13 property values over time.
  14
  15 ## Getting Started
  16
  17 The controller subsystem is contained within the `gstcontroller`
  18 library. You need to include the header in your element's source file:
  19
  20 ``` c
  21 ...
  22 #include <gst/gst.h>
  23 #include <gst/controller/gstcontroller.h>
  24 ...
  25
  26 ```
  27
  28 Even though the `gstcontroller` library may be linked into the host
  29 application, you should make sure it is initialized in your
  30 `plugin_init` function:
  31
  32 ``` c
  33   static gboolean
  34   plugin_init (GstPlugin *plugin)
  35   {
  36     ...
  37     /* initialize library */
  38     gst_controller_init (NULL, NULL);
  39     ...
  40   }
  41
  42 ```
  43
  44 It makes no sense for all GObject parameter to be real-time controlled.
  45 Therefore the next step is to mark controllable parameters. This is done
  46 by using the special flag `GST_PARAM_CONTROLLABLE`. when setting up
  47 GObject params in the `_class_init` method.
  48
  49 ``` c
  50   g_object_class_install_property (gobject_class, PROP_FREQ,
  51       g_param_spec_double ("freq", "Frequency", "Frequency of test signal",
  52           0.0, 20000.0, 440.0,
  53           G_PARAM_READWRITE | GST_PARAM_CONTROLLABLE | G_PARAM_STATIC_STRINGS));
  54
  55 ```
  56
  57 ## The Data Processing Loop
  58
  59 In the last section we learned how to mark GObject params as
  60 controllable. Application developers can then queue parameter changes
  61 for these parameters. The approach the controller subsystem takes is to
  62 make plugins responsible for pulling the changes in. This requires just
  63 one action:
  64
  65 ``` c
  66     gst_object_sync_values(element,timestamp);
  67
  68 ```
  69
  70 This call makes all parameter-changes for the given timestamp active by
  71 adjusting the GObject properties of the element. Its up to the element
  72 to determine the synchronisation rate.
  73
  74 ### The Data Processing Loop for Video Elements
  75
  76 For video processing elements it is the best to synchronise for every
  77 frame. That means one would add the `gst_object_sync_values()` call
  78 described in the previous section to the data processing function of the
  79 element.
  80
  81 ### The Data Processing Loop for Audio Elements
  82
  83 For audio processing elements the case is not as easy as for video
  84 processing elements. The problem here is that audio has a much higher
  85 rate. For PAL video one will e.g. process 25 full frames per second, but
  86 for standard audio it will be 44100 samples. It is rarely useful to
  87 synchronise controllable parameters that often. The easiest solution is
  88 also to have just one synchronisation call per buffer processing. This
  89 makes the control-rate depend on the buffer size.
  90
  91 Elements that need a specific control-rate need to break their data
  92 processing loop to synchronise every n-samples.
  93