doc: Improve vector paths documentation.

1 files changed, 117 insertions, 17 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 3329025..3e76890 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -2313,8 +2313,67 @@ Apply a filled drawing style to @var{paths}.
 Apply a filled and stroked drawing style to @var{paths}.
 @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
+
+Fill colors may be either solid colors (@pxref{Colors}) or gradients.
+For gradient fills, there are two styles: linear or radial.
+
+@deffn {Procedure} linear-gradient [#:origin (vec2 0 0)] [#:start-color white] @
+       [#:end-color black] [#:rotation 0] [#:offset 0] [#:length 100]
+
+Return a new linear gradient that transitions from @var{start-color}
+on the left to @var{end-color} on the right over @var{length} pixels.
+@var{offset} may be used to push the gradient start point to the
+right, creating a solid block of @var{start-color} on the right hand
+side of the painter.  The line's direction may be changed by
+specifying a @var{rotation} value.  The starting point for the
+gradient is determined by @var{origin} and defaults to the lower left
+corner of the painter's bounding box.
+@end deffn
+
+@deffn {Procedure} radial-gradient [#:origin (vec2 0 0)] [#:start-color white] @
+       [#:end-color black] [#:radius 50.0] [#:radius-x] [#:radius-y] @
+       [#:rotation 0] [#:offset 0]
+
+Return a new radial gradient that transitions from @var{start-color}
+at the point @var{origin} to @var{end-color} at @var{radius} pixels
+away.  @var{offset} specifies the distance from the origin where
+@var{start-color} begins to transition.  The default is to immediately
+start transitioning.  The default shape of this type of gradient is a
+circle, but it can also be made elliptical by specifying different
+@var{radius-x} and @var{radius-y} values.  When the gradient shape is
+elliptical, @var{rotation} can be used to rotate it.
+@end deffn
+
+@deffn {Procedure} gradient? obj
+Return @code{#t} when @var{obj} is a gradient object.
+@end deffn
+
+Painters can also be transformed and combined to form new painters.
+
 @deffn {Procedure} transform matrix painter
-Apply @var{matrix}, a 3x3 transformation matrix, to @var{painter}.
+Apply @var{matrix}, a 3x3 transformation matrix (@pxref{Matrices}), to
+@var{painter}.
 @end deffn
 
 @deffn {Procedure} translate v painter
@@ -2346,6 +2405,11 @@ Add @var{pad-x} and @var{pad-y} amount of empty space around
 Stack @var{painters} on top of each other.
 @end deffn
 
+The next batch of procedures is taken straight out of the picture
+language described in
+@url{https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-15.html#%_sec_2.2.4,
+Structure and Interpretation of Computer Programs} section 2.2.4.
+
 @deffn {Procedure} beside . painters
 Place @var{painters} next to each other in a row.
 @end deffn
@@ -2354,28 +2418,64 @@ Place @var{painters} next to each other in a row.
 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}.
+@deffn {Procedure} right-split painter n
+Subdivide @var{painter} into 3 sections, recursively, like so:
 
-Possible style attributes are:
+@verbatim
+*----------------*----------------*
+|                |                |
+|                |  right-split   |
+|                |     n - 1      |
+|                |                |
+|    painter     *----------------*
+|                |                |
+|                |  right-split   |
+|                |     n - 1      |
+|                |                |
+*----------------*----------------*
+@end verbatim
 
-@itemize
-@item blend-mode
-@item fill-color
-@item stroke-color
-@item stroke-width
-@item stroke-feather
-@item stroke-cap
-@end itemize
+@end deffn
 
-@example
-(with-style ((stroke-color green)
-             (stroke-width 4.0))
-  (stroke (circle (vec2 100.0 100.0) 50.0)))
-@end example
+@deffn {Procedure} up-split painter n
+Subdivide @var{painter} into 3 sections, recursively, like so:
+
+@verbatim
+*----------------*----------------*
+|                |                |
+|    up-split    |    up-split    |
+|     n - 1      |     n - 1      |
+|                |                |
+*----------------*----------------*
+|                                 |
+|             painter             |
+|                                 |
+|                                 |
+*----------------*----------------*
+@end verbatim
 
 @end deffn
 
+@deffn {Procedure} corner-split painter n
+Subdivide @var{painter} into 4 sections, recursively, like so:
+
+@verbatim
+*----------------*----------------*
+|                |                |
+|    up-split    |  corner-split  |
+|     n - 1      |     n - 1      |
+|                |                |
+*----------------*----------------*
+|                |                |
+|    painter     |  right-split   |
+|                |     n - 1      |
+|                |                |
+*----------------*----------------*
+@end verbatim
+
+@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.