Manipulator Handles

group FnManipulatorHandle

Typedefs

typedef std::shared_ptr<ManipulatorHandleWrapper> ManipulatorHandleWrapperPtr
class ManipulatorHandlePluginBase
#include <FnManipulatorHandle.h>

Interface for a Viewer Manipulator Handle.

A ManipulatorHandle is a reusable component that can be used by different Manipulators. It is a scene interaction pattern that can appear in different Manipulators to perform different tasks. An example of a ManipulatorHandle: an Arrow handle that draws an arrow that can be clicked and dragged, this can be used, for example, as the axis handle for a translate manipulator and as a light’s image projection positioning handle.

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 ManipulatorHandle* 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::ManipulatorHandle, Foundry::Katana::ViewerAPI::ManipulatorHandleWrapper

Public Functions

ManipulatorHandlePluginBase()

Constructor.

virtual ~ManipulatorHandlePluginBase()

Destructor.

ManipulatorWrapperPtr getManipulator()

Gets the Manipulator.

Gets the Manipulator that created and manages this instance of ManipulatorHandle. This can be used to access the Manipulator’s functionality and also to access the Viewport and ViewerDelegate associated with it, via: 

getManipulator()->getViewport()->getViewerDelegate()

Returns:

The Manipulator that created and manages this handle.

Matrix44d getXform()

Gets the world transform of the handle.

Returns:

A 4x4 matrix that is calculated by multiplying the local transfrom (see setLocalXform() / getLocalXform()) with the Manipulator’s transform (accessible by Manipulator::getXform().

void setLocalXform(const Matrix44d &xform)

Sets the local transform of the handle.

Parameters:

xform – A 4x4 matrix that defines the handle’s local transform in relation to the Manipulator’s transform.

Matrix44d getLocalXform()

Gets the local transform of the handle.

Returns:

A 4x4 matrix previously set by setLocalXform().

bool isActive()

Tells if the Handle is currently being manipulated.

bool isHovered()

Tells if the Handle is currently being hovered by the mouse.

class ManipulatorHandle : public Foundry::Katana::ViewerAPI::ManipulatorHandlePluginBase
#include <FnManipulatorHandle.h>

The ManipulatorHandle class to be extended by plugins.

Subclassed by Foundry::Katana::ViewerUtils::GLManipulatorHandle

Public Functions

ManipulatorHandle()
virtual ~ManipulatorHandle()
virtual void cancelManipulation() = 0

Cancels the manipulation.

Typically called before the handle is destroyed to discard any pending transform that hasn’t been made persistent while dragging the handle.

virtual void draw() = 0

Draws the Manipulator Handle.

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.

virtual void pickerDraw(int64_t pickerId) = 0

Draws the ManipulatorHandle for picking.

Called when the scene needs to be drawn in order to perform objects selection. This will run 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.

virtual bool event(const FnEventWrapper &eventData)

Processes UI events.

Called whenever a user interaction event occurs.

Parameters:

eventData – The event data (see FnEventWrapper).

Returns:

True if the event has been handled, in that case it should not be passed to the following handles. Otherwise false and the event should be passed to the following handles.

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

Parameters:

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

Returns:

The arbitrary private data. A void pointer that can be cast into specific object types by other plugins.

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

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.

Parameters:

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

Returns:

Attribute with the value of the option.

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.

Parameters:

name – The name of the option whose value to retrieve.

Returns:

The value of the option with the given name.

class ManipulatorHandleWrapper : public Foundry::Katana::ViewerAPI::ManipulatorHandlePluginBase
#include <FnManipulatorHandle.h>

The ManipulatorHandle class accessed by other plugins.

Public Functions

ManipulatorHandleWrapper(FnPluginHost *host, FnManipulatorHandleHostHandle hostHandle, FnManipulatorHandlePluginHandle pluginHandle, FnManipulatorHandlePluginSuite_v1 *pluginSuite)
~ManipulatorHandleWrapper()
template<class T>
inline 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 ManipulatorHandle 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 setActive(bool active)

Sets if the Handle is currently active.

void setHovered(bool hovered)

Sets if the Handle is currently being hovered by the mouse.

void cancelManipulation()

Cancels the manipulation.

This is called just before the handle is destroyed to revert any pending transform changes that haven’t yet been applied while dragging.

void draw()

Draws the Manipulator Handle.

This should be called with the correct GL context since the final image will be rendered on the main framebuffer.

bool event(FnEventWrapper eventData)

Processes the UI events on this ManipulatorHandle.

Parameters:

eventData – The event data (see FnEventWrapper).

Returns:

True if the event has been handled, false otherwise.

void pickerDraw(int64_t pickerId)

Draws the Manipulator Handle for picking.

This should be called with the correct GL context since the final image will be rendered on the main framebuffer.

Parameters:

pickerId – The first ID assigned to this manipulator by the picker.

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.