From 8f21fe168533229671afc252b75ea983bd0095d9 Mon Sep 17 00:00:00 2001
From: David Thompson
Date: Tue, 2 Oct 2018 08:10:53 -0400
Subject: [PATCH] doc: Document bezier curve API.
---
doc/api.texi | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 97 insertions(+)
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
--
2.11.0