\hypertarget{a00889}{}\doxysection{Description callback}
\label{a00889}\index{Description callback@{Description callback}}


\doxysubsection{ }
Static configuration for an AAX plug-\/in. 

\hypertarget{a00889_describe_contents}{}\doxysubsection{On this page}\label{a00889_describe_contents}
\begin{DoxyItemize}
\item \mbox{\hyperlink{a00889_describe_about}{About the Describe callback and AAX descriptor interfaces}} \item \mbox{\hyperlink{a00889_describe_collection}{Top level\+: Collection}} \item \mbox{\hyperlink{a00889_describe_effects}{Middle level\+: Effects}} \item \mbox{\hyperlink{a00889_describe_component}{Lowest level\+: Algorithm components}} \item \mbox{\hyperlink{a00889_describe_checking_results}{Checking Results}} \item \mbox{\hyperlink{a00889_describe_validation}{Describe Validation}} \item \mbox{\hyperlink{a00889_describe_additionaltopics}{Additional Topics}}\end{DoxyItemize}
 \hypertarget{a00889_describe_about}{}\doxysubsection{About the Describe callback and AAX descriptor interfaces}\label{a00889_describe_about}
 
\begin{DoxyImageNoCaption}
  \mbox{\includegraphics[width=\textwidth,height=\textheight/2,keepaspectratio=true]{dot_aax_desc_interfaces}}
\end{DoxyImageNoCaption}


 In Describe, a plug-\/in declares its static (or default) configuration and any properties that the host will need in order to manage the plug-\/in.

 A plug-\/in\textquotesingle{}s Describe callback ties the Algorithm, GUI, and Data Model together. In this callback, the plug-\/in provides a description of its algorithm callbacks, data connections, and other static plug-\/in properties using a set of host-\/provided description interfaces. The plug-\/in uses a tiered hierarchy of these description interfaces to complete its description\+: 
\begin{DoxyItemize}
\item At the top level, a single Collection interface represents properties that apply to the plug-\/in binary.  
\item The Collection interface is populated with one or more Effect descriptors, each of which represents a single kind of effect. For example, a single dynamics plug-\/in binary may include both single-\/band and multi-\/band Effects. Each Effect represents a different plug-\/in \char`\"{}product\char`\"{} available to users.  
\item Each Effect is registered with a set of one or more algorithm components that represent the specific processing configurations (e.\+g. stem formats, sample rates) that the plug-\/in supports. The set of components in a single Effect provide possible variations of the single plug-\/in \char`\"{}product\char`\"{}, and as such these variations are mostly transparent to users.  
\end{DoxyItemize}

 The actual description callback entrypoint is \mbox{\hyperlink{a00545_aa455fa4d9a2236334d0fd959b4919788}{ACFRegister\+Plugin()}}, which is declared in \mbox{\hyperlink{a00545}{AAX\+\_\+\+Exports.\+cpp}}. This method is implemented inside of the AAX Library, where it calls the plug-\/in\textquotesingle{}s custom implementation of the \mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{Get\+Effect\+Descriptions()}} callback.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ ***************************************************************************}}
\DoxyCodeLine{\textcolor{comment}{//\ ROUTINE:\ GetEffectDescriptions}}
\DoxyCodeLine{\textcolor{comment}{//\ ***************************************************************************}}
\DoxyCodeLine{\mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{GetEffectDescriptions}}(\ \mbox{\hyperlink{a02210}{AAX\_ICollection}}\ *\ outCollection\ )}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a02254}{AAX\_IEffectDescriptor}}\ *\ \ \ \ plugInDescriptor\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a7aaf7765f164602cc2afb8fb28c2c588}{NewDescriptor}}();}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{if}\ (\ plugInDescriptor\ )}
\DoxyCodeLine{\ \ \ \ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ result\ =\ DemoGain\_GetPlugInDescription(\ plugInDescriptor\ );}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{keywordflow}{if}\ (\ result\ ==\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ )}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ kEffectID\_DemoGain,\ plugInDescriptor\ );}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{else}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937a647cce13fa531e3a46c6eab694048a9c}{AAX\_ERROR\_NULL\_OBJECT}};}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_a7fbeab9630460b9bf4525512609855f0}{SetManufacturerName}}(\ \textcolor{stringliteral}{"{}Avid,\ Inc."{}}\ );}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_acf7410e0d06cf64bea36bf7d18b3456c}{AddPackageName}}(\ \textcolor{stringliteral}{"{}DemoGain\ Plug-\/In"{}}\ );}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_acf7410e0d06cf64bea36bf7d18b3456c}{AddPackageName}}(\ \textcolor{stringliteral}{"{}DemoGain"{}}\ );}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_acf7410e0d06cf64bea36bf7d18b3456c}{AddPackageName}}(\ \textcolor{stringliteral}{"{}DmGi"{}}\ );\ \ \ \ \ \ }
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_a4e69ac93eaac9c285c2bc3ac5b25880b}{SetPackageVersion}}(\ 1\ );\ \ \ \ \ }
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{return}\ result;}
\DoxyCodeLine{}
\DoxyCodeLine{\}}

\end{DoxyCode}
 \mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{Get\+Effect\+Descriptions()}} from the Demo\+Gain example plug-\/in

 In general, the following procedure is used when describing an AAX plug-\/in\+: 
