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