#include <AAX_CEffectParameters.h>

Inheritance diagram for AAX_CEffectParameters:

Collaboration diagram for AAX_CEffectParameters:

Description

Default implementation of the AAX_IEffectParameters interface.

This class provides a default implementation of the AAX_IEffectParameters interface. In nearly all cases, your plug-in's data model should inherit from this class and override only those functions that you wish to explicitly customize.

Legacy Porting Notes:: The default implementations in this class are mostly derived from their equivalent implementations in CProcess and CEffectProcess. For additional CProcess-derived implementations, see AAX_CEffectGUI.

Public Member Functions
	AAX_CEffectParameters (void)

virtual	~AAX_CEffectParameters (void)

AAX_CEffectParameters &	operator= (const AAX_CEffectParameters &other)

Initialization and uninitialization
virtual AAX_Result	Initialize (IACFUnknown *iController)
	Main data model initialization. Called when plug-in instance is first instantiated. More...

virtual AAX_Result	Uninitialize (void)
	Main data model uninitialization. More...

AAX host and plug-in event notification
virtual AAX_Result	NotificationReceived (AAX_CTypeID iNotificationType, const void *iNotificationData, uint32_t iNotificationDataSize)
	Notification Hook. More...

Parameter information
These methods are used by the AAX host to retrieve information about the plug-in's data model. For information about adding parameters to the plug-in and otherwise modifying the plug-in's data model, see AAX_CParameterManager. For information about parameters, see AAX_IParameter.
virtual AAX_Result	GetNumberOfParameters (int32_t *oNumControls) const
	CALL: Retrieves the total number of plug-in parameters. More...

virtual AAX_Result	GetMasterBypassParameter (AAX_IString *oIDString) const
	CALL: Retrieves the ID of the plug-in's Master Bypass parameter. More...

virtual AAX_Result	GetParameterIsAutomatable (AAX_CParamID iParameterID, AAX_CBoolean *oAutomatable) const
	CALL: Retrieves information about a parameter's automatable status. More...

virtual AAX_Result	GetParameterNumberOfSteps (AAX_CParamID iParameterID, int32_t *oNumSteps) const
	CALL: Retrieves the number of discrete steps for a parameter. More...

virtual AAX_Result	GetParameterName (AAX_CParamID iParameterID, AAX_IString *oName) const
	CALL: Retrieves the full name for a parameter. More...

virtual AAX_Result	GetParameterNameOfLength (AAX_CParamID iParameterID, AAX_IString *oName, int32_t iNameLength) const
	CALL: Retrieves an abbreviated name for a parameter. More...

virtual AAX_Result	GetParameterDefaultNormalizedValue (AAX_CParamID iParameterID, double *oValue) const
	CALL: Retrieves default value of a parameter. More...

virtual AAX_Result	SetParameterDefaultNormalizedValue (AAX_CParamID iParameterID, double iValue)
	CALL: Sets the default value of a parameter. More...

virtual AAX_Result	GetParameterType (AAX_CParamID iParameterID, AAX_EParameterType *oParameterType) const
	CALL: Retrieves the type of a parameter. More...

virtual AAX_Result	GetParameterOrientation (AAX_CParamID iParameterID, AAX_EParameterOrientation *oParameterOrientation) const
	CALL: Retrieves the orientation that should be applied to a parameter's controls. More...

virtual AAX_Result	GetParameter (AAX_CParamID iParameterID, AAX_IParameter **oParameter)
	CALL: Retrieves an arbitrary setting within a parameter. More...

virtual AAX_Result	GetParameterIndex (AAX_CParamID iParameterID, int32_t *oControlIndex) const
	CALL: Retrieves the index of a parameter. More...

virtual AAX_Result	GetParameterIDFromIndex (int32_t iControlIndex, AAX_IString *oParameterIDString) const
	CALL: Retrieves the ID of a parameter. More...

virtual AAX_Result	GetParameterValueInfo (AAX_CParamID iParameterID, int32_t iSelector, int32_t *oValue) const
	CALL: Retrieves a property of a parameter. More...

Parameter setters and getters
These methods are used by the AAX host and by the plug-in's UI to retrieve and modify the values of the plug-in's parameters. Note The parameter setters in this section may generate asynchronous requests.
virtual AAX_Result	GetParameterValueFromString (AAX_CParamID iParameterID, double *oValue, const AAX_IString &iValueString) const
	CALL: Converts a value string to a value. More...

virtual AAX_Result	GetParameterStringFromValue (AAX_CParamID iParameterID, double iValue, AAX_IString *oValueString, int32_t iMaxLength) const
	CALL: Converts a normalized parameter value into a string representing its corresponding real value. More...

virtual AAX_Result	GetParameterValueString (AAX_CParamID iParameterID, AAX_IString *oValueString, int32_t iMaxLength) const
	CALL: Retrieves the value string associated with a parameter's current value. More...

virtual AAX_Result	GetParameterNormalizedValue (AAX_CParamID iParameterID, double *oValuePtr) const
	CALL: Retrieves a parameter's current value. More...

virtual AAX_Result	SetParameterNormalizedValue (AAX_CParamID iParameterID, double iValue)
	CALL: Sets the specified parameter to a new value. More...

virtual AAX_Result	SetParameterNormalizedRelative (AAX_CParamID iParameterID, double iValue)
	CALL: Sets the specified parameter to a new value relative to its current value. More...

