PageRenderTime 50ms CodeModel.GetById 21ms RepoModel.GetById 1ms app.codeStats 0ms

/site/zpng-1.0.1/doc/index.html

https://github.com/vikram/lisplibraries
HTML | 266 lines | 201 code | 65 blank | 0 comment | 0 complexity | a16a067285aea171aef0065c072c8506 MD5 | raw file
Possible License(s): LGPL-2.0, LGPL-2.1, CC-BY-SA-3.0, LGPL-3.0, BSD-3-Clause, GPL-2.0 
    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <title>ZPNG - Create PNG files from Common Lisp</title>
    4. 

  4. <style type="text/css">
    5. 

  5.   a, a:visited { text-decoration: none }
    6. 

  6.   a[href]:hover { text-decoration: underline }
    7. 

  7.   pre { background: #DDD; padding: 0.25em }
    8. 

  8.   p.download { color: red }
    9. 

  9.   .transparent { background-image: url(background.gif) }
    10. 

  10. </style>
    11. 

  11. </head>
    12. 

  12. 

  13. <body>
    14. 

  14. 

  15. <h2>ZPNG - Create PNG files from Common Lisp</h2>
    16. 

  16. 

  17. <blockquote class='abstract'>
    18. 

  18. <h3>Abstract</h3>
    19. 

  19. 

  20. <p>ZPNG is a Common Lisp library for creating PNG files. It
    21. 

  21. uses <a href='http://www.xach.com/lisp/salza2/'>Salza2</a> for
    22. 

  22. compression.  
    23. 

  23. 

  24. The current version is 1.0.1, released on January 3rd, 2008.
    25. 

  25. 

  26. <p class='download'>Download shortcut:
    27. 

  27. 

  28. <p><a href='http://www.xach.com/lisp/zpng.tgz'>http://www.xach.com/lisp/zpng.tgz</a>
    29. 

  29. 

  30. </blockquote>
    31. 

  31. 

  32. <h3>Contents</h3>
    33. 

  33. 

  34. <ol>
    35. 

  35. <li> <a href='#sect-overview'>Overview and Limitations</a>
    36. 

  36. <li> <a href='#sect-examples'>Examples</a>
    37. 

  37. <li> <a href='#sect-dictionary'>Dictionary</a>
    38. 

  38. 

  39. <ul>
    40. 

  40. <li> <a href='#png'><tt>png</tt></a>
    41. 

  41. <li> <a href='#samples-per-pixel'><tt>samples-per-pixel</tt></a>
    42. 

  42. <li> <a href='#image-data'><tt>image-data</tt></a>
    43. 

  43. <li> <a href='#data-array'><tt>data-array</tt></a>
    44. 

  44. <li> <a href='#width'><tt>width</tt></a>
    45. 

  45. <li> <a href='#height'><tt>height</tt></a>
    46. 

  46. <li> <a href='#color-type'><tt>color-type</tt></a>
    47. 

  47. <li> <a href='#write-png'><tt>write-png</tt></a>
    48. 

  48. <ul> <a href='#write-png-stream'><tt>write-png-stream</tt></a>
    49. 

  49. </ul>
    50. 

  50. 

  51. <li> <a href='#sect-references'>References</a>
    52. 

  52. <li> <a href='#sect-feedback'>Feedback</a>
    53. 

  53. </ol>
    54. 

  54. 

  55. <a name='sect-overview'><h3>Overview and Limitations</h3></a>
    56. 

  56. 

  57. <p>ZPNG provides an interface for creating
    58. 

  58. a <a href='#png'><tt>PNG</tt></a> object. The objects acts as a
    59. 

  59. container for PNG sample data, which may be updated and saved to a
    60. 

  60. file.
    61. 

  61. 

  62. <p>The PNG file format has many options, and ZPNG supports only a
    63. 

  63. subset of them.
    64. 

  64. 

  65. <ul>
    66. 

  66. <li> does not load PNG files
    67. 

  67. <li> supports only 8 bits per sample
    68. 

  68. <li> does not support filtering
    69. 

  69. <li> does not support indexed color
    70. 

  70. </ul>
    71. 

  71. 

  72. 

  73. <a name='sect-examples'><h3>Examples</h3></a>
    74. 

  74. 

  75. 

  76. <pre><div style='float: right' class='transparent'><img src='mandelbrot.png'
    77. 

  77. ></div>(defun draw-mandelbrot (file)
    78. 

  78.   (let* ((png (make-instance '<a href='#png'>png</a>
    79. 

  79.                              :color-type :grayscale-alpha
    80. 

  80.                              :width 200
    81. 

  81.                              :height 200))
    82. 

  82.          (image (<a href='#data-array'>data-array</a> png))
    83. 

  83.          (max 255))
    84. 

  84.     (dotimes (y 200 (<a href='#write-png'>write-png</a> png file))
    85. 

  85.       (dotimes (x 200)
    86. 

  86.         (let ((c (complex (- (/ x 100.0) 1.5) (- (/ y 100.0) 1.0)))
    87. 

  87.               (z (complex 0.0 0.0))
    88. 

  88.               (iteration 0))
    89. 

  89.           (loop
    90. 

  90.            (setf z (+ (* z z) c))
    91. 

  91.            (incf iteration)
    92. 

  92.            (cond ((< 4 (abs z))
    93. 

  93.                   (setf (aref image y x 1) iteration)
    94. 

  94.                   (return))
    95. 

  95.                  ((= iteration max)
    96. 

  96.                   (setf (aref image y x 1) 255)
    97. 

  97.                   (return)))))))))
    98. 

  98. </pre>
    99. 

  99. 

  100. <a name='sect-dictionary'><h3>Dictionary</h3></a>
    101. 

  101. 

  102. <p>The following symbols are exported from the ZPNG package.
    103. 

  103. 

  104. 

  105. <p><a name='png'>[Class]</a><br>
    106. 

  106. <b>png</b>
    107. 

  107. 

  108. <blockquote>
    109. 

  109. Instances of this class may be created directly. Supported initargs:
    110. 

  110. 

  111. <ul>
    112. 

  112. 

  113. <li> <tt>:width</tt> - required, the width of the image
    114. 

  114. 

  115. <li> <tt>:height</tt> - required, the height of the image
    116. 

  116. 

  117. <li> <tt>:color-type</tt> - optional, the color type of the image, one
    118. 

  118. of <tt>:grayscale</tt>, <tt>:truecolor</tt> (the
    119. 

  119.   default), <tt>:grayscale-alpha</tt>, or <tt>:truecolor-alpha</tt>
    120. 

  120. 

  121. <li> <tt>:image-data</tt> - optional, the sample data of the image. If
    122. 

  122. specified, this must be an octet vector with a length of 
    123. 

  123. <i>width</i>&nbsp;&times;&nbsp;<i>height</i>&nbsp;&times;&nbsp;<i>samples-per-pixel</i>. If
    124. 

  124. not specified, an image data vector of the appropriate size will be
    125. 

  125. created automatically.
    126. 

  126. 

  127. </ul>
    128. 

  128. 

  129. </blockquote>
    130. 

  130. 

  131. <p><a name='samples-per-pixel'>[Function]</a><br>
    132. 

  132. <b>samples-per-pixel</b> <i>png</i> => <i>samples</i>
    133. 

  133. 

  134. <blockquote>
    135. 

  135. Returns the number of octet samples that make up a single pixel. 
    136. 

  136. 

  137. <p><table cellpadding=0 cellspacing=5>
    138. 

  138. <tr>
    139. 

  139.   <th>Image Color Type</th> 
    140. 

  140.   <th>Samples per Pixel</th>
    141. 

  141. </tr>
    142. 

  142. <tr>
    143. 

  143.  <td>Grayscale</td><td align=center>1</td>
    144. 

  144. </tr>
    145. 

  145. <tr>
    146. 

  146.  <td>Truecolor</td><td align=center>3</td>
    147. 

  147. </tr> 
    148. 

  148. <tr>
    149. 

  149.  <td>Grayscale with Alpha</td><td align=center>2</td>
    150. 

  150. </tr>
    151. 

  151. <tr>
    152. 

  152.  <td>Truecolor with Alpha</td><td align=center>4</td>
    153. 

  153. </tr>
    154. 

  154. </table>
    155. 

  155. 

  156. </blockquote>
    157. 

  157. 

  158. 

  159. <p><a name='image-data'>[Function]</a><br>
    160. 

  160. <b>image-data</b> <i>png</i> => <i>octet-vector</i>
    161. 

  161. 

  162. <blockquote>
    163. 

  163. Returns the image data of png. Samples are laid out from left to
    164. 

  164. right, top to bottom, so the first samples of data affect the
    165. 

  165. upper-left of the image and the final samples affect the lower-right.
    166. 

  166. 

  167. <p><table cellpadding=0 cellspacing=5>
    168. 

  168. <tr>
    169. 

  169.   <th>Image Color Type</th> 
    170. 

  170.   <th>Pixel Sample Layout</th>
    171. 

  171. </tr>
    172. 

  172. <tr>
    173. 

  173.  <td>Grayscale</td><td>S|S|S...</td>
    174. 

  174. </tr>
    175. 

  175. <tr>
    176. 

  176.  <td>Truecolor</td><td>RGB|RGB|RGB...</td>
    177. 

  177. </tr> 
    178. 

  178. <tr>
    179. 

  179.  <td>Grayscale with Alpha</td><td>SA|SA|SA...</td>
    180. 

  180. </tr>
    181. 

  181. <tr>
    182. 

  182.  <td>Truecolor with Alpha</td><td>RGBA|RGBA|RGBA...</td>
    183. 

  183. </tr>
    184. 

  184. </table>
    185. 

  185. 

  186. <p>Layout of the samples into pixels is done according to the image's
    187. 

  187. color type and is fully documented in
    188. 

  188. the <a href="http://www.w3.org/TR/PNG/">Portable Network Graphics
    189. 

  189. Specification.
    190. 

  190. </blockquote>
    191. 

  191. 

  192. <p><a name='data-array'>[Function]</a><br>
    193. 

  193. <b>data-array</b> <i>png</i> => <i>data-array</i>
    194. 

  194. 

  195. <blockquote>
    196. 

  196. Returns a multidimensional array representing the pixels
    197. 

  197. of <i>png</i>. The dimensions correspond to the height, width, and
    198. 

  198. pixel components, respectively. For example, to access the red
    199. 

  199. component at &lt;53,100&gt; of a truecolor PNG, you could use this:
    200. 

  200. 

  201. <pre>
    202. 

  202. (aref (data-array png) 100 53 0)
    203. 

  203. </pre>
    204. 

  204. 

  205. <p>Note the reversed order of the coordinate arguments; this is a
    206. 

  206. consequence of Common Lisp's row-major ordering of elements in a
    207. 

  207. multidimensional array and PNG's specified sample layout.
    208. 

    209. 

  209. </blockquote>
    210. 

  210. 

  211. <p><a name='width'><a name='height'>[Functions]</a></a><br>
    212. 

  212. <b>width</b> <i>png</i> => <i>width</i><br>
    213. 

  213. <b>height</b> <i>png</i> => <i>height</i>
    214. 

  214. 

  215. <blockquote>
    216. 

  216. Returns the width or height of <i>png</i>.
    217. 

  217. </blockquote>
    218. 

  218. 

  219. <p><a name='color-type'>[Function]</a><br>
    220. 

  220. <b>color-type</b> <i>png</i> => <i>color-type</i>
    221. 

  221. 

  222. <blockquote>
    223. 

  223. Returns the color type of <i>png</i>, one of
    224. 

  224. of <tt>:grayscale</tt>, <tt>:truecolor</tt>,
    225. 

  225. <tt>:grayscale-alpha</tt>, or <tt>:truecolor-alpha</tt>.
    226. 

  226. </blockquote>
    227. 

  227. 

  228. 

  229. <p><a name='write-png'>[Function]</a><br>
    230. 

  230. <b>write-png</b> <i>png</i> <i>file</i> 
    231. 

  231. <tt>&amp;key</tt> (<i>if-exists</i> <tt>:supersede</tt>)  => pathname
    232. 

  232. 

  233. <blockquote>
    234. 

  234. Writes <i>png</i> to <i>file</i> and returns the truename
    235. 

  235. of <i>file</i>. <i>if-exists</i> is passed to the
    236. 

  236. underlying <tt>OPEN</tt> call for opening the output file.
    237. 

  237. </blockquote>
    238. 

  238. 

  239. 

  240. <p><a name='write-png-stream'>[Function]</a><br>
    241. 

  241. <b>write-png-stream</b> <i>png</i> <i>stream</i> => |
    242. 

  242. 

  243. <blockquote>
    244. 

  244. Writes <i>png</i> to <i>stream</i>, which should be a stream that can
    245. 

  245. accept octets.
    246. 

  246. </blockquote>
    247. 

  247. 

  248. 

  249. <a name='sect-references'><h3>References</h3></a>
    250. 

  250. 

  251. <ul>
    252. 

  252. 

  253. <li> W3C, <a href="http://www.w3.org/TR/PNG/">Portable Network
    254. 

  254. Graphics Specification, Second Edition</a>
    255. 

  255. 

  256. <li>
    257. 

  257. Wikipedia, <a href='http://en.wikipedia.org/wiki/Mandelbrot_set'>Mandelbrot
    258. 

  258. set</a>
    259. 

  259. 

  260. </ul>
    261. 

  261. 

  262. 

  263. <a name='sect-feedback'><h3>Feedback</h3></a>
    264. 

  264. 

  265. <p>Please direct any questions, comments, bug reports, or other
    266. 

  266. feedback to <a href='mailto:xach@xach.com'>Zach Beane</a>.
    267. 

  267.