hg.stevelosh.com > docs.stevelosh.com

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title> API Reference / cl-netpbm</title>
        <link rel="stylesheet" href="../_dmedia/tango.css"/>
        <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
        <script src="../_dmedia/less.js" type="text/javascript">
        </script>
    </head>
    <body class="content">
        <div class="wrap">
            <header><h1><a href="..">cl-netpbm</a></h1></header>
                <div class="markdown">
<h1 id="api-reference"><a href="">API Reference</a></h1><p>The following is a list of all user-facing parts of cl-netpbm.</p>
<p>If there are backwards-incompatible changes to anything listed here, they will
be noted in the changelog and the author will feel bad.</p>
<p>Anything not listed here is subject to change at any time with no warning, so
don't touch it.</p>
<div class="toc">
<ul>
<li><a href="#package-netpbm">Package NETPBM</a><ul>
<li><a href="#read-from-file-function">READ-FROM-FILE (function)</a></li>
<li><a href="#read-from-stream-function">READ-FROM-STREAM (function)</a></li>
<li><a href="#read-texture-from-file-function">READ-TEXTURE-FROM-FILE (function)</a></li>
<li><a href="#read-texture-from-stream-function">READ-TEXTURE-FROM-STREAM (function)</a></li>
<li><a href="#write-to-file-function">WRITE-TO-FILE (function)</a></li>
<li><a href="#write-to-stream-function">WRITE-TO-STREAM (function)</a></li>
</ul>
</li>
</ul></div>
<h2 id="package-netpbm">Package <code>NETPBM</code></h2>
<h3 id="read-from-file-function"><code>READ-FROM-FILE</code> (function)</h3>
<div class="codehilite"><pre><span/>(READ-FROM-FILE PATH)
</pre></div>


<p>Read a PPM image file from <code>path</code>, returning an array of pixels and more.</p>
<p>The primary return value will be a 2D array with dimensions <code>(width height)</code>.
  Each element of the array will be a single pixel whose type depends on the
  image file format:</p>
<ul>
<li>PBM: <code>bit</code></li>
<li>PGM: <code>(integer 0 maximum-value)</code></li>
<li>PPM: <code>(simple-array (integer 0 maximum-value) (3))</code></li>
</ul>
<p>Two other values are returned:</p>
<ul>
<li>The format of the image that was read (one of <code>:pbm</code>, <code>:pgm</code>, <code>:ppm</code>).</li>
<li>The bit depth of the image.</li>
</ul>
<h3 id="read-from-stream-function"><code>READ-FROM-STREAM</code> (function)</h3>
<div class="codehilite"><pre><span/>(READ-FROM-STREAM STREAM)
</pre></div>


<p>Read a PPM image file from <code>stream</code>, returning an array of pixels and more.</p>
<p><code>stream</code> must be a binary input stream, specifically of <code>(unsigned-byte 8)</code>s
  unless you <em>really</em> know what you're doing.</p>
<p>The primary return value will be a 2D array with dimensions <code>(width height)</code>.
  Each element of the array will be a single pixel whose type depends on the
  image file format:</p>
<ul>
<li>PBM: <code>bit</code></li>
<li>PGM: <code>(integer 0 maximum-value)</code></li>
<li>PPM: <code>(simple-array (integer 0 maximum-value) (3))</code></li>
</ul>
<p>Two other values are returned:</p>
<ul>
<li>The format of the image that was read (one of <code>:pbm</code>, <code>:pgm</code>, <code>:ppm</code>).</li>
<li>The bit depth of the image.</li>
</ul>
<h3 id="read-texture-from-file-function"><code>READ-TEXTURE-FROM-FILE</code> (function)</h3>
<div class="codehilite"><pre><span/>(READ-TEXTURE-FROM-FILE PATH)
</pre></div>


<p>Read a PPM image file from <code>path</code>, returning an OpenGL-style array and more.</p>
<p>The primary return value will be an OpenGL-style array of type:</p>
<div class="codehilite"><pre><span/>(simple-array (single-float 0.0 1.0) (* width height 3))
</pre></div>


<p>The vertical axis of the image will be flipped, which is what OpenGL expects.</p>
<p>Three values are returned: the array, the width, and the height.</p>
<h3 id="read-texture-from-stream-function"><code>READ-TEXTURE-FROM-STREAM</code> (function)</h3>
<div class="codehilite"><pre><span/>(READ-TEXTURE-FROM-STREAM STREAM)
</pre></div>


<p>Read a PPM image file from <code>stream</code>, returning an OpenGL-style array and more.</p>
<p><code>stream</code> must be a binary input stream, specifically of <code>(unsigned-byte 8)</code>s
  unless you <em>really</em> know what you're doing.  The stream must contain a PPM
  formatted image — PBM and PGM images are not supported.</p>
<p>The primary return value will be an OpenGL-style array of type:</p>
<div class="codehilite"><pre><span/>(simple-array (single-float 0.0 1.0) (* width height 3))
</pre></div>


<p>The vertical axis of the image will be flipped, which is what OpenGL expects.</p>
<p>Three values are returned: the array, the width, and the height.</p>
<h3 id="write-to-file-function"><code>WRITE-TO-FILE</code> (function)</h3>
<div class="codehilite"><pre><span/>(WRITE-TO-FILE PATH DATA &amp;KEY (IF-EXISTS NIL IF-EXISTS-GIVEN) (FORMAT :PPM) (ENCODING :BINARY)
               (MAXIMUM-VALUE (ECASE FORMAT (:PBM 1) ((:PGM :PPM) 255))))
</pre></div>


<p>Write a PPM image array <code>data</code> to a file at <code>path</code>.</p>
<p>Nothing is returned.</p>
<p><code>format</code> must be one of <code>:pbm</code>, <code>:pgm</code>, <code>:ppm</code>.</p>
<p><code>encoding</code> must be one of <code>:binary</code>, <code>:ascii</code>.</p>
<p><code>maximum-value</code> must be the desired bit depth of the image (the maximum value
  any particular pixel can have).  For PBM images it must be <code>1</code>.</p>
<p>For PBM and PGM images, <code>data</code> must be a two dimensional array of integers
  between <code>0</code> and <code>maximum-value</code> inclusive.</p>
<p>For PPM images, <code>data</code> must be a two dimensional array of pixels, each of
  which must be a 3 element vector of integers between <code>0</code> and <code>maximum-value</code>
  inclusive.</p>
<h3 id="write-to-stream-function"><code>WRITE-TO-STREAM</code> (function)</h3>
<div class="codehilite"><pre><span/>(WRITE-TO-STREAM STREAM DATA &amp;KEY (FORMAT :PPM) (ENCODING :BINARY)
                 (MAXIMUM-VALUE (ECASE FORMAT (:PBM 1) ((:PGM :PPM) 255))))
</pre></div>


<p>Write a PPM image array <code>data</code> to <code>stream</code>.</p>
<p>Nothing is returned.</p>
<p><code>stream</code> must be a binary output stream, specifically of <code>(unsigned-byte 8)</code>s
  unless you <em>really</em> know what you're doing.</p>
<p><code>format</code> must be one of <code>:pbm</code>, <code>:pgm</code>, <code>:ppm</code>.</p>
<p><code>encoding</code> must be one of <code>:binary</code>, <code>:ascii</code>.</p>
<p><code>maximum-value</code> must be the desired bit depth of the image (the maximum value
  any particular pixel can have).  For PBM images it must be <code>1</code>.</p>
<p>For PBM and PGM images, <code>data</code> must be a two dimensional array of integers
  between <code>0</code> and <code>maximum-value</code> inclusive.</p>
<p>For PPM images, <code>data</code> must be a two dimensional array of pixels, each of
  which must be a 3 element vector of integers between <code>0</code> and <code>maximum-value</code>
  inclusive.</p>
                </div>
            <footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.</p>
<p><br/><a id="rochester-made" href="https://rochestermade.com" title="Rochester Made"><img src="http://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p></footer>
        </div>
    </body>
</html>
author	Steve Losh <steve@stevelosh.com>
date	Mon, 05 Apr 2021 22:00:28 -0400
parents	9e0acccd9256
children	(none)