AlGroupNode

Synopsis

#include <AlGroupNode.h>
class AlGroupNode : public AlDagNode
AlGroupNode();
virtual	~AlGroupNode();
virtual AlObject*	copyWrapper() const;
statusCode	create();
virtual AlObjectType	type() const;
AlDagNode*	childNode() const;
AlDagNode*	childNode(AlTM&) const;
AlGroupNode*	nextInstance() const;
AlGroupNode*	prevInstance() const;
statusCode	nextInstanceD();
statusCode	prevInstanceD();
boolean	isInstanceable();
boolean	isInstanceNode();
boolean	isAncestorAnInstance();
statusCode	addChildNode( AlDagNode* );
statusCode	applyIteratorToChildren( AlIterator*, int& );

Description

This class encapsulates the functionality for creating, manipulating and deleting a group node. A group node is a DAG node that refers to a list of child DAG nodes. It is this type of DAG node that allows the hierarchical grouping of DAG nodes.

The transformations that can be defined for a group node are inherited by each child DAG node. This means that a group node’s transformations are combined with a child node’s transformations to define a global transformation for the object that the child node refers to.

A group node’s list of child DAG nodes can be shared by more than one group node. If a group node’s list of child nodes is shared by another group node, both group nodes are considered "instanced". This can be achieved by using the AlDagNode::copyObject() method to create an instanced group node from another group node. The instanced group node is created as a sibling of the group node. There are methods for finding the next and previous instanced group node among its siblings and for determining whether a group node is an instanced node.

To create a group node, the user must call the constructor and then the create method for an AlGroupNode object. If a group node is not an instanced group node, deleting it will cause the deletion of all the child DAG nodes and the deletion of any objects the child DAG nodes refer to. Deleting an instanced group node will not cause all of its child nodes to be deleted since the list of child nodes is shared by another instanced group node.

Note on AlGroupNode::deleteObject()

If a group node is an instanced group node, then only the group node is removed from its list of siblings and is deleted. The list of child DAG nodes an instanced DAG node refers to is not deleted. If this group node is not an instanced group node (that is, none of its siblings share its list of child DAG nodes), then the group node is removed from the list of siblings it belongs to and the group node and every child node of the group node is deleted.

AlGroupNode::AlGroupNode()

Description

Constructs an AlGroupNode wrapper object. Use the create() method to initialize an AlGroupNode. Use the create() method to allocate a Dag_node data structure

AlGroupNode::~AlGroupNode()

Description

Destructor for AlGroupNode wrapper object.

AlObject* AlGroupNode::copyWrapper() const

Description

Returns an exact duplicate of this AlGroupNode wrapper.

statusCode AlGroupNode::create()

Description

Creates a new group node with no children.

Return Codes

sSuccess - group node was successfully created

sFailure - group node could not be created

AlObjectType AlGroupNode::type() const

Description

Returns the class identifier ’kGroupNodeType’.

boolean AlGroupNode::isInstanceable()

Description

Returns FALSE if this group node contains a non-instanceable DAG node. Otherwise it returns TRUE.

boolean AlGroupNode::isInstanceNode()

Description

Returns TRUE if this object shares its list of children with another sibling AlGroupNode.

boolean AlGroupNode::isAncestorAnInstance()

Description

Returns TRUE if this group node or one of its ancestors is an instance group node.

AlDagNode* AlGroupNode::childNode() const

Description

Returns a pointer to the first AlDagNode of its list of child AlDagNodes. Returns NULL if the list of children is empty.

AlDagNode* AlGroupNode::childNode(AlTM& tm) const

Description

Returns a pointer to the first AlDagNode of its list of child AlDagNodes. Returns NULL if the list of children is empty. The AlTM will be updated with the groupNode’s TM if a childNode exists.

Arguments

> tm - the transformation matrix to be updated with the groupNode’s TM

AlGroupNode* AlGroupNode::nextInstance() const

Description

Returns a pointer to the object’s next sibling node in the list that is an instanced group node. Returns NULL if there is no next instanced sibling.

AlGroupNode* AlGroupNode::prevInstance() const

Description

Returns a pointer to the object’s previous sibling node in the list that is an instanced group node. Returns NULL if there is no previous instanced sibling.

statusCode AlGroupNode::nextInstanceD()

Description

Destructively points this wrapper to the object’s next sibling node in the list that is an instanced group node.

Return Codes

sSuccess - wrapper now points to the next sibling

sFailure - there is no next instanced sibling

