A
DAG node that can contain a list of DAG nodes.
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.
