From 5bdd6bc00bc054ba216e5c17526e40bbe6f00f9c Mon Sep 17 00:00:00 2001 From: David Thompson Date: Fri, 28 Sep 2018 08:19:11 -0400 Subject: doc: Document the rectangle API. --- doc/api.texi | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 195 insertions(+), 5 deletions(-) (limited to 'doc') 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 -- cgit v1.2.3