diff options
author | Michael R Sweet <michaelrsweet@gmail.com> | 2018-01-18 17:20:18 -0500 |
---|---|---|
committer | Michael R Sweet <michaelrsweet@gmail.com> | 2018-01-18 17:20:18 -0500 |
commit | 123979a9db0cec406d710e3b89f351f2e98cb686 (patch) | |
tree | 7e286a192a915b863f2122244393b58be8a6e160 /cups/api-raster.shtml | |
parent | 342395f9d1b6146b5c82132b18ee0cc6cd294f8c (diff) | |
download | cups-123979a9db0cec406d710e3b89f351f2e98cb686.tar.gz |
Move libcupsimage to the "cups" subdirectory, along with its unit tests and
benchmark.
Diffstat (limited to 'cups/api-raster.shtml')
-rw-r--r-- | cups/api-raster.shtml | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/cups/api-raster.shtml b/cups/api-raster.shtml new file mode 100644 index 000000000..6d458a2ed --- /dev/null +++ b/cups/api-raster.shtml @@ -0,0 +1,158 @@ +<!-- + Raster API introduction for CUPS. + + 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 + property of Apple Inc. and are protected by Federal copyright + law. Distribution and use rights are outlined in the file "LICENSE.txt" + which should have been included with this file. If this file is + file is missing or damaged, see the license at "http://www.cups.org/". +--> + +<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>Two kinds of CUPS filters use the CUPS raster API - raster image processor +(RIP) filters such as <code>pstoraster</code> and <code>cgpdftoraster</code> +(macOS) 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>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> + +<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); +</pre> + +<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> + +<blockquote><b>Note:</b> + + <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> + +</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/macOS 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/macOS 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> |