diff options
| -rw-r--r-- | doc/api.texi | 134 |
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. |