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

#include <AAX_VController.h>

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

Description

Version-managed concrete Controller class.

For usage information, see Host-provided interfaces

Public Member Functions

 AAX_VController (IACFUnknown *pUnknown)
 
 ~AAX_VController () override
 
AAX_Result GetEffectID (AAX_IString *outEffectID) const AAX_OVERRIDE
 
AAX_Result GetSampleRate (AAX_CSampleRate *outSampleRate) const AAX_OVERRIDE
 CALL: Returns the current literal sample rate. More...
 
AAX_Result GetInputStemFormat (AAX_EStemFormat *outStemFormat) const AAX_OVERRIDE
 CALL: Returns the plug-in's input stem format. More...
 
AAX_Result GetOutputStemFormat (AAX_EStemFormat *outStemFormat) const AAX_OVERRIDE
 CALL: Returns the plug-in's output stem format. More...
 
AAX_Result GetSignalLatency (int32_t *outSamples) const AAX_OVERRIDE
 CALL: Returns the most recent signal (algorithmic) latency that has been published by the plug-in. More...
 
AAX_Result GetHybridSignalLatency (int32_t *outSamples) const AAX_OVERRIDE
 CALL: Returns the latency between the algorithm normal input samples and the inputs returning from the hyrbid component. More...
 
AAX_Result GetPlugInTargetPlatform (AAX_CTargetPlatform *outTargetPlatform) const AAX_OVERRIDE
 CALL: Returns execution platform type, native or TI. More...
 
AAX_Result GetIsAudioSuite (AAX_CBoolean *outIsAudioSuite) const AAX_OVERRIDE
 CALL: Returns true for AudioSuite instances. More...
 
AAX_Result GetCycleCount (AAX_EProperty inWhichCycleCount, AAX_CPropertyValue *outNumCycles) const AAX_OVERRIDE
 CALL: returns the plug-in's current real-time DSP cycle count. More...
 
AAX_Result GetTODLocation (AAX_CTimeOfDay *outTODLocation) const AAX_OVERRIDE
 CALL: Returns the current Time Of Day (TOD) of the system. More...
 
AAX_Result GetCurrentAutomationTimestamp (AAX_CTransportCounter *outTimestamp) const AAX_OVERRIDE
 CALL: Returns the current automation timestamp if called during the GenerateCoefficients() call AND the generation of coefficients is being triggered by an automation point instead of immediate changes. More...
 
AAX_Result GetHostName (AAX_IString *outHostNameString) const AAX_OVERRIDE
 CALL: Returns name of the host application this plug-in instance is being loaded by. This string also typically includes version information. More...
 
AAX_Result SetSignalLatency (int32_t inNumSamples) AAX_OVERRIDE
 CALL: Submits a request to change the delay compensation value that the host uses to account for the plug-in's signal (algorithmic) latency. More...
 
AAX_Result SetCycleCount (AAX_EProperty *inWhichCycleCounts, AAX_CPropertyValue *iValues, int32_t numValues) AAX_OVERRIDE
 CALL: Indicates a change in the plug-in's real-time DSP cycle count. More...
 
AAX_Result PostPacket (AAX_CFieldIndex inFieldIndex, const void *inPayloadP, uint32_t inPayloadSize) AAX_OVERRIDE
 CALL: Posts a data packet to the host for routing between plug-in components. More...
 
AAX_Result SendNotification (AAX_CTypeID inNotificationType, const void *inNotificationData, uint32_t inNotificationDataSize) AAX_OVERRIDE
 CALL: Dispatch a notification. More...
 
AAX_Result SendNotification (AAX_CTypeID inNotificationType) AAX_OVERRIDE
 CALL: Sends an event to the GUI (no payload)

Note
Not an AAX interface method
More...
 
AAX_Result GetCurrentMeterValue (AAX_CTypeID inMeterID, float *outMeterValue) const AAX_OVERRIDE
 CALL: Retrieves the current value of a host-managed plug-in meter. More...
 
AAX_Result GetMeterPeakValue (AAX_CTypeID inMeterID, float *outMeterPeakValue) const AAX_OVERRIDE
 CALL: Retrieves the currently held peak value of a host-managed plug-in meter. More...
 
