Record TQuaternion

Hierarchy
Properties

Unit

Declaration

type TQuaternion = record

Description

Quaternions are useful to represent rotations in 3D that can be easily applied and combined with other rotations. Note that, while this structure (and some, but not all, of it's methods) can handle any quaternion, you are usually interested only in unit quaternions, that can represent a 3D rotation.

Overview

Fields

Public Data: packed

Methods

Public class function ZeroRotation: TQuaternion; static;
Public procedure ToAxisAngle(out Axis: TVector3; out AngleRad: Single); overload;
Public function ToAxisAngle: TVector4; overload;
Public function ToRotationMatrix: TMatrix4;
Public function ToRotationMatrix3: TMatrix3;
Public function Rotate(const Point: TVector4): TVector4; overload;
Public function Rotate(const Point: TVector3): TVector3; overload;
Public function Conjugate: TQuaternion;
Public procedure ConjugateMe; deprecated 'use Q := Q.Conjugate';
Public function Normalize: TQuaternion;
Public procedure NormalizeMe; deprecated 'use Q := Q.Normalize';
Public procedure LazyNormalizeMe;
Public procedure LazyNormalize; deprecated 'use LazyNormalizeMe';
Public class operator * (const Q1, Q2: TQuaternion): TQuaternion;

Description

Fields

Public Data: packed
 

Methods

Public class function ZeroRotation: TQuaternion; static;

Quaternion representing "no rotation". Note: this is not a quaternion filled with zeros (the Data.Real component is 1.0), instead this is a unit quaternion that correctly represents "rotation by zero degrees/radians".

Public procedure ToAxisAngle(out Axis: TVector3; out AngleRad: Single); overload;

Calculate axis (will be normalized) and angle (will be in radians) of rotation encoded in unit quaternion Q. This is the reverse of QuatFromAxisAngle.

Public function ToAxisAngle: TVector4; overload;

Convert quaternion to a rotation axis and angle encoded in 4D vector. Axis is normalized if quaternion was also normalized (which is true if working with rotation quaternions). Angle is in radians.

Public function ToRotationMatrix: TMatrix4;

Calculate matrix doing rotation described by unit quaternion.

Public function ToRotationMatrix3: TMatrix3;
 
Public function Rotate(const Point: TVector4): TVector4; overload;

Rotate a point, treating this quaternion as a representation of 3D rotation. For this operation to make sense in 3D, this must be a "unit" quaternion (which is created by a function like QuatFromAxisAngle).

You can pass here TVector4, which is then understood to be a 3D position in homogeneous coordinates.

Public function Rotate(const Point: TVector3): TVector3; overload;
 
Public function Conjugate: TQuaternion;

Quaternion conjugation. This is just a fancy name for negating Data.Vector.

Public procedure ConjugateMe; deprecated 'use Q := Q.Conjugate';

Warning: this symbol is deprecated: use Q := Q.Conjugate

 
Public function Normalize: TQuaternion;

Make the quaternion normalized.

Public procedure NormalizeMe; deprecated 'use Q := Q.Normalize';

Warning: this symbol is deprecated: use Q := Q.Normalize

 
Public procedure LazyNormalizeMe;

Perform normalization but only if the quaternion is detected to be "significantly unnormalized". It checks if the quaternion needs normalization using fast VectorLenSqr, that is quaternion length is not needed for the check (sqrt not needed). Only if it's significantly different that 1.0, sqrt is done and quaternion is normalized.

This may be useful if you fear of eventual errors because of floating-point error cumulations, e.g. when you repeatedly multiply one quaternion by another, and yet another, and yet another etc. Calling this will trigger normalization from time to time (although will tolerate very small, epsilon-like, differences that are normal). Thus it prevents the quaternion from getting "too unnormalized".

Generally, this is not needed, as quaternions are nicely numerically stable (which means that quaternion "very slightly unnormalized" will only generate "very slightly wrong" results, so it's not that bad). And no, I didn't actually observe the need for this in my programs. But you can see it actually called when you use TMatrixExaminer and deliberately cause spinning by very very large value (e.g. run view3dscene and press and hold right key, this will cause model spinning very fast, which causes quat multiplication every frame). So possibly this would trigger incorrect quaternions at some point.

Anyway, this remains mostly a paranoid correctness measure.

Public procedure LazyNormalize; deprecated 'use LazyNormalizeMe';

Warning: this symbol is deprecated: use LazyNormalizeMe

 
Public class operator * (const Q1, Q2: TQuaternion): TQuaternion;

Multiply two quaternions.

Geometric interpretation: If these are unit quaternions representing rotations, multiplying them calculates one rotation that has the same effect as rotating by Q2 and then by Q1.

Normal of result is equal to norm of Q1 * norm of Q2 (in particular, multiplying unit quaternions (used for rotations) yields another unit quaternion for sure).


Generated by PasDoc 0.16.0.