Viewport Layers

group FnViewportLayer

Typedefs

typedef std::shared_ptr<ViewportLayerWrapper> ViewportLayerWrapperPtr
class ViewportLayerPluginBase
#include <FnViewportLayer.h>

Interface for a layer in the Viewport.

A ViewportLayer (or layer) is an optional component of a Viewport that is responsible for a specific set of drawing and/or event processing. Examples of possible layers that can be implemented in a viewer:

  • Manipulators Layer: draws and interacts with manipulators;
  • Mesh Layer: draws all the meshes in the scene;
  • Camera Pan Layer: deals with the user panning the camera in the viewer.

The ViewportLayer allows a better code organization, but the most important reason for their existence is code reusability. Since they are independent plug-ins they can be reused on different Viewports and Viewers.

Every ViewportLayer instance has a Viewport associated with it. That Viewport can create and manage several ViewportLayers. The Viewport makes sure that the setup(), draw(), resize() and event() functions in its ViewportLayers are called for all of them.

A ViewportLayer also allows picking / selection of rendered objects in the scene inside a certain region of the viewport. This can be a deep picking (all objects inside the region, independently if they are occluded or not from the current camera point of view) or it can select only the visible objects. The Viewport provides an optional internal mechanism that makes use of an internal ID pass framebuffer. This can be used by implementing the pickerDraw() virtual function, calling addPickableObject() in it. If the rendering technology provides its own picking mechanism, then it can be used by implementing the customPick() function, which will not make use of the internal ID picking, and pickerDraw() will not be called. This mechanism also is present in the Viewport plugin type.

This is a virtual base class to be extended in your plug-in. In addition to implementing all the pure virtual functions in this class, you must also implement this static method in your derived class:

 // Returns a new instance of your derived class.
 static ViewportLayer* create();

To indicate an error to the caller, your implementation may throw an exception derived from std::exception.

ViewerDelegate is the class that plugins should extend and implement.

ViewerDelegateWrapper is the class that allows other plugin types to access the ViewerDelegate plugin.

ViewerDelegatePluginBase is the base class that provides the common methods between ViewerDelegate and ViewerDelegateWrapper.

Subclassed by Foundry::Katana::ViewerAPI::ViewportLayer, Foundry::Katana::ViewerAPI::ViewportLayerWrapper

Public Functions

ViewportLayerPluginBase()
virtual ~ViewportLayerPluginBase()
ViewportWrapperPtr getViewport()

Gets the Viewport.

Return
The Viewport that created and manages this layer.

void hover(bool isHovering, int x, int y)

Called when the mouse hovers the ViewportLayer.

Layers can detect when the mouse is hovering them so that, for example, objects under the mouse pointer can be highlighted. This is called with the correct GL context so that GL based picking can be executed.

Parameters
  • isHovering -

    Flag that specifies if the mouse is hovering the layer. If false, then the mouse left the layer. In this case x and y should be ignored.

  • x -

    The horizontal pixel coordinate of the mouse pointer in the layer’s local coordinate system.

  • y -

    The vertical pixel coordinate of the mouse pointer in the layer’s local coordinate system.

void pick(unsigned int x, unsigned int y, unsigned int w, unsigned int h, bool deepPicking, PickedAttrsMap &pickedAttrs, float *singlePointDepth = NULL)

Picks the objects that are inside a given viewport region.

Allows to query the scene for objects that are visible inside a given rectangular region in the viewport. This region can be a single pixel on the screen, by setting both its width and height to 1.

The object picking can optionally be deep, meaning that all the objects viewed inside the region will be picked even if they are currently occluded by other objects. A non-deep picking means that only currently visible objects inside the region will be picked.

Picking can be implemented in two ways:

  • Using the internal ID framebuffer based technique implemented via pickerDraw() and addPickableObject().

  • Implementing a custom picking implemented using some third party technology via customPick().

This function makes use of whatever picking technique is implemented in this ViewportLayer.

This function returns a map of picking IDs to Attributes that represent the picked objects and, optionally a depth value for when the picked region is one single pixel.

