diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.texi | 338 |
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 |