filter/api-raster.shtml

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