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.

CUPS 1.0 and 1.1 used a version 1 raster format. CUPS 1.2 introduces a version 2 format that is a superset of the version 1 format. Applications using the CUPS Imaging API (the cupsRaster* functions) can read both formats without code changes.

The registered MIME media type for CUPS raster files is application/vnd.cups-raster.

Version 1 Raster File Format

A version 1 raster file begins with a 32-bit synchronization word: 0x52615374 ("RaSt") for big-endian architectures and 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.

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.

Table 1: CUPS Version 1 Raster Page Device Dictionary
Bytes Type Description Values
0-63 C String MediaClass Media class string
64-127 C String MediaColor Media color string
128-191 C String MediaType Media type string
192-255 C String OutputType Output type string
256-259 Unsigned Integer AdvanceDistance 0 to 232 - 1 points
260-263 Unsigned Integer AdvanceMedia 0 = Never advance roll
1 = Advance roll after file
2 = Advance roll after job
3 = Advance roll after set
4 = Advance roll after page
264-267 Unsigned Integer Collate 0 = do not collate copies
1 = collate copies
268-271 Unsigned Integer CutMedia 0 = Never cut media
1 = Cut roll after file
2 = Cut roll after job
3 = Cut roll after set
4 = Cut roll after page
272-275 Unsigned Integer Duplex 0 = Print single-sided
1 = Print double-sided
276-283 Unsigned Integers (2) HWResolution Horizontal and vertical resolution in dots-per-inch.
284-299 Unsigned Integers (4) ImagingBoundingBox Four integers giving the left, bottom, right, and top positions of the page bounding box in points
300-303 Unsigned Integer InsertSheet 0 = Do not insert separator sheets
1 = Insert separator sheets
304-307 Unsigned Integer Jog 0 = Do no jog pages
1 = Jog pages after file
2 = Jog pages after job
3 = Jog pages after set
308-311 Unsigned Integer LeadingEdge 0 = Top edge is first
1 = Right edge is first
2 = Bottom edge is first
3 = Left edge is first
312-319 Unsigned Integers (2) Margins Left and bottom origin of image in points
320-323 Unsigned Integer ManualFeed 0 = Do not manually feed media
1 = Manually feed media
324-327 Unsigned Integer MediaPosition Input slot position from 0 to N
328-331 Unsigned Integer MediaWeight Media weight in grams per meter squared
332-335 Unsigned Integer MirrorPrint 0 = Do not mirror prints
1 = Mirror prints
336-339 Unsigned Integer NegativePrint 0 = Do not invert prints
1 = Invert prints
340-343 Unsigned Integer NumCopies 1 to 232 - 1
344-347 Unsigned Integer Orientation 0 = Do not rotate page
1 = Rotate page counter-clockwise
2 = Turn page upside down
3 = Rotate page clockwise
348-351 Unsigned Integer OutputFaceUp 0 = Output face down
1 = Output face up
352-359 Unsigned Integers (2) PageSize Width and length in points
360-363 Unsigned Integer Separations 0 = Print composite image
1 = Print color separations
364-367 Unsigned Integer TraySwitch 0 = Do not change trays if selected tray is empty
1 = Change trays if selected tray is empty
368-371 Unsigned Integer Tumble 0 = Do not rotate even pages when duplexing
1 = Rotate even pages when duplexing
372-375 Unsigned Integer cupsWidth Width of page image in pixels
376-379 Unsigned Integer cupsHeight Height of page image in pixels
380-383 Unsigned Integer cupsMediaType Driver-specific 0 to 232 - 1
384-387 Unsigned Integer cupsBitsPerColor 1, 2, 4, 8 bits for version 1 raster files
1, 2, 4, 8, and 16 bits for version 2 raster files
388-391 Unsigned Integer cupsBitsPerPixel 1 to 32 bits for version 1 raster files
1 to 64 bits for version 2 raster files
392-395 Unsigned Integer cupsBytesPerLine 1 to 232 - 1 bytes
396-399 Unsigned Integer cupsColorOrder 0 = chunky pixels (CMYK CMYK CMYK)
1 = banded pixels (CCC MMM YYY KKK)
2 = planar pixels (CCC... MMM... YYY... KKK...)
400-403 Unsigned Integer cupsColorSpace 0 = white
1 = RGB
2 = RGBA
3 = black
4 = CMY
5 = YMC
6 = CMYK
7 = YMCK
8 = KCMY
9 = KCMYcm
10 = GMCK
11 = GMCS
12 = WHITE
13 = GOLD
14 = SILVER
15 = CIE XYZ
16 = CIE Lab
17 = RGBW
32 = ICC1
33 = ICC2
34 = ICC3
35 = ICC4
36 = ICC5
37 = ICC6
38 = ICC7
39 = ICC8
40 = ICC9
41 = ICCA (10)
42 = ICCB (11)
43 = ICCC (12)
44 = ICCD (13)
45 = ICCE (14)
46 = ICCF (15)
404-407 Unsigned Integer cupsCompression Driver-specific 0 to 232 - 1
408-411 Unsigned Integer cupsRowCount Driver-specific 0 to 232 - 1
412-415 Unsigned Integer cupsRowFeed Driver-specific 0 to 232 - 1
416-419 Unsigned Integer cupsRowStep Driver-specific 0 to 232 - 1

Version 2 Raster File Format

A version 2 raster file begins with a 32-bit synchronization word: 0x52615332 ("RaS2") for big-endian architectures and 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.

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.

Table 2: CUPS Version 2 Raster Page Device Dictionary
Bytes Type Description Values
0-419 Version 1 header data See Table 1
420-423 Unsigned Integer cupsNumColors 1 to 6 colors
424-427 IEEE Single Precision cupsBorderlessScalingFactor 0.0 or 1.0 or greater
428-435 IEEE Single Precision (2) cupsPageSize Width and length in points
436-451 IEEE Single Precision (4) cupsImagingBBox Four floating point numbers giving the left, bottom, right, and top positions of the page bounding box in points
452-515 Unsigned Integers (16) cupsInteger 16 driver-defined integer values
516-579 IEEE Single Precision (16) cupsReal 16 driver-defined floating point values
580-1603 C Strings (16x64) cupsString 16 driver-defined strings
1604-1667 C String cupsMarkerType Ink/toner type string
1668-1731 C String cupsRenderingIntent Color rendering intent string
1732-1795 C String cupsPageSizeName Page size name/keyword string from PPD

Compressed Raster Data Format

The version 2 raster data is compressed using a modified TIFF packbits algorithm. Lines are grouped into an integral number of color values based upon the cupsColorOrder setting:

cupsColorOrder Bytes per color value
0 (chunky) (cupsBitsPerPixel + 7) / 8
1 (banded) (cupsBitsPerColor + 7) / 8
2 (planar) (cupsBitsPerColor + 7) / 8

Each line of raster data begins with a repetition count from 1 to 256 that is encoded using a single byte of "count - 1".

After the repetition count, whole color values for that line are run-length encoded using the TIFF packbits algorithm. 1 to 128 repeated colors are encoded using an initial byte of "count - 1" followed by the color value byte(s). 2 to 128 non-repeating colors are encoded using an initial byte of "257 - count" followed by the color value bytes.

Change History

Changes in CUPS 1.2

Changes in CUPS 1.1.19