PowerIK::Solver Class
Documentation
Solver()
Creates a new instance of a PowerIK solver. Do this once per animated skeleton.
void Solve(const float DeltaTime, const float Alpha) const
Call this every tick to generate a new pose based on the input pose and the effectors.
- Parameters:
DeltaTime
— - the time (in seconds since the last call to Solve(). PowerIK is deterministic, this is only needed for effector smoothing.Alpha
— - blend the entire effect of the solver off and on (0-1). At 0, the solve is skipped entirely and the input pose is completely unchanged.
void Reset() const
Call this to reset all internal data structures. Will not deallocate. Useful for recycling solver memory.
void SetNumBones(int NumBones) const
Call this on a new Solver() or only AFTER calling Reset() to expand/allocate space for a new skeleton.
int GetNumBones() const
- Returns: - int, number of bones in the solver
PowerIKErrorCode AddBone( const int BoneIndex, const char* BoneName, const int ParentIndex) const
Call this for each bone AFTER calling SetNumBones(). Supplies hierarchy information to solver.
- Parameters:
BoneIndex
— - the index of the bone. Index must be >= 0 and less than NumBones.BoneName
— - the string name of the Bone. This name must match the name passed to AddEffector()ParentIndex
— - the index of the bone this bone is parented to or -1 for the root (no parent).- Returns: - SUCCESS or OUT_OF_BOUNDS if either BoneIndex or ParentIndex are invalid
PowerIKErrorCode AddEffector( const char* BoneName, int& OutEffectorIndex) const
Call this AFTER called AddBone() for the whole skeleton. Adds an effector to a given bone (by name).
- Parameters:
BoneName
— - the string name of the Bone to affect. This name must match the name passed to AddBone().OutEffectorIndex
— - the index of the newly created effector. Store this and use it in SetEffectorTransform()- Returns: - SUCCESS or FAILURE if BoneName is invalid
int GetNumEffectors() const
Get how many effectors have been added to the solver.
- Returns: - int, number of effectors in the solver
const char* GetEffectorName(const unsigned int EffectorIndex)
Get name of the bone associated with the given effector.
- Returns: - a pointer to array of char holding the name of the bone for the effector. Returns empty string if index is out of range.
PowerIKErrorCode SetRootBone(const int BoneIndex) const
Tell the solver what the root bone is. All bones ABOVE the root are culled from the solver entirely.
- Parameters:
BoneIndex
— - all of the ground settings - Returns: - SUCCESS or OUT_OF_BOUNDS if BoneIndex is invalid
const char* GetRootBoneName() const
Get name of the currently set root bone.
- Returns: - a pointer to array of char holding the name of the root bone. Returns empty string if no root has been set.
void SetSolverSettings(const SolverSettings& Settings) const
Optional method to modify internal solver settings like iteration counts.
- Parameters:
Settings
— - all the solver settings
void SetCOGSettings(const CenterOfGravitySettings& Settings) const
Optional method to setup Center of Gravity constraint on root bone.
- Parameters:
Settings
— - all of the center of gravity settings
void SetBoneTransform( const int BoneIndex, const Vec3& Position, const Quat& Rotation) const
Call this every tick, for each bone, before Solve() to update the input pose.
- Parameters:
BoneIndex
— - the index of the bone. Index must be >= 0 and less than NumBones.Position
— - the Character Space 3d position of the boneRotation
— - the Character Space rotation of the bone as a quaternion
void GetBoneTransform( const int BoneIndex, Vec3& OutPosition, Quat& OutRotation) const
Call this every tick, for each bone, AFTER Solve() to get the generated output pose.
- Parameters:
BoneIndex
— - the index of the bone. Index must be >= 0 and less than NumBones.OutPosition
— - the Character Space 3d position of the boneOutRotation
— - the Character Space rotation of the bone as a quaternion
PowerIKErrorCode SetEffectorTransform( const int EffectorIndex, const Vec3& Position, const Quat& Rotation, const bool RotateBone, const bool RotateLimb) const
Optionally call this every tick, for each effector, before Solve() to update the effector transform settings.
- Parameters:
EffectorIndex
— - the index of the effector (as returned from AddEffector)Position
— - the Character Space 3d position of the effectorRotation
— - the Character Space rotation of the effector as a quaternionRotateBone
— - if True, affected Bone will rotate to match effector rotationRotateLimb
— - if True, Bones near this effector will be rotated with the effector- Returns: - SUCCESS or OUT_OF_BOUNDS if EffectorIndex is invalid
PowerIKErrorCode SetEffectorWeights( const int EffectorIndex, const float Alpha, const float PullWeight, const bool NormalizePulling, const Vec3& PositivePullFactor, const Vec3& NegativePullFactor) const
Optionally call this every tick, for each effector, before Solve() to update the effector weight settings.
- Parameters:
EffectorIndex
— - the index of the effector (as returned from AddEffector)Alpha
— - used to blend the effect of the effector on/off. Ranges from 0 to 1.PullWeight
— - determines the degree of effect this effector has on the rest of the body. Normalized relative to all other PullWeight values.NormalizePulling
— - if True, total PullWeight on body is normalized to 1 to avoid over/under shooting.PositivePullFactor
— - multiplies effect of this effector on the rest of the body in the positive directionsNegativePullFactor
— - multiplies effect of this effector on the rest of the body in the negative directions- Returns: - SUCCESS or OUT_OF_BOUNDS if EffectorIndex is invalid
PowerIKErrorCode SetEffectorSettings( const int EffectorIndex, const float DeltaSmoothSpeed, const bool AffectsCenterOfGravity) const
Optionally call this every tick, for each effector, before Solve() to update the effector weight settings.
- Parameters:
EffectorIndex
— - the index of the effector (as returned from AddEffector)DeltaSmoothSpeed
— - speed in centimeters per second that this effector adjusts to changing ground height.AffectsCenterOfGravity
— - multiplies effect of this effector on the rest of the body in the negative directions- Returns: - SUCCESS or OUT_OF_BOUNDS if EffectorIndex is invalid
PowerIKErrorCode SetEffectorSmoothing( const int EffectorIndex, const EffectorSmoothingSettings& Settings) const
Optionally call this to smooth an effector's position and/or rotation over time
- Parameters:
EffectorIndex
— - the index of the effector (as returned from AddEffector)Settings
— - the position and rotation smoothing settings- Returns: - SUCCESS or OUT_OF_BOUNDS if EffectorIndex is invalid
PowerIKErrorCode SetEffectorPoleVector( const int EffectorIndex, const EffectorPoleVector& PoleVector) const
Optionally call this to specify an Effector's pole vector settings
- Parameters:
EffectorIndex
— - the index of the effector (as returned from AddEffector)PoleVector
— - the settings defining the Pole Vector behavior- Returns: - SUCCESS or OUT_OF_BOUNDS if EffectorIndex is invalid
PowerIKErrorCode SetBoneBendDirection( const int BoneIndex, const Vec3& Direction) const
Optionally call this to specify a custom bending direction for a single bone
- Parameters:
BoneIndex
— - the index of the bone (as passed to AddBone)Direction
— - a 3d vector in the local space of the bone that is the direction the bone will move in when bending- Returns: - SUCCESS or OUT_OF_BOUNDS if BoneIndex is invalid
PowerIKErrorCode SetBoneLimits( const int BoneIndex, const float Stiffness, const bool UseLimits, const Vec3& MinAngles, const Vec3& MaxAngles, const bool NegateXAxis) const
EXPERIMENTAL! Optionally call this to specify a set of limits and stiffness for a bone
- Parameters:
BoneIndex
— - the index of the bone (as passed to AddBone)Stiffness
— - ranges from 0 to 1. Default is 0. At 1 the bone is completely rigid and will be removed from the solve entirely.UseLimits
— - turn limits on/off.MinAngles
— - minimum allowable X, Y and Z rotations relative to parentMaxAngles
— - maximum allowable X, Y and Z rotations relative to parentNegateXAxis
— - consider limits in opposite direction along X-axis- Returns: - SUCCESS or OUT_OF_BOUNDS if BoneIndex is invalid
PowerIKErrorCode GetBoneLimits( const int BoneIndex, Vec3& OutMinLimits, Vec3& OutMaxLimits, bool& OutNegateXAxis, bool& HasLimits) const
Optionally call this to get the limits for a bone. If the bone has no limits
- Parameters:
BoneIndex
— - the index of the boneOutMinLimits
— - minimum allowable X, Y and Z rotations relative to parentOutMaxLimits
— - maximum allowable X, Y and Z rotations relative to parentOutNegateXAxis
— - consider limits in opposite direction along X-axisHasLimits
— - True if the bone has limits, false otherwise (all Out values will be untouched)- Returns: - SUCCESS or OUT_OF_BOUNDS if BoneIndex is invalid
PowerIKErrorCode ExcludeBone(const int BoneIndex) const
Exclude the given bone. It will be treated as 100% stiff and the solver will ignore it.
- Parameters:
BoneIndex
— - the index of the bone (as passed to AddBone) - Returns: - SUCCESS or OUT_OF_BOUNDS if BoneIndex is invalid
void TranslateSkeletonBeforeSolve(const Vec3& PositionOffset) const
Convenience method for providing global offsets to the skeleton to be applied internally before the main solver pass.
- Parameters:
PositionOffset
— - the amount to translate the entire skeleton
void RotateSkeletonBeforeSolve(const Quat& RotationOffset) const
Convenience method for providing global offsets to the skeleton to be applied internally before the main solver pass.
- Parameters:
RotationOffset
— - the amount to rotate the entire skeleton
PowerIKErrorCode RotateBoneBeforeSolve( const Quat& RotationOffset, const int BoneIndex) const
Convenience method for providing local rotate offsets to specific bones to be applied internally before the main solver pass.
- Parameters:
RotationOffset
— - character space rotation offset applied relative to input poseBoneIndex
— - the index of the bone (as passed to AddBone)- Returns: - SUCCESS or OUT_OF_BOUNDS if BoneIndex is invalid