|
Katana Plug-in APIs 0.1
|
|
Katana Plug-in APIs 0.1
|
A base class for a GL based Transform ManipulatorHandle. More...
#include <FnGLTransformManipulator.h>
Public Member Functions | |
| GLTransformManipulatorHandle (bool alwaysAtLocationOrigin) | |
| Constructor. | |
| virtual | ~GLTransformManipulatorHandle () |
| Destructor. | |
| virtual void | cancelManipulation () |
| Cancels the manipulation. | |
| virtual void | draw () |
| Draws the handle. | |
| virtual void | pickerDraw (int64_t pickerID) |
| Draws the handle for picking using the passed picker ID. | |
| virtual Orientation | getOrientation () |
| Defines the orientation space of the manipulator. | |
| Vec4f | getDisplayColor (const Vec4f &color) |
| Gets the display color for handles. | |
| virtual std::string | getComponentName ()=0 |
| The transform component (trans, rot, scale) attribute full name. | |
| double | getScale () |
| Gets the uniform scale of the manipulator in world space. | |
| IMATH_NAMESPACE::V3d | getOrigin () |
| Gets the origin of the manipulator in world space. | |
| void | placeOnCenterOfInterest (bool placeOnCoi) |
| Indicates whether the manipulator should be placed on the center of interest. | |
| bool | isPlacedOnCenterOfInterest () const |
| Indicates whether the manipulator is placed on the center of interest. | |
| void | setTransformMode (TransformMode transformMode) |
| Sets the mode for the manipulator's handle. | |
| TransformMode | getTransformMode () |
| Gets the mode for the manipulator's handle. | |
Protected Member Functions | |
| GLTransformManipulator * | getGLTransformManipulator () |
| Utility function: Gets the GLTransformManipulator instance. | |
| bool | isParallelToCamera (const IMATH_NAMESPACE::V3d &axis) |
| Determines whether the axis is close to parallel to the camera. | |
| bool | isPerpendicularToCamera (const IMATH_NAMESPACE::V3d &axis) |
| Determines whether the axis is close to perpendicular to the camera. | |
| IMATH_NAMESPACE::V3d | getCameraRayDirection () |
| void | startDrag (const Vec3d &initialPointOnPlane, const Vec2i &initialMousePosition) |
| Called when a mouse dragging occurs. | |
| virtual void | drag (const Vec3d &initialPointOnPlane, const Vec3d &previousPointOnPlane, const Vec3d ¤tPointOnPlane, const Vec2i &initialMousePosition, const Vec2i &previousMousePosition, const Vec2i ¤tMousePosition, bool isFinal) |
| Called when a mouse dragging occurs. | |
| void | endDrag () |
| Called when a mouse dragging ends. | |
| void | applyXformToAllLocations (const IMATH_NAMESPACE::M44d &xform, bool isFinal) |
| Applies a transformation to all the manipulated locations. | |
| virtual void | applyXformToLocation (const std::string &locationPath, const IMATH_NAMESPACE::M44d &xform, bool isFinal)=0 |
| Applies a transformation to a given manipulated location. | |
| virtual IMATH_NAMESPACE::M44d | applyManipulationXform (const IMATH_NAMESPACE::M44d &xform, const std::string &locationPath) |
| Transform from manipulation space to transform component space. | |
| IMATH_NAMESPACE::M44d | calculateXform (const std::string &locationPath, bool includeComponent=false) |
| Calculates the manipulator transform. | |
| virtual void | calculateAndSetLocalXform (const std::string &locationPath) |
| Updates the handle's Local Transform. | |
| SnappingData | pickSnappingTarget (const Vec2i &mousePosition) |
| Fetches snapping data to snap the Manipulator Handle. | |
| void | setAllLocationsOrientation (const IMATH_NAMESPACE::M44d &rotateMatrix, bool isFinal) |
| Sets all locations' orientation to the given rotation. | |
| void | restoreAllLocationsXform () |
| Restores original transformation in all manipulated locations. | |
Static Protected Member Functions | |
| static bool | isSnapWithOrientation (const SnappingData &snappingData) |
Protected Attributes | |
| int | m_handlePriority |
A base class for a GL based Transform ManipulatorHandle.
This is a base class implementation of GLManipulatorHandle for editing transform component parameters/attributes.
The handle can specify its own orientation (object, world, view) by implementing getOrientation() in the subclass. The orientation will affect the Local Transform of the handle. This is calculated in calculateAndSetLocalXform(), which (like in GLTransformManipulator) is called in draw() and pickerDraw(). This guarantees that the latest cooked information is used in cases like in object space orientation, which depends on the rotation of the location where the manipulator is placed.
Each manipulator affects a specific transform component (rotation, scale, translation), and the corresponding attribute name should be specified by extending getComponentName().
The manipulator class of a GLTransformManipulatorHandle should extend GLTransformManipulator.
** The dragging-to-location values transformation algorithm **
The Orientation Transform (getOrientationXform()) is then used in two ways:
A location's Component Transform is defined by its parent location's transform and all the transform components (rotation, translation, scaling) that are applied after the one being manipulated (see ViewerDelegate::getPartialXform()). This is essential to allow the correct manipulation of the component values in different transform orders (SRT, RTS, TSR, etc).
The way a local dragging is transferred to each of the location's local space is via the Manipulation Transform (applyManipulationXform()). This is different for each location and is defined by the its Orientation Transform and by the location's Component Transform. This allows a drag on a given orientation to be correctly applied to each location, even if they contain different transformation orders and when the orientation type depends on the location's transform (like in object space).
This is achieved by implementing the GLManipulator::drag() function in the subclass. This should detect a dragging in the handle's Local Space, because when dragging a handle the manipulator's position and scale calculated by the Manipulator Transform is irrelevant. The delta value should then be converted into a delta matrix that applies that transformation in local space. For example, in a translate manipulator axis handle, this delta matrix should contain just a translation on that axis. Then this matrix should be passed to the applyXformToAllLocations() function as the 'xform' argument. This, in turn, will iterate through each location, apply the corresponding Manipulation Matrix, that turns the local space transform into the location's correct component space and pass it to the virtual function applyXformToLocation(). This function should then be implemented by the subclass, which will apply this transformation to the location's values via the Manipulator::setValue() call.
The transformation matrix calculated in drag() can be relative to either the previous dragging value or to the initial dragging value, and applyXformToLocation() needs to follow that decision in order to produce the correct values.
Summary of the algorithm:
1 - When a mouse drag starts the initial location transforms are cached via get____XformFromLocation(), which should use Manipulator::getValue() to collect the transformation for the component being manipulated
2 - In the function drag() transform a dragged delta value into a local delta transform and there are two options: 2.1 - Apply the delta transform to all the location via applyXformToAllLocations() (go to 3); 2.2 - Apply the delta transform to only one location. Make sure the Manipulation Transform to it via applyManipulationXform() and pass the result to applyXformToLocation() (go to 4)
3 - applyXformToAllLocations() iterates through each location and applies the Manipulation Transform to the local delta transform, passing the resulting location component's space delta matrix to applyXformToLocation() on each location;
4 - applyXformToLocation() will then apply the delta transform to either the initial transform or to the current one (which can be retrieved via get____XformFromLocation()).
5 - Finally, applyXformToLocation() will extract the xform component values from the resulting transformation and set them back into Katan via Manipulator:setValue()
| Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::GLTransformManipulatorHandle | ( | bool | alwaysAtLocationOrigin | ) | [explicit] |
Constructor.
| alwaysAtLocationOrigin | Specifies if this manipulator should always be placed at the location's origin. Some manipulators (example: rotate, scale) have to be placed in a pivot position in some transform orders. Others, like the translate, can always be placed wherever the manipulated object is. |
| virtual IMATH_NAMESPACE::M44d Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::applyManipulationXform | ( | const IMATH_NAMESPACE::M44d & | xform, |
| const std::string & | locationPath | ||
| ) | [protected, virtual] |
Transform from manipulation space to transform component space.
This defines the transformation from manipulation space to the transform component that is being edited (scale, translate, rotate).
The transform order will affect the component space.
Manipulation space is defined by the amount that each of the axis is affected during dragging. The position of the manipulator is irrelevant, so only its orientation is involved in the calculation of this space.
This is used to transform dragged values in local space into values that can be set in the component's node graph parameters.
| void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::applyXformToAllLocations | ( | const IMATH_NAMESPACE::M44d & | xform, |
| bool | isFinal | ||
| ) | [protected] |
Applies a transformation to all the manipulated locations.
This calls applyXformToLocation() on each of the manipulated locations. The transformation is in manipulator's local space, and is transformed by the Manipulation Transform (see applyManipulationXform()) in order to be correctly applied to the locations' transform component attributes or node parameters via applyXformToLocation().
See Manipulator::setValue() for the definition of the isFinal flag.
| virtual void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::applyXformToLocation | ( | const std::string & | locationPath, |
| const IMATH_NAMESPACE::M44d & | xform, | ||
| bool | isFinal | ||
| ) | [protected, pure virtual] |
Applies a transformation to a given manipulated location.
This is meant to be implemented by subclasses and should use the method Manipulator::setValue() to set the new transform attributes/parameters back into Katana. This new transform can be calculated by applying the given xform to either the initial transform at drag start (initialXform) or to the current location's transform, via Manipulator::getValue() or get____XformFromLocation(). The decision of using a transform relative to the initial or current values is made in the implementation of the drag() function.
See Manipulator::setValue() for the definition of the isFinal flag.
This will be typically called by applyXformToAllLocations().
Implemented in GLCoiHandle, GLRotateAxisHandle, GLRotateBallHandle, GLScaleAxisHandle, GLScalePlaneHandle, GLScaleUniformHandle, GLTranslateAxisHandle, GLTranslatePlaneHandle, and GLTranslateScreenPlaneHandle.
| virtual void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::calculateAndSetLocalXform | ( | const std::string & | locationPath | ) | [protected, virtual] |
Updates the handle's Local Transform.
Called by draw() and pickerDraw() and uses the transform of the last manipulated location, where the manipulator is placed. This internally calls GLManipulatorHandle::setLocalXform() in order to cache the local transform.
In the default implementation if this method, the Local Transform is defined by the Orientation Transform given by getOrientationXform().
Reimplemented in GLTranslateAxisHandle, GLTranslatePlaneHandle, and GLTranslateScreenPlaneHandle.
| IMATH_NAMESPACE::M44d Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::calculateXform | ( | const std::string & | locationPath, |
| bool | includeComponent = false |
||
| ) | [protected] |
Calculates the manipulator transform.
Used by the GLTransformManipulatorHandle::draw() and pickerDraw(). This also caches the manipulator scale and origin returned by getScale() and getOrigin().
| locationPath | The path of the scene graph location for which to calculate the manipulator transform matrix. |
| includeComponent | In cases where the Manipulator is not placed on the COI or at the object Origin this boolean specifies whether we should apply the current component to the Xform. This is useful for the translate manipulator where we want to include the object's current translation when drawing the manipulator. (Default: false) |
| virtual void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::cancelManipulation | ( | ) | [virtual] |
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.
Reimplemented from Foundry::Katana::ViewerUtils::GLManipulatorHandle.
| virtual void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::drag | ( | const Vec3d & | initialPointOnPlane, |
| const Vec3d & | previousPointOnPlane, | ||
| const Vec3d & | currentPointOnPlane, | ||
| const Vec2i & | initialMousePosition, | ||
| const Vec2i & | previousMousePosition, | ||
| const Vec2i & | currentMousePosition, | ||
| bool | isFinal | ||
| ) | [inline, protected, virtual] |
Called when a mouse dragging occurs.
This must be implemented by the child classes. This must transform a dragging value into a local transform. This should then be passed to applyXformToAllLocations() in order to be applied to every location. If only one location is meant to be transformed, then applyXformToLocation() should be used, and xform should be transformed by getOrientationXform() and the result should be passed to applyXformToLocation().
Reimplemented from Foundry::Katana::ViewerUtils::GLManipulatorHandle.
Reimplemented in GLRotateAxisHandle, GLRotateBallHandle, GLScaleAxisHandle, GLScalePlaneHandle, GLScaleUniformHandle, and GLTranslateAxisHandle.
| virtual void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::draw | ( | ) | [virtual] |
Draws the handle.
This must be called by the implementation on child classes in order to bind the standard shader (see GLManipulator::draw()) and to calculate and set the handle's local xform. Since the transform of the location where the manipulator is positioned can change when it is cooked, this has to be recalculated here.
Reimplemented from Foundry::Katana::ViewerUtils::GLManipulatorHandle.
Reimplemented in GLCoiHandle, GLRotateAxisHandle, GLRotateBallHandle, GLScaleAxisHandle, GLScalePlaneHandle, GLScaleUniformHandle, GLTranslateAxisHandle, GLTranslatePlaneHandle, and GLTranslateScreenPlaneHandle.
| void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::endDrag | ( | ) | [protected, virtual] |
Called when a mouse dragging ends.
This must be called by the implementation on child classes. It clears the cache with the initial Local Transform matrices at drag start for each manipulated location.
See GLManipulator::endDrag()
Reimplemented from Foundry::Katana::ViewerUtils::GLManipulatorHandle.
Reimplemented in GLRotateAxisHandle, GLScaleAxisHandle, GLTranslateAxisHandle, GLTranslatePlaneHandle, and GLTranslateScreenPlaneHandle.
| IMATH_NAMESPACE::V3d Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::getCameraRayDirection | ( | ) | [protected] |
Returns the direction between the manipulator's projection onto window space and the camera origin (i.e. the direction of the ray towards the manipulator's origin). Used in isParallelToCamera() and isPerpendicularToCamera().
| virtual std::string Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::getComponentName | ( | ) | [pure virtual] |
The transform component (trans, rot, scale) attribute full name.
This is used when calculating the manipulator's transform, and is fed to ViewerDelegate::getPartialXform() as the componentName argument.
Examples: xform.interactive.translate xform.interactive.rotate?
Implemented in GLCoiHandle, GLRotateAxisHandle, GLRotateBallHandle, GLScaleAxisHandle, GLScalePlaneHandle, GLScaleUniformHandle, GLTranslateAxisHandle, GLTranslatePlaneHandle, and GLTranslateScreenPlaneHandle.
| Vec4f Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::getDisplayColor | ( | const Vec4f & | color | ) |
Gets the display color for handles.
This will return the display color for the handles based on if is hovered or active, the color passed as argument is the color to use if the handle is neither hovered or active.
| virtual Orientation Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::getOrientation | ( | ) | [virtual] |
Defines the orientation space of the manipulator.
This uses a "ManipulatorOrientation" option set on the Viewport that specifies the orientation for the manipulator. This option's value is an integer with the correspondent Orientation enum value.
Reimplemented in GLRotateAxisHandle, GLRotateBallHandle, GLScaleAxisHandle, GLScalePlaneHandle, GLScaleUniformHandle, and GLTranslateScreenPlaneHandle.
| IMATH_NAMESPACE::V3d Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::getOrigin | ( | ) | [inline] |
| double Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::getScale | ( | ) | [inline] |
Gets the uniform scale of the manipulator in world space.
This returns the manipulator's scale value cached in the previous draw() call, which calculates the manipulator's transform. If draw() hasn't been called recently this value can be out of date. This is the scale value that keeps the manipulator with constant size on the Viewport.
| TransformMode Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::getTransformMode | ( | ) | [inline] |
Gets the mode for the manipulator's handle.
Manipulators such as the Translate or Rotate manipulator make use of this property to correctly tweaks the objects' xform.
| static bool Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::isSnapWithOrientation | ( | const SnappingData & | snappingData | ) | [static, protected] |
Returns whether the given SnappingData describes a snapping target point with valid orientation information.
| virtual void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::pickerDraw | ( | int64_t | pickerID | ) | [virtual] |
Draws the handle for picking using the passed picker ID.
This must be called by the implementation on child classes in order to bind the standard shader (see GLManipulator::draw()) and to calculate and set the handle's local xform. Since the transform of the location where the manipulator is positioned can change when it is cooked, this has to be recalculated here.
Reimplemented from Foundry::Katana::ViewerUtils::GLManipulatorHandle.
Reimplemented in GLRotateAxisHandle, GLRotateBallHandle, GLScaleAxisHandle, GLScalePlaneHandle, GLScaleUniformHandle, GLTranslateAxisHandle, GLTranslatePlaneHandle, and GLTranslateScreenPlaneHandle.
| SnappingData Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::pickSnappingTarget | ( | const Vec2i & | mousePosition | ) | [protected] |
Fetches snapping data to snap the Manipulator Handle.
This calls `pick` on the `SnappingLayer` to determine if there is any snapping point in the surrounds of the mouse position. The area size will be retrieved from the manipulator.
This method will return useful data to decide where and how to snap the Manipulator Handle. The Snapping Data will contain a boolean indicating whether the handle should snap or not, the snapping point and the normal adjust orientation.
| void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::placeOnCenterOfInterest | ( | bool | placeOnCoi | ) | [inline] |
Indicates whether the manipulator should be placed on the center of interest.
The property is used in calculateAndSetXform().
| void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::restoreAllLocationsXform | ( | ) | [protected] |
Restores original transformation in all manipulated locations.
Restores to the original transformation all locations being currently manipulated.
| void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::setAllLocationsOrientation | ( | const IMATH_NAMESPACE::M44d & | rotateMatrix, |
| bool | isFinal | ||
| ) | [protected] |
Sets all locations' orientation to the given rotation.
Sets the orientation of all the locations being currently manipulated to the given Rotation Matrix.
| void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::setTransformMode | ( | TransformMode | transformMode | ) | [inline] |
Sets the mode for the manipulator's handle.
Manipulators such as the Translate or Rotate manipulator make use of this property to correctly tweaks the objects' xform.
| void Foundry::Katana::ViewerUtils::GLTransformManipulatorHandle::startDrag | ( | const Vec3d & | initialPointOnPlane, |
| const Vec2i & | initialMousePosition | ||
| ) | [protected, virtual] |
Called when a mouse dragging occurs.
This must be called by the implementation on child classes. It caches the initial Local Transform matrices at drag start for each manipulated location, which are then provided to applyXformToLocation() in order to calculate the resulting transform for those locations.
See GLManipulator::startDrag()
Reimplemented from Foundry::Katana::ViewerUtils::GLManipulatorHandle.
Reimplemented in GLRotateAxisHandle, GLRotateBallHandle, GLScaleAxisHandle, and GLTranslateAxisHandle.
The priority of the handle for selection
1.7.3
