\hypertarget{a00875}{}\doxysection{Getting Started with AAX}
\label{a00875}\index{Getting Started with AAX@{Getting Started with AAX}}
A brief introduction to AAX. 

\hypertarget{a00875_aax_getting_started_guide_contents}{}\doxysubsection{Contents}\label{a00875_aax_getting_started_guide_contents}
\begin{DoxyItemize}
\item \mbox{\hyperlink{a00875_aax_sdk_guide_00_introduction}{Welcome}}  \item \mbox{\hyperlink{a00875_aax_sdk_guide_quickstart}{Quick Start}}  \item \mbox{\hyperlink{a00875_aax_sdk_guide_01_aax_design_overview}{AAX Design Overview}} \item \mbox{\hyperlink{a00875_aax_sdk_guide_02_demogain_example}{Demo\+Gain Example}} \item \mbox{\hyperlink{a00875_aax_sdk_guide_next_steps}{Next Steps}}\end{DoxyItemize}


 \hypertarget{a00875_aax_sdk_guide_00_introduction}{}\doxysubsection{Welcome}\label{a00875_aax_sdk_guide_00_introduction}
 Welcome to AAX! This guide is designed to introduce you to the fundamental concepts of AAX. By the end of this guide you will understand\+: \begin{DoxyItemize}
\item The purpose of AAX \item The basic components of an AAX plug-\/in \item The structure of the Demo\+Gain example plug-\/in \item What you need to do to successfully build and run your own AAX plug-\/ins\end{DoxyItemize}


 \hypertarget{a00875_aax_sdk_guide_quickstart}{}\doxysubsection{Quick Start}\label{a00875_aax_sdk_guide_quickstart}
 Use the steps below to get up and running quickly with an example plug-\/in from the AAX SDK.

 
\begin{DoxyItemize}
\item  Build the AAX Library  

If this is your first time opening the AAX SDK then your first step should be to build the AAX Library project. The AAX Library is a static library containing default implementations of the AAX interface and convenience classes designed to make AAX development easy. All of the SDK example plug-\/ins link to this library, and your plug-\/ins should too. 



Open the AAX Library project for your chosen IDE from the Libs/\+AAXLibrary directory and build the library. Now you are ready to build plug-\/ins! 


\item  Open and build the Demo\+Gain example plug-\/in  

The Demo\+Gain project is located in Example\+Plug\+Ins/\+Demo\+Gain. Once you have built the AAX Library project you will be able to successfully build Demo\+Gain. To learn more about the Demo\+Gain example plug-\/in, see the \mbox{\hyperlink{a00875_aax_sdk_guide_02_demogain_example}{Demo\+Gain Example}} section below. 


\item  Install a developer build of Pro Tools  

If you looking at AAX then you are most likely interested in developing plug-\/ins for \mbox{\hyperlink{a00913}{Pro Tools}}. Publicly available builds of Pro Tools require that AAX plug-\/ins be digitally signed. During development, you can use a \char`\"{}developer build\char`\"{} of Pro Tools to run unsigned test builds of your plug-\/ins, like the Demo\+Gain plug-\/in that you just built. 



