Manipulators

group FnManipulator

Typedefs

typedef std::shared_ptr<ManipulatorWrapper> ManipulatorWrapperPtr
class ManipulatorPluginBase
#include <FnManipulator.h>

Interface for a Viewer Manipulator.

A Manipulator allows a user to interact with the Viewer scene by drawing handles that can be interacted with and that can change values in the scene.

A Manipulator can be optionally composed of a series of ManipulatorHandles, which are a plug-in type on its own to allow reusability between Manipulator types. The draw() and event() functions can implement all the drawing and UI event handling without using any ManipulatorHandle. If there are ManipulatorHandles being used then draw() and event() will be propagated by each one of them.

When interacting with a Manipulator Katana will be informed that something changed and needs to potentially be stored in a node attribute and recooked. This is done via the setValue(), which follows a protocol used by Katana that maps Scene Graph attributes with nodes and parameters in the current project. This allows setValue() to set attributes rather than parameters directly.

Because the cooking times can be non-interactive in certain scenes, the Manipulators use a mechanism that will make the ViewerDelegate to return the manipulated values while the cook is running. This means that the function ViewerDelegate::getAttributes() will return these manipulated values so that the Viewer can present interactive performance. Once the cooked value is returned by Geolib3, the ViewerDelegate will return the cooked values as before and the manipulated value is discarded.

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 Manipulator* 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::Manipulator, Foundry::Katana::ViewerAPI::ManipulatorWrapper

Public Functions

ManipulatorPluginBase()

Constructor.

virtual ~ManipulatorPluginBase()

Destructor.

std::string getPluginName()

Gets the Manipulator plugin name.

Return
The name given to the Manipulator plugin when registered.

ViewportWrapperPtr getViewport()

Gets the Viewport.

Gets the Viewport that activated this instance of Manipulator. This can be used to access the Viewport functionality also to access the ViewerDelegate associated with it, via:

getViewport()->getViewerDelegate()

Return
The Viewport that created and manages this layer.

void getLocationPaths(std::vector<std::string> &paths)

Gets the matched locations manipulated by this Manipulator.

These locations are only the ones that match this Manipulator. If any location was associated with the manipulator and does not match it, then that will not be returned by this function. If, after cooking, those locations start/stop matching the Manipulator, then this will return different locations. The result can be an empy vector.

Parameters
  • paths -

    The location paths or an empty vector.

Matrix44d getXform()

Gets the Manipulator’s transform.

Return
A 4x4 matrix in the form of a DoubleAttribute.

void setXform(const Matrix44d &xformMatrix)

Sets the Manipulator’s transform.

Parameters

Matrix44d calculateAveragePositionXform()

Calculates the the averate of the locations positions.

This returns a transform containing solely the world space average translation of the manipulated locations.

Return
A 4x4 matrix in the form of a DoubleAttribute with translation values only.

bool setValue(const std::string &locationPath, const std::string &attrName, FnAttribute::Attribute valueAttr, bool isFinal)

Sets a manipulated value back into Katana.

When the user interacts with a Manipulator some values will have to be sent back to Katana. Setting these values will typically end up setting some node parameters in Katana. Parameters will not be set explicitly by the Manipulators because the same Manipulator might be able to serve different nodes with different parameters. The protocol to communicate these value back into Katana is by using setValue() on Scene Graph attributes that might exist in the scene. For example in order to change the position of an object setValue() would be called for the location of that object on its attribute ‘xform.interactive.translate’.

Katana will know what parameters to change via the protocol defined by discovering the node via the “attributeEditor.exclusiveTo” attribute convention and then via the setOverride() function on that node. This function will return false if no parameter capable of editing the given attribute is found.

Once a value is set the cooked result might take some time to arrive back. During that time, ViewerDelegate::getAttributes() will return the manipulated value, rather than the cooked one, for those attributes.

While a user is scrubbing a Manipulator the values might not end up being committed immediately into Geolib3 to be cooked, as this might not perform at an interactive speed (depending on the project complexity). For this the concept of ‘final’ value is used. While the user is scrubbing a Manipulator handle the value will not be sent back to Katana as the final one. That will happen only once the user releases it, which, at that point, Katana will, guaranteedly, be informed that the new scene can be cooked.

Return
True if a parameter capable of editing the given attribute was found and was successfully set, false otherwise.
Parameters
  • locationPath -

    The location of the object being manipulated.

  • attrName -

    The attribute name for the value being manipulated.

  • valueAttr -

    The value being set.

  • isFinal -

    True if this is a final value.

void openManipulationGroup(const std::string &locationPath)

Marks the beginning of a batch of manipulations.

Multiple manipulations can be batched into a group, allowing them to be processed at the same time. Once called any subsequent calls to setManipulatedAttribute() will be deferred until closeManipulationGroup() is called.

Parameters
  • locationPath -

    The scene graph location that this group is for. Multiple groups can be created for different locations.

void closeManipulationGroup(const std::string &locationPath)

Marks the end of a batch of manipulations.

Parameters
  • locationPath -

    The scene graph location that this group is for. Multiple groups can be created for different locations.

FnAttribute::Attribute getValue(const std::string &locationPath, const std::string &attrName)

Gets a value that has been manipulated.

Return
The value previously set by setValue().
Parameters
  • locationPath -

    The location of the manipulated object.

  • attrName -

    The name of the attribute name with the manipulated value.

ManipulatorHandleWrapperPtr addManipulatorHandle(const std::string &pluginName, const std::string &name)

Instantiates a ManipulatorHandle.

Instantiates a ManipulatorHandle that is part of this Manipulator.

Return
The new ManipulatorHandle instance or 0 if no plugin with the given plugin name exists.
Parameters
  • pluginName -

    The name of the ManipulatorHandle plugin.

  • name -

    The local name of the handle.

ManipulatorHandleWrapperPtr getManipulatorHandle(const std::string &name)

Gets a ManipulatorHandle of this Manipulator by name.

Gets a ManipulatorHandle instance created and managed by this instance of the Manipulator;

Return
The new ManipulatorHandle instance or 0 if none was created with the given name.
Parameters

ManipulatorHandleWrapperPtr getManipulatorHandle(unsigned int index)

Gets a ManipulatorHandle of this Manipulator by index.

Gets a ManipulatorHandle instance created and managed by this instance of the Manipulator;

Return
The new ManipulatorHandle instance or a null shared pointer if none exists with the given index.
Parameters
  • index -

    The position in the list of ManipulatorHandles.

void removeManipulatorHandle(const std::string &name)

Removes a ManipulatorHandle by name.

Parameters

void removeManipulatorHandle(unsigned int index)

Removes a ManipulatorHandle by index.

Parameters
  • index -

    The position in the list of ManipulatorHandles.

unsigned int getNumberOfManipulatorHandles() const

Gets the number of ManipulatorHandles.

Return
The number of ManipulatorHandles added to this Manipulator.

std::string getManipulatorHandleName(unsigned int index)

Gets the name of the ManipulatorHandles on a given index.

Return
The name of the ManipulatorHandles on the given index or empty string if it doesn’t exist.
Parameters
  • index -

    The position in the list of ManipulatorHandles on this Manipulator.

bool isInteractive() const

Returns whether the manipulated location is interactive.

An location is determined to be interactive if the location has an ‘attributeEditor’ attribute that specifies a node where interactive changes should be stored.

Return
true if the location is interactive, otherwise false.

Public Static Functions

static FnAttribute::GroupAttribute GetRegisteredManipulatorsInfo()

Returns information about the registered Manipulators.

Return
A GroupAttribute with a child for each registered Manipulator plug-in, containing the tags returned by the Manipulator plug-in’s getTags() method.

Public Static Attributes

const char kTagName[]

The UI display name of the manipulator.

const char kTagShortcut[]

The default keyboard shortcut.

const char kTagGroup[]

The manipulator group (Transform, Light etc).

const char kTagTechnology[]

The target viewer technology to differentiate between manipulators for different types of viewport.

const char kTagAlwaysAvailable[]

For setting whether the manipulator should always be available to choose in the UI, as opposed to only when scene graph locations with compatible attributes are selected.

const char kTagExclusiveInGroup[]

For setting whether other manipulators in the same group can be active at the same time

const char kTagPriorityInGroup[]

For setting the priority within its group of manipulators. The greater the value, the higher the position in the list.

const char kTagGroup_TRANSFORM[]
const char kTagGroup_LIGHT[]
class Manipulator
#include <FnManipulator.h>

Manipulator plug-in base class.

Inherits from Foundry::Katana::ViewerAPI::ManipulatorPluginBase

Subclassed by Foundry::Katana::ViewerUtils::GLManipulator

Public Functions

Manipulator()

Constructor.

virtual ~Manipulator()

Destructor.

virtual void setup() = 0

Initializes the GL components of the Viewport.

Called when a Manipulator is created. It runs inside the correct GL context. This can be used to initialize anything GL related.

virtual bool event(const FnEventWrapper &eventData)

Processes UI events.

Called whenever a user interaction event occurs.

Return
True if the event has been handled, false otherwise. By default this returns false.
Parameters

virtual void draw()

Draws the Manipulator.

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)

Draws the Manipulator 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 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 Manipulator.

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.

Public Static Functions

static bool matches(const FnAttribute::GroupAttribute &locationAttrs)

Specifies if the Manipulator can be applied to a location.

Specifies if the passed locations attributes has the attributes that are required by this Manipulator. This should be extended in sub-classes.

static FnAttribute::GroupAttribute getTags()

Gets the Manipulator tags.

Returns the tags for this Manipulator. These tags are key:value pairs containing meta-data that can be used by the Viewers to categorize and identify the available Manipulators. For example, a possible tag could be {type:transform}, meaning that the Manipulator allows to manipulate object transforms (manipulators like rotate, translate, scale could be tagged like this). The Viewer tab can use these tags to, for example, group the Manipulators according to their functionality on a UI menu, or it can discard Manipulators that are not meant to be available on on that Viewer.

Return
A GroupAttribute containing the key:value pairs that define the tags of the manipulator.

class ManipulatorWrapper
#include <FnManipulator.h>

Wrapper class for a Manipulator plug-in.

Inherits from Foundry::Katana::ViewerAPI::ManipulatorPluginBase

Public Functions

ManipulatorWrapper(FnPluginHost *host, FnManipulatorHostHandle hostHandle, FnManipulatorPluginHandle pluginHandle, FnManipulatorPluginSuite_v1 *pluginSuite)
~ManipulatorWrapper()
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 Manipulator 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.

bool matches(const FnAttribute::GroupAttribute &locationAttrs)
FnAttribute::GroupAttribute getTags()
void draw()

Draws the Manipulator.

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

bool event(FnEventWrapper eventData)

Triggers the processing of UI events on this Manipulator.

Return
True if the event has been handled, false otherwise.
Parameters

void pickerDraw(int64_t pickerId)

Draws the Manipulator 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.