<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML> <!-- SECTION: Specifications --> <HEAD> <TITLE>CUPS Raster Format</TITLE> <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css"> </HEAD> <BODY> <H1 CLASS="title">CUPS Raster Format</H1> <P>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.</P> <P>CUPS 1.0 and 1.1 used a version 1 raster format. CUPS 1.2 introduced 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.</P> <P>The registered MIME media type for CUPS raster files is <CODE>application/vnd.cups-raster</CODE>.</P> <H2 CLASS="title"><A NAME="V1">Version 1 Raster File Format</A></H2> <P>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.</P> <P>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.</P> <DIV CLASS="table"><TABLE SUMMARY="CUPS Version 1 Raster Page Device Dictionary"> <CAPTION><A NAME="TABLE1">Table 1: CUPS Version 1 Raster Page Device Dictionary</A></CAPTION> <THEAD> <TR> <TH>Bytes</TH> <TH>Type</TH> <TH>Description</TH> <TH>Values</TH> </TR> </THEAD> <TBODY> <TR> <TD>0-63</TD> <TD>C String</TD> <TD>MediaClass</TD> <TD>Media class string</TD> </TR> <TR> <TD>64-127</TD> <TD>C String</TD> <TD>MediaColor</TD> <TD>Media color string</TD> </TR> <TR> <TD>128-191</TD> <TD>C String</TD> <TD>MediaType</TD> <TD>Media type string</TD> </TR> <TR> <TD>192-255</TD> <TD>C String</TD> <TD>OutputType</TD> <TD>Output type string</TD> </TR> <TR> <TD>256-259</TD> <TD>Unsigned Integer</TD> <TD>AdvanceDistance</TD> <TD>0 to 2<SUP>32</SUP> - 1 points</TD> </TR> <TR> <TD>260-263</TD> <TD>Unsigned Integer</TD> <TD>AdvanceMedia</TD> <TD>0 = Never advance roll<BR> 1 = Advance roll after file<BR> 2 = Advance roll after job<BR> 3 = Advance roll after set<BR> 4 = Advance roll after page</TD> </TR> <TR> <TD>264-267</TD> <TD>Unsigned Integer</TD> <TD>Collate</TD> <TD>0 = do not collate copies<BR> 1 = collate copies</TD> </TR> <TR> <TD>268-271</TD> <TD>Unsigned Integer</TD> <TD>CutMedia</TD> <TD>0 = Never cut media<BR> 1 = Cut roll after file<BR> 2 = Cut roll after job<BR> 3 = Cut roll after set<BR> 4 = Cut roll after page</TD> </TR> <TR> <TD>272-275</TD> <TD>Unsigned Integer</TD> <TD>Duplex</TD> <TD>0 = Print single-sided<BR> 1 = Print double-sided</TD> </TR> <TR> <TD>276-283</TD> <TD>Unsigned Integers (2)</TD> <TD>HWResolution</TD> <TD>Horizontal and vertical resolution in dots-per-inch.</TD> </TR> <TR> <TD>284-299</TD> <TD>Unsigned Integers (4)</TD> <TD>ImagingBoundingBox</TD> <TD>Four integers giving the left, bottom, right, and top positions of the page bounding box in points</TD> </TR> <TR> <TD>300-303</TD> <TD>Unsigned Integer</TD> <TD>InsertSheet</TD> <TD>0 = Do not insert separator sheets<BR> 1 = Insert separator sheets</TD> </TR> <TR> <TD>304-307</TD> <TD>Unsigned Integer</TD> <TD>Jog</TD> <TD>0 = Do no jog pages<BR> 1 = Jog pages after file<BR> 2 = Jog pages after job<BR> 3 = Jog pages after set</TD> </TR> <TR> <TD>308-311</TD> <TD>Unsigned Integer</TD> <TD>LeadingEdge</TD> <TD>0 = Top edge is first<BR> 1 = Right edge is first<BR> 2 = Bottom edge is first<BR> 3 = Left edge is first</TD> </TR> <TR> <TD>312-319</TD> <TD>Unsigned Integers (2)</TD> <TD>Margins</TD> <TD>Left and bottom origin of image in points</TD> </TR> <TR> <TD>320-323</TD> <TD>Unsigned Integer</TD> <TD>ManualFeed</TD> <TD>0 = Do not manually feed media<BR> 1 = Manually feed media</TD> </TR> <TR> <TD>324-327</TD> <TD>Unsigned Integer</TD> <TD>MediaPosition</TD> <TD>Input slot position from 0 to N</TD> </TR> <TR> <TD>328-331</TD> <TD>Unsigned Integer</TD> <TD>MediaWeight</TD> <TD>Media weight in grams per meter squared</TD> </TR> <TR> <TD>332-335</TD> <TD>Unsigned Integer</TD> <TD>MirrorPrint</TD> <TD>0 = Do not mirror prints<BR> 1 = Mirror prints</TD> </TR> <TR> <TD>336-339</TD> <TD>Unsigned Integer</TD> <TD>NegativePrint</TD> <TD>0 = Do not invert prints<BR> 1 = Invert prints</TD> </TR> <TR> <TD>340-343</TD> <TD>Unsigned Integer</TD> <TD>NumCopies</TD> <TD>1 to 2<SUP>32</SUP> - 1</TD> </TR> <TR> <TD>344-347</TD> <TD>Unsigned Integer</TD> <TD>Orientation</TD> <TD>0 = Do not rotate page<BR> 1 = Rotate page counter-clockwise<BR> 2 = Turn page upside down<BR> 3 = Rotate page clockwise</TD> </TR> <TR> <TD>348-351</TD> <TD>Unsigned Integer</TD> <TD>OutputFaceUp</TD> <TD>0 = Output face down<BR> 1 = Output face up</TD> </TR> <TR> <TD>352-359</TD> <TD>Unsigned Integers (2)</TD> <TD>PageSize</TD> <TD>Width and length in points</TD> </TR> <TR> <TD>360-363</TD> <TD>Unsigned Integer</TD> <TD>Separations</TD> <TD>0 = Print composite image<BR> 1 = Print color separations</TD> </TR> <TR> <TD>364-367</TD> <TD>Unsigned Integer</TD> <TD>TraySwitch</TD> <TD>0 = Do not change trays if selected tray is empty<BR> 1 = Change trays if selected tray is empty</TD> </TR> <TR> <TD>368-371</TD> <TD>Unsigned Integer</TD> <TD>Tumble</TD> <TD>0 = Do not rotate even pages when duplexing<BR> 1 = Rotate even pages when duplexing</TD> </TR> <TR> <TD>372-375</TD> <TD>Unsigned Integer</TD> <TD>cupsWidth</TD> <TD>Width of page image in pixels</TD> </TR> <TR> <TD>376-379</TD> <TD>Unsigned Integer</TD> <TD>cupsHeight</TD> <TD>Height of page image in pixels</TD> </TR> <TR> <TD>380-383</TD> <TD>Unsigned Integer</TD> <TD>cupsMediaType</TD> <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD> </TR> <TR> <TD>384-387</TD> <TD>Unsigned Integer</TD> <TD>cupsBitsPerColor</TD> <TD>1, 2, 4, 8 bits for version 1 raster files<BR> 1, 2, 4, 8, and 16 bits for version 2 raster files</TD> </TR> <TR> <TD>388-391</TD> <TD>Unsigned Integer</TD> <TD>cupsBitsPerPixel</TD> <TD>1 to 32 bits for version 1 raster files<BR> 1 to 64 bits for version 2 raster files</TD> </TR> <TR> <TD>392-395</TD> <TD>Unsigned Integer</TD> <TD>cupsBytesPerLine</TD> <TD>1 to 2<SUP>32</SUP> - 1 bytes</TD> </TR> <TR> <TD>396-399</TD> <TD>Unsigned Integer</TD> <TD>cupsColorOrder</TD> <TD>0 = chunky pixels (CMYK CMYK CMYK)<BR> 1 = banded pixels (CCC MMM YYY KKK)<BR> 2 = planar pixels (CCC... MMM... YYY... KKK...)</TD> </TR> <TR> <TD>400-403</TD> <TD>Unsigned Integer</TD> <TD>cupsColorSpace</TD> <TD>0 = white (sRGB)<BR> 1 = RGB (sRGB)<BR> 2 = RGBA (sRGB)<BR> 3 = black<BR> 4 = CMY<BR> 5 = YMC<BR> 6 = CMYK<BR> 7 = YMCK<BR> 8 = KCMY<BR> 9 = KCMYcm<BR> 10 = GMCK<BR> 11 = GMCS<BR> 12 = WHITE<BR> 13 = GOLD<BR> 14 = SILVER<BR> 15 = CIE XYZ<BR> 16 = CIE Lab<BR> 17 = RGBW (sRGB)<BR> 32 = ICC1 (CIE Lab with hint for 1 color)<BR> 33 = ICC2 (CIE Lab with hint for 2 colors)<BR> 34 = ICC3 (CIE Lab with hint for 3 colors)<BR> 35 = ICC4 (CIE Lab with hint for 4 colors)<BR> 36 = ICC5 (CIE Lab with hint for 5 colors)<BR> 37 = ICC6 (CIE Lab with hint for 6 colors)<BR> 38 = ICC7 (CIE Lab with hint for 7 colors)<BR> 39 = ICC8 (CIE Lab with hint for 8 colors)<BR> 40 = ICC9 (CIE Lab with hint for 9 colors)<BR> 41 = ICCA (CIE Lab with hint for 10 colors)<BR> 42 = ICCB (CIE Lab with hint for 11 colors)<BR> 43 = ICCC (CIE Lab with hint for 12 colors)<BR> 44 = ICCD (CIE Lab with hint for 13 colors)<BR> 45 = ICCE (CIE Lab with hint for 14 colors)<BR> 46 = ICCF (CIE Lab with hint for 15 colors)<BR> </TD> </TR> <TR> <TD>404-407</TD> <TD>Unsigned Integer</TD> <TD>cupsCompression</TD> <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD> </TR> <TR> <TD>408-411</TD> <TD>Unsigned Integer</TD> <TD>cupsRowCount</TD> <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD> </TR> <TR> <TD>412-415</TD> <TD>Unsigned Integer</TD> <TD>cupsRowFeed</TD> <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD> </TR> <TR> <TD>416-419</TD> <TD>Unsigned Integer</TD> <TD>cupsRowStep</TD> <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD> </TR> </TBODY> </TABLE></DIV> <H2 CLASS="title"><A NAME="V2">Version 2 Raster File Format</A></H2> <P>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.</P> <P>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.</P> <DIV CLASS="table"><TABLE SUMMARY="CUPS Version 2 Raster Page Device Dictionary"> <CAPTION><A NAME="TABLE2">Table 2: CUPS Version 2 Raster Page Device Dictionary</A></CAPTION> <THEAD> <TR> <TH>Bytes</TH> <TH>Type</TH> <TH>Description</TH> <TH>Values</TH> </TR> </THEAD> <TBODY> <TR> <TD>0-419</TD> <TD>Version 1 header data</TD> <TD>See Table 1</TD> </TR> <TR> <TD>420-423</TD> <TD>Unsigned Integer</TD> <TD>cupsNumColors</TD> <TD>1 to 6 colors</TD> </TR> <TR> <TD>424-427</TD> <TD>IEEE Single Precision</TD> <TD>cupsBorderlessScalingFactor</TD> <TD>0.0 or 1.0 or greater</TD> </TR> <TR> <TD>428-435</TD> <TD>IEEE Single Precision (2)</TD> <TD>cupsPageSize</TD> <TD>Width and length in points</TD> </TR> <TR> <TD>436-451</TD> <TD>IEEE Single Precision (4)</TD> <TD>cupsImagingBBox</TD> <TD>Four floating point numbers giving the left, bottom, right, and top positions of the page bounding box in points</TD> </TR> <TR> <TD>452-515</TD> <TD>Unsigned Integers (16)</TD> <TD>cupsInteger</TD> <TD>16 driver-defined integer values</TD> </TR> <TR> <TD>516-579</TD> <TD>IEEE Single Precision (16)</TD> <TD>cupsReal</TD> <TD>16 driver-defined floating point values</TD> </TR> <TR> <TD>580-1603</TD> <TD>C Strings (16x64)</TD> <TD>cupsString</TD> <TD>16 driver-defined strings</TD> </TR> <TR> <TD>1604-1667</TD> <TD>C String</TD> <TD>cupsMarkerType</TD> <TD>Ink/toner type string</TD> </TR> <TR> <TD>1668-1731</TD> <TD>C String</TD> <TD>cupsRenderingIntent</TD> <TD>Color rendering intent string</TD> </TR> <TR> <TD>1732-1795</TD> <TD>C String</TD> <TD>cupsPageSizeName</TD> <TD>Page size name/keyword string from PPD</TD> </TR> </TBODY> </TABLE></DIV> <H3><A NAME="COMPRESSION">Compressed Raster Data Format</A></H3> <P>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 <CODE>cupsColorOrder</CODE> setting:</P> <DIV CLASS="table"><TABLE SUMMARY="Color Value Sizes"> <CAPTION><A NAME="TABLE3">Table 3: Color Value Sizes</A></CAPTION> <TR> <TH>cupsColorOrder</TH> <TH>Bytes per color value</TH> </TR> <TR> <TD>0 (chunky)</TD> <TD>(<CODE>cupsBitsPerPixel</CODE> + 7) / 8</TD> </TR> <TR> <TD>1 (banded)</TD> <TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD> </TR> <TR> <TD>2 (planar)</TD> <TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD> </TR> </TABLE></DIV> <P>Each line of raster data begins with a repetition count from 1 to 256 that is encoded using a single byte of "count - 1".</P> <P>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.</P> <H2 CLASS="title"><A NAME="V3">Version 3 Raster File Format</A></H2> <P>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.</P> <P>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.</P> <H2 CLASS="title"><A NAME="ENCODING">Pixel Value Coding</A></H2> <P>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.</P> <H3>CUPS_ORDER_CHUNKED</H3> <P>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 <CODE>CUPS_CSPACE_RGB</CODE> 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. <I>Multi-byte pixel values are stored in the native word order, just as for 16-bit color values.</I></P> <DIV CLASS="table"><TABLE SUMMARY="Chunked Color Values"> <CAPTION><A NAME="TABLE4">Table 4: Chunked Color Values</A></CAPTION> <THEAD> <TR> <TH>Bits</TH> <TH>1-color</TH> <TH>3-color</TH> <TH>4-color</TH> <TH>6-color</TH> </TR> </THEAD> <TBODY> <TR> <TD>1</TD> <TD>W/W/W/W/W/W/W/W</TD> <TD>0RGB/0RGB</TD> <TD>CMYK/CMYK</TD> <TD>00KCMYcm</TD> </TR> <TR> <TD>2</TD> <TD>WW/WW/WW/WW</TD> <TD>00RRGGBB</TD> <TD>CCMMYYKK</TD> <TD>N/A</TD> </TR> <TR> <TD>4</TD> <TD>WWWW/WWWW</TD> <TD>0000RRRRGGGGBBBB<BR> <I>(multi-byte)</I></TD> <TD>CCCCMMMMYYYYKKKK<BR> <I>(multi-byte)</I></TD> <TD>N/A</TD> </TR> </TBODY> </TABLE></DIV> <H3>CUPS_ORDER_BANDED</H3> <P>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 <CODE>CUPS_CSPACE_CMYK</CODE> 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.</P> <H3>CUPS_ORDER_PLANAR</H3> <P>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 <CODE>CUPS_CSPACE_CMYK</CODE> 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.</P> <H3>CUPS_CSPACE_W, CUPS_CSPACE_RGB, CUPS_CSPACE_RGBA, and CUPS_CSPACE_RGBW</H3> <P>These colorspaces use the sRGB colorspace definition and whitepoint.</P> <H3>CUPS_CSPACE_KCMYcm</H3> <P>When <CODE>cupsBitsPerColor</CODE> is 1, 6 color planes are provided - black, cyan, magenta, yellow, light cyan, and light magenta. When <CODE>cupsBitsPerColor</CODE> is greater than 1, 4 color planes are provided using the <CODE>CUPS_CSPACE_KCMY</CODE> colorspace instead.</P> <P>When <CODE>cupsColorOrder</CODE> is <CODE>CUPS_ORDER_CHUNKED</CODE>, bit 5 corresponds to black and bit 0 corresponds to light magenta. For <CODE>CUPS_ORDER_BANDED</CODE> and <CODE>CUPS_ORDER_PLANAR</CODE>, each color plane is encoded separately.</P> <H3>CUPS_CSPACE_CIELab and CUPS_CSPACE_ICCn</H3> <P>These colorspaces map a CIE Lab color value with a D65 whitepoint to either a 8- or 16-bit per color chunked (<CODE>CUPS_ORDER_CHUNKED</CODE>) format; the banded (<CODE>CUPS_ORDER_BANDED</CODE>) and planar (<CODE>CUPS_ORDER_PLANAR</CODE>) color orders are not supported.</P> <P>The values are encoded and decoded using the following formulas:</P> <UL> <LI>8-bit Encoding:<BR> <I>L8 = 2.55 * L + 0.5<BR> a8 = a + 128.5<BR> b8 = b + 128.5<BR> </I></LI> <LI>8-bit Decoding:<BR> <I>L = L8 / 2.55<BR> a = a8 - 128<BR> b = b8 - 128<BR> </I></LI> <LI>16-bit Encoding:<BR> <I>L16 = 655.35 * L + 0.5<BR> a16 = 256 * (a + 128) + 0.5<BR> b16 = 256 * (b + 128) + 0.5<BR> </I></LI> <LI>16-bit Decoding:<BR> <I>L = L16 / 655.35<BR> a = a16 / 256 - 128<BR> b = b16 / 256 - 128<BR> </I></LI> </UL> <H3>CUPS_CSPACE_CIEXYZ</H3> <P>These colorspaces map a CIE XYZ color value with a D65 whitepoint to either a 8- or 16-bit per color chunked (<CODE>CUPS_ORDER_CHUNKED</CODE>) format; the banded (<CODE>CUPS_ORDER_BANDED</CODE>) and planar (<CODE>CUPS_ORDER_PLANAR</CODE>) color orders are not supported.</P> <P>The values are encoded and decoded using the following formulas:</P> <UL> <LI>8-bit Encoding:<BR> <I>X8 = 231.8181 * X + 0.5<BR> Y8 = 231.8181 * Y + 0.5<BR> Z8 = 231.8181 * Z + 0.5<BR> </I></LI> <LI>8-bit Decoding:<BR> <I>X = X8 / 231.8181<BR> Y = Y8 / 231.8181<BR> Z = Z8 / 231.8181<BR> </I></LI> <LI>16-bit Encoding:<BR> <I>X16 = 59577.2727 * X + 0.5<BR> Y16 = 59577.2727 * Y + 0.5<BR> Z16 = 59577.2727 * Z + 0.5<BR> </I></LI> <LI>16-bit Decoding:<BR> <I>X = X16 / 59577.2727<BR> Y = Y16 / 59577.2727<BR> Z = Z16 / 59577.2727<BR> </I></LI> </UL> <P>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.</P> <H2 CLASS="title"><A NAME="HISTORY">Change History</A></H2> <H3>Changes in CUPS 1.2.2</H3> <ul> <li>Added version 3 (uncompressed) format.</li> </ul> <H3>Changes in CUPS 1.2.1</H3> <ul> <li>Added new sections on coding pixel values.</li> <li>Clarified definitions of color spaces.</li> </ul> <H3>Changes in CUPS 1.2</H3> <ul> <li>Bumped raster version to 2</li> <li>Added RGBW colorspace</li> <li>Added 16 bit per color support</li> <li>Added cupsNumColors, cupsBorderlessScalingFactor, cupsPageSize, cupsImagingBBox, cupsInteger, cupsReal, cupsString, cupsMarkerType, cupsRenderingIntent, and cupsPageSizeName attributes to the page device dictionary</li> <li>Added raster data compression</li> <li>Added data type column to device dictionary documentation.</li> </ul> <h3>Changes in CUPS 1.1.19</h3> <ul> <li>Added ICC and CIE colorspaces.</li> </ul> </BODY> </HTML>