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

- Bumped raster version to 2
- Added RGBW colorspace
- Added 16 bit per color support
- Added cupsNumColors, cupsBorderlessScalingFactor, cupsPageSize, cupsImagingBBox, cupsInteger, cupsReal, cupsString, cupsMarkerType, cupsRenderingIntent, and cupsPageSizeName attributes to the page device dictionary
- Added raster data compression
- Added data type column to device dictionary documentation.

### Changes in CUPS 1.1.19

- Added ICC and CIE colorspaces.