Automated parameter helpers
These methods are used to lock and unlock automation system 'resources' when updating automatable parameters. Note You should never need to override these methods to extend their behavior beyond what is provided in AAX_CEffectParameters and AAX_IParameter Todo: Do these methods belong in the data model? Should integration with automation system be bolt-on or otherwise modular?
virtual AAX_Result	TouchParameter (AAX_CParamID iParameterID)
	"Touches" (locks) a parameter in the automation system to a particular control in preparation for updates More...

virtual AAX_Result	ReleaseParameter (AAX_CParamID iParameterID)
	Releases a parameter from a "touched" state. More...

virtual AAX_Result	UpdateParameterTouch (AAX_CParamID iParameterID, AAX_CBoolean iTouchState)
	Sets a "touched" state on a parameter. More...

Asynchronous parameter update methods
These methods are called by the AAX host when parameter values have been updated. They are called by the host and can be triggered by other plug-in modules via calls to AAX_IParameter's `SetValue` methods, e.g. SetValueWithFloat() These methods are responsible for updating parameter values. Do not call these methods directly! To ensure proper synchronization and to avoid problematic dependency chains, other methods (e.g. SetParameterNormalizedValue()) and components (e.g. AAX_IEffectGUI) should always call a `SetValue` method on AAX_IParameter to update parameter values. The `SetValue` method will properly manage automation locks and other system resources.
virtual AAX_Result	UpdateParameterNormalizedValue (AAX_CParamID iParameterID, double iValue, AAX_EUpdateSource iSource)
	Updates a single parameter's state to its current value. More...

virtual AAX_Result	UpdateParameterNormalizedRelative (AAX_CParamID iParameterID, double iValue)
	Updates a single parameter's state to its current value, as a difference with the parameter's previous value. More...

virtual AAX_Result	GenerateCoefficients (void)
	Generates and dispatches new coefficient packets. More...

State reset handlers
virtual AAX_Result	ResetFieldData (AAX_CFieldIndex iFieldIndex, void *oData, uint32_t iDataSize) const
	Called by the host to reset a private data field in the plug-in's algorithm. More...

Chunk methods
These methods are used to save and restore collections of plug-in state information, known as chunks. Chunks are used by the host when saving or restoring presets and session settings and when providing "compare" functionality for plug-ins. The default implementation of these methods in AAX_CEffectParameters provides save and restore functionality for all of the plug-in's registered parameters. Override these methods to provide additional plug-in state details that are not encapsulated by the plug-in's set of parameters. For reference, see also: AAX_CChunkDataParser AAX_SPlugInChunk
virtual AAX_Result	GetNumberOfChunks (int32_t *oNumChunks) const
	Retrieves the number of chunks used by this plug-in. More...

virtual AAX_Result	GetChunkIDFromIndex (int32_t iIndex, AAX_CTypeID *oChunkID) const
	Retrieves the ID associated with a chunk index. More...

virtual AAX_Result	GetChunkSize (AAX_CTypeID iChunkID, uint32_t *oSize) const
	Get the size of the data structure that can hold all of a chunk's information. More...

virtual AAX_Result	GetChunk (AAX_CTypeID iChunkID, AAX_SPlugInChunk *oChunk) const
	Fills a block of data with chunk information representing the plug-in's current state. More...

virtual AAX_Result	SetChunk (AAX_CTypeID iChunkID, const AAX_SPlugInChunk *iChunk)
	Restores a set of plug-in parameters based on chunk information. More...

virtual AAX_Result	CompareActiveChunk (const AAX_SPlugInChunk iChunkP, AAX_CBoolean oIsEqual) const
	Determine if a chunk represents settings that are equivalent to the plug-in's current state. More...

virtual AAX_Result	GetNumberOfChanges (int32_t *oNumChanges) const
	Retrieves the number of parameter changes made since the plug-in's creation. More...

Threads
Threading functions
virtual AAX_Result	TimerWakeup ()
	Periodic wakeup callback for idle-time operations. More...

Eucon
Eucon functions
virtual AAX_Result	GetCurveData (AAX_CTypeID iCurveType, const float iValues, uint32_t iNumValues, float oValues) const
	Generate a set of output values based on a set of given input values. More...

Custom Data Methods
These functions exist as a proxiable way to move data between different modules (e.g. AAX_IEffectParameters and AAX_IEffectGUI.) Using these, the GUI can query any data through GetCustomData() with a plug-in defined `typeID`, `void*` and size. This has an advantage over just sharing memory in that this function can work as a remote proxy as we enable those sorts of features later in the platform. Likewise, the GUI can also set arbitrary data on the data model by using the SetCustomData() function with the same idea. Note These are plug-in internal only. They are not called from the host right now, or likely ever.
virtual AAX_Result	GetCustomData (AAX_CTypeID iDataBlockID, uint32_t iDataSize, void oData, uint32_t oDataWritten) const
	An optional interface hook for getting custom data from another module. More...

virtual AAX_Result	SetCustomData (AAX_CTypeID iDataBlockID, uint32_t iDataSize, const void *iData)
	An optional interface hook for setting custom data for use by another module. More...

MIDI methods
virtual AAX_Result	DoMIDITransfers ()
	MIDI update callback. More...

virtual AAX_Result	UpdateMIDINodes (AAX_CFieldIndex iFieldIndex, AAX_CMidiPacket &iPacket)
	MIDI update callback. More...