AAX_Result ClearMeterPeakValue (AAX_CTypeID inMeterID) const AAX_OVERRIDE
 CALL: Clears the peak value from a host-managed plug-in meter. More...
 
AAX_Result GetMeterClipped (AAX_CTypeID inMeterID, AAX_CBoolean *outClipped) const AAX_OVERRIDE
 CALL: Retrieves the clipped flag from a host-managed plug-in meter. More...
 
AAX_Result ClearMeterClipped (AAX_CTypeID inMeterID) const AAX_OVERRIDE
 CALL: Clears the clipped flag from a host-managed plug-in meter. More...
 
AAX_Result GetMeterCount (uint32_t *outMeterCount) const AAX_OVERRIDE
 CALL: Retrieves the number of host-managed meters registered by a plug-in. More...
 
AAX_Result GetNextMIDIPacket (AAX_CFieldIndex *outPort, AAX_CMidiPacket *outPacket) AAX_OVERRIDE
 CALL: Retrieves MIDI packets for described MIDI nodes. More...
 
virtual AAX_IPageTableCreateTableCopyForEffect (AAX_CPropertyValue inManufacturerID, AAX_CPropertyValue inProductID, AAX_CPropertyValue inPlugInID, uint32_t inTableType, int32_t inTablePageSize) const AAX_OVERRIDE
 Copy the current page table data for a particular plug-in type. More...
 
virtual AAX_IPageTableCreateTableCopyForLayout (const char *inEffectID, const char *inLayoutName, uint32_t inTableType, int32_t inTablePageSize) const AAX_OVERRIDE
 Copy the current page table data for a particular plug-in effect and page table layout. More...
 
virtual AAX_IPageTableCreateTableCopyForEffectFromFile (const char *inPageTableFilePath, AAX_ETextEncoding inFilePathEncoding, AAX_CPropertyValue inManufacturerID, AAX_CPropertyValue inProductID, AAX_CPropertyValue inPlugInID, uint32_t inTableType, int32_t inTablePageSize) const AAX_OVERRIDE
 Copy the current page table data for a particular plug-in type. More...
 
virtual AAX_IPageTableCreateTableCopyForLayoutFromFile (const char *inPageTableFilePath, AAX_ETextEncoding inFilePathEncoding, const char *inLayoutName, uint32_t inTableType, int32_t inTablePageSize) const AAX_OVERRIDE
 Copy the current page table data for a particular plug-in effect and page table layout. More...
 
- Public Member Functions inherited from AAX_IController
virtual ~AAX_IController (void)
 

Constructor & Destructor Documentation

◆ AAX_VController()

AAX_VController::AAX_VController ( IACFUnknown pUnknown)

◆ ~AAX_VController()

AAX_VController::~AAX_VController ( )
override

Member Function Documentation

◆ GetEffectID()

AAX_Result AAX_VController::GetEffectID ( AAX_IString outEffectID) const
virtual

Implements AAX_IController.

◆ GetSampleRate()

AAX_Result AAX_VController::GetSampleRate ( AAX_CSampleRate outSampleRate) const
virtual

CALL: Returns the current literal sample rate.

Parameters
[out]outSampleRateThe current sample rate

Implements AAX_IController.

◆ GetInputStemFormat()

AAX_Result AAX_VController::GetInputStemFormat ( AAX_EStemFormat outStemFormat) const
virtual

CALL: Returns the plug-in's input stem format.

Parameters
[out]outStemFormatThe current input stem format

Implements AAX_IController.

◆ GetOutputStemFormat()

AAX_Result AAX_VController::GetOutputStemFormat ( AAX_EStemFormat outStemFormat) const
virtual

CALL: Returns the plug-in's output stem format.

Parameters
[out]outStemFormatThe current output stem format

Implements AAX_IController.

◆ GetSignalLatency()

AAX_Result AAX_VController::GetSignalLatency ( int32_t *  outSamples) const
virtual

CALL: Returns the most recent signal (algorithmic) latency that has been published by the plug-in.

This method provides the most recently published signal latency. The host may not have updated its delay compensation to match this signal latency yet, so plug-ins that dynamically change their latency using SetSignalLatency() should always wait for an AAX_eNotificationEvent_SignalLatencyChanged notification before updating its algorithm to incur this latency.

