diff options
Diffstat (limited to 'doc/api.texi')
| -rw-r--r-- | doc/api.texi | 273 |
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 |