math: Add quaternion module.

1 files changed, 40 insertions, 0 deletions

diff --git a/doc/api.texi b/doc/api.texi
index eaad84e..f5a2400 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -410,6 +410,7 @@ detection.
 * Basics::                      Commonly used, miscellaneous things.
 * Vectors::                     Euclidean vectors.
 * Matrices::                    Transformation matrices.
+* Quaternions::                 Rotations.
 * Rectangles::                  Axis-aligned bounding boxes.
 * Easings::                     Easing functions for interesting animations.
 @end menu
@@ -434,6 +435,45 @@ Half of @var{pi}.
 @node Matrices
 @subsection Matrices
 
+@node Quaternions
+@subsection Quaternions
+
+In game development, the quaternion is most often used to represent
+rotations.  Why not use a matrix for that, you may ask.  Unlike
+matrices, quaternions can be interpolated (animated) and produce a
+meaningful result.  When interpolating two quaternions, there is a
+smooth transition from one rotation to another, whereas interpolating
+two matrices would yield garbage.
+
+@deffn {Procedure} quaternion @var{x} @var{y} @var{z} @var{w}
+Return a new quaternion with values @var{x}, @var{y}, @var{z}, and
+@var{w}.
+@end deffn
+
+@deffn {Procedure} quaternion? @var{obj}
+Return @code{#t} if @var{obj} is a quaternion.
+@end deffn
+
+@deffn {Procedure} quaternion-w @var{q}
+Return the W component of the quaternion @var{q}.
+@end deffn
+
+@deffn {Procedure} quaternion-x @var{q}
+Return the X component of the quaternion @var{q}.
+@end deffn
+
+@deffn {Procedure} quaternion-y @var{q}
+Return the Y component of the quaternion @var{q}.
+@end deffn
+
+@deffn {Procedure} quaternion-z @var{q}
+Return the Z component of the quaternion @var{q}.
+@end deffn
+
+@deffn {Procedure} make-identity-quaternion
+Return the identity quaternion.
+@end deffn
+
 @node Rectangles
 @subsection Rectangles