Download and install the latest Pro Tools developer build from the AAX developer downloads in your \href{https://my.avid.com/account}{\texttt{ my.\+avid.\+com}} account. 


\item  Obtain a Pro Tools Developer i\+Lok license (and an i\+Lok)  

Pro Tools developer builds require a special license loaded on an i\+Lok USB device. You can request this Pro Tools Developer license, as well as any other NFR (Not For Resale) licenses which you require for your AAX product development and testing, by writing to \href{mailto:devauth@avid.com?subject=License Request}{\texttt{ devauth@avid.\+com}} with \char`\"{}\+License Request\char`\"{} in the subject. 



If you don\textquotesingle{}t have an i\+Lok device you will also need to obtain one from \href{https://www.ilok.com}{\texttt{ PACE Anti-\/\+Piracy Inc.}} or a reseller, including most music shops which sell audio software. 


\item  Install Demo\+Gain in the AAX Plug-\/\+Ins folder  

In order to be loaded into Pro Tools, a plug-\/in must be present in the system\textquotesingle{}s AAX Plug-\/\+Ins directory. See \mbox{\hyperlink{a00913_subsection__install_directories_}{Install directories}} in the \mbox{\hyperlink{a00913}{Pro Tools Guide}} document for more information about where to install AAX plug-\/ins for Pro Tools. 


\item  Launch Pro Tools and run Demo\+Gain  

You\textquotesingle{}re now ready to run your very first AAX plug-\/in! 
\begin{DoxyEnumerate}
\item Make sure that your i\+Lok USB device is connected to the system and contains the Pro Tools Developer license, then launch the Pro Tools developer build.  
\item Once Pro Tools has launched, you will be prompted to create a new Session or Project. Choose Session (Local Storage) to create a local session file.  
\item Create a new mono audio track in your session using the \char`\"{}\+New Track...\char`\"{} menu item  
\item If it is not already visible, reveal the \char`\"{}\+Inserts A-\/\+E\char`\"{} view in the Edit window using the View \texorpdfstring{$>$}{>} Edit Window menu.  
\item Click on one of the insert slots for your audio track and choose Demo\+Gain from the insert selection menu.  
\end{DoxyEnumerate}



You\textquotesingle{}re now running an instance of the Demo\+Gain AAX plug-\/in. If you have a debugger attached to Pro Tools you should now be able to break in the plug-\/in\textquotesingle{}s methods and step through its code. 


\item  Get ready to release your own products  

Once you have created your own AAX plug-\/in you can follow the steps in \mbox{\hyperlink{a00926}{Distributing Your AAX Plug-\/\+In}} to prepare your plug-\/in for public sale and distribution. 



In particular, for Pro Tools compatibility or to test your product with a public Pro Tools release you will need to digitally sign your plug-\/in using a toolkit from PACE Anti-\/\+Piracy Inc. See the \mbox{\hyperlink{a00913_subsection__digital_signature_}{digital signature}} section of the \mbox{\hyperlink{a00913}{Pro Tools Guide}} for more information about this requirement. 


\end{DoxyItemize}



 \hypertarget{a00875_aax_sdk_guide_01_aax_design_overview}{}\doxysubsection{AAX Design Overview}\label{a00875_aax_sdk_guide_01_aax_design_overview}
\hypertarget{a00875_subsection__architecture_philosophy}{}\doxysubsubsection{Architecture Philosophy}\label{a00875_subsection__architecture_philosophy}
The purpose of the AAX architecture is to provide an {\itshape easy-\/to-\/use} framework for the development of {\itshape high-\/performance audio plug-\/ins} that can run on a {\itshape variety of platforms}, both present and future, with a {\itshape high level of code re-\/use}.

\hypertarget{a00875_subsection__design_attributes}{}\doxysubsubsection{Design Attributes}\label{a00875_subsection__design_attributes}
AAX incorporates a flexible, decoupled component hierarchy, including\+: 
\begin{DoxyEnumerate}
\item A relocatable C-\/style callback that performs the plug-\/in\textquotesingle{}s real-\/time audio processing algorithm  
\item A collection of supporting C++ objects that manage the plug-\/in\textquotesingle{}s data, GUI, and any other non-\/real-\/time information  
\item A \char`\"{}description\char`\"{} method that statically describes the plug-\/in\textquotesingle{}s layout and compatibility requirements to the host.  
\end{DoxyEnumerate}

This flexible design facilitates optimal performance and portability; AAX is 64-\/bit ready and is designed to work well in both host-\/based (Native), accelerated (DSP), and future (e.\+g. embedded) environments. Importantly, plug-\/ins running in each of these environments can use the same code base, and porting to new platforms should not require much more than a re-\/compile. To satisfy these portability requirements, AAX must be decoupled into three parts, the GUI, data model, and algorithm.

\hypertarget{a00875_subsection__component_structure}{}\doxysubsubsection{Component Structure}\label{a00875_subsection__component_structure}
The core component structure of an AAX plug-\/in involves data model, GUI, description, and algorithm modules. The design involves a mixture of C++ objects (data model and GUI modules) and C-\/style callbacks (algorithm and description modules.)

The figure below shows basic object ownership and composition in an AAX plug-\/in. The purple components are provided as part of the AAX SDK while the other components are written as needed by the plug-\/in developer. The classes above the dotted line are pure virtual interfaces, while the classes below the dotted line are concrete implementations.

   Figure 1\+: Core AAX interface design.

As you can see, the plug-\/in\textquotesingle{}s \mbox{\hyperlink{a00879}{data model}} and \mbox{\hyperlink{a00880}{GUI}} are written as C++ objects inherited from SDK interfaces, while its \mbox{\hyperlink{a00878}{algorithm}} and \mbox{\hyperlink{a00877}{Description}} methods are implemented as simple callbacks. This basic model may be expanded by attaching additional modules, such as the \mbox{\hyperlink{a00885}{Host Processor}} module used by advanced non-\/real-\/time plug-\/ins. In this section, however, we will be considering only the four core interfaces and modules.

\hypertarget{a00875_subsection__algorithm}{}\doxysubsubsection{Algorithm}\label{a00875_subsection__algorithm}
The most fundamental, and most important, component of any audio plug-\/in is its processing algorithm. Due to the design requirements of an AAX plug-\/in, this component must meet several constraints in order to be compatible with accelerated platforms\+: 
\begin{DoxyEnumerate}
\item It must be possible to build the algorithm as a compatible component on a variety of platforms  
\item It must be possible for the host to re-\/locate the algorithm in memory without affecting the algorithm\textquotesingle{}s state  
\item The algorithm must be separable from the rest of its plug-\/in, e.\+g. into a different memory space  
\item The algorithm must be as efficient as possible to call.  
\end{DoxyEnumerate}

To satisfy these constraints, AAX uses a decoupled C-\/style callback function. State information within the function is obtained through the context, a custom data structure that contains everything from the \char`\"{}outside world\char`\"{} that is relevant to the algorithm. The context includes information such as audio buffers and coefficient packets, which are provided according to a static set of data routing definitions that we will describe further in the next chapter. The host is responsible for ensuring that this structure is up-\/to-\/date whenever the algorithm callback is entered.

\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{a00878}{Real-\/time algorithm callback}}
\end{DoxySeeAlso}
\hypertarget{a00875_subsection__data_model}{}\doxysubsubsection{Data Model}\label{a00875_subsection__data_model}
The \mbox{\hyperlink{a02245}{AAX\+\_\+\+IEffect\+Parameters}} interface represents the data model portion of your plug-\/in. The AAX host interacts with your plug-\/in\textquotesingle{}s data model via this interface, which includes methods that store and update of your plug-\/in\textquotesingle{}s internal data.

In your plug-\/in\textquotesingle{}s data model implementation, you will be responsible for creating the plug-\/in\textquotesingle{}s parameters and defining how the plug-\/in will respond when these parameters are changed via control updates or preset loads. In order for information to be routed from the data model to the plug-\/in\textquotesingle{}s algorithm, the parameters that are created here must be registered with the host in the plug-\/in\textquotesingle{}s Description callback (see below).

The data model is composed with \mbox{\hyperlink{a02201}{AAX\+\_\+\+IController}}, an interface that provides access to the host. This interface provides a means of querying information from the host such as stem format or sample rate, and is also responsible for communication between the data model and the (decoupled) algorithm.

You will most likely inherit your custom data model\textquotesingle{}s implementation from \mbox{\hyperlink{a01837}{AAX\+\_\+\+CEffect\+Parameters}}, a default implementation of the \mbox{\hyperlink{a02245}{AAX\+\_\+\+IEffect\+Parameters}} interface. This class provides basic functionality such as adding custom parameters, setting control values, restoring state, generating coefficients, etc., which you can override and customize as needed.

 \begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{a00879}{Data model interface}} 
