doc: Document the rectangle API.

1 files changed, 195 insertions, 5 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 4ee287b..79b6dbd 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -362,9 +362,9 @@ detection.
 @menu
 * Basics::                      Commonly used, miscellaneous things.
 * Vectors::                     Euclidean vectors.
-* Matrices::                    Transformation matrices.
-* Quaternions::                 Rotations.
 * Rectangles::                  Axis-aligned bounding boxes.
+* Matrices::                    Transformation matrices.
+* Quaternions::                 Rotations about an arbitrary axis.
 * Easings::                     Easing functions for interesting animations.
 @end menu
 
@@ -587,6 +587,199 @@ 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 Rectangles
+@subsection Rectangles
+
+The @code{(chickadee math rect)} module provides an API for
+manipulating axis-aligned bounding boxes (AABBs).  AABBs are often
+used for collision detection in games.  Common use-cases are defining
+``hitboxes'' in platformers or using them for the ``broad phase'' of a
+collision detection algorithm that uses a more complex (and thus
+slower) method of determining the actual collisions.
+
+Like some of the other math modules, there exists a collection of
+functions that do in-place modification of rectangles for use in
+performance critical code paths.
+
+@deffn {Procedure} make-rect @var{x} @var{y} @var{width} @var{height}
+Create a new rectangle that is @var{width} by @var{height} in size and
+whose bottom-left corner is located at (@var{x}, @var{y}).
+@end deffn
+
+@deffn {Procedure} rect? @var{obj}
+Return @code{#t} if @var{obj} is a rectangle.
+@end deffn
+
+@deffn {Procedure} rect-within? @var{rect1} @var{rect2}
+Return @code{#t} if @var{rect2} is completely within @var{rect1}.
+@end deffn
+
+@deffn {Procedure} rect-intersects? @var{rect1} @var{rect2}
+Return @code{#t} if @var{rect2} overlaps @var{rect1}.
+@end deffn
+
+@deffn {Procedure} rect-contains? @var{rect} @var{x} @var{y}
+Return @code{#t} if the coordinates (@var{x}, @var{y}) are within
+@var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-contains-vec2? @var{rect} @var{v}
+Return @code{#t} if the 2D vector @var{v} is within the bounds of
+@var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-x @var{rect}
+Return the X coordinate of the lower-left corner of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-y @var{rect}
+Return the Y coordinate of the lower-left corner of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-left @var{rect}
+Return the left-most X coordinate of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-right @var{rect}
+Return the right-most X coordinate of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-bottom @var{rect}
+Return the bottom-most Y coordinate of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-top @var{rect}
+Return the top-most Y coordinate of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-center-x @var{rect}
+Return the X coordinate of the center of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-center-y @var{rect}
+Return the Y coordinate of the center of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-width @var{rect}
+Return the width of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-height @var{rect}
+Return the height of @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-area @var{rect}
+Return the surface area covered by @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-clamp-x @var{rect} @var{x}
+Restrict @var{x} to the portion of the X axis covered by @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-clamp-y @var{rect} @var{y}
+Restrict @var{y} to the portion of the Y axis covered by @var{rect}.
+@end deffn
+
+@deffn {Procedure} rect-clamp @var{rect1} @var{rect2}
+Return a new rect that adjusts the location of @var{rect1} so that it
+is completely within @var{rect2}.  An exception is thrown in the case
+that @var{rect1} cannot fit completely within @var{rect2}.
+@end deffn
+
+@deffn {Procedure} rect-move @var{rect} @var{x} @var{y}
+Return a new rectangle based on @var{rect} but moved to the
+coordinates (@var{x}, @var{y}).
+@end deffn
+
+@deffn {Procedure} rect-move-vec2 @var{rect} @var{v}
+Return a new rectangle based on @var{rect} but moved to the
+coordinates in the 2D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} rect-move-by @var{rect} @var{x} @var{y}
+Return a new rectangle based on @var{rect} but moved by (@var{x},
+@var{y}) units relative to its current location.
+@end deffn
+
+@deffn {Procedure} rect-move-by-vec2 @var{rect} @var{v}
+Return a new rectangle based on @var{rect} but moved by the 2D vector
+@var{v} relative to its current location.
+@end deffn
+
+@deffn {Procedure} rect-inflate @var{rect} @var{width} @var{height}
+Return a new rectangle based on @var{rect}, but expanded by
+@var{width} units on the X axis and @var{height} units on the Y axis,
+while keeping the rectangle centered on the same point.
+@end deffn
+
+@deffn {Procedure} rect-union @var{rect1} @var{rect2}
+Return a new rectangle that completely covers the area of @var{rect1}
+and @var{rect2}.
+@end deffn
+
+@deffn {Procedure} rect-clip @var{rect1} @var{rect2}
+Return a new rectangle that is the overlapping region of @var{rect1}
+and @var{rect2}.  If the two rectangles do not overlap, a rectangle of
+0 width and 0 height is returned.
+@end deffn
+
+@deffn {Procedure} set-rect-x! @var{rect} @var{x}
+Set the left X coordinate of @var{rect} to @var{x}.
+@end deffn
+
+@deffn {Procedure} set-rect-y! @var{rect} @var{y}
+Set the bottom Y coordinate of @var{rect} to @var{y}.
+@end deffn
+
+@deffn {Procedure} set-rect-width! @var{rect} @var{width}
+Set the width of @var{rect} to @var{width}.
+@end deffn
+
+@deffn {Procedure} set-rect-height! @var{rect} @var{height}
+Set the height of @var{rect} to @var{height}.
+@end deffn
+
+@deffn {Procedure} rect-move! @var{rect} @var{x} @var{y}
+Move @var{rect} to (@var{x}, @var{y}) in-place.
+@end deffn
+
+@deffn {Procedure} rect-move-vec2! @var{rect} @var{v}
+Move @var{rect} to the 2D vector @var{v} in-place.
+@end deffn
+
+@deffn {Procedure} rect-move-by! @var{rect} @var{x} @var{y}
+Move @var{rect} by (@var{x}, @var{y}) in-place.
+@end deffn
+
+@deffn {Procedure} rect-move-by-vec2! @var{rect} @var{v}
+Move @var{rect} by the 2D vector @var{v} in-place.
+@end deffn
+
+@deffn {Procedure} rect-inflate! @var{rect} @var{width} @var{height}
+Expand @var{rect} by @var{width} and @var{height} in-place.
+@end deffn
+
+@deffn {Procedure} rect-union! @var{rect1} @var{rect2}
+Modify @var{rect1} in-place to completely cover the area of both
+@var{rect1} and @var{rect2}.
+@end deffn
+
+@deffn {Procedure} rect-clip! @var{rect1} @var{rect2}
+Modify @var{rect1} in-place to be the overlapping region of
+@var{rect1} and @var{rect2}.
+@end deffn
+
+@deffn {Procedure} rect-clamp! @var{rect1} @var{rect2}
+Adjust the location of @var{rect1} in-place so that its bounds are
+completely within @var{rect2}.  An exception is thrown in the case
+that @var{rect1} cannot fit completely within @var{rect2}.
+@end deffn
+
+@deffn {Procedure} vec2-clamp-to-rect! @var{v} @var{rect}
+Restrict the coordinates of the 2D vector @var{v} so that they are
+within the bounds of @var{rect}.  @var{v} is modified in-place.
+@end deffn
+
 @node Matrices
 @subsection Matrices
 
@@ -769,9 +962,6 @@ Return the Z component of the quaternion @var{q}.
 Return the identity quaternion.
 @end deffn
 
-@node Rectangles
-@subsection Rectangles
-
 @node Easings
 @subsection Easings