AAX SDK  2.4.1
Avid Audio Extensions Development Kit
Enumerations
EQ and Dynamics Curve Displays

Displaying EQ and Dynamics curves in Pro Tools, control surfaces, and other auxiliary graphical interfaces.

About

Pro Tools, control surfaces, and other auxiliary displays connected to the AAX host may provide a curve data display to enhance the graphical representation of the plug-in's state.
A "bouncing ball" meter may also be overlaid within the curve data presentation for Dynamics plug-ins.
Pro Tools display showing an EQ plug-in instance
Pro Tools Mix Window displaying EQ plug-in instances
Pro Tools | S6 MTM display showing a Dynamics plug-in instance with bouncing-ball metering
Pro Tools | S6 MTM display showing a Dynamics plug-in instance with bouncing-ball metering

Requirements

Host Compatibility Notes:
For S6 control surface displays, see PT-226228 and PT-226227 in the Known Issues page for more information about the requirements listed in this section.
These are the requirements for supporting the AAX curve data display features:
The AAX host will only query and display curve data for plug-ins of the applicable Category, as specified in the AAX_ECurveType documentation.
In order to present a bouncing-ball metering display, Dynamics plug-ins must also support AAX_IEffectParameters::GetCurveDataMeterIds() in addition to the two other curve data methods. This feature is always optional: a Dynamics plug-in may present a curve only without support for a bouncing-ball meter overlay.

Pro Tools Implementation

There are three different kinds of calls that Pro Tools will make when querying EQ plug-ins for curve data:
Pro Tools will call GetCurveData() from a thread in a low-priority thread pool. Most other Pro Tools operations will not be blocked by the execution of this method, though note that if a control surface is also issuing queries then the method may be called concurrently from multiple host threads.
In Pro Tools, curve updates are triggered by incrementing the plug-in's change counter. This is the counter value returned from the GetNumberOfChanges() method in the plug-in. This counter is updated automatically when any plug-in parameter changes.

Testing

There are several ways to test a plug-in's S6 curve implementation:
View the plug-in using Pro Tools or another client app or control surface with curve display support
The best way to test your plug-in's curve data display support is to use a real application or control surface to test the behavior of your plug-in with real user workflows. For EQ plug-ins you can use the EQ Curve display in the Pro Tools Mix Window.
View the plug-in using the S6 Surfulator software to emulate an S6 control surface
You can view the plug-in's curve data on the emulated MTM module display. The emulator runs the same software as a true S6 system, so the curve representation in the emulator will be accurate to what would be displayed on S6 hardware.
Test EQ and Dynamics curves at high resolution within Pro Tools using the "TestGetCurveData" DigiOption
See Using DigiOptions for more information about this option.
TestGetCurveData EQ graph in plug-in header
TestGetCurveData EQ graph in plug-in header
Use the aaxh dish which is included in the DSH Test Tools package to check your plug-in's curve data
dsh> load_dish aaxh
dsh> loadpi "/path/to/your/plug-in.aaxplugin"
dsh> listeffects
	View the list of effects in your plug-in and determine which effect you want to test, if there are more than one
dsh> instantiateforcontext {plugin: 0, effect: 0, plat: native, in: mono, out: mono, rate: 48000, alg: true}
	Use whatever context parameterization is appropriate for the plug-in configuration you want to test
dsh> getcurvedata {plugin: 0, inst: 0, display: graph}
	Experiment with other display values to get other kinds of information
	You can edit the instance's parameter values within DSH using the "setparameter" command to see the effects of various parameter changes on the curve
The "getcurvedata" command will check all three curve data types and will present information for each supported type.
Here is an example of the command output using Avid's Dynamics III plug-in:
cmd_result:
  curve_data:
	AXdr:
	  values:
		supported: false
	AXdy:
	  values:
		ascii_art: |
				0|                                                                                
				 |                                                                                
				 |                                                                                
				 |                                                                                
				 |                                                                                
				 |                                                                        ********
				 |                                                            ************        
				 |                                                ************                    
				 |                                            ****                                
				 |                                       *****                                    
				 |                                   *****                                        
				 |                               *****                                            
				 |                           *****                                                
				 |                       *****                                                    
				 |                   *****                                                        
				 |               *****                                                            
				 |           *****                                                                
				 |       *****                                                                    
				 |   *****                                                                        
			  -60|****                                                                            
		  ----------------------------------------------------------------------------------------
				 | -60                                                                           0
	  
		supported: true
	AXeq:
	  values:
		supported: false
  instanceID: 0
  pluginID: 0
message_type: cmd_result
...

Enumerations

enum  AAX_ECurveType {
  AAX_eCurveType_None = 0 ,
  AAX_eCurveType_EQ = 'AXeq' ,
  AAX_eCurveType_Dynamics = 'AXdy' ,
  AAX_eCurveType_Reduction = 'AXdr'
}
 Different Curve Types that can be queried from the Host. More...
 

