AAX SDK  2.4.1
Avid Audio Extensions Development Kit
List of all members
AAX_IACFEffectGUI Class Referenceabstract

#include <AAX_IACFEffectGUI.h>

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

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 inNotificationType, const void *inNotificationData, uint32_t inNotificationDataSize)=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 inParamID)=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

◆ Initialize()

virtual AAX_Result AAX_IACFEffectGUI::Initialize ( IACFUnknown iController)
pure virtual

Main GUI initialization.

Called when the GUI is created

Parameters
[in]iControllerA versioned reference that resolves to an AAX_IController interface

Implemented in AAX_CEffectGUI.

◆ Uninitialize()

virtual AAX_Result AAX_IACFEffectGUI::Uninitialize ( )
pure virtual

Main GUI uninitialization.

Called when the GUI is destroyed. Frees the GUI.

Implemented in AAX_CEffectGUI.

◆ NotificationReceived()

virtual AAX_Result AAX_IACFEffectGUI::NotificationReceived ( AAX_CTypeID  inNotificationType,
const void *  inNotificationData,
uint32_t  inNotificationDataSize 
)
pure virtual

Notification Hook.

Called from the host to deliver notifications to this object.

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

  • Note
    some notifications are sent only to the plug-in GUI while other notifications are sent only to the plug-in data model. If you are not seeing an expected notification, try checking the other plug-in objects' NotificationReceived() methods.
  • Note
    the host may dispatch notifications synchronously or asynchronously, and calls to this method may occur concurrently on multiple threads.
    A plug-in may also dispatch custom notifications using AAX_IController::SendNotification(). Custom notifications will be posted back to the plug-in's other objects which support a NotificationReceived() method (e.g. the data model).
Parameters
[in]inNotificationTypeType of notification being received. Notifications form the host are one of AAX_ENotificationEvent
[in]inNotificationDataBlock of incoming notification data
[in]inNotificationDataSizeSize of inNotificationData, in bytes

Implemented in AAX_CEffectGUI.

◆ SetViewContainer()

virtual AAX_Result AAX_IACFEffectGUI::SetViewContainer ( IACFUnknown iViewContainer)
pure virtual

Provides a handle to the main plug-in window.

Parameters
[in]iViewContainerAn AAX_IViewContainer providing a native handle to the plug-in's window

Implemented in AAX_CEffectGUI.

◆ GetViewSize()

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]oViewSizeThe size of the plug-in window as a point (width, height)

Implemented in AAX_CEffectGUI.

◆ Draw()

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.

◆ TimerWakeup()

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's 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 runs continuously and cannot be armed/disarmed by the plug-in.

Implemented in AAX_CEffectGUI.

◆ ParameterUpdated()

virtual AAX_Result AAX_IACFEffectGUI::ParameterUpdated ( AAX_CParamID  inParamID)
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

This method may be called on a non-main thread

Implemented in AAX_CEffectGUI.

◆ GetCustomLabel()

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]iSelectorThe requested strong. One of AAX_EPlugInStrings
[out]oStringThe plug-in's custom value for the requested string

Implemented in AAX_CEffectGUI.

◆ SetControlHighlightInfo()

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]iParameterIDID of parameter whose widget(s) must be highlighted
[in]iIsHighlightedTrue if turning highlight on, false if turning it off
[in]iColorDesired highlight color. One of AAX_EHighlightColor

Implemented in AAX_CEffectGUI.


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