1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
3 <!-- SECTION: Specifications -->
5 <TITLE>CUPS Raster Format
</TITLE>
6 <LINK REL=
"STYLESHEET" TYPE=
"test/css" HREF=
"../cups.css">
10 <P>CUPS raster files are device-dependent raster image files that
11 contain a PostScript page device dictionary and device-dependent
12 raster imagery for each page in the document. These files are
13 used to transfer raster data from the PostScript and image file
14 RIPs to device-dependent filters that convert the raster data to
15 a printable format.
</P>
17 <P>CUPS
1.0 and
1.1 used a version
1 raster format. CUPS
1.2
18 introduces version
2 (compressed) and version
3 (uncompressed)
19 formats that are a superset of the version
1 format. Applications
20 using the CUPS Imaging API (the cupsRaster* functions) can read
21 all formats without code changes.
</P>
23 <P>The registered MIME media type for CUPS raster files is
24 <CODE>application/vnd.cups-raster
</CODE>.
</P>
27 <H2 CLASS=
"title"><A NAME=
"V1">Version
1 Raster File Format
</A></H2>
29 <P>A version
1 raster file begins with a
32-bit synchronization
30 word:
0x52615374 (
"RaSt") for big-endian architectures and
31 0x74536152 (
"tSaR") for little-endian architectures. The writer
32 of the raster file will use the native word order, and the reader
33 is responsible for detecting a reversed word order file and
34 swapping bytes as needed. The CUPS Imaging API raster functions
35 perform this function automatically.
</P>
37 <P>Following the synchronization word are a series of raster
38 pages. Each page starts with a page device dictionary header and
39 is followed immediately by the (uncompressed, raw) raster data
42 <DIV CLASS=
"table"><TABLE SUMMARY=
"CUPS Version 1 Raster Page Device Dictionary">
43 <CAPTION><A NAME=
"TABLE1">Table
1: CUPS Version
1 Raster Page Device Dictionary
</A></CAPTION>
57 <TD>Media class string
</TD>
63 <TD>Media color string
</TD>
69 <TD>Media type string
</TD>
75 <TD>Output type string
</TD>
79 <TD>Unsigned Integer
</TD>
80 <TD>AdvanceDistance
</TD>
81 <TD>0 to
2<SUP>32</SUP> -
1 points
</TD>
85 <TD>Unsigned Integer
</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>
95 <TD>Unsigned Integer
</TD>
97 <TD>0 = do not collate copies
<BR>
98 1 = collate copies
</TD>
102 <TD>Unsigned Integer
</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>
112 <TD>Unsigned Integer
</TD>
114 <TD>0 = Print single-sided
<BR>
115 1 = Print double-sided
</TD>
119 <TD>Unsigned Integers (
2)
</TD>
120 <TD>HWResolution
</TD>
121 <TD>Horizontal and vertical resolution in dots-per-inch.
</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>
132 <TD>Unsigned Integer
</TD>
134 <TD>0 = Do not insert separator sheets
<BR>
135 1 = Insert separator sheets
</TD>
139 <TD>Unsigned Integer
</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>
148 <TD>Unsigned Integer
</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>
157 <TD>Unsigned Integers (
2)
</TD>
159 <TD>Left and bottom origin of image in points
</TD>
163 <TD>Unsigned Integer
</TD>
165 <TD>0 = Do not manually feed media
<BR>
166 1 = Manually feed media
</TD>
170 <TD>Unsigned Integer
</TD>
171 <TD>MediaPosition
</TD>
172 <TD>Input slot position from
0 to N
</TD>
176 <TD>Unsigned Integer
</TD>
178 <TD>Media weight in grams per meter squared
</TD>
182 <TD>Unsigned Integer
</TD>
184 <TD>0 = Do not mirror prints
<BR>
185 1 = Mirror prints
</TD>
189 <TD>Unsigned Integer
</TD>
190 <TD>NegativePrint
</TD>
191 <TD>0 = Do not invert prints
<BR>
192 1 = Invert prints
</TD>
196 <TD>Unsigned Integer
</TD>
198 <TD>1 to
2<SUP>32</SUP> -
1</TD>
202 <TD>Unsigned Integer
</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>
211 <TD>Unsigned Integer
</TD>
212 <TD>OutputFaceUp
</TD>
213 <TD>0 = Output face down
<BR>
214 1 = Output face up
</TD>
218 <TD>Unsigned Integers (
2)
</TD>
220 <TD>Width and length in points
</TD>
224 <TD>Unsigned Integer
</TD>
226 <TD>0 = Print composite image
<BR>
227 1 = Print color separations
</TD>
231 <TD>Unsigned Integer
</TD>
233 <TD>0 = Do not change trays if selected tray is empty
<BR>
234 1 = Change trays if selected tray is empty
</TD>
238 <TD>Unsigned Integer
</TD>
240 <TD>0 = Do not rotate even pages when duplexing
<BR>
241 1 = Rotate even pages when duplexing
</TD>
245 <TD>Unsigned Integer
</TD>
247 <TD>Width of page image in pixels
</TD>
251 <TD>Unsigned Integer
</TD>
253 <TD>Height of page image in pixels
</TD>
257 <TD>Unsigned Integer
</TD>
258 <TD>cupsMediaType
</TD>
259 <TD>Driver-specific
0 to
2<SUP>32</SUP> -
1</TD>
263 <TD>Unsigned Integer
</TD>
264 <TD>cupsBitsPerColor
</TD>
265 <TD>1,
2,
4,
8 bits for version
1 raster files
<BR>
266 1,
2,
4,
8, and
16 bits for version
2 raster files
</TD>
270 <TD>Unsigned Integer
</TD>
271 <TD>cupsBitsPerPixel
</TD>
272 <TD>1 to
32 bits for version
1 raster files
<BR>
273 1 to
64 bits for version
2 raster files
</TD>
277 <TD>Unsigned Integer
</TD>
278 <TD>cupsBytesPerLine
</TD>
279 <TD>1 to
2<SUP>32</SUP> -
1 bytes
</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>
291 <TD>Unsigned Integer
</TD>
292 <TD>cupsColorSpace
</TD>
293 <TD>0 = white (sRGB)
<BR>
311 32 = ICC1 (CIE Lab with hint for
1 color)
<BR>
312 33 = ICC2 (CIE Lab with hint for
2 colors)
<BR>
313 34 = ICC3 (CIE Lab with hint for
3 colors)
<BR>
314 35 = ICC4 (CIE Lab with hint for
4 colors)
<BR>
315 36 = ICC5 (CIE Lab with hint for
5 colors)
<BR>
316 37 = ICC6 (CIE Lab with hint for
6 colors)
<BR>
317 38 = ICC7 (CIE Lab with hint for
7 colors)
<BR>
318 39 = ICC8 (CIE Lab with hint for
8 colors)
<BR>
319 40 = ICC9 (CIE Lab with hint for
9 colors)
<BR>
320 41 = ICCA (CIE Lab with hint for
10 colors)
<BR>
321 42 = ICCB (CIE Lab with hint for
11 colors)
<BR>
322 43 = ICCC (CIE Lab with hint for
12 colors)
<BR>
323 44 = ICCD (CIE Lab with hint for
13 colors)
<BR>
324 45 = ICCE (CIE Lab with hint for
14 colors)
<BR>
325 46 = ICCF (CIE Lab with hint for
15 colors)
<BR>
330 <TD>Unsigned Integer
</TD>
331 <TD>cupsCompression
</TD>
332 <TD>Driver-specific
0 to
2<SUP>32</SUP> -
1</TD>
336 <TD>Unsigned Integer
</TD>
337 <TD>cupsRowCount
</TD>
338 <TD>Driver-specific
0 to
2<SUP>32</SUP> -
1</TD>
342 <TD>Unsigned Integer
</TD>
344 <TD>Driver-specific
0 to
2<SUP>32</SUP> -
1</TD>
348 <TD>Unsigned Integer
</TD>
350 <TD>Driver-specific
0 to
2<SUP>32</SUP> -
1</TD>
356 <H2 CLASS=
"title"><A NAME=
"V2">Version
2 Raster File Format
</A></H2>
358 <P>A version
2 raster file begins with a
32-bit synchronization
359 word:
0x52615332 (
"RaS2") for big-endian architectures and
360 0x32536152 (
"2SaR") for little-endian architectures. The writer
361 of the raster file will use the native word order, and the reader
362 is responsible for detecting a reversed word order file and
363 swapping bytes as needed. The CUPS Imaging API raster functions
364 perform this function automatically.
</P>
366 <P>Following the synchronization word are a series of raster
367 pages. Each page starts with a version
2 page device dictionary
368 header and is followed immediately by the compressed raster data
371 <DIV CLASS=
"table"><TABLE SUMMARY=
"CUPS Version 2 Raster Page Device Dictionary">
372 <CAPTION><A NAME=
"TABLE2">Table
2: CUPS Version
2 Raster Page Device Dictionary
</A></CAPTION>
384 <TD>Version
1 header data
</TD>
389 <TD>Unsigned Integer
</TD>
390 <TD>cupsNumColors
</TD>
391 <TD>1 to
6 colors
</TD>
395 <TD>IEEE Single Precision
</TD>
396 <TD>cupsBorderlessScalingFactor
</TD>
397 <TD>0.0 or
1.0 or greater
</TD>
401 <TD>IEEE Single Precision (
2)
</TD>
402 <TD>cupsPageSize
</TD>
403 <TD>Width and length in points
</TD>
407 <TD>IEEE Single Precision (
4)
</TD>
408 <TD>cupsImagingBBox
</TD>
409 <TD>Four floating point numbers giving the left, bottom,
410 right, and top positions of the page bounding box in
415 <TD>Unsigned Integers (
16)
</TD>
417 <TD>16 driver-defined integer values
</TD>
421 <TD>IEEE Single Precision (
16)
</TD>
423 <TD>16 driver-defined floating point values
</TD>
427 <TD>C Strings (
16x64)
</TD>
429 <TD>16 driver-defined strings
</TD>
434 <TD>cupsMarkerType
</TD>
435 <TD>Ink/toner type string
</TD>
440 <TD>cupsRenderingIntent
</TD>
441 <TD>Color rendering intent string
</TD>
446 <TD>cupsPageSizeName
</TD>
447 <TD>Page size name/keyword string from PPD
</TD>
452 <H3><A NAME=
"COMPRESSION">Compressed Raster Data Format
</A></H3>
454 <P>The version
2 raster data is compressed using a modified TIFF
455 packbits algorithm. Lines are grouped into an integral number of
456 color values based upon the
<CODE>cupsColorOrder
</CODE>
459 <DIV CLASS=
"table"><TABLE SUMMARY=
"Color Value Sizes">
460 <CAPTION><A NAME=
"TABLE3">Table
3: Color Value Sizes
</A></CAPTION>
462 <TH>cupsColorOrder
</TH>
463 <TH>Bytes per color value
</TH>
467 <TD>(
<CODE>cupsBitsPerPixel
</CODE> +
7) /
8</TD>
471 <TD>(
<CODE>cupsBitsPerColor
</CODE> +
7) /
8</TD>
475 <TD>(
<CODE>cupsBitsPerColor
</CODE> +
7) /
8</TD>
479 <P>Each line of raster data begins with a repetition count from
1
480 to
256 that is encoded using a single byte of
"count - 1".
</P>
482 <P>After the repetition count, whole color values for that line
483 are run-length encoded using the TIFF packbits algorithm.
1 to
484 128 repeated colors are encoded using an initial byte of
"count -
485 1" followed by the color value byte(s).
2 to
128 non-repeating
486 colors are encoded using an initial byte of
"257 - count"
487 followed by the color value bytes.
</P>
490 <H2 CLASS=
"title"><A NAME=
"V3">Version
3 Raster File Format
</A></H2>
492 <P>A version
3 raster file begins with a
32-bit synchronization
493 word:
0x52615333 (
"RaS3") for big-endian architectures and
494 0x33536152 (
"3SaR") for little-endian architectures. The writer
495 of the raster file will use the native word order, and the reader
496 is responsible for detecting a reversed word order file and
497 swapping bytes as needed. The CUPS Imaging API raster functions
498 perform this function automatically.
</P>
500 <P>Following the synchronization word are a series of raster
501 pages. Each page starts with a version
2 page device dictionary
502 header and is followed immediately by the uncompressed raster data
506 <H2 CLASS=
"title"><A NAME=
"ENCODING">Pixel Value Coding
</A></H2>
508 <P>The following sections describe the encoding and decoding of
509 the color values in a CUPS raster file. In general, colors are
510 packed into the minimum number of bytes, with special
511 consideration provided for efficiency of encoding and access.
512 Multi-byte values are stored in the native byte order and
513 automatically swapped as needed when reading them using the CUPS
516 <H3>CUPS_ORDER_CHUNKED
</H3>
518 <P>The chunked order provides the pixel value packed in a single
519 place. Pixel values with
8 or more bits per color are stored as
520 an array of colors in order, e.g. for
521 <CODE>CUPS_CSPACE_RGB
</CODE> you will see
8/
16-bits of red, then
522 blue, then green, then red, green, blue, etc. Pixel values with
523 less than
8 bits per color are packed together as shown in Table
524 4.
<I>Multi-byte pixel values are stored in the native word
525 order, just as for
16-bit color values.
</I></P>
527 <DIV CLASS=
"table"><TABLE SUMMARY=
"Chunked Color Values">
528 <CAPTION><A NAME=
"TABLE4">Table
4: Chunked Color Values
</A></CAPTION>
541 <TD>W/W/W/W/W/W/W/W
</TD>
556 <TD>0000RRRRGGGGBBBB
<BR>
557 <I>(multi-byte)
</I></TD>
558 <TD>CCCCMMMMYYYYKKKK
<BR>
559 <I>(multi-byte)
</I></TD>
565 <H3>CUPS_ORDER_BANDED
</H3>
567 <P>The banded order provides each color as a separate line of
568 data. Each color plane for a line is written in sequence, e.g.
569 for the
<CODE>CUPS_CSPACE_CMYK
</CODE> colorspace you would see
570 all of the cyan pixels for a line followed by the magenta,
571 yellow, and black pixels for that line. This is repeated for all
572 of the lines on the page. Color values are packed starting with
573 the most-significant bit (MSB) first.
</P>
575 <H3>CUPS_ORDER_PLANAR
</H3>
577 <P>The planar order provides each color as a separate page of
578 data using a shared page header. Each color plane for a page is
579 written in sequence, e.g. for the
<CODE>CUPS_CSPACE_CMYK
</CODE>
580 colorspace you would see all of the cyan pixels for a page
581 followed by the magenta, yellow, and black pixels for that page.
582 Color values are packed starting with the most-significant bit
583 (MSB) first. Each line starts on an
8-bit boundary.
</P>
585 <H3>CUPS_CSPACE_W, CUPS_CSPACE_RGB, CUPS_CSPACE_RGBA, and
586 CUPS_CSPACE_RGBW
</H3>
588 <P>These colorspaces use the sRGB colorspace definition and
591 <H3>CUPS_CSPACE_KCMYcm
</H3>
593 <P>When
<CODE>cupsBitsPerColor
</CODE> is
1,
6 color planes are
594 provided - black, cyan, magenta, yellow, light cyan, and light
595 magenta. When
<CODE>cupsBitsPerColor
</CODE> is greater than
1,
4
596 color planes are provided using the
<CODE>CUPS_CSPACE_KCMY
</CODE>
597 colorspace instead.
</P>
599 <P>When
<CODE>cupsColorOrder
</CODE> is
600 <CODE>CUPS_ORDER_CHUNKED
</CODE>, bit
5 corresponds to black and
601 bit
0 corresponds to light magenta. For
602 <CODE>CUPS_ORDER_BANDED
</CODE> and
603 <CODE>CUPS_ORDER_PLANAR
</CODE>, each color plane is encoded
606 <H3>CUPS_CSPACE_CIELab and CUPS_CSPACE_ICCn
</H3>
608 <P>These colorspaces map a CIE Lab color value with a D65
609 whitepoint to either a
8- or
16-bit per color chunked
610 (
<CODE>CUPS_ORDER_CHUNKED
</CODE>) format; the banded
611 (
<CODE>CUPS_ORDER_BANDED
</CODE>) and planar
612 (
<CODE>CUPS_ORDER_PLANAR
</CODE>) color orders are not
615 <P>The values are encoded and decoded using the following
620 <LI>8-bit Encoding:
<BR>
621 <I>L8 =
2.55 * L +
0.5<BR>
626 <LI>8-bit Decoding:
<BR>
632 <LI>16-bit Encoding:
<BR>
633 <I>L16 =
655.35 * L +
0.5<BR>
634 a16 =
256 * (a +
128) +
0.5<BR>
635 b16 =
256 * (b +
128) +
0.5<BR>
638 <LI>16-bit Decoding:
<BR>
639 <I>L = L16 /
655.35<BR>
640 a = a16 /
256 -
128<BR>
641 b = b16 /
256 -
128<BR>
646 <H3>CUPS_CSPACE_CIEXYZ
</H3>
648 <P>These colorspaces map a CIE XYZ color value with a D65
649 whitepoint to either a
8- or
16-bit per color chunked
650 (
<CODE>CUPS_ORDER_CHUNKED
</CODE>) format; the banded
651 (
<CODE>CUPS_ORDER_BANDED
</CODE>) and planar
652 (
<CODE>CUPS_ORDER_PLANAR
</CODE>) color orders are not
655 <P>The values are encoded and decoded using the following
660 <LI>8-bit Encoding:
<BR>
661 <I>X8 =
231.8181 * X +
0.5<BR>
662 Y8 =
231.8181 * Y +
0.5<BR>
663 Z8 =
231.8181 * Z +
0.5<BR>
666 <LI>8-bit Decoding:
<BR>
667 <I>X = X8 /
231.8181<BR>
668 Y = Y8 /
231.8181<BR>
669 Z = Z8 /
231.8181<BR>
672 <LI>16-bit Encoding:
<BR>
673 <I>X16 =
59577.2727 * X +
0.5<BR>
674 Y16 =
59577.2727 * Y +
0.5<BR>
675 Z16 =
59577.2727 * Z +
0.5<BR>
678 <LI>16-bit Decoding:
<BR>
679 <I>X = X16 /
59577.2727<BR>
680 Y = Y16 /
59577.2727<BR>
681 Z = Z16 /
59577.2727<BR>
686 <P>The scaling factor for XYZ values is
1/
1.1, or
231.8181 for
687 8-bit values and
59577.2727 for
16-bit values. This allows for a
688 slight overflow of XYZ values when converting from RGB, improving
692 <H2 CLASS=
"title"><A NAME=
"HISTORY">Change History
</A></H2>
694 <H3>Changes in CUPS
1.2.2</H3>
698 <li>Added version
3 (uncompressed) format.
</li>
703 <H3>Changes in CUPS
1.2.1</H3>
707 <li>Added new sections on coding pixel values.
</li>
709 <li>Clarified definitions of color spaces.
</li>
714 <H3>Changes in CUPS
1.2</H3>
718 <li>Bumped raster version to
2</li>
720 <li>Added RGBW colorspace
</li>
722 <li>Added
16 bit per color support
</li>
724 <li>Added cupsNumColors, cupsBorderlessScalingFactor,
725 cupsPageSize, cupsImagingBBox, cupsInteger, cupsReal,
726 cupsString, cupsMarkerType, cupsRenderingIntent, and
727 cupsPageSizeName attributes to the page device
730 <li>Added raster data compression
</li>
732 <li>Added data type column to device dictionary
737 <h3>Changes in CUPS
1.1.19</h3>
741 <li>Added ICC and CIE colorspaces.
</li>