Parameters.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018-2023 pongasoft
 *
 * Licensed under the Apache License, Version 2.0 or the MIT license,
 * at your option. You may not use this file except in compliance with
 * one of these licenses. You may obtain copies of the licenses at:
 *
 * https://www.apache.org/licenses/LICENSE-2.0
 * https://opensource.org/licenses/MIT
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 *
 * @author Yan Pujante
 */
#pragma once
 
#include "ParamDef.h"
#include "NormalizedState.h"
 
#include <map>
#include <vector>
#include <set>
#include <functional>
 
#include <public.sdk/source/vst/vstparameters.h>
 
namespace pongasoft::VST {
 
namespace Debug { class ParamDisplay; }

class Parameters
{
public:
  class IChangeListener
  {
  public:
    virtual void onParameterChange(ParamID iParamID) = 0;
  };

  using ChangeCallback = std::function<void()>;

  template<typename Param>
  using ChangeCallback1 = std::function<void(Param &)>;

  template<typename TView, typename Param>
  using ChangeCallback2 = std::function<void(TView *, Param &)>;
 
public:
  struct RawVstParamDefBuilder
  {
    // builder methods
    RawVstParamDefBuilder &units(VstString16 iUnits) { fUnits = std::move(iUnits); return *this; }
    RawVstParamDefBuilder &defaultValue(ParamValue iDefaultValue) { fDefaultValue = iDefaultValue; return *this;}
    RawVstParamDefBuilder &stepCount(int32 iStepCount) { fStepCount = iStepCount; return *this;}
    RawVstParamDefBuilder &flags(int32 iFlags) { fFlags = iFlags; return *this; }
    RawVstParamDefBuilder &unitID(int32 iUnitID) { fUnitID = iUnitID; return *this; }
    RawVstParamDefBuilder &shortTitle(VstString16 iShortTitle) { fShortTitle = std::move(iShortTitle); return *this; }
    RawVstParamDefBuilder &precision(int32 iPrecision) { fPrecision = iPrecision; return *this; }
    RawVstParamDefBuilder &rtOwned() { fOwner = IParamDef::Owner::kRT; return *this; }
    RawVstParamDefBuilder &guiOwned() { fOwner = IParamDef::Owner::kGUI; return *this; }
    RawVstParamDefBuilder &transient(bool iTransient = true) { fTransient = iTransient; return *this; }
    RawVstParamDefBuilder &deprecatedSince(int16 iVersion) { fDeprecatedSince = iVersion; return *this; }
 
    // parameter factory method
    RawVstParam add() const;
 
    // fields
    ParamID fParamID;
    VstString16 fTitle;
    VstString16 fUnits{};
    ParamValue fDefaultValue{};
    int32 fStepCount{0};
    int32 fFlags{ParameterInfo::kCanAutomate};
    UnitID fUnitID{kRootUnitId};
    VstString16 fShortTitle{};
    int32 fPrecision{4};
    IParamDef::Owner fOwner{IParamDef::Owner::kRT};
    bool fTransient{false};
    int16 fDeprecatedSince{IParamDef::kVersionNotDeprecated};
 
    friend class Parameters;
 
  protected:
    RawVstParamDefBuilder(Parameters *iParameters, ParamID iParamID, VstString16 iTitle) :
      fParamID{iParamID}, fTitle{std::move(iTitle)}, fParameters{iParameters} {}
 
  private:
    Parameters *fParameters;
  };

  template<typename T>
  struct VstParamDefBuilder
  {
    // builder methods
    VstParamDefBuilder &units(VstString16 iUnits) { fUnits = std::move(iUnits); return *this; }
    VstParamDefBuilder &defaultValue(T const &iDefaultValue) { fDefaultValue = iDefaultValue; return *this;}
    VstParamDefBuilder &flags(int32 iFlags) { fFlags = iFlags; return *this; }
    VstParamDefBuilder &unitID(int32 iUnitID) { fUnitID = iUnitID; return *this; }
    VstParamDefBuilder &shortTitle(VstString16 iShortTitle) { fShortTitle = std::move(iShortTitle); return *this; }
    VstParamDefBuilder &precision(int32 iPrecision) { fPrecision = iPrecision; return *this; }
    VstParamDefBuilder &rtOwned() { fOwner = IParamDef::Owner::kRT; return *this; }
    VstParamDefBuilder &guiOwned() { fOwner = IParamDef::Owner::kGUI; return *this; }
    VstParamDefBuilder &transient(bool iTransient = true) { fTransient = iTransient; return *this; }
    VstParamDefBuilder &deprecatedSince(int16 iVersion) { fDeprecatedSince = iVersion; return *this; }
    VstParamDefBuilder &converter(std::shared_ptr<IParamConverter<T>> iConverter) { fConverter = std::move(iConverter); return *this; }
    template<typename ParamConverter, typename... Args>
    VstParamDefBuilder &converter(Args&& ...iArgs) { fConverter = std::make_shared<ParamConverter>(std::forward<Args>(iArgs)...); return *this; }
 
    // parameter factory method
    VstParam<T> add() const;
 
    // fields
    ParamID fParamID;
    VstString16 fTitle;
    VstString16 fUnits{};
    T fDefaultValue{};
    int32 fFlags{ParameterInfo::kCanAutomate};
    UnitID fUnitID{kRootUnitId};
    VstString16 fShortTitle{};
    int32 fPrecision{4};
    IParamDef::Owner fOwner{IParamDef::Owner::kRT};
    bool fTransient{false};
    int16 fDeprecatedSince{IParamDef::kVersionNotDeprecated};
    std::shared_ptr<IParamConverter<T>> fConverter{};
 
    friend class Parameters;
 
  protected:
    VstParamDefBuilder(Parameters *iParameters, ParamID iParamID, VstString16 iTitle) :
      fParamID{iParamID}, fTitle{std::move(iTitle)}, fParameters{iParameters} {}
 
  private:
    Parameters *fParameters;
  };

  template<typename T>
  struct JmbParamDefBuilder
  {
    // builder methods
    JmbParamDefBuilder &defaultValue(T const &iDefaultValue) { fDefaultValue = iDefaultValue; return *this;}
    JmbParamDefBuilder &transient(bool iTransient = true) { fTransient = iTransient; return *this; }
    JmbParamDefBuilder &deprecatedSince(int16 iVersion) { fDeprecatedSince = iVersion; return *this; }
    JmbParamDefBuilder &rtOwned() { fOwner = IParamDef::Owner::kRT; return *this; }
    JmbParamDefBuilder &guiOwned() { fOwner = IParamDef::Owner::kGUI; return *this; }
    JmbParamDefBuilder &shared(bool iShared = true) { fShared = iShared; return *this; }
    JmbParamDefBuilder &serializer(std::shared_ptr<IParamSerializer<T>> iSerializer) { fSerializer = std::move(iSerializer); return *this; }
    template<typename ParamSerializer, typename... Args>
    JmbParamDefBuilder &serializer(Args&& ...iArgs) { fSerializer = std::make_shared<ParamSerializer>(std::forward<Args>(iArgs)...); return *this; }
 
    // parameter factory method
    JmbParam<T> add() const;
 
    // fields
    ParamID fParamID;
    VstString16 fTitle;
    T fDefaultValue{};
    IParamDef::Owner fOwner{IParamDef::Owner::kGUI};
    bool fTransient{false};
    int16 fDeprecatedSince{IParamDef::kVersionNotDeprecated};
    bool fShared{false};
    std::shared_ptr<IParamSerializer<T>> fSerializer{};
 
    friend class Parameters;
 
  protected:
    JmbParamDefBuilder(Parameters *iParameters, ParamID iParamID, VstString16 iTitle) :
      fParamID{iParamID}, fTitle{std::move(iTitle)}, fParameters{iParameters} {}
 
  private:
    Parameters *fParameters;
  };
 
public:
  // Constructor
  explicit Parameters() = default;
 
  // Ensure the class is polymorphinc
  virtual ~Parameters() = default;
 

  RawVstParamDefBuilder raw(ParamID iParamID, VstString16 iTitle);

  template<typename ParamConverter, typename... Args>
  VstParamDefBuilder<typename ParamConverter::ParamType> vst(ParamID iParamID, VstString16 iTitle, Args&& ...iConverterArgs);

  template<typename ParamConverter>
  VstParamDefBuilder<typename ParamConverter::ParamType> vst(int32 iParamID,
                                                             VstString16 iTitle,
                                                             typename ParamConverter::ConstructorType initValue);

  template<typename T>
  VstParamDefBuilder<T> vstFromType(ParamID iParamID, VstString16 iTitle);

  template<typename ParamSerializer, typename... Args>
  JmbParamDefBuilder<typename ParamSerializer::ParamType> jmb(ParamID iParamID, VstString16 iTitle, Args&& ...iSerializerArgs);

  template<typename ParamSerializer>
  JmbParamDefBuilder<typename ParamSerializer::ParamType> jmb(int32 iParamID,
                                                              VstString16 iTitle,
                                                              typename ParamSerializer::ConstructorType initValue);

  template<typename T>
  JmbParamDefBuilder<T> jmbFromType(ParamID iParamID, VstString16 iTitle);

  template<typename... Args>
  tresult setRTSaveStateOrder(int16 iVersion, Args&& ...args);

  tresult setRTSaveStateOrder(NormalizedState::SaveOrder const &iSaveOrder);

  template<typename... Args>
  tresult setRTDeprecatedSaveStateOrder(int16 iVersion, Args&& ...args);

  NormalizedState::SaveOrder const &getGUISaveStateOrder() const { return fGUISaveStateOrder; }

  template<typename... Args>
  tresult setGUISaveStateOrder(int16 iVersion, Args&& ...args);

  NormalizedState::SaveOrder const *getGUIDeprecatedSaveStateOrder(int16 iVersion) const;

  template<typename... Args>
  tresult setGUIDeprecatedSaveStateOrder(int16 iVersion, Args&& ...args);

  tresult setGUISaveStateOrder(NormalizedState::SaveOrder const &iSaveOrder);

  NormalizedState::SaveOrder const &getRTSaveStateOrder() const { return fRTSaveStateOrder; }

  void registerVstParameters(Vst::ParameterContainer &iParameterContainer) const;

  virtual tresult readRTState(IBStreamer &iStreamer, NormalizedState *oNormalizedState) const;

  virtual tresult writeRTState(NormalizedState const *iNormalizedState, IBStreamer &oStreamer) const;

  virtual std::unique_ptr<NormalizedState> newRTState() const;

  virtual std::unique_ptr<NormalizedState> newRTState(NormalizedState::SaveOrder const *iSaveOrder) const;

  virtual ParamValue readNormalizedValue(ParamID iParamID, IBStreamer &iStreamer) const;
 
  // getParamDef - nullptr when not found
  std::shared_ptr<RawVstParamDef> getRawVstParamDef(ParamID iParamID) const;
 
  // getJmbParamDef - nullptr when not found
  std::shared_ptr<IJmbParamDef> getJmbParamDef(ParamID iParamID) const;
 
  // getVstRegistrationOrder
  std::vector<ParamID> const &getVstRegistrationOrder() const { return fVstRegistrationOrder; }
 
  // getAllRegistrationOrder
  std::vector<ParamID> const &getAllRegistrationOrder() const { return fAllRegistrationOrder; }

  virtual tresult handleRTStateUpgrade(NormalizedState const &iDeprecatedState, NormalizedState &oNewState) const
  {
    return kResultTrue;
  }
 
  // gives access for debug
  friend class Debug::ParamDisplay;
 
protected:
  // internally called by the builder
  RawVstParam add(RawVstParamDefBuilder const &iBuilder);
 
  // internally called by the builder
  template<typename T>
  VstParam<T> add(VstParamDefBuilder<T> const &iBuilder);
 
  // internally called by the builder
  template<typename T>
  JmbParam<T> add(JmbParamDefBuilder<T> const &iBuilder);
 
  // addVstParamDef
  tresult addVstParamDef(std::shared_ptr<RawVstParamDef> iParamDef);
 
  // addJmbParamDef
  tresult addJmbParamDef(std::shared_ptr<IJmbParamDef> iParamDef);

  virtual tresult readDeprecatedRTState(uint16 iVersion, IBStreamer &iStreamer, NormalizedState *oNormalizedState) const;
 
private:
  // contains all the registered (raw type) parameters (unique ID, will be checked on add)
  std::map<ParamID, std::shared_ptr<RawVstParamDef>> fVstParams{};
 
  // contains all the registered (serializable type) parameters (unique ID, will be checked on add)
  std::map<ParamID, std::shared_ptr<IJmbParamDef>> fJmbParams{};
 
  // order in which the parameters will be registered in the vst world
  std::vector<ParamID> fVstRegistrationOrder{};
 
  // order in which the parameters were registered
  std::vector<ParamID> fAllRegistrationOrder{};
 
  // The "latest" order for both RT and GUI
  NormalizedState::SaveOrder fRTSaveStateOrder{};
  NormalizedState::SaveOrder fGUISaveStateOrder{};
 
  // Keep track of deprecated state orders used for upgrade
  std::map<int16, NormalizedState::SaveOrder> fRTDeprecatedSaveStateOrders{};
  std::map<int16, NormalizedState::SaveOrder> fGUIDeprecatedSaveStateOrders{};
 
private:
  // add id to the param (checking that the parameter actually exists)
  tresult addParamID(std::vector<ParamID> &oParamIDs, ParamID iParamID);
 
  // leaf of templated calls to build a list of ParamIDs from ParamID or ParamDefs
  tresult buildParamIDs(std::vector<ParamID> &iParamIDs) { return kResultOk; }
 
  // case when ParamID
  template<typename... Args>
  tresult buildParamIDs(std::vector<ParamID> &iParamIDs, ParamID id, Args&& ...args);
 
  // case when IJmbParamDef
  template<typename... Args>
  tresult buildParamIDs(std::vector<ParamID> &iParamIDs, std::shared_ptr<IJmbParamDef> &iParamDef, Args&& ...args)
  {
    return buildParamIDs(iParamIDs, iParamDef->fParamID, std::forward<Args>(args)...);
  }
 
  // case when IJmbParamDef
  template<typename T, typename... Args>
  tresult buildParamIDs(std::vector<ParamID> &iParamIDs, std::shared_ptr<JmbParamDef<T>> &iParamDef, Args&& ...args)
  {
    return buildParamIDs(iParamIDs, iParamDef->fParamID, std::forward<Args>(args)...);
  }
 
  // case when VstParamDef
  template<typename ParamConverter, typename... Args>
  tresult buildParamIDs(std::vector<ParamID> &iParamIDs, std::shared_ptr<VstParamDef<ParamConverter>> &iParamDef, Args&& ...args)
  {
    return buildParamIDs(iParamIDs, iParamDef->fParamID, std::forward<Args>(args)...);
  }
 
  // case when array of VstParamDef
  template<typename ParamConverter, size_t N, typename... Args>
  tresult buildParamIDs(std::vector<ParamID> &iParamIDs, std::array<std::shared_ptr<VstParamDef<ParamConverter>>, N> &iParamDefs, Args&& ...args);
 
  // case when RawVstParamDef
  template<typename... Args>
  tresult buildParamIDs(std::vector<ParamID> &iParamIDs, std::shared_ptr<RawVstParamDef> &iParamDef, Args&& ...args)
  {
    return buildParamIDs(iParamIDs, iParamDef->fParamID, std::forward<Args>(args)...);
  }

  tresult setRTDeprecatedSaveStateOrder(NormalizedState::SaveOrder const &iSaveOrder);

  tresult setGUIDeprecatedSaveStateOrder(NormalizedState::SaveOrder const &iSaveOrder);
};
 
//------------------------------------------------------------------------
// Parameters::JmbParamDefBuilder::add
//------------------------------------------------------------------------
template<typename T>
JmbParam<T> Parameters::JmbParamDefBuilder<T>::add() const
{
  return fParameters->add(*this);
}
 
//------------------------------------------------------------------------
// Parameters::VstParamDefBuilder::add
//------------------------------------------------------------------------
template<typename T>
VstParam<T> Parameters::VstParamDefBuilder<T>::add() const
{
  return fParameters->add(*this);
}
 
//------------------------------------------------------------------------
// Parameters::add (called by the builder)
//------------------------------------------------------------------------
template<typename T>
VstParam<T> Parameters::add(VstParamDefBuilder<T> const &iBuilder)
{
  auto param = std::make_shared<VstParamDef<T>>(iBuilder.fParamID,
                                                iBuilder.fTitle,
                                                iBuilder.fUnits,
                                                iBuilder.fDefaultValue,
                                                iBuilder.fFlags,
                                                iBuilder.fUnitID,
                                                iBuilder.fShortTitle,
                                                iBuilder.fPrecision,
                                                iBuilder.fOwner,
                                                iBuilder.fTransient,
                                                iBuilder.fDeprecatedSince,
                                                iBuilder.fConverter);
 
  if(!iBuilder.fTransient && !iBuilder.fConverter)
  {
    DLOG_F(WARNING, "No converter defined for non transient parameter [%d]", iBuilder.fParamID);
  }
 
  if(addVstParamDef(param) == kResultOk)
    return param;
  else
    return nullptr;
}
 
//------------------------------------------------------------------------
// Parameters::add (called by the builder)
//------------------------------------------------------------------------
template<typename T>
JmbParam<T> Parameters::add(Parameters::JmbParamDefBuilder<T> const &iBuilder)
{
  auto param = std::make_shared<JmbParamDef<T>>(iBuilder.fParamID,
                                                iBuilder.fTitle,
                                                iBuilder.fOwner,
                                                iBuilder.fTransient,
                                                iBuilder.fDeprecatedSince,
                                                iBuilder.fShared,
                                                iBuilder.fDefaultValue,
                                                iBuilder.fSerializer);
 
  if(!iBuilder.fTransient && !iBuilder.fSerializer)
  {
    DLOG_F(WARNING, "No serializer defined for parameter [%d] (won't be able to be saved)", iBuilder.fParamID);
  }
 
  if(iBuilder.fShared && !iBuilder.fSerializer)
  {
    DLOG_F(WARNING, "No serializer defined for parameter [%d] (won't be able to be shared with peer)", iBuilder.fParamID);
  }
 
  if(addJmbParamDef(param) == kResultOk)
    return param;
  else
    return nullptr;
}
 
 
//------------------------------------------------------------------------
// Parameters::vstFromType
//------------------------------------------------------------------------
template<typename T>
Parameters::VstParamDefBuilder<T> Parameters::vstFromType(ParamID iParamID, VstString16 iTitle)
{
  return Parameters::VstParamDefBuilder<T>(this, iParamID, std::move(iTitle));
}
 
//------------------------------------------------------------------------
// Parameters::vst
//------------------------------------------------------------------------
template<typename ParamConverter, typename... Args>
Parameters::VstParamDefBuilder<typename ParamConverter::ParamType> Parameters::vst(ParamID iParamID,
                                                                                   VstString16 iTitle,
                                                                                   Args&& ...iConverterArgs)
{
  auto builder = vstFromType<typename ParamConverter::ParamType>(iParamID, std::move(iTitle));
  builder.template converter<ParamConverter>(std::forward<Args>(iConverterArgs)...);
  return builder;
}
 
//------------------------------------------------------------------------
// Parameters::vst
//------------------------------------------------------------------------
template<typename ParamConverter>
Parameters::VstParamDefBuilder<typename ParamConverter::ParamType> Parameters::vst(int32 iParamID,
                                                                                   VstString16 iTitle,
                                                                                   typename ParamConverter::ConstructorType initValue) {
  auto builder = vstFromType<typename ParamConverter::ParamType>(iParamID, std::move(iTitle));
  builder.template converter<ParamConverter>(initValue);
  return builder;
}
 
//------------------------------------------------------------------------
// Parameters::jmbFromType
//------------------------------------------------------------------------
template<typename T>
Parameters::JmbParamDefBuilder<T> Parameters::jmbFromType(ParamID iParamID, VstString16 iTitle)
{
  return Parameters::JmbParamDefBuilder<T>(this, iParamID, std::move(iTitle));
}
 
//------------------------------------------------------------------------
// Parameters::jmb
//------------------------------------------------------------------------
template<typename ParamSerializer, typename... Args>
Parameters::JmbParamDefBuilder<typename ParamSerializer::ParamType> Parameters::jmb(ParamID iParamID,
                                                                                    VstString16 iTitle,
                                                                                    Args&& ...iSerializerArgs)
{
  auto builder = jmbFromType<typename ParamSerializer::ParamType>(iParamID, std::move(iTitle));
  builder.template serializer<ParamSerializer>(std::forward<Args>(iSerializerArgs)...);
  return builder;
}
 
//------------------------------------------------------------------------
// Parameters::jmb
//------------------------------------------------------------------------
template<typename ParamSerializer>
Parameters::JmbParamDefBuilder<typename ParamSerializer::ParamType> Parameters::jmb(int32 iParamID,
                                                                                    VstString16 iTitle,
                                                                                    typename ParamSerializer::ConstructorType initValue) {
  auto builder = jmbFromType<typename ParamSerializer::ParamType>(iParamID, std::move(iTitle));
  builder.template serializer<ParamSerializer>(initValue);
  return builder;
}
 
//------------------------------------------------------------------------
// Parameters::buildParamIDs
//------------------------------------------------------------------------
template<typename... Args>
tresult Parameters::buildParamIDs(std::vector<ParamID> &iParamIDs, ParamID iParamID, Args&& ...args)
{
  tresult res = addParamID(iParamIDs, iParamID);
  res |= buildParamIDs(iParamIDs, std::forward<Args>(args)...);
  return res;
}
 
//------------------------------------------------------------------------
// Parameters::buildParamIDs
//------------------------------------------------------------------------
template<typename ParamConverter, size_t N, typename... Args>
tresult Parameters::buildParamIDs(std::vector<ParamID> &iParamIDs, std::array<std::shared_ptr<VstParamDef<ParamConverter>>, N> &iParamDefs, Args&& ...args)
{
  tresult res = kResultOk;
  for(auto &def: iParamDefs)
    res |= addParamID(iParamIDs, def->fParamID);
  res |= buildParamIDs(iParamIDs, std::forward<Args>(args)...);
  return res;
}
 
//------------------------------------------------------------------------
// Parameters::setRTSaveStateOrder
//------------------------------------------------------------------------
template<typename... Args>
tresult Parameters::setRTSaveStateOrder(int16 iVersion, Args&& ...args)
{
  std::vector<ParamID> ids{};
  buildParamIDs(ids, std::forward<Args>(args)...);
  return setRTSaveStateOrder({iVersion, ids});
}
 
//------------------------------------------------------------------------
// Parameters::setRTDeprecatedSaveStateOrder
//------------------------------------------------------------------------
template<typename... Args>
tresult Parameters::setRTDeprecatedSaveStateOrder(int16 iVersion, Args&& ...args)
{
  std::vector<ParamID> ids{};
  buildParamIDs(ids, std::forward<Args>(args)...);
  return setRTDeprecatedSaveStateOrder({iVersion, ids});
}
 
//------------------------------------------------------------------------
// Parameters::setRTSaveStateOrder
//------------------------------------------------------------------------
template<typename... Args>
tresult Parameters::setGUISaveStateOrder(int16 iVersion, Args&& ...args)
{
  std::vector<ParamID> ids{};
  buildParamIDs(ids, std::forward<Args>(args)...);
  return setGUISaveStateOrder({iVersion, ids});
}
 
//------------------------------------------------------------------------
// Parameters::setGUIDeprecatedSaveStateOrder
//------------------------------------------------------------------------
template<typename... Args>
tresult Parameters::setGUIDeprecatedSaveStateOrder(int16 iVersion, Args&& ...args)
{
  std::vector<ParamID> ids{};
  buildParamIDs(ids, std::forward<Args>(args)...);
  return setGUIDeprecatedSaveStateOrder({iVersion, ids});
}
 
}