sInvalidObject - the groupnode was invalid

statusCode AlGroupNode::prevInstanceD()

Description

Destructively points this wrapper to the object’s previous sibling node in the list that is an instanced group node.

Return Codes

sSuccess - wrapper now points to the previous sibling

sFailure - there is no previous instanced sibling

sInvalidObject - the groupnode was invalid

statusCode AlGroupNode::addChildNode( AlDagNode *child )

Description

Adds an AlDagNode to the end of the list of child AlDagNodes. If the AlDagNode is already a child of this object, then nothing is done. Otherwise, the AlDagNode is removed from the list of siblings it belongs to and added to the end of this object’s list of children. If the AlDagNode is an AlGroupNode and it has siblings that are instanced AlGroupNodes, those instanced siblings are also made children of this object. It is illegal for the AlDagNode argument to be NULL or for it to not have had its create() method called.

Arguments

< child - the AlDagNode to be made a child of this object

Return Codes

sSuccess - the argument is now a child of this object

sInvalidArgument - ’child’ was not valid

sFailure - the AlDagNode could not be made a child of this object

sInvalidObject - the groupnode was invalid

statusCode AlGroupNode::applyIteratorToChildren( AlIterator* iter, int& rc )

Description

Applies the passed-in AlIterator to each of the children of this object.

Arguments

< iter - the iterator to apply to each child

> rc - the result of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied

sInvalidObject - the groupnode was invalid

AlIKHandle

Interface to Inverse Kinematics Handles.

Synopsis

#include <AlIKHandle.h>
class AlIKHandle : public AlObject , public AlAnimatable
AlIKHandle( void );
virtual	~AlIKHandle();
virtual statusCode	deleteObject();
virtual AlObject*	copyWrapper() const;
virtual AlObjectType	type() const;
statusCode	createSingle( AlJoint*, AlJoint* );
statusCode	createMulti( AlJoint*, AlJoint*,
AlIKHandleGoalType );
statusCode	createSpline (AlJoint*, AlJoint*, AlCurveNode*, AlIKHandle*);
statusCode	createSpline (AlJoint*, AlJoint*, AlCurveNode*);
boolean	on( void ) const;
AlIKHandleSolverType	solverType( void ) const;
AlIKHandleGoalType	goalType( void ) const;
double	weight( void ) const;
AlIKHandleRotationOrder	rotationOrder( void ) const;
boolean	worldOrientation( void ) const;
statusCode	restRotation( double[3] ) const;
AlJoint*	root( void ) const;
AlJoint*	endEffector( void ) const;
AlDagNode*	rootNode( void ) const;
AlDagNode*	endEffectorNode( void ) const;
AlIKHandlePositionType	positionType( void ) const;
AlIKHandleTwistType	twistType( void ) const;
AlCurveNode*	curveNode( void ) const;
boolean	oneJointHandle( void ) const;
boolean	touchRootHandle( void ) const;
AlIKHandlePositionType	splineChainPosition( double* ) const;
AlIKHandleTwistType	splineChainTwist( double* ) const;
double	splineChainRoll( void ) const;
statusCode	setOn( boolean );
statusCode	setGoalType( AlIKHandleGoalType );
statusCode	setWeight( double );
statusCode	setRotationOrder( AlIKHandleRotationOrder );
statusCode	setWorldOrientation( boolean );
statusCode	setRestRotation( const double[3] );
statusCode	assumeRestRotation( void );
statusCode	setPositionType( AlIKHandlePositionType );
statusCode	setTwistType ( AlIKHandleTwistType );
AlIKHandleNode*	handleNode( void ) const;

Description

A skeleton is a collection of joint DAG nodes that have no particularly special behavior until IK handles are applied to them. In order to use inverse kinematics in Alias, you must create IK handles that define paths along skeletons to be constrained by IK.

An IK handle is defined by two joints. The end effector is the point on the skeleton that is free to move, and the root is the anchor point on the skeleton. When the end effector is moved, the rotations on all joints leading up to the root are constrained to provide an IK solution.

The IK handle also specifies the solver that will be used. There are two kinds of IK solvers in Alias:

The single-chain solver is analytic and always produces a unique solution. Single-chain handles are never allowed to overlap other IK handles, except when the root of one handle meets the end effector of another.
Single-chain IK handles are always position handles - the rotations of the joints above the end-effector, and below or at the root, are transformed to meet the position of the end-effector.
The multi-chain solver is iterative, and the solution depends on the starting state. Multi-chain handles are allowed to interfere with one another, the result being a best-possible IK solution.
Multi-solver IK handles can be position or orientation goals or both. An orientation goal will try to match the orientation of the bone immediately above the end-effector to the orientation of the IK handle.

