Jamba C++ API  6.2.0
Parameters Class Reference

This is the class which maintains all the registered parameters. More...

#include <Parameters.h>

Classes

class  IChangeListener
 Interface to implement to receive parameter changes. More...
 
struct  JmbParamDefBuilder
 Implements the builder pattern for ease of build. More...
 
struct  RawVstParamDefBuilder
 Implements the builder pattern for ease of build. More...
 
struct  VstParamDefBuilder
 Implements the builder pattern for ease of build. More...
 

Public Types

using ChangeCallback = std::function< void()>
 A callback that will be invoked for changes. More...
 
template<typename Param >
using ChangeCallback1 = std::function< void(Param &)>
 A callback which will be invoked for changes with the param as an argument. More...
 
template<typename TView , typename Param >
using ChangeCallback2 = std::function< void(TView *, Param &)>
 A callback which will be invoked for changes with the view and param as arguments. More...
 

Public Member Functions

std::vector< ParamID > const & getAllRegistrationOrder () const
 
NormalizedState::SaveOrder const * getGUIDeprecatedSaveStateOrder (int16 iVersion) const
 
NormalizedState::SaveOrder const & getGUISaveStateOrder () const
 
std::shared_ptr< IJmbParamDef > getJmbParamDef (ParamID iParamID) const
 
std::shared_ptr< RawVstParamDef > getRawVstParamDef (ParamID iParamID) const
 
NormalizedState::SaveOrder const & getRTSaveStateOrder () const
 
std::vector< ParamID > const & getVstRegistrationOrder () const
 
virtual tresult handleRTStateUpgrade (NormalizedState const &iDeprecatedState, NormalizedState &oNewState) const
 When Jamba detects that a previously saved RT state matches a deprecated version (as registered with setRTDeprecatedSaveStateOrder), it will call this method to let the plugin handle the upgrade if necessary. More...
 
template<typename ParamSerializer , typename... Args>
JmbParamDefBuilder< typename ParamSerializer::ParamType > jmb (ParamID iParamID, VstString16 iTitle, Args &&...iSerializerArgs)
 Used from derived classes to build a non vst parameter (not convertible to a ParamValue) More...
 
template<typename ParamSerializer >
JmbParamDefBuilder< typename ParamSerializer::ParamType > jmb (int32 iParamID, VstString16 iTitle, typename ParamSerializer::ConstructorType initValue)
 This flavor allows the ParamSerializer to provide an actual type for the primary constructor. More...
 
template<typename T >
JmbParamDefBuilder< T > jmbFromType (ParamID iParamID, VstString16 iTitle)
 Used from derived classes to build a non vst parameter (not convertible to a ParamValue). More...
 
virtual std::unique_ptr< NormalizedStatenewRTState () const
 
virtual std::unique_ptr< NormalizedStatenewRTState (NormalizedState::SaveOrder const *iSaveOrder) const
 
 Parameters ()=default
 
RawVstParamDefBuilder raw (ParamID iParamID, VstString16 iTitle)
 Used from derived classes to build a parameter backed by a raw VST parameter. More...
 
virtual ParamValue readNormalizedValue (ParamID iParamID, IBStreamer &iStreamer) const
 
virtual tresult readRTState (IBStreamer &iStreamer, NormalizedState *oNormalizedState) const
 This method is called to read the RTState from the stream. More...
 
void registerVstParameters (Vst::ParameterContainer &iParameterContainer) const
 This method is called from the GUI controller to register all the parameters to the ParameterContainer class which is the class managing the parameters in the vst sdk. More...
 
template<typename... Args>
tresult setGUIDeprecatedSaveStateOrder (int16 iVersion, Args &&...args)
 This method should be called to save the order of a deprecated version so that it can be handled during upgrade. More...
 
template<typename... Args>
tresult setGUISaveStateOrder (int16 iVersion, Args &&...args)
 Used to change the default order (registration order) used when saving the GUI state (getState/setState in the controller) More...
 
tresult setGUISaveStateOrder (NormalizedState::SaveOrder const &iSaveOrder)
 Used to change the default order (registration order) used when saving the GUI state (getState/setState in the controller) More...
 
