Processor Parameter API Plans

[Tim Janik <timj gnu org>]

Hi.

Here is a summary of the current plans (and todays discussion) about
the Bse::AudioSiagnal::Processor parameter API:

- The API will be changed to operate on normalized parameter values
  between 0..+1. This mirrors the JUCE API and VST3 [1]
  Tentative API:
    void   set_normalized (Id32 paramid, double value);
    double get_normalized (Id32 paramid) const;

- The set/get functions are *not* virtual, set_normalized() assigns
  the value to an atomic buffer (which is marked dirty) so it can
  be fetched at the start of process(). get_normalized() clears
  the dirty flag.

- To assign all dirty parameters at the start of process(), use
  adjust_dirty_params(), which calls adjust_param() (to be overloaded)
  once for each dirty parameter.
  Tentative API:
    virtual void  adjust_param        (Id32 tag, double value);
    void          adjust_dirty_params ();
    void          adjust_all_params   ();

- New API is added to convert to/from normalized values, this allows
  serialization to robustly store parameter values in case value ranges
  change in the future, or the list of a choice parameter is extended.
  Tentative API:
    virtual double param_value_to_normalized   (Id32 paramid, double value) const;
    virtual double param_value_from_normalized (Id32 paramid, double normalized) const;
  Note that these methods have a const this, because they will be called
  from multiple threads concurrently.
  These methods will have default implementations, that use min/max/steps
  for linear mappings. Once hints for logarithmic scales are fleshed
  out, these can also be supported by the default implementations.

- Parameters with logarithmic/exponential scaling are currently implemented
  in 3 lines of Javascript (Math.log, Math.pow [2]), and will have to
  move to a more general facility on Processor parameters, JUCE has
  something similar with its NormalisableRange.setSkewForCentre [3].
  Using a normalized Parameter API allows Processors to determine
  the complexity of the normalization mappings, e.g. via an interpolation
  table if pow() on automated blocks is too slow and fast_exp2 +
  fast_log2 is too inaccurate.

- Additional API is provided for parameter to/from text conversion.
  These help the user to understand values during edits and allow numeric
  user inputs.
  Tentative API:
    virtual std::string param_value_to_text   (Id32 paramid, double value) const;
    virtual double      param_value_from_text (Id32 paramid, const std::string &text) const;
  Note that these methods have a const this, because they will be called
  from multiple threads concurrently and have a default implementation.

- Automation will probably be implemented with normalized ranges, but
  being able to convert to/from absolute values enables certain operations
  like shifting Octaves or dB ranges during Automation edits. If an
  automation is directly associated with a parameter value, absolute
  values can be used for robust serialization of the automation.

- The order in which parameters are registered (usually) determines
  the UI layout position. Parameters are associated with an integer ID
  which is either auto-generated (increments starting from 1) or can be
  assigned during parameter creation.
  Picking ID values is up to the programmer and unrelated to the UI
  parameter order, arbitrary integers != 0 are supported.
  The IDs can be constexpr to implement switch statements (e.g. in
  adjust_param()), and the IDs are used for serialization.

Comments welcome, especially about things we failed to consider in this
context.

[1] https://steinbergmedia.github.io/vst3_doc/vstinterfaces/vst3Automation.html#vst3ParameterIntro
[2] 
https://github.com/tim-janik/beast/blob/6616db5007a001a2675851181989c94a2b7a374a/ebeast/b/pro-input.vue#L163
[3] https://docs.juce.com/master/classNormalisableRange.html#a3a583db475e34e251edef004a4e3e3d6


-- 
Yours sincerely,
Tim Janik

https://testbit.eu/timj
Free software author.