Home | History | Annotate | Download | only in filter
      1 <!--
      2   Raster API introduction for CUPS.
      3 
      4   Copyright 2007-2013 by Apple Inc.
      5   Copyright 1997-2006 by Easy Software Products, all rights reserved.
      6 
      7   These coded instructions, statements, and computer programs are the
      8   property of Apple Inc. and are protected by Federal copyright
      9   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
     10   which should have been included with this file.  If this file is
     11   file is missing or damaged, see the license at "http://www.cups.org/".
     12 -->
     13 
     14 <h2 class='title'><a name="OVERVIEW">Overview</a></h2>
     15 
     16 <p>The CUPS raster API provides a standard interface for reading and writing
     17 CUPS raster streams which are used for printing to raster printers. Because the
     18 raster format is updated from time to time, it is important to use this API to
     19 avoid incompatibilities with newer versions of CUPS.</p>
     20 
     21 <p>Two kinds of CUPS filters use the CUPS raster API - raster image processor
     22 (RIP) filters such as <code>pstoraster</code> and <code>cgpdftoraster</code>
     23 (macOS) that produce CUPS raster files and printer driver filters that
     24 convert CUPS raster files into a format usable by the printer. Printer
     25 driver filters are by far the most common.</p>
     26 
     27 <p>CUPS raster files (<code>application/vnd.cups-raster</code>) consists of
     28 a stream of raster page descriptions produced by one of the RIP filters such as
     29 <var>pstoraster</var>, <var>imagetoraster</var>, or
     30 <var>cgpdftoraster</var>. CUPS raster files are referred to using the
     31 <a href='#cups_raster_t'><code>cups_raster_t</code></a> type and are
     32 opened using the <a href='#cupsRasterOpen'><code>cupsRasterOpen</code></a>
     33 function. For example, to read raster data from the standard input, open
     34 file descriptor 0:</p>
     35 
     36 <pre class="example">
     37 #include &lt;cups/raster.h&gt;
     38 
     39 <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
     40 </pre>
     41 
     42 <p>Each page of data begins with a page dictionary structure called
     43 <a href="#cups_page_header2_t"><code>cups_page_header2_t</code></a>. This
     44 structure contains the colorspace, bits per color, media size, media type,
     45 hardware resolution, and so forth used for the page.</p>
     46 
     47 <blockquote><b>Note:</b>
     48 
     49   <p>Do not confuse the colorspace in the page header with the PPD
     50   <tt>ColorModel</tt> keyword. <tt>ColorModel</tt> refers to the general type of
     51   color used for a device (Gray, RGB, CMYK, DeviceN) and is often used to
     52   select a particular colorspace for the page header along with the associate
     53   color profile. The page header colorspace (<tt>cupsColorSpace</tt>) describes
     54   both the type and organization of the color data, for example KCMY (black
     55   first) instead of CMYK and RGBA (RGB + alpha) instead of RGB.</p>
     56 
     57 </blockquote>
     58 
     59 <p>You read the page header using the
     60 <a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a>
     61 function:</p>
     62 
     63 <pre class="example">
     64 #include &lt;cups/raster.h&gt;
     65 
     66 <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
     67 <a href="#cups_page_header2_t">cups_page_header2_t</a> header;
     68 
     69 while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &amp;header))
     70 {
     71   /* setup this page */
     72 
     73   /* read raster data */
     74 
     75   /* finish this page */
     76 }
     77 </pre>
     78 
     79 <p>After the page dictionary comes the page data which is a full-resolution,
     80 possibly compressed bitmap representing the page in the printer's output
     81 colorspace. You read uncompressed raster data using the
     82 <a href="#cupsRasterReadPixels"><code>cupsRasterReadPixels</code></a>
     83 function. A <code>for</code> loop is normally used to read the page one line
     84 at a time:</p>
     85 
     86 <pre class="example">
     87 #include &lt;cups/raster.h&gt;
     88 
     89 <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
     90 <a href="#cups_page_header2_t">cups_page_header2_t</a> header;
     91 int page = 0;
     92 int y;
     93 char *buffer;
     94 
     95 while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &amp;header))
     96 {
     97   /* setup this page */
     98   page ++;
     99   fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies);
    100 
    101   /* allocate memory for 1 line */
    102   buffer = malloc(header.cupsBytesPerLine);
    103 
    104   /* read raster data */
    105   for (y = 0; y &lt; header.cupsHeight; y ++)
    106   {
    107     if (<a href="#cupsRasterReadPixels">cupsRasterReadPixels</a>(ras, buffer, header.cupsBytesPerLine) == 0)
    108       break;
    109 
    110     /* write raster data to printer on stdout */
    111   }
    112 
    113   /* finish this page */
    114 }
    115 </pre>
    116 
    117 <p>When you are done reading the raster data, call the
    118 <a href="#cupsRasterClose"><code>cupsRasterClose</code></a> function to free
    119 the memory used to read the raster file:</p>
    120 
    121 <pre class="example">
    122 <a href="#cups_raster_t">cups_raster_t</a> *ras;
    123 
    124 <a href="#cupsRasterClose">cupsRasterClose</a>(ras);
    125 </pre>
    126 
    127 
    128 <h2 class='title'><a name="TASKS">Functions by Task</a></h2>
    129 
    130 <h3><a name="OPENCLOSE">Opening and Closing Raster Streams</a></h3>
    131 
    132 <ul class="code">
    133 
    134 	<li><a href="#cupsRasterClose" title="Close a raster stream.">cupsRasterClose</a></li>
    135 	<li><a href="#cupsRasterOpen" title="Open a raster stream.">cupsRasterOpen</a></li>
    136 
    137 </ul>
    138 
    139 <h3><a name="READING">Reading Raster Streams</a></h3>
    140 
    141 <ul class="code">
    142 
    143 	<li><a href="#cupsRasterReadHeader" title="Read a raster page header and store it in a version 1 page header structure.">cupsRasterReadHeader</a> <span class="info">Deprecated in CUPS 1.2/macOS 10.5</span></li>
    144 	<li><a href="#cupsRasterReadHeader2" title="Read a raster page header and store it in a version 2 page header structure.">cupsRasterReadHeader2</a></li>
    145 	<li><a href="#cupsRasterReadPixels" title="Read raster pixels.">cupsRasterReadPixels</a></li>
    146 
    147 </ul>
    148 
    149 <h3><a name="WRITING">Writing Raster Streams</a></h3>
    150 
    151 <ul class="code">
    152 
    153 	<li><a href="#cupsRasterInterpretPPD" title="Interpret PPD commands to create a page header.">cupsRasterInterpretPPD</a></li>
    154 	<li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a version 1 page header structure.">cupsRasterWriteHeader</a> <span class="info">Deprecated in CUPS 1.2/macOS 10.5</span></li>
    155 	<li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a version 2 page header structure.">cupsRasterWriteHeader2</a></li>
    156 	<li><a href="#cupsRasterWritePixels" title="Write raster pixels.">cupsRasterWritePixels</a></li>
    157 
    158 </ul>
    159