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>CUPS raster files (<code>application/vnd.cups-raster</code>) consists of
  24 a stream of raster page descriptions produced by one of the RIP filters such as
  25 <var>pstoraster</var>, <var>imagetoraster</var>, or
  26 <var>cgpdftoraster</var>. CUPS raster files are referred to using the
  27 <a href='#cups_raster_t'><code>cups_raster_t</code></a> type and are
  28 opened using the <a href='#cupsRasterOpen'><code>cupsRasterOpen</code></a>
  29 function. For example, to read raster data from the standard input, open
  30 file descriptor 0:</p>
  31
  32 <pre class="example">
  33 #include &lt;cups/raster.h&gt;>
  34
  35 <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
  36 </pre>
  37
  38 <p>Each page of data begins with a page dictionary structure called
  39 <a href="#cups_page_header2_t"><code>cups_page_header2_t</code></a>. This
  40 structure contains the colorspace, bits per color, media size, media type,
  41 hardware resolution, and so forth used for the page. You read the page header
  42 using the
  43 <a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a>
  44 function:</p>
  45
  46 <pre class="example">
  47 #include &lt;cups/raster.h&gt;>
  48
  49 <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
  50 <a href="#cups_page_header2_t">cups_page_header2_t</a> header;
  51
  52 while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &amp;header))
  53 {
  54   /* setup this page */
  55
  56   /* read raster data */
  57
  58   /* finish this page */
  59 }
  60 </pre>
  61
  62 <p>After the page dictionary comes the page data which is a full-resolution,
  63 possibly compressed bitmap representing the page in the printer's output
  64 colorspace. You read uncompressed raster data using the
  65 <a href="#cupsRasterReadPixels"><code>cupsRasterReadPixels</code></a>
  66 function. A <code>for</code> loop is normally used to read the page one line
  67 at a time:</p>
  68
  69 <pre class="example">
  70 #include &lt;cups/raster.h&gt;>
  71
  72 <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
  73 <a href="#cups_page_header2_t">cups_page_header2_t</a> header;
  74 int page = 0;
  75 int y;
  76 char *buffer;
  77
  78 while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &amp;header))
  79 {
  80   /* setup this page */
  81   page ++;
  82   fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies);
  83
  84   /* allocate memory for 1 line */
  85   buffer = malloc(header.cupsBytesPerLine);
  86
  87   /* read raster data */
  88   for (y = 0; y &lt; header.cupsHeight; y ++)
  89   {
  90     if (<a href="#cupsRasterReadPixels">cupsRasterReadPixels</a>(ras, buffer, header.cupsBytesPerLine) == 0)
  91       break;
  92
  93     /* write raster data to printer */
  94   }
  95
  96   /* finish this page */
  97 }
  98 </pre>
  99
 100 <p>When you are done reading the raster data, call the
 101 <a href="#cupsRasterClose"><code>cupsRasterClose</code></a> function to free
 102 the memory used to read the raster file:</p>
 103
 104 <pre class="example">
 105 <a href="#cups_raster_t">cups_raster_t</a> *ras;
 106
 107 <a href="#cupsRasterClose">cupsRasterClose</a>(ras);
 108 </pre>