\begin{DoxyEnumerate}
\item Create an Effect description interface from the Collection interface provided by the host  
\item Use the Effect description interface to create references to one or more component description interfaces.  
\item Describe each algorithm component by populating the component descriptions.  
\item Add the components to the Effect description 
\item Add additional modules and properties to the Effect description.  
\item Add the completed Effect to the Collection  
\item Repeat for any additional Effects included in the plug-\/in binary.  
\item Return the completed Collection interface to the host and exit.  
\end{DoxyEnumerate}

 \begin{DoxyNote}{Note}
The host owns all memory associated with any descriptors that the plug-\/in returns via this callback.
\end{DoxyNote}


 \hypertarget{a00889_describe_collection}{}\doxysubsection{Top level\+: Collection}\label{a00889_describe_collection}
 The \mbox{\hyperlink{a02210}{AAX\+\_\+\+ICollection}} interface provides a creation function (\mbox{\hyperlink{a02210_a7aaf7765f164602cc2afb8fb28c2c588}{AAX\+\_\+\+ICollection\+::\+New\+Descriptor()}}) for new plug-\/in descriptors, which in turn provides access to the various interfaces necessary for describing a plug-\/in (see the {\ttfamily Demo\+Gain\+\_\+\+Get\+Plug\+In\+Description()} and {\ttfamily Describe\+Algorithm\+Component()} listings below).

 When a plug-\/in description is complete, it is added to the collection via the \mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AAX\+\_\+\+ICollection\+::\+Add\+Effect()}} method. The \mbox{\hyperlink{a02210}{AAX\+\_\+\+ICollection}} interface also provides some additional description methods that are used to describe the overall plug-\/in package. These methods can be used to describe the plug-\/in package\textquotesingle{}s name, the name of the plug-\/in\textquotesingle{}s manufacturer, and the plug-\/in package version. Once these have been described, the completed description interface is returned to the host and exits.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ ***************************************************************************}}
\DoxyCodeLine{\textcolor{comment}{//\ ROUTINE:\ GetEffectDescriptions}}
\DoxyCodeLine{\textcolor{comment}{//\ ***************************************************************************}}
\DoxyCodeLine{\mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{GetEffectDescriptions}}(\ \mbox{\hyperlink{a02210}{AAX\_ICollection}}\ *\ outCollection\ )}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a02254}{AAX\_IEffectDescriptor}}\ *\ \ \ \ plugInDescriptor\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a7aaf7765f164602cc2afb8fb28c2c588}{NewDescriptor}}();}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ result\ =\ DemoGain\_GetPlugInDescription(\ plugInDescriptor\ );}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ kEffectID\_DemoGain,\ plugInDescriptor\ );}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_a7fbeab9630460b9bf4525512609855f0}{SetManufacturerName}}(\ \textcolor{stringliteral}{"{}Avid,\ Inc."{}}\ );}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_acf7410e0d06cf64bea36bf7d18b3456c}{AddPackageName}}(\ \textcolor{stringliteral}{"{}DemoGain\ Plug-\/In"{}}\ );}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_acf7410e0d06cf64bea36bf7d18b3456c}{AddPackageName}}(\ \textcolor{stringliteral}{"{}DemoGain"{}}\ );}
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_acf7410e0d06cf64bea36bf7d18b3456c}{AddPackageName}}(\ \textcolor{stringliteral}{"{}DmGi"{}}\ );\ \ \ \ \ \ }
\DoxyCodeLine{\ \ \ \ outCollection-\/>\mbox{\hyperlink{a02210_a4e69ac93eaac9c285c2bc3ac5b25880b}{SetPackageVersion}}(\ 1\ );\ \ \ \ \ }
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{return}\ result;}
\DoxyCodeLine{\}}

\end{DoxyCode}
 Populating the \mbox{\hyperlink{a02210}{AAX\+\_\+\+ICollection}} interface



 \hypertarget{a00889_describe_effects}{}\doxysubsection{Middle level\+: Effects}\label{a00889_describe_effects}
 The \mbox{\hyperlink{a02254}{AAX\+\_\+\+IEffect\+Descriptor}} interface provides description methods that are used to describe the Effect, such as its name, category, associated page table, and, importantly, creation methods for its data model, GUI, and other AAX modules.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ ***************************************************************************}}
\DoxyCodeLine{\textcolor{comment}{//\ ROUTINE:\ DemoGain\_GetPlugInDescription}}
\DoxyCodeLine{\textcolor{comment}{//\ ***************************************************************************}}
\DoxyCodeLine{\textcolor{keyword}{static}\ \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ DemoGain\_GetPlugInDescription(\ \mbox{\hyperlink{a02254}{AAX\_IEffectDescriptor}}\ *\ outDescriptor\ )}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{int}\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ err;}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a02214}{AAX\_IComponentDescriptor}}\ *\ \ compDesc\ =\ outDescriptor-\/>\mbox{\hyperlink{a02254_af97bdbad865d89f360d1b5fd6f71b3bf}{NewComponentDescriptor}}\ ();}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{if}\ (\ !compDesc\ )}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{keywordflow}{return}\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937a647cce13fa531e3a46c6eab694048a9c}{AAX\_ERROR\_NULL\_OBJECT}};}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Add\ empty\ component\ descriptors\ to\ the\ host,\ register\ a\ processing}}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ entrypoint\ for\ each,\ and\ populate\ with\ description\ information.\ }}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//}}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Alg\ component}}
\DoxyCodeLine{\ \ \ \ DescribeAlgorithmComponent(\ compDesc\ );}
\DoxyCodeLine{\ \ \ \ err\ =\ outDescriptor-\/>\mbox{\hyperlink{a02254_aec33938f50461dd5e7c1dcc25faf6917}{AddComponent}}(\ compDesc\ );\ \mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}\ (err\ ==\ 0);}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>AddPlugInName\ (\ \textcolor{stringliteral}{"{}Demo\ Gain\ AAX"{}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>AddPlugInName\ (\ \textcolor{stringliteral}{"{}Demo\ Gain"{}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>AddPlugInName\ (\ \textcolor{stringliteral}{"{}DemoGain"{}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>AddPlugInName\ (\ \textcolor{stringliteral}{"{}DmGain"{}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>AddPlugInName\ (\ \textcolor{stringliteral}{"{}DGpr"{}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>AddPlugInName\ (\ \textcolor{stringliteral}{"{}Dn"{}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>AddPlugInCategory\ (\ \mbox{\hyperlink{a00446_aef9637518fb1ac0e2f403444c73aba4aa1e8d5202983c58aa0346a9a547f55bd9}{AAX\_ePlugInCategory\_Dynamics}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>\mbox{\hyperlink{a02254_ad1a286ef7cb869e6f79423dd774ec976}{AddProcPtr}}(\ (\textcolor{keywordtype}{void}\ *)\ DemoGain\_Parameters::Create,\ \mbox{\hyperlink{a00779_af0682195d377392ad356fd2b00c36892a86aab4af036f1087b4f31bbac234ac3d}{kAAX\_ProcPtrID\_Create\_EffectParameters}}\ );}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>\mbox{\hyperlink{a02254_a3326bd8e29690a352408539029a50a61}{AddResourceInfo}}\ (\ \mbox{\hyperlink{a00446_ae2805e88175d975589153a04e42898bbab0028d7fb45564dc4afa0f0a50296043}{AAX\_eResourceType\_PageTable}},\ \textcolor{stringliteral}{"{}DemoGainPages.xml"{}}\ );}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{preprocessor}{\#if\ PLUGGUI\ !=\ 0}}
\DoxyCodeLine{\ \ \ \ outDescriptor-\/>\mbox{\hyperlink{a02254_ad1a286ef7cb869e6f79423dd774ec976}{AddProcPtr}}(\ (\textcolor{keywordtype}{void}\ *)\ DemoGain\_GUI::Create,\ \mbox{\hyperlink{a00779_af0682195d377392ad356fd2b00c36892a102df0cf99f7423a7997dd283eed7a88}{kAAX\_ProcPtrID\_Create\_EffectGUI}}\ );}
\DoxyCodeLine{\textcolor{preprocessor}{\#endif}}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{return}\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{\}}

\end{DoxyCode}
 Populating an \mbox{\hyperlink{a02254}{AAX\+\_\+\+IEffect\+Descriptor}} interface

 All components in an Effect must share the same AAX modules; for example, it is not possible to use one data model definition for one sample rate and another data model definition for a different sample rate. Therefore, a plug-\/in\textquotesingle{}s AAX modules are defined in its Effect description.

\hypertarget{a00889_describe_effects_multiple}{}\doxysubsubsection{Registering multiple Effects}\label{a00889_describe_effects_multiple}
 A single plug-\/in package may include multiple Effects, which are added in turn in the description method. Once these connections are made, Describe passes the host a populated description interface and returns.

 For example, consider an EQ plug-\/in that contains both one-\/band and four-\/band variations, each of which the user should see as a distinct plug-\/in. These Effects would be described and added separately to the collection object and would appear as separate products to the user.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ GetEffectsDescriptions\ (\ \mbox{\hyperlink{a02210}{AAX\_ICollection}}\ *\ outCollection\ )}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ ;}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{if}\ (\ result\ ==\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ )}
\DoxyCodeLine{\ \ \ \ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \mbox{\hyperlink{a02254}{AAX\_IEffectDescriptor}}\ *\ aDesc1\ =\ outCollection\ -\/>\ NewDescriptor\ ();}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ ...}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ Populate\ aDesc1\ with\ one\ -\/\ band\ EQ\ description}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ ...}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ result\ =\ outCollection\ -\/>\ AddEffect\ (\ kEffectID\_MyOneBandEQ\ ,\ aDesc1\ );}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{if}\ (\ result\ ==\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ )}
\DoxyCodeLine{\ \ \ \ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \mbox{\hyperlink{a02254}{AAX\_IEffectDescriptor}}\ *\ aDesc4\ =\ outCollection\ -\/>\ NewDescriptor\ ();}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ ...}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ Populate\ aDesc4\ with\ four\ -\/\ band\ EQ\ description}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \textcolor{comment}{//\ ...}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ result\ =\ outCollection\ -\/>\ AddEffect\ (\ kEffectID\_MyFourBandEQ\ ,\ aDesc4\ );}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{if}\ (\ result\ ==\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ )}
\DoxyCodeLine{\ \ \ \ \{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ outCollection\ -\/>\ SetManufacturerName\ (\ \textcolor{stringliteral}{"{}My\ Plug\ -\/Ins\ ,\ \ Inc."{}}\ );}
\DoxyCodeLine{\ \ \ \ \ \ \ \ outCollection\ -\/>\ AddPackageName\ (\ \textcolor{stringliteral}{"{}\ MyEQ\ \ Plug\ -\/In"{}}\ );}
\DoxyCodeLine{\ \ \ \ \ \ \ \ outCollection\ -\/>\ AddPackageName\ (\ \textcolor{stringliteral}{"{}\ MyQ"{}}\ );\ \textcolor{comment}{//\ Short\ name}}
\DoxyCodeLine{\ \ \ \ \ \ \ \ outCollection\ -\/>\ SetPackageVersion\ (\ 1\ );}
\DoxyCodeLine{\ \ \ \ \}}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordflow}{return}\ result\ ;}
\DoxyCodeLine{\}}

\end{DoxyCode}
 Registering multiple Effects in a single Collection



 \hypertarget{a00889_describe_component}{}\doxysubsection{Lowest level\+: Algorithm components}\label{a00889_describe_component}
 In order to register an algorithm component, a plug-\/in must describe the component\textquotesingle{}s external interface. This includes each of the component\textquotesingle{}s ports and any other fi elds in its context structure, a reference to its processing function entrypoint (its \char`\"{}\+Process Procedure\char`\"{}, or Process\+Proc,) and any other special properties that the host should know about.

 The description of a context structure 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). See \mbox{\hyperlink{a00890}{Real-\/time algorithm callback}} for more information on an algorithm\textquotesingle{}s context structure.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{static}\ \textcolor{keywordtype}{void}\ DescribeAlgorithmComponent(\ \mbox{\hyperlink{a02214}{AAX\_IComponentDescriptor}}\ *\ outDesc\ )}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ err;}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Subscribe\ context\ fields\ to\ host-\/provided\ services\ or\ information}}
\DoxyCodeLine{\ \ \ \ err\ =\ outDesc-\/>AddField\ (\ eAlgFieldID\_AudioIn,\ kAAX\_FieldTypeAudioIn\ );\ \mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}(err\ ==\ 0);}
\DoxyCodeLine{\ \ \ \ err\ =\ outDesc-\/>AddField\ (\ eAlgFieldID\_AudioOut,\ kAAX\_FieldTypeAudioOut\ );\ \mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}\ (err\ ==\ 0);}
\DoxyCodeLine{\ \ \ \ err\ =\ outDesc-\/>AddField\ (\ eAlgFieldID\_BufferSize,\ kAAX\_FieldTypeAudioBufferLength\ );\ \mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}\ (err\ ==\ 0);}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Register\ context\ fields\ as\ communications\ destinations}}
\DoxyCodeLine{\ \ \ \ err\ =\ outDesc-\/>\mbox{\hyperlink{a02214_a230293b9f6bb413626cd487ca501df75}{AddDataInPort}}\ (\ eAlgPortID\_BypassIn,\ \textcolor{keyword}{sizeof}\ (int32\_t)\ );\ \mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}\ (err\ ==\ 0);}
\DoxyCodeLine{\ \ \ \ err\ =\ outDesc-\/>\mbox{\hyperlink{a02214_a230293b9f6bb413626cd487ca501df75}{AddDataInPort}}\ (\ eAlgPortID\_CoefsGainIn,\ \textcolor{keyword}{sizeof}\ (SDemoGain\_CoefsGain)\ );\ \mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}\ (err\ ==\ 0);}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\}}

\end{DoxyCode}
 Populating a single \mbox{\hyperlink{a02214}{AAX\+\_\+\+IComponent\+Descriptor}} interface

\hypertarget{a00889_describe_component_properties}{}\doxysubsubsection{Algorithm callback properties}\label{a00889_describe_component_properties}
 A set of callback properties is required when adding a Process Procedure to an algorithm component. This is done via the \mbox{\hyperlink{a02314}{AAX\+\_\+\+IProperty\+Map}} interface. Using distinct property maps, a single component may register multiple versions of its callback. For example, an audio processing component might register mono and stereo callbacks, or Native and TI callbacks, assigning each the applicable property mapping. This allows the host to determine the correct callback to use depending on the environment in which the plug-\/in is instantiated.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{static}\ \textcolor{keywordtype}{void}\ DescribeAlgorithmComponent(\ \mbox{\hyperlink{a02214}{AAX\_IComponentDescriptor}}\ *\ outDesc\ )}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a02314}{AAX\_IPropertyMap}}\ *\ \ \ \ \ \ \ \ \ \ properties\ =\ outDesc-\/>\mbox{\hyperlink{a02214_a19c95a83c0af45316532bea904b58d43}{NewPropertyMap}}();}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .\ \ \ \ \ \ \ }
\DoxyCodeLine{\ \ \ \ properties-\/>Clear\ ();}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da996465cca29a2a15291d1c788ac5728c}{AAX\_eProperty\_ManufacturerID}},\ cDemoGain\_ManufactureID\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da3a41fcdff5af1a4fd19dcbca7b1ba6f3}{AAX\_eProperty\_ProductID}},\ cDemoGain\_ProductID\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0dadebf03028b758123965a8b988fa2df99}{AAX\_eProperty\_InputStemFormat}},\ \mbox{\hyperlink{a00446_ad8af5ef008b2bd478add9a0acb0a1d85a0cc08ddb9923a4093c820efe84588947}{AAX\_eStemFormat\_Mono}}\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da211fdc6277e7fa652b5d482e810b0bc9}{AAX\_eProperty\_OutputStemFormat}},\ \mbox{\hyperlink{a00446_ad8af5ef008b2bd478add9a0acb0a1d85a0cc08ddb9923a4093c820efe84588947}{AAX\_eStemFormat\_Mono}}\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da6819867a9e86913e59decf318416d755}{AAX\_eProperty\_CanBypass}},\ \textcolor{keyword}{true}\ );}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ Native\ and\ AudioSuite\ versions}}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da89ca3dd6e96895cda14976c1b1ceb826}{AAX\_eProperty\_PlugInID\_Native}},\ cDemoGain\_PlugInID\_Native\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0dad3344696b8298a8b254add3d039ea927}{AAX\_eProperty\_PlugInID\_AudioSuite}},\ cDemoGain\_PlugInID\_AudioSuite\ );\ \ \ \textcolor{comment}{//\ Since\ this\ is\ a\ linear\ plug-\/in\ the\ RTAS\ version\ can\ also\ be\ an\ AudioSuite\ version.}}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da09fbd1cbcae0e86ad81005258dc1b67e}{AAX\_eProperty\_DSP\_AudioBufferLength}},\ kAAX\_NativeAudioBufferLength\_Default);}
\DoxyCodeLine{\ \ \ \ err\ =\ outDesc-\/>\mbox{\hyperlink{a02214_a1c069508cf54a523905c8160ebf628ad}{AddProcessProc\_Native}}\ (\ DemoGain\_AlgorithmProcessFunction\ <1,\ 1,\ 1<<kAAX\_NativeAudioBufferLength\_Default>,\ properties\ );\ \mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}\ (err\ ==\ 0);}
\DoxyCodeLine{}
\DoxyCodeLine{\ \ \ \ \textcolor{comment}{//\ TI\ DSP\ Version}}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da75f174df4efbeca86eaada126c1d9214}{AAX\_eProperty\_PlugInID\_TI}},\ cDemoGain\_PlugInID\_TI\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da09fbd1cbcae0e86ad81005258dc1b67e}{AAX\_eProperty\_DSP\_AudioBufferLength}},\ \mbox{\hyperlink{a00446_ab33e0f1ecf04ca4161fa8d8de5845d67ad1a72546e5300b5c64a19e8e41d12e15}{AAX\_eAudioBufferLengthDSP\_Default}}\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da5d8e5be9f3698a9c67a578c29da66405}{AAX\_eProperty\_TI\_InstanceCycleCount}},\ 1055\ );}
\DoxyCodeLine{\ \ \ \ properties-\/>\mbox{\hyperlink{a02314_a0997671afce9a2367662c764c1d055dd}{AddProperty}}\ (\ \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da3e5b289333ba49f5a33de40d89fa4ade}{AAX\_eProperty\_TI\_SharedCycleCount}},\ 58\ );}
\DoxyCodeLine{\}}

\end{DoxyCode}
 Adding properties to a component description

 AAX does not require that every value in \mbox{\hyperlink{a02314}{AAX\+\_\+\+IProperty\+Map}} be assigned by the developer. However, if a speci c value is not assigned to one of an element\textquotesingle{}s properties then the element must support any value for that property. For example, if an audio processing component does not provide any stem format properties then the host will assume that the callback will support any stem format.



 \hypertarget{a00889_describe_checking_results}{}\doxysubsection{Checking Results}\label{a00889_describe_checking_results}
\hypertarget{a00889_describe_checking_results_summary}{}\doxysubsubsection{Summary}\label{a00889_describe_checking_results_summary}

\begin{DoxyItemize}
\item Use \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} to store result values from all method calls in Describe.
\item Use the \mbox{\hyperlink{a00620_a8f177823e9388c5163d1b402a9069bce}{AAX\+\_\+\+SWALLOW}} and \mbox{\hyperlink{a00620_aef6db72a3774d079609f94720928cdd6}{AAX\+\_\+\+SWALLOW\+\_\+\+MULT}} macros to encapsulate independent describe code, such as registration logic for separate Effects or for separate Process\+Proc variations within a single Effect.
\end{DoxyItemize}

\hypertarget{a00889_describe_checking_results_problem}{}\doxysubsubsection{The Problem}\label{a00889_describe_checking_results_problem}
 With plain \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} values it can be challenging to properly detect and handle error states. Each description method call returns an \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} to indicate success or failure, and often problems in a plug-\/in\textquotesingle{}s configuration can be addressed by properly detecting and resolving errors that occur here. However, adding a return value check after ever method and providing conditional logic in the case of a failure is onerous, ugly, and difficult to maintain.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{}
\DoxyCodeLine{result\ =\ descriptor-\/>SomeMethod();}
\DoxyCodeLine{result\ =\ descriptor-\/>AnotherMethod();\ \textcolor{comment}{//\ oops!\ might\ ignore\ an\ error}}

\end{DoxyCode}


 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ -\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/}}
\DoxyCodeLine{\textcolor{comment}{//\ Safer,\ but\ not\ a\ good\ solution:}}
\DoxyCodeLine{\textcolor{comment}{//\ Information\ about\ the\ errors\ is\ lost,\ the}}
\DoxyCodeLine{\textcolor{comment}{//\ merged\ error\ code\ is\ meaningless,\ and}}
\DoxyCodeLine{\textcolor{comment}{//\ debugging\ to\ find\ the\ location\ of\ the}}
\DoxyCodeLine{\textcolor{comment}{//\ failure\ is\ hard.}}
\DoxyCodeLine{\textcolor{comment}{//}}
\DoxyCodeLine{result\ |=\ descriptor-\/>SomeMethod();}
\DoxyCodeLine{result\ |=\ descriptor-\/>AnotherMethod();}
\DoxyCodeLine{\textcolor{comment}{//\ ...}}
\DoxyCodeLine{\textcolor{keywordflow}{if}\ (\mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ !=\ result)}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ handle\ the\ merged\ error\ code}}
\DoxyCodeLine{\}}

\end{DoxyCode}


 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ -\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/}}
\DoxyCodeLine{\textcolor{comment}{//\ This\ is\ also\ not\ a\ good\ solution:}}
\DoxyCodeLine{\textcolor{comment}{//\ There\ is\ no\ actual\ handling\ of\ errors}}
\DoxyCodeLine{\textcolor{comment}{//\ (from\ the\ SDK\ example\ plug-\/ins)}}
\DoxyCodeLine{\textcolor{comment}{//}}
\DoxyCodeLine{result\ =\ descriptor-\/>SomeMethod();}
\DoxyCodeLine{\mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}(\mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ ==\ result);}
\DoxyCodeLine{result\ =\ descriptor-\/>AnotherMethod();}
\DoxyCodeLine{\mbox{\hyperlink{a00740_a168ee44fd7a5485ab50160db36fb2988}{AAX\_ASSERT}}(\mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ ==\ result);}

\end{DoxyCode}


 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{//\ -\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/}}
\DoxyCodeLine{\textcolor{comment}{//\ This\ is\ correct\ but\ is\ too\ hard}}
\DoxyCodeLine{\textcolor{comment}{//}}
\DoxyCodeLine{\mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{result\ =\ descriptor-\/>SomeMethod();}
\DoxyCodeLine{\textcolor{keywordflow}{if}\ (\mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ !=\ result)\ \{}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ logic\ to\ handle\ this\ error:}}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ assert\ and/or\ log\ the\ failure?}}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ return\ or\ continue\ execution?}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{result\ =\ descriptor-\/>AnotherMethod();}
\DoxyCodeLine{\textcolor{keywordflow}{if}\ (\mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}}\ !=\ result)\ \{}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ ditto}}
\DoxyCodeLine{\}}

\end{DoxyCode}
 \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} based error checking is awkward

\hypertarget{a00889_describe_checking_results_solution}{}\doxysubsubsection{The Solution}\label{a00889_describe_checking_results_solution}
 The \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} class is designed to solve this problem. \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} can be used just like a plain-\/old-\/data \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} \+:

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{a01990}{AAX\_CheckedResult}}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{result\ =\ descriptor-\/>SomeMethod();}
\DoxyCodeLine{result\ =\ descriptor-\/>AnotherMethod();}

\end{DoxyCode}
 Simpler result checking with \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}}

 When a failure is encountered, \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} will\+:
\begin{DoxyItemize}
\item Store the error value
\item Log the error using AAX\+\_\+\+TRACE\+\_\+\+RELEASE
\item Throw an exception of type \mbox{\hyperlink{a01990_a36fd71afc6d62993c1dd96e1ca9fcc0e}{AAX\+\_\+\+Checked\+Result\+::\+Exception}}
\end{DoxyItemize}

 To make this safe to use in the Describe routine, the \mbox{\hyperlink{a00948}{AAX}} Library includes a try/catch block around the call to the plug-\/in\textquotesingle{}s {\ttfamily \mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{Get\+Effect\+Descriptions()}}} routine.

 \begin{DoxyWarning}{Warning}
Do not use \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} anywhere where an exception could escape to the host (\mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{Get\+Effect\+Descriptions()}} is OK)
\end{DoxyWarning}
\hypertarget{a00889_describe_checking_results_handling_errors}{}\doxysubsubsection{Handling Errors and Managing Control Flow}\label{a00889_describe_checking_results_handling_errors}
 With the basic approach shown above, any error which is encountered will throw an exception which will cancel the plug-\/in\textquotesingle{}s registration and prevent the plug-\/in from being shown in the host. However, most errors can be safely handled without canceling the entire plug-\/in registration.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{a01990}{AAX\_CheckedResult}}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ effect\ 1\ registration}}
\DoxyCodeLine{result\ =\ DescribeMyEffect1(\ effect1Descriptor\ );}
\DoxyCodeLine{result\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ myEffect1ID,\ effect1Descriptor\ );}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ effect\ 2\ registration}}
\DoxyCodeLine{result\ =\ DescribeMyEffect2(\ effect2Descriptor\ );}
\DoxyCodeLine{result\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ myEffect2ID,\ effect2Descriptor\ );}

\end{DoxyCode}
 Example with no error handling

 In this example, a failure when describing either individual effect will prevent the other effect from being registered. Registration of individual Process\+Procs within a single effect, e.\+g. for different stem formats, is similar.

 To allow the registration of other effects to proceed in the event of a failure, any exceptions thrown during the registration of one effect should be caught and should only prevent the registration of that individual effect.

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{a01990}{AAX\_CheckedResult}}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ effect\ 1\ registration}}
\DoxyCodeLine{\textcolor{keywordflow}{try}\ \{}
\DoxyCodeLine{\ \ result\ =\ DescribeMyEffect1(\ effect1Descriptor\ );}
\DoxyCodeLine{\ \ result\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ myEffect1ID,\ effect1Descriptor\ );}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keywordflow}{catch}\ (\textcolor{keyword}{const}\ \mbox{\hyperlink{a01986}{AAX\_CheckedResult::Exception}}\&\ ex)\ \{}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ log\ the\ error\ using\ ex.What()}}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ swallow\ the\ exception\ and\ proceed}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ effect\ 2\ registration}}
\DoxyCodeLine{\textcolor{keywordflow}{try}\ \{}
\DoxyCodeLine{\ \ result\ =\ DescribeMyEffect2(\ effect2Descriptor\ );}
\DoxyCodeLine{\ \ result\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ myEffect2ID,\ effect2Descriptor\ );}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keywordflow}{catch}\ (\textcolor{keyword}{const}\ \mbox{\hyperlink{a01986}{AAX\_CheckedResult::Exception}}\&\ ex)\ \{}
\DoxyCodeLine{\ \ \textcolor{comment}{//\ ditto}}
\DoxyCodeLine{\}}

\end{DoxyCode}
 Example of error handling with try/catch

 This solves the problem fully, but it is still cumbersome -\/ especially when registering a long list of separate Process\+Proc variants!

 The \mbox{\hyperlink{a00620_aef6db72a3774d079609f94720928cdd6}{AAX\+\_\+\+SWALLOW\+\_\+\+MULT}} macro makes it easier to handle errors which are thrown by \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} \+:

 
\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{a01990}{AAX\_CheckedResult}}\ result\ =\ \mbox{\hyperlink{a00539_a5f8c7439f3a706c4f8315a9609811937aeddbd1bb67e3a66e6af54a4b4a7a57b3}{AAX\_SUCCESS}};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ effect\ 1\ registration}}
\DoxyCodeLine{\mbox{\hyperlink{a00620_aef6db72a3774d079609f94720928cdd6}{AAX\_SWALLOW\_MULT}}\ (}
\DoxyCodeLine{\ \ result\ =\ DescribeMyEffect1(\ effect1Descriptor\ );}
\DoxyCodeLine{\ \ result\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ myEffect1ID,\ effect1Descriptor\ );}
\DoxyCodeLine{);}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{//\ effect\ 2\ registration}}
\DoxyCodeLine{\mbox{\hyperlink{a00620_aef6db72a3774d079609f94720928cdd6}{AAX\_SWALLOW\_MULT}}\ (}
\DoxyCodeLine{\ \ result\ =\ DescribeMyEffect2(\ effect2Descriptor\ );}
\DoxyCodeLine{\ \ result\ =\ outCollection-\/>\mbox{\hyperlink{a02210_a5ff114b8c4da2081515186f2faf65c8c}{AddEffect}}(\ myEffect2ID,\ effect2Descriptor\ );}
\DoxyCodeLine{);}

\end{DoxyCode}
 Example of error handling with \mbox{\hyperlink{a00620_aef6db72a3774d079609f94720928cdd6}{AAX\+\_\+\+SWALLOW\+\_\+\+MULT}}

 {\itshape Variations}
\begin{DoxyItemize}
\item For single-\/line try/catch there is also \mbox{\hyperlink{a00620_a8f177823e9388c5163d1b402a9069bce}{AAX\+\_\+\+SWALLOW}}.
\item If you need to reference the error value after the exception is caught, use \mbox{\hyperlink{a00620_a078be92d3d19a5a4b3da2b55ae5ac1c9}{AAX\+\_\+\+CAPTURE\+\_\+\+MULT}} (multi-\/line) or \mbox{\hyperlink{a00620_af9972551e4546e894010f99eade68c94}{AAX\+\_\+\+CAPTURE}} (single-\/line)
\item If you know that a certain error code is OK and should not throw in a given situation then you can add it as an exception to the \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} object with \mbox{\hyperlink{a01990_af6c4b10c55e959f5f8424514a3cbb68a}{AAX\+\_\+\+Checked\+Result\+::\+Add\+Accepted\+Result()}}.
\end{DoxyItemize}

 For examples of \mbox{\hyperlink{a01990}{AAX\+\_\+\+Checked\+Result}} in use, see the \mbox{\hyperlink{a00944_DemoGain_Multichannel}{Demo\+Gain\+\_\+\+Multichannel}} and \mbox{\hyperlink{a00944_DemoGain_UpMixer}{Demo\+Gain\+\_\+\+Up\+Mixer}} plug-\/ins



 \hypertarget{a00889_describe_validation}{}\doxysubsection{Describe Validation}\label{a00889_describe_validation}
\hypertarget{a00889_describe_validation_dsh}{}\doxysubsubsection{Validation with DSH}\label{a00889_describe_validation_dsh}
 You can validate your plug-\/in\textquotesingle{}s Describe routine using the \mbox{\hyperlink{a00931}{Digi\+Shell}} command-\/line tool. The validation command is available directly in the aaxh dish and is also available through an AAX Validator test module\+:

 {\itshape aaxh dish} \begin{DoxyVerb}dsh> load_dish aaxh
dsh> loadpi "/quoted/path/without escape chars/MyPlugIn.aaxplugin"
dsh> getdescriptionvalidationinfo 0\end{DoxyVerb}


 {\itshape AAX Validator} \begin{DoxyVerb}dsh> load_dish aaxval
dsh> runtest [test.describe_validation, "/quoted/path/without escape chars/MyPlugIn.aaxplugin"]\end{DoxyVerb}


\hypertarget{a00889_describe_validation_protools}{}\doxysubsubsection{Validation with Pro Tools}\label{a00889_describe_validation_protools}
 Beginning in Pro Tools 12.\+8.\+2, developer builds of Pro Tools will also check plug-\/in describe routines and will present an alert dialog when the plug-\/in is scanned if any aspect of the plug-\/in\textquotesingle{}s describe code has failed the validation step.

   Describe validation warning in a Pro Tools developer build

 The specific kinds of errors which were encountered will be printed to the \mbox{\hyperlink{a00930}{Digi\+Trace}} log file\+:

 \begin{DoxyVerb}13033.502646,00307,0073: ERROR: Unknown target host for the plug-in.
13033.502662,00307,0073: ERROR: PlugInID property is missing for a ProcessProc (process, initialization, or background function).
13033.502734,00307,0e0f: CMN_TRACEASSERT  Sandbox.aaxplugin configuration contains 2 errors. See the DigiTrace log or run the AAX Validator for more info. (0 == numErrors)\end{DoxyVerb}


 This check may be suppressed using the following \mbox{\hyperlink{a00926_aax_pro_tools_guide__digioptions}{Digi\+Option}}\+:

 {\ttfamily Test\+Plug\+In\+Descriptions 0}



 \hypertarget{a00889_describe_additionaltopics}{}\doxysubsection{Additional Topics}\label{a00889_describe_additionaltopics}
 \begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{a00902}{Plug-\/in meters}}
\end{DoxySeeAlso}
 \doxysubsection*{Classes}
\begin{DoxyCompactItemize}
\item 
class \mbox{\hyperlink{a02210}{AAX\+\_\+\+ICollection}}
\begin{DoxyCompactList}\small\item\em Interface to represent a plug-\/in binary\textquotesingle{}s static description. \end{DoxyCompactList}\item 
class \mbox{\hyperlink{a02214}{AAX\+\_\+\+IComponent\+Descriptor}}
\begin{DoxyCompactList}\small\item\em Description interface for an AAX plug-\/in component. \end{DoxyCompactList}\item 
class \mbox{\hyperlink{a02254}{AAX\+\_\+\+IEffect\+Descriptor}}
\begin{DoxyCompactList}\small\item\em Description interface for an effect\textquotesingle{}s (plug-\/in type\textquotesingle{}s) components. \end{DoxyCompactList}\item 
class \mbox{\hyperlink{a02314}{AAX\+\_\+\+IProperty\+Map}}
\begin{DoxyCompactList}\small\item\em Generic plug-\/in description property map. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
\mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} \mbox{\hyperlink{a00889_ga83d05333118598c179ca6d89487fa203}{AAXRegister\+Plugin}} (\mbox{\hyperlink{a01770}{IACFUnknown}} $\ast$p\+Unk\+Host, IACFPlugin\+Definition $\ast$$\ast$pp\+Plugin\+Definition)
\begin{DoxyCompactList}\small\item\em The main plug-\/in registration method.   \end{DoxyCompactList}\item 
\mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} \mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{Get\+Effect\+Descriptions}} (\mbox{\hyperlink{a02210}{AAX\+\_\+\+ICollection}} $\ast$in\+Collection)
\begin{DoxyCompactList}\small\item\em The plug-\/in\textquotesingle{}s static Description entrypoint. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Function Documentation}
\mbox{\Hypertarget{a00889_ga83d05333118598c179ca6d89487fa203}\label{a00889_ga83d05333118598c179ca6d89487fa203}} 
\index{Description callback@{Description callback}!AAXRegisterPlugin@{AAXRegisterPlugin}}
\index{AAXRegisterPlugin@{AAXRegisterPlugin}!Description callback@{Description callback}}
\doxysubsubsection{\texorpdfstring{AAXRegisterPlugin()}{AAXRegisterPlugin()}}
{\footnotesize\ttfamily \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} AAXRegister\+Plugin (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{a01770}{IACFUnknown}} $\ast$}]{p\+Unk\+Host,  }\item[{IACFPlugin\+Definition $\ast$$\ast$}]{pp\+Plugin\+Definition }\end{DoxyParamCaption})}



The main plug-\/in registration method.   

This method determines the number of components defined in the dll. The implementation of this method in the AAX library calls the following function, which must be implemented somewhere in your plug-\/in\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{extern}\ \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \mbox{\hyperlink{a00889_gae0d356eef326f77cbb972e48946d4892}{GetEffectDescriptions}}(\ \mbox{\hyperlink{a02210}{AAX\_ICollection}}\ *\ outCollection\ );}

\end{DoxyCode}


{\itshape Wrapped by \mbox{\hyperlink{a00545_aa455fa4d9a2236334d0fd959b4919788}{ACFRegister\+Plugin()}} } 

Referenced by \mbox{\hyperlink{a00545_aa455fa4d9a2236334d0fd959b4919788}{ACFRegister\+Plugin()}}.

Here is the caller graph for this function\+:
% FIG 0
\mbox{\Hypertarget{a00889_gae0d356eef326f77cbb972e48946d4892}\label{a00889_gae0d356eef326f77cbb972e48946d4892}} 
\index{Description callback@{Description callback}!GetEffectDescriptions@{GetEffectDescriptions}}
\index{GetEffectDescriptions@{GetEffectDescriptions}!Description callback@{Description callback}}
\doxysubsubsection{\texorpdfstring{GetEffectDescriptions()}{GetEffectDescriptions()}}
{\footnotesize\ttfamily \mbox{\hyperlink{a00542_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\+\_\+\+Result}} Get\+Effect\+Descriptions (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{a02210}{AAX\+\_\+\+ICollection}} $\ast$}]{in\+Collection }\end{DoxyParamCaption})}



The plug-\/in\textquotesingle{}s static Description entrypoint. 

This function is responsible for describing an AAX plug-\/in to the host. It does this by populating an \mbox{\hyperlink{a02210}{AAX\+\_\+\+ICollection}} interface.

This function must be included in every plug-\/in that links to the AAX library. It is called when the host first loads the plug-\/in.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ out}}  & {\em in\+Collection} & \\
\hline
\end{DoxyParams}
Collaboration diagram for Description callback\+:
% FIG 1
