doc: Document 3x3 matrices.

1 files changed, 83 insertions, 1 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 974a7f8..091c936 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1024,7 +1024,89 @@ objects.
 
 @subsubsection 3x3 Matrices
 
-@deffn {Procedure} make-matrix3
+@deffn {Procedure} make-matrix3 aa ab ac ba bb bc ca cb cc
+Return a new 3x3 initialized with the given 9 values in column-major
+format.
+@end deffn
+
+@deffn {Procedure} make-null-matrix3
+Return a new 3x3 matrix with all values initialized to 0.
+@end deffn
+
+@deffn {Procedure} make-identity-matrix3
+Return a new 3x3 identity matrix.  Any matrix multiplied by the
+identity matrix yields the original matrix.  This procedure is
+equivalent to the following code:
+
+@example
+(make-matrix3 1 0 0
+              0 1 0
+              0 0 1)
+@end example
+
+@end deffn
+
+@deffn {Procedure} matrix3? obj
+Return @code{#t} if @var{obj} is a 3x3 matrix.
+@end deffn
+
+@deffn {Procedure} matrix3* . matrices
+Return a new 3x3 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} matrix3-translate v
+Return a new 3x3 matrix that represents a translation by @var{v}, a 2D
+vector.
+@end deffn
+
+@deffn {Procedure} matrix3-scale s
+Return a new 3x3 matrix that represents a scaling along the x and y
+axes by the scaling factor @var{s}, a number or 2D vector.
+@end deffn
+
+@deffn {Procedure} matrix3-rotate angle
+Return a new 3x3 matrix that represents a rotation by @var{angle}
+radians.
+@end deffn
+
+@deffn {Procedure} matrix3-transform matrix v
+Return a new 2D vector that is @var{v} as transformed by the 3x3
+matrix @var{matrix}.
+@end deffn
+
+The following procedures perform in-place, destructive updates to 3x3
+matrix objects:
+
+@deffn {Procedure} matrix3-identity! matrix
+Modify @var{matrix} in-place to contain the identity matrix.
+@end deffn
+
+@deffn {Procedure} matrix3-mult! dest a b
+Multiply the 3x3 matrix @var{a} by the 3x3 matrix @var{b} and store
+the result in the 3x3 matrix @var{dest}.
+@end deffn
+
+@deffn {Procedure} matrix3-translate! matrix v
+Modify @var{matrix} in-place to contain a translation by @var{v}, a 2D
+vector.
+@end deffn
+
+@deffn {Procedure} matrix3-scale! matrix s
+Modify @var{matrix} in-place to contain a scaling along the x and y
+axes by the scaling factor @var{s}, a number or 2D vector.
+@end deffn
+
+@deffn {Procedure} matrix3-rotate! matrix angle
+Modify @var{matrix} in-place to contain a rotation by @var{angle}
+radians.
+@end deffn
+
+@deffn {Procedure} matrix3-transform! matrix v
+Modify the 2D vector @var{v} in-place to contain @var{v} as
+transformed by the 3x3 matrix @var{matrix}.
 @end deffn
 
 @subsubsection 4x4 Matrices