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 bone
  • Rotation — - 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 bone
  • OutRotation — - 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 effector
  • Rotation — - the Character Space rotation of the effector as a quaternion
  • RotateBone — - if True, affected Bone will rotate to match effector rotation
  • RotateLimb — - 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 directions
  • NegativePullFactor — - 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 parent
  • MaxAngles — - maximum allowable X, Y and Z rotations relative to parent
  • NegateXAxis — - 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 bone
  • OutMinLimits — - minimum allowable X, Y and Z rotations relative to parent
  • OutMaxLimits — - maximum allowable X, Y and Z rotations relative to parent
  • OutNegateXAxis — - consider limits in opposite direction along X-axis
  • HasLimits — - 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 pose
  • BoneIndex — - the index of the bone (as passed to AddBone)
  • Returns: - SUCCESS or OUT_OF_BOUNDS if BoneIndex is invalid