AAX SDK  2.4.1
Avid Audio Extensions Development Kit

Communicating parameter state with the host.

On this page

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:
{
virtual AAX_Result TouchParameter ( AAX_CParamID inParameterID );
virtual AAX_Result ReleaseParameter ( AAX_CParamID inParameterID );
};
{
virtual void Touch ();
virtual void Release ();
};
const char * AAX_CParamID
Parameter identifier.
Definition: AAX.h:352
int32_t AAX_Result
Definition: AAX.h:337
virtual AAX_Result ReleaseParameter(AAX_CParamID iParameterID)=0
Releases a parameter from a "touched" state.
virtual AAX_Result TouchParameter(AAX_CParamID iParameterID)=0
"Touches" (locks) a parameter in the automation system to a particular control in preparation for upd...
The interface for an AAX Plug-in's data model.
Definition: AAX_IEffectParameters.h:83
The base interface for all normalizable plug-in parameters.
Definition: AAX_IParameter.h:140
virtual void Release()=0
Signals the automation system that a control has been released.
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:
{
virtual AAX_Result UpdateParameterTouch ( AAX_CParamID iParameterID, AAX_CBoolean iTouchState );
};
uint8_t AAX_CBoolean
Cross-compiler boolean type used by AAX interfaces.
Definition: AAX.h:329
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:
{
bool SetValueWithBool ( bool value );
bool SetValueWithInt32 ( int32_t value );
bool SetValueWithFloat ( float value );
bool SetValueWithDouble ( double value );
void SetNormalizedValue ( double normalizedNewValue );
bool SetValueFromString ( const AAX_CString & newValueString );
};
Generic implementation of an AAX_IParameter.
Definition: AAX_CParameter.h:238
bool SetValueWithBool(bool value) AAX_OVERRIDE
Sets the parameter's value as a bool.
Definition: AAX_CParameter.h:758
bool SetValueWithDouble(double value) AAX_OVERRIDE
Sets the parameter's value as a double.
Definition: AAX_CParameter.h:782
void SetToDefaultValue() AAX_OVERRIDE
Restores the state of this parameter to its default value.
Definition: AAX_CParameter.h:826
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:1054
bool SetValueWithInt32(int32_t value) AAX_OVERRIDE
Sets the parameter's value as an int32_t.
Definition: AAX_CParameter.h:766
bool SetValueWithFloat(float value) AAX_OVERRIDE
Sets the parameter's value as a float.
Definition: AAX_CParameter.h:774
void SetNormalizedValue(double newNormalizedValue) AAX_OVERRIDE
Sets a parameter value using it's normalized representation.
Definition: AAX_CParameter.h:922
A generic AAX string class with similar functionality to std::string
Definition: AAX_CString.h:46
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:
{
AAX_Result UpdateParameterNormalizedValue ( AAX_CParamID iParameterID, double aValue, AAX_EUpdateSource inSource);
};
AAX_EUpdateSource
Source for values passed into UpdateParameterNormalizedValue().
Definition: AAX_Enums.h:1028
Default implementation of the AAX_IEffectParameters interface.
Definition: AAX_CEffectParameters.h:66
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:
{
void UpdateNormalizedValue ( double newNormalizedValue );
};
void UpdateNormalizedValue(double newNormalizedValue) AAX_OVERRIDE
Sets the parameter's state given a normalized value.
Definition: AAX_CParameter.h:657
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: