| AAX SDK 2.8.0 Avid Audio Extensions Development Kit

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

Loading...
Searching...
No Matches
Enumerations
EQ and Dynamics Curve Displays
AAX SDK Manual » Additional AAX features

##

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 Mix Window displaying EQ plug-in instances
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:

- To support EQ curve data displays, a plug-in must support AAX_IEffectParameters::GetCurveData()
- To support Dynamics curve data displays, a plug-in must also support AAX_IEffectParameters::GetCurveDataDisplayRange() for the Dynamics curve data types.

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:

- An initial query with a small set of points. This query is used only to determine whether the plug-in supports the EQ Curve display feature. The result data is not used. If the plug-in does not support the feature it must return an error value from GetCurveData()
- A normal full-curve query to get the base curve data across the full display range
- One or more targeted queries around any detected inflection points. These queries are used to increase display resolution for plug-ins with very narrow Q settings.

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

##### 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.

## 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.
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.

## Enumeration Type Documentation

## ◆ AAX_ECurveType

enum 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.

- Note
    This method may be called by the host simultaneously from multiple threads with differents `iValues`.
- Note
    `oValues` must be allocated by caller with the same size as `iValues` (`iNumValues`).
  Host Compatibility Notes:
    Versions of S6 software which support the GetCurveDataDisplayRange() method will not display a plug-in's curve data unless both GetCurveData() and GetCurveDataDisplayRange() are supported by the plug-in.

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] | iCurveType | One of AAX_ECurveType
  [in] | iValues | An array of input values
  [in] | iNumValues | The size of `iValues`
  [out] | oValues | An 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] | iCurveType | One of AAX_ECurveType
  [out] | oXMeterId | Id of the X-axis meter
  [out] | oYMeterId | Id 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] | iCurveType | One of AAX_ECurveType
  [out] | oXMin | Min value of X-axis range
  [out] | oXMax | Max value of X-axis range
  [out] | oYMin | Min value of Y-axis range
  [out] | oYMax | Max 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: