AAX SDK  2.4.1
Avid Audio Extensions Development Kit
Page Table Guide

How to map a plug-in's parameters to control surfaces.

Contents

Introduction

Control Surfaces Overview

A tactile, external hardware control surface can be used to control different aspects of an application such as Pro Tools or Media Composer. Users prefer purpose-built control surfaces for DAW manipulation due to the control surface's superior accessibility, tactile feel, ergonomics, and user feedback.
Avid provides several different control surface products designed to accommodate a wide variety of user needs and workflows. Most Avid control surfaces implement EUCON (Extended User Control), a high-speed open control protocol featuring high-resolution, responsive control over almost all software functions. Some other control surfaces, such as the C|24, implement a dedicated control protocol for direct integration with Pro Tools. Finally, Pro Tools includes support for Mackie's HUI protocol and can interface with third-party control surfaces that implement this protocol.

Page Tables Overview

When a control surface is attached to a DAW system running AAX plug-ins the surface can be used to manipulate plug-ins' parameters. Plug-ins define the mapping between their parameters and control surface encoders using page tables.
Abstractly, a page table is a static mapping of a plug-in's controls to the interface of the control surface. Since a plug-in may have many more controls than the control surface can accommodate at a given time, the controls may be split across several "pages" that the user can freely switch between.
More concretely, a set of page tables is simply a set of single dimensional arrays. Each slot of the array corresponds to a particular rotary encoder or push-button of the control surface. By inserting control indices into the elements of the array, a plug-in's controls are mapped to particular tangible controls of the CS. Page tables are stored as XML data created by the Page Table Editor application available as part of the AAX SDK Toolkit on the My Toolkits and Downloads page at avid.com. The XML is referenced by the plug-in as a resource using a call to AAX_IEffectDescriptor::AddResourceInfo().
The following sections describe the various interfaces that the supported control surfaces provide for modifying plug-in parameters. Later, the specifics of implementation of page tables is described.

Avid Control Surfaces

EUCON

Pro Tools | Control app and Pro Tools | Dock

The free Pro Tools | Control app provides a EUCON-enabled control surface for iPad. Combining Pro Tools | Control with Pro Tools | S3, Pro Tools | Dock, or Artist Mix hardware adds additional touch workflows and custom control. Pro Tools | Control app controlling an EQ plug-in instance
Pro Tools | Control app display controlling an EQ plug-in instance
Pro Tools | Dock connects with an iPad and the free Pro Tools | Control iOS app, providing intelligent control of audio and video projects. The app offers a host of touch controls and visual feedback. The Dock provides eight push-top, touch-sensitive Soft Knobs that interact with whatever knobset has been chosen in the Pro Tools | Control app. Select an EQ, plug-in, send, pan, or other item, and all parameters instantly map to the knobs for tweaking.
Pro Tools | Dock with iPad and Pro Tools | Control app
When laying out plug-in parameters on its display, Pro Tools | Control uses the same page table layotus as Artist Control

Pro Tools | S6

Pro Tools | S6 is a modular control surface solution for the most demanding audio mixing and production environments. Built on the same proven technology that is core to the industry-leading ICON and System 5 product families, S6 enables mixers to quickly turn around complex projects while swiftly handling last-minute changes. With its unparalleled ability to simultaneously control multiple Pro Tools and other EUCON-enabled DAWs over simple Ethernet, S6 also speeds workflows and enables network collaboration on a single integrated platform. Pro Tools | S6
Pro Tools | S6
The main touch screen display on S6 can be configured to show graphs representing a plug-in's frequency or dynamics response curves. To support this feature, a plug-in must implement AAX_IEffectParameters::GetCurveData() for the applicable AAX_ECurveType selector.

Pro Tools | S3

Pro Tools | S3 is a compact, EUCON-enabled, ergonomic desktop control surface that offers a streamlined yet versatile mixing solution for the modern sound engineer. Like S6, S3 delivers intelligent control over every aspect of Pro Tools and other DAWs, but at a more affordable price. While its small form factor makes it ideal for space-confined or on-the-go music and post mixing, it packs enormous power and accelerated mixing efficiency for faster turnarounds, making it the perfect fit everywhere, from project studios to the largest, most demanding facilities. Pro Tools | S3
Pro Tools | S3
On the S3 control surface, the top-right eight encoder/OLED pairs may be dedicated to any plug-in instance. In addition, the S3 includes support for dedicated EQ and dynamics plug-ins: a user can select a particular plug-in as his EQ or dynamics processor and use the surface's EQ, Compressor/Limiter, and Expander/Gate selectors to bring up the plug-in in a separate group of eight encoders. This mode uses the plug-in's D-Control Center Section EQ or Dynamics page tables when mapping plug-in controls. In order to be selectable as the system's EQ or dynamics processor a plug-in must meet the criteria for an ICON center-section plug-in.

Avid Artist Series: Artist Control

The Artist Control can run as either a standalone device or connected to additional units to form a larger system for your favored DAW. Encoder layout for the Artist Control surface
EUCON Artist Series: Artist Control
The plug-in editing section for the Artist Control consists of 8 touch and velocity sensitive rotary encoders, and 8 touch screen switches. The rotary knobs are physically laid out as two groups of 4, vertically aligned and positioned next to the customizable LED-backlit touch-screen interface, with their corresponding touch screen switches right next to them. The alpha-numeric scribble strip and plug-in editing displays are 8 characters wide. The knobs and switches can be assigned using the Av81 page table.
Mapping of plug-in parameters to the surface's various controllers can also be done through use of the ProControl or D-Control page tables, giving the Artist Control the ability to emulate various plug-in editing sections(D-Control's Center Section EQ/Dynamics Sections and Channel Strip ) or as a dedicated plug-in editing section (ProControl). Consequently, if using the ProControl page table, plug-in developers will have access to 16 controls, rotary encoders numbered top to bottom, left to right, as 0 through 7, and touch screen switches numbered top to bottom, left to right, as 8 through 15.

Avid Artist Series: Artist Mix

The Artist Mix can run as either a standalone device or connected to additional units to form a larger system for audio mixing applications.
Encoder layout for the Artist Mix surface
EUCON Artist Series: Artist Mix
The plug-in editing section for the Artist Mix consists of 8 touch and velocity sensitive rotary encoders, and 8 switches. The rotary knobs are physically laid out horizontally along the top of the control surface as a goup of 8, located right below the display screen, with the switches located directly below the encoders (the "ON" buttons). The alpha-numeric scribble strip and plug-in editing display are 8 characters wide. The Artist Mix is mapped using the Av18 page table, with the recommendation that the most important parameter is listed first. Like the Artist Control, mapping of plug-in parameters to the surface's various controllers can be done through use of the ProControl and/or D-Control page tables. This allows the Artist Mix to emulate the various plug-in editing sections that pertain to the D-Control, as well as the ProControl's dedicated plug-in section. Both rotary encoders and switches are numbered right to left, as 0 through 7, and 8 through 15 respectively.

Avid Pro Series: System 5

The System 5 Avid series consists of digital audio mixing systems that can be configured with hundreds of channels. These systems are used specifically for audio post production and music applications. Channels have a 4 band EQ, dynamics, two filters, and consist of 8 rotary knobs and a touch-sensitive motorized fader.
The plug-in editing section consists of 8 knob/switch pairs. This section can take it's mapping from the Av81 page table, with the recommendation that the most important parameter is last (closer to the operator). Like the Artist Series of EUCON controllers, mapping of plug-in parameters can also be accomplished through use of either ProControl or D-Control page tables. When using these page tables, the plug-in editing section is numbered top to bottom, 0 through 7, and 8 through 15, respectively.
The System 5 can also be put into a mode where a single plug-in is mapped across 4 rows of rotary knobs across an entire 8-fader bank. This mode uses the Av48 page table.

Avid Pro Series: MC Pro

The MC Pro is a workstation control surface that is geared towards professional post production. As the professional version of Avid's Artist Series Artist Control, it delivers precise and fast control of your editing applications.
The plug-in editing section consists of 8 pairs of touch-sensitive rotary knobs and switches. The rotary knobs are equipped with LED display rings that are available for control of EQ, Dynamics or any type of control your plug-in may need. As with the Artist Control, plug-in parameters can be mapped with the EUCON Av81 page table or by the ProControl or D-Control page tables described below. The 8 knobs are placed as two vertical groups of 4, laid out on the left half of the control surface, and are numbered top to bottom, left to right.

Avid C|24 and ICON

C|24

C|24 is a hardware control surface allowing great flexibility and power to Pro Tools systems. The alphanumeric scribble strip and plug-in editing displays allow 4 characters each for the plug-in name and a control's name. Three characters are allowed for the control's value.
Encoder layout for the C|24 surface
C|24
The plug-in editing section consists of 24 horizontally aligned rotary data encoders and 24 switches lined up under the encoders. (the image above shows only 12 so that more detail can be displayed.) The C|24 encoders and switches are set up as pairs.
In any given control pair, either the encoder or a mix of encoder + the switch is used depending on how the mapped parameter has been defined in the plug-in:
Therefore, whether the plug-in has all switches, all encoders, or a mix, there are 24 controls available per page on the C|24.

ICON: D-Control ES

D-Control is a modular hardware control surface that adds high-quality tactile mixing and editing capability to Pro Tools systems. D-Control is a high-end mixing system that includes a center section and one or more fader packs. A fader pack consists of 16 channel strips, displaying track and plug-in information. Further general information about D-Control and how it works is available from the "BuckleyBriefing.pdf" on the developer website.
D-Control has the potential of displaying plug-in controls in four different sections: Channel Strip, Custom Fader, Center Section EQ, and Center Section Dynamics. The Dynamics section actually makes use of two different page table types, while the other three each have one page table type. In all sections, scribble strips are 6-characters wide and do not support the Digidesign Extended character set (i.e. special characters).

ICON: D-Command ES

D-Command ES is a more compact yet expandable console than the D-Control. Coming standard with 8 physical faders/channel strips (two encoders per strip), it is expandable to 40 faders/channels.
The plug-in editing section for the D-Command follows closely to that of the D-Control, with two encoders per channel strip. It provides dedicated Dynamics and EQ sections for plug-ins that support Dynamics and EQ plug-in mapping, as well as the ability to display plug-ins in a Custom Fader section as described in the D-Control section. All sections provide scribble strips that 6 alpha numeric characters wide.

VENUE

VENUE is a revolutionary line of digital live sound systems that deliver amazing sound quality, reliability, flexibility, and ease-of-use. These live sound systems come equipped with plug-in editing sections, and work together to deliver studio-grade sound and powerful performance. For more information about using AAX plug-ins with VENUE systems see the VENUE Guide.

VENUE | S6L

VENUE | S6L is a modular system designed to take on the world's most demanding tours and events with ease. Offering unprecedented processing capabilities - with over 300 processing channels - S6L delivers unrelenting performance and reliability through its advanced engine design and backs it up with modern touchscreen workflows and scalability to meet any challenge. VENUE | S6L console
VENUE | S6L console
S6L uses the same modular components as Pro Tools | S6, but uses a different set of encoder layouts on these components in order to best support mixing workflows in a live sound setting. When displaying plug-in parameters, S6L maps the parameters onto its CKM. The leftmost two columns on the CKM are reserved (one column for constant operations, one as a "spacer" row with not assignments), leaving six columns of knob cells available for plug-in parameters. S6L uses the 'Av46' 4x6 page table type to map plug-in parameters to the CKM knob cells in this mode.
If a 'Av46' page table is not available from the plug-in, S6L uses the plug-in's C|24 'FrTL' layout in order to map one plug-in parameter to each of the 24 available knob cells. This generally leads to a very sub-optimal layout of parameters on the surface, both because the C|24 page table is designed for a linear layout and because it results in only one parameter assigned per knob cell, leaving two of the available encoders unassigned. Therefore, Avid strongly recommends that all AAX DSP plug-ins which are compatible with S6L are updated to include the new 4x6 page table layout.
S6L also supports dedicated EQ and dynamics plug-ins: a user can select a particular plug-in as his EQ or dynamics processor and use the surface's EQ, Compressor/Limiter, and Expander/Gate selectors to display the plug-in's parameters using a fixed layout for the given plug-in type. This mode uses the plug-in's D-Control Center Section EQ or Dynamics page tables when mapping plug-in controls. In order to be selectable as the system's EQ or dynamics processor a plug-in must meet the criteria for an ICON center-section plug-in.

VENUE | S3L-X

The VENUE | S3L-X System is a modular live sound solution including an HDX-powered processing engine, scalable remote I/O, and an S3 control surface VENUE | S3L-X System
VENUE | S3L-X System
When used as part of an S3L system, the top-right eight encoder/OLED pairs on the S3 control surface (the Global Control encoders) may be placed into Insert mode in order to map to any plug-in instance. When in Insert Mode, the Global Control encoders use the plug-in's 'PcTL' page tables to map parameters onto the surface encoders.
Like S6L, S3L also includes support for dedicated EQ and dynamics plug-ins: a user can select a particular plug-in as his EQ or dynamics processor and use the surface's EQ, Compressor/Limiter, and Expander/Gate selectors to bring up the plug-in on the top-left eight encoder/OLED pairs on the S3 (the Channel Control encoders.) This mode uses the plug-in's D-Control Center Section EQ or Dynamics page tables when mapping plug-in controls. In order to be selectable as the system's EQ or dynamics processor a plug-in must meet the criteria for an ICON center-section plug-in. See Using Channel Control in the VENUE Guide and also Center Section Parameter Mapping on VENUE | S3L-X below for more information about encoder mapping in Channel Control mode.

Plug-In Page Table Guidelines

This section is intended as a guide in setting up defined 'pages' using some general rules. However, due to the sheer number of variables, it is simply not possible to account for all scenarios. But by following these suggestions, an AAX plug-in developer should find these guidelines useful in setting up their own plug-in pages. Moreover, it is hoped that a consistent and somewhat standard mapping topology will be realized across the broad range of plug-ins and control surfaces.
Here, we are primarily concerned with the number of controls on a control surface (CS) available for plug-in editing; and secondarily with the layout of controls provided for plug-ins. Accordingly, we need a method of mapping a plug-in's control parameters to a CS, and we need to take into account the varying numbers of controls available on a CS. Using 'page tables', from a software point of view, a plugin's control parameters can be mapped to a CS. Each page of the page table describes which of the plugin's parameters will be accessible from the CS's controls that are used for plug-in editing. Multiple pages are needed in the case where a CS has fewer controls available than the actual number of controls on a plug-in. We begin by stating guidelines that should be followed when mapping a plug-in's control parameters to a CS. At the end of this chapter, you will find the technical details of creating page tables for your plug-in.
The following guidelines are for simple, generic control surfaces. More advanced CSs, such as the MackieHUI and ProControl, have some guidelines of their own which are listed after these.

General Guidelines

Map a plug-in's controls from left-top to right-bottom sequentially onto each page.
Follow the layout of the plug-in GUI as closely as possible, allowing the controls to sequentially map to the Control Surface in the order specified above. In so doing, the CS controls will match the plug-in GUI; in the sense that by counting the location of a given control on the PI GUI, one should be able to grasp the corresponding slider or pot on the CS.
Note that Master Bypass, located in the plug-in's floating inserts window, should nearly always be placed as the first control on the first page. The only time this guideline might not be followed is if the plug-in has a particularly favorable layout for the control surface, and where this placement of Master Bypass would disrupt it. Also, on some control surfaces a dedicated bypass is already provided, in which case theMaster Bypass should not be mapped into the page table.
Related control parameters should be grouped together on the same page.
Controls that are often 'adjusted' with other similar or related controls should be mapped to the same page. This enhances the users ability to tweak related parameters and alleviates unnecessary paging.
Related control parameters should not be split across pages.
This follows directly from the bullet above. If some closely related controls cannot all fit on the same page, it is better to leave some blanks (i.e., unused pots, sliders, or switches) and move onto the next page where they can be adjusted together.
As a hypothetical example, let's say a control surface has 5 sliders, and we are mapping an EQ PI with 6 parameters - a low, mid, and high frequency band which has gain for each band. It would be best to map them to the CS as follows on page 1, from left to right on the CS: low freq, low gain, mid freq, mid gain, blank. Then map the remaining two parameters onto page 2: high freq, high gain, blank, blank, blank.
Equivalent left and right stereo parameters should remain on the same page.
Since adjusting the left or right parameter of a stereo PI has considerable impact on the sound field, it is important that equivalent left and right stereo controls remain on the same page. Contrast this to placing the left parameters on one page, and the right parameters on another which is not desirable. This rule also changes according to the controller's layout. As an example, the CS-10 has 6 pots for PI editing arranged in a matrix of 3 rows x 2 columns. From left to right, the pots in row 1 are numbered 1 and 4. In row 2 the pots are numbered 2 and 5. Finally, the pots in row3 are numbered 3 and 6. A layout for L/R controls should be mapped param1L = control 1, param1R = control 4, and so on.
Repeat control parameters on pages where it makes sense to do so.
In some situations, it is desirable to have access to the same control on many pages. For example, this might mean having an output and/or input gain control available on each page of an EQ PI - since EQs change the overall gain. This is especially desirable if there would otherwise be blanks (i.e., unused pots, sliders, or switches).

Avid Center Section Page Tables

"Center Section" page tables provide a mapping of plug-in parameters to dedicated functions. These page tables are used by D-Control/D-Command (ICON), D-Show (VENUE), and EUCON-enabled consoles to provide a consistent user experience when interacting with EQ and Dynamics plug-ins.
There are three Center Section page table types:
Table type Plug-in category
'DgEQ' EQ
'DgCP' Compressor/Limiter (Dynamics)
'DgGT' Expander/Gate (Dynamics)
Dynamics plug-ins that include both Compressor/Limiter and Expander/Gate processing should support both DgCP and DgGT page tables.
The control surfaces which use these page tables each use a different physical layout of parameter functions onto the surface. These layouts have been designed to provide an intuitive and consistent way to control EQ and Dynamics plug-ins in a way that is appropriate for the encoder layout on each surface. By adding these page tables to your EQ and Dynamics plug-ins, your plug-ins will map correctly to all products which use these tables.

Center Section Page Table Guidelines

It is important to note that Center Section page table types are different from all other page table types in a fundamental way:
Each slot in the page table is pre-defined for a specific type of control. Therefore, your plug-in must conform to this pre-defined layout.
The purpose of these tables is to give the user a standard interface for EQ and Dynamics plug-ins - no matter what particular plug-in they are using. It allows the user to quickly access the most common controls in their favorite EQ or Dynamics plug-ins. This is different from all other page table types because the only restriction on other page table types is that - for types that have dedicated discrete controls - you cannot place continuous controls in a dedicated switch. However, the user will also know that if there are controls they would like to access that are missing from the Center Section, they can access them through one of the other layouts available on the control surface.
You'll notice looking at the pictures of these sections in D-Control (below) that the only scribble strips are in the center of the section. Unlike the Channel Strip section, there is not a scribble strip to label each control. The control's purpose is physically printed on the control surface. This model of hard-coding "center section" plug-in functions to specific encoders is followed on VENUE systems and on EUCON-enabled control surfaces which use these table types as well. That is why it is imperative that your plug-in conform to the pre-defined layout.
Because of the strict definitions of the layouts, it may mean that 1) not all of the controls for your plug-in can fit in these sections, and that 2) there may be controls your plug-in does not have and therefore are blank in this view. For example, let's say your plug-in is a 10-band EQ that does not have individual Q controls on any of the bands. Such a plug-in will be forced to leave off some of its bands, even though all Q controls specific to the bands on the page table are empty. That is fine as there will be another way for the user to display the plug-in on the control surface that will include all of the controls. For example, on D-Control, a user can also view an EQ or Dynamics plug-in in both the Channel Strip and Custom Fader modes which will display all controls. The important point is this:
Do not assign a parameter to a Center Section page table slot that does not match the parameter's function.
If you do, the parameter's function will be mislabeled and will cause confusion for the user.
You should only implement one page for these Center Section layouts. This is different from the other page table types, where it is expected to implement as many pages as necessary to give access to all controls in the plug-in. In the case of the Center Section layouts, you should only define one page, except in the case when the plug-in has separate controls for each channel (Left, Right, Center, etc.).
More than one page in Center Section layouts is allowed only if the plug-in has separate controls for each channel.
For example, if your EQ plug-in allows the user to change the EQ differently for the left and right channels, then you would implement two pages for the DgEQ page table. You'll notice in the pictures below for the EQ and Dynamics sections of D-Control, there are buttons labeled for channel selections (L, LC, C, RC, R, etc.). The control surface will automatically map the pages to the buttons, according to the standard order for surround channels. For example, in a stereo EQ, Left controls should be in the first page, and Right controls in the second. D-Control will automatically map page 1 to the L button and page 2 to the R button.
Note
We cannot emphasize strongly enough that trying to fill in all of your controls into these layouts, whether it is by creating extra pages, or by filling in empty slots, will only serve to confuse the user. You must adhere strictly to the guidelines given for these sections.

EQ Center Section Page Table Guidelines

To demonstrate the guidelines for EQ Center Section tables, we will use the D-Control Center Section encoders. Since all control surfaces which use Center Section page tables use a similar approach with hard-coded layouts for these types, the guidelines in this section are equally applicable to all control surfaces.
Take a look at D-Control's EQ section more closely in the image below.
Encoder layout for the D-Control surface's EQ center section
D-Control EQ Center Section.
It supports a maximum of seven bands of EQ, each a vertical column of controls and labeled from left to right as follows:
Each of these bands has a Q/Slope control, Frequency control, and an In Circuit/ Out of Circuit button. Five of the bands have an additional Gain control. Four of the bands have an additional EQ type selector switch, each surrounded by a pair of EQ type LED's. Input and Output Level controls are also available, as is a multi-channel Link button in the middle section.
Note
If an EQ plug-in implements a band that does not have an In/Out Circuit control or a Type control, but wants the related LED's to light properly, please see the discussion of the GetParameterValueInfo() API below.
The topmost rotary encoders in the HPF, LF, HF, and LPF bands are not labeled but they are indeed Q / Slope controls. The EQ type selector switches located between the Q/Slope and Frequency knobs control the type of filter on that band. Thus they define the behavior of all controls in that band (and not just the unlabeled Q/Slope control).
The EQ page table indices map to the dedicated EQ Center Section hardware encoders as follows:
Note
In order to use the "Q/Slope alternate parameter" functions in the EQ page table, a plug-in must respond to the AAX_ePageTable_UseAlternateControl selector in the GetParameterValueInfo() method. When the band type is changed, the control surface will call into the plug-in with this selector to determine if the control in the "Alt" position should be used. Please see the discussion of the GetParameterValueInfo() below.
If your plug-in supports fewer than seven simultaneous bands of EQ, you have some options for where to place them. We recommend the following placement guidelines so users have consistency with various EQ plug-ins.
Note that this layout includes a few additional functions not in D-Control's EQ section. These extra functions are the "Low-Mid Filter - Type switch", "Mid Filter - Type switch", and "High-Mid Filter - Type switch" slots.

Dynamics Center Section Page Table Guidelines

To demonstrate the guidelines for Dynamics Center Section tables, we will use the D-Control Center Section encoders. As with the EQ Center Section tables above, all control surfaces which use Center Section page tables use a similar approach with hard-coded layouts for these types, the guidelines in this section are equally applicable to all control surfaces.
The D-Control Dynamics section is shown below. Keep in mind that the D-Control's Dynamics section displays page tables for both the Compressor/Limiter page table type and the Expander/Gate type. Therefore, the function of certain rotaries and switches differs depending on which page table type has been loaded. In these cases, there is a LED to indicate the current function of a rotary or switch.
Encoder layout for the D-Control surface's Dynamics center section
D-Control Dynamics Center Section.
Several rotary encoders have alternate uses while others are always dedicated to one function. The two page tables' indices map to the dedicated Dynamics Center Section hardware encoders as follows:
The compressor/limiter page table, DgCP, supports all the controls above except Range, Hysteresis, and Hold. (As you create the page table in the Page Table Editor, this is clear.)
The expander/gate page table, DgGT, supports all the controls above except Knee and Makeup Gain. It does support both Ratio and Range. The user presses the Page button to select between them.
A plug-in can support both DgCP and DgGT page tables. Again, the user presses the Page button to select between them. If a plug-in supports both of these page tables and the DgGT page table includes support for both Ratio and Range controls, pressing the Page button will switch between all available controls as follows:
DgCP -> DgGT with Ratio -> DgGT with Range (and all other controls unchanged)-> DgCP -> ...

Center Section Parameter Mapping to Single-Column/Row Layouts

The following tables show the layout mapping and hard-coded names for center section page tables on EUCON surfaces which use single-column or single-row layouts for Eq and Dyn plug-in modes. The tables show the assignment of specific center section table indices to cells on the EUCON control surface. Each EUCON control surface cell includes three encoders: a rotary knob encoder and two push-button encoders. These tables use the following codes to indicate encoders in each control surface cell:
Note
For center section page table layouts the "Sel" push-button encoder is only used to toggle the rotary encoder between two possible parameters. It is never mapped to a single discrete parameter in these layouts.
With some versions of EUCON, the cell mapping on the first page is "reversed" relative to the second page when the surface is laid out horizontally; the first page moves left to right through increasing cell indices, while later pages move right to left.

'DgEQ' PageTable - Equalizer

Page 1 Page 2
Far from user / Left Close to user / Right Far from user / Left Close to user / Right
Function 8 7 6 5 4 3 2 1 16 15 14 13 12 11 10 9
1 HPF In/Out Knob/In
2 HPF Type In
3 HPF Freq Knob (Sel O)
4 HPF Q Knob (Sel I)
5 Lo In/Out In
6 Lo Type In
7 Lo Gain Knob
8 Lo Freq Knob (Sel O)
9 Lo Q Knob (Sel I)
10 Lo Mid In/Out In
11 Lo Mid Type In
12 Lo Mid Gain Knob
13 Lo Mid Freq Knob (Sel O)
14 Lo Mid Q Knob (Sel I)
15 Mid In/Out In
16 Mid Type In
17 Mid Gain Knob
18 Mid Freq Knob (Sel O)
19 Mid Q Knob (Sel I)
20 Hi Mid In/Out In
21 Hi Mid Type In
22 Hi Mid Gain Knob
23 Hi Mid Freq Knob (Sel O)
24 Hi Mid Q Knob (Sel I)
25 Hi In/Out In
26 Hi Type In
27 Hi Gain Knob
28 Hi Freq Knob (Sel O)
29 Hi Q Knob (Sel I)
30 LPF In/Out Knob/In
31 LPF Type In
32 LPF Freq Knob (Sel O)
33 LPF Q Knob (Sel I)
34 Input Level Knob
35 Output Level Knob
36 Link
37 HPF Q Alt Knob (Sel I)*
38 Lo Q Alt Knob (Sel I)*
39 Lo Mid Q Alt Knob (Sel I)*
40 Mid Q Alt Knob (Sel I)*
41 Hi Mid Q Alt Knob (Sel I)*
42 Hi Q Alt Knob (Sel I)*
43 LPF Q Alt Knob (Sel I)*
Notes

Both 'DgCP' and 'DgGT' PageTables - Multi-dynamics

If both Dynamics center section page table types are defined for the plug-in then EUCON control surfaces will use the following mapping.
Note
Some control surfaces may only partially follow this mapping. For example, the mapping of the Artist Mix control surface in Dyn mode uses two pages: it follows this mapping for encoder cells 1-8 on the first page and follows the 'DgCP'-only mapping for encoder cells 9-16 on the second page.
Page 1 Page 2
Far from user / Left Close to user / Right Close to user / Left Far from user / Right
Function 8 7 6 5 4 3 2 1 16 15 14 13 12 11 10 9
DgCP 1 C Threshold Knob Knob
DgCP 2 C Ratio Knob Knob
DgCP 3 C Attack Time Knob Knob
DgCP 4 C Release Time Knob Knob
DgCP 5 C Knee Knob
DgCP 6 C Gain Makeup Knob
DgCP 7 HPF Enabled
DgCP 8 HPF Type
DgCP 9 HPF Freq
DgCP 10 HPF Q
DgCP 11 LPF Enabled
DgCP 12 LPF Type
DgCP 13 LPF Freq
DgCP 14 LPF Q
DgCP 15 Ext Key
DgCP 16 Key Listen
DgCP 17 Input Gain
DgCP 18 Output Gain
DgCP 19 Link Knob
DgCP 20 Depth
DgGT 1 X Threshold Knob
DgGT 2 X Ratio Knob
DgGT 3 X Range
DgGT 4 X Attack Time Knob
DgGT 5 X Release Time Knob
DgGT 6 X Hysteresis
DgGT 7 X Hold
Page 3 Page 4
Close to user / Left Far from user / Right Close to user / Left Far from user / Right
Function 24 23 22 21 20 19 18 17 32 31 30 29 28 27 26 25
DgCP 1 C Threshold
DgCP 2 C Ratio
DgCP 3 C Attack Time
DgCP 4 C Release Time
DgCP 5 C Knee
DgCP 6 C Gain Makeup
DgCP 7 HPF Enabled Knob/In
DgCP 8 HPF Type In
DgCP 9 HPF Freq Knob (Sel O)
DgCP 10 HPF Q Knob (Sel I)
DgCP 11 LPF Enabled Knob/In
DgCP 12 LPF Type In
DgCP 13 LPF Freq Knob (Sel O)
DgCP 14 LPF Q Knob (Sel I)
DgCP 15 Ext Key Knob/In
DgCP 16 Key Listen Knob/In
DgCP 17 Input Gain Knob
DgCP 18 Output Gain Knob
DgCP 19 Link
DgCP 20 Depth
DgGT 1 X Threshold Knob
DgGT 2 X Ratio Knob
DgGT 3 X Range Knob
DgGT 4 X Attack Time Knob
DgGT 5 X Release Time Knob
DgGT 6 X Hysteresis Knob
DgGT 7 X Hold Knob
Notes

'DgCP' PageTable - Compressor/Limiter

If the plug-in defines a 'DgCP' page table but does not define a 'DgGT' page table then EUCON control surfaces will use the following mapping.
Page 1* Page 2
Far from user / Left Close to user / Right Far from user / Left Close to user / Right
Function 8 7 6 5 4 3 2 1 16 15 14 13 12 11 10 9
1 C Threshold Knob
2 C Ratio Knob
3 C Attack Time Knob
4 C Release Time Knob
5 C Knee Knob
6 C Gain Makeup Knob* Knob*
7 HPF Enabled Knob/In
8 HPF Type In
9 HPF Freq Knob (Sel O)
10 HPF Q Knob (Sel I)
11 LPF Enabled Knob/In
12 LPF Type In
13 LPF Freq Knob (Sel O)
14 LPF Q Knob (Sel I)
15 Ext Key Knob/In
16 Key Listen Knob/In
17 Input Gain Knob
18 Output Gain Knob
19 Link
20 Depth Knob
Notes

'DgGT' PageTable - Expander/Gate

If the plug-in defines a 'DgGT' page table but does not define a 'DgCP' page table then EUCON control surfaces will use the following mapping.
Page 1 Page 2
Far from user / Left Close to user / Right Far from user / Left Close to user / Right
Function 8 7 6 5 4 3 2 1 16 15 14 13 12 11 10 9
1 X Threshold Knob
2 X Ratio Knob
3 X Range Knob
4 X Attack Time Knob
5 X Release Time Knob
6 X Hysteresis Knob
7 X Hold Knob
8 HPF Enabled Knob/In
9 HPF Type In
10 HPF Freq Knob (Sel O)
11 HPF Q Knob (Sel I)
12 LPF Enabled Knob/In
13 LPF Type In
14 LPF Freq Knob (Sel O)
15 LPF Q Knob (Sel I)
16 Ext Key Knob/In
17 Key Listen Knob/In
18 Input Gain Knob
19 Output Gain Knob
20 Link

Center Section Parameter Mapping in S6 Expand Mode

In addition to supporting single-row and single-column EQ and Dynamics layouts as described above, S6 also includes an Expand Mode for EQ and Dynamics plug-ins which allows the targeted plug-in's EQ or Dynamics center section mapping to be displayed across an entire CKM module.

