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