Parameters
  • x -

    The region origin X component in viewport pixels.

  • y -

    The region origin Y component in viewport pixels.

  • w -

    The region width in viewport pixels.

  • h -

    The region height in viewport pixels.

  • deepPicking -

    Specifies if all objects inside the region, including occluded ones, will be picked. If set to false, only the visible objects should be picked. This should not be set to true in very frequent events, like a mouse move, since this might trigger several calls to pickerDraw().

  • pickedAttrs -

    A map top be filled with FnPickId (key) to Attribute (value) pairs that represent the picked objects. Internally, this will be either populated by customPick() or by addPickableObject() calls inside pickerDraw(). PickedAttrsMap has the same public interface as std::map<FnPickId, FnAttributes::Attribute>.

  • singlePointDepth -

    The value pointed by this will be set with the GL depth of a single pixel when the region with and height are both 1 and this pointer is set to something other than NULL. This can be used to solve occlusion between picked objects from the Viewport and different ViewportLayers when, for example, the user clicks on a single pixel when selecting something.

class ViewportLayer
#include <FnViewportLayer.h>

The ViewportLayer class to be extended by plugins.

Inherits from Foundry::Katana::ViewerAPI::ViewportLayerPluginBase

Subclassed by BallLayer, ExampleSceneLayer, Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer

Public Functions

ViewportLayer(bool usePickingOnHover = false)

Constructor.

Parameters
  • usePickingOnHover -

    If true, then this layer will be calling pick() very frequently to detect if the mouse is hovering any pickable object. This can be used, for example, to highlight an object hovered by the mouse. This specifies that pickerDraw() will run right after any draw() call, so that the IDs readily available on each mouse move. If set to false, the ID pass render will only occur when pick() is called, which is more efficient.

virtual ~ViewportLayer()

Destructor.

virtual void setup() = 0

Initializes the GL components of the ViewportLayer.

Called when a ViewportLayer is created. It runs inside the correct GL context. Can be used to initialize anything GL related. For example, in the case of an OpenGL renderer this function should set up any required OpenGL context rendering flags, defining display lists, etc.

This function is exposed in the Viewport Python class.

virtual void cleanup() = 0

Cleans up the ViewportLayer resources.

Called when a ViewportLayer is removed by the ViewerDelegate.

virtual bool event(const FnEventWrapper &eventData)

Processes UI events.

Called whenever a user interaction event occurs. This will be also propagated through the ViewerLayers of this ViewportLayer.

Return
True if the event has been handled, in that case it will not be passed to the following layers. Otherwise false and the event will be passed to the following layers.
Parameters

virtual void draw() = 0

Draws the scene.

Called when the scene needs to be drawn in the correct GL context. In a non-GL renderer the generated image should be drawn in the GL framebuffer in order to be displayed. This will be also propagated through the ViewerLayers of this ViewportLayer.

This function is exposed in the ViewportLayer Python class.

virtual void resize(unsigned int width, unsigned int height) = 0

Processes viewport resizing.

Called when the viewport widget is resized. This can be extended by sub-clases to accomodate viewport size changes in the renderer.

virtual void hover(bool isHovering, int x, int y)

Called when the mouse hovers the ViewportLayer.

The Viewport can detect when the mouse is hovering it so that, for example, objects under the mouse pointer can be highlighted. This is called with the correct GL context so that GL based picking can be executed.

Parameters
  • isHovering -

    Flag that specifies if the mouse is hovering the viewport. If false, then the mouse left the viewport. In this case x and y should be ignored.

  • x -

    The horizontal pixel coordinate of the mouse pointer in the Viewport’s local coordinate system.

  • y -

    The vertical pixel coordinate of the mouse pointer in the Viewport’s local coordinate system.

virtual void freeze() = 0

Freezes the ViewportLayer when the viewport widget is hidden.

Allows the ViewportLayer to freeze its activities when the viewport is not visible. This allows the ViewerDelegate to stop any kind of unecessary processing that might happen during that time.

virtual void thaw() = 0

Thaws the ViewportLayer when the viewport widget is shown.

Allows the ViewportLayer to restart its activities when the viewport becomes visible. This restarts the activities paused by freeze().

This function is exposed in the Viewport Python class.

virtual void *getPrivateData(void *inputData)

Returns some arbitrary data.

This can be used by other plugins to access some data that is specific to this object after it is compiled, allowing built-in parts of existing Viewers to be extendable by other plugins like ViewerDelegateComponents, Viewports and ViewportLayers.

This function should be called by other plugins after getting a ManipulatorWrapperPtr and converting it into a concrete instance via ManipulatorWrapper::getPluginInstance(). These other plugins will have to be built with the same compiler and using the same compiler flags as the ViewerDelegate so that this data can be cast and used without running into C++ name mangling issues.