\end{DoxySeeAlso}
\hypertarget{a00875_subsection__gui_interface}{}\doxysubsubsection{GUI Interface}\label{a00875_subsection__gui_interface}
The \mbox{\hyperlink{a02241}{AAX\+\_\+\+IEffect\+GUI}} interface contains the plug-\/in\textquotesingle{}s GUI methods. This interface is decoupled from the plug-\/in\textquotesingle{}s data model, allowing AAX to support distributed architectures that incorporate remote GUIs.

The GUI is also composed with \mbox{\hyperlink{a02201}{AAX\+\_\+\+IController}}, from which references to the plug-\/in\textquotesingle{}s other components, such as its data model interface, may be retrieved.

The AAX SDK includes a set of GUI extensions to help you get started implementing your plug-\/ins\textquotesingle{} GUIs. These extensions include both native drawing formats and suggested integrations with third-\/party graphics frameworks. Although the SDK does not include any actual graphics frameworks, these extensions provide examples of how you can incorporate your chosen GUI framework with \mbox{\hyperlink{a00935}{AAX}}.

 \begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{a00880}{GUI interface}}
\end{DoxySeeAlso}
\hypertarget{a00875_subsection__describe}{}\doxysubsubsection{Describe}\label{a00875_subsection__describe}
A plug-\/in\textquotesingle{}s Describe callback ties all the plug-\/in\textquotesingle{}s components together and registers the plug-\/in with the host. In this callback, your plug-\/in defines a set of algorithm callbacks, data connections, and static plug-\/in properties

