Manipulator Handles¶
-
group
FnManipulatorHandle
Typedefs
-
typedef FnPlatform::internal::SharedPtr<ManipulatorHandleWrapper>::type
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()
- Return
- The Manipulator that created and manages this handle.
-
Matrix44d
getXform
()¶ Gets the world transform of the handle.
- Return
- 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.
- Return
- 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
¶ - #include <FnManipulatorHandle.h>
The ManipulatorHandle class to be extended by plugins.
Inherits from Foundry::Katana::ViewerAPI::ManipulatorHandlePluginBase
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.
- Return
- 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.
- Parameters
eventData
-The event data (see FnEventWrapper).
-
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 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.
- 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.
-
void
setHostHandle
(FnManipulatorHandleHostHandle m_hostHandle)¶
-
FnManipulatorHandleHostHandle
getHostHandle
()¶
Public Static Functions
-
static FnManipulatorHandlePluginSuite_v1 Foundry::Katana::ViewerAPI::ManipulatorHandle::createSuite(FnManipulatorHandlePluginHandle(*create)(FnManipulatorHandleHostHandle hostHandle))
-
static FnManipulatorHandlePluginHandle
newManipulatorHandleHandle
(ManipulatorHandle *manipulatorHandle)¶
-
-
class
ManipulatorHandleWrapper
¶ - #include <FnManipulatorHandle.h>
The ManipulatorHandle class accessed by other plugins.
Inherits from Foundry::Katana::ViewerAPI::ManipulatorHandlePluginBase
Public Functions
-
ManipulatorHandleWrapper
(FnPluginHost *host, FnManipulatorHandleHostHandle hostHandle, FnManipulatorHandlePluginHandle pluginHandle, FnManipulatorHandlePluginSuite_v1 *pluginSuite)¶
-
~ManipulatorHandleWrapper
()¶
- 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 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.
- Return
- True if the event has been handled, false otherwise.
- Parameters
eventData
-The event data (see FnEventWrapper).
-
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.
-
-
typedef FnPlatform::internal::SharedPtr<ManipulatorHandleWrapper>::type