summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2021-09-22 08:04:19 -0400
committerDavid Thompson <dthompson2@worcester.edu>2021-09-22 08:04:19 -0400
commit82f259c8d02c1cc0832fa09d42ed6c192f268f74 (patch)
treee9822c7c6b0af4014081fc036ec39a0fab439bb1 /doc/api.texi
parentd297c59ce2538b2f88d808346e8b9bbea2848e7d (diff)
doc: Improve vector paths documentation.
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi134
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.