Linked parameters

How to link parameters.

On this page

• Linked Parameter Operation
• Changing Tapers

Linked Parameter Operation

The key rule, that can be difficult to follow, is to ONLY LINK USER EDITING. As it states, this means to only link parameters when a user is editing them. This can be somewhat of a difficult rule to follow, but will simplify many issues, both preventing conflicts with automation data which can be edited by the user and avoiding strange behaviors when restoring a chunk. This means your plug-in should still operate the parameters independently without linked behaviors. This is the difficult part!

Here is how the system works WITH linked parameters (aided by our AAX SDK sample plug-in DemoGain_LinkedParameters):

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.
   • The touched parameter status comes back to the plug-in. If the parameters are linked the other linked parameter should have a TOUCH token sent. This really should only be done for linked continuous parameters. This is done by overriding the AAX_CEffectParameters::UpdateParameterTouch() method.
2. The user changes the parameter from the GUI or controls surface. A SET token should be sent at this point.

   // *******************************************************************************
   // METHOD:  UpdateParameterTouch
   // *******************************************************************************
   AAX_Result DemoGain_Parameters::UpdateParameterTouch ( AAX_CParamID inParameterID, AAX_CBoolean inTouchState )
   {
       if ( inTouchState )
       {
           AAX_CParamID linkedControl = this->GetLinkedControl ( inParameterID );
           if ( linkedControl )
           {
               this->TouchParameter ( linkedControl );
               mLinkTouchMap.insert ( std::pair<std::string,std::string>( inParameterID, linkedControl ) );
           }
       }
       [...]
   }

3. The SET token goes into the system and comes back to the plugin via AAX_CEffectParameters::UpdateParameterNormalizedValue().
   • If the parameter is linked then the other linked parameter should have it's value set for it's linked behaviour. The system knows this is a linked parameter so when the value comes back to the plug-in via UpdateParameterNormalizedValue() it will know not to perform linked behaviors on that value change. To determine if a parameter should set a linked parameter you check it with the AAX_CEffectParameters::IsParameterTouched() method.
4. The plug-in updates it's internal state and sends an UPDATE tokens for both parameters.

   // *******************************************************************************
   // METHOD:  UpdateParameterNormalizedValue
   // *******************************************************************************
   AAX_Result DemoGain_Parameters::UpdateParameterNormalizedValue ( AAX_CParamID inParameterID, double inValue, AAX_EUpdateSource inSource )
   {
       AAX_Result  result = AAX_CEffectParameters::UpdateParameterNormalizedValue ( inParameterID, inValue, inSource );
       bool        touched = this->IsParameterTouched ( inParameterID );
   
       [...]
                   if ( touched && inSource == AAX_eUpdateSource_Unspecified )
                   {
                       if ( type == eType_Pan )
                           this->SetParameterNormalizedValue( linkedControl, (1.0 - inValue) );
                       else if ( type == eType_Gain )
                           this->SetParameterNormalizedValue( linkedControl, inValue );
                   }
       [...]
   }

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.
   • The touched parameter status comes back to the plug-in. If the parameters were linked the other linked parameter should have a TOUCH token with the release status sent. This again is done by overriding the AAX_CEffectParameters::UpdateParameterTouch() method.

     // *******************************************************************************
     // METHOD:  UpdateParameterTouch
     // *******************************************************************************
     AAX_Result DemoGain_Parameters::UpdateParameterTouch ( AAX_CParamID inParameterID, AAX_CBoolean inTouchState )
     {
         if ( inTouchState )
         {
             [...]
         }
         else
         {
             [...]
                 this->ReleaseParameter ( iter->second.c_str () );
             [...]
         }
     
         return AAX_SUCCESS;
     }

Automation Playback

1. The SET token comes from the automation system and enters the plugin via UpdateParameterNormalizedValue().
   • The plug-in will know this is not from the user editing therefore it will NOT set the other linked parameter. Remember ONLY LINK USER EDITING. That way there's no conflicts if the user edited the automation or if the order in which automation arrives at the plug-in changes.
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 chuck.
2. The plug-in sets every parameters value.
3. The SET tokens comes back to the plugin via UpdateParameterNormalizedValue().
   • The plug-in will know this is not from the user editing therefore it will NOT set the other linked parameter. Remember ONLY LINK USER EDITING. Hopefully the result of this is that the contents of the chunk will be restored to its exact state.
4. The plug-in updates it's internal state and sends out UPDATE tokens.

Changing Tapers

One common use of linked parameters is to change the taper associated with a parameter. For changing tapers there are basically only a two rules you need to follow:

1. When you're loading a new chunk you need to set the taper values first. If a parameter is what updates the taper then set that value first. That way when the value of a parameter is set from a chunk it wont change because of a taper change.
2. Update the taper from the UpdateParameterNormalizedValue() method. If the new taper needs to change the value of the parameter you only do so if the user is editing the linked parameter. This still follows the ONLY LINK USER EDITING rule.

AAX_Result Simple_Parameters::UpdateParameterNormalizedValue ( AAX_CParamID inParameterID, double inValue, AAX_EUpdateSource inSource )
{
    // GetLinkedControl() is a user defined method which determines the linked control ID.
    AAX_CParamID linkedControl = this->GetLinkedControl ( inParameterID );
    if ( linkedControl )
    {
        // IsParameterLinkReady()* is a built in method of AAX_CEffectParameters which determines if the 
        // parameter should perform linked behaviors based on the touch state of the parameter and the 
        // source of the UpdateParameterNormalizedValue() call.
        if ( this->IsParameterLinkReady ( inParameterID, inSource ) )
            this->SetParameterNormalizedValue( linkedControl, inValue );
    }

    // Call the inherited method for the original parameter
    AAX_Result   result = AAX_CEffectParameters::UpdateParameterNormalizedValue ( inParameterID, inValue, inSource );
    return result;
}

Collaboration diagram for Linked parameters: