4 Raster API introduction for the Common UNIX Printing System (CUPS).
6 Copyright 2007-2008 by Apple Inc.
7 Copyright 1997-2006 by Easy Software Products, all rights reserved.
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/".
16 <h2 class='title'><a name="OVERVIEW">Overview</a></h2>
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>
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>
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>
39 #include <cups/raster.h>>
41 <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
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>
49 <blockquote><b>Note:</b>
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>
61 <p>You read the page header using the
62 <a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a>
66 #include <cups/raster.h>>
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;
71 while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &header))
75 /* read raster data */
77 /* finish this page */
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
89 #include <cups/raster.h>>
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;
97 while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &header))
101 fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies);
103 /* allocate memory for 1 line */
104 buffer = malloc(header.cupsBytesPerLine);
106 /* read raster data */
107 for (y = 0; y < header.cupsHeight; y ++)
109 if (<a href="#cupsRasterReadPixels">cupsRasterReadPixels</a>(ras, buffer, header.cupsBytesPerLine) == 0)
112 /* write raster data to printer on stdout */
115 /* finish this page */
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>
123 <pre class="example">
124 <a href="#cups_raster_t">cups_raster_t</a> *ras;
126 <a href="#cupsRasterClose">cupsRasterClose</a>(ras);
130 <h2 class='title'><a name="TASKS">Functions by Task</a></h2>
132 <h3><a name="OPENCLOSE">Opening and Closing Raster Streams</a></h3>
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>
141 <h3><a name="READING">Reading Raster Streams</a></h3>
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>
151 <h3><a name="WRITING">Writing Raster Streams</a></h3>
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> <span class="info">Deprecated in CUPS 1.2/Mac OS X 10.5</span></li>
157 <li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a version 2 page header structure.">cupsRasterWriteHeader2</a></li>
158 <li><a href="#cupsRasterWritePixels" title="Write raster pixels.">cupsRasterWritePixels</a></li>