CUPS Raster Format

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

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

Organization of a CUPS Raster File

Figure 1, "Raster Organization", 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.

Each page bitmap is stored as described by the cupsBitsPerColor, cupsBytesPerLine, cupsColorOrder, cupsColorSpace, cupsHeight, and cupsWidth 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 cupsBackSide keyword ("Normal", "ManualTumble", "Rotated", or "Flipped") in the PPD file and the Tumble value ("true" or "false") in the page header. Figure 2, "Page Bitmaps", shows the pixel order for each combination.

Version 1 Raster File Format

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.

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, 0 = printer default
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 0 to 232 - 1, 0 = printer default
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/3 raster files
388-391 Unsigned Integer cupsBitsPerPixel 1 to 32 bits for version 1 raster files
1 to 240 bits for version 2/3 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 = gray (device, typically sRGB-based)
1 = RGB (device, typically sRGB)
2 = RGBA (device, typically sRGB)
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 (sRGB)
18 = sGray (gray using sRGB gamma/white point)
19 = sRGB
20 = AdobeRGB
32 = ICC1 (CIE Lab with hint for 1 color)
33 = ICC2 (CIE Lab with hint for 2 colors)
34 = ICC3 (CIE Lab with hint for 3 colors)
35 = ICC4 (CIE Lab with hint for 4 colors)
36 = ICC5 (CIE Lab with hint for 5 colors)
37 = ICC6 (CIE Lab with hint for 6 colors)
38 = ICC7 (CIE Lab with hint for 7 colors)
39 = ICC8 (CIE Lab with hint for 8 colors)
40 = ICC9 (CIE Lab with hint for 9 colors)
41 = ICCA (CIE Lab with hint for 10 colors)
42 = ICCB (CIE Lab with hint for 11 colors)
43 = ICCC (CIE Lab with hint for 12 colors)
44 = ICCD (CIE Lab with hint for 13 colors)
45 = ICCE (CIE Lab with hint for 14 colors)
46 = ICCF (CIE Lab with hint for 15 colors)
48 = Device1 (DeviceN for 1 color)
49 = Device2 (DeviceN for 2 colors)
50 = Device3 (DeviceN for 3 colors)
51 = Device4 (DeviceN for 4 colors)
52 = Device5 (DeviceN for 5 colors)
53 = Device6 (DeviceN for 6 colors)
54 = Device7 (DeviceN for 7 colors)
55 = Device8 (DeviceN for 8 colors)
56 = Device9 (DeviceN for 9 colors)
57 = DeviceA (DeviceN for 10 colors)
58 = DeviceB (DeviceN for 11 colors)
59 = DeviceC (DeviceN for 12 colors)
60 = DeviceD (DeviceN for 13 colors)
61 = DeviceE (DeviceN for 14 colors)
62 = DeviceF (DeviceN for 15 colors)
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 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.

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 15 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 PackBits-like algorithm. Lines are grouped into an integral number of color values based upon the cupsColorOrder setting:

Table 3: Color Value Sizes
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 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.

For example, the 8x8 24-bit sRGB image shown in Figure 3, "Sample Image", would be encoded as the following 89 octets:

%x00 %x00.FF.FF.FF %x02.FF.FF.00 %x03.FF.FF.FF
%x00 %xFE.FF.FF.00.00.00.FF.FF.FF.00 %x02.FF.FF.FF %x00.00.FF.00 %x00.FF.FF.FF
%x00 %x01.FF.FF.00 %x02.FF.FF.FF %x02.00.FF.00
%x00 %x02.FF.FF.00 %x02.FF.FF.FF %x00.00.FF.00 %x00.FF.FF.FF
%x00 %x00.FF.FF.FF %x02.FF.FF.00 %x03.FF.FF.FF
%x00 %x07.FF.FF.FF
%x01 %x07.FF.00.00

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

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

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)

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

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

The sixth line (%x00) contains 8 white pixels (%x07.FF.FF.FF).

The seventh and eighth lines (%x01) contain 8 red pixels (%x07.FF.00.00).

Version 3 Raster File Format

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.

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.

Pixel Value Coding

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.

CUPS_ORDER_CHUNKED

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 CUPS_CSPACE_RGB 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. Multi-byte pixel values are stored in the native word order, just as for 16-bit color values.

Table 4: Chunked Color Values
Bits 1-color 3-color 4-color 6-color
1 W/W/W/W/W/W/W/W 0RGB/0RGB CMYK/CMYK 00KCMYcm
2 WW/WW/WW/WW 00RRGGBB CCMMYYKK N/A
4 WWWW/WWWW 0000RRRRGGGGBBBB
(multi-byte)
CCCCMMMMYYYYKKKK
(multi-byte)
N/A

CUPS_ORDER_BANDED

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

CUPS_ORDER_PLANAR

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

CUPS_CSPACE_RGBW

This color space provides a dedicated black text channel and uses the sRGB color space definition and white point 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.

CUPS_CSPACE_KCMYcm

When cupsBitsPerColor is 1, 6 color planes are provided - black, cyan, magenta, yellow, light cyan, and light magenta. When cupsBitsPerColor is greater than 1, 4 color planes are provided using the CUPS_CSPACE_KCMY color space instead.

When cupsColorOrder is CUPS_ORDER_CHUNKED, bit 5 corresponds to black and bit 0 corresponds to light magenta. For CUPS_ORDER_BANDED and CUPS_ORDER_PLANAR, each color plane is encoded separately.

CUPS_CSPACE_CIELab and CUPS_CSPACE_ICCn

These color spaces map a CIE Lab color value with a D65 white point to either a 8- or 16-bit per color chunked (CUPS_ORDER_CHUNKED) format; the banded (CUPS_ORDER_BANDED) and planar (CUPS_ORDER_PLANAR) color orders are not supported.

The values are encoded and decoded using the following formulas:

  • 8-bit Encoding:
    L8 = 2.55 * L + 0.5
    a8 = a + 128.5
    b8 = b + 128.5
     
  • 8-bit Decoding:
    L = L8 / 2.55
    a = a8 - 128
    b = b8 - 128
     
  • 16-bit Encoding:
    L16 = 655.35 * L + 0.5
    a16 = 256 * (a + 128) + 0.5
    b16 = 256 * (b + 128) + 0.5
     
  • 16-bit Decoding:
    L = L16 / 655.35
    a = a16 / 256 - 128
    b = b16 / 256 - 128
     

CUPS_CSPACE_CIEXYZ

These color spaces map a CIE XYZ color value with a D65 white point to either a 8- or 16-bit per color chunked (CUPS_ORDER_CHUNKED) format; the banded (CUPS_ORDER_BANDED) and planar (CUPS_ORDER_PLANAR) color orders are not supported.

The values are encoded and decoded using the following formulas:

  • 8-bit Encoding:
    X8 = 231.8181 * X + 0.5
    Y8 = 231.8181 * Y + 0.5
    Z8 = 231.8181 * Z + 0.5
     
  • 8-bit Decoding:
    X = X8 / 231.8181
    Y = Y8 / 231.8181
    Z = Z8 / 231.8181
     
  • 16-bit Encoding:
    X16 = 59577.2727 * X + 0.5
    Y16 = 59577.2727 * Y + 0.5
    Z16 = 59577.2727 * Z + 0.5
     
  • 16-bit Decoding:
    X = X16 / 59577.2727
    Y = Y16 / 59577.2727
    Z = Z16 / 59577.2727
     

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.

Change History

Changes in CUPS 1.4.7

  • Greatly improved the detail and now include an example of the bitmap compression.
  • Added all missing cupsColorSpace values and a separate description of CUPS_CSPACE_RGBW.

Changes in CUPS 1.2.2

  • Added version 3 (uncompressed) format.

Changes in CUPS 1.2.1

  • Added new sections on coding pixel values.
  • Clarified definitions of color spaces.

Changes in CUPS 1.2

  • Bumped raster version to 2
  • Added RGBW color space
  • 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 color spaces.