render: Add vector path rendering module.

1 files changed, 213 insertions, 60 deletions

diff --git a/doc/api.texi b/doc/api.texi
index a8bac69..e93263e 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1365,10 +1365,6 @@ 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 p0 p1 p2 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
@@ -1502,7 +1498,7 @@ blocks to implement additional rendering techniques.
 * Textures::                    2D images.
 * Sprites::                     Draw 2D images.
 * Tile Maps::                   Draw 2D tile maps.
-* Lines and Shapes::            Draw line segments and polygons.
+* Vector Paths::                Draw filled and stroked paths.
 * Fonts::                       Drawing text.
 * Particles::                   Pretty little flying pieces!
 * 3D Models::                   Spinning teapots everywhere.
@@ -2214,61 +2210,218 @@ Return @code{#t} if @var{obj} is a polygon.
 Return the list of points that form @var{polygon}.
 @end deffn
 
-@node Lines and Shapes
-@subsection Lines and Shapes
-
-Sprites are fun, but sometimes simple, untextured lines and polygons
-are desired.  That's where the @code{(chickadee graphics shapes)} module
-comes in!
-
-@deffn {Procedure} draw-line start end @
-       [#:thickness 0.5] [#:feather 1.0] [#:cap round] [#:color] @
-       [#:shader]
-
-Draw a line segment from @var{start} to @var{end}. The line will be
-@var{thickness} pixels thick with an antialiased border @var{feather}
-pixels wide.  The line will be colored @var{color}. @var{cap}
-specifies the type of end cap that should be used to terminate the
-lines, either @code{none}, @code{butt}, @code{square}, @code{round},
-@code{triangle-in}, or @code{triangle-out}.  Advanced users may use
-the @var{shader} argument to override the built-in line segment
-shader.
-@end deffn
-
-@deffn {Procedure} draw-bezier-curve 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 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.
+@node Vector Paths
+@subsection Vector Paths
+
+The @code{(chickadee graphics path)} module can be used to draw lines,
+curves, circles, rectangles, and more in a scalable, resolution
+independent manner.  It is @emph{not} an SVG compliant renderer, nor
+does it intend to be.  However, those familiar with SVG and/or the
+HTML5 Canvas API should find lots of similarities.
+
+@emph{This API is considered to be experimental and may change
+substantially in future releases of Chickadee.  There are many missing
+features such as gradient fills and dashed strokes.}
+
+The first step to rendering vector graphics is to create a
+@emph{path}: A series of commands that can be thought of as moving a
+pen around a piece of paper.  A path can be either open or closed.  A
+closed path draws a straight line from the last point in the path to
+the first.
+
+@deffn {Procedure} path . commands
+Return a new path that follows @var{commands}.
+
+@example
+(path (move-to (vec2 50.0 50.0))
+      (line-to (vec2 500.0 50.0))
+      (line-to (vec2 400.0 200.0))
+      (bezier-to (vec2 500.0 250.0) (vec2 380.0 300.0) (vec2 400.0 400.0))
+      (line-to (vec2 300.0 400.0))
+      (close-path))
+@end example
+
+@end deffn
+
+Available drawing commands:
+
+@deffn {Procedure} move-to point
+Pick up the pen and move it to @var{point}.
+@end deffn
+
+@deffn {Procedure} line-to point
+Draw a line from the current pen position to @var{point}.
+@end deffn
+
+@deffn {Procedure} bezier-to control1 control2 point
+Draw a cubic bezier curve from the current pen position to
+@var{point}.  The shape of the curve is determined by the two control
+points: @var{control1} and @var{control2}.
+@end deffn
+
+@deffn {Procedure} close-path
+Draw a straight line back to the first point drawn in the path.
+@end deffn
+
+@deffn {Procedure} arc center rx ry angle-start angle-end
+Draw an elliptical arc spanning the angle range [@var{angle-start},
+@var{angle-end}], centered at @var{center} with radii @var{rx} and
+@var{ry} (set both to the same value for a circular arc.)
+@end deffn
+
+Included are some helpful procedures for generating common types of
+paths:
+
+@deffn {Procedure} line start end
+Return a path that draws a straight line from @var{start} to @var{end}.
+@end deffn
+
+@deffn {Procedure} polyline . points
+Return a path that draws a series of lines connecting @var{points}.
+@end deffn
+
+@deffn {Procedure} rectangle bottom-left width height
+Return a path that draws a rectangle whose bottom-left corner is at
+@var{bottom-left} and whose size is defined by @var{width} and
+@var{height}.
+@end deffn
+
+@deffn {Procedure} square bottom-left size
+Return a path draws a square whose bottom-left corner is at
+@var{bottom-left} and whose size is defined by @var{size}.
+@end deffn
+
+@deffn {Procedure} rounded-rectangle bottom-left width height @
+                   [#:radius 4.0] [#:radius-bottom-left] @
+                   [#:radius-bottom-right] [#:radius-top-left] @
+                   [#:radius-top-right]
+
+Return a path that draws a rectangle with rounded corners whose
+bottom-left corner is at @var{bottom-left} and whose size is defined
+by @var{width} and @var{height}.  The argument @var{radius} is used to
+define the corner radius for all corners.  To use a different radius
+value for a corner, use @var{radius-bottom-left},
+@var{radius-bottom-right}, @var{radius-top-left}, and/or
+@var{radius-top-right}.
+@end deffn
+
+@deffn {Procedure} regular-polygon center num-sides radius
+Return a path that draws a regular polygon with @var{num-sides} sides
+centered on the point @var{center} with each vertex @var{radius} units
+away from the center.
+@end deffn
+
+@deffn {Procedure} ellipse center rx ry
+Return a path that draws an ellipsed centered on the point
+@var{center} with radii @var{rx} and @var{ry}.
+@end deffn
+
+@deffn {Procedure} circle center r
+Return a path that draws a circle centered on the point @var{center}
+with radius @var{r}.
+@end deffn
+
+With one or more paths created, a @emph{painter} is needed to give the
+path its style and placement in the final picture.  Painters can be
+combined together to form arbitrarily complex pictures.
+
+@deffn {Procedure} stroke . paths
+Apply a stroked drawing style to @var{paths}.
+@end deffn
+
+@deffn {Procedure} fill . paths
+Apply a filled drawing style to @var{paths}.
+@end deffn
+
+@deffn {Procedure} fill-and-stroke . paths
+Apply a filled and stroked drawing style to @var{paths}.
+@end deffn
+
+@deffn {Procedure} transform matrix painter
+Apply @var{matrix}, a 3x3 transformation matrix, to @var{painter}.
+@end deffn
+
+@deffn {Procedure} translate v painter
+Translate @var{painter} by the 2D vector @var{v}.
+@end deffn
+
+@deffn {Procedure} rotate angle painter
+Rotate @var{painter} by @var{angle} radians.
+@end deffn
+
+@deffn {Procedure} scale x painter
+Scale @var{painter} by the scalar @var{x}.
+@end deffn
+
+@deffn {Procedure} pad pad-x pad-y painter
+Add @var{pad-x} and @var{pad-y} amount of empty space around
+@var{painter}.
+@end deffn
+
+@deffn {Procedure} superimpose . painters
+Stack @var{painters} on top of each other.
+@end deffn
+
+@deffn {Procedure} beside . painters
+Place @var{painters} next to each other in a row.
+@end deffn
+
+@deffn {Procedure} below . painters
+Place @var{painters} next to each other in a column.
+@end deffn
+
+@deffn {Syntax} with-style ((style-name value) ...) painter
+Apply all the given style settings to @var{painter}.
+
+Possible style attributes are:
+
+@itemize
+@item blend-mode
+@item fill-color
+@item stroke-color
+@item stroke-width
+@item stroke-feather
+@item stroke-cap
+@end itemize
+
+@example
+(with-style ((stroke-color green)
+             (stroke-width 4.0))
+  (stroke (circle (vec2 100.0 100.0) 50.0)))
+@end example
+
+@end deffn
+
+As in real life, a painter cannot paint anything without a canvas.
+Once a painter has been associated with a canvas, it can finally be
+rendered to the screen.
+
+@deffn {Procedure} make-canvas painter [#:matrix]
+Return a new canvas that will @var{painter} will draw on.  Optionally,
+a 3x3 @var{matrix} may be specified to apply an arbitrary
+transformation to the resulting image.
+@end deffn
+
+@deffn {Procedure} make-empty-canvas [#:matrix]
+Return a new canvas that no painter is using. Optionally, a 3x3
+@var{matrix} may be specified to apply an arbitrary transformation to
+the image, should a painter later be associated with this canvas.
+@end deffn
+
+@deffn {Procedure} canvas? obj
+Return @code{#t} is @var{obj} is a canvas.
+@end deffn
+
+@deffn {Procedure} set-canvas-painter! canvas painter
+Associate @var{painter} with @var{canvas}.
+@end deffn
+
+@deffn {Procedure} set-canvas-matrix! canvas matrix
+Set the 3x3 transformation matrix of @var{canvas} to @var{matrix}.
+@end deffn
+
+@deffn {Procedure} draw-canvas canvas
+Render @var{canvas} to the screen.
 @end deffn
 
 @node Fonts