![]() |
AAX SDK
2.4.1
Avid Audio Extensions Development Kit
|
#include <AAX_IComponentDescriptor.h>
Description interface for an AAX plug-in component.
This is an abstract interface containing everything needed to describe a single algorithm of an Effect. For more information about algorithm processing in AAX plug-ins, see Real-time algorithm callback.
Public Member Functions | |
virtual | ~AAX_IComponentDescriptor () |
virtual AAX_Result | Clear ()=0 |
Clears the descriptor. More... | |
virtual AAX_Result | AddAudioIn (AAX_CFieldIndex inFieldIndex)=0 |
Subscribes an audio input context field. More... | |
virtual AAX_Result | AddAudioOut (AAX_CFieldIndex inFieldIndex)=0 |
Subscribes an audio output context field. More... | |
virtual AAX_Result | AddAudioBufferLength (AAX_CFieldIndex inFieldIndex)=0 |
Subscribes a buffer length context field. More... | |
virtual AAX_Result | AddSampleRate (AAX_CFieldIndex inFieldIndex)=0 |
Subscribes a sample rate context field. More... | |
virtual AAX_Result | AddClock (AAX_CFieldIndex inFieldIndex)=0 |
Subscribes a clock context field. More... | |
virtual AAX_Result | AddSideChainIn (AAX_CFieldIndex inFieldIndex)=0 |
Subscribes a side-chain input context field. More... | |
virtual AAX_Result | AddDataInPort (AAX_CFieldIndex inFieldIndex, uint32_t inPacketSize, AAX_EDataInPortType inPortType=AAX_eDataInPortType_Buffered)=0 |
Adds a custom data port to the algorithm context. More... | |
virtual AAX_Result | AddAuxOutputStem (AAX_CFieldIndex inFieldIndex, int32_t inStemFormat, const char inNameUTF8[])=0 |
Adds an auxiliary output stem for a plug-in. More... | |
virtual AAX_Result | AddPrivateData (AAX_CFieldIndex inFieldIndex, int32_t inDataSize, uint32_t inOptions=AAX_ePrivateDataOptions_DefaultOptions)=0 |
Adds a private data port to the algorithm context. More... | |
virtual AAX_Result | AddTemporaryData (AAX_CFieldIndex inFieldIndex, uint32_t inDataElementSize)=0 |
Adds a block of data to a context that is not saved between callbacks and is scaled by the system buffer size. More... | |
virtual AAX_Result | AddDmaInstance (AAX_CFieldIndex inFieldIndex, AAX_IDma::EMode inDmaMode)=0 |
Adds a DMA field to the plug-in's context. More... | |
virtual AAX_Result | AddMeters (AAX_CFieldIndex inFieldIndex, const AAX_CTypeID *inMeterIDs, const uint32_t inMeterCount)=0 |
Adds a meter field to the plug-in's context. More... | |
virtual AAX_Result | AddMIDINode (AAX_CFieldIndex inFieldIndex, AAX_EMIDINodeType inNodeType, const char inNodeName[], uint32_t channelMask)=0 |
Adds a MIDI node field to the plug-in's context. More... | |
virtual AAX_Result | AddReservedField (AAX_CFieldIndex inFieldIndex, uint32_t inFieldType)=0 |
Subscribes a context field to host-provided services or information. More... | |
virtual AAX_IPropertyMap * | NewPropertyMap () const =0 |
Creates a new, empty property map. More... | |
virtual AAX_IPropertyMap * | DuplicatePropertyMap (AAX_IPropertyMap *inPropertyMap) const =0 |
Creates a new property map using an existing property map. More... | |
virtual AAX_Result | AddProcessProc_Native (AAX_CProcessProc inProcessProc, AAX_IPropertyMap *inProperties=NULL, AAX_CInstanceInitProc inInstanceInitProc=NULL, AAX_CBackgroundProc inBackgroundProc=NULL, AAX_CSelector *outProcID=NULL)=0 |
Registers an algorithm processing entrypoint (process procedure) for the native architecture. More... | |
virtual AAX_Result | AddProcessProc_TI (const char inDLLFileNameUTF8[], const char inProcessProcSymbol[], AAX_IPropertyMap *inProperties, const char inInstanceInitProcSymbol[]=NULL, const char inBackgroundProcSymbol[]=NULL, AAX_CSelector *outProcID=NULL)=0 |
Registers an algorithm processing entrypoint (process procedure) for the native architecture. More... | |
virtual AAX_Result | AddProcessProc (AAX_IPropertyMap *inProperties, AAX_CSelector *outProcIDs=NULL, int32_t inProcIDsSize=0)=0 |
Registers one or more algorithm processing entrypoints (process procedures) More... | |
template<typename aContextType > | |
AAX_Result | AddProcessProc_Native (void(AAX_CALLBACK *inProcessProc)(aContextType *const inInstancesBegin[], const void *inInstancesEnd), AAX_IPropertyMap *inProperties=NULL, int32_t(AAX_CALLBACK *inInstanceInitProc)(const aContextType *inInstanceContextPtr, AAX_EComponentInstanceInitAction inAction)=NULL, int32_t(AAX_CALLBACK *inBackgroundProc)(void)=NULL) |
Registers an algorithm processing entrypoint (process procedure) for the native architecture. More... | |
|
inlinevirtual |
|
pure virtual |
Clears the descriptor.
Clears the descriptor and readies it for the next algorithm description
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Subscribes an audio input context field.
Defines an audio in port for host-provided information in the algorithm's context structure.
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Subscribes an audio output context field.
Defines an audio out port for host-provided information in the algorithm's context structure.
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Subscribes a buffer length context field.
Defines a buffer length port for host-provided information in the algorithm's context structure.
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Subscribes a sample rate context field.
Defines a sample rate port for host-provided information in the algorithm's context structure.
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Subscribes a clock context field.
Defines a clock port for host-provided information in the algorithm's context structure.
Data kind: A running counter which increments even when the transport is not playing. The counter increments exactly once per sample quantum.
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Subscribes a side-chain input context field.
Defines a side-chain input port for host-provided information in the algorithm's context structure.
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Adds a custom data port to the algorithm context.
Defines a read-only data port for plug-in information in the algorithm's context structure. The plug-in can send information to this port using AAX_IController::PostPacket().
The host guarantees that all packets will be delivered to this port in the order in which they were posted, up to the point of a packet buffer overflow, though some packets may be dropped depending on the inPortType
and host implementation.
[in] | inFieldIndex | Unique identifier for the port, generated using AAX_FIELD_INDEX |
[in] | inPacketSize | Size of the data packets that will be sent to this port |
[in] | inPortType | The requested packet delivery behavior for this port |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Adds an auxiliary output stem for a plug-in.
Use this method to add additional output channels to the algorithm context.
The aux output stem audio buffers will be added to the end of the audio outputs array in the order in which they are described. When writing audio data to a specific aux output, find the proper starting channel by accumulating all of the channels of the main output stem format and any previously-described aux output stems.
The plug-in is responsible for providing a meaningful name for each aux outputs. At the very least, individual outputs should be labeled "Output xx", where "xx" is the aux output number as it is defined in the plug-in. The output name should also include the words "mono" and "stereo" to support when users are looking for an output with a specific stem format.
[in] | inFieldIndex | DEPRECATED: This parameter is no longer needed by the host, but is included in the interface for binary compatibility |
[in] | inStemFormat | The stem format of the new aux output |
[in] | inNameUTF8 | The name of the aux output. This name is static and cannot be changed after the descriptor is submitted to the host |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Adds a private data port to the algorithm context.
Defines a read/write data port for private state data. Data written to this port will be maintained by the host between calls to the algorithm context.
[in] | inFieldIndex | Unique identifier for the port, generated using AAX_FIELD_INDEX |
[in] | inDataSize | Size of the data packets that will be sent to this port |
[in] | inOptions | Options that define the private data port's behavior |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Adds a block of data to a context that is not saved between callbacks and is scaled by the system buffer size.
This can be very useful if you use block processing and need to store intermediate results. Just specify your base element size and the system will scale the overall block size by the buffer size. For example, to create a buffer of floats that is the length of the block, specify 4 bytes as the elementsize.
This data block does not retain state across callback and can also be reused across instances on memory contrained systems.
[in] | inFieldIndex | Unique identifier for the port, generated using AAX_FIELD_INDEX |
[in] | inDataElementSize | The size of a single piece of data in the block. This number will be multipied by the processing block size to determine total block size. |
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Adds a DMA field to the plug-in's context.
DMA (direct memory access) provides efficient reads from and writes to external memory on the DSP. DMA behavior is emulated in host-based plug-ins for cross-platform portability.
For more information, see Direct Memory Access .
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
[in] | inDmaMode | AAX_IDma::EMode that will apply to this field |
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Adds a meter field to the plug-in's context.
Meter fields include an array of meter tap values, with one tap per meter per context. Only one meter field should be added per Component. Individual meter behaviors can be described at the Effect level.
For more information, see Plug-in meters .
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
[in] | inMeterIDs | Array of 32-bit IDs, one for each meter. Meter IDs must be unique within the Effect. |
[in] | inMeterCount | The number of meters included in this field |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Adds a MIDI node field to the plug-in's context.
The resulting MIDI node data will be available both in the algorithm context and in the plug-in's data model via UpdateMIDINodes().
To add a MIDI node that is only accessible to the plug-in's data model, use AAX_IEffectDescriptor::AddControlMIDINode()
[in] | inFieldIndex | The ID of the port. MIDI node ports should formatted as a pointer to an AAX_IMIDINode. |
[in] | inNodeType | The type of MIDI node, as AAX_EMIDINodeType |
[in] | inNodeName | The name of the MIDI node as it should appear in the host's UI |
[in] | channelMask | The channel mask for the MIDI node. This parameter specifies used MIDI channels. For Global MIDI nodes, use a mask of AAX_EMidiGlobalNodeSelectors |
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Subscribes a context field to host-provided services or information.
[in] | inFieldIndex | Unique identifier for the field, generated using AAX_FIELD_INDEX |
[in] | inFieldType | Type of field that is being added |
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Creates a new, empty property map.
The component descriptor owns the reference to the resulting property map, and the underlying property map is destroyed when the component descriptor is released.
Implemented in AAX_VComponentDescriptor.
Referenced by AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Creates a new property map using an existing property map.
The component descriptor owns the reference to the resulting property map, and the underlying property map is destroyed when the component descriptor is released.
[in] | inPropertyMap | The property values in this map will be copied into the new map |
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Registers an algorithm processing entrypoint (process procedure) for the native architecture.
[in] | inProcessProc | Symbol for this processing callback |
[in] | inProperties | A property map for this processing callback. The property map's values are copied by the host and associated with the new ProcessProc. The property map contents are unchanged and the map may be re-used when registering additional ProcessProcs. |
[in] | inInstanceInitProc | Initialization routine that will be called when a new instance of the Effect is created. See Algorithm initialization. |
[in] | inBackgroundProc | Background routine that will be called in an idle context within the same address space as the associated process procedure. See Background processing callback |
[out] | outProcID |
Implemented in AAX_VComponentDescriptor.
Referenced by AddProcessProc_Native(), and AAX_CMonolithicParameters::StaticDescribe().
|
pure virtual |
Registers an algorithm processing entrypoint (process procedure) for the native architecture.
[in] | inDLLFileNameUTF8 | UTF-8 encoded filename for the ELF DLL containing the algorithm code fragment |
[in] | inProcessProcSymbol | Symbol for this processing callback |
[in] | inProperties | A property map for this processing callback. The property map's values are copied by the host and associated with the new ProcessProc. The property map contents are unchanged and the map may be re-used when registering additional ProcessProcs. |
[in] | inInstanceInitProcSymbol | Initialization routine that will be called when a new instance of the Effect is created. Must be included in the same DLL as the main algorithm entrypoint. See Algorithm initialization. |
[in] | inBackgroundProcSymbol | Background routine that will be called in an idle context within the same address space as the associated process procedure. Must be included in the same DLL as the main algorithm entrypoint. See Background processing callback |
[out] | outProcID |
Implemented in AAX_VComponentDescriptor.
|
pure virtual |
Registers one or more algorithm processing entrypoints (process procedures)
Any non-overlapping set of processing entrypoints may be specified. Typically this can be used to specify both Native and TI entrypoints using the same call.
The AAX Library implementation of this method includes backwards compatibility logic to complete the ProcessProc registration on hosts which do not support this method. Therefore plug-in code may use this single registration routine instead of separate calls to AddProcessProc_Native(), AddProcessProc_TI(), etc. regardless of the host version.
The following properties replace the input arguments to the platform-specific registration methods:
AddProcessProc_Native() (AAX_eProperty_PlugInID_Native, AAX_eProperty_PlugInID_AudioSuite)
iProcessProc:
AAX_eProperty_NativeProcessProc (required)iInstanceInitProc:
AAX_eProperty_NativeInstanceInitProc (optional)iBackgroundProc:
AAX_eProperty_NativeBackgroundProc (optional)AddProcessProc_TI() (AAX_eProperty_PlugInID_TI)
const char inDLLFileNameUTF8[]
: AAX_eProperty_TIDLLFileName (required)const char iProcessProcSymbol[]
: AAX_eProperty_TIProcessProc (required)const char iInstanceInitProcSymbol[]
: AAX_eProperty_TIInstanceInitProc (optional)const char iBackgroundProcSymbol[]
: AAX_eProperty_TIBackgroundProc (optional)If any platform-specific plug-in ID property is present in iProperties
then AddProcessProc() will check for the required properties for that platform.
[in] | inProperties | A property map for this processing callback. The property map's values are copied by the host and associated with the new ProcessProc. The property map contents are unchanged and the map may be re-used when registering additional ProcessProcs. |
[out] | outProcIDs |
[in] | inProcIDsSize | The size of the array provided to oProcIDs . If oProcIDs is non-NULL but iProcIDsSize is not large enough for all of the registered ProcessProcs (plus one for NULL termination) then this method will fail with AAX_ERROR_ARGUMENT_BUFFER_OVERFLOW |
Implemented in AAX_VComponentDescriptor.
|
inline |
Registers an algorithm processing entrypoint (process procedure) for the native architecture.
This template provides an AAX_CALLBACK based interface to the AddProcessProc_Native method.
[in] | inProperties | A property map for this processing callback. The property map's values are copied by the host and associated with the new ProcessProc. The property map contents are unchanged and the map may be re-used when registering additional ProcessProcs. |
References AddProcessProc_Native().