<!--
"$Id$"
- Raster API introduction for the Common UNIX Printing System (CUPS).
+ Raster API introduction for CUPS.
- Copyright 2007 by Apple Inc.
+ Copyright 2007-2013 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
file is missing or damaged, see the license at "http://www.cups.org/".
-->
-<h2 class='title'>Introduction</h2>
+<h2 class='title'><a name="OVERVIEW">Overview</a></h2>
-<p>The CUPS raster API provides a standard interface for reading
-and writing CUPS raster streams which are used for printing to
-raster printers. Because the raster format is updated from time
-to time, it is important to use this API to avoid
-incompatibilities with newer versions of CUPS.</p>
+<p>The CUPS raster API provides a standard interface for reading and writing
+CUPS raster streams which are used for printing to raster printers. Because the
+raster format is updated from time to time, it is important to use this API to
+avoid incompatibilities with newer versions of CUPS.</p>
-<h2 class='title'>General Usage</h2>
+<p>Two kinds of CUPS filters use the CUPS raster API - raster image processor
+(RIP) filters such as <code>pstoraster</code> and <code>cgpdftoraster</code>
+(OS X) that produce CUPS raster files and printer driver filters that
+convert CUPS raster files into a format usable by the printer. Printer
+driver filters are by far the most common.</p>
-<p>The <var><cups/raster.h></var> header file must be
-included to use the <tt>cupsRaster</tt> functions.</p>
+<p>CUPS raster files (<code>application/vnd.cups-raster</code>) consists of
+a stream of raster page descriptions produced by one of the RIP filters such as
+<var>pstoraster</var>, <var>imagetoraster</var>, or
+<var>cgpdftoraster</var>. CUPS raster files are referred to using the
+<a href='#cups_raster_t'><code>cups_raster_t</code></a> type and are
+opened using the <a href='#cupsRasterOpen'><code>cupsRasterOpen</code></a>
+function. For example, to read raster data from the standard input, open
+file descriptor 0:</p>
-<p>Programs using these functions must be linked to the CUPS
-imaging library: <var>libcupsimage.a</var>,
-<var>libcupsimage.so.2</var>, <var>libcupsimage.2.dylib</var>,
-<var>libcupsimage_s.a</var>, or <var>libcupsimage2.lib</var>
-depending on the platform. The following command compiles
-<var>myprogram.c</var> using GCC and the CUPS imaging
-library:</p>
+<pre class="example">
+#include <cups/raster.h>>
-<pre class='command'>
-<kbd>gcc -o myprogram myprogram.c -lcupsimage</kbd>
+<a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
</pre>
-<h2 class='title'>Compatibility</h2>
+<p>Each page of data begins with a page dictionary structure called
+<a href="#cups_page_header2_t"><code>cups_page_header2_t</code></a>. This
+structure contains the colorspace, bits per color, media size, media type,
+hardware resolution, and so forth used for the page.</p>
-<p>Unless otherwise specified, the raster API functions require
-CUPS 1.1 or higher.</p>
+<blockquote><b>Note:</b>
-<h2 class='title'>Licensing</h2>
+ <p>Do not confuse the colorspace in the page header with the PPD
+ <tt>ColorModel</tt> keyword. <tt>ColorModel</tt> refers to the general type of
+ color used for a device (Gray, RGB, CMYK, DeviceN) and is often used to
+ select a particular colorspace for the page header along with the associate
+ color profile. The page header colorspace (<tt>cupsColorSpace</tt>) describes
+ both the type and organization of the color data, for example KCMY (black
+ first) instead of CMYK and RGBA (RGB + alpha) instead of RGB.</p>
-<p>The CUPS raster API is provided under the terms of the GNU
-Library General Public License, with exceptions for MacOS X-based
-programs. Please see the CUPS license agreement for more
-information.</p>
+</blockquote>
+
+<p>You read the page header using the
+<a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a>
+function:</p>
+
+<pre class="example">
+#include <cups/raster.h>>
+
+<a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
+<a href="#cups_page_header2_t">cups_page_header2_t</a> header;
+
+while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &header))
+{
+ /* setup this page */
+
+ /* read raster data */
+
+ /* finish this page */
+}
+</pre>
+
+<p>After the page dictionary comes the page data which is a full-resolution,
+possibly compressed bitmap representing the page in the printer's output
+colorspace. You read uncompressed raster data using the
+<a href="#cupsRasterReadPixels"><code>cupsRasterReadPixels</code></a>
+function. A <code>for</code> loop is normally used to read the page one line
+at a time:</p>
+
+<pre class="example">
+#include <cups/raster.h>>
+
+<a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ);
+<a href="#cups_page_header2_t">cups_page_header2_t</a> header;
+int page = 0;
+int y;
+char *buffer;
+
+while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &header))
+{
+ /* setup this page */
+ page ++;
+ fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies);
+
+ /* allocate memory for 1 line */
+ buffer = malloc(header.cupsBytesPerLine);
+
+ /* read raster data */
+ for (y = 0; y < header.cupsHeight; y ++)
+ {
+ if (<a href="#cupsRasterReadPixels">cupsRasterReadPixels</a>(ras, buffer, header.cupsBytesPerLine) == 0)
+ break;
+
+ /* write raster data to printer on stdout */
+ }
+
+ /* finish this page */
+}
+</pre>
+
+<p>When you are done reading the raster data, call the
+<a href="#cupsRasterClose"><code>cupsRasterClose</code></a> function to free
+the memory used to read the raster file:</p>
+
+<pre class="example">
+<a href="#cups_raster_t">cups_raster_t</a> *ras;
+
+<a href="#cupsRasterClose">cupsRasterClose</a>(ras);
+</pre>
+
+
+<h2 class='title'><a name="TASKS">Functions by Task</a></h2>
+
+<h3><a name="OPENCLOSE">Opening and Closing Raster Streams</a></h3>
+
+<ul class="code">
+
+ <li><a href="#cupsRasterClose" title="Close a raster stream.">cupsRasterClose</a></li>
+ <li><a href="#cupsRasterOpen" title="Open a raster stream.">cupsRasterOpen</a></li>
+
+</ul>
+
+<h3><a name="READING">Reading Raster Streams</a></h3>
+
+<ul class="code">
+
+ <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/OS X 10.5</span></li>
+ <li><a href="#cupsRasterReadHeader2" title="Read a raster page header and store it in a version 2 page header structure.">cupsRasterReadHeader2</a></li>
+ <li><a href="#cupsRasterReadPixels" title="Read raster pixels.">cupsRasterReadPixels</a></li>
+
+</ul>
+
+<h3><a name="WRITING">Writing Raster Streams</a></h3>
+
+<ul class="code">
+
+ <li><a href="#cupsRasterInterpretPPD" title="Interpret PPD commands to create a page header.">cupsRasterInterpretPPD</a></li>
+ <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/OS X 10.5</span></li>
+ <li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a version 2 page header structure.">cupsRasterWriteHeader2</a></li>
+ <li><a href="#cupsRasterWritePixels" title="Write raster pixels.">cupsRasterWritePixels</a></li>
+
+</ul>
projects / thirdparty / cups.git / blobdiff