doc: Document vector and matrix math APIs.

1 files changed, 338 insertions, 0 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 5bfad7a..4ee287b 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -389,9 +389,347 @@ Return the cotangent of @var{z}.
 @node Vectors
 @subsection Vectors
 
+Unlike Scheme's vector data type, which is a sequence of arbitrary
+Scheme objects, Chickadee's @code{(chickadee math vector)} module
+provides vectors in the linear algebra sense: Sequences of numbers
+specialized for particular coordinate spaces.  As of now, Chickadee
+provides 2D and 3D vectors, with 4D vector support coming in a future
+release.
+
+Here's a quick example of adding two vectors:
+
+@example
+(define v (vec2+ (vec2 1 2) (vec2 3 4)))
+@end example
+
+Since vectors are used so frequently, the reader macro @code{#v} is
+used to cut down on typing:
+
+@example
+(define v (vec2+ #v(1 2) #v(3 4)))
+@end example
+
+@subsubsection A Note About Performance
+
+A lot of time has been spent making Chickadee's vector operations
+perform relatively efficiently in critical code paths where excessive
+garbage generation will cause major performance issues.  The general
+rule is that procedures ending with @code{!} perform an in-place
+modification of one of the arguments in order to avoid allocating a
+new vector.  These procedures are also inlined by Guile's compiler in
+order to take advantage of optimizations relating to floating point
+math operations.  The downside is that since these are not pure
+functions, they do not compose well and create more verbose code.
+
+@subsubsection 2D Vectors
+
+@deffn {Procedure} vec2 @var{x} @var{y}
+Return a new 2D vector with coordinates (@var{x}, @var{y}).
+@end deffn
+
+@deffn {Procedure} vec2/polar @var{r} @var{theta}
+Return a new 2D vector containing the Cartesian representation of the
+polar coordinate (@var{r}, @var{theta}).  The angle @var{theta} is
+measured in radians.
+@end deffn
+
+@deffn {Procedure} vec2? @var{obj}
+Return @code{#t} if @var{obj} is a 2D vector.
+@end deffn
+
+@deffn {Procedure} vec2-x @var{v}
+Return the X coordinate of the 2D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec2-y @var{v}
+Return the Y coordinate of the 2D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec2-copy @var{v}
+Return a fresh copy of the 2D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec2-magnitude @var{v}
+Return the magnitude of the 2D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec2-dot-product @var{v1} @var{v2}
+Return the dot product of the 2D vectors @var{v1} and @var{v2}.
+@end deffn
+
+@deffn {Procedure} vec2-normalize @var{v}
+Return the normalized form of the 2D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec2+ @var{v} @var{x}
+Add @var{x}, either a 2D vector or a scalar (i.e. a real number), to
+the 2D vector @var{v} and return a new vector containing the sum.
+@end deffn
+
+@deffn {Procedure} vec2- @var{v} @var{x}
+Subtract @var{x}, either a 2D vector or a scalar, from the 2D vector
+@var{v} and return a new vector containing the difference.
+@end deffn
+
+@deffn {Procedure} vec2* @var{v} @var{x}
+Multiply the 2D vector @var{v} by @var{x}, a 2D vector or a scalar,
+and return a new vector containing the product.
+@end deffn
+
+@deffn {Procedure} set-vec2-x! @var{v} @var{x}
+Set the X coordinate of the 2D vector @var{v} to @var{x}.
+@end deffn
+
+@deffn {Procedure} set-vec2-y! @var{v} @var{y}
+Set the Y coordinate of the 2D vector @var{v} to @var{y}.
+@end deffn
+
+@deffn {Procedure} vec2-copy! @var{source} @var{target}
+Copy the 2D vector @var{source} into the 2D vector @var{target}.
+@end deffn
+
+@deffn {Procedure} vec2-add! @var{v} @var{x}
+Perform an in-place modification of the 2D vector @var{v} by adding
+@var{x}, a 2D vector or a scalar.
+@end deffn
+
+@deffn {Procedure} vec2-sub! @var{v} @var{x}
+Perform an in-place modification of the 2D vector @var{v} by
+subtracting @var{x}, a 2D vector or a scalar.
+@end deffn
+
+@deffn {Procedure} vec2-mult! @var{v} @var{x}
+Perform an in-place modification of the 2D vector @var{v} by
+multiplying it by @var{x}, a 2D vector or a scalar.
+@end deffn
+
+@subsubsection 3D Vectors
+
+@deffn {Procedure} vec3 @var{x} @var{y}
+Return a new 2D vector with coordinates (@var{x}, @var{y}).
+@end deffn
+
+@deffn {Procedure} vec3? @var{obj}
+Return @code{#t} if @var{obj} is a 3D vector.
+@end deffn
+
+@deffn {Procedure} vec3-x @var{v}
+Return the X coordinate of the 3D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec3-y @var{v}
+Return the Y coordinate of the 3D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec3-z @var{v}
+Return the Z coordinate of the 3D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec3-copy @var{v}
+Return a fresh copy of the 3D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec3-magnitude @var{v}
+Return the magnitude of the 3D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec3-dot-product @var{v1} @var{v2}
+Return the dot product of the 3D vectors @var{v1} and @var{v2}.
+@end deffn
+
+@deffn {Procedure} vec3-normalize @var{v}
+Return the normalized form of the 3D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} vec3+ @var{v} @var{x}
+Add @var{x}, either a 3D vector or a scalar (i.e. a real number), to
+the 3D vector @var{v} and return a new vector containing the sum.
+@end deffn
+
+@deffn {Procedure} vec3- @var{v} @var{x}
+Subtract @var{x}, either a 3D vector or a scalar, from the 3D vector
+@var{v} and return a new vector containing the difference.
+@end deffn
+
+@deffn {Procedure} vec3* @var{v} @var{x}
+Multiply the 3D vector @var{v} by @var{x}, a 3D vector or a scalar,
+and return a new vector containing the product.
+@end deffn
+
+@deffn {Procedure} set-vec3-x! @var{v} @var{x}
+Set the X coordinate of the 3D vector @var{v} to @var{x}.
+@end deffn
+
+@deffn {Procedure} set-vec3-y! @var{v} @var{y}
+Set the Y coordinate of the 3D vector @var{v} to @var{y}.
+@end deffn
+
+@deffn {Procedure} set-vec3-z! @var{v} @var{z}
+Set the Z coordinate of the 3D vector @var{v} to @var{z}.
+@end deffn
+
+@deffn {Procedure} vec3-copy! @var{source} @var{target}
+Copy the 3D vector @var{source} into the 3D vector @var{target}.
+@end deffn
+
+@deffn {Procedure} vec3-add! @var{v} @var{x}
+Perform an in-place modification of the 3D vector @var{v} by adding
+@var{x}, a 3D vector or a scalar.
+@end deffn
+
+@deffn {Procedure} vec3-sub! @var{v} @var{x}
+Perform an in-place modification of the 3D vector @var{v} by
+subtracting @var{x}, a 3D vector or a scalar.
+@end deffn
+
+@deffn {Procedure} vec3-mult! @var{v} @var{x}
+Perform an in-place modification of the 3D vector @var{v} by
+multiplying it by @var{x}, a 3D vector or a scalar.
+@end deffn
+
 @node Matrices
 @subsection Matrices
 
+The @code{(chickadee math matrix)} module provides an interface for
+working with the most common type of matrices in game development: 4x4
+transformation matrices.
+
+@subsubsection Another Note About Performance
+
+Much like the vector API, the matrix API is commonly used in
+performance critical code paths.  In order to reduce the amount of
+garbage generated and improve matrix multiplication performance, there
+are many procedures that perform in-place modifications of matrix
+objects.
+
+@subsubsection Matrix Operations
+
+@deffn {Procedure} make-matrix4 @var{aa} @var{ab} @var{ac} @var{ad} @
+                                @var{ba} @var{bb} @var{bc} @var{bd} @
+                                @var{ca} @var{cb} @var{cc} @var{cd} @
+                                @var{da} @var{db} @var{dc} @var{dd}
+
+Return a new 4x4 matrix initialized with the given 16 values in
+column-major format.
+@end deffn
+
+@deffn {Procedure} make-null-matrix4
+Return a new 4x4 matrix with all values initialized to 0.
+@end deffn
+
+@deffn {Procedure} make-identity-matrix4
+Return a new 4x4 identity matrix.  Any matrix multiplied by the
+identity matrix yields the original matrix.  This procedure is
+equivalent to the following code:
+
+@example
+(make-matrix4 1 0 0 0
+              0 1 0 0
+              0 0 1 0
+              0 0 0 1)
+@end example
+
+@end deffn
+
+@deffn {Procedure} matrix4? @var{obj}
+Return @code{#t} if @var{obj} is a 4x4 matrix.
+@end deffn
+
+@deffn {Procedure} matrix4* . @var{matrices}
+Return a new 4x4 matrix containing the product of multiplying all of
+the given @var{matrices}.
+
+Note: Remember that matrix multiplication is @strong{not} commutative!
+@end deffn
+
+@deffn {Procedure} orthographic-projection @var{left} @var{right} @
+                                           @var{top} @var{bottom} @
+                                           @var{near} @var{far}
+
+Return a new 4x4 matrix that represents an orthographic (2D)
+projection for the horizontal clipping plane @var{top} and
+@var{bottom}, the vertical clipping plane @var{top} and @var{bottom},
+and the depth clipping plane @var{near} and @var{far}.
+@end deffn
+
+@deffn {Procedure} perspective-projection @var{fov} @
+                                          @var{aspect-ratio} @
+                                          @var{near} @var{far}
+
+Return a new 4x4 matrix that represents a perspective (3D) projection
+with a field of vision of @var{fov} radians, an aspect ratio of
+@var{aspect-ratio}, and a depth clipping plane defined by @var{near}
+and @var{far}.
+@end deffn
+
+@deffn {Procedure} matrix4-translate @var{x}
+Return a new 4x4 matrix that represents a translation by @var{x}, a 2D
+vector, a 3D vector, or a rectangle (in which case the bottom-left
+corner of the rectangle is used).
+@end deffn
+
+@deffn {Procedure} matrix4-scale @var{s}
+Return a new 4x4 matrix that represents a scaling along the X, Y, and
+Z axes by the scaling factor @var{s}, a real number.
+@end deffn
+
+@deffn {Procedure} matrix4-rotate @var{q}
+Return a new 4x4 matrix that represents a rotation about an arbitrary
+axis defined by the quaternion @var{q}.
+@end deffn
+
+@deffn {Procedure} matrix4-rotate-z @var{theta}
+Return a new 4x4 matrix that represents a rotation about the Z axis by
+@var{theta} radians.
+@end deffn
+
+@deffn {Procedure} matrix4-identity! @var{matrix}
+Modify @var{matrix} in-place to contain the identity matrix.
+@end deffn
+
+@deffn {Procedure} matrix4-mult! @var{dest} @var{a} @var{b}
+Multiply the 4x4 matrix @var{a} by the 4x4 matrix @var{b} and store
+the result in the 4x4 matrix @var{dest}.
+@end deffn
+
+@deffn {Procedure} matrix4-translate! @var{matrix} @var{x}
+Modify @var{matrix} in-place to contain a translation by @var{x}, a 2D
+vector, a 3D vector, or a rectangle (in which case the bottom-left
+corner of the rectangle is used).
+@end deffn
+
+@deffn {Procedure} matrix4-scale! @var{matrix} @var{s}
+Modify @var{matrix} in-place to contain a scaling along the X, Y, and
+Z axes by the scaling factor @var{s}, a real number.
+@end deffn
+
+@deffn {Procedure} matrix4-rotate! @var{matrix} @var{q}
+Modify @var{matrix} in-place to contain a rotation about an arbitrary
+axis defined by the quaternion @var{q}.
+@end deffn
+
+@deffn {Procedure} matrix4-rotate-z! @var{matrix} @var{theta}
+Modify @var{matrix} in-place to contain a rotation about the Z axis by
+@var{theta} radians.
+@end deffn
+
+@deffn {Procedure} matrix4-2d-transform! @var{matrix} [#:origin] @
+                                         [#:position] [#:rotation] @
+                                         [#:scale] [#:skew]
+
+Modify @var{matrix} in-place to contain the transformation described
+by @var{position}, a 2D vector or rectangle, @var{rotation}, a scalar
+representing a rotation about the Z axis, @var{scale}, a 2D vector,
+and @var{skew}, a 2D vector.  The transformation happens with respect
+to @var{origin}, a 2D vector.  If an argument is not provided, that
+particular transformation will not be included in the result.
+@end deffn
+
+@deffn {Procedure} transform! @var{matrix} @var{v}
+Modify the 2D vector @var{v} in-place by multiplying it by the 4x4
+matrix @var{matrix}.
+@end deffn
+
 @node Quaternions
 @subsection Quaternions