]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/help/spec-raster.html
projects / thirdparty / cups.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge changes from CUPS 1.5svn-r9641
[thirdparty/cups.git] / doc / help / spec-raster.html
CommitLineData
745129be 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
4744bd90 2<HTML>
3<!-- SECTION: Specifications -->
4<HEAD>
5 <TITLE>CUPS Raster Format</TITLE>
178cb736 6 <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
4744bd90 7</HEAD>
8<BODY>
9
178cb736
MS		 10<H1 CLASS="title">CUPS Raster Format</H1>
11
0268488e 12<P>CUPS Raster files are device-dependent raster image files that contain a PostScript page device dictionary and device-dependent raster imagery for each page in the document. These files are used to transfer raster data from the PostScript and image file RIPs to device-dependent filters that convert the raster data to a printable format.</P>
4744bd90 13
0268488e 14<P>CUPS 1.0 and 1.1 used version 1 of the raster format. CUPS 1.2 and later use version 2 (compressed) and version 3 (uncompressed) that are a superset of the version 1 raster format. All three versions of CUPS Raster are streamable formats, and applications using the CUPS Imaging API (the cupsRaster* functions) can read all formats without code changes.</P>
4744bd90 15
0268488e
MS		 16<P>The registered MIME media type for CUPS Raster files is <CODE>application/vnd.cups-raster</CODE>.</P>
17
18
19<H2 CLASS="title"><A NAME="ORGANIZATION">Organization of a CUPS Raster File</A></H2>
20
21<P><A HREF="FILEFORMAT">Figure 1, "Raster Organization"</A>, shows the general organization of all CUPS Raster files. Each file begins with a 32-bit synchronization word followed by zero or more pages. Each page consists of a header (the PostScript page device dictionary and raster-specific values) followed by the bitmap image for the page.</P>
22
23<DIV CLASS="figure"><TABLE SUMMARY="Raster Organization">
24<CAPTION><A NAME="FILEFORMAT">Figure 1: Raster Organization</A></CAPTION>
25<TR><TD><IMG SRC="../images/raster-organization.png" WIDTH="446" HEIGHT="1056" ALT="Raster Organization"></TD></TR>
26</TABLE></DIV>
27
28<P>Each page bitmap is stored as described by the <CODE>cupsBitsPerColor</CODE>, <CODE>cupsBytesPerLine</CODE>, <CODE>cupsColorOrder</CODE>, <CODE>cupsColorSpace</CODE>, <CODE>cupsHeight</CODE>, and <CODE>cupsWidth</CODE> values in the page header. Pixels for the front side of a sheet are always stored left-to-right, top-to-bottom. When doing duplex printing, pixels for the back side of a sheet may be stored differently depending on the value of the <CODE>cupsBackSide</CODE> keyword ("Normal", "ManualTumble", "Rotated", or "Flipped") in the PPD file and the <CODE>Tumble</CODE> value ("true" or "false") in the page header. <A HREF="#PAGEBITMAPS">Figure 2, "Page Bitmaps"</A>, shows the pixel order for each combination.</P>
29
30<DIV CLASS="figure"><TABLE SUMMARY="Page Bitmaps">
31<CAPTION><A NAME="PAGEBITMAPS">Figure 2: Page Bitmaps</A></CAPTION>
32<TR><TD><IMG SRC="../images/raster.png" WIDTH="624" HEIGHT="448" ALT="Page Bitmaps"></TD></TR>
33</TABLE></DIV>
4744bd90 34
35
36<H2 CLASS="title"><A NAME="V1">Version 1 Raster File Format</A></H2>
37
0268488e 38<P>A version 1 raster file begins with a 32-bit synchronization word: 0x52615374 ("RaSt") for big-endian architectures or 0x74536152 ("tSaR") for little-endian architectures. The writer of the raster file will use the native word order, and the reader is responsible for detecting a reversed word order file and swapping bytes as needed. The CUPS Imaging API raster functions perform this function automatically.</P>
4744bd90 39
0268488e 40<P>Following the synchronization word are a series of raster pages. Each page starts with a page device dictionary header and is followed immediately by the (uncompressed/raw) raster data for that page.</P>
4744bd90 41
42<DIV CLASS="table"><TABLE SUMMARY="CUPS Version 1 Raster Page Device Dictionary">
f301802f 43<CAPTION><A NAME="TABLE1">Table 1: CUPS Version 1 Raster Page Device Dictionary</A></CAPTION>
44<THEAD>
4744bd90 45<TR>
46 <TH>Bytes</TH>
47 <TH>Type</TH>
48 <TH>Description</TH>
49 <TH>Values</TH>
50</TR>
f301802f 51</THEAD>
52<TBODY>
4744bd90 53<TR>
54 <TD>0-63</TD>
55 <TD>C String</TD>
56 <TD>MediaClass</TD>
57 <TD>Media class string</TD>
58</TR>
59<TR>
60 <TD>64-127</TD>
61 <TD>C String</TD>
62 <TD>MediaColor</TD>
63 <TD>Media color string</TD>
64</TR>
65<TR>
66 <TD>128-191</TD>
67 <TD>C String</TD>
68 <TD>MediaType</TD>
69 <TD>Media type string</TD>
70</TR>
71<TR>
72 <TD>192-255</TD>
73 <TD>C String</TD>
74 <TD>OutputType</TD>
75 <TD>Output type string</TD>
76</TR>
77<TR>
78 <TD>256-259</TD>
79 <TD>Unsigned Integer</TD>
80 <TD>AdvanceDistance</TD>
81 <TD>0 to 2<SUP>32</SUP> - 1 points</TD>
82</TR>
83<TR>
84 <TD>260-263</TD>
85 <TD>Unsigned Integer</TD>
86 <TD>AdvanceMedia</TD>
87 <TD>0 = Never advance roll<BR>
88 1 = Advance roll after file<BR>
89 2 = Advance roll after job<BR>
90 3 = Advance roll after set<BR>
91 4 = Advance roll after page</TD>
92</TR>
93<TR>
94 <TD>264-267</TD>
95 <TD>Unsigned Integer</TD>
96 <TD>Collate</TD>
97 <TD>0 = do not collate copies<BR>
98 1 = collate copies</TD>
99</TR>
100<TR>
101 <TD>268-271</TD>
102 <TD>Unsigned Integer</TD>
103 <TD>CutMedia</TD>
104 <TD>0 = Never cut media<BR>
105 1 = Cut roll after file<BR>
106 2 = Cut roll after job<BR>
107 3 = Cut roll after set<BR>
108 4 = Cut roll after page</TD>
109</TR>
110<TR>
111 <TD>272-275</TD>
112 <TD>Unsigned Integer</TD>
113 <TD>Duplex</TD>
114 <TD>0 = Print single-sided<BR>
115 1 = Print double-sided</TD>
116</TR>
117<TR>
118 <TD>276-283</TD>
119 <TD>Unsigned Integers (2)</TD>
120 <TD>HWResolution</TD>
121 <TD>Horizontal and vertical resolution in dots-per-inch.</TD>
122</TR>
123<TR>
124 <TD>284-299</TD>
125 <TD>Unsigned Integers (4)</TD>
126 <TD>ImagingBoundingBox</TD>
127 <TD>Four integers giving the left, bottom, right, and top positions
128 of the page bounding box in points</TD>
129</TR>
130<TR>
131 <TD>300-303</TD>
132 <TD>Unsigned Integer</TD>
133 <TD>InsertSheet</TD>
134 <TD>0 = Do not insert separator sheets<BR>
135 1 = Insert separator sheets</TD>
136</TR>
137<TR>
138 <TD>304-307</TD>
139 <TD>Unsigned Integer</TD>
140 <TD>Jog</TD>
141 <TD>0 = Do no jog pages<BR>
142 1 = Jog pages after file<BR>
143 2 = Jog pages after job<BR>
144 3 = Jog pages after set</TD>
145</TR>
146<TR>
147 <TD>308-311</TD>
148 <TD>Unsigned Integer</TD>
149 <TD>LeadingEdge</TD>
150 <TD>0 = Top edge is first<BR>
151 1 = Right edge is first<BR>
152 2 = Bottom edge is first<BR>
153 3 = Left edge is first</TD>
154</TR>
155<TR>
156 <TD>312-319</TD>
157 <TD>Unsigned Integers (2)</TD>
158 <TD>Margins</TD>
159 <TD>Left and bottom origin of image in points</TD>
160</TR>
161<TR>
162 <TD>320-323</TD>
163 <TD>Unsigned Integer</TD>
164 <TD>ManualFeed</TD>
165 <TD>0 = Do not manually feed media<BR>
166 1 = Manually feed media</TD>
167</TR>
168<TR>
169 <TD>324-327</TD>
170 <TD>Unsigned Integer</TD>
171 <TD>MediaPosition</TD>
172 <TD>Input slot position from 0 to N</TD>
173</TR>
174<TR>
175 <TD>328-331</TD>
176 <TD>Unsigned Integer</TD>
177 <TD>MediaWeight</TD>
0268488e 178 <TD>Media weight in grams per meter squared, 0 = printer default</TD>
4744bd90 179</TR>
180<TR>
181 <TD>332-335</TD>
182 <TD>Unsigned Integer</TD>
183 <TD>MirrorPrint</TD>
184 <TD>0 = Do not mirror prints<BR>
185 1 = Mirror prints</TD>
186</TR>
187<TR>
188 <TD>336-339</TD>
189 <TD>Unsigned Integer</TD>
190 <TD>NegativePrint</TD>
191 <TD>0 = Do not invert prints<BR>
192 1 = Invert prints</TD>
193</TR>
194<TR>
195 <TD>340-343</TD>
196 <TD>Unsigned Integer</TD>
197 <TD>NumCopies</TD>
0268488e 198 <TD>0 to 2<SUP>32</SUP> - 1, 0 = printer default</TD>
4744bd90 199</TR>
200<TR>
201 <TD>344-347</TD>
202 <TD>Unsigned Integer</TD>
203 <TD>Orientation</TD>
204 <TD>0 = Do not rotate page<BR>
205 1 = Rotate page counter-clockwise<BR>
206 2 = Turn page upside down<BR>
207 3 = Rotate page clockwise</TD>
208</TR>
209<TR>
210 <TD>348-351</TD>
211 <TD>Unsigned Integer</TD>
212 <TD>OutputFaceUp</TD>
213 <TD>0 = Output face down<BR>
214 1 = Output face up</TD>
215</TR>
216<TR>
217 <TD>352-359</TD>
218 <TD>Unsigned Integers (2)</TD>
219 <TD>PageSize</TD>
220 <TD>Width and length in points</TD>
221</TR>
222<TR>
223 <TD>360-363</TD>
224 <TD>Unsigned Integer</TD>
225 <TD>Separations</TD>
226 <TD>0 = Print composite image<BR>
227 1 = Print color separations</TD>
228</TR>
229<TR>
230 <TD>364-367</TD>
231 <TD>Unsigned Integer</TD>
232 <TD>TraySwitch</TD>
233 <TD>0 = Do not change trays if selected tray is empty<BR>
234 1 = Change trays if selected tray is empty</TD>
235</TR>
236<TR>
237 <TD>368-371</TD>
238 <TD>Unsigned Integer</TD>
239 <TD>Tumble</TD>
240 <TD>0 = Do not rotate even pages when duplexing<BR>
241 1 = Rotate even pages when duplexing</TD>
242</TR>
243<TR>
244 <TD>372-375</TD>
245 <TD>Unsigned Integer</TD>
246 <TD>cupsWidth</TD>
247 <TD>Width of page image in pixels</TD>
248</TR>
249<TR>
250 <TD>376-379</TD>
251 <TD>Unsigned Integer</TD>
252 <TD>cupsHeight</TD>
253 <TD>Height of page image in pixels</TD>
254</TR>
255<TR>
256 <TD>380-383</TD>
257 <TD>Unsigned Integer</TD>
258 <TD>cupsMediaType</TD>
259 <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
260</TR>
261<TR>
262 <TD>384-387</TD>
263 <TD>Unsigned Integer</TD>
264 <TD>cupsBitsPerColor</TD>
265 <TD>1, 2, 4, 8 bits for version 1 raster files<BR>
84315f46 266 1, 2, 4, 8, and 16 bits for version 2/3 raster files</TD>
4744bd90 267</TR>
268<TR>
269 <TD>388-391</TD>
270 <TD>Unsigned Integer</TD>
271 <TD>cupsBitsPerPixel</TD>
272 <TD>1 to 32 bits for version 1 raster files<BR>
84315f46 273 1 to 240 bits for version 2/3 raster files</TD>
4744bd90 274</TR>
275<TR>
276 <TD>392-395</TD>
277 <TD>Unsigned Integer</TD>
278 <TD>cupsBytesPerLine</TD>
279 <TD>1 to 2<SUP>32</SUP> - 1 bytes</TD>
280</TR>
281<TR>
282 <TD>396-399</TD>
283 <TD>Unsigned Integer</TD>
284 <TD>cupsColorOrder</TD>
285 <TD>0 = chunky pixels (CMYK CMYK CMYK)<BR>
286 1 = banded pixels (CCC MMM YYY KKK)<BR>
287 2 = planar pixels (CCC... MMM... YYY... KKK...)</TD>
288</TR>
289<TR>
290 <TD>400-403</TD>
291 <TD>Unsigned Integer</TD>
292 <TD>cupsColorSpace</TD>
0268488e
MS		 293 <TD>0 = gray (device, typically sRGB-based)<BR>
294 1 = RGB (device, typically sRGB)<BR>
295 2 = RGBA (device, typically sRGB)<BR>
4744bd90 296 3 = black<BR>
297 4 = CMY<BR>
298 5 = YMC<BR>
299 6 = CMYK<BR>
300 7 = YMCK<BR>
301 8 = KCMY<BR>
302 9 = KCMYcm<BR>
303 10 = GMCK<BR>
304 11 = GMCS<BR>
305 12 = WHITE<BR>
306 13 = GOLD<BR>
307 14 = SILVER<BR>
308 15 = CIE XYZ<BR>
309 16 = CIE Lab<BR>
f301802f 310 17 = RGBW (sRGB)<BR>
0268488e
MS		 311 18 = sGray (gray using sRGB gamma/white point)<BR>
312 19 = sRGB<BR>
313 20 = AdobeRGB<BR>
f301802f 314 32 = ICC1 (CIE Lab with hint for 1 color)<BR>
315 33 = ICC2 (CIE Lab with hint for 2 colors)<BR>
316 34 = ICC3 (CIE Lab with hint for 3 colors)<BR>
317 35 = ICC4 (CIE Lab with hint for 4 colors)<BR>
318 36 = ICC5 (CIE Lab with hint for 5 colors)<BR>
319 37 = ICC6 (CIE Lab with hint for 6 colors)<BR>
320 38 = ICC7 (CIE Lab with hint for 7 colors)<BR>
321 39 = ICC8 (CIE Lab with hint for 8 colors)<BR>
322 40 = ICC9 (CIE Lab with hint for 9 colors)<BR>
323 41 = ICCA (CIE Lab with hint for 10 colors)<BR>
324 42 = ICCB (CIE Lab with hint for 11 colors)<BR>
325 43 = ICCC (CIE Lab with hint for 12 colors)<BR>
326 44 = ICCD (CIE Lab with hint for 13 colors)<BR>
327 45 = ICCE (CIE Lab with hint for 14 colors)<BR>
328 46 = ICCF (CIE Lab with hint for 15 colors)<BR>
0268488e 329 48 = Device1 (DeviceN for 1 color)<BR>
84315f46
MS		 330 49 = Device2 (DeviceN for 2 colors)<BR>
331 50 = Device3 (DeviceN for 3 colors)<BR>
332 51 = Device4 (DeviceN for 4 colors)<BR>
333 52 = Device5 (DeviceN for 5 colors)<BR>
334 53 = Device6 (DeviceN for 6 colors)<BR>
335 54 = Device7 (DeviceN for 7 colors)<BR>
336 55 = Device8 (DeviceN for 8 colors)<BR>
337 56 = Device9 (DeviceN for 9 colors)<BR>
338 57 = DeviceA (DeviceN for 10 colors)<BR>
339 58 = DeviceB (DeviceN for 11 colors)<BR>
340 59 = DeviceC (DeviceN for 12 colors)<BR>
341 60 = DeviceD (DeviceN for 13 colors)<BR>
342 61 = DeviceE (DeviceN for 14 colors)<BR>
343 62 = DeviceF (DeviceN for 15 colors)
4744bd90 344 </TD>
345</TR>
346<TR>
347 <TD>404-407</TD>
348 <TD>Unsigned Integer</TD>
349 <TD>cupsCompression</TD>
350 <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
351</TR>
352<TR>
353 <TD>408-411</TD>
354 <TD>Unsigned Integer</TD>
355 <TD>cupsRowCount</TD>
356 <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
357</TR>
358<TR>
359 <TD>412-415</TD>
360 <TD>Unsigned Integer</TD>
361 <TD>cupsRowFeed</TD>
362 <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
363</TR>
364<TR>
365 <TD>416-419</TD>
366 <TD>Unsigned Integer</TD>
367 <TD>cupsRowStep</TD>
368 <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
369</TR>
f301802f 370</TBODY>
4744bd90 371</TABLE></DIV>
372
373
374<H2 CLASS="title"><A NAME="V2">Version 2 Raster File Format</A></H2>
375
0268488e 376<P>A version 2 raster file begins with a 32-bit synchronization word: 0x52615332 ("RaS2") for big-endian architectures or 0x32536152 ("2SaR") for little-endian architectures. The writer of the raster file will use the native word order, and the reader is responsible for detecting a reversed word order file and swapping bytes as needed. The CUPS Imaging API raster functions perform this function automatically.</P>
4744bd90 377
0268488e 378<P>Following the synchronization word are a series of raster pages. Each page starts with a version 2 page device dictionary header and is followed immediately by the compressed raster data for that page.</P>
4744bd90 379
380<DIV CLASS="table"><TABLE SUMMARY="CUPS Version 2 Raster Page Device Dictionary">
f301802f 381<CAPTION><A NAME="TABLE2">Table 2: CUPS Version 2 Raster Page Device Dictionary</A></CAPTION>
382<THEAD>
4744bd90 383<TR>
384 <TH>Bytes</TH>
385 <TH>Type</TH>
386 <TH>Description</TH>
387 <TH>Values</TH>
388</TR>
f301802f 389</THEAD>
390<TBODY>
4744bd90 391<TR>
392 <TD>0-419</TD>
393 <TD>Version 1 header data</TD>
394 <TD>See Table 1</TD>
395</TR>
396<TR>
397 <TD>420-423</TD>
398 <TD>Unsigned Integer</TD>
399 <TD>cupsNumColors</TD>
84315f46 400 <TD>1 to 15 colors</TD>
4744bd90 401</TR>
402<TR>
403 <TD>424-427</TD>
404 <TD>IEEE Single Precision</TD>
405 <TD>cupsBorderlessScalingFactor</TD>
406 <TD>0.0 or 1.0 or greater</TD>
407</TR>
408<TR>
409 <TD>428-435</TD>
410 <TD>IEEE Single Precision (2)</TD>
411 <TD>cupsPageSize</TD>
412 <TD>Width and length in points</TD>
413</TR>
414<TR>
415 <TD>436-451</TD>
416 <TD>IEEE Single Precision (4)</TD>
417 <TD>cupsImagingBBox</TD>
0268488e 418 <TD>Four floating point numbers giving the left, bottom, right, and top positions of the page bounding box in points</TD>
4744bd90 419</TR>
420<TR>
421 <TD>452-515</TD>
422 <TD>Unsigned Integers (16)</TD>
423 <TD>cupsInteger</TD>
424 <TD>16 driver-defined integer values</TD>
425</TR>
426<TR>
427 <TD>516-579</TD>
428 <TD>IEEE Single Precision (16)</TD>
429 <TD>cupsReal</TD>
430 <TD>16 driver-defined floating point values</TD>
431</TR>
432<TR>
433 <TD>580-1603</TD>
434 <TD>C Strings (16x64)</TD>
435 <TD>cupsString</TD>
436 <TD>16 driver-defined strings</TD>
437</TR>
438<TR>
439 <TD>1604-1667</TD>
440 <TD>C String</TD>
441 <TD>cupsMarkerType</TD>
442 <TD>Ink/toner type string</TD>
443</TR>
444<TR>
445 <TD>1668-1731</TD>
446 <TD>C String</TD>
447 <TD>cupsRenderingIntent</TD>
448 <TD>Color rendering intent string</TD>
449</TR>
450<TR>
451 <TD>1732-1795</TD>
452 <TD>C String</TD>
453 <TD>cupsPageSizeName</TD>
454 <TD>Page size name/keyword string from PPD</TD>
455</TR>
f301802f 456</TBODY>
4744bd90 457</TABLE></DIV>
458
459<H3><A NAME="COMPRESSION">Compressed Raster Data Format</A></H3>
460
0268488e 461<P>The version 2 raster data is compressed using a PackBits-like algorithm. Lines are grouped into an integral number of color values based upon the <CODE>cupsColorOrder</CODE> setting:</P>
4744bd90 462
463<DIV CLASS="table"><TABLE SUMMARY="Color Value Sizes">
f301802f 464<CAPTION><A NAME="TABLE3">Table 3: Color Value Sizes</A></CAPTION>
4744bd90 465<TR>
466 <TH>cupsColorOrder</TH>
467 <TH>Bytes per color value</TH>
468</TR>
469<TR>
470 <TD>0 (chunky)</TD>
471 <TD>(<CODE>cupsBitsPerPixel</CODE> + 7) / 8</TD>
472</TR>
473<TR>
474 <TD>1 (banded)</TD>
475 <TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD>
476</TR>
477<TR>
478 <TD>2 (planar)</TD>
479 <TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD>
480</TR>
481</TABLE></DIV>
482
0268488e
MS		 483<P>Each line of raster data begins with a repetition count from 1 to 256 that is encoded using a single byte of "count - 1".</P>
484
485<P>After the repetition count, whole color values for that line are run-length encoded using a PackBits-like run-length encoding algorithm: 1 to 128 repeated colors are encoded using an initial byte of "count - 1" followed by the color value byte(s) while 2 to 128 non-repeating colors are encoded using an initial byte of "257 - count" followed by the color value bytes.</P>
486
487<P>For example, the 8x8 24-bit sRGB image shown in <a href="#SAMPLEIMAGE">Figure 3, "Sample Image"</a>, would be encoded as the following 89 octets:</p>
488
489<PRE CLASS="example">
490%x00 %x00.FF.FF.FF %x02.FF.FF.00 %x03.FF.FF.FF
491%x00 %xFE.FF.FF.00.00.00.FF.FF.FF.00 %x02.FF.FF.FF %x00.00.FF.00 %x00.FF.FF.FF
492%x00 %x01.FF.FF.00 %x02.FF.FF.FF %x02.00.FF.00
493%x00 %x02.FF.FF.00 %x02.FF.FF.FF %x00.00.FF.00 %x00.FF.FF.FF
494%x00 %x00.FF.FF.FF %x02.FF.FF.00 %x03.FF.FF.FF
495%x00 %x07.FF.FF.FF
496%x01 %x07.FF.00.00
497</PRE>
498
499<P>The first line (%x00) contains 1 white pixel (%x00.FF.FF.FF), 3 yellow pixels (%x02.FF.FF.00), and 4 white pixels (%x03.FF.FF.FF).</P>
500
501<P>The second line (%x00) contains a sequence of yellow + blue + yellow pixels (%xFE.FF.FF.00.00.00.FF.FF.FF.00), 3 white pixels (%x02.FF.FF.FF), 1 green pixel (%x00.00.FF.00), and 1 white pixel (%x00.FF.FF.FF).</P>
4744bd90 502
0268488e
MS		 503<P>The third line (%x00) contains 2 yellow pixels (%x01.FF.FF.00), 3 white pixels (%x02.FF.FF.FF), and 3 green pixels (%x02.00.FF.00)</P>
504
505<P>The fourth line (%x00) contains 3 yellow pixels (%x02.FF.FF.00), 3 white pixels (%x02.FF.FF.FF), 1 green pixel (%x00.00.FF.00), and 1 white pixel (%x00.FF.FF.FF).</P>
506
507<P>The fifth line (%x00) contains 1 white pixel (%x00.FF.FF.FF), 3 yellow pixels (%x02.FF.FF.00), and 4 white pixels (%x03.FF.FF.FF).</P>
508
509<P>The sixth line (%x00) contains 8 white pixels (%x07.FF.FF.FF).</P>
510
511<P>The seventh and eighth lines (%x01) contain 8 red pixels (%x07.FF.00.00).</P>
512
513<DIV CLASS="figure"><TABLE SUMMARY="Sample Image">
514<CAPTION><A NAME="SAMPLEIMAGE">Figure 3: Sample Image</A></CAPTION>
515<TR><TD><IMG SRC="../images/sample-image.png" WIDTH="257" HEIGHT="257" ALT="Sample Image"></TD></TR>
516</TABLE></DIV>
4744bd90 517
518
ed486911 519<H2 CLASS="title"><A NAME="V3">Version 3 Raster File Format</A></H2>
520
0268488e 521<P>A version 3 raster file begins with a 32-bit synchronization word: 0x52615333 ("RaS3") for big-endian architectures and 0x33536152 ("3SaR") for little-endian architectures. The writer of the raster file will use the native word order, and the reader is responsible for detecting a reversed word order file and swapping bytes as needed. The CUPS Imaging API raster functions perform this function automatically.</P>
ed486911 522
0268488e 523<P>Following the synchronization word are a series of raster pages. Each page starts with a version 2 page device dictionary header and is followed immediately by the uncompressed/raw raster data for that page.</P>
ed486911 524
525
f301802f 526<H2 CLASS="title"><A NAME="ENCODING">Pixel Value Coding</A></H2>
527
0268488e 528<P>The following sections describe the encoding and decoding of the color values in a CUPS Raster file. In general, colors are packed into the minimum number of bytes, with special consideration provided for efficiency of encoding and access. Multi-byte values are stored in the native byte order and automatically swapped as needed when reading them using the CUPS imaging API.</P>
f301802f 529
530<H3>CUPS_ORDER_CHUNKED</H3>
531
0268488e 532<P>The chunked order provides the pixel value packed in a single place. Pixel values with 8 or more bits per color are stored as an array of colors in order, e.g. for <CODE>CUPS_CSPACE_RGB</CODE> you will see 8/16-bits of red, then blue, then green, then red, green, blue, etc. Pixel values with less than 8 bits per color are packed together as shown in Table 4. <I>Multi-byte pixel values are stored in the native word order, just as for 16-bit color values.</I></P>
f301802f 533
534<DIV CLASS="table"><TABLE SUMMARY="Chunked Color Values">
535<CAPTION><A NAME="TABLE4">Table 4: Chunked Color Values</A></CAPTION>
536<THEAD>
537<TR>
538 <TH>Bits</TH>
539 <TH>1-color</TH>
540 <TH>3-color</TH>
541 <TH>4-color</TH>
542 <TH>6-color</TH>
543</TR>
544</THEAD>
545<TBODY>
546<TR>
547 <TD>1</TD>
548 <TD>W/W/W/W/W/W/W/W</TD>
549 <TD>0RGB/0RGB</TD>
550 <TD>CMYK/CMYK</TD>
551 <TD>00KCMYcm</TD>
552</TR>
553<TR>
554 <TD>2</TD>
555 <TD>WW/WW/WW/WW</TD>
556 <TD>00RRGGBB</TD>
557 <TD>CCMMYYKK</TD>
558 <TD>N/A</TD>
559</TR>
560<TR>
561 <TD>4</TD>
562 <TD>WWWW/WWWW</TD>
563 <TD>0000RRRRGGGGBBBB<BR>
564 <I>(multi-byte)</I></TD>
565 <TD>CCCCMMMMYYYYKKKK<BR>
566 <I>(multi-byte)</I></TD>
567 <TD>N/A</TD>
568</TR>
569</TBODY>
570</TABLE></DIV>
571
572<H3>CUPS_ORDER_BANDED</H3>
573
0268488e 574<P>The banded order provides each color as a separate line of data. Each color plane for a line is written in sequence, e.g. for the <CODE>CUPS_CSPACE_CMYK</CODE> color space you would see all of the cyan pixels for a line followed by the magenta, yellow, and black pixels for that line. This is repeated for all of the lines on the page. Color values are packed starting with the most-significant bit (MSB) first.</P>
f301802f 575
576<H3>CUPS_ORDER_PLANAR</H3>
577
0268488e 578<P>The planar order provides each color as a separate page of data using a shared page header. Each color plane for a page is written in sequence, e.g. for the <CODE>CUPS_CSPACE_CMYK</CODE> color space you would see all of the cyan pixels for a page followed by the magenta, yellow, and black pixels for that page. Color values are packed starting with the most-significant bit (MSB) first. Each line starts on an 8-bit boundary.</P>
f301802f 579
0268488e 580<H3>CUPS_CSPACE_RGBW</H3>
f301802f 581
0268488e 582<P>This color space provides a dedicated black text channel and uses the sRGB color space definition and whitepoint for the RGB color channels. The white channel is 0 for text (or "true") black, otherwise it must contain the maximum color value: 1 for 1-bit, 3 for 2-bit, 15 for 4-bit, 255 for 8-bit, or 65535 for 16-bit.</P>
f301802f 583
584<H3>CUPS_CSPACE_KCMYcm</H3>
585
0268488e 586<P>When <CODE>cupsBitsPerColor</CODE> is 1, 6 color planes are provided - black, cyan, magenta, yellow, light cyan, and light magenta. When <CODE>cupsBitsPerColor</CODE> is greater than 1, 4 color planes are provided using the <CODE>CUPS_CSPACE_KCMY</CODE> color space instead.</P>
f301802f 587
0268488e 588<P>When <CODE>cupsColorOrder</CODE> is <CODE>CUPS_ORDER_CHUNKED</CODE>, bit 5 corresponds to black and bit 0 corresponds to light magenta. For <CODE>CUPS_ORDER_BANDED</CODE> and <CODE>CUPS_ORDER_PLANAR</CODE>, each color plane is encoded separately.</P>
f301802f 589
590<H3>CUPS_CSPACE_CIELab and CUPS_CSPACE_ICCn</H3>
591
0268488e 592<P>These color spaces map a CIE Lab color value with a D65 whitepoint to either a 8- or 16-bit per color chunked (<CODE>CUPS_ORDER_CHUNKED</CODE>) format; the banded (<CODE>CUPS_ORDER_BANDED</CODE>) and planar (<CODE>CUPS_ORDER_PLANAR</CODE>) color orders are not supported.</P>
f301802f 593
0268488e 594<P>The values are encoded and decoded using the following formulas:</P>
f301802f 595
596<UL>
597
598 <LI>8-bit Encoding:<BR>
599 <I>L8 = 2.55 * L + 0.5<BR>
600 a8 = a + 128.5<BR>
601 b8 = b + 128.5<BR>
602 &nbsp;</I></LI>
603
604 <LI>8-bit Decoding:<BR>
605 <I>L = L8 / 2.55<BR>
606 a = a8 - 128<BR>
607 b = b8 - 128<BR>
608 &nbsp;</I></LI>
609
610 <LI>16-bit Encoding:<BR>
611 <I>L16 = 655.35 * L + 0.5<BR>
612 a16 = 256 * (a + 128) + 0.5<BR>
613 b16 = 256 * (b + 128) + 0.5<BR>
614 &nbsp;</I></LI>
615
616 <LI>16-bit Decoding:<BR>
617 <I>L = L16 / 655.35<BR>
618 a = a16 / 256 - 128<BR>
619 b = b16 / 256 - 128<BR>
620 &nbsp;</I></LI>
621
622</UL>
623
624<H3>CUPS_CSPACE_CIEXYZ</H3>
625
0268488e 626<P>These color spaces map a CIE XYZ color value with a D65 whitepoint to either a 8- or 16-bit per color chunked (<CODE>CUPS_ORDER_CHUNKED</CODE>) format; the banded (<CODE>CUPS_ORDER_BANDED</CODE>) and planar (<CODE>CUPS_ORDER_PLANAR</CODE>) color orders are not supported.</P>
f301802f 627
0268488e 628<P>The values are encoded and decoded using the following formulas:</P>
f301802f 629
630<UL>
631
632 <LI>8-bit Encoding:<BR>
633 <I>X8 = 231.8181 * X + 0.5<BR>
634 Y8 = 231.8181 * Y + 0.5<BR>
635 Z8 = 231.8181 * Z + 0.5<BR>
636 &nbsp;</I></LI>
637
638 <LI>8-bit Decoding:<BR>
639 <I>X = X8 / 231.8181<BR>
640 Y = Y8 / 231.8181<BR>
641 Z = Z8 / 231.8181<BR>
642 &nbsp;</I></LI>
643
644 <LI>16-bit Encoding:<BR>
645 <I>X16 = 59577.2727 * X + 0.5<BR>
646 Y16 = 59577.2727 * Y + 0.5<BR>
647 Z16 = 59577.2727 * Z + 0.5<BR>
648 &nbsp;</I></LI>
649
650 <LI>16-bit Decoding:<BR>
651 <I>X = X16 / 59577.2727<BR>
652 Y = Y16 / 59577.2727<BR>
653 Z = Z16 / 59577.2727<BR>
654 &nbsp;</I></LI>
655
656</UL>
657
0268488e 658<P>The scaling factor for XYZ values is 1/1.1, or 231.8181 for 8-bit values and 59577.2727 for 16-bit values. This allows for a slight overflow of XYZ values when converting from RGB, improving accuracy.</P>
f301802f 659
4744bd90 660
661<H2 CLASS="title"><A NAME="HISTORY">Change History</A></H2>
662
0268488e
MS		 663<H3>Changes in CUPS 1.4.7</H3>
664
665<ul>
666
667 <li>Greatly improved the detail and now include an example of the bitmap compression.</li>
668 <li>Added all missing cupsColorSpace values and a separate description of CUPS_CSPACE_RGBW.</li>
669
670</ul>
671
672
ed486911 673<H3>Changes in CUPS 1.2.2</H3>
674
675<ul>
676
677 <li>Added version 3 (uncompressed) format.</li>
678
679</ul>
680
681
f301802f 682<H3>Changes in CUPS 1.2.1</H3>
683
684<ul>
685
686 <li>Added new sections on coding pixel values.</li>
687
688 <li>Clarified definitions of color spaces.</li>
689
690</ul>
691
692
4744bd90 693<H3>Changes in CUPS 1.2</H3>
694
695<ul>
696
697 <li>Bumped raster version to 2</li>
698
0268488e 699 <li>Added RGBW color space</li>
4744bd90 700
701 <li>Added 16 bit per color support</li>
702
0268488e 703 <li>Added cupsNumColors, cupsBorderlessScalingFactor, cupsPageSize, cupsImagingBBox, cupsInteger, cupsReal, cupsString, cupsMarkerType, cupsRenderingIntent, and cupsPageSizeName attributes to the page device dictionary</li>
4744bd90 704
705 <li>Added raster data compression</li>
706
0268488e 707 <li>Added data type column to device dictionary documentation.</li>
4744bd90 708
709</ul>
710
711<h3>Changes in CUPS 1.1.19</h3>
712
713<ul>
714
0268488e 715 <li>Added ICC and CIE color spaces.</li>
4744bd90 716
717</ul>
718
719</BODY>
720</HTML>
Unnamed repository; edit this file 'description' to name the repository.