'DgEQ' PageTable - Equalizer

EQ layout in S6 Expand Mode
EQ layout in S6 Expand Mode

'DgCP' and 'DgGT' PageTables - Compressor/Limiter and Expander/Gate

Dynamics layout in S6 Expand Mode
Dynamics layout in S6 Expand Mode

Center Section Parameter Mapping on VENUE | S3L-X

Built-in processing parameters are mapped to the Channel Control encoders on VENUE | S3L. For more information about Channel Control mode in S3L-X see Using Channel Control in the VENUE Guide.

'DgEQ' PageTable - Equalizer

Channel Control
Encoder
Knob Sel Switch In Switch
1 Low Gain Low EQ band in/out
2 Low Freq/Q Toggles Freq/Q Low EQ band type
3 LoMid Gain LoMid EQ band in/out
4 LoMid Freq/Q Toggles Freq/Q
5 HiMid Gain HiMid EQ band in/out
6 HiMid Freq/Q Toggles Freq/Q
7 High Gain High EQ band in/out
8 High Freq/Q Toggles Freq/Q High EQ band type

'DgCP' and 'DgGT' PageTables - Compressor/Limiter and Expander/Gate

Channel Control
Encoder
Knob Sel Switch In Switch
1 Threshold level Comp/Lim or Exp/Gate in/out
2 Ratio
3 Attack
4 Knee
5 Release
6 Gain level
7 Key HF Key Listen Filter in/out
8 Key LF Key In Filter in/out

EUCON Page Tables

Plug-ins should implement specific EUCON page tables to take advantage of EUCON-specific features and layouts. By writing EUCON-specific page tables, your plug-in is able to re-define both the in/out button as well as the select button per EUCON control cell on compatible surfaces.
Host Compatibility Notes:
Pro Tools versions prior to Pro Tools 11.1 use plug-ins' ProControl and ICON page tables (Dynamics, EQ, Channel Strip, Custom Fader, etc.) to map plug-in parameters to EUCON-enabled surfaces, so be sure that your plug-ins also implement these page tables correctly so that users with earlier versions of Pro Tools can have the best possible experience when using your plug-ins.
Note
The legacy PeTE editor will remove all EUCON sections from any page table XML file that it saves. Developers should no longer use PeTE for AAX page table editing. If you do use Pete, it is important to always back up your page table file before editing the file in PeTE.

Specification

EUCON page tables use modern formatting, making them more intuitive to implement than non-EUCON tables. Here are some example lines from a EUCON page table:
<PageTable type='Av18' pgsz='24' >
<Page num='1'\>
<Cell row='1' col='1' knobID="Knob1" inOutButtonID="Button1A" selectButtonID="Button1B" />
<Cell row='1' col='2' knobID="Knob2" inOutButtonID="Button2A" selectButtonID="Button2B" />
<Cell row='1' col='3' knobID="Knob3" inOutButtonID="Button3A" selectButtonID="Button3B" />
...
</Page\>
...
</PageTable >
The EUCON PageTable element includes a series of Cell sub-elements. The attributes of each Cell sub-element are as follows:

Types

Av81 Av18 Av48 Av46
type='Av81' type='Av18' type='Av48' type='Av46'
8 rows 1 row 4 rows 4 rows
1 column 8 columns 8 columns 6 columns
pgsz='24' (3 elements per cell) pgsz='24' (3 elements per cell) pgsz='96' (3 elements per cell) pgsz='72' (3 elements per cell)
Used for vertical sets of knob cells Used for horizontal sets of knob cells Used for 4x8 knob cell arrays, e.g. S6 "Expand Mode" Used for 4x6 knob cell arrays, e.g. plug-in layouts on S6L
Most important parameters should be placed in highest-numbered rows (closest to user) Most important controls should be placed in lowest-numbered columns (left) Layout should be similar to plug-in GUI Layout should be similar to plug-in GUI

Conventions

Requirements

Implementing Page Tables

Page table XML specification

This section includes a rough specification for plug-in page table XML. Whenever possible, we encourage developers to use the Page Table Editor tool to generate plug-in page tables rather than writing or editing the page table XML by hand.
The page table XML format contains three main tags:

PageTableLayouts tag

This section provides a static mapping of control elements to page table layouts. Multiple layouts may be provided in this section, e.g. in cases where different control sets are used by different plug-in Types.
Each layout includes a complete set of page table descriptions. There are multiple kinds of page tables, each of which may have multiple pages. At minimum, each layout must include a PageTable with type='pgTL' and pgsz='1'. This is the default page table, and the order of the control elements that it describes must match the order in which the corresponding parameters are added to the plug-in itself.
Here is an excerpt from the PageTableLayouts section in Avid's Eleven plug-in page tables demonstrating non-EUCON PageTable elements. For the EUCON PageTable element specification, see Eucon page table specification.
<PageTableLayouts>
<Plugin manID='Digi' prodID='ElvF' plugID='ELFr'>
<Desc>Eleven Free 1 -&amp;gt; 1 by Avid Technology, Inc.</Desc>
<Layout>PageTable Free</Layout>
</Plugin><!--manID='Digi' prodID='ElvF' plugID='ELFr'-->
<Plugin manID='Digi' prodID='Elvn' plugID='ELVr'>
<Desc>Eleven 1 -&amp;gt; 1 by Avid Technology, Inc.</Desc>
<Layout>PageTable 1</Layout>
</Plugin><!--manID='Digi' prodID='Elvn' plugID='ELVr'-->
<!-- ... -->
<PTLayout name='PageTable 1'>
<PageTable type='BkCS' pgsz='12'>
<Page num='1'>
<ID>Mic Type</ID>
<ID>Cab Type</ID>
<ID>Amp Type</ID>
<ID>Master</ID>
<ID>Gain 2</ID>
<ID>Gain 1</ID>
<ID>Mic Axis</ID>
<ID>Cab Type</ID>
<ID>Amp Type</ID>
<ID> </ID>
<ID> </ID>
<ID>Bright Switch</ID>
</Page><!--num='1'-->
<Page num='2'>
<!-- ... -->
</Page><!--num='2'-->
<Page num='3'>
<!-- ... -->
</Page><!--num='3'-->
</PageTable><!--type='BkCS' pgsz='12'-->
<!-- ... -->
<PageTable type='PgTL' pgsz='1'>
<Page num='1'>
<ID>Master Bypass</ID>
</Page><!--num='1'-->
<Page num='2'>
<ID>Input Level</ID>
</Page><!--num='2'-->
<Page num='3'>
<ID>Output Level</ID>
</Page><!--num='3'-->
<Page num='4'>
<ID>Gate Threshold</ID>
</Page><!--num='4'-->
<!-- ... -->
</PageTable><!--type='PgTL' pgsz='1'-->
</PTLayout><!--name='PageTable 1'-->
<PTLayout name='PageTable Free'>
<!-- ... -->
</PTLayout><!--name='PageTable Free'-->
</PageTableLayouts>
The sub-tags for this section are as follows:

ControlNameVariations tag