virtual AAX_Result	UpdateControlMIDINodes (AAX_CTypeID nodeID, AAX_CMidiPacket &iPacket)
	MIDI update callback for control MIDI nodes. More...

Hybrid audio methods
virtual AAX_Result	RenderAudio_Hybrid (AAX_SHybridRenderInfo *ioRenderInfo)
	Hybrid audio render function. More...

Private data accessors
AAX_IController *	Controller ()
	Access to the Effect controller. More...

const AAX_IController *	Controller () const
	`const` access to the Effect controller More...

AAX_ITransport *	Transport ()
	Access to the Transport object. More...

const AAX_ITransport *	Transport () const
	`const` access to the Transport object More...

AAX_IAutomationDelegate *	AutomationDelegate ()

const AAX_IAutomationDelegate *	AutomationDelegate () const

Public Member Functions inherited from AAX_IEffectParameters
ACFMETHOD()	InternalQueryInterface (const acfIID &riid, void **ppvObjOut)

Hybrid audio methods
MIDI methods
Initialization and uninitialization
AAX host and plug-in event notification
Parameter information
These methods are used by the AAX host to retrieve information about the plug-in's data model. For information about adding parameters to the plug-in and otherwise modifying the plug-in's data model, see AAX_CParameterManager. For information about parameters, see AAX_IParameter.
Parameter setters and getters
These methods are used by the AAX host and by the plug-in's UI to retrieve and modify the values of the plug-in's parameters. Note The parameter setters in this section may generate asynchronous requests.
Automated parameter helpers
These methods are used to lock and unlock automation system 'resources' when updating automatable parameters. Note You should never need to override these methods to extend their behavior beyond what is provided in AAX_CEffectParameters and AAX_IParameter Todo: Do these methods belong in the data model? Should integration with automation system be bolt-on or otherwise modular?
Asynchronous parameter update methods
These methods are called by the AAX host when parameter values have been updated. They are called by the host and can be triggered by other plug-in modules via calls to AAX_IParameter's `SetValue` methods, e.g. SetValueWithFloat() These methods are responsible for updating parameter values. Do not call these methods directly! To ensure proper synchronization and to avoid problematic dependency chains, other methods (e.g. SetParameterNormalizedValue()) and components (e.g. AAX_IEffectGUI) should always call a `SetValue` method on AAX_IParameter to update parameter values. The `SetValue` method will properly manage automation locks and other system resources.
State reset handlers
Chunk methods
These methods are used to save and restore collections of plug-in state information, known as chunks. Chunks are used by the host when saving or restoring presets and session settings and when providing "compare" functionality for plug-ins. The default implementation of these methods in AAX_CEffectParameters provides save and restore functionality for all of the plug-in's registered parameters. Override these methods to provide additional plug-in state details that are not encapsulated by the plug-in's set of parameters. For reference, see also: AAX_CChunkDataParser AAX_SPlugInChunk
Thread Methods
EUCON Methods
Custom Data Methods
These functions exist as a proxiable way to move data between different modules (e.g. AAX_IEffectParameters and AAX_IEffectGUI.) Using these, the GUI can query any data through GetCustomData() with a plug-in defined `typeID`, `void*` and size. This has an advantage over just sharing memory in that this function can work as a remote proxy as we enable those sorts of features later in the platform. Likewise, the GUI can also set arbitrary data on the data model by using the SetCustomData() function with the same idea. Note These are plug-in internal only. They are not called from the host right now, or likely ever.
MIDI methods
Public Member Functions inherited from IACFUnknown
virtual BEGIN_ACFINTERFACE ACFRESULT ACFMETHODCALLTYPE	QueryInterface (const acfIID &iid, void **ppOut)=0
	Returns pointers to supported interfaces. More...

virtual acfUInt32 ACFMETHODCALLTYPE	AddRef (void)=0
	Increments reference count. More...

virtual acfUInt32 ACFMETHODCALLTYPE	Release (void)=0
	Decrements reference count. More...

Protected Member Functions
void	BuildChunkData (void) const
	Clears out the current chunk in Chunk Parser and adds all of the new values. Used by default implementations of GetChunk() and GetChunkSize(). More...

Parameter management methods
AAX_Result	SetTaperDelegate (AAX_CParamID iParameterID, AAX_ITaperDelegateBase &iTaperDelegate, bool iPreserveValue)

AAX_Result	SetDisplayDelegate (AAX_CParamID iParameterID, AAX_IDisplayDelegateBase &iDisplayDelegate)

bool	IsParameterTouched (AAX_CParamID iParameterID) const

bool	IsParameterLinkReady (AAX_CParamID inParameterID, AAX_EUpdateSource inSource) const

Convenience functions
These convenience functions provide quick access to various aspects of the default AAX_CEffectParameters implementation.
virtual AAX_Result	EffectInit (void)
	Initialization helper routine. Called from AAX_CEffectParameters::Initialize. More...

void	FilterParameterIDOnSave (AAX_CParamID controlID)
	CALL: Indicates the indices of parameters that should not be saved in the default AAX_CEffectParameters chunk. More...

Protected Attributes
int32_t	mNumPlugInChanges

int32_t	mChunkSize

AAX_CChunkDataParser	mChunkParser

int32_t	mNumChunkedParameters

AAX_CBoolean	mClipped
	Set by SetClipped() and returned by GetClipped(). More...

AAX_CPacketDispatcher	mPacketDispatcher

AAX_CParameterManager	mParameterManager

std::set< std::string >	mFilteredParameters

Constructor & Destructor Documentation

AAX_CEffectParameters::AAX_CEffectParameters ( void )

virtual AAX_CEffectParameters::~AAX_CEffectParameters ( void )

virtual

Member Function Documentation

AAX_CEffectParameters& AAX_CEffectParameters::operator= ( const AAX_CEffectParameters & other )

virtual AAX_Result AAX_CEffectParameters::Initialize ( IACFUnknown * iController )

virtual

Main data model initialization. Called when plug-in instance is first instantiated.

Note: Most plug-ins should override AAX_CEffectParameters::EffectInit() rather than directly overriding this method

Parameters

[in] iController A versioned reference that resolves to an AAX_IController interface

This default implementation calls EffectInit(). Only override Initialize() when additional initialization steps must be performed prior to EffectInit().

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::Uninitialize ( void )

virtual

Main data model uninitialization.

Todo:: Docs: When exactly is AAX_IACFEffectParameters::Uninitialize() called, and under what conditions?

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::NotificationReceived	(	AAX_CTypeID	iNotificationType,
		const void *	iNotificationData,
		uint32_t	iNotificationDataSize
	)

virtual

Notification Hook.

Called from the host when major changes take place such as instantiation, insert position, track name. Most of these notifications are not sent from the host at this point, but we're putting this function in as a placeholder for plug-ins to be notified when events happen.

Look at the AAX_ENotificationEvent enumeration to see a description of events you can listen for and the data they come with.

Parameters

[in]	iNotificationType	Type of notification being received
[in]	iNotificationData	Block of incoming notification data
[in]	iNotificationDataSize	Size of `iNotificationData`, in bytes

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetNumberOfParameters ( int32_t * oNumControls ) const

virtual

CALL: Retrieves the total number of plug-in parameters.

Parameters

[out] oNumControls The number of parameters in the plug-in's Parameter Manager

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetMasterBypassParameter ( AAX_IString * oIDString ) const

virtual

CALL: Retrieves the ID of the plug-in's Master Bypass parameter.

This is required if you want our master bypass functionality in the host to hook up to your bypass parameters.

Parameters

[out] oIDString The ID of the plug-in's Master Bypass control

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterIsAutomatable	(	AAX_CParamID	iParameterID,
		AAX_CBoolean *	oAutomatable
	)		const

virtual

CALL: Retrieves information about a parameter's automatable status.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oAutomatable	True if the queried parameter is automatable, false if it is not

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterNumberOfSteps	(	AAX_CParamID	iParameterID,
		int32_t *	oNumSteps
	)		const

virtual

CALL: Retrieves the number of discrete steps for a parameter.

Note: The value returned for oNumSteps MUST be greater than zero. All other values will be considered an error by the host.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oNumSteps	The number of steps for this parameter

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterName	(	AAX_CParamID	iParameterID,
		AAX_IString *	oName
	)		const

virtual

CALL: Retrieves the full name for a parameter.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oName	The parameter's name, formatted as a `char*`. Currently DAE does not be allow names longer that 31 characters.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterNameOfLength	(	AAX_CParamID	iParameterID,
		AAX_IString *	oName,
		int32_t	iNameLength
	)		const

virtual

CALL: Retrieves an abbreviated name for a parameter.

In general, lengths of 3 through 8 and 31 should be specifically addressed.

Host Compatibility Notes:: In most cases, the AAX host will call GetParameterName() to retrieve parameter names for display. However, when Pro Tools is retrieving a plug-in name for display on a control surface the XML data stored in the plug-in's page tables will be used in preference to values retrieved from GetParameterName().

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oName	The name of the plug-in, abbreviated to aNameLength characters or fewer, formatted as a `char*`
[in]	iNameLength	The maximum number of characters in aName

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterDefaultNormalizedValue	(	AAX_CParamID	iParameterID,
		double *	oValue
	)		const

virtual

CALL: Retrieves default value of a parameter.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oValue	The parameter's default value

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::SetParameterDefaultNormalizedValue	(	AAX_CParamID	iParameterID,
		double	iValue
	)

virtual

CALL: Sets the default value of a parameter.

Parameters

[in]	iParameterID	The ID of the parameter that is being updated
[out]	iValue	The parameter's new default value

Todo:: THIS IS NOT CALLED FROM HOST. USEFUL FOR INTERNAL USE ONLY?

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterType	(	AAX_CParamID	iParameterID,
		AAX_EParameterType *	oParameterType
	)		const

virtual

CALL: Retrieves the type of a parameter.

Todo:: The concept of parameter type needs more documentation

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oParameterType	The parameter's type

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterOrientation	(	AAX_CParamID	iParameterID,
		AAX_EParameterOrientation *	oParameterOrientation
	)		const

virtual

CALL: Retrieves the orientation that should be applied to a parameter's controls.

Todo:: update this documentation

This method allows you to specify the orientation of knob controls that are managed by the host (e.g. knobs on an attached control surface.)

Here is an example override of this method that reverses the orientation of a control for a parameter:

// AAX_IParameter* myBackwardsParameter
if (iParameterID == myBackwardsParameter->Identifier())
{
    *oParameterType =
       AAX_eParameterOrientation_BottomMinTopMax |
       AAX_eParameterOrientation_LeftMinRightMax |
       AAX_eParameterOrientation_RotaryWrapMode |
       AAX_eParameterOrientation_RotaryLeftMinRightMax;
 }

The orientation options are set according to AAX_EParameterOrientationBits

Legacy Porting Notes:: AAX_IEffectParameters::GetParameterOrientation() corresponds to the GetControlOrientation() method in the legacy RTAS/TDM SDK.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oParameterOrientation	The orientation of the parameter

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameter	(	AAX_CParamID	iParameterID,
		AAX_IParameter **	oParameter
	)

virtual

CALL: Retrieves an arbitrary setting within a parameter.

This is a convenience function for accessing the richer parameter interface from the plug-in's other modules.

Note: This function must not be called by the host; AAX_IParameter is not safe for passing across the binary boundary with the host!

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oParameter	A pointer to the returned parameter

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterIndex	(	AAX_CParamID	iParameterID,
		int32_t *	oControlIndex
	)		const

virtual

CALL: Retrieves the index of a parameter.

Although parameters are normally referenced by their AAX_CParamID, each parameter is also associated with a unique numeric index.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oControlIndex	The parameter's numeric index

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterIDFromIndex	(	int32_t	iControlIndex,
		AAX_IString *	oParameterIDString
	)		const

virtual

CALL: Retrieves the ID of a parameter.

This method can be used to convert a parameter's unique numeric index to its AAX_CParamID

Parameters

[in]	iControlIndex	The numeric index of the parameter that is being queried
[out]	oParameterIDString	The parameter's ID, written into an AAX_IString for safefy.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterValueInfo	(	AAX_CParamID	iParameterID,
		int32_t	iSelector,
		int32_t *	oValue
	)		const

virtual

CALL: Retrieves a property of a parameter.

This is a general purpose query that is specialized based on the value of iSelector. The currently supported selector values are described by AAX_EParameterValueInfoSelector . The meaning of oValue is dependent upon iSelector .

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[in]	iSelector	The selector of the parameter value to retrieve. See AAX_EParameterValueInfoSelector
[out]	oValue	The value of the specified parameter

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterValueFromString	(	AAX_CParamID	iParameterID,
		double *	oValue,
		const AAX_IString &	iValueString
	)		const

virtual

CALL: Converts a value string to a value.

This method uses the queried parameter's display delegate and taper to convert a char* string into its corresponding value. The formatting of valueString must be supported by the parameter's display delegate in order for this call to succeed.

Legacy Porting Notes:: This method corresponds to CProcess::MapControlStringToVal() in the RTAS/TDM SDK

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oValue	The value associated with valueString
[in]	iValueString	The formatted value string that will be converted into a value

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterStringFromValue	(	AAX_CParamID	iParameterID,
		double	iValue,
		AAX_IString *	oValueString,
		int32_t	iMaxLength
	)		const

virtual

CALL: Converts a normalized parameter value into a string representing its corresponding real value.

This method uses the queried parameter's display delegate and taper to convert a normalized value into the corresponding char* value string for its real value.

Legacy Porting Notes:: This method corresponds to CProcess::MapControlValToString() in the RTAS/TDM SDK

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[in]	iValue	The normalized value that will be converted to a formatted valueString
[out]	oValueString	The formatted value string associated with value
[in]	iMaxLength	The maximum length of valueString

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterValueString	(	AAX_CParamID	iParameterID,
		AAX_IString *	oValueString,
		int32_t	iMaxLength
	)		const

virtual

CALL: Retrieves the value string associated with a parameter's current value.

This method uses the queried parameter's display delegate and taper to convert its current value into a corresponding char* value string.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oValueString	The formatted value string associated with the parameter's current value
[in]	iMaxLength	The maximum length of valueString

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetParameterNormalizedValue	(	AAX_CParamID	iParameterID,
		double *	oValuePtr
	)		const

virtual

CALL: Retrieves a parameter's current value.

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[out]	oValuePtr	The parameter's current value

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::SetParameterNormalizedValue	(	AAX_CParamID	iParameterID,
		double	iValue
	)

virtual

CALL: Sets the specified parameter to a new value.

SetParameterNormalizedValue() is responsible for initiating any process that is required in order to update all of the parameter's controls (e.g. in the plug-in's GUI, on control surfaces, in automation lanes, etc.) In most cases, the parameter manager will handle this initiation step.

Parameters

[in]	iParameterID	The ID of the parameter that is being set
[in]	iValue	The value to which the parameter should be set

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::SetParameterNormalizedRelative	(	AAX_CParamID	iParameterID,
		double	iValue
	)

virtual

CALL: Sets the specified parameter to a new value relative to its current value.

This method is used in cases when a relative control value is more convenient, for example when updating a GUI control using a mouse wheel or the arrow keys. Note that the host may apply the parameter's step size prior to calling SetParameterNormalizedRelative() in order to determine the correct value for aValue.

SetParameterNormalizedRelative() can be used to incorporate "wrapping" behavior in a parameter's controls, if desired. If this behavior is not desired, then this method must properly account for overflow of the parameter's normalized value.

SetParameterNormalizedRelative() is responsible for initiating any process that is required in order to update all of the parameter's controls (e.g. in the plug-in's GUI, on control surfaces, in automation lanes, etc.) In most cases, the parameter manager will handle this initiation step.

Todo:: REMOVE THIS METHOD (?)

Parameters

[in]	iParameterID	The ID of the parameter that is being queried
[in]	iValue	The change in value that should be applied to the parameter

Todo:: NOT CURRENTLY CALLED FROM THE HOST. USEFUL FOR INTERNAL USE ONLY?

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::TouchParameter ( AAX_CParamID iParameterID )

virtual

"Touches" (locks) a parameter in the automation system to a particular control in preparation for updates

This method is called by the Parameter Manager to prime a parameter for receiving new automation data. When an automatable parameter is touched by a control, it will reject input from other controls until it is released.

Note: You should never need to override this method when using AAX_CEffectParameters.

Parameters

[in] iParameterID The parameter that is being touched

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::ReleaseParameter ( AAX_CParamID iParameterID )

virtual

Releases a parameter from a "touched" state.

This method is called by the Parameter Manager to release a parameter so that any control may send updates to the parameter.

Note: You should never need to override this method when using AAX_CEffectParameters.

Parameters

[in] iParameterID The parameter that is being released

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::UpdateParameterTouch	(	AAX_CParamID	iParameterID,
		AAX_CBoolean	iTouchState
	)

virtual

Sets a "touched" state on a parameter.

Note: This method should be overriden when dealing with linked parameters. Do NOT use this method to keep track of touch states. Use the automation delegate for that.

Parameters

[in]	iParameterID	The parameter that is changing touch states.
[in]	iTouchState	The touch state of the parameter.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::UpdateParameterNormalizedValue	(	AAX_CParamID	iParameterID,
		double	iValue,
		AAX_EUpdateSource	iSource
	)

virtual

Updates a single parameter's state to its current value.

Note: Do not call this method from the plug-in. This method should be called by the host only. To set parameter values from within the plug-in, use the AAX_IParameter interface.

Todo:: FLAGGED FOR CONSIDERATION OF REVISION

Parameters

[in]	iParameterID	The ID of the parameter that is being updated
[in]	iValue	The parameter's current value, to which its internal state must be updated
[in]	iSource	The source of the update

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::UpdateParameterNormalizedRelative	(	AAX_CParamID	iParameterID,
		double	iValue
	)

virtual

Updates a single parameter's state to its current value, as a difference with the parameter's previous value.

Deprecated:: This is not called from the host. It may still be useful for internal calls within the plug-in, though it should only ever be used to update non-automatable parameters. Automatable parameters should always be updated through the AAX_IParameter interface, which will ensure proper coordination with other automation clients.

UpdateParameterNormalizedRelative() can be used to incorporate "wraparound" behavior in a parameter's controls, if desired. If this behavior is not desired, then this method must properly account for overflow of the parameter's normalized value.

See Also: SetParameterNormalizedRelative()

Parameters

[in]	iParameterID	The ID of the parameter that is being updated
[in]	iValue	The difference between the parameter's current value and its previous value (normalized). The parameter's state must be updated to reflect this difference.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GenerateCoefficients ( void )

virtual

Generates and dispatches new coefficient packets.

This method is responsible for updating the coefficient packets associated with all parameters whose states have changed since the last call to GenerateCoefficients(). The host may call this method once for every parameter update, or it may "batch" parameter updates such that changes for several parameters are all handled by a single call to GenerateCoefficients().

For more information on tracking parameters' statuses using the AAX_CPacketDispatcher, helper class, see AAX_CPacketDispatcher::SetDirty().

Note: Do not call this method from the plug-in. This method should be called by the host only. To set parameter values from within the plug-in, use the AAX_IParameter interface.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::ResetFieldData	(	AAX_CFieldIndex	iFieldIndex,
		void *	oData,
		uint32_t	iDataSize
	)		const

virtual

Called by the host to reset a private data field in the plug-in's algorithm.

This method is called sequentially for all private data fields on Effect initialization and during any "reset" event, such as priming for a non-real-time render. This method is called before the algorithm's optional initialization callback, and the initialized private data will be available within that callback via its context block.

See Also: Algorithm initialization.

Parameters

[in]	iFieldIndex	The index of the field that is being initialized
[out]	oData	The pre-allocated block of data that should be initialized
[in]	iDataSize	The size of the data block, in bytes

Implements AAX_IACFEffectParameters.

Reimplemented in AAX_CInstrumentParameters.

virtual AAX_Result AAX_CEffectParameters::GetNumberOfChunks ( int32_t * oNumChunks ) const

virtual

Retrieves the number of chunks used by this plug-in.

Parameters

[out] oNumChunks The number of distinct chunks used by this plug-in

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetChunkIDFromIndex	(	int32_t	iIndex,
		AAX_CTypeID *	oChunkID
	)		const

virtual

Retrieves the ID associated with a chunk index.

Parameters

[in]	iIndex	Index of the queried chunk
[out]	oChunkID	ID of the queried chunk

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetChunkSize	(	AAX_CTypeID	iChunkID,
		uint32_t *	oSize
	)		const

virtual

Get the size of the data structure that can hold all of a chunk's information.

If chunkID is one of the plug-in's custom chunks, initialize *size to the size of the chunk's data in bytes.

This method is invoked every time a chunk is saved, therefore it is possible to have dynamically sized chunks. However, note that each call to GetChunkSize() will correspond to a following call to GetChunk(). The chunk provided in GetChunk() must have the same size as the size provided by GetChunkSize().

Legacy Porting Notes:: In AAX, the value provided by GetChunkSize() should NOT include the size of the chunk header. The value should ONLY reflect the size of the chunk's data.

Parameters

[in]	iChunkID	ID of the queried chunk
[out]	oSize	The chunk's size in bytes

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetChunk	(	AAX_CTypeID	iChunkID,
		AAX_SPlugInChunk *	oChunk
	)		const

virtual

Fills a block of data with chunk information representing the plug-in's current state.

By calling this method, the host is requesting information about the current state of the plug-in. The following chunk fields should be explicitly populated in this method. Other fields will be populated by the host.

AAX_SPlugInChunk::fData
AAX_SPlugInChunk::fVersion
AAX_SPlugInChunk::fName (Optional)
AAX_SPlugInChunk::fSize (Data size only)

Parameters

[in]	iChunkID	ID of the chunk that should be provided
[out]	oChunk	A preallocated block of memory that should be populated with the chunk's data.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::SetChunk	(	AAX_CTypeID	iChunkID,
		const AAX_SPlugInChunk *	iChunk
	)

virtual

Restores a set of plug-in parameters based on chunk information.

By calling this method, the host is attempting to update the plug-in's current state to match the data stored in a chunk. The plug-in should initialize itself to this new state by calling SetParameterNormalizedValue() for each of the relevant parameters.

Parameters

[in]	iChunkID	ID of the chunk that is being set
[in]	iChunk	The chunk

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::CompareActiveChunk	(	const AAX_SPlugInChunk *	iChunkP,
		AAX_CBoolean *	oIsEqual
	)		const

virtual

Determine if a chunk represents settings that are equivalent to the plug-in's current state.

Host Compatibility Notes:: In Pro Tools, this method will only be called if a prior call to GetNumberOfChanges() has indicated that the plug-in's state has changed. If the plug-in's current settings are different from the settings in aChunkP then the plug-in's Compare Light will be illuminated in the plug-in header, allowing users to toggle between the plug-in's custom state and its saved state.

Parameters

[in]	iChunkP	The chunk that is to be tested
[out]	oIsEqual	True if the chunk represents equivalent settings when compared with the plug-in's current state. False if the chunk represents

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetNumberOfChanges ( int32_t * oNumChanges ) const

virtual

Retrieves the number of parameter changes made since the plug-in's creation.

This method is polled regularly by the host, and can additionally be triggered by some events such as mouse clicks. When the number provided by this method changes, the host subsequently calls CompareActiveChunk() to determine if the plug-in's Compare light should be activated.

The value provided by this method should increment with each call to UpdateParameterNormalizedValue()

Parameters

[out] oNumChanges Must be set to indicate the number of parameter changes that have occurred since plug-in initialization.Chunk 8

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::TimerWakeup ( )

virtual

Periodic wakeup callback for idle-time operations.

This method is called from the host using a non-main thread. In general, it should be driven at approximately one call per 30 ms. However, the wakeup is not guaranteed to be called at any regular interval - for example, it could be held off by a high real-time processing load - and there is no host contract regarding maximum latency between wakeup calls.

This wakeup thread runs continuously and cannot be armed/disarmed or by the plug-in.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetCurveData	(	AAX_CTypeID	iCurveType,
		const float *	iValues,
		uint32_t	iNumValues,
		float *	oValues
	)		const

virtual

Generate a set of output values based on a set of given input values.

This method is used by the host to generate EQ and Dynamics curves. Given a set of input values, e.g. frequencies in Hz, this method should generate a corresponding set of output values, e.g. dB gain at each frequency. The semantics of these input and output values are dictated by iCurveType.

Plug-ins may also define custom curve type IDs to use this method internally. For example, the plug-in's GUI could use this method to request curve data in an arbitrary format.

Note: oValues must be allocated by caller with the same size as iValues (iNumValues).

Parameters

[in]	iCurveType	One of AAX_ECurveType
[in]	iValues	An array of input values
[in]	iNumValues	The size of `iValues`
[out]	oValues	An array of ouptut values

Returns: This method should return AAX_ERROR_UNIMPLEMENTED if the plug-in does not support curve data.

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::GetCustomData	(	AAX_CTypeID	iDataBlockID,
		uint32_t	iDataSize,
		void *	oData,
		uint32_t *	oDataWritten
	)		const

virtual

An optional interface hook for getting custom data from another module.

Parameters

[in]	iDataBlockID	Identifier for the requested block of custom data
[in]	iDataSize	Size of provided buffer, in bytes
[out]	oData	Pointer to an allocated buffer. Data will be written here.
[out]	oDataWritten	The number of bytes actually written

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::SetCustomData	(	AAX_CTypeID	iDataBlockID,
		uint32_t	iDataSize,
		const void *	iData
	)

virtual

An optional interface hook for setting custom data for use by another module.

Parameters

[in]	iDataBlockID	Identifier for the provided block of custom data
[in]	iDataSize	Size of provided buffer, in bytes
[in]	iData	Pointer to the data buffer

Implements AAX_IACFEffectParameters.

virtual AAX_Result AAX_CEffectParameters::DoMIDITransfers ( )

inlinevirtual

MIDI update callback.

Call AAX_IController::GetNextMIDIPacket() from within this method to retrieve and process MIDI packets directly within the Effect's data model. MIDI data will also be delivered to the Effect algorithm.

This method is called regularly by the host, similarly to AAX_IEffectParameters::TimerWakeup()

Implements AAX_IACFEffectParameters.

References AAX_SUCCESS.

virtual AAX_Result AAX_CEffectParameters::UpdateMIDINodes	(	AAX_CFieldIndex	iFieldIndex,
		AAX_CMidiPacket &	iPacket
	)

virtual

MIDI update callback.

This method is called by the host for each pending MIDI packet for MIDI nodes in algorithm context structure. Overwrite this method in Plug-In's EffectParameter class if you want to receive MIDI data packets directly in the data model. MIDI data will also be delivered to the Effect algorithm.

Note: This method called by the host for the nodes described with AAX_IComponentDescriptor::AddMIDINode(); To use this method plug-in should register some MIDI nodes in Describe

Parameters

[in]	iFieldIndex	MIDI node field index in algorithm context structure
[in]	iPacket	The incoming MIDI packet for the node

Implements AAX_IACFEffectParameters_V2.

virtual AAX_Result AAX_CEffectParameters::UpdateControlMIDINodes	(	AAX_CTypeID	nodeID,
		AAX_CMidiPacket &	iPacket
	)

virtual

MIDI update callback for control MIDI nodes.

This method is called by the host for each pending MIDI packets for Control MIDI nodes. Overwrite this method in Plug-In's EffectParameter class if you want to receive MIDI data packets directly in the data model. MIDI data will NOT be delivered to the Effect algorithm.

Note: This method called for Host only nodes which were described with AAX_IEffectDescriptor::AddControlMIDINode()

Parameters

[in]	nodeID	Identifier for the MIDI node
[in]	iPacket	The incoming MIDI packet for the node

Implements AAX_IACFEffectParameters_V2.

virtual AAX_Result AAX_CEffectParameters::RenderAudio_Hybrid ( AAX_SHybridRenderInfo * ioRenderInfo )

virtual

Hybrid audio render function.

This method is called from the host to render audio for the hybrid piece of the algorithm.

Note: To use this method plug-in should register some hybrid inputs and ouputs in "Describe"

Implements AAX_IACFEffectParameters_V2.

AAX_IController* AAX_CEffectParameters::Controller ( )

Access to the Effect controller.

const AAX_IController* AAX_CEffectParameters::Controller ( ) const

const access to the Effect controller

AAX_ITransport* AAX_CEffectParameters::Transport ( )

Access to the Transport object.

const AAX_ITransport* AAX_CEffectParameters::Transport ( ) const

const access to the Transport object

AAX_IAutomationDelegate* AAX_CEffectParameters::AutomationDelegate ( )

const AAX_IAutomationDelegate* AAX_CEffectParameters::AutomationDelegate ( ) const

AAX_Result AAX_CEffectParameters::SetTaperDelegate	(	AAX_CParamID	iParameterID,
		AAX_ITaperDelegateBase &	iTaperDelegate,
		bool	iPreserveValue
	)

protected

AAX_Result AAX_CEffectParameters::SetDisplayDelegate	(	AAX_CParamID	iParameterID,
		AAX_IDisplayDelegateBase &	iDisplayDelegate
	)

protected

bool AAX_CEffectParameters::IsParameterTouched ( AAX_CParamID iParameterID ) const

protected

bool AAX_CEffectParameters::IsParameterLinkReady	(	AAX_CParamID	inParameterID,
		AAX_EUpdateSource	inSource
	)		const

protected

virtual AAX_Result AAX_CEffectParameters::EffectInit ( void )

inlineprotectedvirtual

Initialization helper routine. Called from AAX_CEffectParameters::Initialize.

Override to add parameters, packets, meters, and to do any other custom initialization.

Add custom parameters:

Create an AAX_CParameter for each parameter in the plug-in
Call AAX_CParameterManager::AddParameter() using mParameterManager to add parameters to the Parameter Manager

Register packets:

Call AAX_CPacketDispatcher::RegisterPacket() using mPacketDispatcher to register a packet and handling callback.

References AAX_SUCCESS.

void AAX_CEffectParameters::FilterParameterIDOnSave ( AAX_CParamID controlID )

protected

CALL: Indicates the indices of parameters that should not be saved in the default AAX_CEffectParameters chunk.

Allows specific parameters to filtered out of the default AAX_CEffectParameters "Save Settings" functionality. This call is automatically invoked on the Master Bypass control when specified by the DefineMasterBypassControlIndex() call.

Parameters

[in] controlID The ID of the parameter that should be removed from the default chunk

void AAX_CEffectParameters::BuildChunkData ( void ) const

protected

Clears out the current chunk in Chunk Parser and adds all of the new values. Used by default implementations of GetChunk() and GetChunkSize().

Member Data Documentation

int32_t AAX_CEffectParameters::mNumPlugInChanges

protected

int32_t AAX_CEffectParameters::mChunkSize

mutableprotected

AAX_CChunkDataParser AAX_CEffectParameters::mChunkParser

mutableprotected

int32_t AAX_CEffectParameters::mNumChunkedParameters

protected

AAX_CBoolean AAX_CEffectParameters::mClipped

protected

Set by SetClipped() and returned by GetClipped().

AAX_CPacketDispatcher AAX_CEffectParameters::mPacketDispatcher

protected

AAX_CParameterManager AAX_CEffectParameters::mParameterManager

protected

std::set<std::string> AAX_CEffectParameters::mFilteredParameters

protected

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

AAX_CEffectParameters.h

Description

Related classes

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation