doc/index.html

   1 <html>
   2 <head>
   3 <title>Vecto - Simple Vector Drawing with Common Lisp</title>
   4 <style type="text/css">
   5   a, a:visited { text-decoration: none }
   6   a[href]:hover { text-decoration: underline }
   7   pre { background: #DDD; padding: 0.25em }
   8   p.download { color: red }
   9   .transparent { background-image: url(background.gif) }
  10 </style>
  11 </head>
  12
  13 <body>
  14
  15 <h2>Vecto - Simple Vector Drawing with Common Lisp</h2>
  16
  17 <blockquote class='abstract'>
  18 <h3>Abstract</h3>
  19
  20 <p>Vecto is a simplified interface to the
  21 powerful <a href="http://projects.tuxee.net/cl-vectors/">CL-VECTORS</a>
  22 vector rasterization library. It presents a function-oriented
  23 interface similar to <a href="http://www.cliki.net/CL-PDF">CL-PDF</a>,
  24 but the results can be saved to a PNG instead of a PDF file. Since
  25 Vecto and all supporting libraries are written completely in Common
  26 Lisp, without depending on external non-Lisp libraries, it should work
  27 in any Common Lisp environment. Vecto is available under a BSD-like
  28 license. The current version is 1.0.2, released on October 1st,
  29 2007.
  30
  31 <p>Vecto is used by <a href="http://wigflip.com/easystreet/">Easystreet</a>.
  32
  33 <p>The canonical location for Vecto
  34 is <a href="http://www.xach.com/lisp/vecto/">http://www.xach.com/lisp/vecto/</a>.
  35
  36 <p class='download'>Download shortcut:</p>
  37
  38 <p><a href="http://www.xach.com/lisp/vecto.tgz">http://www.xach.com/lisp/vecto.tgz</a>
  39
  40 </blockquote>
  41
  42 <h3>Contents</h3>
  43
  44 <ol>
  45 <li> <a href='#sect-overview-and-limitations'>Overview and Limitations</a>
  46 <li> <a href='#sect-examples'>Examples</a>
  47 <li> <a href='#sect-dictionary'>Dictionary</a>
  48
  49 <ul>
  50   <li> <a href='#sect-canvases'>Canvases</a>
  51     <ul>
  52       <li> <a href='#with-canvas'><tt>with-canvas</tt></a>
  53       <li> <a href='#clear-canvas'><tt>clear-canvas</tt></a>
  54       <li> <a href='#save-png'><tt>save-png</tt></a>
  55       <li> <a href='#save-png-stream'><tt>save-png-stream</tt></a>
  56     </ul>
  57
  58   <li> <a href='#sect-graphics-state'>Graphics State</a>
  59     <ul>
  60       <li> <a href='#with-graphics-state'><tt>with-graphics-state</tt></a>
  61       <li> <a href='#set-rgba-fill'><tt>set-rgba-fill</tt></a>
  62       <li> <a href='#set-rgba-fill'><tt>set-rgb-fill</tt></a>
  63       <li> <a href='#set-rgba-stroke'><tt>set-rgba-stroke</tt></a>
  64       <li> <a href='#set-rgba-stroke'><tt>set-rgb-stroke</tt></a>
  65       <li> <a href='#set-line-cap'><tt>set-line-cap</tt></a>
  66       <li> <a href='#set-line-join'><tt>set-line-join</tt></a>
  67       <li> <a href='#set-line-width'><tt>set-line-width</tt></a>
  68       <li> <a href='#set-dash-pattern'><tt>set-dash-pattern</tt></a>
  69       <li> <a href='#translate'><tt>translate</tt></a>
  70       <li> <a href='#rotate'><tt>rotate</tt></a>
  71       <li> <a href='#scale'><tt>scale</tt></a>
  72       <li> <a href='#skew'><tt>skew</tt></a>
  73       <li> <a href='#clip-path'><tt>clip-path</tt></a>
  74       <li> <a href='#even-odd-clip-path'><tt>even-odd-clip-path</tt></a>
  75     </ul>
  76
  77   <li> <a href='#sect-paths'>Paths</a>
  78     <ul>
  79       <li> <a href='#move-to'><tt>move-to</tt></a>
  80       <li> <a href='#line-to'><tt>line-to</tt></a>
  81       <li> <a href='#curve-to'><tt>curve-to</tt></a>
  82       <li> <a href='#quadratic-to'><tt>quadratic-to</tt></a>
  83       <li> <a href='#close-subpath'><tt>close-subpath</tt></a>
  84       <li> <a href='#rectangle'><tt>rectangle</tt></a>
  85       <li> <a href='#centered-ellipse-path'><tt>centered-ellipse-path</tt></a>
  86       <li> <a href='#centered-circle-path'><tt>centered-circle-path</tt></a>
  87     </ul>
  88
  89   <li> <a href='#sect-painting'>Painting</a>
  90     <ul>
  91       <li> <a href='#fill-path'><tt>fill-path</tt></a>
  92       <li> <a href='#even-odd-fill'><tt>even-odd-fill</tt></a>
  93       <li> <a href='#stroke'><tt>stroke</tt></a>
  94       <li> <a href='#fill-and-stroke'><tt>fill-and-stroke</tt></a>
  95       <li> <a href='#even-odd-fill-and-stroke'><tt>even-odd-fill-and-stroke</tt></a>
  96       <li> <a href='#end-path-no-op'><tt>end-path-no-op</tt></a>
  97     </ul>
  98
  99   <li> <a href='#sect-text'>Text</a>
 100     <ul>
 101       <li> <a href='#get-font'><tt>get-font</tt></a>
 102       <li> <a href='#set-font'><tt>set-font</tt></a>
 103       <li> <a href='#draw-string'><tt>draw-string</tt></a>
 104       <li> <a href='#draw-centered-string'><tt>draw-centered-string</tt></a>
 105       <li> <a href='#string-bounding-box'><tt>string-bounding-box</tt></a>
 106     </ul>
 107
 108   <li> <a href='#sect-miscellaneous'>Miscellaneous</a>
 109     <ul>
 110       <li> <a href='#const-kappa'><tt>+kappa+</tt></a>
 111     </ul>
 112
 113 </ul>
 114
 115 <li> <a href='#sect-references'>References</a>
 116 <li> <a href='#sect-feedback'>Feedback</a>
 117
 118 </ol>
 119
 120 <a name='sect-overview-and-limitations'><h3>Overview and Limitations</h3></a>
 121
 122 <p>Vecto is a library that provides a simple interface to the
 123 the <a href="http://projects.tuxee.net/cl-vectors/">CL-VECTORS</a>
 124 vector drawing library. It supports drawing on a canvas and saving the
 125 results to a PNG file.
 126
 127 <p>Vecto depends on the following libraries:
 128
 129 <ul>
 130 <li> <a href="http://projects.tuxee.net/cl-vectors/">CL-VECTORS</a>
 131 <li> <a href="http://www.xach.com/lisp/zpb-ttf/">ZPB-TTF</a>
 132 <li> <a href="http://www.cliki.net/salza">Salza</a>
 133 <li> <a href="http://www.cliki.net/salza-png">Salza-PNG</a>
 134 </ul>
 135
 136 <p>The easiest way to install Vecto and all its dependencies is
 137 with <a href="http://www.cliki.net/asdf-install">ASDF-Install</a>.
 138
 139 <p>Vecto's function interface is similar to the
 140 PDF vector description and painting interface: you create images by
 141 describing vector paths, then using stroke or fill operations to paint
 142 to the canvas.
 143
 144 <p>Vecto's color system uses red, green, blue, and alpha color
 145 components for drawing. The results can be be saved to a PNG with an
 146 alpha channel.
 147
 148 <p>Vecto's coordinate system starts at the lower-left corner of the
 149 image, and increases rightwards along the X axis and upwards along the
 150 Y axis.
 151
 152 <p>All measurements are in pixels.
 153
 154 <p>PDF is a feature-rich system. Vecto supports a small subset of
 155 PDF-style operations. In particular, it does not support:
 156
 157 <ul>
 158 <li> sampled images
 159 <li> pattern, gradient, or functional fill
 160 <li> complex layout of text
 161 <li> PostScript fonts
 162 <li> non-RGB color spaces
 163 </ul>
 164
 165 <p>Other limitations:
 166
 167 <ul>
 168 <li> No output formats other than 8-bit, truecolor-alpha PNGs
 169 <li> No access to underlying pixel data
 170 </ul>
 171
 172 <p>Related libraries:
 173
 174 <ul>
 175   <li> <a href="http://common-lisp.net/project/imago/">Imago</a>
 176
 177   <li> <a href="http://cyrusharmon.org/projects?project=ch-image">ch-image</a>
 178
 179   <li> <a href="http://ygingras.net/poly-pen">Poly-pen</a>
 180 </ul>
 181
 182
 183 <a name='sect-examples'><h3>Examples</h3></a>
 184
 185 <p>All examples are available in <tt>doc/examples.lisp</tt> in the Vecto
 186 distribution. That file starts with:
 187
 188 <pre>
 189 (defpackage #:vecto-examples
 190   (:use #:cl #:vecto))
 191
 192 (in-package #:vecto-examples)
 193 </pre>
 194
 195
 196 <pre>
 197 <img border=0 align=right src='lambda-example.png'
 198 >(defun radiant-lambda (file)
 199   (<a href='#with-canvas'>with-canvas</a> (:width 90 :height 90)
 200     (let ((font (<a href='#get-font'>get-font</a> "times.ttf"))
 201           (step (/ pi 7)))
 202       (<a href='#set-font'>set-font</a> font 40)
 203       (<a href='#translate'>translate</a> 45 45)
 204       (<a href='#draw-centered-string'>draw-centered-string</a> 0 -10 #(#x3BB))
 205       (<a href='#set-rgb-stroke'>set-rgb-stroke</a> 1 0 0)
 206       (<a href='#centered-circle-path'>centered-circle-path</a> 0 0 35)
 207       (<a href='#stroke'>stroke</a>)
 208       (<a href='#set-rgba-stroke'>set-rgba-stroke</a> 0 0 1.0 0.5)
 209       (<a href='#set-line-width'>set-line-width</a> 4)
 210       (dotimes (i 14)
 211         (<a href='#with-graphics-state'>with-graphics-state</a>
 212           (<a href='#rotate'>rotate</a> (* i step))
 213           (<a href='#move-to'>move-to</a> 30 0)
 214           (<a href='#line-to'>line-to</a> 40 0)
 215           (stroke)))
 216       (<a href='#save-png'>save-png</a> file))))
 217 </pre>
 218
 219 <pre>
 220 <img align=right src='feedlike-icon.png'
 221 >(defun feedlike-icon (file)
 222   (with-canvas (:width 100 :height 100)
 223     (set-rgb-fill 1.0 0.65 0.3)
 224     (<a href='#rounded-rectangle'>rounded-rectangle</a> 0 0 100 100 10 10)
 225     (<a href='#fill-path'>fill-path</a>)
 226     (set-rgb-fill 1.0 1.0 1.0)
 227     (centered-circle-path 20 20 10)
 228     (fill-path)
 229     (flet ((quarter-circle (x y radius)
 230              (let ((kappa (* <a href='#const-kappa'>+kappa+</a> radius)))
 231                (move-to (+ x radius) y)
 232                (curve-to (+ x radius) (+ y kappa)
 233                          (+ x kappa) (+ y radius)
 234                          x (+ y radius)))))
 235       (set-rgb-stroke 1.0 1.0 1.0)
 236       (set-line-width 15)
 237       (quarter-circle 20 20 30)
 238       (stroke)
 239       (quarter-circle 20 20 60)
 240       (stroke))
 241     (save-png file)))
 242 </pre>
 243
 244 <pre><div style='float: right' class='transparent'><img src='star-clipping.png'
 245 ></div>(defun star-clipping (file)
 246   (with-canvas (:width 200 :height 200)
 247     (let ((size 100)
 248           (angle 0)
 249           (step (* 2 (/ (* pi 2) 5))))
 250       (translate size size)
 251       (move-to 0 size)
 252       (dotimes (i 5)
 253         (setf angle (+ angle step))
 254         (line-to (* (sin angle) size)
 255                  (* (cos angle) size)))
 256       (<a href='#even-odd-clip-path'><tt>even-odd-clip-path</tt></a>)
 257       (<a href='#end-path-no-op'><tt>end-path-no-op</tt></a>)
 258       (flet ((circle (distance)
 259                (<a href='#set-rgba-fill'><tt>set-rgba-fill</tt></a> distance 0 0
 260                               (- 1.0 distance))
 261                (centered-circle-path 0 0 (* size distance))
 262                (fill-path)))
 263         (loop for i downfrom 1.0 by 0.05
 264               repeat 20 do
 265               (circle i)))
 266       (save-png file))))
 267 </pre>
 268
 269 <a name='sect-dictionary'><h3>Dictionary</h3></a>
 270
 271 <p>The following symbols are exported from the <tt>VECTO</tt> package.
 272
 273 <a name='sect-canvases'><h4>Canvases</h4></a>
 274
 275 <p><a name='with-canvas'>[Macro]</a><br>
 276 <b>with-canvas</b> (<tt>&amp;key</tt> <i>width</i> <i>height</i>)
 277 <tt>&amp;body</tt> <i>body</i>
 278
 279 <blockquote>
 280 Evaluates <i>body</i> with a canvas established with the specified
 281 dimensions as the target for drawing commands. The canvas is initially
 282 completely clear (all pixels have 0 alpha).
 283 </blockquote>
 284
 285
 286 <p><a name='clear-canvas'>[Function]</a><br>
 287 <b>clear-canvas</b> => |
 288
 289 <blockquote>
 290 Completely fills the canvas with the current fill color. Any marks on
 291 the canvas are cleared.
 292 </blockquote>
 293
 294
 295 <p><a name='save-png'>[Function]</a><br>
 296 <b>save-png</b> <i>file</i> => <i>truename</i>
 297
 298 <blockquote>
 299 Writes the contents of the canvas as the PNG <i>file</i>, and returns
 300 the truename of <i>file</i>.
 301 </blockquote>
 302
 303
 304 <p><a name='save-png-stream'>[Function]</a><br>
 305 <b>save-png-stream</b> <i>stream</i> => |
 306
 307 <blockquote>
 308 Writes the contents of the canvas as a PNG to <i>stream</i>, which
 309 must accept <tt>(unsigned-byte&nbsp;8)</tt> data.
 310 </blockquote>
 311
 312
 313 <a name='sect-graphics-state'><h4>Graphics State</h4></a>
 314
 315 <p>The graphics state stores several parameters used for graphic
 316 operations.
 317
 318 <p><a name='with-graphics-state'>[Macro]</a><br>
 319 <b>with-graphics-state</b> <tt>&amp;body</tt> <i>body</i>
 320
 321 <blockquote>
 322 Evaluates the forms of <i>body</i> with a copy of the current graphics
 323 state. Any modifications to the state are undone at the end of the
 324 form.
 325 </blockquote>
 326
 327
 328 <p><a name='set-rgba-fill'>[Functions]</a><br>
 329 <b>set-rgba-fill</b> <i>r</i> <i>g</i> <i>b</i> <i>alpha</i> => |<br>
 330 <b>set-rgb-fill</b> <i>r</i> <i>g</i> <i>b</i> => |
 331
 332 <blockquote>
 333 Sets the fill color. <i>r</i>, <i>g</i>, <i>b</i>, and <i>alpha</i>
 334 should be in the range of 0.0 to 1.0.
 335
 336 <p><tt>set-rgb-fill</tt> is the same as <tt>set-rgba-fill</tt> with an
 337 implicit alpha value of 1.0.
 338
 339 <p>The fill color is used
 340 for <a
 341 href='#clear-canvas'><tt>CLEAR-CANVAS</tt></a>, <a
 342 href='#fill-path'><tt>FILL-PATH</tt></a>, <a
 343 href='#even-odd-fill'><tt>EVEN-ODD-FILL</tt></a>, <a
 344 href='#fill-and-stroke'><tt>FILL-AND-STROKE</tt></a>, <a
 345 href='#even-odd-fill-and-stroke'><tt>EVEN-ODD-FILL-AND-STROKE</tt></a>,
 346 and <a href='#draw-string'><tt>DRAW-STRING</tt></a>.
 347
 348 </blockquote>
 349
 350 <p><a name='set-rgba-stroke'>[Functions]</a><br>
 351 <b>set-rgba-stroke</b> <i>r</i> <i>g</i> <i>b</i> <i>alpha</i> => |<br>
 352 <b>set-rgb-stroke</b> <i>r</i> <i>g</i> <i>b</i> => |
 353
 354 <blockquote>
 355 Sets the stroke color. <i>r</i>, <i>g</i>, <i>b</i>, and <i>alpha</i>
 356 should be in the range of 0.0 to 1.0.
 357
 358 <p><tt>set-rgb-stroke</tt> is the same as <tt>set-rgba-stroke</tt>
 359 with an implicit alpha value of 1.0.
 360
 361 <p>The stroke color is used for <a href='#stroke'><tt>STROKE</tt></a>,
 362 <a href='#fill-and-stroke'><tt>FILL-AND-STROKE</tt></a>,
 363 and <a href='#even-odd-fill-and-stroke'><tt>EVEN-ODD-FILL-AND-STROKE</tt></a>.
 364 </blockquote>
 365
 366
 367 <p><a name='set-line-cap'>[Function]</a><br>
 368 <b>set-line-cap</b> <i>style</i> => |
 369
 370 <blockquote>
 371 Sets the line cap style to <i>style</i>, which must be one
 372 of <tt>:BUTT</tt>, <tt>:SQUARE</tt>, or <tt>:ROUND</tt>. The initial
 373 value is <tt>:BUTT</tt>.
 374
 375 <p><table cellspacing=5 id="line-cap">
 376 <tr>
 377  <td align=center><img src="cap-style-butt.png"></td>
 378  <td align=center><img src="cap-style-square.png"></td>
 379  <td align=center><img src="cap-style-round.png"></td>
 380 </tr>
 381 <tr>
 382  <td align=center><tt>:BUTT</tt></td>
 383  <td align=center><tt>:SQUARE</tt></td>
 384  <td align=center><tt>:ROUND</tt></td>
 385 </tr>
 386 </table>
 387
 388 </blockquote>
 389
 390
 391 <p><a name='set-line-join'>[Function]</a><br>
 392 <b>set-line-join</b> <i>style</i> => |
 393
 394 <blockquote>
 395 Sets the line join style to <i>style</i>, which must be one
 396 of <tt>:MITER</tt>, <tt>:BEVEL</tt>, or <tt>:ROUND</tt>. The initial
 397 value is <tt>:MITER</tt>.
 398
 399 <p><table cellspacing=5 id="line-join">
 400 <tr>
 401  <td align=center><img src="join-style-miter.png"></td>
 402  <td align=center><img src="join-style-bevel.png"></td>
 403  <td align=center><img src="join-style-round.png"></td>
 404 </tr>
 405 <tr>
 406  <td align=center><tt>:MITER</tt></td>
 407  <td align=center><tt>:BEVEL</tt></td>
 408  <td align=center><tt>:ROUND</tt></td>
 409 </tr>
 410 </table>
 411
 412 </blockquote>
 413
 414
 415 <p><a name='set-line-width'>[Function]</a><br>
 416 <b>set-line-width</b> <i>width</i> => |
 417
 418 <blockquote>
 419 Sets the line width for strokes to <i>width</i>.
 420 </blockquote>
 421
 422
 423
 424 <p><a name='set-dash-pattern'>[Function]</a><br>
 425 <b>set-dash-pattern</b> <i>dash-vector</i> <i>phase</i> => |
 426
 427 <blockquote>
 428 Sets the dash pattern according to <i>dash-vector</i> and <i>phase</i>.
 429
 430 <p><i>dash-vector</i> should be a vector of numbers denoting on and
 431 off patterns for a stroke. An empty <i>dash-vector</i> is the same as
 432 having no dash pattern at all.
 433
 434 <p><i>phase</i> is how far along the dash pattern to proceed before
 435 applying the pattern to the current stroke.
 436
 437 <p>
 438 <table>
 439   <tr>
 440     <th>Appearance</th>
 441     <th>Dash Vector and Phase</th>
 442   </tr>
 443   <tr>
 444     <td align=center><img src="dash-pattern-none.png"></td>
 445     <td align=left><tt>#() 0</tt></td>
 446   </tr>
 447   <tr>
 448     <td align=center><img src="dash-pattern-a.png"></td>
 449     <td align=left><tt>#(30 30) 0</tt></td>
 450   </tr>
 451   <tr>
 452     <td align=center><img src="dash-pattern-b.png"></td>
 453     <td align=left><tt>#(30 30) 15</tt></td>
 454   </tr>
 455   <tr>
 456     <td align=center><img src="dash-pattern-c.png"></td>
 457     <td align=left><tt>#(10 20 10 40) 0</tt></td>
 458   </tr>
 459   <tr>
 460     <td align=center><img src="dash-pattern-d.png"></td>
 461     <td align=left><tt>#(10 20 10 40) 13</tt></td>
 462   </tr>
 463   <tr>
 464     <td align=center><img src="dash-pattern-e.png"></td>
 465     <td align=left><tt>#(30 30) 0</tt>, <tt>:ROUND</tt> line caps</td>
 466   </tr>
 467 </table>
 468 </blockquote>
 469
 470
 471 <p><a name='translate'>[Function]</a><br>
 472 <b>translate</b> <i>x</i> <i>y</i> => |
 473
 474 <blockquote>
 475 Offsets the coordinate system by <i>x</i> units horizontally
 476 and <i>y</i> units vertically.
 477 </blockquote>
 478
 479
 480 <p><a name='rotate'>[Function]</a><br>
 481 <b>rotate</b> <i>radians</i> => |
 482
 483 <blockquote>
 484 Rotates the coordinate system by <i>radians</i>.
 485 </blockquote>
 486
 487
 488 <p><a name='scale'>[Function]</a><br>
 489 <b>scale</b> <i>sx</i> <i>sy</i> => |
 490
 491 <blockquote>
 492 Scales the coordinate system by <i>sx</i> horizontally
 493 and <i>sy</i> vertically.
 494 </blockquote>
 495
 496
 497 <p><a name='skew'>[Function]</a><br>
 498 <b>skew</b> <i>ax</i> <i>ay</i> => |
 499
 500 <blockquote>
 501 Skews the X axis of the coordinate system by <i>ax</i> radians and the
 502 Y axis by <i>ay</i> radians.
 503 </blockquote>
 504
 505
 506 <p><a name='clip-path'>[Function]</a><br>
 507 <b>clip-path</b> => |
 508
 509 <blockquote>
 510 Defines a clipping path based on the current path. It is not applied
 511 immediately, but is created after after the painting is done in the
 512 next call to one
 513 of <a
 514 href='#fill-path'><tt>FILL-PATH</tt></a>, <a
 515 href='#even-odd-fill'><tt>EVEN-ODD-FILL</tt></a>, <a
 516 href='#fill-and-stroke'><tt>FILL-AND-STROKE</tt></a>, <a
 517 href='#even-odd-fill-and-stroke'><tt>EVEN-ODD-FILL-AND-STROKE</tt></a>,
 518 or <a href='#end-path-no-op'><tt>END-PATH-NO-OP</tt></a>.
 519
 520 <p>The clipping path initially covers the entire canvas; no clipping
 521 is done. Subsequent calls to <tt>CLIP-PATH</tt> set the clipping path
 522 to the intersection of the established clipping path and the new
 523 clipping path, and all drawing will be done within the outline of the
 524 clipping path.
 525
 526 <p>The outline of the clipping path is defined with the nonzero
 527 winding rule, as with <a href='#fill-path'><tt>FILL-PATH</tt></a>.
 528
 529 <p>There is no way to enlarge the clipping path. However, the clipping
 530 path is part of the graphics state, so changes may be localized by
 531 using <a href='#with-graphics-state'><tt>WITH-GRAPHICS-STATE</tt></a>.
 532
 533
 534 <p><table>
 535 <tr>
 536  <td><img src="clip-unclipped.png"></td>
 537  <td>A filled red rectangle, not clipped</td>
 538 </tr>
 539 <tr>
 540  <td><img src="clip-to-circle.png"></td>
 541  <td>The same rectangle drawn with a circle clipping path in effect</td>
 542 </tr>
 543 <tr>
 544  <td><img src="clip-to-rectangle.png"></td>
 545  <td>Clipped to a rounded rectangle clipping path</td>
 546 </tr>
 547 <tr>
 548  <td><img src="clip-to-both.png"></td>
 549  <td>Clipped to the intersection of the circle and rounded rectangle clipping paths</td>
 550 </tr>
 551 </table>
 552
 553
 554
 555 </blockquote>
 556
 557
 558 <p><a name='even-odd-clip-path'>[Function]</a><br>
 559 <b>even-odd-clip-path</b> => |
 560
 561 <blockquote>
 562 Like <a href='#clip-path'><tt>CLIP-PATH</tt></a>, but uses the
 563 even/odd fill rule to determine the outline of the clipping path.
 564 </blockquote>
 565
 566
 567 <a name='sect-paths'><h4>Paths</h4></a>
 568
 569 <p>Paths are used to create lines for stroking or outlines for
 570 filling. Paths consist of straight lines and curves. Paths consist of
 571 one or more subpaths.
 572
 573 <p><a name='move-to'>[Function]</a><br>
 574 <b>move-to</b> <i>x</i> <i>y</i> => |
 575
 576 <blockquote>
 577 Starts a new subpath at (<i>x</i>,<i>y</i>). <tt>move-to</tt> must be the
 578 first step of constructing a subpath.
 579 </blockquote>
 580
 581
 582 <p><a name='line-to'>[Function]</a><br>
 583 <b>line-to</b> <i>x</i> <i>y</i> => |
 584
 585 <blockquote>
 586 Appends a straight line ending at (<i>x</i>,<i>y</i>) to the
 587 current subpath.
 588 </blockquote>
 589
 590
 591 <p><a name='curve-to'>[Function]</a><br>
 592 <b>curve-to</b>
 593 <i>cx1</i> <i>cy1</i>
 594 <i>cx2</i> <i>cy2</i>
 595 <i>x</i> <i>y</i> => |
 596
 597 <blockquote>
 598 Appends a
 599 cubic <a href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve">B&eacute;zier
 600 curve</a> ending at (<i>x</i>,<i>y</i>) and with control
 601 points (<i>cx1</i>,<i>cy1</i>) and (<i>cx2</i>,<i>cy2</i>) to the current
 602 subpath.
 603 </blockquote>
 604
 605
 606 <p><a name='quadratic-to'>[Function]</a><br>
 607 <b>quadratic-to</b>
 608 <i>cx</i> <i>cy</i>
 609 <i>x</i> <i>y</i> => |
 610
 611 <blockquote>
 612 Appends a quadratic B&eacute;zier curve ending at (<i>x</i>,<i>y</i>)
 613 and with the control point (<i>cx</i>,<i>cy</i>) to the current
 614 subpath.
 615 </blockquote>
 616
 617
 618 <p><a name='close-subpath'>[Function]</a><br>
 619 <b>close-subpath</b> => |
 620
 621 <blockquote>
 622 Closes the current subpath. If the current point is not the same as the
 623 starting point for the subpath, appends a straight line from the
 624 current point to the starting point of the current subpath.
 625
 626 <p>Subpaths with start and end points that coincidentally overlap are
 627 not the same as closed subpaths. The distinction is important when
 628 stroking:
 629
 630 <p><table cellpadding=5>
 631  <tr>
 632    <td align=center><img src="open-subpath.png"></td>
 633    <td align=center><img src="closed-subpath.png"></td>
 634  </tr>
 635  <tr>
 636    <td align=center>Open subpath</td>
 637    <td align=center>Closed subpath</td>
 638  </tr>
 639 </table>
 640
 641 <p>If the subpath is not closed, the start and points of the subpath
 642   will be drawn with the current line cap style. If the path is
 643   closed, the start and endpoints will be treated as joined and drawn
 644   with the line join style.
 645 </blockquote>
 646
 647
 648 <p><a name='rectangle'>[Function]</a><br>
 649 <b>rectangle</b> <i>x</i> <i>y</i> <i>width</i> <i>height</i>
 650
 651 <blockquote>
 652 Creates a rectangular subpath with the given <i>width</i>
 653 and <i>height</i> that has its lower-left corner at
 654 (<i>x</i>,<i>y</i>). It is effectively the same as:
 655
 656 <pre>
 657 (move-to x y)
 658 (line-to (+ x width) y)
 659 (line-to (+ x width) (+ y height))
 660 (line-to x (+ y height))
 661 (close-subpath)
 662 </pre>
 663 </blockquote>
 664
 665 <p><a name='centered-ellipse-path'>[Function]</a><br>
 666 <b>centered-ellipse-path</b>
 667 <i>x</i> <i>y</i>
 668 <i>rx</i> <i>ry</i>
 669
 670 <blockquote>
 671 Adds a closed subpath that outlines an ellipse centered at
 672 (<i>x</i>,<i>y</i>) with an X radius of <i>rx</i> and a Y radius
 673 of <i>ry</i>.
 674 </blockquote>
 675
 676 <p><a name='centered-circle-path'>[Function]</a><br>
 677 <b>centered-circle-path</b> <i>x</i> <i>y</i> <i>radius</i> => |
 678
 679 <blockquote>
 680 Adds a closed subpath that outlines a circle centered at
 681 (<i>x</i>,<i>y</i>) with a radius of <i>radius</i>. It is effectively
 682 the same as:
 683
 684 <pre>
 685 (centered-ellipse-path x y radius radius)
 686 </pre>
 687 </blockquote>
 688
 689
 690
 691 <a name='sect-painting'><h4>Painting</h4></a>
 692
 693 <p>After a path is defined, filling, stroking, or both will use the
 694 path to apply color to the canvas. After a path has been filled or
 695 stroked, it is no longer active; it effectively disappears.
 696
 697
 698 <p><a name='fill-path'>[Function]</a><br>
 699 <b>fill-path</b> => |
 700
 701 <blockquote>
 702 Fills the current path with the fill color. If the path has not been
 703 explicitly closed
 704 with <a href='#close-subpath'><tt>CLOSE-SUBPATH</tt></a>, it is
 705 implicitly closed before filling.  The non-zero winding rule is used
 706 to determine what areas are considered inside the path.
 707 </blockquote>
 708
 709
 710 <p><a name='even-odd-fill'>[Function]</a><br>
 711 <b>even-odd-fill</b> => |
 712
 713 <blockquote>
 714 The same as <a href='#fill-path'><tt>FILL-PATH</tt></a>, but uses the
 715 even/odd rule to determine what areas are considered inside the path.
 716 </blockquote>
 717
 718
 719 <p><a name='stroke'>[Function]</a><br>
 720 <b>stroke</b> => |
 721
 722 <blockquote>
 723 Strokes the current path. The line width, stroke color, line join
 724 style, line cap style, and dash pattern and phase determine how the
 725 stroked path will appear on the canvas.
 726 </blockquote>
 727
 728
 729 <p><a name='fill-and-stroke'>[Function]</a><br>
 730 <b>fill-and-stroke</b> => |
 731
 732 <blockquote>
 733 Fills the current path, then strokes it.
 734 </blockquote>
 735
 736
 737 <p><a name='even-odd-fill-and-stroke'>[Function]</a><br>
 738 <b>even-odd-fill-and-stroke</b> => |
 739
 740 <blockquote>
 741 Fills the current path using the even/odd rule, then strokes it.
 742 </blockquote>
 743
 744
 745 <p><a name='end-path-no-op'>[Function]</a><br>
 746 <b>end-path-no-op</b> => |
 747
 748 <blockquote>
 749 Ends the current path without painting anything. If a clipping path
 750 has been specified with <a href='#clip-path'><tt>CLIP-PATH</tt></a>
 751 or <a href='#even-odd-clip-path'><tt>EVEN-ODD-CLIP-PATH</tt></a>, it
 752 will be created by <tt>end-path-no-op</tt>.
 753 </blockquote>
 754
 755
 756
 757 <a name='sect-text'><h4>Text</h4></a>
 758
 759 <p>Vecto can draw text to a canvas. It loads glyph shapes from
 760   TrueType font files
 761   with <a href="http://www.xach.com/lisp/zpb-ttf/">ZPB-TTF</a>.
 762
 763 <p><a name='get-font'>[Function]</a><br>
 764 <b>get-font</b> <i>font-file</i> => <i>font-loader</i>
 765
 766 <blockquote>
 767 Creates and returns a ZPB-TTF font loader object
 768 from <i>font-file</i>. Any font loader created this way will
 769 automatically be closed at the end of its
 770 enclosing <a href='#with-canvas'><tt>WITH-CANVAS</tt></a> form.
 771 </blockquote>
 772
 773
 774 <p><a name='set-font'>[Function]</a><br>
 775 <b>set-font</b> <i>font-loader</i> <i>size</i> => |
 776
 777 <blockquote>
 778 Sets the active font to the font associated
 779 with <i>font-loader</i>, scaled to <i>size</i> units per line.
 780
 781 <p>The first argument can be any ZPB-TTF font loader; it need not be
 782 created via <a href='#get-font'><tt>GET-FONT</tt></a>. However, only
 783 font loaders created via <tt>GET-FONT</tt> will be automatically
 784 closed at the end of <a href='#with-canvas'><tt>WITH-CANVAS</tt></a>.
 785 </blockquote>
 786
 787
 788 <p><a name='draw-string'>[Function]</a><br>
 789 <b>draw-string</b> <i>x</i> <i>y</i> <i>string</i> => |
 790
 791 <blockquote>
 792 Draws <i>string</i> on the canvas with the active font. The glyph
 793 origin of the first character in the string is positioned at <i>x</i>
 794 and the baseline of the string is positioned at <i>y</i>. The text is
 795 filled with the current <a href='#set-rgba-fill'>fill color</a>.
 796
 797 <p>The string may be a specialized vector of characters (a true CL
 798 string) or a vector containing characters, Unicode code-points, or both. For
 799 example, <tt>#(#\L #\a #\m #\b #\d #\a #\= #x3BB)</tt> is a valid
 800 argument for <tt>DRAW-STRING</tt>.
 801 </blockquote>
 802
 803
 804 <p><a name='draw-centered-string'>[Function]</a><br>
 805 <b>draw-centered-string</b> <i>x</i> <i>y</i> <i>string</i> => |
 806
 807 <blockquote>
 808 Draws <i>string</i> on the canvas with the active font. The horizontal
 809 center of the string is positioned at <i>x</i> and the baseline of the
 810 string is positioned at <i>y</i>.
 811 </blockquote>
 812
 813
 814 <p><a name='string-bounding-box'>[Function]</a><br>
 815 <b>string-bounding-box</b> <i>string</i> <i>size</i> <i>loader</i>
 816 => <i>#(xmin ymin xmax ymax)</i>
 817
 818 <blockquote>
 819 Calculates the bounding box of <i>string</i> for <i>font-loader</i>
 820 at <i>size</i>.
 821 </blockquote>
 822
 823
 824 <a name='sect-miscellaneous'><h3>Miscellaneous</h3></a>
 825
 826 <p><a name='const-kappa'>[Constant]</a><br>
 827 <b>+kappa+</b> => 0.5522847498307936d0.
 828
 829 <blockquote>
 830 This constant is useful to draw portions of a circle.
 831 </blockquote>
 832
 833
 834 <a name='sect-references'><h2>References</h2></a>
 835
 836 <ul>
 837   <li> Adobe Systems Inc., <a href="http://www.adobe.com/devnet/pdf/pdf_reference.html">PDF Reference, Sixth Edition, Version 1.7</a>
 838   <li> Lawrence Kesteloot, <a href="http://www.teamten.com/lawrence/graphics/premultiplication/">Alpha Premultiplication</a>
 839   <li> Dr. Thomas Sederberg, <a href="http://www.tsplines.com/resources/class_notes/Bezier_curves.pdf">B&eacute;zier curves</a>
 840   <li> Alvy Ray Smith, <a href="http://alvyray.com/Memos/MemosMicrosoft.htm#ImageCompositing">Image Compositing Fundamentals</a>
 841   <li> G. Adam Stanislav, <a href="http://www.whizkidtech.redprince.net/bezier/circle/">Drawing a circle with B&eacute;zier curves</a>
 842   <li> Wikipedia, <a href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve">B&eacute;zier curve</a>
 843
 844 </ul>
 845
 846
 847 <a name='sect-feedback'><h2>Feedback</h2></a>
 848
 849 <p>If you have any questions, comments, bug reports, or other feedback
 850 regarding Vecto, please email <a href="mailto:xach@xach.com">Zach
 851 Beane</a>.
 852
 853 <p><hr>
 854 <tt>$Id: index.html,v 1.27 2007/10/01 20:03:18 xach Exp $</tt>
 855