Return
The arbitrary private data. A void pointer that can be cast into specific object types by other plugins.
Parameters
  • inputData -

    A pointer to some input data that can be used to produce the returned data.

virtual void setOption(OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr)

Sets a generic option.

Optional. Reacts to a generic option being set from Python or called directly by other C++ Viewer plugin classes. This can be used as a message passing mechanism from the outside into the ViewportLayer.

Parameters
  • optionId -

    The ID of the option created from OptionIdGenerator or manually defined by users.

  • attr -

    Attribute with the value being set.

virtual FnAttribute::Attribute getOption(OptionIdGenerator::value_type optionId)

Gets the value of a generic option.

Optional. Returns the value of a generic option being requested from Python or from other C++ Viewer plugin classes.

Return
Attribute with the value of the option.
Parameters
  • optionId -

    The ID of the option created from OptionIdGenerator or manually defined by users.

void setOption(const std::string &name, FnAttribute::Attribute attr)

Sets a generic option by generating an option ID from the passed name.

This generates an Option ID from the passed string and passes it to setOption(OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr). Since the ID is generated on every call, it is more efficient to generate the ID once, and store it for future use.

Parameters
  • name -

    The name of the option whose value to set.

  • attr -

    Attribute with the value to set for the option.

FnAttribute::Attribute getOption(const std::string &name)

Gets a generic option by generating an option ID from the passed name.

This generates an Option ID from the passed string and passes it to getOption(OptionIdGenerator::value_type optionId). Since the ID is generated on every call, it is more efficient to generate the ID once, and store it for future use.

Return
The value of the option with the given name.
Parameters
  • name -

    The name of the option whose value to retrieve.

bool usesPickingOnHover()

Tells if the layer picks objects when the mouse is hovering them.

This returns the value passed to the ViewportLayer’s constructor argument usePickingOnHover. This leads to pickerDraw() to be called right after any draw() call, so that each frame produces the correct pickable IDs pass internall. This will not happen if customPick() is implemented and returns true.

virtual void pickerDraw(unsigned int x, unsigned int y, unsigned int w, unsigned int h, const PickedAttrsMap &ignoreAttrs)

Draws an ID pass to be used by the optional internal picking.

This allows this layer to make use of the internal ID framebuffer pass technique provided to the Viewport and ViewportLayers. This function should draw all the pickable objects into the current GL framebuffer using an ID color. Inside this function each pickable object has to be registered using addPickableObject(), which will return a FnPickId. This id can be converted into a color using pickIdToColor() (see FnPickingTypes.h), the objects should be rendered without any kind of antialiasing and with that flat color, so that they cover their pickable pixels.

This will be called by Katana if customPick() returns false or if it is not implemented.

This function receives a list of Attributes that refer to pickable objects to be ignored in this render. This is internally used to do a multi-pass id render for deep picking, in which an onion peeling technique is used to detect all the occluded objects. On each iteration this function should not render the objects that were detected in previous iterations. These Attributes correspond to the ones passed previously to addPickableObject().

Parameters
  • x -

    The region origin X component in viewport pixels.

  • y -

    The region origin Y component in viewport pixels.

  • w -

    The region width in viewport pixels.

  • h -

    The region height in viewport pixels.

  • ignoreAttrs -

    Map that contains information about the objects that should not be rendered here. PickedAttrsMap has the same public interface as std::map<FnPickId, FnAttributes::Attribute>.

virtual bool customPick(unsigned int x, unsigned int y, unsigned int w, unsigned int h, bool deepPicking, PickedAttrsMap &pickedAttrs, float *singlePointDepth = NULL)

Overrides the internal ID picking using a third party technique.

If the technology used in the Viewport implements its own picking, or if a GL ID pass is not feasible, then this function allows to override the internal ID picking and to implement the picking of what is present in the scene. If this is implemented and returns true, then pickerDraw() will never be called by Katana. This is called internally by pick(), which will return the returned values of this function.

An example of the use of this function is when using a non-realtime renderer that is able to produce its own ID pass or when the renderer data structures allows to query the geometry present inside the frustrum defined by the picking area.

There is no need to call addPickableObject() inside this function.

This should return a map of FnPickId to Attributes, similar to the one returned by pickerDraw(), which can identify or contain information about each picked objects. The

This can optionally return a depth value for when the picked region is one single pixel.

Parameters
  • x -

    The region origin X component in viewport pixels.

  • y -

    The region origin Y component in viewport pixels.

  • w -

    The region width in viewport pixels.

  • h -

    The region height in viewport pixels.

  • deepPicking -

    Specifies if all objects inside the region, including occluded ones, will be picked. If set to false, only the visible objects should be picked.

  • pickedAttrs -

    A map top be filled with FnPickId (key) to Attribute (value) pairs that represent the picked objects. Internally, this will be either populated by customPick() or by addPickableObject() calls inside pickerDraw(). PickedAttrsMap has the same public interface as std::map<FnPickId, FnAttributes::Attribute>.

  • singlePointDepth -

    The value pointed by this will be set with the GL depth of a single pixel when the region with and height are both 1 and this pointer is set to something other than NULL. This can be used to solve occlusion between picked objects from the Viewport and different ViewportLayers when, for example, the user clicks on a single pixel when selecting something.

FnPickId addPickableObject(FnAttribute::Attribute attr)

Registers a pickable object during pickerDraw().

This should be called inside pickerDraw() in order to let the internal ID picking system know about each pickable object.

The ID returned by this function can be used to both identify an object in some data structure implemented inside this plugin and to define the color to be used by the object when rendering itself in the current ID framebuffer in pickerDraw(), via the pickIdToColor() function (see FnPickingTypes.h). Also see FnGLShaderProgram.h, which implements a way of loading GLSL shaders.

The Attribute passed to this function can contain further information about the pickable object. For some generic cases there will be Attribute conventions that prescribe how this Attribute should be structured in order to be recognized as some typical objects. This allows some out-of-the-box or third party plugins, like other ViewportLayer plugins, to identify objects like, for example, a location:

  • A location should be identified using a GroupAttribute containing at least a child StringAttribute named “location” and with a single value containing the full location path. This will be recognized by the ViewportLayer plugin “SelectionLayer” shipped with Katana, which is responsible for dealing with locations selection in the Viewer.

Any kind of rendered object, other than locations, can be pickable. For example, a handle of some overlay widget that can be manipulated using the mouse. For this, each Viewport will make use of some Attribute convention that is suitable to identify its own pickable objects.

The pick() function will return the FnPickID / Attribute pairs of all picked objects inside its region.

Return
A picking ID assigned to the pickable object.
Parameters
  • attr -

    The Attribute that describes the pickable object.

Public Static Functions

static void flush()

Flush plugin Caches.

Allows to discard any cache for this plugin when a Flush Caches event occurs.

This function is exposed in the Viewport Python class.

class ViewportLayerWrapper
#include <FnViewportLayer.h>

The ViewportLayer class accessed by other plugins.

Inherits from Foundry::Katana::ViewerAPI::ViewportLayerPluginBase

Public Functions

ViewportLayerWrapper(FnPluginHost *host, FnViewportLayerHostHandle hostHandle, FnViewportLayerPluginHandle pluginHandle, FnViewportLayerPluginSuite_v2 *pluginSuite)
~ViewportLayerWrapper()
template <class T>
T *getPluginInstance()

Gets a pointer to the real plugin instance.

WARNING: This function purposely breaks the compiler agnostic pattern of the Katana plugin API, so it needs to be used with care. This performs a dynamic cast to the real type so the implications of what that means in different circumstances should be understood. If the caller and plugin instance are not contained in the same shared library the RTTI check may fail.

This function allows a plugin wrapper to return the actual plugin class. The plugin is returned as a pointer to a child class of ViewportLayer that is a registerd plugin. The type of that child class needs to be specified in the template, so that it can be properly cast. If the specified type doesn’t match the plugin type then NULL is returned.

void draw()

Draws the Viewport Layer.

This function is exposed in the Viewport Python class.

bool event(FnEventWrapper eventData)

Processes the UI events on this ViewportLayer.

This function is exposed in the Viewport Python class.

Return
True if the event has been handled, in which case it will not be passed to the following layers. Otherwise false and the event will be passed to the following layers.
Parameters

void setOption(OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr)

Sets a generic option.

FnAttribute::Attribute getOption(OptionIdGenerator::value_type optionId)

Gets a generic option.

void setOption(const std::string &name, FnAttribute::Attribute attr)

Sets a generic option.

FnAttribute::Attribute getOption(const std::string &name)

Gets a generic option.