template<typename... Args>
tresult setRTDeprecatedSaveStateOrder (int16 iVersion, Args &&...args)
 This method should be called to save the order of a deprecated version so that it can be handled during upgrade. More...
 
template<typename... Args>
tresult setRTSaveStateOrder (int16 iVersion, Args &&...args)
 Used to change the default order (registration order) used when saving the RT state (getState/setState in the processor, setComponentState in the controller) More...
 
tresult setRTSaveStateOrder (NormalizedState::SaveOrder const &iSaveOrder)
 Used to change the default order (registration order) used when saving the RT state (getState/setState in the processor, setComponentState in the controller) More...
 
template<typename ParamConverter , typename... Args>
VstParamDefBuilder< typename ParamConverter::ParamType > vst (ParamID iParamID, VstString16 iTitle, Args &&...iConverterArgs)
 Used from derived classes to build a parameter backed by a VST parameter. More...
 
template<typename ParamConverter >
VstParamDefBuilder< typename ParamConverter::ParamType > vst (int32 iParamID, VstString16 iTitle, typename ParamConverter::ConstructorType initValue)
 This flavor allows the ParamConverter to provide an actual type for the primary constructor. More...
 
template<typename T >
VstParamDefBuilder< T > vstFromType (ParamID iParamID, VstString16 iTitle)
 Used from derived classes to build a parameter backed by a VST parameter. More...
 
virtual tresult writeRTState (NormalizedState const *iNormalizedState, IBStreamer &oStreamer) const
 This method is called to write the NormalizedState to the stream. More...
 
virtual ~Parameters ()=default
 

Protected Member Functions

RawVstParam add (RawVstParamDefBuilder const &iBuilder)
 
template<typename T >
VstParam< T > add (VstParamDefBuilder< T > const &iBuilder)
 
template<typename T >
JmbParam< T > add (JmbParamDefBuilder< T > const &iBuilder)
 
tresult addJmbParamDef (std::shared_ptr< IJmbParamDef > iParamDef)
 
tresult addVstParamDef (std::shared_ptr< RawVstParamDef > iParamDef)
 
virtual tresult readDeprecatedRTState (uint16 iVersion, IBStreamer &iStreamer, NormalizedState *oNormalizedState) const
 This method is called to read a deprecated (prior version) RTState from the stream. More...
 

Private Member Functions

tresult addParamID (std::vector< ParamID > &oParamIDs, ParamID iParamID)
 
tresult buildParamIDs (std::vector< ParamID > &iParamIDs)
 
template<typename... Args>
tresult buildParamIDs (std::vector< ParamID > &iParamIDs, ParamID id, Args &&...args)
 
template<typename... Args>
tresult buildParamIDs (std::vector< ParamID > &iParamIDs, std::shared_ptr< IJmbParamDef > &iParamDef, Args &&...args)
 
template<typename T , typename... Args>
tresult buildParamIDs (std::vector< ParamID > &iParamIDs, std::shared_ptr< JmbParamDef< T >> &iParamDef, Args &&...args)
 
template<typename ParamConverter , typename... Args>
tresult buildParamIDs (std::vector< ParamID > &iParamIDs, std::shared_ptr< VstParamDef< ParamConverter >> &iParamDef, Args &&...args)
 
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)
 
template<typename... Args>
tresult buildParamIDs (std::vector< ParamID > &iParamIDs, std::shared_ptr< RawVstParamDef > &iParamDef, Args &&...args)
 
tresult setGUIDeprecatedSaveStateOrder (NormalizedState::SaveOrder const &iSaveOrder)
 Called internally with the order for a deprecated version. More...
 
tresult setRTDeprecatedSaveStateOrder (NormalizedState::SaveOrder const &iSaveOrder)
 Called internally with the order for a deprecated version. More...
 

Private Attributes

std::vector< ParamID > fAllRegistrationOrder {}
 
std::map< int16, NormalizedState::SaveOrderfGUIDeprecatedSaveStateOrders {}
 
NormalizedState::SaveOrder fGUISaveStateOrder {}
 
std::map< ParamID, std::shared_ptr< IJmbParamDef > > fJmbParams {}
 
std::map< int16, NormalizedState::SaveOrderfRTDeprecatedSaveStateOrders {}
 
NormalizedState::SaveOrder fRTSaveStateOrder {}
 
