AAX SDK  2.4.1
Avid Audio Extensions Development Kit
List of all members | Public Member Functions | Friends
AAX_VComponentDescriptor Class Reference

#include <AAX_VComponentDescriptor.h>

Inheritance diagram for AAX_VComponentDescriptor:
[legend]
Collaboration diagram for AAX_VComponentDescriptor:
[legend]

Description

Version-managed concrete AAX_IComponentDescriptor class.

Public Member Functions

 AAX_VComponentDescriptor (IACFUnknown *pUnkHost)
 
 ~AAX_VComponentDescriptor () AAX_OVERRIDE
 
AAX_Result Clear () AAX_OVERRIDE
 Clears the descriptor. More...
 
AAX_Result AddReservedField (AAX_CFieldIndex inFieldIndex, uint32_t inFieldType) AAX_OVERRIDE
 Subscribes a context field to host-provided services or information. More...
 
AAX_Result AddAudioIn (AAX_CFieldIndex inFieldIndex) AAX_OVERRIDE
 Subscribes an audio input context field. More...
 
AAX_Result AddAudioOut (AAX_CFieldIndex inFieldIndex) AAX_OVERRIDE
 Subscribes an audio output context field. More...
 
AAX_Result AddAudioBufferLength (AAX_CFieldIndex inFieldIndex) AAX_OVERRIDE
 Subscribes a buffer length context field. More...
 
AAX_Result AddSampleRate (AAX_CFieldIndex inFieldIndex) AAX_OVERRIDE
 Subscribes a sample rate context field. More...
 
AAX_Result AddClock (AAX_CFieldIndex inFieldIndex) AAX_OVERRIDE
 Subscribes a clock context field. More...
 
AAX_Result AddSideChainIn (AAX_CFieldIndex inFieldIndex) AAX_OVERRIDE
 Subscribes a side-chain input context field. More...
 
AAX_Result AddDataInPort (AAX_CFieldIndex inFieldIndex, uint32_t inPacketSize, AAX_EDataInPortType inPortType) AAX_OVERRIDE
 Adds a custom data port to the algorithm context. More...
 
AAX_Result AddAuxOutputStem (AAX_CFieldIndex inFieldIndex, int32_t inStemFormat, const char inNameUTF8[]) AAX_OVERRIDE
 Adds an auxiliary output stem for a plug-in. More...
 
AAX_Result AddPrivateData (AAX_CFieldIndex inFieldIndex, int32_t inDataSize, uint32_t inOptions) AAX_OVERRIDE
 Adds a private data port to the algorithm context. More...
 
AAX_Result AddTemporaryData (AAX_CFieldIndex inFieldIndex, uint32_t inDataElementSize) AAX_OVERRIDE
 Adds a block of data to a context that is not saved between callbacks and is scaled by the system buffer size. More...
 
AAX_Result AddDmaInstance (AAX_CFieldIndex inFieldIndex, AAX_IDma::EMode inDmaMode) AAX_OVERRIDE
 Adds a DMA field to the plug-in's context. More...
 
AAX_Result AddMeters (AAX_CFieldIndex inFieldIndex, const AAX_CTypeID *inMeterIDs, const uint32_t inMeterCount) AAX_OVERRIDE
 Adds a meter field to the plug-in's context. More...
 
AAX_Result AddMIDINode (AAX_CFieldIndex inFieldIndex, AAX_EMIDINodeType inNodeType, const char inNodeName[], uint32_t channelMask) AAX_OVERRIDE
 Adds a MIDI node field to the plug-in's context. More...
 
AAX_IPropertyMapNewPropertyMap () const AAX_OVERRIDE
 Creates a new, empty property map. More...
 
AAX_IPropertyMapDuplicatePropertyMap (AAX_IPropertyMap *inPropertyMap) const AAX_OVERRIDE
 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) AAX_OVERRIDE
 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=NULL, const char inInstanceInitProcSymbol[]=NULL, const char inBackgroundProcSymbol[]=NULL, AAX_CSelector *outProcID=NULL) AAX_OVERRIDE
 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) AAX_OVERRIDE
 Registers one or more algorithm processing entrypoints (process procedures) More...
 
IACFUnknownGetIUnknown (void) const
 
- Public Member Functions inherited from AAX_IComponentDescriptor
virtual ~AAX_IComponentDescriptor ()
 
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...
 

Friends

class AAX_VPropertyMap
 

Constructor & Destructor Documentation

◆ AAX_VComponentDescriptor()

AAX_VComponentDescriptor::AAX_VComponentDescriptor ( IACFUnknown pUnkHost)

◆ ~AAX_VComponentDescriptor()

AAX_VComponentDescriptor::~AAX_VComponentDescriptor ( )

Member Function Documentation

◆ Clear()

AAX_Result AAX_VComponentDescriptor::Clear ( )
virtual

Clears the descriptor.

Clears the descriptor and readies it for the next algorithm description

Implements AAX_IComponentDescriptor.

◆ AddReservedField()

AAX_Result AAX_VComponentDescriptor::AddReservedField ( AAX_CFieldIndex  inFieldIndex,
uint32_t  inFieldType 
)
virtual

Subscribes a context field to host-provided services or information.

Note
Currently for internal use only.
Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX
[in]inFieldTypeType of field that is being added

Implements AAX_IComponentDescriptor.

◆ AddAudioIn()

AAX_Result AAX_VComponentDescriptor::AddAudioIn ( AAX_CFieldIndex  inFieldIndex)
virtual

Subscribes an audio input context field.

Defines an audio in port for host-provided information in the algorithm's context structure.

  • Data type: float**
  • Data kind: An array of float arrays, one for each input channel
Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX

Implements AAX_IComponentDescriptor.

◆ AddAudioOut()

AAX_Result AAX_VComponentDescriptor::AddAudioOut ( AAX_CFieldIndex  inFieldIndex)
virtual

Subscribes an audio output context field.

Defines an audio out port for host-provided information in the algorithm's context structure.

  • Data type: float**
  • Data kind: An array of float arrays, one for each output channel
Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX

Implements AAX_IComponentDescriptor.

◆ AddAudioBufferLength()

AAX_Result AAX_VComponentDescriptor::AddAudioBufferLength ( AAX_CFieldIndex  inFieldIndex)
virtual

Subscribes a buffer length context field.

Defines a buffer length port for host-provided information in the algorithm's context structure.

  • Data type: int32_t*
  • Data kind: The number of samples in the current audio buffer
Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX

Implements AAX_IComponentDescriptor.

◆ AddSampleRate()

AAX_Result AAX_VComponentDescriptor::AddSampleRate ( AAX_CFieldIndex  inFieldIndex)
virtual

Subscribes a sample rate context field.

Defines a sample rate port for host-provided information in the algorithm's context structure.

Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX

Implements AAX_IComponentDescriptor.

◆ AddClock()

AAX_Result AAX_VComponentDescriptor::AddClock ( AAX_CFieldIndex  inFieldIndex)
virtual

Subscribes a clock context field.

Defines a clock port for host-provided information in the algorithm's context structure.

  • Data type: AAX_CTimestamp *
  • Data kind: A running counter which increments even when the transport is not playing. The counter increments exactly once per sample quantum.

    Host Compatibility Notes:
    As of Pro Tools 11.1, this field may be used in both Native and DSP plug-ins. The DSP clock data is a 16-bit cycling counter. This field was only available for Native plug-ins in previous Pro Tools versions.
Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX

Implements AAX_IComponentDescriptor.

◆ AddSideChainIn()

AAX_Result AAX_VComponentDescriptor::AddSideChainIn ( AAX_CFieldIndex  inFieldIndex)
virtual

Subscribes a side-chain input context field.

Defines a side-chain input port for host-provided information in the algorithm's context structure.

  • Data type: int32_t*
  • Data kind: The index of the plug-in's first side-chain input channel within the array of input audio buffers
Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX

Implements AAX_IComponentDescriptor.

◆ AddDataInPort()

AAX_Result AAX_VComponentDescriptor::AddDataInPort ( AAX_CFieldIndex  inFieldIndex,
uint32_t  inPacketSize,
AAX_EDataInPortType  inPortType 
)
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.

Note
When a plug-in is operating in offline (AudioSuite) mode, all data ports operate as AAX_eDataInPortType_Unbuffered ports
Parameters
[in]inFieldIndexUnique identifier for the port, generated using AAX_FIELD_INDEX
[in]inPacketSizeSize of the data packets that will be sent to this port
[in]inPortTypeThe requested packet delivery behavior for this port

Implements AAX_IComponentDescriptor.

◆ AddAuxOutputStem()

AAX_Result AAX_VComponentDescriptor::AddAuxOutputStem ( AAX_CFieldIndex  inFieldIndex,
int32_t  inStemFormat,
const char  inNameUTF8[] 
)
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.

Host Compatibility Notes:
There is a hard limit to the number of outputs that Pro Tools supports for a single plug-in instance. This limit is currently set at 256 channels, which includes all of the plug-in's output channels in addition to the sum total of all of its aux output stem channels.
Host Compatibility Notes:
Pro Tools supports only mono and stereo auxiliary output stem formats
Warning
This method will return an error code on hosts which do not support auxiliary output stems. This indicates that the host will not provide audio buffers for auxiliary output stems during processing. A plug-in must not attempt to write data into auxiliary output stem buffers which have not been provided by the host!
Parameters
[in]inFieldIndexDEPRECATED: This parameter is no longer needed by the host, but is included in the interface for binary compatibility
[in]inStemFormatThe stem format of the new aux output
[in]inNameUTF8The name of the aux output. This name is static and cannot be changed after the descriptor is submitted to the host

Implements AAX_IComponentDescriptor.

◆ AddPrivateData()

AAX_Result AAX_VComponentDescriptor::AddPrivateData ( AAX_CFieldIndex  inFieldIndex,
int32_t  inDataSize,
uint32_t  inOptions 
)
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.

See also
alg_pd_registration
Parameters
[in]inFieldIndexUnique identifier for the port, generated using AAX_FIELD_INDEX
[in]inDataSizeSize of the data packets that will be sent to this port
[in]inOptionsOptions that define the private data port's behavior

Implements AAX_IComponentDescriptor.

◆ AddTemporaryData()

AAX_Result AAX_VComponentDescriptor::AddTemporaryData ( AAX_CFieldIndex  inFieldIndex,
uint32_t  inDataElementSize 
)
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.

Parameters
[in]inFieldIndexUnique identifier for the port, generated using AAX_FIELD_INDEX
[in]inDataElementSizeThe 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.

Implements AAX_IComponentDescriptor.

◆ AddDmaInstance()

AAX_Result AAX_VComponentDescriptor::AddDmaInstance ( AAX_CFieldIndex  inFieldIndex,
AAX_IDma::EMode  inDmaMode 
)
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.

Note
The order in which DMA instances are added defines their priority and therefore order of execution of DMA operations. In most plug-ins, Scatter fields should be placed first in order to achieve the lowest possible access latency.

For more information, see Direct Memory Access .

Todo:
Update the DMA system management such that operation priority can be set arbitrarily
Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX
[in]inDmaModeAAX_IDma::EMode that will apply to this field

Implements AAX_IComponentDescriptor.

◆ AddMeters()

AAX_Result AAX_VComponentDescriptor::AddMeters ( AAX_CFieldIndex  inFieldIndex,
const AAX_CTypeID inMeterIDs,
const uint32_t  inMeterCount 
)
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 .

Parameters
[in]inFieldIndexUnique identifier for the field, generated using AAX_FIELD_INDEX
[in]inMeterIDsArray of 32-bit IDs, one for each meter. Meter IDs must be unique within the Effect.
[in]inMeterCountThe number of meters included in this field

Implements AAX_IComponentDescriptor.

◆ AddMIDINode()

AAX_Result AAX_VComponentDescriptor::AddMIDINode ( AAX_CFieldIndex  inFieldIndex,
AAX_EMIDINodeType  inNodeType,
const char  inNodeName[],
uint32_t  channelMask 
)
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()

Host Compatibility Notes:
Due to current restrictions MIDI data won't be delivered to DSP algorithms, only to AAX Native.
Parameters
[in]inFieldIndexThe ID of the port. MIDI node ports should formatted as a pointer to an AAX_IMIDINode.
[in]inNodeTypeThe type of MIDI node, as AAX_EMIDINodeType
[in]inNodeNameThe name of the MIDI node as it should appear in the host's UI
[in]channelMaskThe channel mask for the MIDI node. This parameter specifies used MIDI channels. For Global MIDI nodes, use a mask of AAX_EMidiGlobalNodeSelectors

Implements AAX_IComponentDescriptor.

◆ NewPropertyMap()

AAX_IPropertyMap* AAX_VComponentDescriptor::NewPropertyMap ( ) const
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.

This implementation retains each generated AAX_IPropertyMap and destroys the property map upon AAX_VComponentDescriptor destruction

Implements AAX_IComponentDescriptor.

◆ DuplicatePropertyMap()

AAX_IPropertyMap* AAX_VComponentDescriptor::DuplicatePropertyMap ( AAX_IPropertyMap inPropertyMap) const
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.

Parameters
[in]inPropertyMapThe property values in this map will be copied into the new map

This implementation retains each generated AAX_IPropertyMap and destroys the property map upon AAX_VComponentDescriptor destruction

Implements AAX_IComponentDescriptor.

◆ AddProcessProc_Native()

virtual AAX_Result AAX_VComponentDescriptor::AddProcessProc_Native ( AAX_CProcessProc  inProcessProc,
AAX_IPropertyMap inProperties = NULL,
AAX_CInstanceInitProc  inInstanceInitProc = NULL,
AAX_CBackgroundProc  inBackgroundProc = NULL,
AAX_CSelector outProcID = NULL 
)
virtual

Registers an algorithm processing entrypoint (process procedure) for the native architecture.

Parameters
[in]inProcessProcSymbol for this processing callback
[in]inPropertiesA 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]inInstanceInitProcInitialization routine that will be called when a new instance of the Effect is created. See Algorithm initialization.
[in]inBackgroundProcBackground 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
Todo:
document this parameter

Implements AAX_IComponentDescriptor.

◆ AddProcessProc_TI()

virtual AAX_Result AAX_VComponentDescriptor::AddProcessProc_TI ( const char  inDLLFileNameUTF8[],
const char  inProcessProcSymbol[],
AAX_IPropertyMap inProperties = NULL,
const char  inInstanceInitProcSymbol[] = NULL,
const char  inBackgroundProcSymbol[] = NULL,
AAX_CSelector outProcID = NULL 
)
virtual

Registers an algorithm processing entrypoint (process procedure) for the native architecture.

Parameters
[in]inDLLFileNameUTF8UTF-8 encoded filename for the ELF DLL containing the algorithm code fragment
[in]inProcessProcSymbolSymbol for this processing callback
[in]inPropertiesA 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]inInstanceInitProcSymbolInitialization 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]inBackgroundProcSymbolBackground 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
Todo:
document this parameter

Implements AAX_IComponentDescriptor.

◆ AddProcessProc()

virtual AAX_Result AAX_VComponentDescriptor::AddProcessProc ( AAX_IPropertyMap inProperties,
AAX_CSelector outProcIDs = NULL,
int32_t  inProcIDsSize = 0 
)
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)

AddProcessProc_TI() (AAX_eProperty_PlugInID_TI)

If any platform-specific plug-in ID property is present in iProperties then AddProcessProc() will check for the required properties for that platform.

Note
AAX_eProperty_AudioBufferLength will be ignored for the Native and AudioSuite ProcessProcs since it should only be used for AAX DSP.
Parameters
[in]inPropertiesA 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
Todo:
document this parameter Returned array will be NULL-terminated
Parameters
[in]inProcIDsSizeThe 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

Implements AAX_IComponentDescriptor.

◆ GetIUnknown()

IACFUnknown* AAX_VComponentDescriptor::GetIUnknown ( void  ) const

Friends And Related Function Documentation

◆ AAX_VPropertyMap

friend class AAX_VPropertyMap
friend

The documentation for this class was generated from the following file: