| AAX SDK 2.8.0 Avid Audio Extensions Development Kit

- Welcome
- Manual
- Classes
- Files
- Lists
- Support

Loading...
Searching...
No Matches
Token protocol
AAX SDK Manual » Additional Topics » Parameter updates

Communicating parameter state with the host.

# On this page

- An Introduction to Tokens
- Basic Token Operation

# An Introduction to Tokens

One way in which a plug-in can communicate with the "outside world" is through Shared Data Services, also known as the Token System. This is a mechanism that allows Pro Tools to share parameter information with external hardware and software modules. While the AAX SDK only uses the Token System indirectly, knowing how it works will provide a good understanding of how linked parameters should operate.

## Touch

Touch tokens inform the system of user interaction with a parameter. When a parameter is being touched the system knows to stop sending automation data to the plug-in and just use the SET value of the parameter. It is also used to tell the system when to start/stop recording new automation data.
In AAX, the touch message is sent to the host by AAX_IAutomationDelegate::PostTouchRequest(). The most common way to call this method is via the following methods:
class AAX_IEffectParameters
{
virtual AAX_Result TouchParameter ( AAX_CParamID inParameterID );
virtual AAX_Result ReleaseParameter ( AAX_CParamID inParameterID );
};
class AAX_IParameter
{
virtual void Touch ();
virtual void Release ();
};
AAX_CParamID
const char * AAX_CParamID
Parameter identifier.
Definition: AAX.h:362
AAX_Result
int32_t AAX_Result
Definition: AAX.h:347
AAX_IACFEffectParameters::ReleaseParameter
virtual AAX_Result ReleaseParameter(AAX_CParamID iParameterID)=0
Releases a parameter from a "touched" state.
AAX_IACFEffectParameters::TouchParameter
virtual AAX_Result TouchParameter(AAX_CParamID iParameterID)=0
"Touches" (locks) a parameter in the automation system to a particular control in preparation for upd...
AAX_IEffectParameters
The interface for an AAX Plug-in's data model.
Definition: AAX_IEffectParameters.h:93
AAX_IParameter
The base interface for all normalizable plug-in parameters.
Definition: AAX_IParameter.h:150
AAX_IParameter::Release
virtual void Release()=0
Signals the automation system that a control has been released.
AAX_IParameter::Touch
virtual void Touch()=0
Signals the automation system that a control has been touched.
However, AAX plug-ins will rarely need to call these methods directly since the AAX_CParameter and AAX_CEffectParameters implementations will automatically handle parameter touch and release tokens whenever a new value is set on the parameter by the plug-in.
Other clients besides the plug-in may touch a parameter. Since the TOUCH token can come from a control surface the touch state will actually come back to the plug-in via:
class AAX_IEffectParameters
{
virtual AAX_Result UpdateParameterTouch ( AAX_CParamID iParameterID, AAX_CBoolean iTouchState );
};
AAX_CBoolean
uint8_t AAX_CBoolean
Cross-compiler boolean type used by AAX interfaces.
Definition: AAX.h:339
AAX_IACFEffectParameters::UpdateParameterTouch
virtual AAX_Result UpdateParameterTouch(AAX_CParamID iParameterID, AAX_CBoolean iTouchState)=0
Sets a "touched" state on a parameter.
This method is mainly important for linked parameters.
Touch request from a view controller, with resulting async touch update

## Set