See also
SetSignalLatency()
Parameters
[out]outSamplesThe number of samples of signal delay published by the plug-in

Implements AAX_IController.

◆ GetHybridSignalLatency()

AAX_Result AAX_VController::GetHybridSignalLatency ( int32_t *  outSamples) const
virtual

CALL: Returns the latency between the algorithm normal input samples and the inputs returning from the hyrbid component.

This method provides the number of samples that the AAX host expects the plug-in to delay a signal. The host will use this value when accounting for latency across the system.

Note
This value will generally scale up with sample rate, although it's not a simple multiple due to some fixed overhead. This value will be fixed for any given sample rate regardless of other buffer size settings in the host app.
Parameters
[out]outSamplesThe number of samples of hybrid signal delay

Implements AAX_IController.

◆ GetPlugInTargetPlatform()

AAX_Result AAX_VController::GetPlugInTargetPlatform ( AAX_CTargetPlatform outTargetPlatform) const
virtual

CALL: Returns execution platform type, native or TI.

Parameters
[out]outTargetPlatformThe type of the current execution platform as one of AAX_ETargetPlatform.

Implements AAX_IController.

◆ GetIsAudioSuite()

AAX_Result AAX_VController::GetIsAudioSuite ( AAX_CBoolean outIsAudioSuite) const
virtual

CALL: Returns true for AudioSuite instances.

Parameters
[out]outIsAudioSuiteThe boolean flag which indicate true for AudioSuite instances.

Implements AAX_IController.

◆ GetCycleCount()

AAX_Result AAX_VController::GetCycleCount ( AAX_EProperty  inWhichCycleCount,
AAX_CPropertyValue outNumCycles 
) const
virtual

CALL: returns the plug-in's current real-time DSP cycle count.

This method provides the number of cycles that the AAX host expects the DSP plug-in to consume. The host uses this value when allocating DSP resources for the plug-in.

Note
A plug-in should never apply a DSP algorithm with more demanding resource requirements than what is currently accounted for by the host. To set a higher cycle count value, a plug-in must call AAX_IController::SetCycleCount(), then poll AAX_IController::GetCycleCount() until the new value has been applied. Once the host has recognized the new cycle count value, the plug-in may apply the more demanding algorithm.
Parameters
[in]inWhichCycleCountSelector for the requested cycle count metric. One of:
[in]outNumCyclesThe current value of the selected cycle count metric
Todo:
PLACEHOLDER - NOT CURRENTLY IMPLEMENTED IN HOST

Implements AAX_IController.

◆ GetTODLocation()

AAX_Result AAX_VController::GetTODLocation ( AAX_CTimeOfDay outTODLocation) const
virtual

CALL: Returns the current Time Of Day (TOD) of the system.

This method provides a plug-in the TOD (in samples) of the current system. TOD is the number of samples that the playhead has traversed since the beginning of playback.

Note
The TOD value is the immediate value of the audio engine playhead. This value is incremented within the audio engine's real-time rendering context; it is not synchronized with non-real-time calls to plug-in interface methods.
Parameters
[out]outTODLocationThe current Time Of Day as set by the host

Implements AAX_IController.

◆ GetCurrentAutomationTimestamp()

AAX_Result AAX_VController::GetCurrentAutomationTimestamp ( AAX_CTransportCounter outTimestamp) const
virtual

CALL: Returns the current automation timestamp if called during the GenerateCoefficients() call AND the generation of coefficients is being triggered by an automation point instead of immediate changes.

Note
This function will return 0 if called from outside of GenerateCoefficients() or if the GenerateCoefficients() call was initiated due to a non-automated change. In those cases, you can get your sample offset from the transport start using GetTODLocation().
Parameters
[out]outTimestampThe current coefficient timestamp. Sample count from transport start.

Implements AAX_IController.

◆ GetHostName()

AAX_Result AAX_VController::GetHostName ( AAX_IString outHostNameString) const
virtual

CALL: Returns name of the host application this plug-in instance is being loaded by. This string also typically includes version information.

Host Compatibility Notes:
Pro Tools versions from Pro Tools 11.0 to Pro Tools 12.3.1 will return a generic version string to this call. This issue is resolved beginning in Pro Tools 12.4.
Parameters
[out]outHostNameStringThe name of the current host application.

