/
api-raster.shtml
155 lines (112 loc) · 5.91 KB
/
api-raster.shtml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
<!--
Raster API introduction for CUPS.
Copyright © 2007-2019 by Apple Inc.
Copyright © 1997-2006 by Easy Software Products, all rights reserved.
Licensed under Apache License v2.0. See the file "LICENSE" for more
information.
-->
<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="#cupsRasterInitPWGHeader" title="Interpret IPP attributes to create a page header.">cupsRasterInitPWGHeader</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>