Multi-solver IK handles also have weights. When several multi-solver IK handles overlap, the weights on these handles are used to determine the relative effect each solution has on the overall rotation of the joints in the affected skeleton.

AlIKHandle::AlIKHandle()

Description

Constructs an AlIKHandle wrapper object.

AlIKHandle::~AlIKHandle()

Description

Deletes an AlIKHandle wrapper object.

AlObject *AlIKHandle::copyWrapper() const

Description

An object wrapper duplicator for AlIKHandle.

AlObjectType AlIKHandle::type() const

Description

Returns the class identifier kIKHandleType;

statusCode AlIKHandle::deleteObject( void )

Description

Deletes the actual handle corresponding to this AlIKHandle.

statusCode AlIKHandle::createSingle( AlJoint* root, AlJoint* end )

Description

Builds a new single-chain IK handle when given the root and end effector joints. Single-chain IK handles are always position handles.

Note: The chain from the root to the end should be on its rest pose before the single chain IK handle is created.

Arguments

< root - the root joint of the handle

< end - the end effector joint of the handle

Return Codes

sSuccess - successful completion

sInvalidArgument - either the root or the end was not valid

sFailure - the request could not be completed

statusCode AlIKHandle::createMulti(AlJoint* root, AlJoint* end, AlIKHandleGoalType goal )

Description

Builds a new multi-IK handle, given the root and end effector nodes and the goal type of the handle. Returns statusCode, indicating whether the IK handle was successfully constructed.

Arguments

< root - the root joint of the handle

< end - the end effector joint of the handle

< tp - the solver type for the handle: kSingleChain or kMultiSolver

< goal - specifies the kind of goal to give this handle: kPositionGoal, kOrientationGoal, or kBothGoal (position and orientation)

Return Codes

sSuccess - successful completion

sInvalidArgument - one of root or end was not valid

sFailure - the request could not be completed

statusCode AlIKHandle::createSpline(AlJoint* root, AlJoint* end, AlCurveNode* curve, AlIKHandle*& rHandle)

Description

Builds a pair of new spline IK handles: master spline handle and its root spline handle. You must specify the root, end joints and the curve to be matched with. The rHandle must be a NULL AlIKHandle pointer which is to be set with an associated one-joint spline handle for 'this' handle.

A root spline handle EQUALS a one-joint handle. It can only be created when a master spline handle is created. (That is, it cannot be created separately.)

A one-joint spline handle can be set to different position types with AlIKHandlePositionType.

A master spline handle can be set to different twist types with AlIKHandleTwistType.

This function creates spline handles in default position type (kParameter) and twist type (kTwist_Linear). They can be changed later by setPositionType() and setTwistType().

Arguments

<root - the root joint of the handle

<end - the end joint of the handle

<curve - the target of the handle

<rHandle - a reference for an empty AlIKHandle pointer

When return code is sSuccess:

>rHandle - may or may not be set. If set, the rHandle is a pointer to a created root spline handle.

Return Codes

sSuccess - successful completion

sInvalidArgument - one of root or end was not valid

sFailure - the request could not be completed

statusCode AlIKHandle::createSpline( AlJoint* root, AlJoint* end, AlCurveNode* curve)

Description

Builds a master spline handle without root spline handle. Requires the root and end joints, also the curve to be matched with.

This function creates a spline handle in default position type (kParameter) and twist type (kTwist_Linear). They can be changed later by setPositionType() and setTwistType().

Arguments

< root - the root joint of the handle

< end - the end joint of the handle

< curve - the target of the handle

Return Codes

sSuccess - successful completion

sInvalidArgument - one of root or end was not valid

sFailure - the request could not be completed

boolean AlIKHandle::on( void ) const

Description

Returns whether or not this IK handle is currently enabled.

AlIKHandleSolverType AlIKHandle::solverType( void ) const

Description

Returns the IK algorithm being used on this handle, multi-solver or single chain. If the object is not valid, single chain is returned.

AlIKHandleGoalType AlIKHandle::goalType( void ) const

Description

Returns the goal type of this AlIKHandle: kPositionGoal, kOrientationGoal, or kBothGoal.

double AlIKHandle::weight( void ) const

Description

Returns the weight on this IK handle. If the AlIKHandle is invalid, or not a multi-handle, -1 is returned.

AlIKHandleRotationOrder AlIKHandle::rotationOrder( void ) const

Description

Returns the rotation order applied to this IK handle. This method only applies to single-chain IK handles.

boolean AlIKHandle::worldOrientation( void ) const

Description

Returns true if this single-chain IK handle controls its rotate_plane in world space. Returns false if this IK handle is not a single-chain handle or controls its rotate plane in local space.

statusCode AlIKHandle::restRotation( double restRot[3] ) const

Description

Returns the rest rotation of the single-chain IK handle.

Arguments

> restRot - rest rotation of the single-chain IK handle.

Return Codes

sSuccess - the rest rotation was found

sInvalidArgument - the rest rotation is null

sInvalidObject - invalid IK handle

AlJoint* AlIKHandle::root( void ) const

Description

Gets the root AlJoint in the chain referenced by this IK handle.

AlJoint* AlIKHandle::endEffector( void ) const

Description

Gets the end effector AlJoint in the chain referenced by this IK handle.

AlDagNode* AlIKHandle::rootNode( void ) const

Description

Gets the AlDagNode corresponding to the root AlJoint in the chain referenced by this IK handle.

AlDagNode* AlIKHandle::endEffectorNode( void ) const

Description

Gets the AlDagNode corresponding to the end effector AlJoint in the chain referenced by this IK handle.

AlIKHandlePositionType AlIKHandle::positionType( void ) const

Description

Returns the position type of this AlIKHandle. This method only applies to spline handles.

AlIKHandleTwistType AlIKHandle::twistType( void ) const

Description

Returns the twist type of this AlIKHandle. This method only applies to spline handles.

AlCurveNode* AlIKHandle::curveNode( void ) const

Description

Gets the curve node (AlCurveNode) defined by this spline handle. This function only applies to spline handles.

boolean AlIKHandle::oneJointHandle( void ) const

Description

Returns true if this IK handle is a spline handle and is one joint handle.

boolean AlIKHandle::touchRootHandle( void ) const

Description

Returns true if this handle is a spline handle and directly under a one-joint spline handle.

AlIKHandlePositionType AlIKHandle::splineChainPosition(double* pos) const

Description

Returns the spline chain position in curve space.

AlIKHandleTwistType AlIKHandle::splineChainTwist(double *twist) const

Description

Returns the spline handle twist angle and type.

double AlIKHandle::splineChainRoll() const

Description

Returns the roll angle of a spline handle.

statusCode AlIKHandle::setOn( boolean f )

Description

Sets the IK handle on.

statusCode AlIKHandle::setGoalType( AlIKHandleGoalType tp )

Description

Sets the goal type of this IK handle to kPositionGoal, kOrientationGoal or kBothGoal. This method can only be used on multi-handles.

statusCode AlIKHandle::setWeight( double d )

Description

Sets the weight of this AlIKHandle to the passed-in value. Note that this can only be done for AlIKHandles that have a solver type of kMultiSolver.

statusCode AlIKHandle::setRotationOrder( AlIKHandleRotationOrder ro )

Description

Sets the rotation order of this IK handle to the passed-in value. This method only applies to single-chain IK handles.

statusCode AlIKHandle::setWorldOrientation( boolean set )

Description

If set to true, sets this single-chain IK handle to control its rotate-plane in world space. Otherwise, the rotate-plane is controlled in local space. This method only applies to single-chain IK handles.

statusCode AlIKHandle::setRestRotation( const double restRot[3] )

Description

Sets a new rest rotation for the single-chain IK handle.

Arguments

< restRot - rest rotation for this single-chain IK handle.

Return Codes

sSuccess - the rest rotation was set

sInvalidArgument - the value of the rest rotation was null

sInvalidObject - the single-chain IK handle is not valid

statusCode AlIKHandle::assumeRestRotation( void )

Description

Returns the single-chain IK handle to its rest pose.

Return Codes

sSuccess - the handle was returned to its rest pose

sInvalidObject - the single-chain IK handle is not valid

statusCode AlIKHandle::setPositionType( AlIKHandlePositionType type )

Description

Sets this spline handle’s position type. This method only applies to root spline handles (one-joint handles).

statusCode AlIKHandle::setTwistType( AlIKHandleTwistType type )

Description

Sets this spline handle’s twist type. This method only applies to master spline handles.

AlIKHandleNode* AlIKHandle::handleNode( void ) const

Description

Returns the IK handle node associated with this IK handle. Returns NULL if there is no attached IK handle node.