SET tokens can come from many different locations: the plug-in GUI, a control surface, loading a chunk or automation playback. Eventually the value of a SET token comes into the plug-in and that's when the internal value of the parameter gets updated. In AAX the SET token will be sent as a result of calling the following method:
class AAX_CParemeter<T>
{
void SetValue ( T newValue );
};
which will be called from many other supporting methods:
class AAX_CParameter<T>
{
bool SetValueWithBool ( bool value );
bool SetValueWithInt32 ( int32_t value );
bool SetValueWithFloat ( float value );
bool SetValueWithDouble ( double value );
void SetToDefaultValue ();
void SetNormalizedValue ( double normalizedNewValue );
bool SetValueFromString ( const AAX_CString & newValueString );
};
AAX_CParameter
Generic implementation of an AAX_IParameter.
Definition: AAX_CParameter.h:248
AAX_CParameter::SetValueWithBool
bool SetValueWithBool(bool value) AAX_OVERRIDE
Sets the parameter's value as a bool.
Definition: AAX_CParameter.h:771
AAX_CParameter::SetValueWithDouble
bool SetValueWithDouble(double value) AAX_OVERRIDE
Sets the parameter's value as a double.
Definition: AAX_CParameter.h:795
AAX_CParameter::SetToDefaultValue
void SetToDefaultValue() AAX_OVERRIDE
Restores the state of this parameter to its default value.
Definition: AAX_CParameter.h:839
AAX_CParameter::SetValueFromString
bool SetValueFromString(const AAX_CString &newValueString) AAX_OVERRIDE
Converts a string to a real parameter value and sets the parameter to this value.
Definition: AAX_CParameter.h:1067
AAX_CParameter::SetValueWithInt32
bool SetValueWithInt32(int32_t value) AAX_OVERRIDE
Sets the parameter's value as an int32_t.
Definition: AAX_CParameter.h:779
AAX_CParameter::SetValueWithFloat
bool SetValueWithFloat(float value) AAX_OVERRIDE
Sets the parameter's value as a float.
Definition: AAX_CParameter.h:787
AAX_CParameter::SetNormalizedValue
void SetNormalizedValue(double newNormalizedValue) AAX_OVERRIDE
Sets a parameter value using it's normalized representation.
Definition: AAX_CParameter.h:935
AAX_CString
A generic AAX string class with similar functionality to std::string
Definition: AAX_CString.h:57
When a SET token enters the system from the GUI, control surface or automation the value comes bak to the plug-in via the following method:
class AAX_CEffectParameters
{
AAX_Result UpdateParameterNormalizedValue ( AAX_CParamID iParameterID, double aValue, AAX_EUpdateSource inSource);
};
AAX_EUpdateSource
AAX_EUpdateSource
Source for values passed into UpdateParameterNormalizedValue().
Definition: AAX_Enums.h:1095
AAX_CEffectParameters
Default implementation of the AAX_IEffectParameters interface.
Definition: AAX_CEffectParameters.h:76
AAX_CEffectParameters::UpdateParameterNormalizedValue
AAX_Result UpdateParameterNormalizedValue(AAX_CParamID iParameterID, double iValue, AAX_EUpdateSource iSource) AAX_OVERRIDE
Updates a single parameter's state to its current value.
At this point the internal contents of the plug-in are set.
Set token asynchronously changes state of the parameter data

## Update

An update token is generated when the internal value of a parameter has been set. GUIs and control surfaces listen for UPDATE tokens to update the displayed values. In AAX the UPDATE token is sent by calling the following method:
class AAX_CParameter<T>
{
void UpdateNormalizedValue ( double newNormalizedValue );
};
AAX_CParameter::UpdateNormalizedValue
void UpdateNormalizedValue(double newNormalizedValue) AAX_OVERRIDE
Sets the parameter's state given a normalized value.
Definition: AAX_CParameter.h:670
All views of the parameter are then asynchronously notified that the value has changed. The plug-in GUI is notified via a call to AAX_IEffectGUI::ParameterUpdated().
Update token triggers async updates to all views

# Basic Token Operation

The lists below indicate how the system works in a few different standard update scenarios. To enable logging for these events set `DTF_AUTOMATION=file@DTP_LOW` in the DigiTrace configuration file. For more detailed information about the sequence of calls used to update parameters in different situations, see Basic parameter update sequences.

## User Editing

1. User clicks on a parameter in the GUI or grabs a parameter on the controls surface. A TOUCH token should be sent at this point.
2. The user changes the parameter from the GUI or controls surface. A SET token should be sent at this point.
3. The SET token goes into the system and comes back to the plugin via UpdateParameterNormalizedValue().
4. The plug-in updates it's internal state and sends an UPDATE token.
5. Repeat steps 2-4 while changing the parameter.
6. The user lets go of the GUI or controls surface. A TOUCH token with the released state should be sent.

## Automation Playback

1. The SET token comes from the automation system and enters the plugin via UpdateParameterNormalizedValue().
2. The plug-in updates it's internal state and sends an UPDATE token.
3. Repeat steps 1-2 while playing back automation.

## Chunk Restoring

1. Plug-in loads the chunk.
2. The plug-in sets every parameters value. Another thing to note is that the
3. SetValue() method also contains Touch() and Release() calls. So, while setting every parameter there is a combination of TOUCH and SET tokens sent to the system.
4. The SET tokens comes back to the plugin via UpdateParameterNormalizedValue().
5. The plug-in updates it's internal state and sends out UPDATE tokens.

Collaboration diagram for Token protocol: