Viewer Modifier Porting Guide¶

Summary¶

Viewer Modifier plug-ins are a feature of Katana’s legacy, OpenSceneGraph-based Viewer tab, which allows custom drawing code to be executed for arbitrary scene graph location types. Viewer Modifiers are typically used to draw viewer-only representations of light and camera locations.

Viewer Modifiers are limited in their power and flexibility for various reasons, so with the development of the new Viewer API an alternative solution (now known as Locators) was developed. This guide will cover an approach for emulating the behaviour of legacy Viewer Modifier plug-ins, and how to convert any existing Viewer Modifiers to the new Viewer API’s Locators.

ViewerPluginExtensions¶

A new type of Python plug-in called a ViewerPluginExtension has been added which contains several callback functions that are triggered from the BaseViewerTab class in response to certain events. These functions are onTabCreated(), onDelegateCreated(), onViewportCreated() and onApplyTerminalOps(). Each function is passed relevant arguments, such as the ViewerDelegate or ViewportWidget objects. This allows a ViewerPluginExtension to modify a viewer’s behaviour by applying other plug-in types which may need to work together, such as ViewerDelegateComponents and ViewportLayers.

An example of a VPE may look like this:

from PluginAPI.BaseViewerPluginExtension import BaseViewerPluginExtension

class BallViewerPluginExtension(BaseViewerPluginExtension):
    def onDelegateCreated(self, viewerDelegate, pluginName):
        viewerDelegate.addComponent('BallComponent', 'BallComponent')

    def onViewportCreated(self, viewportWidget, pluginName, viewportName):
        # Insert a layer named BallLayer at index 4 into the given viewport widget
        viewportWidget.insertLayer('BallLayer', 'BallLayer', 4)

PluginRegistry = [
    ("ViewerPluginExtension", 1, "BallViewerPluginExtension", BallViewerPluginExtension),
]

Viewport Layer & Viewer Delegate Component¶

These are two separate plug-ins that can be added to a viewer, usually by a ViewerPluginExtension. The ViewerDelegateComponent is used to track the scene graph and identify locations that require custom drawing and the ViewportLayer is responsible for drawing the locations that have been identified. These classes give you complete control over the drawing of your own geometry, but will require some bookkeeping in order to track changes to the scene graph and selection states.

Typically a viewer will have one ViewerDelegate, but possibly multiple viewports, so computationally heavy work is best suited in the VDC. Any code that requires a current OpenGL context should be called within one of the relevant ViewportLayer functions, or you can call Viewport::makeGLContextCurrent() before executing.

An example of this style of plug-in is distributed with Katana and can be found at $KATANA_ROOT/plugins/Src/ViewerPlugins/BallLocationType.

Once you have a ViewportLayer and ViewerDelegateComponent plug-in you need to write a ViewerPluginExtension as seen above to append them to the ViewerDelegate and Viewport.

// Determines whether this locator plug-in should be used to draw the
// location described in the given viewer location event.
static bool matches(const FnKat::ViewerAPI::ViewerLocationEvent& event);

// Specifies whether this locator plug-in overrides the standard geometry
// representation for matched locations.
static bool overridesBaseGeometry(const FnKat::ViewerAPI::ViewerLocationEvent& event);

// Gets the bounds of the given location.
static FnAttribute::DoubleAttribute getBounds(
    const FnKat::ViewerAPI::ViewerLocationEvent& event);

// Computes the extent of the given location.
static FnAttribute::DoubleAttribute computeExtent(
    const FnKat::ViewerAPI::ViewerLocationEvent& event);