This section includes information about the names of each control in the plug-in. Here is an excerpt from our Eleven plug-in page tables which demonstrates the basic format of this section:
<Ctrl ID='Amp Bypass'>
<name typ='PgTL' sz='1'>AB</name>
<name typ='PgTL' sz='4'>AByp</name>
<name typ='PgTL' sz='5'>A Byp</name>
<name typ='PgTL' sz='6'>AmpByp</name>
<name typ='PgTL' sz='7'>Amp Byp</name>
</Ctrl><!--ID='Amp Bypass'-->
<Ctrl ID='Amp Type'>
<name typ='PgTL' sz='1'>AT</name>
<name typ='PgTL' sz='3'>Amp </name>
<name typ='PgTL' sz='5'>AmpTp</name>
<name typ='PgTL' sz='6'>AmpTyp</name>
<name typ='PgTL' sz='7'>Amp Typ</name>
</Ctrl><!--ID='Amp Type'-->
<Ctrl ID='Bright Switch'>
<name typ='PgTL' sz='1'>Brt </name>
<name typ='PgTL' sz='6'>Bright</name>
</Ctrl><!--ID='Bright Switch'-->
The sub-tags used are as follows:
Ctrl element with ID attribute - The identifier of the control that is being identified.
The identifiers for all parameters in the page table must and should match the IDs used for the control both in the <PageTableLayouts> layouts and in the Editor tag's DiscCtrls sub-tag (see below). See Parameter identifiers for more information about parameter identifiers.
name element - The desired abbreviated name of the control for display on control surface UIs, which may have limited display space available.
The typ parameter allows you to choose which page table type the given abbreviation will be specific to. For example, a name provided with typ='HgTL' would only appear on Command|8, 002, and 003 hardware. As with all other tags, the name associated with typ PgTL (the generic page table identifier) will be used if no other name is given for the specific page table that is being loaded.
The sz parameter defines the size of the control surface display for which the given name is appropriate. The control surface will use the name associated with the largest size that will fit on its display.
To reduce the number of names that must be specified, abbreviated names can be given that are longer than their specified size. These names will be truncated when necessary. For example, a control surface that could accommodate two characters on its display would use the size-1 name for the "Bright Switch" control above, since 1 is the largest number less than or equal to 2 from the provided set of name sizes (in this case, 1 and 6.) The size-1 name, 'Brt ', has four characters in it. Therefore, it would be truncated down to 'Br' to fit onto the control surface's display.

Editor tag

The last of the three main sections in an XML plug-in page table is the Editor section. This section is used by the Page Table Editor application and you should not need to modify its contents. However, if you are encountering problems modifying your plug-in in the Page Table Editor then you may wish to verify that all plug-ins and controls are properly identified within the PluginList and DiscCtrls sub-tabs, respectively. Here is the Editor section from the Eleven page table XML:
<Editor vers='1.3.7.1'>
<PluginList>
<TDM>
<PluginID manID='Digi' prodID='Elvn' plugID='ELVt'>
<MenuStr>TDM: Eleven, 1 in X 1 out</MenuStr>
</PluginID><!--manID='Digi' prodID='Elvn' plugID='ELVt'-->
</TDM>
<RTAS>
<PluginID manID='Digi' prodID='Elvn' plugID='ELVr'>
<MenuStr>RTAS: Eleven, 1 in X 1 out</MenuStr>
</PluginID><!--manID='Digi' prodID='Elvn' plugID='ELVr'-->
<PluginID manID='Digi' prodID='ElvF' plugID='ELFr'>
<MenuStr>RTAS: Eleven Free, 1 in X 1 out</MenuStr>
</PluginID><!--manID='Digi' prodID='ElvF' plugID='ELFr'-->
</RTAS>
</PluginList>
<DiscCtrls>
<CtrlID>Amp Bypass</CtrlID>
<CtrlID>Amp Type</CtrlID>
<CtrlID>Bright Switch</CtrlID>
<CtrlID>Cab Bypass</CtrlID>
<CtrlID>Cab Type</CtrlID>
<CtrlID>Master Bypass</CtrlID>
<CtrlID>Mic Axis</CtrlID>
<CtrlID>Mic Type</CtrlID>
</DiscCtrls>
</Editor><!--vers='1.3.7.1'-->

Parameter identifiers

The ID tags/arguments in a page table must reference parameters which are exposed by the plug-in's AAX_IEffectParameters implementation via methods such as GetParameterIndex().
There are two supported ways to identify parameters in a page table:
A single page table may only reference the plug-in's parameters using one of these two approaches; a page table file may not reference one parameter by its name and another by its ID, and it may not reference one parameter by its name in one location but by its ID in another location.
If a plug-in will change its parameters' names at run time then the parameter identifiers used in the page tables must reference parameters by ID.

Creating page tables using the AAX Plug-In Page Table Editor

Page tables can be created and edited using the AAX Plug-In Page Table Editor application available on the Developer website. The Page Table Editor generates an XML file that can be used in both Windows and Macintosh plug-in projects.
The Page Table Editor can also open page table files in existing .aaxplugin bundles on your system. If you're looking for examples of how to lay out the common parameters in your plug-ins try opening up the page tables for one of the standard Avid plug-ins like Avid Channel Strip or D-Verb.
Note
The Page Table Editor only supports opening a single file at a time. It can be useful to open multiple files in order to compare their layouts. To open multiple page tables at the same time you can launch multiple instances of the Page Table Editor application by running the application from a terminal shell.
The Page Table Editor will make use of the Parameter IDs that are defined in a plug-in, and will associate them with the 'Plugin' tags in the XML file. Using the DemoDist sample plug-in included in the AAX SDK, you'll see that there is one Plugin entry for each plug-in type in the binary.
// Type, product, and relation IDs
const AAX_CTypeID cDemoDist_ManufactureID ='AVID ';
const AAX_CTypeID cDemoDist_ProductID = 'DmDE ';
const AAX_CTypeID cDemoDist_TypeID_AS = 'DmAS ';
const AAX_CTypeID cDemoDist_TypeID_MonoNative = 'DmRT ';
const AAX_CTypeID cDemoDist_TypeID_StereoNative = 'DsRT ';
const AAX_CTypeID cDemoDist_TypeID_MonoTI = 'DDT1 ';
const AAX_CTypeID cDemoDist_TypeID_StereoTI = 'DDT2 ';
uint32_t AAX_CTypeID
Matches type of OSType used in classic plugins.
Definition: AAX.h:336
Listing 1: DemoDist Plug-In IDs
.
.
.
<Plugin manID ='AVID ' prodID ='DmDE ' plugID ='DmRT '>
<Desc > DemoDist 1 -&amp;gt; 1 by Avid Technology , Inc .</ Desc >
<Layout > PageTable 1</ Layout >
</ Plugin ><!-- manID ='AVID ' prodID ='DmDE ' plugID ='DmRT '-->
<Plugin manID ='AVID ' prodID ='DmDE ' plugID ='DsRT '>
<Desc > DemoDist 2 -&amp;gt; 2 by Avid Technology , Inc .</ Desc >
<Layout > PageTable 1</ Layout >
</ Plugin ><!-- manID ='AVID ' prodID ='DmDE ' plugID ='DsRT '-->
<Plugin manID ='AVID ' prodID ='DmDE ' plugID ='DDT1 '>
<Desc > DemoDist 1 -&amp;gt; 1 by Avid Technology , Inc .</ Desc >
<Layout > PageTable 1</ Layout >
</ Plugin ><!-- manID ='AVID ' prodID ='DmDE ' plugID ='DDT1 '-->
<Plugin manID ='AVID ' prodID ='DmDE ' plugID ='DDT2 '>
<Desc > DemoDist 2 -&amp;gt; 2 by Avid Technology , Inc .</ Desc >
<Layout > PageTable 1</ Layout >
</ Plugin ><!-- manID ='AVID ' prodID ='DmDE ' plugID ='DDT2 '-->
.
.
.
Listing 2: DemoDist XML
Note
For compatibility between your AAX and corresponding RTAS or TDM plug-ins, make sure the 4 character IDs for AAX_eProperty_ManufacturerID, AAX_eProperty_ProductID, AAX_eProperty_PlugInID_Native, and AAX_eProperty_PlugInID_AudioSuite are identical to the legacy SDK's counterpart.
For more information about the AAX Plug-In Page Table Editor tool, see the ReadMe file which accompanies the application.

Verifying Page Table Layouts: The Hidden Pop-Up Menu

You can verify the page tables created in your plug-in in Pro Tools with a "hidden" developer debug Page Tables popup menu. To verify the page tables, first include the YourPageTables.r file in your project and compile the plug-in. Then, after launching Pro Tools, instantiate the plug-in, hold down the Commandkey (Ctrl-key in Windows) and mouse-click the Automation button in the plug-in window to display the menu.

Control Highlighting Scheme

Note that plug-in controls that are currently controllable on any page of a plug-in will be highlighted in blue when they are the active page on a control surface. Therefore, it is very important to implement the highlighting of controls in your plug-in. Plug-in highlighting is also used with automation. In general, four common colors should be implemented:
You can use the "hidden" popup menu above to test that your color schemes are working properly.

Control Numbering Layouts

