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 version 2 (compressed) and version 3 (uncompressed)
formats that are a superset of the version 1 format. 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.
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.
0 = white (sRGB)
1 = RGB (sRGB)
2 = RGBA (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)
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)
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.
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:
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.
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 raster data
for that page.
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.
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 colorspace 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
colorspace 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_W, CUPS_CSPACE_RGB, CUPS_CSPACE_RGBA, and
CUPS_CSPACE_RGBW
These colorspaces use the sRGB colorspace definition and
whitepoint.
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
colorspace 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 colorspaces map a CIE Lab color value with a D65
whitepoint 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 Decoding: L = L16 / 655.35
a = a16 / 256 - 128
b = b16 / 256 - 128
CUPS_CSPACE_CIEXYZ
These colorspaces map a CIE XYZ color value with a D65
whitepoint 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.