In order to route data to the plug-\/in\textquotesingle{}s algorithm, Describe includes a description of the algorithm\textquotesingle{}s context structure. This description involves a set of port definitions, which can be \char`\"{}hard-\/wired\char`\"{} to receive data from the host (such as audio buffers,) from the plug-\/in\textquotesingle{}s data model (such as packets of coefficients,) or even from past calls to the algorithm (private, persistent algorithm state.)

Once these connections are made, Describe passes the host a populated description interface and returns. In the next section we will demonstrate how all these interfaces interact with one another by examining a sample plug-\/in.

\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{a00877}{Description callback}}
\end{DoxySeeAlso}
\hypertarget{a00875_subsection__controller}{}\doxysubsubsection{Controller}\label{a00875_subsection__controller}
There is one additional core component to any AAX plug-\/in, the Controller. The plug-\/in does not implement this component -\/ rather, the Controller is an interface that provides access to various facilities provided by the host, as well as to the plug-\/in\textquotesingle{}s other modules. 

 \hypertarget{a00875_aax_sdk_guide_02_demogain_example}{}\doxysubsection{Demo\+Gain Example}\label{a00875_aax_sdk_guide_02_demogain_example}
The AAX SDK includes a basic example plug-\/in named Demo\+Gain. In this section we will examine this plug-\/in to show how the various core modules in an AAX plug-\/in interact with one another. We will focus in particular on how the Demo\+Gain\textquotesingle{}s \char`\"{}gain\char`\"{} parameter is defined, routed to the algorithm, and used to apply a gain effect to audio samples. In this way we will \char`\"{}visit\char`\"{} each of the core components in Demo\+Gain.

 For a description of all the example plug-\/ins included in the SDK, see the \mbox{\hyperlink{a00931}{Example Plug-\/\+Ins}} page.

 \begin{DoxyNote}{Note}
To run Demo\+Gain or other example plug-\/ins in Pro Tools 10 you must change the {\ttfamily AAX\+\_\+e\+Plug\+In\+Category\+\_\+\+Example} category to {\ttfamily AAX\+\_\+e\+Plug\+In\+Category\+\_\+\+Dynamics} in the plug-\/in\textquotesingle{}s Describe function. The \char`\"{}example\char`\"{} category is not supported in Pro Tools 10. 
\end{DoxyNote}
\hypertarget{a00875_subsection__overview_of_parameter_creation}{}\doxysubsubsection{AAX Plug-\/\+In Parameters}\label{a00875_subsection__overview_of_parameter_creation}
 A good starting point for understanding a plug-\/in is to understand its parameters. In Demo\+Gain, as in most AAX plug-\/ins, the plug-\/in\textquotesingle{}s parameters define its data model state and the plug-\/in\textquotesingle{}s parameters provide the fundamental connection between user interactions and audio processing.

The sections below will guide you through each of the main steps of parameter creation and connection, making use of the default implementation in {\itshape \mbox{\hyperlink{a01837}{AAX\+\_\+\+CEffect\+Parameters}}}\+: 
\begin{DoxyEnumerate}
\item \mbox{\hyperlink{a00875_subsection__data_model_create_your_parameter}{Data Model\+: Create Your Parameter}} 
\begin{DoxyEnumerate}
\item Create a new parameter object  
\item Register the parameter with the Packet Dispatcher  
\item Create an update callback that converts the raw parameter value into a packet of processed coefficients  
\end{DoxyEnumerate}
\item \mbox{\hyperlink{a00875_subsection__algorithm_add_coefficients_to_the_algorithms_context_structure}{Algorithm\+: Add coefficients to the algorithm\textquotesingle{}s context structure}} 
\begin{DoxyEnumerate}
\item Create a new field for incoming coefficient packets  
\item Generate a {\itshape field ID} to reference the new member  
\item Add the new coefficient to the plug-\/in\textquotesingle{}s algorithm code  
\end{DoxyEnumerate}
\item \mbox{\hyperlink{a00875_subsection__describe_connect_the_parameter_throughout_the_plugin}{Describe\+: Connect the parameter throughout the plug-\/in}} 
\begin{DoxyEnumerate}
\item Add a new Data Input Port to the algorithm via the component descriptor interface  
\item Add a connection between the parameter\textquotesingle{}s {\itshape packet ID} and its coefficients\textquotesingle{} {\itshape field ID} 
\end{DoxyEnumerate}
\item \mbox{\hyperlink{a00875_subsection__gui_add_a_control}{GUI\+: Add a control}} 
\begin{DoxyEnumerate}
\item Create a GUI widget that can update the parameter\textquotesingle{}s state  
\item Add logic to notify the data model when the GUI is edited  
\item Add logic to update the GUI when the data model state changes  
\end{DoxyEnumerate}
\end{DoxyEnumerate}

\hypertarget{a00875_subsection__data_model_create_your_parameter}{}\doxysubsubsection{Data Model\+: Create Your Parameter}\label{a00875_subsection__data_model_create_your_parameter}
Demo\+Gain\textquotesingle{}s data model inherits its functionality from \mbox{\hyperlink{a01837}{AAX\+\_\+\+CEffect\+Parameters}} (the default implementation of \mbox{\hyperlink{a02245}{AAX\+\_\+\+IEffect\+Parameters}}). The {\ttfamily Demo\+Gain\+\_\+\+Parameters.\+h} and {\ttfamily Demo\+Gain\+\_\+\+Parameters.\+cpp} source files comprise the source code for Demo\+Gain\textquotesingle{}s data model.

During plug-\/in initialization, {\ttfamily Demo\+Gain\+\_\+\+Parameters\+::\+Effect\+Init()} creates the plug-\/in\textquotesingle{}s custom parameters. A look inside of the .cpp file shows how this is done via the creation of a new \mbox{\hyperlink{a01893}{AAX\+\_\+\+CParameter}} for the gain\+Parameter\+: the \mbox{\hyperlink{a01893}{AAX\+\_\+\+CParameter}} constructor is parametrized with a set of arguments that define the gain parameter\textquotesingle{}s behavior, such as its default value ({\ttfamily 1.\+0f}), name (\char`\"{}\+Gain\char`\"{}), taper behavior (linear), etc.

After creating the parameter objects, a series of packets are registered with the host via the inherited \mbox{\hyperlink{a01885}{Packet Dispatcher}}, {\ttfamily m\+Packet\+Dispatcher}, which is a helper object used by \mbox{\hyperlink{a01837}{AAX\+\_\+\+CEffect\+Parameters}} to assist with the plug-\/in\textquotesingle{}s packet management tasks.


\begin{DoxyCode}{0}
\DoxyCodeLine{mPacketDispatcher.RegisterPacket(}
\DoxyCodeLine{\ \ \ \ DemoGain\_GainID,}
\DoxyCodeLine{\ \ \ \ eAlgPortID\_CoefsGainIn,}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{this},}
\DoxyCodeLine{\ \ \ \ \&DemoGain\_Parameters::UpdatePacket\_Gain);\ }

\end{DoxyCode}
  Listing 1\+: Registration of Demo\+Gain\textquotesingle{}s \char`\"{}gain\char`\"{} packet handler

The last parameter in \mbox{\hyperlink{a01885_a1848f0bfa473b54e9ee8e32872c89cb1}{AAX\+\_\+\+CPacket\+Dispatcher\+::\+Register\+Packet()}} takes a reference to a packet handler callback. This method will be called by the Packet Dispatcher whenever new parameter values need to be converted into coefficients that can be used by the algorithm. In Demo\+Gain, a reference to Demo\+Gain\+\_\+\+Parameters\+::\+Update\+Packet\+\_\+\+Gain() is used for the gain parameter\textquotesingle{}s coefficient packet.

As a developer, you will choose how this portion of your data model gets handled; you can choose to use the default handler method, which simply forwards the raw parameter values to the algorithm, or you can define a custom handler. You can also choose to bypass the Packet Dispatcher completely (see the {\ttfamily Demo\+Dist\+\_\+\+Gen\+Coef} plug-\/in for an example of this.)

Although the handling of Demo\+Gain\textquotesingle{}s gain parameter is trivial, for the sake of demonstration this plug-\/in uses both Packet Dispatcher approaches in the registration of its bypass and gain parameters.

\hypertarget{a00875_subsection__algorithm_add_coefficients_to_the_algorithms_context_structure}{}\doxysubsubsection{Algorithm\+: Add coefficients to the algorithm\textquotesingle{}s context structure}\label{a00875_subsection__algorithm_add_coefficients_to_the_algorithms_context_structure}
 Your plug-\/in\textquotesingle{}s context is nothing more than a data structure of pointers that is registered with the host during Describe. These pointers function as {\itshape  ports} where host-\/managed data may be delivered or retrieved.

\hypertarget{a00875_subsubsection__context_definition_}{}\doxyparagraph{Context definition}\label{a00875_subsubsection__context_definition_}


 Looking under the \char`\"{}\+Component context definitions\char`\"{} section within Demo\+Gain\+\_\+\+Alg.\+h, you will find Demo\+Gain\textquotesingle{}s {\ttfamily SDemo\+Gain\+\_\+\+Alg\+\_\+\+Context} context. This is Demo\+Gain\textquotesingle{}s context structure, and its sole purpose is to parametrize Demo\+Gain\textquotesingle{}s algorithm with a set of ports. Note the definition of a port for the gain coefficients that are created by {\ttfamily Demo\+Gain\+\_\+\+Parameters\+::\+Update\+Packet\+\_\+\+Gain()} and another port for the bypass value that is forwarded via the default packet update handler.




\begin{DoxyCode}{0}
\DoxyCodeLine{int32\_t\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ *\ mCtrlBypassP;}
\DoxyCodeLine{SDemoGain\_CoefsGain\ \ \ *\ mCoefsGainP;\ }

\end{DoxyCode}
  Listing 2\+: Gain and bypass ports in the Demo\+Gain algorithm\textquotesingle{}s context structure

Once ports have been defined for the algorithm\textquotesingle{}s coefficients and other algorithmic data, unique identifiers for each port in the context must be generated. This is accomplished through use of the \mbox{\hyperlink{a00533_acf807247ecd6e5899dc9dc31644e9a1d}{AAX\+\_\+\+FIELD\+\_\+\+INDEX}} macro. The basic idea behind this macro is to generate IDs that the host can use to directly address the ports within their context\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{,\ eAlgPortID\_CoefsGainIn\ =\ \mbox{\hyperlink{a00533_acf807247ecd6e5899dc9dc31644e9a1d}{AAX\_FIELD\_INDEX}}\ (\ SDemoGain\_Alg\_Context\ ,\ mCoef\ ),}
\DoxyCodeLine{,\ eAlgFieldID\_AudioIn\ =\ \mbox{\hyperlink{a00533_acf807247ecd6e5899dc9dc31644e9a1d}{AAX\_FIELD\_INDEX}}\ (\ SDemoGain\_Alg\_Context\ ,\ mInputPP\ )\ )\ }

\end{DoxyCode}
  Listing 3\+: Some port ID definitions for the Demo\+Gain algorithm\textquotesingle{}s context structure

Now the context\textquotesingle{}s definition is complete. So far these are just fields in a struct; the host doesn\textquotesingle{}t yet know how to route packets from the data model to these ports. That information will come later, in the plug-\/in\textquotesingle{}s \mbox{\hyperlink{a00875_subsection__describe_connect_the_parameter_throughout_the_plugin}{description}}. Once this context is described to the host, the host will know to populate it and pass it to the processing function located in Demo\+Gain\+\_\+\+Alg\+Proc.\+cpp.

\hypertarget{a00875_subsubsection__algorithm_processing_callback_}{}\doxyparagraph{Algorithm processing callback}\label{a00875_subsubsection__algorithm_processing_callback_}



\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void}}
\DoxyCodeLine{\mbox{\hyperlink{a00533_aaa22112139aa627574b1ef562f579d43}{AAX\_CALLBACK}}}
\DoxyCodeLine{DemoGain\_AlgorithmProcessFunction\ (}
\DoxyCodeLine{\ \ \ \ SDemoGain\_Alg\_Context\ *\ \textcolor{keyword}{const}\ inInstancesBegin\ [],}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{const}\ \textcolor{keywordtype}{void}\ *\ inInstancesEnd\ )\ }

\end{DoxyCode}
  Listing 4\+: The Demo\+Gain algorithm\textquotesingle{}s callback prototype

This is where the plug-\/in\textquotesingle{}s audio buffer processing of the plug-\/in occurs. Note that this function is passed a pointer to an array of {\ttfamily SDemo\+Gain\+\_\+\+Alg\+\_\+\+Contexts}. Each of these represents the state of a particular instance of Demo\+Gain, and contains pointers to the applicable coefficient and audio buffer data.

Using the {\ttfamily SDemo\+Gain\+\_\+\+Alg\+\_\+\+Context} array, instance-\/specific information and audio buffers are easily retrieved for processing. Demo\+Gain accomplishes this by first iterating over each plug-\/in instance, then over each channel, and finally over each sample, at which point the gain coefficient is applied to each sample in the input audio buffer and the sample data is copied to the output audio buffer\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ -\/-\/-\/-\/-\/-\/-\/-\/-\/\ Iterate\ over\ plug\ -\/in\ instances\ -\/-\/-\/-\/-\/-\/-\/-\/-\///}}
\DoxyCodeLine{\textcolor{keywordflow}{for}\ (SDemoGain\_Alg\_Context\ *\ \textcolor{keyword}{const}\ *\ walk\ =\ inInstancesBegin\ ;\ walk\ \&lt;}
\DoxyCodeLine{\ \ \ \ inInstancesEnd\ ;\ ++\ walk\ )}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ -\/-\/-\/-\/-\/-\/-\/-\/-\/\ Run\ processing\ loop\ over\ each\ input\ channel\ -\/-\/-\/-\/-\/-\/-\/-\/-\///}}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{for}\ (\textcolor{keywordtype}{int}\ ch\ =\ 0;\ ch\ \&lt;\ kNumChannelsIn\ ;\ ch\ ++)}
\DoxyCodeLine{\ \ \ \ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ -\/-\/-\/-\/-\/-\/-\/-\/-\/\ Run\ processing\ loop\ over\ each\ sample\ -\/-\/-\/-\/-\/-\/-\/-\/-\///}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{keywordflow}{for}\ (\textcolor{keywordtype}{int}\ t\ =\ 0;\ t\ \&lt;\ kAudioWindowSize\ ;\ t++)}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ pdO\ [t]\ =\ gain\ *\ pdI\ [t];}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \}\ \textcolor{comment}{//\ Go\ to\ the\ next\ sample}}
\DoxyCodeLine{\ \ \ \ \}\ \textcolor{comment}{//\ Go\ to\ next\ channel}}
\DoxyCodeLine{\ \}\ \textcolor{comment}{//\ End\ instance-\/iteration\ loop\ }}

\end{DoxyCode}
  Listing 5\+: Iterative loops in the Demo\+Gain algorithm

\hypertarget{a00875_subsection__describe_connect_the_parameter_throughout_the_plugin}{}\doxysubsubsection{Describe\+: Connect the parameter throughout the plug-\/in}\label{a00875_subsection__describe_connect_the_parameter_throughout_the_plugin}
 As mentioned before, Describe provides a static description of all communication pathways between a plug-\/in\textquotesingle{}s algorithm, host, and data model. In addition, various effect properties are defined that help the host determine how to handle the plug-\/in.

Communication paths between the various plug-\/in components are described as connections between source and destination ports. In order for these communication paths to be created, the algorithm must first define some destination ports by actually registering its previously defined context fields as communication destinations. Demo\+Gain does this for its gain parameter through the following call to \mbox{\hyperlink{a02193_a230293b9f6bb413626cd487ca501df75}{AAX\+\_\+\+IComponent\+Descriptor\+::\+Add\+Data\+In\+Port()}} in Demo\+Gain\+\_\+\+Describe.\+cpp\textquotesingle{}s {\ttfamily Describe\+Algorithm\+Component()} method\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{a02193}{AAX\_IComponentDescriptor}}\ *\ compDesc;}
\DoxyCodeLine{compDesc\ =\ outDescriptor-\/>NewComponentDescriptor\ ();}
\DoxyCodeLine{err\ =\ compDesc-\/>\mbox{\hyperlink{a02193_a230293b9f6bb413626cd487ca501df75}{AddDataInPort}}\ (}
\DoxyCodeLine{\ \ \ \ eAlgPortID\_CoefsGainIn\ ,}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{sizeof}\ (SDemoGain\_CoefsGain)\ );\ }

\end{DoxyCode}
  Listing 6\+: Adding a data port to Demo\+Gain\textquotesingle{}s algorithm component descriptor

This registration process is required for both custom coefficients (Gain) and for data that all plug-\/ins need such as audio input and output fields.

That completes the connection, and now the plug-\/in is fully wired to receive parameter updates, convert raw parameter values to algorithmic coefficients, pack these coefficients into a packet, post the packet to the host for routing, receive the updated packet in the list of context structures that the host provides when calling the algorithm callback, and apply the updated coefficient data in the appropriate context structure to the plug-\/in\textquotesingle{}s audio data. Whew! \hypertarget{a00875_subsection__gui_add_a_control}{}\doxysubsubsection{GUI\+: Add a control}\label{a00875_subsection__gui_add_a_control}
 Although the specific steps for adding a GUI control to edit a plug-\/in parameter will vary depending on the GUI framework you choose, there are a few basic design principles that should always be followed.

The basic Demo\+Gain plug-\/in does not include any GUI implementation. For practical GUI implementation examples, open the Demo\+Gain\+\_\+\+GUIExtensions sample plug-\/ins. Demo\+Gain\+\_\+\+Cocoa provides an example of a custom plug-\/in GUI using the native mac\+OS SDK, while Demo\+Gain\+\_\+\+Win32 uses native Windows APIs. The other examples in this folder require common third-\/party libraries.

\hypertarget{a00875_subsubsection__control_edits_vs_parameter_updates_}{}\doxyparagraph{Control edits vs. parameter updates}\label{a00875_subsubsection__control_edits_vs_parameter_updates_}
 The most important principle for AAX GUI design is that an edit in a plug-\/in\textquotesingle{}s GUI should never directly set the state of the associated parameter or parameters. This is because there may be other controller clients of the plug-\/in\textquotesingle{}s data model which will need to be notified of the edit, or which may need to override edits from the GUI. 
\begin{DoxyItemize}
\item  On control edit

When a control is edited in the plug-\/in GUI, call \mbox{\hyperlink{a02049_a368b0f5a761d1eda4c41b420f153a077}{AAX\+\_\+\+IEffect\+Parameters\+::\+Set\+Parameter\+Normalized\+Value()}}. The implementation of this method should post a request to the host in order to trigger the parameter update. The GUI should not update its state until the corresponding parameter update notification is received.  
\item  On parameter update

A parameter update can occur in response to a GUI edit, an edit from another attached controller, an update to a linked parameter, or any other event that affects the state of the data model. When the state of a parameter changes, \mbox{\hyperlink{a02045_a45b468fef806611581f748af9301ab4d}{AAX\+\_\+\+IEffect\+GUI\+::\+Parameter\+Updated()}} is called. The plug-\/in\textquotesingle{}s GUI should be updated in this method in order to reflect the new state of the affected parameter.  
\end{DoxyItemize}

 For detailed information about the sequence of events and GUI responsibilities during a parameter update, see \mbox{\hyperlink{a00903}{Parameter updates}} 

\hypertarget{a00875_subsubsection__notifying_the_host_of_gui_events_}{}\doxyparagraph{Notifying the host of GUI events}\label{a00875_subsubsection__notifying_the_host_of_gui_events_}
 Some GUI events must be handled by the host rather than by the plug-\/in. For example, in Pro Tools a user should be able to display a pop-\/up menu for controlling automation information by command-\/option-\/control-\/clicking (Mac) or alt-\/ctl-\/right clicking (Windows) a control. These events, and other direct communication between the GUI and the \char`\"{}container\char`\"{} in which the host creates the plug-\/in view, is accomplished via the \mbox{\hyperlink{a02329}{AAX\+\_\+\+IView\+Container}} interface. Be sure to always call the handler methods in this interface before handling a mouse event within the plug-\/in GUI, in order to maintain the expected host behavior.



 \hypertarget{a00875_aax_sdk_guide_next_steps}{}\doxysubsection{Next Steps}\label{a00875_aax_sdk_guide_next_steps}
 Now that you have a basic understanding of AAX, head back to the \mbox{\hyperlink{a00874_welcome_basics}{front page}} and continue reading through the suggested documentation. Or dig in to the \mbox{\hyperlink{a00931}{sample plug-\/ins}} to see how specific features are supported in AAX.

 \begin{DoxyWarning}{Warning}
Your AAX plug-\/ins will not be compatible with shipping versions of Pro Tools until they are digitally signed using tools provided by PACE Anti-\/\+Piracy, Inc. As an AAX developer you can receive these tools free of charge. Read the \mbox{\hyperlink{a00913_subsection__digital_signature_}{Digital signature}} section of the \mbox{\hyperlink{a00913}{Pro Tools Guide}} to learn about the digital signing requirements for compatibility with Pro Tools.
\end{DoxyWarning}
 Collaboration diagram for Getting Started with AAX\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=337pt]{a00875}
\end{center}
\end{figure}
