cups/api-raster.shtml

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