pfQuat(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQuat(3pf)NAME
pfMakeRotQuat, pfGetQuatRotMat, pfMakeRotMatQuat, pfMakeVecRotVecQuat,
pfGetQuatRot, pfLengthQuat, pfConjQuat, pfExpQuat, pfLogQuat, pfMultQuat,
pfDivQuat, pfInvertQuat, pfSlerpQuat, pfSquadQuat, pfQuatMeanTangent -
Set and operate on quaternions
FUNCTION SPECIFICATION
#include <Performer/pr.h>
#include <Performer/prmath.h>
void pfMakeRotQuat(pfQuat dst, float angle, float x, float y,
float z);
void pfGetQuatRotMat(pfQuat quat, pfMatrix m);
void pfMakeRotMatQuat(pfQuat quat, const pfMatrix m);
void pfMakeVecRotVecQuat(pfQuat quat, const pfVec3 rotateFrom,
const pfVec3 rotateTo);
void pfGetQuatRot(const pfQuat q, float *angle, float *x,
float *y, float *z);
float pfLengthQuat(const pfQuat q);
void pfConjQuat(pfQuat dst, const pfQuat q);
void pfExpQuat(pfQuat dst, const pfQuat q);
void pfLogQuat(pfQuat dst, const pfQuat q);
void pfMultQuat(pfQuat dst, const pfQuat q1, const pfQuat q2);
void pfDivQuat(pfQuat dst, const pfQuat q1, const pfQuat q2);
void pfInvertQuat(pfQuat dst, const pfQuat q);
void pfSlerpQuat(pfQuat dst, float t, const pfQuat q1,
const pfQuat q2);
void pfSquadQuat(pfQuat dst, float t, const pfQuat q1,
const pfQuat q2, const pfQuat a, const pfQuat b);
extern void pfQuatMeanTangent(pfQuat dst, const pfQuat q1,
const pfQuat q2, const pfQuat q3);
typedef pfVec4 pfQuat;
Page 1
pfQuat(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQuat(3pf)PARENT CLASS FUNCTIONS
The OpenGL Performer class pfQuat is derived from the parent class
pfVec4, so each of these member functions of class pfVec4 are also
directly usable with objects of class pfQuat. Casting an object of class
pfQuat to an object of class pfVec4 is taken care of automatically. This
is also true for casts to objects of ancestor classes of class pfVec4.
void pfAddScaledVec4(pfVec3 dst, const pfVec3 v1, float s,
const pfVec3 v2);
void pfAddVec4(pfVec4 dst, const pfVec4 v1, const pfVec4 v2);
int pfAlmostEqualVec4(pfVec4 v1, const pfVec4 v2, float tol);
void pfCombineVec4(pfVec4 dst, float s1, const pfVec4 v1, float s2,
const pfVec4 v2);
void pfCopyVec4(pfVec4 dst, const pfVec4 v);
float pfDistancePt4(const pfVec4 pt1, const pfVec4 pt2);
float pfDotVec4(const pfVec4 v1, const pfVec4 v2);
int pfEqualVec4(const pfVec4 v1, const pfVec4 v2);
float pfLengthVec4(const pfVec4 v);
void pfNegateVec4(pfVec4 dst, const pfVec4 v);
float pfNormalizeVec4(pfVec4 v);
void pfScaleVec4(pfVec4 dst, float s, const pfVec4 v);
void pfSetVec4(pfVec4 dst, float x, float y, float z, float w);
float pfSqrDistancePt4(const pfVec4 pt1, const pfVec4 pt2);
void pfSubVec4(pfVec4 dst, const pfVec4 v1, const pfVec4 v2);
void pfXformVec4(pfVec4 dst, const pfVec4 v, const pfMatrix m);
DESCRIPTION
pfQuat represents a quaternion as the four floating point values (x, y,
z, w) of a pfVec4.
pfMakeRotQuat converts an axis and angle rotation representation to a
quaternion. pfGetQuatRot is the inverse operation. It produces the axis
(as a unit length direction vector) and angle equivalent to the given
quaternion. Also see pfMakeQuatMat and pfGetOrthoMatQuat.
pfMakeRotMatQuat converts the rotation expressed by an orthonormal
pfMatrix to a pfQuat. If the pfMatrix is not orthonormal the results are
undefined (and will most certainly not be the rotation that you wanted).
pfGetQuatRotMat constructs a rotation matrix from the quaternion.
pfMakeVecRotVecQuat constructs a quaternion from the rotation between the
two vectors rotateFrom and rotateTo.
Several monadic quaternion operators are provided. pfConjQuat produces
the complex conjugate dst of q by negating only the complex components
(x, y, and z) which results in an inverse rotation. pfExpQuat and
pfLogQuat perform complex exponentiation and logarithm functions
respectively. The length of a quaternion is computed by pfLengthQuat and
is defined as the norm of all four quaternion components. Macro
equivalents are PFCONJ_QUAT and PFLENGTH_QUAT. For negation, use the
pfVec4 routine, pfNegateVec4.
Page 2
pfQuat(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQuat(3pf)
pfMultQuat and pfDivQuat are dyadic quaternion operations which provide
the product, and quotient of two quaternions. When quaternions are used
to represent rotations, multiplication of two quaternions is equivalent,
but more efficient, than the multiplication of the two correspondinging
rotation matrices.
pfInvertQuat computes the multiplicative inverse of a quaternion. These
operations are the basis from which the other quaternion capabilities
have been derived. Macro equivalents are PFMULT_QUAT, PFDIV_QUAT, and
PFINVERT_QUAT. For addition and scalar multiplication, use the pfVec4
routines pfAddVec4, pfSubVec4, and pfScaleVec4. Comparisons can be made
with pfEqualVec4 and pfAlmostEqualVec4.
Interpolation of quaternions (as presented by Ken Shoemake) is an
effective technique for rotation interpolation. Spherical linear
interpolation is performed with pfSlerpQuat, which produces a rotation
dst that is t of the way between q1 and q2.
Spherical quadratic interpolation is provided by pfSquadQuat and its
helper function, pfQuatMeanTangent.
NOTES
These functions use a pfVec4 to represent quaternions and store the
imaginary part first, thus the array contents q = {x,y,z,w} are a
representation of the quaternion w + xi + yj+ zk.
Because both q and -q represent the same rotation (quaternions have a
rotation range of [-360,360] degrees) conversions such as
pfGetOrthoMatQuat make an arbitrary choice of the sign of the returned
quaternion. To prevent the arbitrary sign from introducing large,
unintended rotations, pfSlerpQuat checks the angle theta between q1 and
q2. If theta exceeds 180 degrees, q2 is negated changing the
interpolations range from [0,theta] to [0, theta-360 degrees].
When using overloaded operators in C++, assignment operators, e.g. "+=",
are somewhat more efficient than the corresponding binary operators, e.g.
"+", because the latter construct a temporary intermediate object. Use
assignment operators or macros for binary operations where optimal speed
is important.
C++ does not support array deletion (i.e. delete[]) for arrays of objects
allocated new operators that take additional arguments. Hence, the array
deletion operator delete[] should not be used on arrays of objects
created with new(arena) pfVec4[n].
For more information on quaternions, see the article by Sir William Rowan
Hamilton "On quaternions; or on a new system of imaginaries in algebra,"
in the Philosophical Magazine, xxv, pp. 10-13 (July 1844). More recent
references include "Animating Rotation with Quaternion Curves," SIGGRAPH
Proceedings Vol 19, Number 3, 1985, and "Quaternion Calculus For
Animation," in "Math for SIGGRAPH", Course Notes, #23, SIGGRAPH 1989,
Page 3
pfQuat(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQuat(3pf)
both by Ken Shoemake. An introductory tutorial is available on the
Internet at ftp://ftp.cis.upenn.edu/pub/graphics/shoemake/quatut.ps.Z.
Note that for consistency with Performer's transformation order, pfQuats
are the conjugates of the quaternions described in these references.
SEE ALSO
pfVec4, pfMatrix
Page 4
