]>
Commit | Line | Data |
---|---|---|
b423cd4c | 1 | <!-- |
f7faf1f5 | 2 | "$Id$" |
b423cd4c | 3 | |
4 | Raster API introduction for the Common UNIX Printing System (CUPS). | |
5 | ||
5a738aea | 6 | Copyright 2007-2008 by Apple Inc. |
bc44d920 | 7 | Copyright 1997-2006 by Easy Software Products, all rights reserved. |
b423cd4c | 8 | |
9 | These coded instructions, statements, and computer programs are the | |
bc44d920 | 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/". | |
b423cd4c | 14 | --> |
15 | ||
5a738aea | 16 | <h2 class='title'><a name="OVERVIEW">Overview</a></h2> |
b423cd4c | 17 | |
5a738aea MS |
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> | |
b423cd4c | 22 | |
5a738aea MS |
23 | <p>CUPS raster files (<code>application/vnd.cups-raster</code>) consists of |
24 | a stream of raster page descriptions produced by one of the RIP filters such as | |
25 | <var>pstoraster</var>, <var>imagetoraster</var>, or | |
26 | <var>cgpdftoraster</var>. CUPS raster files are referred to using the | |
27 | <a href='#cups_raster_t'><code>cups_raster_t</code></a> type and are | |
28 | opened using the <a href='#cupsRasterOpen'><code>cupsRasterOpen</code></a> | |
29 | function. For example, to read raster data from the standard input, open | |
30 | file descriptor 0:</p> | |
b423cd4c | 31 | |
5a738aea MS |
32 | <pre class="example"> |
33 | #include <cups/raster.h>> | |
b423cd4c | 34 | |
5a738aea MS |
35 | <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ); |
36 | </pre> | |
37 | ||
38 | <p>Each page of data begins with a page dictionary structure called | |
39 | <a href="#cups_page_header2_t"><code>cups_page_header2_t</code></a>. This | |
40 | structure contains the colorspace, bits per color, media size, media type, | |
41 | hardware resolution, and so forth used for the page. You read the page header | |
42 | using the | |
43 | <a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a> | |
44 | function:</p> | |
45 | ||
46 | <pre class="example"> | |
47 | #include <cups/raster.h>> | |
48 | ||
49 | <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ); | |
50 | <a href="#cups_page_header2_t">cups_page_header2_t</a> header; | |
b423cd4c | 51 | |
5a738aea MS |
52 | while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &header)) |
53 | { | |
54 | /* setup this page */ | |
55 | ||
56 | /* read raster data */ | |
57 | ||
58 | /* finish this page */ | |
59 | } | |
b423cd4c | 60 | </pre> |
61 | ||
5a738aea MS |
62 | <p>After the page dictionary comes the page data which is a full-resolution, |
63 | possibly compressed bitmap representing the page in the printer's output | |
64 | colorspace. You read uncompressed raster data using the | |
65 | <a href="#cupsRasterReadPixels"><code>cupsRasterReadPixels</code></a> | |
66 | function. A <code>for</code> loop is normally used to read the page one line | |
67 | at a time:</p> | |
68 | ||
69 | <pre class="example"> | |
70 | #include <cups/raster.h>> | |
71 | ||
72 | <a href="#cups_raster_t">cups_raster_t</a> *ras = <a href="#cupsRasterOpen">cupsRasterOpen</a>(0, CUPS_RASTER_READ); | |
73 | <a href="#cups_page_header2_t">cups_page_header2_t</a> header; | |
74 | int page = 0; | |
75 | int y; | |
76 | char *buffer; | |
b423cd4c | 77 | |
5a738aea MS |
78 | while (<a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a>(ras, &header)) |
79 | { | |
80 | /* setup this page */ | |
81 | page ++; | |
82 | fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies); | |
b423cd4c | 83 | |
5a738aea MS |
84 | /* allocate memory for 1 line */ |
85 | buffer = malloc(header.cupsBytesPerLine); | |
b423cd4c | 86 | |
5a738aea MS |
87 | /* read raster data */ |
88 | for (y = 0; y < header.cupsHeight; y ++) | |
89 | { | |
90 | if (<a href="#cupsRasterReadPixels">cupsRasterReadPixels</a>(ras, buffer, header.cupsBytesPerLine) == 0) | |
91 | break; | |
92 | ||
93 | /* write raster data to printer */ | |
94 | } | |
95 | ||
96 | /* finish this page */ | |
97 | } | |
98 | </pre> | |
99 | ||
100 | <p>When you are done reading the raster data, call the | |
101 | <a href="#cupsRasterClose"><code>cupsRasterClose</code></a> function to free | |
102 | the memory used to read the raster file:</p> | |
103 | ||
104 | <pre class="example"> | |
105 | <a href="#cups_raster_t">cups_raster_t</a> *ras; | |
106 | ||
107 | <a href="#cupsRasterClose">cupsRasterClose</a>(ras); | |
108 | </pre> |