Implements AAX_IController.

◆ SetSignalLatency()

AAX_Result AAX_VController::SetSignalLatency ( int32_t  inNumSamples)
virtual

CALL: Submits a request to change the delay compensation value that the host uses to account for the plug-in's signal (algorithmic) latency.

This method is used to request a change in the number of samples that the AAX host expects the plug-in to delay a signal.

The host is not guaranteed to immediately apply the new latency value. A plug-in should avoid incurring an actual algorithmic latency that is different than the latency accounted for by the host.

To set a new latency value, a plug-in must call AAX_IController::SetSignalLatency(), then wait for an AAX_eNotificationEvent_SignalLatencyChanged notification. Once this notification has been received, AAX_IController::GetSignalLatency() will reflect the updated latency value and the plug-in should immediately apply any relevant algorithmic changes that alter its latency to this new value.

Warning
Parameters which affect the latency of a plug-in should not be made available for control through automation. This will result in audible glitches when delay compensation is adjusted while playing back automation for these parameters.
Parameters
[in]inNumSamplesThe number of samples of signal delay that the plug-in requests to incur

Implements AAX_IController.

◆ SetCycleCount()

AAX_Result AAX_VController::SetCycleCount ( AAX_EProperty inWhichCycleCounts,
AAX_CPropertyValue iValues,
int32_t  numValues 
)
virtual

CALL: Indicates a change in the plug-in's real-time DSP cycle count.

This method is used to request a change in the number of cycles that the AAX host expects the DSP plug-in to consume.

Note
A plug-in should never apply a DSP algorithm with more demanding resource requirements than what is currently accounted for by the host. To set a higher cycle count value, a plug-in must call AAX_IController::SetCycleCount(), then poll AAX_IController::GetCycleCount() until the new value has been applied. Once the host has recognized the new cycle count value, the plug-in may apply the more demanding algorithm.
Parameters
[in]inWhichCycleCountsArray of selectors indicating the specific cycle count metrics that should be set. Each selector must be one of:
[in]iValuesAn array of values requested, one for each of the selected cycle count metrics.
[in]numValuesThe size of iValues
Todo:
PLACEHOLDER - NOT CURRENTLY IMPLEMENTED IN HOST

Implements AAX_IController.

◆ PostPacket()

AAX_Result AAX_VController::PostPacket ( AAX_CFieldIndex  inFieldIndex,
const void *  inPayloadP,
uint32_t  inPayloadSize 
)
virtual

CALL: Posts a data packet to the host for routing between plug-in components.

The posted packet is identified with a AAX_CFieldIndex packet index value, which is equivalent to the target data port's identifier. The packet's payload must have the expected size for the given packet index / data port, as defined when the port is created in Describe. See AAX_IComponentDescriptor::AddDataInPort().

Warning
Any data structures that will be passed between platforms (for example, sent to a TI DSP in an AAX DSP plug-in) must be properly data-aligned for compatibility across both platforms. See AAX_ALIGN_FILE_ALG for more information about guaranteeing cross-platform compatibility of data structures used for algorithm processing.
Note
All calls to this method should be made within the scope of AAX_IEffectParameters::GenerateCoefficients(). Calls from outside this method may result in packets not being delivered. See PT-206161
Parameters
[in]inFieldIndexThe packet's destination port
[in]inPayloadPA pointer to the packet's payload data
[in]inPayloadSizeThe size, in bytes, of the payload data

Implements AAX_IController.

◆ SendNotification() [1/2]

AAX_Result AAX_VController::SendNotification ( AAX_CTypeID  inNotificationType,
const void *  inNotificationData,
uint32_t  inNotificationDataSize 
)
virtual

CALL: Dispatch a notification.

The notification is handled by the host and may be delivered back to other plug-in components such as the GUI or data model (via AAX_IEffectGUI::NotificationReceived() or AAX_IEffectParameters::NotificationReceived(), respectively) depending on the notification type.

The host may choose to dispatch the posted notification either synchronously or asynchronously.

See the AAX_ENotificationEvent documentation for more information.

This method is supported by AAX V2 Hosts only. Check the return code on the return of this function. If the error is AAX_ERROR_UNIMPLEMENTED, your plug-in is being loaded into a host that doesn't support this feature.

Parameters
[in]inNotificationTypeType of notification to send
[in]inNotificationDataBlock of notification data
[in]inNotificationDataSizeSize of inNotificationData, in bytes

Implements AAX_IController.

◆ SendNotification() [2/2]

AAX_Result AAX_VController::SendNotification ( AAX_CTypeID  inNotificationType)
virtual

CALL: Sends an event to the GUI (no payload)

Note
Not an AAX interface method

This version of the notification method is a convenience for notifications which do not take any payload data. Internally, it simply calls AAX_IController::SendNotification(AAX_CTypeID, const void*, uint32_t) with a null payload.

Parameters
[in]inNotificationTypeType of notification to send
Note
Not an AAX interface method

Implements AAX_IController.

◆ GetCurrentMeterValue()

AAX_Result AAX_VController::GetCurrentMeterValue ( AAX_CTypeID  inMeterID,
float *  outMeterValue 
) const
virtual

CALL: Retrieves the current value of a host-managed plug-in meter.

Parameters
[in]inMeterIDID of the meter that is being queried
[out]outMeterValueThe queried meter's current value

Implements AAX_IController.

◆ GetMeterPeakValue()

AAX_Result AAX_VController::GetMeterPeakValue ( AAX_CTypeID  inMeterID,
float *  outMeterPeakValue 
) const
virtual

CALL: Retrieves the currently held peak value of a host-managed plug-in meter.

Parameters
[in]inMeterIDID of the meter that is being queried
[out]outMeterPeakValueThe queried meter's currently held peak value

Implements AAX_IController.

◆ ClearMeterPeakValue()

AAX_Result AAX_VController::ClearMeterPeakValue ( AAX_CTypeID  inMeterID) const
virtual

CALL: Clears the peak value from a host-managed plug-in meter.

Parameters
[in]inMeterIDID of the meter that is being cleared

Implements AAX_IController.

◆ GetMeterClipped()

AAX_Result AAX_VController::GetMeterClipped ( AAX_CTypeID  inMeterID,
AAX_CBoolean outClipped 
) const
virtual

CALL: Retrieves the clipped flag from a host-managed plug-in meter.

See AAX_IComponentDescriptor::AddMeters().

Parameters
[in]inMeterIDID of the meter that is being queried.
[out]outClippedThe queried meter's clipped flag.

Implements AAX_IController.

◆ ClearMeterClipped()

AAX_Result AAX_VController::ClearMeterClipped ( AAX_CTypeID  inMeterID) const
virtual

CALL: Clears the clipped flag from a host-managed plug-in meter.

See AAX_IComponentDescriptor::AddMeters().

Parameters
[in]inMeterIDID of the meter that is being cleared.

Implements AAX_IController.

◆ GetMeterCount()

AAX_Result AAX_VController::GetMeterCount ( uint32_t *  outMeterCount) const
virtual

CALL: Retrieves the number of host-managed meters registered by a plug-in.

See AAX_IComponentDescriptor::AddMeters().

Parameters
[out]outMeterCountThe number of registered plug-in meters.

Implements AAX_IController.

◆ GetNextMIDIPacket()

AAX_Result AAX_VController::GetNextMIDIPacket ( AAX_CFieldIndex outPort,
AAX_CMidiPacket outPacket 
)
virtual

CALL: Retrieves MIDI packets for described MIDI nodes.

Parameters
[out]outPortport ID of the MIDI node that has unhandled packet
[out]outPacketThe MIDI packet

Implements AAX_IController.

◆ CreateTableCopyForEffect()

virtual AAX_IPageTable* AAX_VController::CreateTableCopyForEffect ( AAX_CPropertyValue  inManufacturerID,
AAX_CPropertyValue  inProductID,
AAX_CPropertyValue  inPlugInID,
uint32_t  inTableType,
int32_t  inTablePageSize 
) const
virtual

Copy the current page table data for a particular plug-in type.

The host may restrict plug-ins to only copying page table data from certain plug-in types, such as plug-ins from the same manufacturer or plug-in types within the same effect.

See Page Table Guide for more information about page tables.

Returns
A new page table object to which the requested page table data has been copied. Ownership of this object passes to the caller.
a null pointer if the requested plug-in type is unknown, if inTableType is unknown or if inTablePageSize is not a supported size for the given table type.
Parameters
[in]inManufacturerIDManufacturer ID of the desired plug-in type
[in]inProductIDProduct ID of the desired plug-in type
[in]inPlugInIDType ID of the desired plug-in type (AAX_eProperty_PlugInID_Native, AAX_eProperty_PlugInID_TI)
[in]inTableTypeFour-char type identifier for the requested table type (e.g. 'PgTL', 'Av81', etc.)
[in]inTablePageSizePage size for the requested table. Some tables support multiple page sizes.

Implements AAX_IController.

◆ CreateTableCopyForLayout()

virtual AAX_IPageTable* AAX_VController::CreateTableCopyForLayout ( const char *  inEffectID,
const char *  inLayoutName,
uint32_t  inTableType,
int32_t  inTablePageSize 
) const
virtual

Copy the current page table data for a particular plug-in effect and page table layout.

The host may restrict plug-ins to only copying page table data from certain effects, such as effects registered within the current AAX plug-in bundle.

See Page Table Guide for more information about page tables.

Returns
A new page table object to which the requested page table data has been copied. Ownership of this object passes to the caller.
a null pointer if the requested effect ID is unknown or if inLayoutName is not a valid layout name for the page tables registered for the effect.
Parameters
[in]inEffectIDEffect ID for the desired effect. See AAX_ICollection::AddEffect()
[in]inLayoutNamePage table layout name ("name" attribute of the PTLayout XML tag)
[in]inTableTypeFour-char type identifier for the requested table type (e.g. 'PgTL', 'Av81', etc.)
[in]inTablePageSizePage size for the requested table. Some tables support multiple page sizes.

Implements AAX_IController.

◆ CreateTableCopyForEffectFromFile()

virtual AAX_IPageTable* AAX_VController::CreateTableCopyForEffectFromFile ( const char *  inPageTableFilePath,
AAX_ETextEncoding  inFilePathEncoding,
AAX_CPropertyValue  inManufacturerID,
AAX_CPropertyValue  inProductID,
AAX_CPropertyValue  inPlugInID,
uint32_t  inTableType,
int32_t  inTablePageSize 
) const
virtual

Copy the current page table data for a particular plug-in type.

Returns
A new page table object to which the requested page table data has been copied. Ownership of this object passes to the caller.
a null pointer if the requested plug-in type is unkown, if inTableType is unknown or if inTablePageSize is not a supported size for the given table type.
Parameters
[in]inPageTableFilePathPath to XML page table file.
[in]inFilePathEncodingFile path text encoding.
[in]inManufacturerIDManufacturer ID of the desired plug-in type
[in]inProductIDProduct ID of the desired plug-in type
[in]inPlugInIDType ID of the desired plug-in type (AAX_eProperty_PlugInID_Native, AAX_eProperty_PlugInID_TI)
[in]inTableTypeFour-char type identifier for the requested table type (e.g. 'PgTL', 'Av81', etc.)
[in]inTablePageSizePage size for the requested table. Some tables support multiple page sizes.

Implements AAX_IController.

◆ CreateTableCopyForLayoutFromFile()

virtual AAX_IPageTable* AAX_VController::CreateTableCopyForLayoutFromFile ( const char *  inPageTableFilePath,
AAX_ETextEncoding  inFilePathEncoding,
const char *  inLayoutName,
uint32_t  inTableType,
int32_t  inTablePageSize 
) const
virtual

Copy the current page table data for a particular plug-in effect and page table layout.

Returns
A new page table object to which the requested page table data has been copied. Ownership of this object passes to the caller.
a null pointer if inLayoutName is not a valid layout name for the page tables file.
Parameters
[in]inPageTableFilePathPath to XML page table file.
[in]inFilePathEncodingFile path text encoding.
[in]inLayoutNamePage table layout name ("name" attribute of the PTLayout XML tag)
[in]inTableTypeFour-char type identifier for the requested table type (e.g. 'PgTL', 'Av81', etc.)
[in]inTablePageSizePage size for the requested table. Some tables support multiple page sizes.

Implements AAX_IController.


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