![]() |
AAX SDK
2.4.1
Avid Audio Extensions Development Kit
|
#include <AAX_IACFEffectGUI.h>
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.
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... | |
![]() | |
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... | |
|
pure virtual |
Main GUI initialization.
Called when the GUI is created
[in] | iController | A versioned reference that resolves to an AAX_IController interface |
Implemented in AAX_CEffectGUI.
|
pure virtual |
Main GUI uninitialization.
Called when the GUI is destroyed. Frees the GUI.
Implemented in AAX_CEffectGUI.
|
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.
NotificationReceived()
methods.NotificationReceived()
method (e.g. the data model).[in] | inNotificationType | Type of notification being received. Notifications form the host are one of AAX_ENotificationEvent |
[in] | inNotificationData | Block of incoming notification data |
[in] | inNotificationDataSize | Size of inNotificationData , in bytes |
Implemented in AAX_CEffectGUI.
|
pure virtual |
Provides a handle to the main plug-in window.
[in] | iViewContainer | An AAX_IViewContainer providing a native handle to the plug-in's window |
Implemented in AAX_CEffectGUI.
|
pure virtual |
Retrieves the size of the plug-in window.
[out] | oViewSize | The size of the plug-in window as a point (width, height) |
Implemented in AAX_CEffectGUI.
|
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.
|
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.
|
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.
|
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.
[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.
|
pure virtual |
Called by host application. Indicates that a control widget should be updated with a highlight color.
SetControlHighliteInfo()
, its name in the legacy plug-in SDK.[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.