From 8f21fe168533229671afc252b75ea983bd0095d9 Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Tue, 2 Oct 2018 08:10:53 -0400
Subject: doc: Document bezier curve API.

---
 doc/api.texi | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)

(limited to 'doc')

diff --git a/doc/api.texi b/doc/api.texi
index 79b6dbd..47e16f5 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -366,6 +366,7 @@ detection.
 * Matrices::                    Transformation matrices.
 * Quaternions::                 Rotations about an arbitrary axis.
 * Easings::                     Easing functions for interesting animations.
+* Bezier Curves::               Cubic Bezier curves and paths in 2D space.
 @end menu
 
 @node Basics
@@ -1016,6 +1017,66 @@ Return the identity quaternion.
 @deffn {Procedure} ease-in-out-sine @var{t}
 @end deffn
 
+@node Bezier Curves
+@subsection Bezier Curves
+
+The @code{(chickadee math bezier)} module provides an API for
+describing cubic Bezier curves in 2D space.  These curves are notably
+used in font description, vector graphics programs, and when it comes
+to games: path building.  With Bezier curves, it's somewhat easy to
+create a smooth looking path for an enemy to move along, for example.
+Bezier curves become particularly interesting when they are chained
+together to form a Bezier ``path'', where the end point of one curve
+becomes the starting point of the next.
+
+Currently, the rendering of Bezier curves is rather crude and provided
+mostly for visualizing and debugging curves that would be unseen in
+the final game.  See @xref{Lines and Shapes} for more information.
+
+@deffn {Procedure} make-bezier-curve @var{p0} @var{p1} @var{p2} @var{p3}
+Return a new Bezier curve object whose starting point is @var{p0},
+ending point is @var{p3}, and control points are @var{p1} and
+@var{p2}.  All points are 2D vectors.
+@end deffn
+
+@deffn {Procedure} bezier-curve? @var{obj}
+Return @code{#t} if @var{obj} is a Bezier curve.
+@end deffn
+
+@deffn {Procedure} bezier-curve-p0 @var{bezier}
+Return the starting point of @var{bezier}.
+@end deffn
+
+@deffn {Procedure} bezier-curve-p1 @var{bezier}
+Return the first control point of @var{bezier}.
+@end deffn
+
+@deffn {Procedure} bezier-curve-p2 @var{bezier}
+Return the second control point of @var{bezier}.
+@end deffn
+
+@deffn {Procedure} bezier-curve-p3 @var{bezier}
+Return the end point of @var{bezier}.
+@end deffn
+
+@deffn {Procedure} bezier-path . @var{control-points}
+Return a list of connected bezier curves defined by
+@var{control-points}.  The first curve is defined by the first 4
+arguments and every additional curve thereafter requires 3 additional
+arguments.
+@end deffn
+
+@deffn {Procedure} bezier-curve-point-at @var{bezier} @var{t}
+Return the coordinates for @var{bezier} at @var{t} (a value in the
+range [0, 1] representing how far from the start of the curve to
+check) as a 2D vector.
+@end deffn
+
+@deffn {Procedure} bezier-curve-point-at! @var{dest} @var{bezier} @var{t}
+Modify the 2D vector @var{dest} in-place to contain the coordinates
+for @var{bezier} at @var{t}.
+@end deffn
+
 @node Graphics
 @section Graphics
 
@@ -1297,6 +1358,42 @@ the @var{shader} argument to override the built-in line segment
 shader.
 @end deffn
 
+@deffn {Procedure} draw-bezier-curve @var{bezier} [#:segments 32] @
+                                     [#:control-points?] [#:tangents?] @
+                                     [#:control-point-size 8] @
+                                     [#:control-point-color yellow] @
+                                     [#:tangent-color yellow] @
+                                     [#:thickness 0.5] [#:feather 1.0] @
+                                     [#:matrix]
+
+Draw the curve defined by @var{bezier} using a resolution of N
+@var{segments}.  When @var{control-points?} is @code{#t}, the control
+points are rendered as squares of size @var{control-point-size} pixels
+and a color of @var{control-point-color}.  When @var{tangents?} is
+@code{#t}, the tangent lines from terminal point to control point are
+rendered using the color @var{tangent-color}.
+
+All line segments rendered use @code{draw-line}, and thus the
+arguments @var{thickness} and @var{feather} have the same effect as in
+that procedure.
+
+A custom @var{matrix} may be passed for applications that require more
+control over the final output.
+@end deffn
+
+@deffn {Procedure} draw-bezier-path @var{path} [#:segments 32] @
+                                    [#:control-points?] [#:tangents?] @
+                                    [#:control-point-size 8] @
+                                    [#:control-point-color yellow] @
+                                    [#:tangent-color yellow] @
+                                    [#:thickness 0.5] [#:feather 1.0] @
+                                    [#:matrix]
+
+Render @var{path}, a list of bezier curves.  See the documentation for
+@code{draw-bezier-curve} for an explanation of all the keyword
+arguments.
+@end deffn
+
 @node Fonts
 @subsection Fonts
 
-- 
cgit v1.2.3