Most of the advanced control surfaces have both rotary encoders (knobs) and switches. The knobs and switches are handled differently by different surfaces. C|24 has a set of 24 rotary encoders and 24 switches for plug-in editing, and 003 has 8 encoders and 8 switches, all set up in pairs. However, both of these control surfaces automatically assign a control with only two possible values (e.g., "on" or "off") to a switch, while a control with three or more possible values, whether it is discrete or continuous, is automatically assigned to the rotary encoder. Therefore, no distinction is made between control numbers for switches and control numbers for encoders.
The following tables show how the control numbers are arranged for control surfaces which have distinctions between their encoders and switches.
Table 2: D-Control Channel Strip - Numbering Layout
Encoders Switches
1 7
2 8
3 9
4 10
5 11
6 12
Table 3: D-Control/Pro-Control Custom Fader Mode - Numbering Layout
Encoders Switches
1 9
2 10
3 11
4 12
5 13
6 14
7 15
8 16

Alphanumeric Displays

With the advent of the newer advanced control surfaces (CS), plug-ins now have the opportunity to provide information to the user via alphanumeric displays on the CS. Unfortunately, the displays are limited in the number of characters that can be shown. For instance, on the Mackie HUI, nine characters are provided for each plug-in control, allowing only four characters for the control name, and four characters for the control value, and one for a space between them. On ProControl, eight characters are provided for each plug-in control, with three characters allocated to displaying a control name, and four characters for its control value. On C|24 and 003, four characters are provided for the plug-in name, control name, and the control value. For the control value, these four characters include a +/- and/or any necessary unit abbreviations (ex: K, s, dB, etc.). D-Control and Command|8 provide six characters for the plug-in name, control name, and control value.
In order to display meaningful information in these short character strings, plug-ins will have to optimize the strings that they return to AAE. The dispatcher calls MapControlValToString(), which in turn calls GetValueString(), is used to obtain these control value strings. Typically in the past, the requested length argument of both these member functions, i.e., maxChars in MapControlValToString() or maxLength in GetValueString() has been ignored; but, from here on out, they should be carefully examined and used to create an optimum and meaningful string for any requested length.
To prevent the code from becoming unwieldy, as in the case of trying to provide strings for all requested lengths, a minimum number of expected lengths should be specifically addressed. The expected value lengths are: 4, 5, 6, 7, 8, and 31. In addition, ProControl switch states are a maximum length of 3 (i.e., when dealing with the state of a switch for ProControl, provide this information in 3 characters or less). Therefore, whenever possible, a plug-in should return the most meaningful string that will fit in any particular requested length, and at minimum, handle the expected lengths. If a plug-in does not have custom code to handle a particular requested length, it can round the length down to the next smaller expected length and use the code that it has for it. For example, a request of 9 characters should be converted to an expected request of 8 characters.
Please note: Since truncating a long string to fit within the requested length will not provide meaningful results in most cases, plug-ins must specifically provide code for deriving useful strings for the expected lengths where applicable.
Since the smaller lengths, especially 4 and 5 characters, are usually too short to display a plug-in's true full value including units, some decisions will have to be made about how to suitably shorten them. The following provides some general guidelines.
If needed, and in order of precedence, try to:
Here is a table depicting a typical example in more detail. The expected lengths are shown in the left most vertical column.
Name abbreviation example table
Alphanumeric Characters
While creating the above strings, the requested length argument passed in (maxChars in MapControlValToString(), and maxLength in GetValueString()) should be strictly adhered to! The string returned should be no greater than the requested number of characters. Furthermore, the developer should assume that the buffer passed into this function is only as large as the requested length. Any intermediate string processing should be done in temporary local buffers and only when you have the final string should you copy back to the buffer that was passed in, making sure you copy no more than the requested number of characters, plus the Null character or Length byte, as appropriate; since in general, MapControlValToString() uses C strings and GetValueString() uses Pascal strings.
Also, in an effort to further help prevent buffer overruns, two new functions have been added to the PI library file SliderConversions.cp: SmartAppendNum() and SmartAppendXNum(), which includes a maximum length argument and should be used in place of FicAppendNum() and FicAppendXNum() from FicBasics.cpp.
Finally, note that ProControl and HUI will sometimes utilize 5 characters to display its value when a sign is involved. For instance, if the number is -100, the negative sign will appear in the space separating the control name from the control value. Pro Tools will take care of this conversion as long as all of the expected lengths are properly provided for. For C|24 and 003, this is not the case - only four characters are allowed, so the +/- must be a part of those four characters.
HUI, ProControl, C|24, and 003 all provide alphanumeric displays for visual feedback, with the primary purpose being plug-in parameter editing. Functions in the plug-in library are provided that allow customized parameter strings to be created for use on the display. Specifically, these functions are: GetControlNameOfLength() and GetValueString(). Fortunately, the details of writing to the display are taken care of by the application. Therefore, the plug-in developer only needs to be concerned with providing meaningful display strings for all plug-in parameters that are controllable. Whether using the XML or legacy page table system, GetControlNameOfLength() should return the long version (31 characters maximum) of the plug-in's control names. Short versions of plug-in control names are stored in the XML file, edited with the Page Table Editor application. If you are also using legacy page tables to support versions of Pro Tools prior to 6.4, the short names should also be coded in the GetControlNameOfLength() function.
AAE clients like Pro Tools call GetControlNameOfLength(), but if AAE finds XML data stored in the plug-in, it gets the information from there rather than calling into the plug-in. GetControlNameOfLength() is responsible for providing the parameter "names" used on the display. As with parameter "value" strings, it is important to carefully create parameter names that are meaningful in the limited space allocated to displaying parameter names. On ProControl, string lengths of three characters will be used for the parameter name strings, where four characters will be used on the HUI, C|24, and 003. D-Control and Command|8 use six characters for control names. In general, lengths of 3, 4, 5, 6, 7, 8, and 31 should be specifically addressed in the Page Table Editor or GetControlNameOfLength(). We begin next, by looking at some concrete examples.

ProControl Display

ProControl also provides an alphanumeric display; however, there are some significant differences that need to be addressed. Shown is a generic representation for the ProControl display. The image below shows what users will usually be viewing on ProControl's displays, which are the current Encoder/Value settings. Figure 13 shows the current switch settings when the user toggles to the Switch/State display mode. ProControl will only display one of three views at any given time.
Pro-Control encoder display
Pro-Control Encoder Display
    Pro-Control switch display
ProControl Switch Display
As with the HUI, meaningful strings will have to be provided in the limited available lengths. ProControl, C|24 or 003 value strings require no special treatment other than what has already been stated above for HUI, since all of these control surfaces display their values in 4 digits/characters, as returned by GetValueString(). The biggest difference between the HUI display and the Avid control surfaces' displays is that the Avid control surfaces can display symbols.
Let's take a moment to explain how the displays of C|24 and 003 work. Both of these surfaces have a four character LED display located above each encoder/switch pair. When in Channel mode, these scribble strips show the plug-in name (if any) on that channel. When that plug-in is selected, the display switches to show the controls for the plug-in. Now each display shows the name of the control. The display automatically switches to the current value of the control when the encoder or switch is moved or pushed.

Appendix A. Get Parameter Value Info

Overview

AAX_Result GetParameterValueInfo ( AAX_CParamID iParameterID, int32_t iSelector, int32_t* oValue)
GetParameterValueInfo() is implemented at the Data Model's AAX_CEffectParameters level, and will allow the app to query a plug-in for the "meaning" of its parameter values. It was designed as a general purpose mechanism that will find additional uses with new selectors in the future. It is used:

Implementation

GetParameterValueInfo() will be of type AAX_EParameterValueInfoSelector (AAX_Enums.h) and will allow for future queries on parameter value "meaning."
{
};
AAX_EParameterValueInfoSelector
Query type selectors for use with AAX_IEffectParameters::GetParameterValueInfo()
Definition: AAX_Enums.h:878
@ AAX_ePageTable_UseAlternateControl
Description of whether an alternate parameter should be used for a given slot.
Definition: AAX_Enums.h:914
@ AAX_ePageTable_EQ_Band_Type
EQ filter band type.
Definition: AAX_Enums.h:887
@ AAX_ePageTable_EQ_InCircuitPolarity
Description of whether a particular EQ band is active.
Definition: AAX_Enums.h:896
Listing 3: Parameter Selector Enums
Results (not return values) passed back by GetParameterValueInfo() will be of one of these two types:
{
};
AAX_EEQBandTypes
Definitions of band types for EQ page table.
Definition: AAX_Enums.h:923
@ AAX_eEQBandType_Parametric
Definition: AAX_Enums.h:926
@ AAX_eEQBandType_LowShelf
Definition: AAX_Enums.h:925
@ AAX_eEQBandType_LowPass
Definition: AAX_Enums.h:928
@ AAX_eEQBandType_Notch
Definition: AAX_Enums.h:929
@ AAX_eEQBandType_HighPass
Definition: AAX_Enums.h:924
@ AAX_eEQBandType_HighShelf
Definition: AAX_Enums.h:927
Listing 4: EQ Band Type Enums
{
};
AAX_EEQInCircuitPolarity
Definitions for band in/out for EQ page table.
Definition: AAX_Enums.h:938
@ AAX_eEQInCircuitPolarity_Disabled
Definition: AAX_Enums.h:941
@ AAX_eEQInCircuitPolarity_Enabled
Definition: AAX_Enums.h:939
@ AAX_eEQInCircuitPolarity_Bypassed
Definition: AAX_Enums.h:940
Listing 5: EQ Circuit Polarity Enums
{
};
AAX_EUseAlternateControl
Definitions for Use Alternate Control parameter.
Definition: AAX_Enums.h:950
@ AAX_eUseAlternateControl_No
Definition: AAX_Enums.h:951
@ AAX_eUseAlternateControl_Yes
Definition: AAX_Enums.h:952
Listing 6: Alternate Control Enum
Please see AAX_Enums.h for more information.
To add support for this method, you must to override AAX_CEffectParameters::GetParameterValueInfo() from within your plug-ins Data Model. For a given AAX_CParamID, selector, and parameter value, you must pass back a result (not a return value) denoting the "meaning" of that parameter value. If a parameter has no meaning in the context of the given selector, you should return AAX_ERROR_UNIMPLEMENTED.
One point to note, is that an EQ or Dynamics plug-in may have a band of EQ that does not include an EQ type selector control. The band is just always, say, a HPF. There's no control to map to the EQ type selector button in the page table and therefore no obvious control for which you would pass back AAX_eEQBandType_HighPass in GetParameterValueInfo(). What is the solution? Well, the other controls on that band (Frequency, Q/Slope, Gain, In) know what type of band they're on. Thus the plug-in should pass back the relevant EEQ_Band_Types enum in GetParameterValueInfo() for all controls on a given band of EQ. This also applies to key filter bands in your Dynamics plug-ins. In this way, the EQ type selector LEDs in both the EQ and Dynamics sections will always light appropriately.
The second exception applies to EQ or Dynamics plug-ins that have a band of EQ that does not include an In Circuit / Out of Circuit control for that band. In this case, the band is always In Circuit (or On) and the other controls for this band should return AAX_eEQInCircuitPolarity_Enabled as the result for GetParameterValueInfo() when the AAX_ePageTable_EQ_InCircuitPolarity selector is passed in. Code snippets for GetParameterValueInfo() from the EQ III 7-Band AAX plug-in is provided below:
Note
The logic for the In Circuit / Out of Circuit LED is available in Pro Tools 6.7 and higher.
// *************************************************
// METHOD: GetParameterValueInfo
// *************************************************
AAX_Result EQIII_7_Parameters::GetParameterValueInfo ( AAX_CParamID iParameterID, int32_t iSelector, int32_t* oValue) const
{
const AAX_IParameter * parameter = mParameterManager.GetParameterByID( iParameterID );
if ( !parameter )
if ( iSelector == AAX_ePageTable_EQ_Band_Type )
{
if ( parameter->Name() == EQIII_HPF_Type )
{
switch( parameter->GetStepValue() )
{
case 0 /*Notch*/: *oValue = AAX_eEQBandType_Notch; break;
case 1 /*HiPass*/: *oValue = AAX_eEQBandType_HighPass; break;
default: *oValue = -1; return AAX_ERROR_UNIMPLEMENTED; break;
}
return AAX_SUCCESS;
}
else if ( parameter->Name() == EQIII_LF_Type )
{
switch( parameter->GetStepValue() )
{
case 0 /*Peak*/: *oValue = AAX_eEQBandType_Parametric; break;
case 1 /*Shelf*/: *oValue = AAX_eEQBandType_LowShelf; break;
default: *oValue = -1; return AAX_ERROR_UNIMPLEMENTED; break;
}
return AAX_SUCCESS;
}
else if (parameter->Name() == EQIII_HF_Type )
{
switch (parameter->GetStepValue() )
{
case 0 /*Peak*/: *oValue = AAX_eEQBandType_Parametric; break;
case 1 /*Shelf*/: *oValue = AAX_eEQBandType_HighShelf; break;
default: *oValue = -1; return AAX_ERROR_UNIMPLEMENTED; break;
}
return AAX_SUCCESS;
}
else if ( parameter->Name() == EQIII_LPF_Type )
{
switch ( parameter->GetStepValue() )
{
case 0 /*Notch*/: *oValue = AAX_eEQBandType_Notch; break;
case 1 /*LoPass*/: *oValue = AAX_eEQBandType_LowPass; break;
default: *oValue = -1; return AAX_ERROR_UNIMPLEMENTED; break;
}
return AAX_SUCCESS;
}
}
else if (iSelector == AAX_ePageTable_UseAlternateControl)
{
if ( (parameter->Name() == EQIII_HPF_Type ) ||
(parameter->Name() == EQIII_HPF_Q) ||
(parameter->Name() == EQIII_HPF_Slope) )
{
const AAX_IParameter* typeParam = mParameterManager.GetParameterByID(EQIII_HPF_Type_Ch);
*oValue = (typeParam->GetStepValue() == 0 /*Notch*/) ? AAX_eUseAlternateControl_No : AAX_eUseAlternateControl_Yes;
return AAX_SUCCESS;
}
else if ( (parameter->Name() == EQIII_LPF_Type) ||
(parameter->Name() == EQIII_LPF_Q) ||
(parameter->Name() == EQIII_LPF_Slope) )
{
const AAX_IParameter* typeParam = mParameterManager.GetParameterByID(EQIII_LPF_Type_Ch);
*oValue = (typeParam->GetStepValue() == 0 /*Notch*/) ? AAX_eUseAlternateControl_No : AAX_eUseAlternateControl_Yes;
return AAX_SUCCESS;
}
}
};
const char * AAX_CParamID
Parameter identifier.
Definition: AAX.h:352
int32_t AAX_Result
Definition: AAX.h:337
@ AAX_ERROR_INVALID_PARAMETER_ID
Definition: AAX_Errors.h:41
@ AAX_ERROR_UNIMPLEMENTED
Definition: AAX_Errors.h:49
@ AAX_SUCCESS
Definition: AAX_Errors.h:39
The base interface for all normalizable plug-in parameters.
Definition: AAX_IParameter.h:140
virtual uint32_t GetStepValue() const =0
Returns the current step for the current value of the parameter.
virtual const AAX_CString & Name() const =0
Returns the parameter's display name.
Listing 7: EQIII GetParameterValueInfo()
As you'll notice, the EQ III plug-in has separate controls for Q and Slope in its HPF and LPF bands, depending on whether the band is set to notch or band pass. When the Band Type control is set to notch, the continuous Q control is used. When the Band Type is set to Hi/Lo Pass, the discrete Slope control is used. In the page table, the HPF / LPF Q controls are set to the ``Q or Slope'' in the Page Table Editor application, and the HPF / LPF Slope controls are set to the ``Q or Slope Alt''. Then, with the GetParameterValueInfo() implementation above, the control surface properly swaps the controls when the band type control is changed. In other words, when the function is called with the AAX_ePageTable_UseAlternateControl selector, if the band type control is set to notch, then AAX_eUseAlternateControl_No is returned in the result and the control surface puts the Q control at that position. If the band type is set to pass, then AAX_eUseAlternateControl_Yes is returned and the Slope is placed at that position.
Collaboration diagram for Page Table Guide: