#include <AAX_IComponentDescriptor.h>

Inheritance diagram for AAX_IComponentDescriptor:

Description

Description interface for an AAX plug-in component.

:Implemented by the AAX Host:

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 iFieldIndex)=0
	Subscribes an audio input context field. More...

virtual AAX_Result	AddAudioOut (AAX_CFieldIndex iFieldIndex)=0
	Subscribes an audio output context field. More...

virtual AAX_Result	AddAudioBufferLength (AAX_CFieldIndex iFieldIndex)=0
	Subscribes a buffer length context field. More...

virtual AAX_Result	AddSampleRate (AAX_CFieldIndex iFieldIndex)=0
	Subscribes a sample rate context field. More...

virtual AAX_Result	AddClock (AAX_CFieldIndex iFieldIndex)=0
	Subscribes a clock context field. More...

virtual AAX_Result	AddSideChainIn (AAX_CFieldIndex iFieldIndex)=0
	Subscribes a side-chain input context field. More...

virtual AAX_Result	AddDataInPort (AAX_CFieldIndex iFieldIndex, uint32_t iPacketSize, AAX_EDataInPortType iPortType=AAX_eDataInPortType_Buffered)=0
	Adds a custom data port to the algorithm context. More...

virtual AAX_Result	AddAuxOutputStem (AAX_CFieldIndex iFieldIndex, int32_t iStemFormat, const char iNameUTF8[])=0
	Adds an auxiliary output stem for a plug-in. More...

virtual AAX_Result	AddPrivateData (AAX_CFieldIndex iFieldIndex, int32_t iDataSize, uint32_t iOptions=AAX_ePrivateDataOptions_DefaultOptions)=0
	Adds a private data port to the algorithm context. More...

virtual AAX_Result	AddTemporaryData (AAX_CFieldIndex iFieldIndex, uint32_t iDataElementSize)=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 iFieldIndex, AAX_IDma::EMode iDmaMode)=0
	Adds a DMA field to the plug-in's context. More...

virtual AAX_Result	AddMeters (AAX_CFieldIndex iFieldIndex, const AAX_CTypeID *iMeterIDs, const uint32_t iMeterCount)=0
	Add a meter field to the plug-in's context. More...

virtual AAX_Result	AddMIDINode (AAX_CFieldIndex iFieldIndex, AAX_EMIDINodeType iNodeType, const char iNodeName[], uint32_t channelMask)=0
	Add your MIDI node objects as context fields. More...

virtual AAX_Result	AddReservedField (AAX_CFieldIndex iFieldIndex, uint32_t iFieldType)=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 *iPropertyMap) const =0
	Creates a new property map using an existing property map. More...

virtual AAX_Result	AddProcessProc_Native (AAX_CProcessProc iProcessProc, AAX_IPropertyMap iProperties=NULL, AAX_CInstanceInitProc iInstanceInitProc=NULL, AAX_CBackgroundProc iBackgroundProc=NULL, AAX_CSelector oProcID=NULL)=0
	Registers an algorithm processing entrypoint (process procedure) for the native architecture. More...

virtual AAX_Result	AddProcessProc_TI (const char inDLLFileNameUTF8[], const char iProcessProcSymbol[], AAX_IPropertyMap iProperties=NULL, const char iInstanceInitProcSymbol[]=NULL, const char iBackgroundProcSymbol[]=NULL, AAX_CSelector oProcID=NULL)=0
	Registers an algorithm processing entrypoint (process procedure) for the native architecture. More...

template<typename aContextType >
AAX_Result	AddProcessProc_Native (void(AAX_CALLBACK iProcessProc)(aContextType const iInstancesBegin[], const void iInstancesEnd), AAX_IPropertyMap iProperties=NULL, int32_t(AAX_CALLBACK iInstanceInitProc)(const aContextType iInstanceContextPtr, AAX_EComponentInstanceInitAction iAction)=NULL, int32_t(AAX_CALLBACK *iBackgroundProc)(void)=NULL)
	Registers an algorithm processing entrypoint (process procedure) for the native architecture. More...

Constructor & Destructor Documentation

virtual AAX_IComponentDescriptor::~AAX_IComponentDescriptor ( )

inlinevirtual

Member Function Documentation

virtual AAX_Result AAX_IComponentDescriptor::Clear ( )

pure virtual

Clears the descriptor.

Clears the descriptor and readies it for the next algorithm description

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddAudioIn ( AAX_CFieldIndex iFieldIndex )

pure 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] iFieldIndex Unique identifier for the field, generated using AAX_FIELD_INDEX

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddAudioOut ( AAX_CFieldIndex iFieldIndex )

pure 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] iFieldIndex Unique identifier for the field, generated using AAX_FIELD_INDEX

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddAudioBufferLength ( AAX_CFieldIndex iFieldIndex )

pure 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] iFieldIndex Unique identifier for the field, generated using AAX_FIELD_INDEX

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddSampleRate ( AAX_CFieldIndex iFieldIndex )

pure virtual

Subscribes a sample rate context field.

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

Data type: AAX_CSampleRate *
Data kind: The current sample rate

Parameters

[in] iFieldIndex Unique identifier for the field, generated using AAX_FIELD_INDEX

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddClock ( AAX_CFieldIndex iFieldIndex )

pure 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 time counter which increments even when the transport is not playing.

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] iFieldIndex Unique identifier for the field, generated using AAX_FIELD_INDEX

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddSideChainIn ( AAX_CFieldIndex iFieldIndex )

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.

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] iFieldIndex Unique identifier for the field, generated using AAX_FIELD_INDEX

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddDataInPort	(	AAX_CFieldIndex	iFieldIndex,
		uint32_t	iPacketSize,
		AAX_EDataInPortType	iPortType = `AAX_eDataInPortType_Buffered`
	)

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.

Parameters

[in]	iFieldIndex	Unique identifier for the port, generated using AAX_FIELD_INDEX
[in]	iPacketSize	Size of the data packets that will be sent to this port
[in]	iPortType	Whether or not the host should buffer this port

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddAuxOutputStem	(	AAX_CFieldIndex	iFieldIndex,
		int32_t	iStemFormat,
		const char	iNameUTF8[]
	)

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.

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

Parameters

[in]	iFieldIndex	DEPRECATED: This parameter is no longer needed by the host, but is included in the interface for binary compatibility
[in]	iStemFormat	The stem format of the new aux output
[in]	iNameUTF8	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.

virtual AAX_Result AAX_IComponentDescriptor::AddPrivateData	(	AAX_CFieldIndex	iFieldIndex,
		int32_t	iDataSize,
		uint32_t	iOptions = `AAX_ePrivateDataOptions_DefaultOptions`
	)

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.

See Also: alg_pd_registration

Parameters

[in]	iFieldIndex	Unique identifier for the port, generated using AAX_FIELD_INDEX
[in]	iDataSize	Size of the data packets that will be sent to this port
[in]	iOptions	Options that define the private data port's behavior

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddTemporaryData	(	AAX_CFieldIndex	iFieldIndex,
		uint32_t	iDataElementSize
	)

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.

Parameters

[in]	iFieldIndex	Unique identifier for the port, generated using AAX_FIELD_INDEX
[in]	iDataElementSize	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.

virtual AAX_Result AAX_IComponentDescriptor::AddDmaInstance	(	AAX_CFieldIndex	iFieldIndex,
		AAX_IDma::EMode	iDmaMode
	)

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.

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.

Todo:: Update the DMA system management such that operation priority can be set arbitrarily

Parameters

[in]	iFieldIndex	Unique identifier for the field, generated using AAX_FIELD_INDEX
[in]	iDmaMode	AAX_IDma::EMode that will apply to this field

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddMeters	(	AAX_CFieldIndex	iFieldIndex,
		const AAX_CTypeID *	iMeterIDs,
		const uint32_t	iMeterCount
	)

pure virtual

Add 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]	iFieldIndex	Unique identifier for the field, generated using AAX_FIELD_INDEX
[in]	iMeterIDs	Array of 32-bit IDs, one for each meter. Meter IDs must be unique within the Effect.
[in]	iMeterCount	The number of meters included in this field

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddMIDINode	(	AAX_CFieldIndex	iFieldIndex,
		AAX_EMIDINodeType	iNodeType,
		const char	iNodeName[],
		uint32_t	channelMask
	)

pure virtual

Add your MIDI node objects as context fields.

Host Compatibility Notes:: Due to current restrictions MIDI data won't be delivered to DSP algorithms, only to AAX Native.

Parameters

[in]	iFieldIndex	The ID of the port. MIDI node ports should formatted as a pointer to an AAX_IMIDINode.
[in]	iNodeType	The type of MIDI node, as AAX_EMIDINodeType
[in]	iNodeName	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.

virtual AAX_Result AAX_IComponentDescriptor::AddReservedField	(	AAX_CFieldIndex	iFieldIndex,
		uint32_t	iFieldType
	)

pure virtual

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

Note: Currently for internal use only.

Parameters

[in]	iFieldIndex	Unique identifier for the field, generated using AAX_FIELD_INDEX
[in]	iFieldType	Type of field that is being added

Implemented in AAX_VComponentDescriptor.

virtual AAX_IPropertyMap* AAX_IComponentDescriptor::NewPropertyMap ( ) const

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.

virtual AAX_IPropertyMap* AAX_IComponentDescriptor::DuplicatePropertyMap ( AAX_IPropertyMap * iPropertyMap ) const

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.

Parameters

[in] iPropertyMap The property values in this map will be copied into the new map

Implemented in AAX_VComponentDescriptor.

virtual AAX_Result AAX_IComponentDescriptor::AddProcessProc_Native	(	AAX_CProcessProc	iProcessProc,
		AAX_IPropertyMap *	iProperties = `NULL`,
		AAX_CInstanceInitProc	iInstanceInitProc = `NULL`,
		AAX_CBackgroundProc	iBackgroundProc = `NULL`,
		AAX_CSelector *	oProcID = `NULL`
	)

pure virtual

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

Parameters

[in]	iProcessProc	Symbol for this processing callback
[in]	iProperties	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]	iInstanceInitProc	Initialization routine that will be called when a new instance of the Effect is created. See Algorithm initialization.
[in]	iBackgroundProc	Background routine that will be called in an idle context within the same address space as the associated process procedure. See Background processing callback
[in]	oProcID

Todo:: document this parameter

Implemented in AAX_VComponentDescriptor.

Referenced by AddProcessProc_Native().

Here is the caller graph for this function:

virtual AAX_Result AAX_IComponentDescriptor::AddProcessProc_TI	(	const char	inDLLFileNameUTF8[],
		const char	iProcessProcSymbol[],
		AAX_IPropertyMap *	iProperties = `NULL`,
		const char	iInstanceInitProcSymbol[] = `NULL`,
		const char	iBackgroundProcSymbol[] = `NULL`,
		AAX_CSelector *	oProcID = `NULL`
	)

pure virtual

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

Parameters

[in]	inDLLFileNameUTF8	UTF-8 encoded filename for the ELF DLL containing the algorithm code fragment
[in]	iProcessProcSymbol	Symbol for this processing callback
[in]	iProperties	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]	iInstanceInitProcSymbol	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]	iBackgroundProcSymbol	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
[in]	oProcID

Todo:: document this parameter

Implemented in AAX_VComponentDescriptor.

template<typename aContextType >

AAX_Result AAX_IComponentDescriptor::AddProcessProc_Native	(	void(AAX_CALLBACK iProcessProc)(aContextType const iInstancesBegin[], const void *iInstancesEnd)	,
		AAX_IPropertyMap *	iProperties = `NULL`,
		int32_t(AAX_CALLBACK iInstanceInitProc)(const aContextType iInstanceContextPtr, AAX_EComponentInstanceInitAction iAction)	= `NULL`,
		int32_t(AAX_CALLBACK *iBackgroundProc)(void)	= `NULL`
	)

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.

iProcessProc: AAX_CALLBACK for this processing callback

iProperties: 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.

iInstanceInitProc: AAX_CALLBACK initialization routine that will be called when a new instance of the Effect is created. See Algorithm initialization.

iBackgroundProc: AAX_CALLBACK background routine that will be called in an idle context within the same address space as the associated process procedure. See Background processing callback

References AddProcessProc_Native().

Here is the call graph for this function:

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

AAX_IComponentDescriptor.h

Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation