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
.
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.
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 |
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.
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 |
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.