Foundry::Katana::ViewerAPI::ManipulatorPluginBase Class Reference

Interface for a Viewer Manipulator. More...

#include <FnManipulator.h>

Inheritance diagram for Foundry::Katana::ViewerAPI::ManipulatorPluginBase:

List of all members.

Public Member Functions
	ManipulatorPluginBase ()
	Constructor.
virtual	~ManipulatorPluginBase ()
	Destructor.
std::string	getPluginName ()
	Gets the Manipulator plugin name.
ViewportWrapperPtr	getViewport ()
	Gets the Viewport.
void	getLocationPaths (std::vector< std::string > &paths)
	Gets the matched locations manipulated by this Manipulator.
Matrix44d	getXform ()
	Gets the Manipulator's transform.
void	setXform (const Matrix44d &xformMatrix)
	Sets the Manipulator's transform.
Matrix44d	calculateAveragePositionXform ()
	Calculates the the averate of the locations positions.
bool	setValue (const std::string &locationPath, const std::string &attrName, FnAttribute::Attribute valueAttr, bool isFinal)
	Sets a manipulated value back into Katana.
void	openManipulationGroup (const std::string &locationPath)
	Marks the beginning of a batch of manipulations.
void	closeManipulationGroup (const std::string &locationPath)
	Marks the end of a batch of manipulations.
FnAttribute::Attribute	getValue (const std::string &locationPath, const std::string &attrName)
	Gets a value that has been manipulated.
ManipulatorHandleWrapperPtr	addManipulatorHandle (const std::string &pluginName, const std::string &name)
	Instantiates a ManipulatorHandle.
ManipulatorHandleWrapperPtr	getManipulatorHandle (const std::string &name)
	Gets a ManipulatorHandle of this Manipulator by name.
ManipulatorHandleWrapperPtr	getManipulatorHandle (unsigned int index)
	Gets a ManipulatorHandle of this Manipulator by index.
void	removeManipulatorHandle (const std::string &name)
	Removes a ManipulatorHandle by name.
void	removeManipulatorHandle (unsigned int index)
	Removes a ManipulatorHandle by index.
unsigned int	getNumberOfManipulatorHandles () const
	Gets the number of ManipulatorHandles.
std::string	getManipulatorHandleName (unsigned int index)
	Gets the name of the ManipulatorHandles on a given index.
bool	isInteractive () const
	Returns whether the manipulated location is interactive.
Static Public Member Functions
static FnAttribute::GroupAttribute	GetRegisteredManipulatorsInfo ()
	Returns information about the registered Manipulators.
Static Public Attributes
static const char	kTagName []
	The UI display name of the manipulator.
static const char	kTagShortcut []
	The default keyboard shortcut.
static const char	kTagGroup []
	The manipulator group (Transform, Light etc).
static const char	kTagTechnology []
static const char	kTagAlwaysAvailable []
static const char	kTagExclusiveInGroup []
static const char	kTagPriorityInGroup []

---

Detailed Description

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.

---

Member Function Documentation

ManipulatorHandleWrapperPtr Foundry::Katana::ViewerAPI::ManipulatorPluginBase::addManipulatorHandle	(	const std::string &	pluginName,
		const std::string &	name
	)

Instantiates a ManipulatorHandle.

Instantiates a ManipulatorHandle that is part of this Manipulator.

Parameters:

pluginName	The name of the ManipulatorHandle plugin.
name	The local name of the handle.

Returns:

The new ManipulatorHandle instance or 0 if no plugin with the given plugin name exists.

Matrix44d Foundry::Katana::ViewerAPI::ManipulatorPluginBase::calculateAveragePositionXform

(

)

Calculates the the averate of the locations positions.

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

Returns:

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

void Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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.

void Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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:

[out]

paths

The location paths or an empty vector.

ManipulatorHandleWrapperPtr Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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;

Parameters:

name	The name given to the ManipulatorHandle.

Returns:

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

ManipulatorHandleWrapperPtr Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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;

Parameters:

index

The position in the list of ManipulatorHandles.

Returns:

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

std::string Foundry::Katana::ViewerAPI::ManipulatorPluginBase::getManipulatorHandleName

(

unsigned int

index

)

Gets the name of the ManipulatorHandles on a given index.

Parameters:

index

The position in the list of ManipulatorHandles on this Manipulator.

Returns:

The name of the ManipulatorHandles on the given index or empty string if it doesn't exist.

unsigned int Foundry::Katana::ViewerAPI::ManipulatorPluginBase::getNumberOfManipulatorHandles

(

)

const

Gets the number of ManipulatorHandles.

Returns:

The number of ManipulatorHandles added to this Manipulator.

std::string Foundry::Katana::ViewerAPI::ManipulatorPluginBase::getPluginName

(

)

Gets the Manipulator plugin name.

Returns:

The name given to the Manipulator plugin when registered.

static FnAttribute::GroupAttribute Foundry::Katana::ViewerAPI::ManipulatorPluginBase::GetRegisteredManipulatorsInfo

(

)

[static]

Returns information about the registered Manipulators.

Returns:

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

FnAttribute::Attribute Foundry::Katana::ViewerAPI::ManipulatorPluginBase::getValue	(	const std::string &	locationPath,
		const std::string &	attrName
	)

Gets a value that has been manipulated.

Parameters:

locationPath	The location of the manipulated object.
attrName	The name of the attribute name with the manipulated value.

Returns:

The value previously set by setValue().

ViewportWrapperPtr Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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()

Returns:

The Viewport that created and manages this layer.

Matrix44d Foundry::Katana::ViewerAPI::ManipulatorPluginBase::getXform

(

)

Gets the Manipulator's transform.

Returns:

A 4x4 matrix in the form of a DoubleAttribute.

bool Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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.

Returns:

true if the location is interactive, otherwise false.

void Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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 Foundry::Katana::ViewerAPI::ManipulatorPluginBase::removeManipulatorHandle

(

const std::string &

name

)

Removes a ManipulatorHandle by name.

Parameters:

name	The name of the ManipulatorHandle.

void Foundry::Katana::ViewerAPI::ManipulatorPluginBase::removeManipulatorHandle

(

unsigned int

index

)

Removes a ManipulatorHandle by index.

Parameters:

index

The position in the list of ManipulatorHandles.

bool Foundry::Katana::ViewerAPI::ManipulatorPluginBase::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.

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.

Returns:

True if a parameter capable of editing the given attribute was found and was successfully set, false otherwise.

void Foundry::Katana::ViewerAPI::ManipulatorPluginBase::setXform

(

const Matrix44d &

xformMatrix

)

Sets the Manipulator's transform.

Parameters:

xformMatrix

A 4x4 matrix in the form of a DoubleAttribute.

---

Member Data Documentation

const char Foundry::Katana::ViewerAPI::ManipulatorPluginBase::kTagAlwaysAvailable[] [static]

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.

Referenced by GLTranslateManipulator::getTags(), GLScaleManipulator::getTags(), GLRotateManipulator::getTags(), and GLCoiManipulator::getTags().

const char Foundry::Katana::ViewerAPI::ManipulatorPluginBase::kTagExclusiveInGroup[] [static]

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

Referenced by GLTranslateManipulator::getTags(), GLScaleManipulator::getTags(), GLRotateManipulator::getTags(), and GLCoiManipulator::getTags().

const char Foundry::Katana::ViewerAPI::ManipulatorPluginBase::kTagPriorityInGroup[] [static]

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

Referenced by GLTranslateManipulator::getTags(), GLScaleManipulator::getTags(), GLRotateManipulator::getTags(), and GLCoiManipulator::getTags().

const char Foundry::Katana::ViewerAPI::ManipulatorPluginBase::kTagTechnology[] [static]

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

Referenced by GLTranslateManipulator::getTags(), GLScaleManipulator::getTags(), GLRotateManipulator::getTags(), and GLCoiManipulator::getTags().

---

The documentation for this class was generated from the following file:

• FnManipulator.h