File: index.html

package info (click to toggle)
cl-gd 0.5.6-4
links: PTS
area: main
in suites: lenny
size: 544 kB
ctags: 269
sloc: lisp: 2,758; ansic: 264; makefile: 59
file content (1441 lines) | stat: -rw-r--r-- 90,086 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html> 

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <title>CL-GD - Use the GD Graphics library from Common Lisp</title>
  <style type="text/css">
  pre { padding:5px; background-color:#e0e0e0 }
  h3, h4 { text-decoration: underline; }
  a { text-decoration: none; padding: 1px 2px 1px 2px; }
  a:visited { text-decoration: none; padding: 1px 2px 1px 2px; }
  a:hover { text-decoration: none; padding: 1px 1px 1px 1px; border: 1px solid #000000; } 
  a:focus { text-decoration: none; padding: 1px 2px 1px 2px; border: none; }
  a.none { text-decoration: none; padding: 0; }
  a.none:visited { text-decoration: none; padding: 0; } 
  a.none:hover { text-decoration: none; border: none; padding: 0; } 
  a.none:focus { text-decoration: none; border: none; padding: 0; } 
  a.noborder { text-decoration: none; padding: 0; } 
  a.noborder:visited { text-decoration: none; padding: 0; } 
  a.noborder:hover { text-decoration: none; border: none; padding: 0; } 
  a.noborder:focus { text-decoration: none; border: none; padding: 0; }  
  pre.none { padding:5px; background-color:#ffffff }
  </style>
</head>

<body bgcolor=white>

<h2>CL-GD - Use the GD Graphics library from Common Lisp</h2>

<blockquote>
<br>&nbsp;<br><h3>Abstract</h3>

CL-GD is a library for Common Lisp which provides an interface to the
<a href="http://www.boutell.com/gd/">GD Graphics Library</a> for the
dynamic creation of images. It is based on <a
href="http://uffi.b9.com/">UFFI</a> and should thus be portable to all
CL implementations supported by UFFI.
<p>
A version which also works with CLISP is available from <a
href="http://ungil.com/cl-gd-clisp.tgz">http://ungil.com/cl-gd-clisp.tgz</a>
thanks to Carlos Ungil.  Also, beginning from version 0.5.0/0.5.1, CL-GD
contains initial code to support CLISP and OpenMCL via <a
href="http://common-lisp.net/project/cffi/">CFFI</a> (<a href="http://common-lisp.net/pipermail/cl-gd-devel/2005-September/000030.html">thanks to Luis
Oliveira</a> and Bryan O'Connor).  Please try it and report to <a href="#mail">the mailing list</a> if you 
have problems.
<p>
The focus of CL-GD is convenience and correctness, not necessarily speed. If you think CL-GD is too slow and you're concerned about speed, <a href="#mail">contact me</a> before you start coding in C... :)
<p>
CL-GD comes with a <a
href="http://www.opensource.org/licenses/bsd-license.php">BSD-style
license</a> so you can basically do with it whatever you want. Please send bug reports to <a href="#mail">the mailing list</a> mentioned below if you encounter any problems with CL-GD. (I'm glad to fix CL-GD but I can't do much about GD, of course. So if CL-GD basically works for you but you encounter seemingly strange behaviour when drawing please try if and how you can achieve the intended result with GD directly. That would help me a lot. Thanks.)
<p>
CL-GD is used by <a href="http://www.quickhoney.com/">QuickHoney</a>.

<p>
<font color=red>Download shortcut:</font> <a href="http://weitz.de/files/cl-gd.tar.gz">http://weitz.de/files/cl-gd.tar.gz</a>.
</blockquote>

<br>&nbsp;<br><h3><a href="#contents" name="example" class=none>A simple example</a></h3>

The image to the right was created with this piece of code:

<pre>
<img alt="chart.png" title="chart.png" align=right border=0 vspace=10 hspace=10 width=200 height=200 src="chart.png">(<a class=noborder href="#with-image*">with-image*</a> (200 200) <font color=orange>; create 200x200 pixel image</font>
  (<a class=noborder href="#allocate-color">allocate-color</a> 68 70 85) <font color=orange>; background color</font>
  (let ((beige (allocate-color 222 200 81))
        (brown (allocate-color 206 150 75))
        (green (allocate-color 104 156 84))
        (red (allocate-color 163 83 84))
        (white (allocate-color 255 255 255))
        (two-pi (* 2 pi)))
    <font color=orange>;; move origin to center of image</font>
    (<a class=noborder href="#with-transformation">with-transformation</a> (:x1 -100 :x2 100 :y1 -100 :y2 100 :radians t)
      <font color=orange>;; draw some 'pie slices'</font>
      (<a class=noborder href="#draw-arc">draw-arc</a> 0 0 130 130 0 (* .6 two-pi)
                :center-connect t :filled t :color beige)
      (draw-arc 0 0 130 130 (* .6 two-pi) (* .8 two-pi)
                :center-connect t :filled t :color brown)
      (draw-arc 0 0 130 130 (* .8 two-pi) (* .95 two-pi)
                :center-connect t :filled t :color green)
      (draw-arc 0 0 130 130 (* .95 two-pi) two-pi
                :center-connect t :filled t :color red)
      (<a class=noborder href="#with-default-color">with-default-color</a> (white)
        (<a class=noborder href="#with-default-font">with-default-font</a> (:small)
          (<a class=noborder href="#draw-string">draw-string</a> -8 -30 &quot;60%&quot;)
          (draw-string -20 40 &quot;20%&quot;)
          (draw-string 20 30 &quot;15%&quot;))
        (<a class=noborder href="#draw-freetype-string">draw-freetype-string</a> -90 75 &quot;Global Revenue&quot;
                              <font color=orange>;; this assumes that 'DEFAULT_FONTPATH'</font>
                              <font color=orange>;; is set correctly</font>
                              :font-name &quot;verdanab&quot;))))
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;chart.png&quot;
                       :compression-level 6 :if-exists :supersede))
</pre>

<p>
See below for more examples.

<br>&nbsp;<br><h3><a class=none name="contents">Contents</a></h3>
<ul>
  <li><a href="#example">A simple example</a>
  <li><a href="#install">Download and installation</a>
  <li><a href="#mail">Support and mailing lists</a>
  <li><a href="#images">Images</a>
  <ul>
    <li><a href="#create-image"><code>create-image</code></a>
    <li><a href="#create-image-from-file"><code>create-image-from-file</code></a>
    <li><a href="#create-image-from-gd2-part"><code>create-image-from-gd2-part</code></a>
    <li><a href="#destroy-image"><code>destroy-image</code></a>
    <li><a href="#with-image"><code>with-image</code></a>
    <li><a href="#with-image-from-file"><code>with-image-from-file</code></a>
    <li><a href="#with-image-from-gd2-part"><code>with-image-from-gd2-part</code></a>
    <li><a href="#default-image"><code>*default-image*</code></a>
    <li><a href="#with-default-image"><code>with-default-image</code></a>
    <li><a href="#with-image*"><code>with-image*</code></a>
    <li><a href="#with-image-from-file*"><code>with-image-from-file*</code></a>
    <li><a href="#with-image-from-gd2-part*"><code>with-image-from-gd2-part*</code></a>
    <li><a href="#write-jpeg-to-stream"><code>write-jpeg-to-stream</code></a>
    <li><a href="#write-png-to-stream"><code>write-png-to-stream</code></a>
    <li><a href="#write-wbmp-to-stream"><code>write-wbmp-to-stream</code></a>
    <li><a href="#write-gif-to-stream"><code>write-gif-to-stream</code></a>
    <li><a href="#write-gd-to-stream"><code>write-gd-to-stream</code></a>
    <li><a href="#write-gd2-to-stream"><code>write-gd2-to-stream</code></a>
    <li><a href="#write-image-to-stream"><code>write-image-to-stream</code></a>
    <li><a href="#write-image-to-file"><code>write-image-to-file</code></a>
    <li><a href="#image-width"><code>image-width</code></a>
    <li><a href="#image-height"><code>image-height</code></a>
    <li><a href="#image-size"><code>image-size</code></a>
  </ul>
  <li><a href="#colors">Colors</a>
  <ul>
    <li><a href="#default-color"><code>*default-color*</code></a>
    <li><a href="#with-default-color"><code>with-default-color</code></a>
    <li><a href="#allocate-color"><code>allocate-color</code></a>
    <li><a href="#find-color"><code>find-color</code></a>
    <li><a href="#find-color-from-image"><code>find-color-from-image</code></a>
    <li><a href="#color-component"><code>color-component</code></a>
    <li><a href="#color-components"><code>color-components</code></a>
    <li><a href="#deallocate-color"><code>deallocate-color</code></a>
    <li><a href="#true-color-p"><code>true-color-p</code></a>
    <li><a href="#number-of-colors"><code>number-of-colors</code></a>
    <li><a href="#max-colors"><code>+max-colors+</code></a>
    <li><a href="#transparent-color"><code>transparent-color</code></a>
    <li><a href="#alpha-blending-p"><code>alpha-blending-p</code></a>
    <li><a href="#save-alpha-p"><code>save-alpha-p</code></a>
  </ul>
  <li><a href="#brushes">Styles, brushes, tiles, anti-aliased lines</a>
  <ul>
    <li><a href="#make-brush"><code>make-brush</code></a>
    <li><a href="#make-tile"><code>make-tile</code></a>
    <li><a href="#make-anti-aliased"><code>make-anti-aliased</code></a>
  </ul>
  <li><a href="#transformations">Transformations</a>
  <ul>
    <li><a href="#with-transformation"><code>with-transformation</code></a>
    <li><a href="#without-transformations"><code>without-transformations</code></a>
  </ul>
  <li><a href="#drawing">Drawing and filling</a>
  <ul>
    <li><a href="#get-pixel"><code>get-pixel</code></a>
    <li><a href="#set-pixel"><code>set-pixel</code></a>
    <li><a href="#set-pixels"><code>set-pixels</code></a>
    <li><a href="#draw-line"><code>draw-line</code></a>
    <li><a href="#draw-rectangle"><code>draw-rectangle</code></a>
    <li><a href="#draw-rectangle*"><code>draw-rectangle*</code></a>
    <li><a href="#draw-polygon"><code>draw-polygon</code></a>
    <li><a href="#draw-filled-circle"><code>draw-filled-circle</code></a>
    <li><a href="#draw-filled-ellipse"><code>draw-filled-ellipse</code></a>
    <li><a href="#draw-arc"><code>draw-arc</code></a>
    <li><a href="#fill-image"><code>fill-image</code></a>
    <li><a href="#clipping-rectangle"><code>clipping-rectangle</code></a>
    <li><a href="#clipping-rectangle*"><code>clipping-rectangle*</code></a>
    <li><a href="#set-clipping-rectangle*"><code>set-clipping-rectangle*</code></a>
    <li><a href="#with-clipping-rectangle"><code>with-clipping-rectangle</code></a>
    <li><a href="#with-clipping-rectangle*"><code>with-clipping-rectangle*</code></a>
    <li><a href="#current-thickness"><code>current-thickness</code></a>
    <li><a href="#with-thickness"><code>with-thickness</code></a>
  </ul>
  <li><a href="#strings">Strings and characters</a>
  <ul>
    <li><a href="#default-font"><code>*default-font*</code></a>
    <li><a href="#with-default-font"><code>with-default-font</code></a>
    <li><a href="#draw-character"><code>draw-character</code></a>
    <li><a href="#draw-string"><code>draw-string</code></a>
    <li><a href="#draw-freetype-string"><code>draw-freetype-string</code></a>
  </ul>
  <li><a href="#misc">Miscellaneous</a>
  <ul>
    <li><a href="#do-rows"><code>do-rows</code></a>
    <li><a href="#do-pixels-in-row"><code>do-pixels-in-row</code></a>
    <li><a href="#do-pixels"><code>do-pixels</code></a>
    <li><a href="#raw-pixel"><code>raw-pixel</code></a>
    <li><a href="#interlacedp"><code>interlacedp</code></a>
    <li><a href="#differentp"><code>differentp</code></a>
    <li><a href="#copy-image"><code>copy-image</code></a>
    <li><a href="#copy-palette"><code>copy-palette</code></a>
    <li><a href="#true-color-to-palette"><code>true-color-to-palette</code></a>
  </ul>
  <li><a href="#ack">Acknowledgements</a>
</ul>

<br>&nbsp;<br><h3><a href="#contents" name="install" class=none>Download and installation</a></h3>

CL-GD together with this documentation can be downloaded from <a
href="http://weitz.de/files/cl-gd.tar.gz">http://weitz.de/files/cl-gd.tar.gz</a>. The
current version is 0.5.6.  A <a href="http://packages.debian.org/cgi-bin/search_packages.pl?keywords=cl-gd&amp;searchon=names&amp;subword=1&amp;version=all&amp;release=all">Debian package</a> is available thanks to <a href="http://pvaneynd.mailworks.org/">Peter van Eynde</a> and <a href="http://b9.com/">Kevin Rosenberg</a>, so if you're on Debian you should have no problems installing CL-GD. There's also a port
for <a href="http://www.gentoo.org/proj/en/common-lisp/index.xml">Gentoo Linux</a> thanks to Matthew Kennedy. Otherwise, proceed like this:
<ul>
<li>Download and install a recent version of <a href="http://www.cliki.net/asdf">asdf</a>.
<li>Download and install <a href="http://uffi.b9.com/">UFFI</a>. CL-GD needs at least version&nbsp;1.3.4 of UFFI to work properly. However, as of August 2003, only AllegroCL, CMUCL, LispWorks, SBCL, and SCL are fully supported because CL-GD needs the new UFFI macros <a href="http://uffi.b9.com/manual/with-cast-pointer.html"><code>WITH-CAST-POINTER</code></a> and <a href="http://uffi.b9.com/manual/def-foreign-var.html"><code>DEF-FOREIGN-VAR</code></a> which haven't yet been ported to all UFFI platforms.  <b>Note:</b> For CLISP or OpenMCL download and install <a
href="http://common-lisp.net/project/cffi/">CFFI</a> instead.
<li>Download and install a recent version of <a href="http://www.boutell.com/gd/">GD</a> and its supporting libraries <a href="http://www.libpng.org/pub/png/">libpng</a>, <a href="http://www.info-zip.org/pub/infozip/zlib/">zlib</a>, <a href="http://www.ijg.org/">libjpeg</a>, <a href="http://www.freetype.org/">libfreetype</a>, and maybe <a href="http://www.gnu.org/software/libiconv/">libiconv</a>. CL-GD has been tested and developed with GD 2.0.28, older version probably won't work. Note that you won't be able to compile CL-GD unless you have installed <em>all</em> supporting libraries. This is different from using GD directly from C where you only have to install the libraries you intend to use.
<li>Download <a href="http://weitz.de/files/cl-gd.tar.gz"><code>cl-gd.tar.gz</code></a>, unzip and untar the file and put the resulting directory wherever you want, then cd into this directory.
<li>Compile <code>cl-gd-glue.c</code> into a shared library for your platform. On FreeBSD or Linux this would be
<pre>
gcc -fPIC -c cl-gd-glue.c
ld -lgd -lz -lpng -ljpeg -lfreetype -lm -shared cl-gd-glue.o -o cl-gd-glue.so
rm cl-gd-glue.o
</pre>
(Note: On older versions of Linux, you might have to add <code>-liconv</code>.)
<p>
For Mac OS X, use
<pre>
gcc -lgd -ljpeg -dynamiclib cl-gd-glue.c -o cl-gd-glue.dylib
</pre>
<li>Make sure that <code>cl-gd.asd</code> can be seen from asdf (this is usually achieved by a symbolic link), start your favorite Lisp, and compile CL-GD:
<pre>
(asdf:oos 'asdf:compile-op :cl-gd)
</pre>
<li>From now on you can simply load CL-GD into a running Lisp image with
<pre>
(asdf:oos 'asdf:load-op :cl-gd)
</pre>
<li>To build <em>without</em> GIF support compile the C library with the option <code>-DGD_DONT_USE_GIF</code> and push the symbol <code>:CL-GD-NO-GIF</code> onto <a href="http://www.lispworks.com/documentation/HyperSpec/Body/v_featur.htm"><code>*FEATURES*</code></a> <em>before</em> compiling CL-GD.

<li>CL-GD comes with a simple test suite that can be used to check if it's
basically working. Note that this'll only test a subset of CL-GD. To
run the tests load CL-GD and then
<pre>
(asdf:oos 'asdf:load-op :cl-gd-test)
(cl-gd-test:test)
</pre>
If you have the <a
href="http://corefonts.sourceforge.net/"><code>georgiab.ttf</code>
TrueType font from Microsoft</a> you can also check the FreeType
support of CL-GD with
<pre>
(cl-gd-test:test #p&quot;/usr/X11R6/lib/X11/fonts/truetype/georgiab.ttf&quot;)
</pre>
where you should obviously replace the path above with the pull path
to the font on your machine.  </ul>
<p>
Note that CL-GD might work correctly even if some of the tests fail
(as long as you don't get error messages). The exact results of the
tests seem to depend on the versions of the C&nbsp;libraries which are
used.
<p>
<b>It is recommended that you at least skim over the <a href="http://www.boutell.com/gd/manual2.0.33.html">original GD documentation</a> before you start using CL-GD.</b>
<p>
Note: If you're on Windows you might want to try this:
<ul>
<li>Download and install the supporting libraries (see above) from <a href="http://gnuwin32.sf.net/">GnuWin32</a> and put the DLLs into a place where your Lisp's FFI will find them. The folder where your Lisp image starts up is usually a good place.
<li>Download the file <code>cl-gd-glue.dll</code> from <a href="http://weitz.de/files/cl-gd-glue.dll">http://weitz.de/files/cl-gd-glue.dll</a> and put it into the CL-GD folder. You <em>don't</em> need to download and install GD itself because it's already integrated into <code>cl-gd-glue.dll</code>.
<li>Start your Lisp and compile CL-GD as described above.
</ul>
This works for me on Windows&nbsp;XP&nbsp;pro&nbsp;SP2 with AllegroCL&nbsp;6.2&nbsp;trial as well as with LispWorks&nbsp;4.3.7&nbsp;pro.
<p>
Lu&iacute;s Oliveira maintains a <a href="http://darcs.net/">darcs</a>
repository of CL-GD
at <a
href="http://common-lisp.net/~loliveira/ediware/">http://common-lisp.net/~loliveira/ediware/</a>.


<br>&nbsp;<br><h3><a name="mail" class=none>Support and mailing lists</a></h3>

For questions, bug reports, feature requests, improvements, or patches
please use the <a
href="http://common-lisp.net/mailman/listinfo/cl-gd-devel">cl-gd-devel
mailing list</a>. If you want to be notified about future releases
subscribe to the <a
href="http://common-lisp.net/mailman/listinfo/cl-gd-announce">cl-gd-announce
mailing list</a>. These mailing lists were made available thanks to
the services of <a href="http://common-lisp.net/">common-lisp.net</a>.
<p>
If you want to send patches, please <a href="http://weitz.de/patches.html">read this first</a>.

<br>&nbsp;<br><h3><a href="#contents" name="images" class=none>Images</a></h3>

In order to work with CL-GD you first have to create at least one
<em>image</em> - think of it as your canvas, kind of. Images can be
created from scratch or you can load an existing image file from
disk. After you've drawn something or otherwise modified your image
you can write it to a file or a stream. Once you're done with it you
must <em>destroy</em> it to avoid memory leaks. It is recommended that
you use the <code>WITH-IMAGE-</code> macros instead of the
<code>CREATE-IMAGE-</code> functions so you can be sure that images
will always be destroyed no matter what happens.

<p><br>[Function]
<br><a class=none name="create-image"><b>create-image</b> <i>width height <tt>&amp;optional</tt> true-color</i> =&gt; <i>image</i></a>

<blockquote><br>
Allocates and returns an image with size <code><i>width</i></code> <tt>x</tt> <code><i>height</i></code> (in pixels). Creates a true color image if
<code><i>true-color</i></code> is true - the default is <code>NIL</code>. You are responsible for
<a href="#destroy-image">destroying</a> the image after you're done with it. It is advisable to use
<a href="#with-image"><code>WITH-IMAGE</code></a> instead.
</blockquote>

<p><br>[Function]
<br><a class=none name="create-image-from-file"><b>create-image-from-file</b> <i>file-name <tt>&amp;optional</tt> type</i> =&gt; <i>image</i></a>

<blockquote><br>
Creates an image from the file specified by <code><i>file-name</i></code> (which is
either a pathname or a string). The type of the image can be provided
as <code><i>type</i></code> (one of the keywords <code>:JPG</code>, <code>:JPEG</code>, <code>:GIF</code>, <code>:PNG</code>, <code>:GD</code>, <code>:GD2</code>, <code>:XBM</code>, or <code>:XPM</code>), or otherwise it will be guessed from the <code>PATHNAME-TYPE</code> of
<code><i>file-name</i></code>. You are responsible for <a href="#destroy-image">destroying</a> the image after you're
done with it. It is advisable to use <a href="#with-image-from-file"><code>WITH-IMAGE-FROM-FILE</code></a> instead.
</blockquote>

<p><br>[Function]
<br><a class=none name="create-image-from-gd2-part"><b>create-image-from-gd2-part</b> <i>file-name src-x src-y width height</i> =&gt; <i>image</i></a>

<blockquote><br>
Creates an image from the part of the GD2 file specified by <code><i>file-name</i></code> (which is
either a pathname or a string) specified by <code><i>src-x</i></code>, <code><i>src-y</i></code>, <code><i>width</i></code>, and <code><i>height</i></code>. You are responsible for <a href="#destroy-image">destroying</a> the image after you're
done with it. It is advisable to use <a href="#with-image-from-gd2-part"><code>WITH-IMAGE-FROM-GD2-PART</code></a> instead.
</blockquote>

<p><br>[Function]
<br><a class=none name="destroy-image"><b>destroy-image</b> <i>image</i> =&gt; <i>result</i></a>

<blockquote><br>
Destroys (deallocates) <code><i>image</i></code> which has been created by <a href="#create-image"><code>CREATE-IMAGE</code></a>,
<a href="#create-image-from-file"><code>CREATE-IMAGE-FROM-FILE</code></a>, or <a href="#create-image-from-gd2-part"><code>CREATE-IMAGE-FROM-GD2-PART</code></a>. <code><i>result</i></code> is always <code>NIL</code>.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-image"><b>with-image</b> <i>(name width height <tt>&amp;optional</tt> true-color) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Creates an image as with <a
href="#create-image"><code>CREATE-IMAGE</code></a> and executes
<code><i>form*</i></code> with the image bound to
<code><i>name</i></code>. The image is
guaranteed to be <a href="#destroy-image">destroyed</a> before this macro exits.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-image-from-file"><b>with-image-from-file</b> <i>(name file-name <tt>&amp;optional</tt> type) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Creates an image as with <a
href="#create-image-from-file"><code>CREATE-IMAGE-FROM-FILE</code></a> and executes
<code><i>form*</i></code> with the image bound to
<code><i>name</i></code>. The image is
guaranteed to be <a href="#destroy-image">destroyed</a> before this macro exits.
</blockquote>

<pre>
(<a class=noborder href="#with-image-from-file">with-image-from-file</a> (old &quot;zappa.jpg&quot;)<img vspace=10 hspace=10 border=0 alt="zappa-green.jpg" title="zappa-green.jpg" src="zappa-green.jpg" width=150 height=200 align=right><img vspace=10 hspace=10 border=0 alt="zappa.jpg" title="zappa.jpg" src="zappa.jpg" width=150 height=200 align=right>
  (multiple-value-bind (width height)
      (<a class=noborder href="#image-size">image-size</a> old)
    (<a class=noborder href="#with-image">with-image</a> (new width height)
      (<a class=noborder href="#allocate-color">allocate-color</a> 0 255 0 :image new) <font color=orange>; green background</font>
      (<a class=noborder href="#copy-image">copy-image</a> old new 0 0 0 0 width height
                  :merge 50)
      (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;zappa-green.jpg&quot;
                           :image new
                           :if-exists :supersede))))
</pre>

<p><br>[Macro]
<br><a class=none name="with-image-from-gd2-part"><b>with-image-from-gd2-part</b> <i>(name file-name src-x src-y width height) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Creates an image as with <a
href="#create-image-from-gd2-part"><code>CREATE-IMAGE-FROM-GD2-PART</code></a> and executes
<code><i>form*</i></code> with the image bound to
<code><i>name</i></code>. The image is
guaranteed to be <a href="#destroy-image">destroyed</a> before this macro exits.
</blockquote>

<p><br>[Special variable]
<br><a class=none name="default-image"><b>*default-image*</b></a>

<blockquote><br>
Whenever a CL-GD function or macro has an optional or keyword argument called <em>image</em> the default is to use <code><i>*default-image*</i></code>. The idea behind this is that you'll never have to provide these arguments as long as you work with one image at a time (which should be the usual case). See the <a href="#example">example</a> at the top of the page.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-default-image"><b>with-default-image</b> <i>(image) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
This is just a convenience macro which will execute <code><i>form*</i></code> with <a href="#default-image"><code>*DEFAULT-IMAGE*</code></a> bound to <code><i>image</i></code>.
</blockquote>


<p><br>[Macro]
<br><a class=none name="with-image*"><b>with-image*</b> <i>(width height <tt>&amp;optional</tt> true-color) form*</i> =&gt; <i>results</i></a>
<p><br>[Macro]
<br><a class=none name="with-image-from-file*"><b>with-image-from-file*</b> <i>(file-name <tt>&amp;optional</tt> type) form*</i> =&gt; <i>results</i></a>
<p><br>[Macro]
<br><a class=none name="with-image-from-gd2-part*"><b>with-image-from-gd2-part*</b> <i>(file-name src-x src-y width height) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
These are essentially like their asterisk-less counterparts but bind the image to <a href="#default-image"><code>*DEFAULT-IMAGE*</code></a> instead.
</blockquote>


<P>
<b>For the rest of this document, whenever a function expects an image as
one of its arguments you <em>must</em> pass a value which was created
with one of the functions or macros above.</b> An image should be
considered an opaque object which you can pass to CL-GD functions but
should otherwise leave alone. (Internally it is a foreign pointer
wrapped in a <code>CL-GD::IMAGE</code> structure in order to enable
type checking.)

<p><br>[Function]
<br><a class=none name="write-jpeg-to-stream"><b>write-jpeg-to-stream</b> <i>stream <tt>&amp;key</tt> quality image</i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the stream
<code><i>stream</i></code> as a JPEG file. If
<code><i>quality</i></code> is not specified, the default <a href="http://www.ijg.org/">IJG</a> JPEG
quality value is used. Otherwise, 
<code><i>quality</i></code> must be an integer in the range&nbsp;0-100. <code><i>stream</i></code> must be a character stream or a binary
stream of element type <code>(UNSIGNED-BYTE&nbsp;8)</code>. If STREAM is a character
stream, the user of this function has to make sure the external format
yields <a href="http://cl-cookbook.sf.net/io.html#faith">faithful output</a> of all 8-bit characters. CL-GD knows about AllegroCL's <a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">simple streams</a> and the bivalent streams of <a href="http://www.lispworks.com/">LispWorks</a>&nbsp;4.3 and acts accordingly, i.e. it uses <code>WRITE-BYTE</code> instead of <code>WRITE-CHAR</code> whenever possible.
</blockquote>

<p><br>[Function]
<br><a class=none name="write-png-to-stream"><b>write-png-to-stream</b> <i>stream <tt>&amp;key</tt> compression-level image</i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the stream
<code><i>stream</i></code> as a PNG file. If
<code><i>compression-level</i></code> is not specified, the default compression level at
the time zlib was compiled on your system will be used.  Otherwise, a
compression level of&nbsp;0 means 'no compression', a compression level of&nbsp;1 means 'compressed, but as quickly as possible', a compression level
of&nbsp;9 means 'compressed as much as possible to produce the smallest
possible file.' <code><i>stream</i></code> must be a character stream or a binary
stream of element type <code>(UNSIGNED-BYTE&nbsp;8)</code>. If STREAM is a character
stream, the user of this function has to make sure the external format
yields <a href="http://cl-cookbook.sf.net/io.html#faith">faithful output</a> of all 8-bit characters. CL-GD knows about AllegroCL's <a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">simple streams</a> and the bivalent streams of <a href="http://www.lispworks.com/">LispWorks</a>&nbsp;4.3 and acts accordingly, i.e. it uses <code>WRITE-BYTE</code> instead of <code>WRITE-CHAR</code> whenever possible.
</blockquote>

<p><br>[Function]
<br><a class=none name="write-wbmp-to-stream"><b>write-wbmp-to-stream</b> <i>stream <tt>&amp;key</tt> foreground image</i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the stream
<code><i>stream</i></code> as a WBMP (wireless bitmap) file. WBMP file support is black and white
only. The <a href="#colors">color</a> specified by the <code><i>foreground</i></code> argument is the
&quot;foreground,&quot; and only pixels of this color will be set in the WBMP
file. <code><i>stream</i></code> must be a character stream or a binary
stream of element type <code>(UNSIGNED-BYTE&nbsp;8)</code>. If STREAM is a character
stream, the user of this function has to make sure the external format
yields <a href="http://cl-cookbook.sf.net/io.html#faith">faithful output</a> of all 8-bit characters. CL-GD knows about AllegroCL's <a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">simple streams</a> and the bivalent streams of <a href="http://www.lispworks.com/">LispWorks</a>&nbsp;4.3 and acts accordingly, i.e. it uses <code>WRITE-BYTE</code> instead of <code>WRITE-CHAR</code> whenever possible.
</blockquote>

<p><br>[Function]
<br><a class=none name="write-gd-to-stream"><b>write-gd-to-stream</b> <i>stream <tt>&amp;key</tt> image</i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the stream
<code><i>stream</i></code> as a GD file. <code><i>stream</i></code> must be a character stream or a binary
stream of element type <code>(UNSIGNED-BYTE&nbsp;8)</code>. If STREAM is a character
stream, the user of this function has to make sure the external format
yields <a href="http://cl-cookbook.sf.net/io.html#faith">faithful output</a> of all 8-bit characters. CL-GD knows about AllegroCL's <a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">simple streams</a> and the bivalent streams of <a href="http://www.lispworks.com/">LispWorks</a>&nbsp;4.3 and acts accordingly, i.e. it uses <code>WRITE-BYTE</code> instead of <code>WRITE-CHAR</code> whenever possible.
</blockquote>

<p><br>[Function]
<br><a class=none name="write-gif-to-stream"><b>write-gif-to-stream</b> <i>stream <tt>&amp;key</tt> image</i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the stream
<code><i>stream</i></code> as a GIF file. <code><i>stream</i></code> must be a character stream or a binary
stream of element type <code>(UNSIGNED-BYTE&nbsp;8)</code>. If STREAM is a character
stream, the user of this function has to make sure the external format
yields <a href="http://cl-cookbook.sf.net/io.html#faith">faithful output</a> of all 8-bit characters. CL-GD knows about AllegroCL's <a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">simple streams</a> and the bivalent streams of <a href="http://www.lispworks.com/">LispWorks</a>&nbsp;4.3 and acts accordingly, i.e. it uses <code>WRITE-BYTE</code> instead of <code>WRITE-CHAR</code> whenever possible.
</blockquote>

<p><br>[Function]
<br><a class=none name="write-gd2-to-stream"><b>write-gd2-to-stream</b> <i>stream <tt>&amp;key</tt> image</i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the stream
<code><i>stream</i></code> as a GD2 file. <code><i>stream</i></code> must be a character stream or a binary
stream of element type <code>(UNSIGNED-BYTE&nbsp;8)</code>. If STREAM is a character
stream, the user of this function has to make sure the external format
yields <a href="http://cl-cookbook.sf.net/io.html#faith">faithful output</a> of all 8-bit characters. CL-GD knows about AllegroCL's <a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">simple streams</a> and the bivalent streams of <a href="http://www.lispworks.com/">LispWorks</a>&nbsp;4.3 and acts accordingly, i.e. it uses <code>WRITE-BYTE</code> instead of <code>WRITE-CHAR</code> whenever possible.
</blockquote>

<p><br>[Function]
<br><a class=none name="write-image-to-stream"><b>write-image-to-stream</b> <i>stream type <tt>&amp;key</tt> <tt>&amp;allow-other-keys</tt></i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the stream
<code><i>stream</i></code>. The type of the image is determined by <code><i>type</i></code>
which must be one of the keywords <code>:JPG</code>, <code>:JPEG</code>, <code>:GIF</code>, <code>:PNG</code>, <code>:WBMP</code>, <code>:GD</code>, or <code>:GD2</code>. The rest of the keyword arguments are handed over to the corresponding <code>WRITE-<i>XXX</i>-TO-STREAM</code> function. <code><i>stream</i></code> must be a character stream or a binary
stream of element type <code>(UNSIGNED-BYTE&nbsp;8)</code>. If STREAM is a character
stream, the user of this function has to make sure the external format
yields <a href="http://cl-cookbook.sf.net/io.html#faith">faithful output</a> of all 8-bit characters. CL-GD knows about AllegroCL's <a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">simple streams</a> and the bivalent streams of <a href="http://www.lispworks.com/">LispWorks</a>&nbsp;4.3 and acts accordingly, i.e. it uses <code>WRITE-BYTE</code> instead of <code>WRITE-CHAR</code> whenever possible.
</blockquote>

<p><br>[Function]
<br><a class=none name="write-image-to-file"><b>write-image-to-file</b> <i>file-name <tt>&amp;key</tt> type if-exists <tt>&amp;allow-other-keys</tt></i> =&gt; <i>image</i></a>

<blockquote><br>
Writes image <code><i>image</i></code> to the file specified by <code><i>file-name</i></code> (which is
either a pathname or a string). The <code><i>type</i></code> argument is interpreted as in <a href="#write-image-to-stream"><code>WRITE-IMAGE-TO-STREAM</code></a>. If it is not provided it will be guessed from the <code>PATHNAME-TYPE</code> of
<code><i>file-name</i></code>. The <code><i>if-exists</i></code> keyword argument is given to <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_open.htm"><code>OPEN</code></a>,
the rest of the keyword arguments are handed over to the corresponding <code>WRITE-<i>XXX</i>-TO-STREAM</code> function. 
</blockquote>

<p><br>[Function]
<br><a class=none name="image-width"><b>image-width</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>width</i></a>

<blockquote><br>
Returns the width of the image <code><i>image</i></code>. The result of this function is affected by <a href="#with-transformation"><code>WITH-TRANSFORMATION</code></a>.
</blockquote>

<p><br>[Function]
<br><a class=none name="image-height"><b>image-height</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>height</i></a>

<blockquote><br>
Returns the height of the image <code><i>image</i></code>. The result of this function is affected by <a href="#with-transformation"><code>WITH-TRANSFORMATION</code></a>.
</blockquote>

<p><br>[Function]
<br><a class=none name="image-size"><b>image-size</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>width, height</i></a>

<blockquote><br>
Returns the width and height of the image <code><i>image</i></code> as two values. The results of this function are affected by <a href="#with-transformation"><code>WITH-TRANSFORMATION</code></a>.
</blockquote>

<br>&nbsp;<br><h3><a href="#contents" name="colors" class=none>Colors</a></h3>

Images in CL-GD are usually palette-based (although true color images
are also supported) and colors have to be <a
href="#allocate-color">allocated</a> before they can be used, i.e. <b>whenever a function expects a color as
one of its arguments you <em>must</em> pass a value which was created
with one of the functions below or with a 'special' color as described in the <a href="#brushes">next section</a></b>.
<p>
Colors
are determined by specifying values for their red, green, blue, and
optionally alpha <a href="#color-component">components</a>. The first
three have to be integer values in the range&nbsp;0-255 while the last
one has to be in the range&nbsp;0-127. For a palette-based image the
first color you allocate will be its background color. Note that
colors are allocated per image, i.e. you can't allocate a color in one
image and then use it to draw something in another image.
<p>
See also the <a href="#brushes">next section</a> for some 'special colors.'

<p><br>[Special variable]
<br><a class=none name="default-color"><b>*default-color*</b></a>

<blockquote><br>
Whenever a CL-GD function or macro has an optional or keyword argument called <em>color</em> the default is to use <code><i>*default-color*</i></code>. See <a href="#with-default-color"><code>WITH-DEFAULT-COLOR</code></a> below.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-default-color"><b>with-default-color</b> <i>(color) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
This is just a convenience macro which will execute <code><i>form*</i></code> with <a href="#default-color"><code>*DEFAULT-COLOR*</code></a> bound to <code><i>color</i></code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="allocate-color"><b>allocate-color</b> <i>red green blue <tt>&amp;key</tt> alpha errorp image</i> =&gt; <i>color</i></a>

<blockquote><br>
Finds the first available color index in the image <code><i>image</i></code> specified,
sets its RGB values to those requested (255 is the maximum for each),
and returns the index of the new color table entry, or an RGBA value in
the case of a true color image. In either case you can then use the
returned value as a color parameter to drawing functions. When
creating a new palette-based image, the first time you invoke this
function  you are setting the background color for that image. If
<code><i>alpha</i></code> (not greater than 127) is provided, an RGBA color will always
be allocated. If all <a href="#max-colors"><code>+MAX-COLORS+</code></a> have already been allocated this
function will, depending on the value of <code><i>errorp</i></code>, either raise an error
or return <code>NIL</code>. The default is to raise an error.
</blockquote>

<p><br>[Function]
<br><a class=none name="find-color"><b>find-color</b> <i>red green blue <tt>&amp;key</tt> alpha exact hwb resolve image</i> =&gt; <i>color</i></a>

<blockquote><br>
Tries to find and/or allocate a color from <code><i>image</i></code>'s color
palette. If <code><i>exact</i></code> is <em>true</em>, the color will only be returned if it is
already allocated. If <code><i>exact</i></code> is <em>false</em>, a color which is 'close' to
the color specified by <code><i>red</i></code>, <code><i>green</i></code>, and <code><i>blue</i></code> (and probably <code><i>alpha</i></code>)
might be returned (unless there aren't any colors allocated in the
image yet). If <code><i>hwb</i></code> is <em>true</em>, the 'closeness' will be determined by hue,
whiteness, and blackness, otherwise by the Euclidian distance of the
RGB values. If <code><i>resolve</i></code> is <em>true</em> a color (probably a new one) will
always be returned, otherwise the result of this function might be
<code>NIL</code>. If <code><i>alpha</i></code> (not greater than 127) is provided, an RGBA color (or
<code>NIL</code>) will be returned.
<code><i>alpha</i></code>, <code><i>exact</i></code>, and <code><i>hwb</i></code> are mutually exclusive. <code><i>resolve</i></code> can't be used
together with <code><i>exact</i></code> or <code><i>hwb</i></code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="find-color-from-image"><b>find-color-from-image</b> <i>color source-image <tt>&amp;key</tt> alpha exact hwb resolve image</i> =&gt; <i>color</i></a>

<blockquote><br>
Tries to find and/or allocate a color from <code><i>image</i></code>'s color
palette that corresponds to <code><i>color</i></code> in <code><i>source-image</i></code>.
<code><i>find-color-from-image</i></code> calls <a href="#find-color"><code><i>find-color</i></code></a>
with the color components of <code><i>color</i></code>.
Refer to <a href="#find-color"><code><i>find-color</i></code></a> for a description of the
keyword arguments.
</blockquote>

<p><br>[Function]
<br><a class=none name="color-component"><b>color-component</b> <i>color component <tt>&amp;key</tt> image</i> =&gt; <i>component</i></a>

<blockquote><br>
Returns the specified color component of <code><i>color</i></code>. <code><i>component</i></code> can be
one of <code>:RED</code>, <code>:GREEN</code>, <code>:BLUE</code>, and <code>:ALPHA</code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="color-components"><b>color-components</b> <i>color <tt>&amp;key</tt> image</i> =&gt; <i>components</i></a>

<blockquote><br>
Returns the color components of <code><i>color</i></code> as a list. The components are in the
order red, green, blue, alpha.
</blockquote>

<pre>
* (defun foo ()
    (<a class=noborder href="#with-image*">with-image*</a> (10 10)
      (loop for i below <a class=noborder href="#max-colors">+max-colors+</a> do
            <font color=orange>;; allocate enough colors (all gray) to fill the palette</font>
            (<a class=noborder href="#allocate-color">allocate-color</a> i i i))
      (format t &quot;Number of colors allocated: ~A~%&quot; (<a class=noborder href="#number-of-colors">number-of-colors</a>))
      (format t &quot;Maximal number of colors: ~A~%&quot; <a class=noborder href="#max-colors">+max-colors+</a>)
      (format t &quot;Exact match for red: ~A~%&quot; (<a class=noborder href="#find-color">find-color</a> 255 0 0 :exact t))
      (format t &quot;Red, green, and blue components of 'closest' match for red: ~A~%&quot;
              (let ((match (<a class=noborder href="#find-color">find-color</a> 255 0 0)))
                (if match
                  (list (<a class=noborder href="#color-component">color-component</a> :red match)
                        (<a class=noborder href="#color-component">color-component</a> :green match)
                        (<a class=noborder href="#color-component">color-component</a> :blue match))))))
    (values))

FOO
* (foo)
Number of colors allocated: 256
Maximal number of colors: 256
Exact match for red: NIL
Red, green, and blue components of 'closest' match for red: (64 64 64)
</pre>

<p><br>[Function]
<br><a class=none name="deallocate-color"><b>deallocate-color</b> <i>color <tt>&amp;optional</tt> image</i> =&gt; <i>color</i></a>

<blockquote><br>
Marks the specified color <code><i>color</i></code> as being available for reuse. No
attempt will be made to determine whether the color index is still in
use in the image <code><i>image</i></code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="true-color-p"><b>true-color-p</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>result</i></a>

<blockquote><br>
Returns <em>true</em> iff <code><i>image</i></code> is a true color image.
</blockquote>

<p><br>[Function]
<br><a class=none name="number-of-colors"><b>number-of-colors</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>result</i></a>

<blockquote><br>
Returns the number of colors allocated in <code><i>image</i></code> or NIL if <code><i>image</i></code> is a true color image.
</blockquote>

<p><br>[Constant]
<br><a class=none name="max-colors"><b>+max-colors+</b></a>

<blockquote><br>
Maximum number of colors for palette-based images.
</blockquote>

<p><br>[Accessor]
<br><a class=none name="transparent-color"><b>transparent-color</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>color</i>
<br><i>(setf (<b>transparent-color</b> <i><tt>&amp;optional</tt> image</i>) color)</i></a>

<blockquote><br>
Gets and sets the transparent color of <code><i>image</i></code>. If <code><i>color</i></code> is <code>NIL</code> there is no transparent color.
</blockquote>

<p><br>[Accessor]
<br><a class=none name="alpha-blending-p"><b>alpha-blending-p</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>blending</i>
<br><i>(setf (<b>alpha-blending-p</b> <i><tt>&amp;optional</tt> image</i>) blending)</i></a>

<blockquote><br>
Gets and set whether pixels drawn on <code><i>image</i></code> will be copied literally
including alpha channel information (if <code><i>blending</i></code> is <em>false</em>) or if
their alpha channel information will determine how much of the
underlying color will shine through (if <code><i>blending</i></code> is <em>true</em>). This is
only meaningful for true color images.
</blockquote>

<p><br>[Accessor]
<br><a class=none name="save-alpha-p"><b>save-alpha-p</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>save</i>
<br><i>(setf (<b>save-alpha-p</b> <i><tt>&amp;optional</tt> image</i>) save)</i></a>

<blockquote><br>
Gets and sets whether PNG images will be saved with full alpha channel information.
</blockquote>

<pre>
(<a class=noborder href="#with-image*">with-image*</a> (200 100)<img vspace=10 hspace=10 border=0 alt="brushed-arc.png" title="brushed-arc.png" src="brushed-arc.png" width=200 height=100 align=right>
  (<a class=noborder href="#allocate-color">allocate-color</a> 255 165 0) <font color=orange>; orange background</font>
  (<a class=noborder href="#with-image">with-image</a> (brush 6 6)
    (let* ((black (<a class=noborder href="#allocate-color">allocate-color</a> 0 0 0 :image brush)) <font color=orange>; black background</font>
           (red (<a class=noborder href="#allocate-color">allocate-color</a> 255 0 0 :image brush))
           (blue (<a class=noborder href="#allocate-color">allocate-color</a> 0 0 255 :image brush)))
      (setf (<a class=noborder href="#transparent-color">transparent-color</a> brush) black) <font color=orange>; make background transparent</font>
      <font color=orange>;; now set the pixels in the brush</font>
      (<a class=noborder href="#set-pixels">set-pixels</a> '(2 2 2 3 3 2 3 3)
                  :color blue :image brush)
      (<a class=noborder href="#set-pixels">set-pixels</a> '(3 2 3 3 1 2 1 3 4 2 4 3 2 1 3 1 2 4 3 4)
                  :color red :image brush)
      <font color=orange>;; then use it to draw an arc</font>
      (<a class=noborder href="#draw-arc">draw-arc</a> 100 50 180 80 180 300
                <font color=orange>;; convert BRUSH to brush</font>
                :color (<a class=noborder href="#make-brush">make-brush</a> brush)))
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;brushed-arc.png&quot;
                       :compression-level 7
                       :if-exists :supersede)))
</pre>

<br>&nbsp;<br><h3><a href="#contents" name="brushes" class=none>Styles, brushes, tiles, anti-aliased lines</a></h3>

Most <a href="#drawing">drawing</a> and <a href="#strings">string</a>
functions (with <a
href="#draw-freetype-string"><code>DRAW-FREETYPE-STRING</code></a>
being the only exception) will, when expecting a <a
href="#colors">color</a>, also accept other types of arguments. The
full range of allowed types which can be used for
<code><i>color</i></code> keyword arguments is listed below:

<ul>
  <li>A <em>style</em> which is either a list or a vector of colors
  allocated with one of the functions described above or
  <code>NIL</code> for transparent colors. When a style is used as the
  color, the colors of the pixels are drawn successively from the
  sequence provided. If the corresponding element of the sequence is
  <code>NIL</code>, that pixel is not altered.

  <li>A <em>brush</em> as created with <a
  href="#make-brush"><code>MAKE-BRUSH</code></a> for drawing lines. A
  brush is itself an <a href="#images">image</a> created as described
  above. When a brush is used as the color, the brush image is drawn
  in place of each pixel of the line drawn. (The brush is usually
  larger than one pixel, creating the effect of a wide paintbrush.)

  <li>A <em>tile</em> as created with <a
  href="#make-tile"><code>MAKE-TILE</code></a> for filling regions. A
  tile is itself an <a href="#images">image</a> created as described
  above. When a tile is used as the color, a pixel from the tile image
  is selected in such a way as to ensure that the filled area will be
  tiled with copies of the tile image.

  <li>A <code>CONS</code> where the <code>CAR</code> is a brush and
  the <code>CDR</code> is a list or a vector. This is called a
  <em>styled brush</em>. When a styled brush is used as the color, the
  brush image is drawn at each pixel of the line, provided that the
  corresponding element of the style sequence is <em>true</em>.
  (Pixels are drawn successively from the style as the line is drawn,
  returning to the beginning when the available pixels in the style
  are exhausted.) Note that the semantics described here differ
  slightly from the styles described above.

  <li>An <em>anti-aliased color</em> as created with <a
  href="#make-anti-aliased"><code>MAKE-ANTI-ALIASED</code></a> for
  drawing lines. When an anti-aliased color is used, the line is drawn
  with anti-aliasing mechanisms to minimize any &quot;jagged&quot;
  appearance.

  <li>A 'normal' color as created with one of the functions from the
  <a href="#colors">previous section</a>.

</ul>

Note that you can't arbitrarily combine 'color types' and drawing
functions, e.g. you can't set an anti-aliased pixel. However, it
should generally be obvious which types make sense and which don't.
Check the <a
href="http://www.boutell.com/gd/manual2.0.15.html">original GD
documentation</a> for more details. 
<p>
In GD itself, if you, say, change a brush after you've 'set' it with
<a
href="http://www.boutell.com/gd/manual2.0.15.html#gdImageSetBrush"><code>gdImageSetBrush</code></a>
but before you actually use it for drawing these changes won't be
visible, i.e. the brush is 'frozen' once it's 'set.' The same applies
to tiles and styles. CL-GD's behaviour differs in this regard,
i.e. brushes, tiles, and styles are 'set' at the very moment they're
used. This introduces a little bit of overhead but feels more 'Lisp-y'
and intuitive to me.

<p><br>[Function]
<br><a class=none name="make-brush"><b>make-brush</b> <i>image</i> =&gt; <i>brush</i></a>

<blockquote><br>

Creates a <a href="#brushes"><em>brush</em></a> from the <a
href="#images">image</a> <code><i>image</i></code>. Note that the new
brush is still 'linked' to <code><i>image</i></code>, i.e. changes you
make to <code><i>image</i></code> will also be visible in the
brush - the brush is just a kind of 'tagged' image.

</blockquote>

<p><br>[Function]
<br><a class=none name="make-tile"><b>make-tile</b> <i>image</i> =&gt; <i>tile</i></a>

<blockquote><br>

Creates a <a href="#brushes"><em>tile</em></a> from the <a
href="#images">image</a> <code><i>image</i></code>. Note that the new
tile is still 'linked' to <code><i>image</i></code>, i.e. changes you
make to <code><i>image</i></code> will also be visible in the
tile - the tile is just a kind of 'tagged' image.

</blockquote>

<p><br>[Function]
<br><a class=none name="make-anti-aliased"><b>make-anti-aliased</b> <i>color <tt>&amp;optional</tt>do-not-blend</i> =&gt; <i>color'</i></a>

<blockquote><br>

Creates an <a href="#brushes"><em>anti-aliased color</em></a> from the
<a href="#colors">color</a>
<code><i>color</i></code>. <code><i>do-not-blend</i></code> (if provided) is the
color anti-aliased lines stand out against clearly.

</blockquote>

<pre>
(<a class=noborder href="#with-image*">with-image*</a> (150 50)<img vspace=10 hspace=10 border=0 alt="anti-aliased-lines.png" title="anti-aliased-lines.png" src="anti-aliased-lines.png" width=150 height=50 align=right>
  (let ((orange (<a class=noborder href="#allocate-color">allocate-color</a> 255 165 0)) <font color=orange>; orange background</font>
        (white (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 255))
        (red (<a class=noborder href="#allocate-color">allocate-color</a> 255 0 0)))
    <font color=orange>;; white background rectangle in the middle third</font>
    (<a class=noborder href="#draw-rectangle*">draw-rectangle*</a> 50 0 99 49
                    :filled t
                    :color white)
    (<a class=noborder href="#with-thickness">with-thickness</a> (2)
      <font color=orange>;; just a red line</font>
      (<a class=noborder href="#draw-line">draw-line</a> 5 10 145 10 :color red)
      <font color=orange>;; anti-aliased red line</font>
      (<a class=noborder href="#draw-line">draw-line</a> 5 25 145 25 :color (<a class=noborder href="#make-anti-aliased">make-anti-aliased</a> red))
      <font color=orange>;; anti-aliased red line which should stand out against
      ;; orange background</font>
      (<a class=noborder href="#draw-line">draw-line</a> 5 40 145 40 :color (<a class=noborder href="#make-anti-aliased">make-anti-aliased</a> red orange))))
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;anti-aliased-lines.png&quot;
                       :compression-level 3
                       :if-exists :supersede))
</pre>

<br>&nbsp;<br><h3><a href="#contents" name="transformations" class=none>Transformations</a></h3>

Usually, CL-GD coordinates and dimensions (width and height) have to be integers. The origin <code>(0,0)</code> of an <a href="#images">image</a> is its upper left corner and all other points like <code>(X,Y)</code> have positive <code>X</code> and <code>Y</code> values. Angles are also provided as integers (in the range&nbsp;0-360) meaning degrees. A <em>transformation</em> provides a way to change this. 

<p><br>[Macro]
<br><a class=none name="with-transformation"><b>with-transformation</b> <i>(<tt>&amp;key</tt> x1 x2 width y1 y2 height reverse-x reverse-y radians image) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Executes <code><i>form*</i></code> such that all points and width/height data are
subject to a simple affine transformation defined by the keyword
parameters. The new x-axis of <code><i>image</i></code> will start at <code><i>x1</i></code> and end at <code><i>x2</i></code> and
have length <code><i>width</i></code>. The new y-axis of <code><i>image</i></code> will start at <code><i>y1</i></code> and end at
<code><i>y2</i></code> and have length <code><i>height</i></code>. In both cases it suffices to provide two of
the three values - if you provide all three they have to match. If
<code><i>reverse-x</i></code> is <em>false</em> the x-axis will be oriented as usual in Cartesian
coordinates, otherwise its direction will be reversed. The same
applies to <code><i>reverse-y</i></code>, of course. If <code><i>radians</i></code> is true angles inside of
the macro's body will be assumed to be provided in radians, otherwise in degrees. The previous transformation (if any) will be restored before this macro exits.
<p>
<code><i>with-transformation</i></code> macros can be nested but they always transform the <em>original</em> coordinates of the image, i.e. you shouldn't expect that, say, two succesive applications of <code><i>reverse-x</i></code> will neutralize each other. There's a little bit of overhead involved with this macro, so it is recommended to wrap it around everything you do with an image instead of calling it repeatedly. Note that transformations are always bound to one particular image.
</blockquote>

<p><br>[Macro]
<br><a class=none name="without-transformations"><b>without-transformations</b> <i>form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Executes <code><i>form*</i></code> without any transformations applied.
</blockquote>

<br>&nbsp;<br><h3><a href="#contents" name="drawing" class=none>Drawing and filling</a></h3>

This section (and the next one about <a href="#strings">strings</a>) finally describes how you can actually change the visual appearance of an <a href="#images">image</a>. You can set single pixels, draw lines or geometric figures, and fill regions. Note that the current <a href="#transformations">transformation</a> (if any) applies to the input and output of these functions.

<p><br>[Function]
<br><a class=none name="get-pixel"><b>get-pixel</b> <i>x y <tt>&amp;key</tt> image</i> =&gt; <i>color</i></a>

<blockquote><br>
Returns the <a href="#colors">color</a> of the pixel specified by <code><i>x</i></code> and <code><i>y</i></code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="set-pixel"><b>set-pixel</b> <i>x y <tt>&amp;key</tt> color image</i> =&gt; <i>x, y</i></a>

<blockquote><br>
Sets the pixel specified by <code><i>x</i></code> and <code><i>y</i></code> to the <a href="#colors">color</a> specified by <code><i>color</i></code>.
</blockquote>

<p><br>[Generic function]
<br><a class=none name="set-pixels"><b>set-pixels</b> <i>points <tt>&amp;key</tt> color image</i> =&gt; <i>points</i></a>

<blockquote><br>
Sets the pixels specified by <code><i>points</i></code> which can be a list <code>(X1&nbsp;Y1&nbsp;X2&nbsp;Y2&nbsp;...)</code> or a vector <code>#(X1&nbsp;Y1&nbsp;X2&nbsp;Y2&nbsp;...)</code> to the <a href="#colors">color</a> specified by <code><i>color</i></code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="draw-line"><b>draw-line</b> <i>x1 y1 x2 y2 <tt>&amp;key</tt> color image</i> =&gt; <i>x1, y1, x2, y2</i></a>

<blockquote><br>
Draws a line with <a href="#colors">color</a> <code><i>color</i></code> from point <code>(<i>x1</i>,<i>y1</i>)</code> to point <code>(<i>x2</i>,<i>y2</i>)</code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="draw-rectangle"><b>draw-rectangle</b> <i>rectangle <tt>&amp;key</tt> filled color image</i> =&gt; <i>rectangle</i></a>

<blockquote><br>
Draws a rectangle with upper left corner <code>(X1,Y1)</code> and lower right corner <code>(X2,Y2)</code> where <code><i>rectangle</i></code> is the list <code>(X1&nbsp;Y2&nbsp;X2&nbsp;Y2)</code>. If <code><i>filled</i></code> is <em>true</em> the rectangle will be filled with <code><i>color</i></code>, otherwise it will be outlined.
</blockquote>

<p><br>[Function]
<br><a class=none name="draw-rectangle*"><b>draw-rectangle*</b> <i>x1 y1 x2 y2 <tt>&amp;key</tt> filled color image</i> =&gt; <i>x1, y1, x2, y2</i></a>

<blockquote><br>
Draws a rectangle with upper left corner <code>(<i>x1</i>,<i>y1</i>)</code> and lower right corner <code>(<i>x2</i>,<i>y2</i>)</code>. If <code><i>filled</i></code> is <em>true</em> the rectangle will be filled with <code><i>color</i></code>, otherwise it will be outlined.
</blockquote>

<p><br>[Generic function]
<br><a class=none name="draw-polygon"><b>draw-polygon</b> <i>vertices <tt>&amp;key</tt> filled start end color image</i> =&gt; <i>vertices</i></a>

<blockquote><br>
Draws a polygon with the vertices (at least three)
specified as a list <code>(X1&nbsp;Y1&nbsp;X2&nbsp;Y2&nbsp;...)</code> or as a vector <code>#\(X1&nbsp;Y1&nbsp;X2&nbsp;Y2&nbsp;...)</code>.
If <code><i>filled</i></code> is true the polygon will be filled with the <a href="#colors">color</a> <code><i>color</i></code>,
otherwise it will be outlined. If <code><i>start</i></code> and/or <code><i>end</i></code> are specified then
only the corresponding part of <code><i>vertices</i></code> is used as input.
</blockquote>

<pre>
(<a class=noborder href="#with-image*">with-image*</a> (100 100)<img vspace=10 hspace=10 border=0 alt="triangle.png" title="triangle.png" src="triangle.png" width=100 height=100 align=right>
  (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 255) <font color=orange>; white background</font>
  (let ((red (<a class=noborder href="#allocate-color">allocate-color</a> 255 0 0))
        (yellow (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 0))
        (orange (<a class=noborder href="#allocate-color">allocate-color</a> 255 165 0)))
    <font color=orange>;; thin black border</font>
    (<a class=noborder href="#draw-rectangle*">draw-rectangle*</a> 0 0 99 99
                     :color (<a class=noborder href="#allocate-color">allocate-color</a> 0 0 0))
    <font color=orange>;; line thickness is five pixels</font>
    (<a class=noborder href="#with-thickness">with-thickness</a> (5)
      <font color=orange>;; triangle</font>
      (<a class=noborder href="#draw-polygon">draw-polygon</a> (list 10 10 90 50 50 90)
                    <font color=orange>;; styled color</font>
                    :color (list red red red
                                 yellow yellow yellow
                                 nil nil nil
                                 orange orange orange))
      (<a class=noborder href="#write-image-to-file">write-image-to-file</a> "triangle.png"
                           :compression-level 8
                           :if-exists :supersede))))
</pre>

<p><br>[Function]
<br><a class=none name="draw-filled-circle"><b>draw-filled-circle</b> <i>center-x center-y radius <tt>&amp;key</tt> color image</i> =&gt; <i>center-x center-y radius</i></a>

<blockquote><br>
Draws a filled circle with center <code>(<i>center-x</i>,<i>center-y</i>)</code> and radius <code><i>radius</i></code>.
</blockquote>

<p><br>[Function]
<br><a class=none name="draw-filled-ellipse"><b>draw-filled-ellipse</b> <i>center-x center-y width height <tt>&amp;key</tt> color image</i> =&gt; <i>center-x center-y width height</i></a>

<blockquote><br>
Draws a filled ellipse with center <code>(<i>center-x</i>,<i>center-y</i>)</code>, width <code><i>width</i></code>, and height <code><i>height</i></code>.
</blockquote>

<pre>
(<a class=noborder href="#with-image*">with-image*</a> (250 150)
  (<a class=noborder href="#with-image-from-file">with-image-from-file</a> (zappa &quot;smallzappa.png&quot;)<img vspace=10 hspace=0 border=0 alt="zappa-ellipse.png" title="zappa-ellipse.png" src="zappa-ellipse.png" width=250 height=150 align=right>
    (setf (<a class=noborder href="#transparent-color">transparent-color</a>) (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 255))
    (<a class=noborder href="#draw-filled-ellipse">draw-filled-ellipse</a> 125 75 250 150
                         :color (<a class=noborder href="#make-tile">make-tile</a> zappa)))
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;zappa-ellipse.png&quot;
                       :if-exists :supersede))
</pre>

<p><br>[Function]
<br><a class=none name="draw-arc"><b>draw-arc</b> <i>center-x center-y width height start end <tt>&amp;key</tt> straight-line center-connect filled color image</i> =&gt; <i>center-x, center-y, width, height, start, end</i></a>

<blockquote><br>
Draws a partial ellipse centered at <code>(<i>center-x</i>,<i>center-y</i>)</code> with
width <code><i>width</i></code> and height <code><i>height</i></code>. The arc begins at angle <code><i>start</i></code> and ends
at angle <code><i>end</i></code>. If <code><i>straight-line</i></code> is <em>true</em> the start and end points are
just connected with a straight line. If <code><i>center-connect</i></code> is true, they
are connected to the center (which is useful to create 'pie
slices' - see <a href="#example">example</a> at the top of the page.). If <code><i>filled</i></code> is true the arc will be filled with the <a href="#colors">color</a> <code><i>color</i></code>, otherwise it will be outlined.
</blockquote>

<p><br>[Function]
<br><a class=none name="fill-image"><b>fill-image</b> <i>x y <tt>&amp;key</tt> border color image</i> =&gt; <i>x, y</i></a>

<blockquote><br>
Floods a portion of the <a href="#images">image</a> <code><i>image</i></code> with the <a href="#colors">color</a> <code><i>color</i></code> beginning
at point <code>(<i>x</i>,<i>y</i>)</code> and extending into the surrounding region. If <code><i>border</i></code>
is true it must be a <a href="#colors">color</a> and the filling will stop at the specified
border color. (You can't use <a href="#brushes">'special colors'</a> for the border color.) Otherwise only points with the same color as the
starting point will be colored. If <code><i>color</i></code> is a <a href="#brushes">tile</a> the tile must not have a <a href="#transparent-color">transparent</a> color.
</blockquote>

<p><br>[Accessor]
<br><a class=none name="clipping-rectangle"><b>clipping-rectangle</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>rectangle</i>
<br><i>(setf (<b>clipping-rectangle</b> <i><tt>&amp;optional</tt> image</i>) rectangle)</i></a>

<blockquote><br>
Gets and sets the <em>clipping rectangle</em> of <code><i>image</i></code> where <code><i>rectangle</i></code> should be a
list <code>(X1&nbsp;Y1&nbsp;X2&nbsp;Y2)</code> describing the upper left and lower right corner of the rectangle. Once a clipping rectangle has been set, all future drawing operations on <code><i>image</i></code> will remain within the specified clipping area, until a new clipping rectangle is established. For instance, if a clipping rectangle <code>(25&nbsp;25&nbsp;75&nbsp;75)</code> has been set within a 100x100 image, a diagonal line from <code>(0,0)</code> to <code>(99,99)</code> will appear only between <code>(25,25)</code> and <code>(75,75)</code>. See also <a href="#clipping-rectangle*"><code>CLIPPING-RECTANGLE*</code></a> and <a href="#set-clipping-rectangle*"><code>SET-CLIPPING-RECTANGLE*</code></a>.
</blockquote>

<p><br>[Function]
<br><a class=none name="clipping-rectangle*"><b>clipping-rectangle*</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>x1, y1, x2, y2</i></a>

<blockquote><br>
Returns the <a href="#clipping-rectangle">clipping rectangle</a> of <code><i>image</i></code> as four values.
</blockquote>

<p><br>[Function]
<br><a class=none name="set-clipping-rectangle*"><b>set-clipping-rectangle*</b> <i>x1 y1 x2 y2 <tt>&amp;optional</tt> image</i> =&gt; <i>x1, y1, x2, y2</i></a>

<blockquote><br>
Sets the <a href="#clipping-rectangle">clipping rectangle</a> of <code><i>image</i></code> as if set with <code>(SETF&nbsp;(<a href="#clipping-rectangle"><code>CLIPPING-RECTANGLE</code></a>&nbsp;IMAGE)&nbsp;(LIST&nbsp;X1&nbsp;Y1&nbsp;X2&nbsp;Y2))</code>.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-clipping-rectangle"><b>with-clipping-rectangle</b> <i>(rectangle <tt>&amp;key</tt> image) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Executes <code><i>form*</i></code> with the <a href="#clipping-rectangle">clipping rectangle</a> of <code><i>image</i></code> set to <code><i>rectangle</i></code>
which should be a list as in <a href="#clipping-rectangle"><code>CLIPPING-RECTANGLE</code></a>. The previous clipping rectangle
is guaranteed to be restored before the macro exits.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-clipping-rectangle*"><b>with-clipping-rectangle*</b> <i>(x1 y1 x2 y2 <tt>&amp;key</tt> image) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Executes <code><i>form*</i></code> with the <a href="#clipping-rectangle">clipping rectangle</a> of <code><i>image</i></code> set as if set with <code>(SETF&nbsp;(<a href="#clipping-rectangle"><code>CLIPPING-RECTANGLE</code></a>&nbsp;IMAGE)&nbsp;(LIST&nbsp;X1&nbsp;Y1&nbsp;X2&nbsp;Y2))</code>. The previous clipping rectangle
is guaranteed to be restored before the macro exits.
</blockquote>

<pre>
(<a class=noborder href="#with-image*">with-image*</a> (150 150)<img vspace=10 hspace=10 border=0 alt="clipped-tangent.png" title="clipped-tangent.png" src="clipped-tangent.png" width=150 height=150 align=right>
  (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 255) <font color=orange>; white background</font>
  <font color=orange>;; transform such that x axis ranges from (- PI) to PI and y
  ;; axis ranges from -3 to 3</font>
  (<a class=noborder href="#with-transformation">with-transformation</a> (:x1 (- pi) :width (* 2 pi) :y1 -3 :y2 3)
    (let ((black (<a class=noborder href="#allocate-color">allocate-color</a> 0 0 0))
          (red (<a class=noborder href="#allocate-color">allocate-color</a> 255 0 0))
          (rectangle (list (- .4 pi) 2.5 (- pi .4) -2.5)))
      (<a class=noborder href="#with-default-color">with-default-color</a> (black)
        <font color=orange>;; draw axes</font>
        (<a class=noborder href="#draw-line">draw-line</a> 0 -3 0 3 :color black)
        (<a class=noborder href="#draw-line">draw-line</a> (- pi) 0 pi 0))
      <font color=orange>;; show clipping rectangle (styled)</font>
      (<a class=noborder href="#draw-rectangle">draw-rectangle</a> rectangle :color (list black black black nil black nil))
      (<a class=noborder href="#with-clipping-rectangle">with-clipping-rectangle</a> (rectangle)
        <font color=orange>;; draw tangent function</font>
        (loop for x from (- pi) below (* 2 pi) by (/ pi 75) do
              (<a class=noborder href="#set-pixel">set-pixel</a> x (tan x) :color red)))))
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;clipped-tangent.png&quot;
                       :if-exists :supersede))
</pre>

<p><br>[Accessor]
<br><a class=none name="current-thickness"><b>current-thickness</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>thickness</i>
<br><i>(setf (<b>current-thickness</b> <i><tt>&amp;optional</tt> image</i>) thickness)</i></a>

<blockquote><br>
Get and sets the current <em>thickness</em> of <code><i>image</i></code> in pixels. This determines the width of lines drawn with the <a href="#drawing">drawing</a> functions. <code><i>thickness</i></code> has to be an integer. See also <a href="#with-thickness"><code>WITH-THICKNESS</code></a>.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-thickness"><b>with-thickness</b> <i>(thickness <tt>&amp;key</tt> image) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
Executes <code><i>form*</i></code> with the <a href="#current-thickness">current thickness</a> of <code><i>image</i></code> set to <code><i>thickness</i></code>. The image's previous thickness is guaranteed to be restored
before the macro exits.
</blockquote>

<br>&nbsp;<br><h3><a href="#contents" name="strings" class=none>Characters and strings</a></h3>

CL-GD (actually GD) comes with five included fonts which can be accessed with the keywords <code>:TINY</code>, <code>:SMALL</code>, <code>:MEDIUM</code>, <code>:MEDIUM-BOLD</code> (a synonym for <code>:MEDIUM</code>), <code>:LARGE</code>, and <code>:GIANT</code> and used with  <a href="#draw-string"><code>DRAW-STRING</code></a> and <a href="#draw-character"><code>DRAW-CHARACTER</code></a>. Using these fonts will make your application portable to all platforms supported by CL-GD (and thus GD). You can also invoke the <a href="http://www.freetype.org/">FreeType library</a> to draw (anti-aliased) strings with arbitrary TrueType fonts, sizes, and angles. This is, however, subject to the availability and location of the corresponding fonts on your target platform.

<p><br>[Special variable]
<br><a class=none name="default-font"><b>*default-font*</b></a>

<blockquote><br>
Whenever a CL-GD string or character function has an optional or keyword argument called <em>font</em> or <em>font-name</em> the default is to use <code><i>*default-font*</i></code>. See <a href="#with-default-font"><code>WITH-DEFAULT-FONT</code></a> below.
</blockquote>

<p><br>[Macro]
<br><a class=none name="with-default-font"><b>with-default-font</b> <i>(font) form*</i> =&gt; <i>results</i></a>

<blockquote><br>
This is just a convenience macro which will execute <code><i>form*</i></code> with <a href="#default-font"><code>*DEFAULT-FONT*</code></a> bound to <code><i>font</i></code>. But
note that the fonts used for <a href="#draw-string"><code>DRAW-STRING</code></a>/<a href="#draw-character"><code>DRAW-CHARACTER</code></a> and <a href="#draw-freetype-string"><code>DRAW-FREETYPE-STRING</code></a> are incompatible
</blockquote>

<p><br>[Function]
<br><a class=none name="draw-character"><b>draw-character</b> <i>x y char <tt>&amp;key</tt> up font color image</i> =&gt; <i>char</i></a>

<blockquote><br>
Draws the character <code><i>char</i></code> from font <code><i>font</i></code> in color <code><i>color</i></code> at position <code>(<i>x</i>,<i>y</i>)</code>. If
<code><i>up</i></code> is <em>true</em> the character will be drawn from bottom to top (rotated 90&nbsp;degrees). <code><i>font</i></code> must be one of the keywords listed <a href="#strings">above</a>.
</blockquote>

<p><br>[Function]
<br><a class=none name="draw-string"><b>draw-string</b> <i>x y string <tt>&amp;key</tt> up font color image</i> =&gt; <i>string</i></a>

<blockquote><br>
Draws the string <code><i>string</i></code> in color <code><i>color</i></code> at position <code>(<i>y</i>,<i>y</i>)</code>. If
<code><i>up</i></code> is <em>true</em> the string will be drawn from bottom to top (rotated 90&nbsp;degrees). <code><i>font</i></code> must be one of the keywords listed <a href="#strings">above</a>.
</blockquote>

<p><br>[Function]
<br><a class=none name="draw-freetype-string"><b>draw-freetype-string</b> <i>x y string <tt>&amp;key</tt> anti-aliased point-size angle convert-chars line-spacing font-name do-not-draw color image</i> =&gt; <i>bounding-rectangle</i></a>

<blockquote><br>
Draws the string <code><i>string</i></code> in <a href="#colors">color</a> <code><i>color</i></code> at position <code>(<i>x</i>,<i>y</i>)</code> using the
<a href="http://www.freetype.org/">FreeType</a> library. <code><i>font-name</i></code> is the full path (a pathname or a string)
to a TrueType font file, or a font face name if the <code>GDFONTPATH</code>
environment variable or FreeType's <code>DEFAULT_FONTPATH</code> variable have been
set intelligently. The string may be arbitrarily scaled (<code><i>point-size</i></code>)
and rotated (<code><i>angle</i></code> in radians). The direction of rotation is
counter-clockwise, with 0&nbsp;radians (0&nbsp;degrees) at 3&nbsp;o'clock and <code>(/&nbsp;PI&nbsp;2)</code>&nbsp;radians (90&nbsp;degrees) at 12&nbsp;o'clock. Note that the <code><i>angle</i></code> argument is
purposefully <em>not</em> affected by <a href="#with-transformation"><code>WITH-TRANSFORMATION</code></a>. If <code><i>anti-aliased</i></code> if
false, anti-aliasing is disabled. It is enabled by default. To output
multiline text with a specific line spacing, provide a value for
<code><i>line-spacing</i></code>, expressed as a multiple of the font height. The default
is to use 1.05. The string may contain XML character entity references
like &quot;&amp;#192;&quot;. If <code><i>convert-chars</i></code> is <em>true</em> (which is the default)
characters of <code><i>string</i></code> with <code>CHAR-CODE</code> greater than&nbsp;127 are converted
accordingly. This of course pre-supposes that your Lisp's <code>CHAR-CODE</code>
function returns ISO/IEC&nbsp;10646 (Unicode) character codes.
<p>
The return value is an array containing 8&nbsp;elements representing
the 4&nbsp;corner coordinates (lower left, lower right, upper right, upper left) of the bounding rectangle around the
string that was drawn. The points are relative to the text regardless
of the angle, so &quot;upper left&quot; means in the top left-hand
corner seeing the text horizontally. Set <code><i>do-not-draw</i></code>
to <em>true</em> to get the bounding
rectangle without rendering. This is a relatively cheap operation if
followed by a rendering of the same string, because of the caching of
the partial rendering during bounding rectangle calculation.
</blockquote>

<pre>
(<a class=noborder href="#with-image*">with-image*</a> (200 200)<img vspace=0 hspace=0 border=0 alt="strings.png" title="strings.png" src="strings.png" width=200 height=200 align=right>
  <font color=orange>;; set background (white) and make it transparent</font>
  (setf (<a class=noborder href="#transparent-color">transparent-color</a>)
          (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 255))
  (loop for angle from 0 to (* 2 pi) by (/ pi 6)
        for blue downfrom 255 by 20 do
        (<a class=noborder href="#draw-freetype-string">draw-freetype-string</a> 100 100 "Common Lisp"
                              :font-name &quot;/usr/X11R6/lib/X11/fonts/truetype/georgia.ttf&quot;
                              :angle angle
                              <font color=orange>;; note that ALLOCATE-COLOR won't work
                              ;; here because the anti-aliasing uses
                              ;; up too much colors</font>
                              :color (<a class=noborder href="#find-color">find-color</a> 0 0 blue
                                                 :resolve t)))
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> "strings.png"
                       :if-exists :supersede))
</pre>

<br>&nbsp;<br><h3><a href="#contents" class=none name="misc">Miscellaneous</a></h3>

Things that didn't seem to fit into one of the other categories...

<p><br>[Macro]
<br><a class=none name="do-rows"><b>do-rows</b> <i>(y-var <tt>&amp;optional</tt> image) declaration* form*</i> =&gt; <i>results</i></a>

<blockquote><br>
This macro loops through all rows (from top to bottom) in turn and
executes <code><i>form*</i></code> for each row with
<code><i>y-var</i></code> bound to the vertical index of the current row
(starting with <code>0</code>). It is <em>not</em> affected by <a
href="#with-transformation"><code>WITH-TRANSFORMATION</code></a>.
</blockquote>

<p><br>[Local macro]
<br><a class=none name="do-pixels-in-row"><b>do-pixels-in-row</b> <i>(x-var) declaration* form*</i> =&gt; <i>results</i></a>

<blockquote><br>
This macro is only available within the body of a <a
href="#do-rows"><code>DO-ROWS</code></a> form.
It loops through all pixels (from left to right) in turn and
executes <code><i>form*</i></code> for each pixel with
<code><i>x-var</i></code> bound to the horizontal index of the current pixel
(starting with <code>0</code>). It is <em>not</em> affected by <a
href="#with-transformation"><code>WITH-TRANSFORMATION</code></a>.
</blockquote>

<p><br>[Macro]
<br><a class=none name="do-pixels"><b>do-pixels</b> <i>(<tt>&amp;optional</tt> image) declaration* form*</i> =&gt; <i>results</i></a>

<blockquote><br>
This is a shortcut for the previous two macros. It loops through all pixels and executes <code><i>form*</i></code> for each pixel. Obviously it only makes sense when used together with <a
href="#raw-pixel"><code>RAW-PIXEL</code></a>.
</blockquote>

<p><br>[Accessor]
<br><a class=none name="raw-pixel"><b>raw-pixel</b> =&gt; <i>pixel</i>
<br><i>(setf (<b>raw-pixel</b>) pixel)</i></a>

<blockquote><br>
This accessor is only available within the body of a <a
href="#do-pixels-in-row"><code>DO-PIXELS-IN-ROW</code></a> form (and
thus also within <a href="#do-pixels"><code>DO-PIXELS</code></a>
forms). It provides access to the &quot;raw&quot; pixel the loop is
currently at, i.e. for true color images you access an element of the
<code>im-&gt;tpixels</code> array, for palette-based images it's
<code>im-&gt;pixels</code>. Read the <a
href="http://www.boutell.com/gd/manual2.0.15.html">original GD
documentation</a> for details. Make sure you know what you're doing if
you change these values...
</blockquote>

<pre>
* (<a class=noborder href="#with-image*">with-image*</a> (3 3 t) <font color=orange>; true-color image with 3x3 pixels</font>
    (<a class=noborder href="#draw-rectangle*">draw-rectangle*</a> 0 0 2 2 :color (<a class=noborder href="#allocate-color">allocate-color</a> 0 0 0)) <font color=orange>; black background</font>
    (<a class=noborder href="#draw-line">draw-line</a> 0 0 2 2 :color (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 255)) <font color=orange>; white line</font>
    (<a class=noborder href="#do-pixels">do-pixels</a> ()
      <font color=orange>;; loop through all pixels and change those which arent't black</font>
      (unless (zerop (<a class=noborder href="#raw-pixel">raw-pixel</a>))
        (decf (<a class=noborder href="#raw-pixel">raw-pixel</a>) #xff)))
    (<a class=noborder href="#do-rows">do-rows</a> (y)
      <font color=orange>;; loop through all rows</font>
      (format t &quot;Starting with row ~A~%&quot; y)
      (<a class=noborder href="#do-pixels-in-row">do-pixels-in-row</a> (x)
        <font color=orange>;; loop through all pixels in row</font>
        (format t &quot;  Pixel &lt;~A,~A&gt; has value ~X~%&quot; x y (<a class=noborder href="#raw-pixel">raw-pixel</a>)))
      (format t &quot;Done with row ~A~%&quot; y)))
Starting with row 0
  Pixel &lt;0,0&gt; has value FFFF00 <font color=orange>; the line is yellow now</font>
  Pixel &lt;1,0&gt; has value 0
  Pixel &lt;2,0&gt; has value 0
Done with row 0
Starting with row 1
  Pixel &lt;0,1&gt; has value 0
  Pixel &lt;1,1&gt; has value FFFF00
  Pixel &lt;2,1&gt; has value 0
Done with row 1
Starting with row 2
  Pixel &lt;0,2&gt; has value 0
  Pixel &lt;1,2&gt; has value 0
  Pixel &lt;2,2&gt; has value FFFF00
Done with row 2
NIL
</pre>

<p><br>[Accessor]
<br><a class=none name="interlacedp"><b>interlacedp</b> <i><tt>&amp;optional</tt> image</i> =&gt; <i>interlaced</i>
<br><i>(setf (<b>interlacedp</b> <i><tt>&amp;optional</tt> image</i>) interlaced)</i></a>

<blockquote><br>
Gets or sets whether <code><i>image</i></code> will be stored in an interlaced fashion.
</blockquote>

<p><br>[Function]
<br><a class=none name="differentp"><b>differentp</b> <i>image1 image2</i> =&gt; <i>different</i></a>

<blockquote><br>
Returns <em>false</em> if the two images won't appear different when
displayed. Otherwise the return value is a list of keywords describing
the differences between the images.
</blockquote>

<p><br>[Function]
<br><a class=none name="copy-image"><b>copy-image</b> <i>source destination source-x source-y dest-x dest-y width height <tt>&amp;key</tt> resample rotate angle resize dest-width dest-height merge merge-gray</i> =&gt; <i>destination</i></a>

<blockquote><br>
Copies (a part of) the <a href="#images">image</a> <code><i>source</i></code> into the image <code><i>destination</i></code>. Copies the
rectangle with the upper left corner <code>(<i>source-x</i>,<i>source-y</i>)</code> and size
<code><i>width</i></code> <tt>x</tt> <code><i>height</i></code> to the rectangle with the upper left corner <code>(<i>dest-x</i>,<i>dest-y</i>)</code>.

If <code><i>resample</i></code> is <em>true</em> pixel colors will be
smoothly interpolated. If <code><i>resize</i></code> is <em>true</em>
the copied rectangle will be strechted or shrunk so that its size is
<code><i>dest-width</i></code> <tt>x</tt>
<code><i>dest-height</i></code>. If <code><i>rotate</i></code> is true
the image will be rotated by <code><i>angle</i></code>. In this
particular case <code><i>dest-x</i></code> and
<code><i>dest-y</i></code> specify the <em>center</em> of the copied
image rather than its upper left corner! If <code><i>merge</i></code>
is true then it has to be an integer in the range&nbsp;0-100 and the
two images will be 'merged' by the amount specified. If
<code><i>merge</i></code> is 100 then the source image will simply be
copied. If instead <code><i>merge-gray</i></code> is true the hue of
the source image is preserved by converting the destination area to
gray pixels before merging.

The keyword arguments <code><i>resample</i></code>, <code><i>rotate</i></code>, <code><i>resize</i></code>, <code><i>merge</i></code>, and <code><i>merge-gray</i></code>
are mutually exclusive (with the exception of <code><i>resample</i></code> and
<code><i>resize</i></code>). <code><i>angle</i></code> is assumed to be specified in degrees if it's an
integer, and in radians otherwise. This function is not affected by <a href="#with-transformation"><code>WITH-TRANSFORMATION</code></a>.
</blockquote>

<p><br>[Function]
<br><a class=none name="copy-palette"><b>copy-palette</b> <i>source destination </i> =&gt; <i>destination</i></a>

<blockquote><br>
Copies the palette of the <a href="#images">image</a> <code><i>source</i></code> to the image <code><i>destination</i></code> attempting to
match the colors in the target image to the colors in the source palette.
</blockquote>

<p><br>[Function]
<br><a class=none name="true-color-to-palette"><b>true-color-to-palette</b> <i><tt>&amp;key</tt> dither colors-wanted image</i> =&gt; <i>image</i></a>

<blockquote><br>
Converts the true color image <code><i>image</i></code> to a palette-based image using
a high-quality two-pass quantization routine. If <code><i>dither</i></code> is true, the
image will be dithered to approximate colors better, at the expense of
some obvious &quot;speckling.&quot; <code><i>colors-wanted</i></code> can be any positive integer
up to&nbsp;256 (which is the default). If the original source image
includes photographic information or anything that came out of a JPEG,
256&nbsp;is strongly recommended. 100%&nbsp;transparency of a single transparent
color in the original true color image will be preserved. There is no
other support for preservation of alpha channel or transparency in the
destination image.
</blockquote>

<pre>
(<a class=noborder href="#with-image*">with-image*</a> ((+ 256 384) 384 t)
  (let ((white (<a class=noborder href="#allocate-color">allocate-color</a> 255 255 255))
        (red (<a class=noborder href="#allocate-color">allocate-color</a> 255 0 0))
        (green (<a class=noborder href="#allocate-color">allocate-color</a> 0 255 0))
        (blue (<a class=noborder href="#allocate-color">allocate-color</a> 0 0 255))
        (vertices (list 64 0 0 128 128 128))
        (image-width (<a class=noborder href="#image-width">image-width</a>))
        (image-height (<a class=noborder href="#image-height">image-height</a>)))
    (setf (<a class=noborder href="#transparent-color">transparent-color</a>) white)
    (<a class=noborder href="#draw-rectangle*">draw-rectangle*</a> 0 0 image-width image-height :color white)
    <font color=orange>;; &quot;demoin.png&quot; is part of the GD distribution</font>
    (<a class=noborder href="#with-image-from-file">with-image-from-file</a> (in-file &quot;demoin.png&quot;)
      (<a class=noborder href="#copy-image">copy-image</a> in-file *default-image*
                  0 0 32 32 192 192
                  :resize t
                  :dest-width 255
                  :dest-height 255
                  :resample t)
      (multiple-value-bind (in-width in-height)
          (<a class=noborder href="#image-size">image-size</a> in-file)
        (loop for a below 360 by 45 do
              (<a class=noborder href="#copy-image">copy-image</a> in-file *default-image*
                          0 0
                          (+ 256 192 (* 128 (cos (* a .0174532925))))
                          (- 192 (* 128 (sin (* a .0174532925))))
                          in-width in-height
                          :rotate t
                          :angle a))
        (<a class=noborder href="#with-default-color">with-default-color</a> (green)
          (<a class=noborder href="#with-thickness">with-thickness</a> (4)
            (<a class=noborder href="#draw-line">draw-line</a> 16 16 240 16)
            (<a class=noborder href="#draw-line">draw-line</a> 240 16 240 240)
            (<a class=noborder href="#draw-line">draw-line</a> 240 240 16 240)
            (<a class=noborder href="#draw-line">draw-line</a> 16 240 16 16))
          (<a class=noborder href="#draw-polygon">draw-polygon</a> vertices :filled t))
        (dotimes (i 3)
          (incf (nth (* 2 i) vertices) 128))
        (<a class=noborder href="#draw-polygon">draw-polygon</a> vertices
                      :color (<a class=noborder href="#make-anti-aliased">make-anti-aliased</a> green)
                      :filled t)
        (<a class=noborder href="#with-default-color">with-default-color</a> (blue)
          (<a class=noborder href="#draw-arc">draw-arc</a> 128 128 60 20 0 720)
          (<a class=noborder href="#draw-arc">draw-arc</a> 128 128 40 40 90 270)
          (<a class=noborder href="#fill-image">fill-image</a> 8 8))
        (<a class=noborder href="#with-image">with-image</a> (brush 16 16 t)
          (<a class=noborder href="#copy-image">copy-image</a> in-file brush
                      0 0 0 0
                      in-width in-height
                      :resize t
                      :dest-width (<a class=noborder href="#image-width">image-width</a> brush)
                      :dest-height (<a class=noborder href="#image-height">image-height</a> brush))
          (<a class=noborder href="#draw-line">draw-line</a> 0 255 255 0
                     :color (cons (<a class=noborder href="#make-brush">make-brush</a> brush)
                                  (list nil nil nil nil nil nil nil t))))))
    (<a class=noborder href="#with-default-color">with-default-color</a> (red)
      (<a class=noborder href="#draw-string">draw-string</a> 32 32 &quot;hi&quot; :font :giant)
      (<a class=noborder href="#draw-string">draw-string</a> 64 64 &quot;hi&quot; :font :small))
    (<a class=noborder href="#with-clipping-rectangle*">with-clipping-rectangle*</a> (0 (- image-height 100) 100 image-height)
      (<a class=noborder href="#with-default-color">with-default-color</a> ((<a class=noborder href="#make-anti-aliased">make-anti-aliased</a> white))
        (dotimes (i 100)
          (<a class=noborder href="#draw-line">draw-line</a> (random image-width)
                     (random image-height)
                     (random image-width)
                     (random image-height))))))
  (setf (<a class=noborder href="#interlacedp">interlacedp</a>) t)
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;demoout.png&quot;
                       :if-exists :supersede)
  (<a class=noborder href="#true-color-to-palette">true-color-to-palette</a>)
  (<a class=noborder href="#write-image-to-file">write-image-to-file</a> &quot;demooutp.png&quot;
                       :if-exists :supersede))
</pre>

This last example is the demo which comes with GD. The equivalent C code is <a href="gddemo.c">here</a>.

<p>
<img border=0 alt="demooutp.png" title="demooutp.png" src="demooutp.png" width=640 height=384>

<br>&nbsp;<br><h3><a href="#contents" class=none name="ack">Acknowledgements</a></h3>

Thanks to Thomas Boutell for <a
href="http://www.boutell.com/gd/">GD</a> and thanks to Kevin Rosenberg
for <a href="http://uffi.b9.com/">UFFI</a> without which CL-GD would
not have been possible. Kevin was also extremely helpful when I needed
functionality which wasn't yet part of UFFI. Thanks to <a href="http://huebner.org/">Hans
H&uuml;bner</a> for the GIF patches. Thanks to <a href='http://bl0rg.net/'>Manuel Odendahl</a> for lots of useful patches.
Thanks to Luis Oliveira for CLISP/CFFI support and to Bryan O'Connor for OpenMCL support.
<p>
$Header: /usr/local/cvsrep/gd/doc/index.html,v 1.75 2007/07/29 16:37:15 edi Exp $
<p><a href="http://weitz.de/index.html">BACK TO MY HOMEPAGE</a>

</body>
</html>