Interface to joint node data.
Synopsis
#include <AlJoint.h>
class AlJoint : public AlObject
virtual ~AlJoint();
virtual AlObject* copyWrapper() const;
virtual AlObjectType type() const;
AlIKHandle* endEffectorHandle( void ) const;
AlIKHandle* firstRootHandle( void ) const;
AlIKHandle* nextRootHandle( const AlIKHandle* ) const;
statusCode nextRootHandleD( AlIKHandle* ) const;
statusCode applyIteratorToRootHandles( AlIterator*, int& );
statusCode useTransforms( boolean[3], boolean[3] ) const;
statusCode useLimits( boolean[3], boolean[3] ) const;
statusCode rotation( double[3], double[3], int[3] ) const;
statusCode translation( double[3], double[3], int[3] ) const;
statusCode restPose( double[3], double[3] ) const;
statusCode setUseTransforms( const boolean[3], const boolean[3] );
statusCode setUseLimits( const boolean[3], const boolean[3] );
statusCode setRotation( const double[3], const double[3], const int[3] );
statusCode setTranslation( const double[3], const double[3], const int[3] );
statusCode setRestPose( const double[3], const double[3] );
statusCode assumeRestPose( void );
boolean charJoint() const;
statusCode charJointLimits(double&, double&, AlJointInterpolationType&) const;
boolean useBulge() const;
statusCode bulgeAttributes(int*, int*, double*, AlBulgeSections*, int*, int*, AlDagNodeFields*, AlBulgeRelateTo*, char*, double*) const;
statusCode setCharJoint(boolean);
statusCode setCharJointLimits(double, double, AlJointInterpolationType);
statusCode setUseBulge(boolean);
statusCode setBulgeAttributes(int, int, double, AlBulgeSections, int, int, AlDagNodeFields, AlBulgeRelateTo, const char *, double);
AlDagNode* dagNode( void ) const;
Description
The AlJoint class allows access to the joint information on an AlDagNode.
The joint node is used by the inverse kinematic algorithm to define properties of a joint. The character joint attributes
are used to define properties of the bone below the joint for skinning operations. See the Alias reference books for information on skeletons, joints, constraints, IK, and character builder.
In general, minimum values must be less than maximum values and stiffness values must be between 0 and 100 inclusive.
AlJoint::~AlJoint()
Description
Deletes an AlJoint wrapper object.
AlObject *AlJoint::copyWrapper() const
Description
Object wrapper duplicator for AlJoint.
AlObjectType AlJoint::type() const
Description
Returns the class identifier kJointType;
AlJoint* AlJoint::asJointPtr()
Description
This virtual function returns a non-null pointer to itself, indicating that it is safe to cast to an object of this class.
AlIKHandle* AlJoint::endEffectorHandle( void ) const
Description
If this joint is the end effector in some IK chain, this method will return the AlIKHandle corresponding to that end effector.
If the joint is not an end effector, or if the wrapper is not valid, this method will return NULL.
AlIKHandle* AlJoint::firstRootHandle( void ) const
Description
If this joint is the root in some IK chain, this method will return the AlIKHandle corresponding to that root. If the joint
is not a root, or the wrapper is not valid, this method will return NULL.
AlIKHandle* AlJoint::nextRootHandle( const AlIKHandle* ali ) const
Description
Given that this joint is a root handle in some collection of IK chains, and the passed-in AlIKHandle refers to one of those
root handles, this method will return an AlIKHandle corresponding to the next root handle in the collection.
Arguments
< ali - IK handle from which to walk forward
statusCode AlJoint::nextRootHandleD( AlIKHandle* ali ) const
Description
Like AlJoint::nextRootHandle, but destructively sets the passed in AlIKHandle to point to the next root handle in the collection
of handles with roots at this joint. If this operation cannot be completed, the contents of the argument will be left unchanged
and sFailure will be returned.
Arguments
< ali - IK handle from which to walk forward
Return Codes
sSuccess - the method was successful
sInvalidArgument - the passed-in AlIKHandle is not valid
sInvalidObject - the joint is not valid
sFailure - the next root handle could not be obtained
statusCode AlJoint::applyIteratorToRootHandles( AlIterator* iter, int& rc )
Description
Applies the passed-in iterator (AlIterator) to the collection of AlIKHandles that have their roots at this AlJoint. See the
documentation for AlIterator for more information.
statusCode AlJoint::useTransforms( boolean translations[3], boolean rotations[3]) const
Description
Used to determine which transformations may be used on the joint. Transformations may be toggled on or off using the setUseTransforms()
method. If this joint is the root of a single chain IK handle, then all three rotations must be used.
Arguments
> translations - boolean array of states for the translations
> rotations - boolean array of states for the rotations
Return Codes
sSuccess - successful
sInvalidArgument - translations/rotations is NULL
sInvalidObject - invalid joint
sFailure - transformations could not be determined
statusCode AlJoint::useLimits( boolean translations[3], boolean rotations[3]) const
Description
Used to determine whether the limits for the joint transformations should be used. The use of the limits can be toggled on
or off using the setUseLimits() method.
Arguments
> translations - boolean array of limits for the translations
> rotations - boolean array of limits for the rotations
Return Codes
sSuccess - successful
sInvalidArgument - translations/rotations is NULL
sInvalidObject - invalid joint
statusCode AlJoint::rotation( double Min[3], double Max[3], int stiffness[3] ) const
Description
Used to determine min and max rotations for this joint, as well as the stiffness of the rotations. These values can be set
using the setRotation() method.
Arguments
> Min - minimum rotation angles
> Max - maximum rotation angles
> stiffness - stiffness of rotations
Return Codes
sSuccess - successful
sInvalidArgument - Min/Max/stiffness is NULL
sInvalidObject - invalid joint
statusCode AlJoint::translation( double Min[3], double Max[3], int stiffness[3] ) const
Description
Used to determine min and max translations for this joint, as well as the stiffness of the translations. These values can
be set using the setTranslation() method.
Arguments
> Min - minimum translations for the joint
> Max - maximum translation for the joint
> stiffness - stiffness of the translations
Return Codes
sSuccess - successful
sInvalidArgument - Min/Max/stiffness is NULL
sInvalidObject - invalid joint
statusCode AlJoint::restPose( double rotRest[3], double transRest[3] ) const
Description
Used to get rest pose of rotations and translations for this joint. These values can be set using the setRestPose() method.
Arguments
> rotRest - rest pose of rotations for the joint
> transRest - rest pose of translation for the joint
Return Codes
sSuccess - successful
sInvalidArgument - Min/Max/stiffness is NULL
sInvalidObject - invalid joint
statusCode AlJoint::setUseTransforms( const boolean translations[3], const boolean rotations[3] )
Description
Used to toggle on or off which transformations may be used on the joint. TRUE means that the transformation is toggled on
and FALSE means that it is toggled off.
Arguments
< translations - boolean array of states for the translations
< rotations - boolean array of states for the rotations
Return Codes
sSuccess - successful
sInvalidArgument - NULL argument passed
sInvalidObject - invalid joint
sFailure - transformations could not be set
statusCode AlJoint::setUseLimits(const boolean translations[3], const boolean rotations[3] )
Description
Used to toggle on or off whether the limits for the joint transformations should be used. TRUE means that the transformation
limits are toggled on and FALSE means that they are toggled off.
Arguments
< translations - boolean array of states for the translations
< rotations - boolean array of states for the rotations
Return Codes
sSuccess - successful
sInvalidArgument - NULL argument passed
sInvalidObject - invalid joint
sFailure - limits could not be set
statusCode AlJoint::setRotation( const double Min[3], const double Max[3], const int stiffness[3] )
Description
Used to set min and max rotations for this joint, as well as the stiffness of the rotations. The min must be less than the
max, and the stiffness must be between 0 and 100 inclusive.
Arguments
< Min - minimum rotation angles
< Max - maximum rotation angles
< stiffness - stiffness of the rotations
Return Codes
sSuccess - successful
sInvalidArgument - NULL argument passed
sInvalidObject - invalid joint
sFailure - rotations could not be set
statusCode AlJoint::setTranslation( const double Min[3], const double Max[3], const int stiffness[3] )
Description
Used to set min and max translations for this joint, as well as the stiffness of the translations. The min must be less than
the max, and the stiffness must be between 0 and 100 inclusive.
Arguments
< Min - minimum for the translations
< Max - maximum for the translations
< stiffness - stiffness of the translations
Return Codes
sSuccess - successful
sInvalidArgument - NULL argument passed
sInvalidObject - invalid joint
statusCode AlJoint::setRestPose( const double rot_rest[3], const double trans_rest[3] )
Description
Used to set rest pose of rotations and translations for this joint. If the min and max are out of rest pose, they will be
adjusted to the rest pose.
Note:
If this function is used on a hierarchy of joints (a skeleton), single-chain IK handles attached to this skeleton may also
need to be set with proper rest poses by using AlIKHandle::setRestRotation().
Arguments
< rot_rest - rest pose for the rotations
< trans_rest - rest pose for the translations
Return Codes
sSuccess - successful
sInvalidArgument - NULL argument passed
sInvalidObject - invalid joint
statusCode AlJoint::assumeRestPose( void )
Description
Used to resume rest pose of rotations and translations for this joint.
Note:
If this function is used on a hierarchy of joints (a skeleton), single-chain IK handles attached to this skeleton may also
need to be set to their rest poses by using AlIKHandle::assumeRestRotation().
Return Codes
sSuccess - successful
sInvalidObject - invalid joint
boolean AlJoint::charJoint() const
Description
Used to determine whether this particular joint is a character joint, and thus has character joint attributes. If this joint
is a character joint, TRUE is returned; otherwise, FALSE is returned.
statusCode AlJoint::charJointLimits(double &upper, double &lower, AlJointInterpolationType &interpolation) const
Description
Returns the upper and lower limits of the character joint bounds around this joint. It also returns the interpolation type
used to interpolate cluster percentages on the CVs between the lower and upper bound.
Arguments
> double &upper - upper limit of the joint bound
> double &lower - lower limit of the joint bound
> &interpolation - interpolation type
Return Codes
sSuccess - successful
sInvalidObject - invalid joint
sFailure - the limits could not be set
boolean AlJoint::useBulge() const
Description
Returns TRUE if the character joint specifies there to be bulging effects in the bone(s) below this joint. Otherwise, this
method returns FALSE.
statusCode AlJoint::bulgeAttributes(int *bulgeCode, int *bulgeOrient, double *bulgeScale, AlBulgeSections *bulgeSections,
int *sectionsAround, int *sectionsAlong, AlDagNodeFields *relateToParameter, AlBulgeRelateTo *relateTo, char *relateToNode,
double *bulgeRange) const
Description
Used to get the bulge attributes on a character joint. If any argument is NULL, then the attributes are not returned. Note
that if the ’relateToNode’ parameter is non-NULL, then a strcpy() will be used to assign the name of the node. It is up to
the caller of this routine to ensure that enough memory is allocated by relateToNode.
Arguments
See the method AlJoint::setBulgeAttributes().
Return Codes
sSuccess - successful
sInvalidObject - invalid joint
sFailure - the attributes could not be returned
statusCode AlJoint::setCharJoint(boolean isCharJoint)
Description
If isCharJoint is TRUE, this method makes this joint into a character joint. If isCharJoint is FALSE, the joint becomes just
an ordinary non-character joint.
Arguments
< isCharJoint - boolean to decide whether to make this a character joint
Return Codes
sSuccess - successful
sInvalidObject - invalid joint
statusCode AlJoint::setCharJointLimits(double upper, double lower,AlJointInterpolationType interpolation)
Description
Sets the upper and lower joint bounds limits on the character joint. These bounds are the percentage along the bone above
and below the joint. The values must be between 0 and 1. It also sets the interpolation type to be used between these two
bounds.
Arguments
< upper - upper joint bounds limit
< lower - lower joint bounds limit
< interpolation - interpolation type
Return Codes
sSuccess - successful
sInvalidArgument - upper or lower is outside of [0..1]
sInvalidObject - invalid joint
sFailure - the limits could not be set
statusCode AlJoint::setUseBulge(boolean useBulge)
Description
Used to describe this character joint as one defining a bulge or not. If useBulge is TRUE, then the bones below this joint
will receive bulging effects.
Return Codes
sSuccess - successful
sInvalidObject - invalid joint
sFailure - the bulge could not be set
statusCode AlJoint::setBulgeAttributes(int bulgeCode, int bulgeOrient, double bulgeScale, AlBulgeSections bulgeSections, int
sectionsAround, int sectionsAlong, AlDagNodeFields relateToParameter, AlBulgeRelateTo relateTo, const char *relateToNode,
double bulgeRange)
Description
Used to set the bulge attributes for a character joint. The bulge attributes apply to the bone(s) below this joint. Each of
the bulge attributes are described below
|
|
this is the code that identifies which bulge type will be used to create the bulge on the bone below this character joint.
The bulge code can be found in the "bulge_types" file in the ’misc_data’ directory of the current project.
|
|
|
this value should be 0 (X), 1 (Y) or 2 (Z). It represents the local axis to be used to specify the direction around the bone
that should be considered 0 degrees, when defining a particular bulge type. The local axis associated with a bone is at the
lower end of the bone. Thus, these bulging attributes define the bulge on the bone below this character joint, and the axis
used is the local axis from the joint at the other (lower) end of this bone.
|
|
|
this value will scale the value of the bulge at any point by this amount.
|
|
|
when doing a character builder "attach", the clusters that do the bulge can be placed one per "knot" on the defining bulge
type (kBulgeDefinition), or evenly spaced around and along the bone (kBulgeEvenlySpaced). In the latter case, the number of
clusters created will be up to sectionsAround*sectionsAlong.
|
|
|
if bulgeSections is kBulgeEvenlySpaced, this defines the number of subdivisions around the bone.
|
|
|
if bulgeSections is kBulgeEvenlySpaced, this defines the number of subdivisions along the bone.
|
|
|
when a bulge is created on a skin, expressions are created on clusters. This parameter defines the animation parameter of
the node which the expression will use.
|
|
|
if relateTo is kBulgeLowerJoint, then the expression on the cluster defining the bulge will be the joint node that is at the
other end of the bone from this character joint. If relateTo is kBulgeOtherNode, then the node used in the expression will
be the one defined by relateToNode.
|
|
|
See explanation for relateTo. A copy of this string is made.
|
|
|
When an expression is created, the bulging on the bone will occur when the value of the joint used in the expression is between
its current value, and its current value plus bulgeRange.
|
Return Codes
sSuccess - successful
sInvalidArgument - an argument is out of range
sInvalidObject - invalid joint
sFailure - the bulge could not be set
AlDagNode * AlJoint::dagNode( void ) const
Description
Returns the DAG node that this joint refers to.
