AlJoint

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

bulgeCode	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.
bulgeOrient	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.
bulgeScale	this value will scale the value of the bulge at any point by this amount.
bulgeSections	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.
sectionsAround	if bulgeSections is kBulgeEvenlySpaced, this defines the number of subdivisions around the bone.
sectionsAlong	if bulgeSections is kBulgeEvenlySpaced, this defines the number of subdivisions along the bone.
relateToParameter	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.
relateTo	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.
relateToNode	See explanation for relateTo. A copy of this string is made.
bulgeRange	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.