Auxiliary UI methods

virtual AAX_Result AAX_IACFEffectParameters::GetCurveData (AAX_CTypeID iCurveType, const float *iValues, uint32_t iNumValues, float *oValues) const =0
 Generate a set of output values based on a set of given input values. More...
 

Auxiliary UI methods

virtual AAX_Result AAX_IACFEffectParameters_V3::GetCurveDataMeterIds (AAX_CTypeID iCurveType, uint32_t *oXMeterId, uint32_t *oYMeterId) const =0
 Indicates which meters correspond to the X and Y axes of the EQ or Dynamics graph. More...
 
virtual AAX_Result AAX_IACFEffectParameters_V3::GetCurveDataDisplayRange (AAX_CTypeID iCurveType, float *oXMin, float *oXMax, float *oYMin, float *oYMax) const =0
 Determines the range of the graph shown by the plug-in. More...
 

Enumeration Type Documentation

◆ AAX_ECurveType

Different Curve Types that can be queried from the Host.

Note
All 'AX__' IDs are reserved for host messages
See also
AAX_IEffectParameters::GetCurveData()
AAX_IEffectParameters::GetCurveDataMeterIds()
AAX_IEffectParameters::GetCurveDataDisplayRange()
Enumerator
AAX_eCurveType_None 
AAX_eCurveType_EQ 

EQ Curve, input values are in Hz, output values are in dB.

Host Compatibility Notes:
Pro Tools requests this curve type for EQ plug-ins only
AAX_eCurveType_Dynamics 

Dynamics Curve showing input vs. output, input and output values are in dB.

Host Compatibility Notes:
Pro Tools requests this curve type for Dynamics plug-ins only
AAX_eCurveType_Reduction 

Gain-reduction curve showing input vs. gain reduction, input and output values are in dB.

Host Compatibility Notes:
Pro Tools requests this curve type for Dynamics plug-ins only

Function Documentation

◆ GetCurveData()

virtual AAX_Result AAX_IACFEffectParameters::GetCurveData ( AAX_CTypeID  iCurveType,
const float *  iValues,
uint32_t  iNumValues,
float *  oValues 
) const
pure virtual

Generate a set of output values based on a set of given input values.

This method is used by the host to generate graphical curves. Given a set of input values, e.g. frequencies in Hz, this method should generate a corresponding set of output values, e.g. dB gain at each frequency. The semantics of these input and output values are dictated by iCurveType. See AAX_ECurveType.

Plug-ins may also define custom curve type IDs to use this method internally. For example, the plug-in's GUI could use this method to request curve data in an arbitrary format.

Warning
S6 currently polls this method to update a plug-in's EQ or dynamics curves based on changes to the parameters mapped to the plug-in's EQ or dynamics center section page tables. Parameters that are not included in these page tables will not trigger updates to the curves displayed on S6. (GWSW-7314, PTSW-195316 / PT-218485)
Parameters
[in]iCurveTypeOne of AAX_ECurveType
[in]iValuesAn array of input values
[in]iNumValuesThe size of iValues
[out]oValuesAn array of ouptut values
Returns
This method must return AAX_ERROR_UNIMPLEMENTED if the plug-in does not support curve data for the requested iCurveType

Implemented in AAX_CEffectParameters.

◆ GetCurveDataMeterIds()

virtual AAX_Result AAX_IACFEffectParameters_V3::GetCurveDataMeterIds ( AAX_CTypeID  iCurveType,
uint32_t *  oXMeterId,
uint32_t *  oYMeterId 
) const
pure virtual

Indicates which meters correspond to the X and Y axes of the EQ or Dynamics graph.

These meters can be used by attached control surfaces to present an indicator in the same X/Y coordinate plane as the plug-in's curve data.

Parameters
[in]iCurveTypeOne of AAX_ECurveType
[out]oXMeterIdId of the X-axis meter
[out]oYMeterIdId of the Y-axis meter
Returns
This method should return AAX_ERROR_UNIMPLEMENTED if the plug-in does not implement it.

Implemented in AAX_CEffectParameters.

◆ GetCurveDataDisplayRange()

virtual AAX_Result AAX_IACFEffectParameters_V3::GetCurveDataDisplayRange ( AAX_CTypeID  iCurveType,
float *  oXMin,
float *  oXMax,
float *  oYMin,
float *  oYMax 
) const
pure virtual

Determines the range of the graph shown by the plug-in.

Min/max arguments define the range of the axes of the graph.

Parameters
[in]iCurveTypeOne of AAX_ECurveType
[out]oXMinMin value of X-axis range
[out]oXMaxMax value of X-axis range
[out]oYMinMin value of Y-axis range
[out]oYMaxMax value of Y-axis range
Returns
This method should return AAX_ERROR_UNIMPLEMENTED if the plug-in does not implement it.

Implemented in AAX_CEffectParameters.

Collaboration diagram for EQ and Dynamics Curve Displays: