#include <AAX_IACFEffectGUI.h>

Inheritance diagram for AAX_IACFEffectGUI:

Collaboration diagram for AAX_IACFEffectGUI:

Description

The interface for a AAX Plug-in's GUI (graphical user interface).

This is the interface for an instance of a plug-in's GUI that gets exposed to the host application. The AAX host interacts with your plug-in's GUI via this interface. See GUI interface.

The plug-in's implementation of this interface is responsible for managing the plug-in's window and graphics objects and for defining the interactions between GUI views and the plug-in's data model.

At initialization, the host provides this interface with a reference to AAX_IController. The GUI may use this controller to retrieve a pointer to the plug-in's AAX_IEffectParameters interface, allowing the GUI to request changes to the plug-in's data model in response to view events. In addition, the controller provides a means of querying information from the host such as stem format or sample rate

When managing a plug-in's GUI it is important to remember that this is just one of many possible sets of views for the plug-in's parameters. Other views and editors, such as automation lanes or control surfaces, also have the ability to synchronously interact with the plug-in's abstract data model interface. Therefore, the GUI should not take asymmetric control over the data model, act as a secondary data model, or otherwise assume exclusive ownership of the plug-in's state. In general, the data model's abstraction to a pure virtual interface will protect against such aberrations, but this remains an important consideration when managing sophisiticated GUI interactions.

You will most likely inherit your implementation of this interface from AAX_CEffectGUI, a default implementation that provides basic GUI functionality and which you can override and customize as needed.

The SDK includes several examples of how the GUI interface may be extended and implemented in order to provide support for third-party frameworks. These examples can be found in the /Extensions/GUI directory in the SDK.

Note: Your implementation of this interface must inherit from AAX_IEffectGUI.

Legacy Porting Notes:: In the legacy plug-in SDK, these methods were found in CProcess and CEffectProcess. For additional CProcess methods, see AAX_IEffectParameters.

Public Member Functions
Initialization and uninitialization
virtual AAX_Result	Initialize (IACFUnknown *iController)=0
	Main GUI initialization. More...

virtual AAX_Result	Uninitialize ()=0
	Main GUI uninitialization. More...

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

View accessors
virtual AAX_Result	SetViewContainer (IACFUnknown *iViewContainer)=0
	Provides a handle to the main plug-in window. More...

virtual AAX_Result	GetViewSize (AAX_Point *oViewSize) const =0
	Retrieves the size of the plug-in window. More...

GUI update methods
virtual AAX_Result	Draw (AAX_Rect *iDrawRect)=0
	DEPRECATED, Not called from host any longer. Your chosen graphics framework should be directly handling draw events from the OS. More...

virtual AAX_Result	TimerWakeup ()=0
	Periodic wakeup callback for idle-time operations. More...

virtual AAX_Result	ParameterUpdated (AAX_CParamID iParamID)=0
	Notifies the GUI that a parameter value has changed. More...

Host interface methods
Miscellaneous methods to provide host-specific functionality
virtual AAX_Result	GetCustomLabel (AAX_EPlugInStrings iSelector, AAX_IString *oString) const =0
	Called by host application to retrieve a custom plug-in string. More...

virtual AAX_Result	SetControlHighlightInfo (AAX_CParamID iParameterID, AAX_CBoolean iIsHighlighted, AAX_EHighlightColor iColor)=0
	Called by host application. Indicates that a control widget should be updated with a highlight color. More...

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

Member Function Documentation

virtual AAX_Result AAX_IACFEffectGUI::Initialize ( IACFUnknown * iController )

pure virtual

Main GUI initialization.

Called when the GUI is created

Parameters

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

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::Uninitialize ( )

pure virtual

Main GUI uninitialization.

Called when the GUI is destroyed. Frees the GUI.

Implemented in AAX_CEffectGUI.

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

pure virtual

Notification Hook.

Called from the host when major changes take place such as instantiation, entering/exiting offline mode, etc.

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. One of AAX_ENotificationEvent
[in]	iNotificationData	Block of incoming notification data
[in]	iNotificationDataSize	Size of `iNotificationData`, in bytes

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::SetViewContainer ( IACFUnknown * iViewContainer )

pure virtual

Provides a handle to the main plug-in window.

Parameters

[in] iViewContainer An AAX_IViewContainer providing a native handle to the plug-in's window

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::GetViewSize ( AAX_Point * oViewSize ) const

pure virtual

Retrieves the size of the plug-in window.

See Also: AAX_IViewContainer::SetViewSize()

Parameters

[out] oViewSize The size of the plug-in window as a point (width, height)

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::Draw ( AAX_Rect * iDrawRect )

pure virtual

DEPRECATED, Not called from host any longer. Your chosen graphics framework should be directly handling draw events from the OS.

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::TimerWakeup ( )

pure virtual

Periodic wakeup callback for idle-time operations.

GUI animation events such as meter updates should be triggered from this method.

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.

Todo:: Document whether or not this method is called when the GUI is closed, hidden, or obscured

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::ParameterUpdated ( AAX_CParamID iParamID )

pure virtual

Notifies the GUI that a parameter value has changed.

This method is called by the host whenever a parameter value has been modified

Todo:: Create a "batch" version of this method, or convert this API to accept multiple updates in a single call a la GenerateCoefficients().

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::GetCustomLabel	(	AAX_EPlugInStrings	iSelector,
		AAX_IString *	oString
	)		const

pure virtual

Called by host application to retrieve a custom plug-in string.

If no string is provided then the host's default will be used.

Parameters

[in]	iSelector	The requested strong. One of AAX_EPlugInStrings
[out]	oString	The plug-in's custom value for the requested string

Implemented in AAX_CEffectGUI.

virtual AAX_Result AAX_IACFEffectGUI::SetControlHighlightInfo	(	AAX_CParamID	iParameterID,
		AAX_CBoolean	iIsHighlighted,
		AAX_EHighlightColor	iColor
	)

pure virtual

Called by host application. Indicates that a control widget should be updated with a highlight color.

Todo:: Document this method

Legacy Porting Notes:: This method was re-named from SetControlHighliteInfo(), its name in the legacy plug-in SDK.

Parameters

[in]	iParameterID	ID of parameter whose widget(s) must be highlighted
[in]	iIsHighlighted	True if turning highlight on, false if turning it off
[in]	iColor	Desired highlight color. One of AAX_EHighlightColor

Implemented in AAX_CEffectGUI.

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

AAX_IACFEffectGUI.h

Description

Public Member Functions

Member Function Documentation