std::map< ParamID, std::shared_ptr< RawVstParamDef > > fVstParams {}
 
std::vector< ParamID > fVstRegistrationOrder {}
 

Friends

class Debug::ParamDisplay
 

Detailed Description

This is the class which maintains all the registered parameters.

Member Typedef Documentation

◆ ChangeCallback

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

A callback that will be invoked for changes.

Note that unlike the IChangeListener, there is no parameter since it is expected to be used like this:

fMyParam = registerVstParam(myParamId, [this]() { .... ; });

◆ ChangeCallback1

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

A callback which will be invoked for changes with the param as an argument.

◆ ChangeCallback2

using ChangeCallback2 = std::function<void(TView *, Param &)>

A callback which will be invoked for changes with the view and param as arguments.

Constructor & Destructor Documentation

◆ Parameters()

Parameters ( )
explicitdefault

◆ ~Parameters()

virtual ~Parameters ( )
virtualdefault

Member Function Documentation

◆ add() [1/3]

RawVstParam add ( RawVstParamDefBuilder const &  iBuilder)
protected

◆ add() [2/3]

VstParam< T > add ( VstParamDefBuilder< T > const &  iBuilder)
protected

◆ add() [3/3]

JmbParam< T > add ( Parameters::JmbParamDefBuilder< T > const &  iBuilder)
protected

◆ addJmbParamDef()

tresult addJmbParamDef ( std::shared_ptr< IJmbParamDef >  iParamDef)
protected

◆ addParamID()

tresult addParamID ( std::vector< ParamID > &  oParamIDs,
ParamID  iParamID 
)
private

◆ addVstParamDef()

tresult addVstParamDef ( std::shared_ptr< RawVstParamDef >  iParamDef)
protected

◆ buildParamIDs() [1/7]

tresult buildParamIDs ( std::vector< ParamID > &  iParamIDs)
inlineprivate

◆ buildParamIDs() [2/7]

tresult buildParamIDs ( std::vector< ParamID > &  iParamIDs,
ParamID  id,
Args &&...  args 
)
private

◆ buildParamIDs() [3/7]

tresult buildParamIDs ( std::vector< ParamID > &  iParamIDs,
std::shared_ptr< IJmbParamDef > &  iParamDef,
Args &&...  args 
)
inlineprivate

◆ buildParamIDs() [4/7]

tresult buildParamIDs ( std::vector< ParamID > &  iParamIDs,
std::shared_ptr< JmbParamDef< T >> &  iParamDef,
Args &&...  args 
)
inlineprivate

◆ buildParamIDs() [5/7]

tresult buildParamIDs ( std::vector< ParamID > &  iParamIDs,
std::shared_ptr< VstParamDef< ParamConverter >> &  iParamDef,
Args &&...  args 
)
inlineprivate

◆ buildParamIDs() [6/7]

tresult buildParamIDs ( std::vector< ParamID > &  iParamIDs,
std::array< std::shared_ptr< VstParamDef< ParamConverter >>, N > &  iParamDefs,
Args &&...  args 
)
private

◆ buildParamIDs() [7/7]

tresult buildParamIDs ( std::vector< ParamID > &  iParamIDs,
std::shared_ptr< RawVstParamDef > &  iParamDef,
Args &&...  args 
)
inlineprivate

◆ getAllRegistrationOrder()

std::vector<ParamID> const& getAllRegistrationOrder ( ) const
inline

◆ getGUIDeprecatedSaveStateOrder()

NormalizedState::SaveOrder const * getGUIDeprecatedSaveStateOrder ( int16  iVersion) const
Returns
the order used when saving the GUI state (getState/setState in the controller) for the given (deprecated) version or nullptr if there is no such version

◆ getGUISaveStateOrder()

NormalizedState::SaveOrder const& getGUISaveStateOrder ( ) const
inline
Returns
the order used when saving the GUI state (getState/setState in the controller)

◆ getJmbParamDef()

std::shared_ptr< IJmbParamDef > getJmbParamDef ( ParamID  iParamID) const

◆ getRawVstParamDef()

std::shared_ptr< RawVstParamDef > getRawVstParamDef ( ParamID  iParamID) const

◆ getRTSaveStateOrder()

NormalizedState::SaveOrder const& getRTSaveStateOrder ( ) const
inline
Returns
the order used when saving the RT state (getState/setState in the processor, setComponentState in the controller)

◆ getVstRegistrationOrder()

std::vector<ParamID> const& getVstRegistrationOrder ( ) const
inline

◆ handleRTStateUpgrade()

virtual tresult handleRTStateUpgrade ( NormalizedState const &  iDeprecatedState,
NormalizedState oNewState 
) const
inlinevirtual

When Jamba detects that a previously saved RT state matches a deprecated version (as registered with setRTDeprecatedSaveStateOrder), it will call this method to let the plugin handle the upgrade if necessary.

Here is an example of a typical implementation of this method:

switch(iDeprecatedState.getVersion())
{
case kRT_V1: // assuming this is the previous version
{
// __deprecated_fNumSlices is a deprecated param (removed from deprecated state) so we read
// its value using a helper in the deprecated state
auto oldNumSlices = __deprecated_fNumSlices->readFromState(iDeprecatedState);
// fNumSlices is a new parameter (added to the new state) which handles number of slices completely
// differently so we save the new value in the new state using a helper
fNumSlices->writeToState(NumSlice{oldNumSlices}, oNewState);
return kResultTrue;
}
default:
DLOG_F(ERROR, "Unexpected deprecated version %d", iDeprecatedState.fSaveOrder->fVersion);
return kResultFalse;
}
Note
Since oNewState has already been populated with the values from iDeprecatedState that had the same parameter ID, this method should be overridden only when further tweaks need to happen (like in the above example when a parameter value which was an enumeration, need to be converted to a float)
Parameters
iDeprecatedStatethe populated deprecated state from which to read the deprecated values
oNewStatethe new state already populated with the common values from iDeprecatedState for further tweaks
Returns
kResultTrue if handled, kResultFalse if unhandled

◆ jmb() [1/2]

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

Used from derived classes to build a non vst parameter (not convertible to a ParamValue)

◆ jmb() [2/2]

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

This flavor allows the ParamSerializer to provide an actual type for the primary constructor.

◆ jmbFromType()

Parameters::JmbParamDefBuilder< T > jmbFromType ( ParamID  iParamID,
VstString16  iTitle 
)

Used from derived classes to build a non vst parameter (not convertible to a ParamValue).

Use this version if you want to provide a different serializer.

◆ newRTState() [1/2]

std::unique_ptr< NormalizedState > newRTState ( ) const
virtual
Returns
a new normalized state for RT (can be overridden to return a subclass!)

◆ newRTState() [2/2]

std::unique_ptr< NormalizedState > newRTState ( NormalizedState::SaveOrder const *  iSaveOrder) const
virtual
Returns
a new normalized state for RT (can be overridden to return a subclass!)

◆ raw()

Parameters::RawVstParamDefBuilder raw ( ParamID  iParamID,
VstString16  iTitle 
)

Used from derived classes to build a parameter backed by a raw VST parameter.

◆ readDeprecatedRTState()

tresult readDeprecatedRTState ( uint16  iVersion,
IBStreamer &  iStreamer,
NormalizedState oNormalizedState 
) const
protectedvirtual

This method is called to read a deprecated (prior version) RTState from the stream.

◆ readNormalizedValue()

ParamValue readNormalizedValue ( ParamID  iParamID,
IBStreamer &  iStreamer 
) const
virtual
Returns
normalized value read from the stream for the given parameter

◆ readRTState()

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

This method is called to read the RTState from the stream.

◆ registerVstParameters()

void registerVstParameters ( Vst::ParameterContainer &  iParameterContainer) const

This method is called from the GUI controller to register all the parameters to the ParameterContainer class which is the class managing the parameters in the vst sdk.

◆ setGUIDeprecatedSaveStateOrder() [1/2]

tresult setGUIDeprecatedSaveStateOrder ( int16  iVersion,
Args &&...  args 
)

This method should be called to save the order of a deprecated version so that it can be handled during upgrade.

A deprecated version should be used when the state changes in a non compatible fashion.

For example, adding new parameters at the end of the state is not an incompatible change and does not require to deprecate the version.

On the other end, adding new parameters in the middle and removing parameters are incompatible changes and require to deprecate the version.

Parameters
iVersionshould be a >= 0 number. If negative it will be ignored
argscan be any combination of ParamID, RawVstParamDef, VstParamDef, JmbParamDef

◆ setGUIDeprecatedSaveStateOrder() [2/2]

tresult setGUIDeprecatedSaveStateOrder ( NormalizedState::SaveOrder const &  iSaveOrder)
private

Called internally with the order for a deprecated version.

◆ setGUISaveStateOrder() [1/2]

tresult setGUISaveStateOrder ( int16  iVersion,
Args &&...  args 
)

Used to change the default order (registration order) used when saving the GUI state (getState/setState in the controller)

Parameters
iVersionshould be a >= 0 number. If negative it will be ignored
argscan be any combination of ParamID, RawVstParamDef, VstParamDef, JmbParamDef

◆ setGUISaveStateOrder() [2/2]

tresult setGUISaveStateOrder ( NormalizedState::SaveOrder const &  iSaveOrder)

Used to change the default order (registration order) used when saving the GUI state (getState/setState in the controller)

◆ setRTDeprecatedSaveStateOrder() [1/2]

tresult setRTDeprecatedSaveStateOrder ( int16  iVersion,
Args &&...  args 
)

This method should be called to save the order of a deprecated version so that it can be handled during upgrade.

A deprecated version should be used when the state changes in a non compatible fashion.

For example, adding new parameters at the end of the state is not an incompatible change and does not require to deprecate the version.

On the other end, adding new parameters in the middle and removing parameters are incompatible changes and require to deprecate the version.

Parameters
iVersionshould be a >= 0 number. If negative it will be ignored
argscan be any combination of ParamID, RawVstParamDef, VstParamDef

◆ setRTDeprecatedSaveStateOrder() [2/2]

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

Called internally with the order for a deprecated version.

◆ setRTSaveStateOrder() [1/2]

tresult setRTSaveStateOrder ( int16  iVersion,
Args &&...  args 
)

Used to change the default order (registration order) used when saving the RT state (getState/setState in the processor, setComponentState in the controller)

Parameters
iVersionshould be a >= 0 number. If negative it will be ignored
argscan be any combination of ParamID, RawVstParamDef, VstParamDef

◆ setRTSaveStateOrder() [2/2]

tresult setRTSaveStateOrder ( NormalizedState::SaveOrder const &  iSaveOrder)

Used to change the default order (registration order) used when saving the RT state (getState/setState in the processor, setComponentState in the controller)

◆ vst() [1/2]

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

Used from derived classes to build a parameter backed by a VST parameter.

◆ vst() [2/2]

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

This flavor allows the ParamConverter to provide an actual type for the primary constructor.

◆ vstFromType()

Parameters::VstParamDefBuilder< T > vstFromType ( ParamID  iParamID,
VstString16  iTitle 
)

Used from derived classes to build a parameter backed by a VST parameter.

Use this version if you want to provide a different converter.

◆ writeRTState()

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

This method is called to write the NormalizedState to the stream.

Friends And Related Function Documentation

◆ Debug::ParamDisplay

friend class Debug::ParamDisplay
friend

Member Data Documentation

◆ fAllRegistrationOrder

std::vector<ParamID> fAllRegistrationOrder {}
private

◆ fGUIDeprecatedSaveStateOrders

std::map<int16, NormalizedState::SaveOrder> fGUIDeprecatedSaveStateOrders {}
private

◆ fGUISaveStateOrder

NormalizedState::SaveOrder fGUISaveStateOrder {}
private

◆ fJmbParams

std::map<ParamID, std::shared_ptr<IJmbParamDef> > fJmbParams {}
private

◆ fRTDeprecatedSaveStateOrders

std::map<int16, NormalizedState::SaveOrder> fRTDeprecatedSaveStateOrders {}
private

◆ fRTSaveStateOrder

NormalizedState::SaveOrder fRTSaveStateOrder {}
private

◆ fVstParams

std::map<ParamID, std::shared_ptr<RawVstParamDef> > fVstParams {}
private

◆ fVstRegistrationOrder

std::vector<ParamID> fVstRegistrationOrder {}
private

The documentation for this class was generated from the following files: