[thirdparty/cups.git] / doc / help / spec-raster.html

<HTML>
<!-- SECTION: Specifications -->
<HEAD>
	<TITLE>CUPS Raster Format</TITLE>
	<LINK REL="STYLESHEET" TYPE="test/css" HREF="../cups.css">
</HEAD>
<BODY>

<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
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.</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="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>
	&nbsp;</I></LI>

	<LI>8-bit Decoding:<BR>
	<I>L = L8 / 2.55<BR>
	a = a8 - 128<BR>
	b = b8 - 128<BR>
	&nbsp;</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>
	&nbsp;</I></LI>

	<LI>16-bit Decoding:<BR>
	<I>L = L16 / 655.35<BR>
	a = a16 / 256 - 128<BR>
	b = b16 / 256 - 128<BR>
	&nbsp;</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>
	&nbsp;</I></LI>

	<LI>8-bit Decoding:<BR>
	<I>X = X8 / 231.8181<BR>
	Y = Y8 / 231.8181<BR>
	Z = Z8 / 231.8181<BR>
	&nbsp;</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>
	&nbsp;</I></LI>

	<LI>16-bit Decoding:<BR>
	<I>X = X16 / 59577.2727<BR>
	Y = Y16 / 59577.2727<BR>
	Z = Z16 / 59577.2727<BR>
	&nbsp;</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.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>
Commit	Line	Data
4744bd90	1	<HTML>
	2	<!-- SECTION: Specifications -->
	3	<HEAD>
	4	<TITLE>CUPS Raster Format</TITLE>
f301802f	5	<LINK REL="STYLESHEET" TYPE="test/css" HREF="../cups.css">
4744bd90	6	</HEAD>
	7	<BODY>
	8
	9	<P>CUPS raster files are device-dependent raster image files that
	10	contain a PostScript page device dictionary and device-dependent
	11	raster imagery for each page in the document. These files are
	12	used to transfer raster data from the PostScript and image file
	13	RIPs to device-dependent filters that convert the raster data to
	14	a printable format.</P>
	15
	16	<P>CUPS 1.0 and 1.1 used a version 1 raster format. CUPS 1.2
	17	introduces a version 2 format that is a superset of the version 1
	18	format. Applications using the CUPS Imaging API (the cupsRaster*
	19	functions) can read both formats without code changes.</P>
	20
	21	<P>The registered MIME media type for CUPS raster files is
	22	<CODE>application/vnd.cups-raster</CODE>.</P>
	23
	24
	25	<H2 CLASS="title"><A NAME="V1">Version 1 Raster File Format</A></H2>
	26
	27	<P>A version 1 raster file begins with a 32-bit synchronization
	28	word: 0x52615374 ("RaSt") for big-endian architectures and
	29	0x74536152 ("tSaR") for little-endian architectures. The writer
	30	of the raster file will use the native word order, and the reader
	31	is responsible for detecting a reversed word order file and
	32	swapping bytes as needed. The CUPS Imaging API raster functions
	33	perform this function automatically.</P>
	34
	35	<P>Following the synchronization word are a series of raster
	36	pages. Each page starts with a page device dictionary header and
	37	is followed immediately by the (uncompressed, raw) raster data
	38	for that page.</P>
	39
	40	<DIV CLASS="table"><TABLE SUMMARY="CUPS Version 1 Raster Page Device Dictionary">
f301802f	41	<CAPTION><A NAME="TABLE1">Table 1: CUPS Version 1 Raster Page Device Dictionary</A></CAPTION>
f301802f	42	<THEAD>
4744bd90	43	<TR>
	44	<TH>Bytes</TH>
	45	<TH>Type</TH>
	46	<TH>Description</TH>
	47	<TH>Values</TH>
	48	</TR>
f301802f	49	</THEAD>
f301802f	50	<TBODY>
4744bd90	51	<TR>
	52	<TD>0-63</TD>
	53	<TD>C String</TD>
	54	<TD>MediaClass</TD>
	55	<TD>Media class string</TD>
	56	</TR>
	57	<TR>
	58	<TD>64-127</TD>
	59	<TD>C String</TD>
	60	<TD>MediaColor</TD>
	61	<TD>Media color string</TD>
	62	</TR>
	63	<TR>
	64	<TD>128-191</TD>
	65	<TD>C String</TD>
	66	<TD>MediaType</TD>
	67	<TD>Media type string</TD>
	68	</TR>
	69	<TR>
	70	<TD>192-255</TD>
	71	<TD>C String</TD>
	72	<TD>OutputType</TD>
	73	<TD>Output type string</TD>
	74	</TR>
	75	<TR>
	76	<TD>256-259</TD>
	77	<TD>Unsigned Integer</TD>
	78	<TD>AdvanceDistance</TD>
	79	<TD>0 to 2<SUP>32</SUP> - 1 points</TD>
	80	</TR>
	81	<TR>
	82	<TD>260-263</TD>
	83	<TD>Unsigned Integer</TD>
	84	<TD>AdvanceMedia</TD>
	85	<TD>0 = Never advance roll<BR>
	86	1 = Advance roll after file<BR>
	87	2 = Advance roll after job<BR>
	88	3 = Advance roll after set<BR>
	89	4 = Advance roll after page</TD>
	90	</TR>
	91	<TR>
	92	<TD>264-267</TD>
	93	<TD>Unsigned Integer</TD>
	94	<TD>Collate</TD>
	95	<TD>0 = do not collate copies<BR>
	96	1 = collate copies</TD>
	97	</TR>
	98	<TR>
	99	<TD>268-271</TD>
	100	<TD>Unsigned Integer</TD>
	101	<TD>CutMedia</TD>
	102	<TD>0 = Never cut media<BR>
	103	1 = Cut roll after file<BR>
	104	2 = Cut roll after job<BR>
	105	3 = Cut roll after set<BR>
	106	4 = Cut roll after page</TD>
	107	</TR>
	108	<TR>
	109	<TD>272-275</TD>
	110	<TD>Unsigned Integer</TD>
	111	<TD>Duplex</TD>
	112	<TD>0 = Print single-sided<BR>
	113	1 = Print double-sided</TD>
	114	</TR>
115	<TR>
116	<TD>276-283</TD>
117	<TD>Unsigned Integers (2)</TD>
118	<TD>HWResolution</TD>
119	<TD>Horizontal and vertical resolution in dots-per-inch.</TD>
120	</TR>
121	<TR>
122	<TD>284-299</TD>
123	<TD>Unsigned Integers (4)</TD>
124	<TD>ImagingBoundingBox</TD>
125	<TD>Four integers giving the left, bottom, right, and top positions
126	of the page bounding box in points</TD>
127	</TR>
128	<TR>
129	<TD>300-303</TD>
130	<TD>Unsigned Integer</TD>
131	<TD>InsertSheet</TD>
132	<TD>0 = Do not insert separator sheets<BR>
133	1 = Insert separator sheets</TD>
134	</TR>
135	<TR>
136	<TD>304-307</TD>
137	<TD>Unsigned Integer</TD>
138	<TD>Jog</TD>
139	<TD>0 = Do no jog pages<BR>
140	1 = Jog pages after file<BR>
141	2 = Jog pages after job<BR>
142	3 = Jog pages after set</TD>
143	</TR>
144	<TR>
145	<TD>308-311</TD>
146	<TD>Unsigned Integer</TD>
147	<TD>LeadingEdge</TD>
148	<TD>0 = Top edge is first<BR>
149	1 = Right edge is first<BR>
150	2 = Bottom edge is first<BR>
151	3 = Left edge is first</TD>
152	</TR>
153	<TR>
154	<TD>312-319</TD>
155	<TD>Unsigned Integers (2)</TD>
156	<TD>Margins</TD>
157	<TD>Left and bottom origin of image in points</TD>
158	</TR>
159	<TR>
160	<TD>320-323</TD>
161	<TD>Unsigned Integer</TD>
162	<TD>ManualFeed</TD>
163	<TD>0 = Do not manually feed media<BR>
164	1 = Manually feed media</TD>
165	</TR>
166	<TR>
167	<TD>324-327</TD>
168	<TD>Unsigned Integer</TD>
169	<TD>MediaPosition</TD>
170	<TD>Input slot position from 0 to N</TD>
171	</TR>
172	<TR>
173	<TD>328-331</TD>
174	<TD>Unsigned Integer</TD>
175	<TD>MediaWeight</TD>
176	<TD>Media weight in grams per meter squared</TD>
177	</TR>
178	<TR>
179	<TD>332-335</TD>
180	<TD>Unsigned Integer</TD>
181	<TD>MirrorPrint</TD>
182	<TD>0 = Do not mirror prints<BR>
183	1 = Mirror prints</TD>
184	</TR>
185	<TR>
186	<TD>336-339</TD>
187	<TD>Unsigned Integer</TD>
188	<TD>NegativePrint</TD>
189	<TD>0 = Do not invert prints<BR>
190	1 = Invert prints</TD>
191	</TR>
192	<TR>
193	<TD>340-343</TD>
194	<TD>Unsigned Integer</TD>
195	<TD>NumCopies</TD>
196	<TD>1 to 2<SUP>32</SUP> - 1</TD>
197	</TR>
198	<TR>
199	<TD>344-347</TD>
200	<TD>Unsigned Integer</TD>
201	<TD>Orientation</TD>
202	<TD>0 = Do not rotate page<BR>
203	1 = Rotate page counter-clockwise<BR>
204	2 = Turn page upside down<BR>
205	3 = Rotate page clockwise</TD>
206	</TR>
207	<TR>
208	<TD>348-351</TD>
209	<TD>Unsigned Integer</TD>
210	<TD>OutputFaceUp</TD>
211	<TD>0 = Output face down<BR>
212	1 = Output face up</TD>
213	</TR>
214	<TR>
215	<TD>352-359</TD>
216	<TD>Unsigned Integers (2)</TD>
217	<TD>PageSize</TD>
218	<TD>Width and length in points</TD>
219	</TR>
220	<TR>
221	<TD>360-363</TD>
222	<TD>Unsigned Integer</TD>
223	<TD>Separations</TD>
224	<TD>0 = Print composite image<BR>
225	1 = Print color separations</TD>
226	</TR>
227	<TR>
228	<TD>364-367</TD>
229	<TD>Unsigned Integer</TD>
230	<TD>TraySwitch</TD>
231	<TD>0 = Do not change trays if selected tray is empty<BR>
232	1 = Change trays if selected tray is empty</TD>
233	</TR>
234	<TR>
235	<TD>368-371</TD>
236	<TD>Unsigned Integer</TD>
237	<TD>Tumble</TD>
238	<TD>0 = Do not rotate even pages when duplexing<BR>
239	1 = Rotate even pages when duplexing</TD>
240	</TR>
241	<TR>
242	<TD>372-375</TD>
243	<TD>Unsigned Integer</TD>
244	<TD>cupsWidth</TD>
245	<TD>Width of page image in pixels</TD>
246	</TR>
247	<TR>
248	<TD>376-379</TD>
249	<TD>Unsigned Integer</TD>
250	<TD>cupsHeight</TD>
251	<TD>Height of page image in pixels</TD>
252	</TR>
253	<TR>
254	<TD>380-383</TD>
255	<TD>Unsigned Integer</TD>
256	<TD>cupsMediaType</TD>
257	<TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
258	</TR>
259	<TR>
260	<TD>384-387</TD>
261	<TD>Unsigned Integer</TD>
262	<TD>cupsBitsPerColor</TD>
263	<TD>1, 2, 4, 8 bits for version 1 raster files<BR>
264	1, 2, 4, 8, and 16 bits for version 2 raster files</TD>
265	</TR>
266	<TR>
267	<TD>388-391</TD>
268	<TD>Unsigned Integer</TD>
269	<TD>cupsBitsPerPixel</TD>
270	<TD>1 to 32 bits for version 1 raster files<BR>
271	1 to 64 bits for version 2 raster files</TD>
272	</TR>
273	<TR>
274	<TD>392-395</TD>
275	<TD>Unsigned Integer</TD>
276	<TD>cupsBytesPerLine</TD>
277	<TD>1 to 2<SUP>32</SUP> - 1 bytes</TD>
278	</TR>
279	<TR>
280	<TD>396-399</TD>
281	<TD>Unsigned Integer</TD>
282	<TD>cupsColorOrder</TD>
283	<TD>0 = chunky pixels (CMYK CMYK CMYK)<BR>
284	1 = banded pixels (CCC MMM YYY KKK)<BR>
285	2 = planar pixels (CCC... MMM... YYY... KKK...)</TD>
286	</TR>
287	<TR>
288	<TD>400-403</TD>
289	<TD>Unsigned Integer</TD>
290	<TD>cupsColorSpace</TD>
f301802f	291	<TD>0 = white (sRGB)<BR>
	292	1 = RGB (sRGB)<BR>
	293	2 = RGBA (sRGB)<BR>
4744bd90	294	3 = black<BR>
	295	4 = CMY<BR>
	296	5 = YMC<BR>
	297	6 = CMYK<BR>
	298	7 = YMCK<BR>
	299	8 = KCMY<BR>
	300	9 = KCMYcm<BR>
	301	10 = GMCK<BR>
	302	11 = GMCS<BR>
	303	12 = WHITE<BR>
	304	13 = GOLD<BR>
	305	14 = SILVER<BR>
	306	15 = CIE XYZ<BR>
	307	16 = CIE Lab<BR>
f301802f	308	17 = RGBW (sRGB)<BR>
	309	32 = ICC1 (CIE Lab with hint for 1 color)<BR>
	310	33 = ICC2 (CIE Lab with hint for 2 colors)<BR>
	311	34 = ICC3 (CIE Lab with hint for 3 colors)<BR>
	312	35 = ICC4 (CIE Lab with hint for 4 colors)<BR>
	313	36 = ICC5 (CIE Lab with hint for 5 colors)<BR>
	314	37 = ICC6 (CIE Lab with hint for 6 colors)<BR>
	315	38 = ICC7 (CIE Lab with hint for 7 colors)<BR>
	316	39 = ICC8 (CIE Lab with hint for 8 colors)<BR>
	317	40 = ICC9 (CIE Lab with hint for 9 colors)<BR>
	318	41 = ICCA (CIE Lab with hint for 10 colors)<BR>
	319	42 = ICCB (CIE Lab with hint for 11 colors)<BR>
	320	43 = ICCC (CIE Lab with hint for 12 colors)<BR>
	321	44 = ICCD (CIE Lab with hint for 13 colors)<BR>
	322	45 = ICCE (CIE Lab with hint for 14 colors)<BR>
	323	46 = ICCF (CIE Lab with hint for 15 colors)<BR>
4744bd90	324	</TD>
	325	</TR>
	326	<TR>
	327	<TD>404-407</TD>
	328	<TD>Unsigned Integer</TD>
	329	<TD>cupsCompression</TD>
	330	<TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
	331	</TR>
	332	<TR>
	333	<TD>408-411</TD>
	334	<TD>Unsigned Integer</TD>
	335	<TD>cupsRowCount</TD>
	336	<TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
	337	</TR>
	338	<TR>
	339	<TD>412-415</TD>
	340	<TD>Unsigned Integer</TD>
	341	<TD>cupsRowFeed</TD>
	342	<TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
	343	</TR>
	344	<TR>
	345	<TD>416-419</TD>
	346	<TD>Unsigned Integer</TD>
	347	<TD>cupsRowStep</TD>
	348	<TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
	349	</TR>
f301802f	350	</TBODY>
4744bd90	351	</TABLE></DIV>
	352
	353
	354	<H2 CLASS="title"><A NAME="V2">Version 2 Raster File Format</A></H2>
	355
	356	<P>A version 2 raster file begins with a 32-bit synchronization
	357	word: 0x52615332 ("RaS2") for big-endian architectures and
	358	0x32536152 ("2SaR") for little-endian architectures. The writer
	359	of the raster file will use the native word order, and the reader
	360	is responsible for detecting a reversed word order file and
	361	swapping bytes as needed. The CUPS Imaging API raster functions
	362	perform this function automatically.</P>
	363
	364	<P>Following the synchronization word are a series of raster
	365	pages. Each page starts with a version 2 page device dictionary
	366	header and is followed immediately by the compressed raster data
	367	for that page.</P>
	368
	369	<DIV CLASS="table"><TABLE SUMMARY="CUPS Version 2 Raster Page Device Dictionary">
f301802f	370	<CAPTION><A NAME="TABLE2">Table 2: CUPS Version 2 Raster Page Device Dictionary</A></CAPTION>
f301802f	371	<THEAD>
4744bd90	372	<TR>
	373	<TH>Bytes</TH>
	374	<TH>Type</TH>
	375	<TH>Description</TH>
	376	<TH>Values</TH>
	377	</TR>
f301802f	378	</THEAD>
f301802f	379	<TBODY>
4744bd90	380	<TR>
	381	<TD>0-419</TD>
	382	<TD>Version 1 header data</TD>
	383	<TD>See Table 1</TD>
	384	</TR>
	385	<TR>
	386	<TD>420-423</TD>
	387	<TD>Unsigned Integer</TD>
	388	<TD>cupsNumColors</TD>
	389	<TD>1 to 6 colors</TD>
	390	</TR>
	391	<TR>
	392	<TD>424-427</TD>
	393	<TD>IEEE Single Precision</TD>
	394	<TD>cupsBorderlessScalingFactor</TD>
	395	<TD>0.0 or 1.0 or greater</TD>
	396	</TR>
	397	<TR>
	398	<TD>428-435</TD>
	399	<TD>IEEE Single Precision (2)</TD>
	400	<TD>cupsPageSize</TD>
	401	<TD>Width and length in points</TD>
	402	</TR>
	403	<TR>
	404	<TD>436-451</TD>
	405	<TD>IEEE Single Precision (4)</TD>
	406	<TD>cupsImagingBBox</TD>
	407	<TD>Four floating point numbers giving the left, bottom,
	408	right, and top positions of the page bounding box in
	409	points</TD>
	410	</TR>
	411	<TR>
	412	<TD>452-515</TD>
	413	<TD>Unsigned Integers (16)</TD>
	414	<TD>cupsInteger</TD>
	415	<TD>16 driver-defined integer values</TD>
	416	</TR>
	417	<TR>
	418	<TD>516-579</TD>
	419	<TD>IEEE Single Precision (16)</TD>
	420	<TD>cupsReal</TD>
	421	<TD>16 driver-defined floating point values</TD>
	422	</TR>
	423	<TR>
	424	<TD>580-1603</TD>
	425	<TD>C Strings (16x64)</TD>
	426	<TD>cupsString</TD>
	427	<TD>16 driver-defined strings</TD>
	428	</TR>
	429	<TR>
	430	<TD>1604-1667</TD>
	431	<TD>C String</TD>
	432	<TD>cupsMarkerType</TD>
	433	<TD>Ink/toner type string</TD>
	434	</TR>
	435	<TR>
	436	<TD>1668-1731</TD>
	437	<TD>C String</TD>
	438	<TD>cupsRenderingIntent</TD>
	439	<TD>Color rendering intent string</TD>
	440	</TR>
	441	<TR>
	442	<TD>1732-1795</TD>
	443	<TD>C String</TD>
444	<TD>cupsPageSizeName</TD>
445	<TD>Page size name/keyword string from PPD</TD>
446	</TR>
f301802f	447	</TBODY>
4744bd90	448	</TABLE></DIV>
	449
	450	<H3><A NAME="COMPRESSION">Compressed Raster Data Format</A></H3>
	451
	452	<P>The version 2 raster data is compressed using a modified TIFF
	453	packbits algorithm. Lines are grouped into an integral number of
	454	color values based upon the <CODE>cupsColorOrder</CODE>
	455	setting:</P>
	456
	457	<DIV CLASS="table"><TABLE SUMMARY="Color Value Sizes">
f301802f	458	<CAPTION><A NAME="TABLE3">Table 3: Color Value Sizes</A></CAPTION>
4744bd90	459	<TR>
	460	<TH>cupsColorOrder</TH>
	461	<TH>Bytes per color value</TH>
	462	</TR>
	463	<TR>
	464	<TD>0 (chunky)</TD>
	465	<TD>(<CODE>cupsBitsPerPixel</CODE> + 7) / 8</TD>
	466	</TR>
	467	<TR>
	468	<TD>1 (banded)</TD>
	469	<TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD>
	470	</TR>
	471	<TR>
	472	<TD>2 (planar)</TD>
	473	<TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD>
	474	</TR>
	475	</TABLE></DIV>
	476
	477	<P>Each line of raster data begins with a repetition count from 1
	478	to 256 that is encoded using a single byte of "count - 1".</P>
	479
	480	<P>After the repetition count, whole color values for that line
	481	are run-length encoded using the TIFF packbits algorithm. 1 to
	482	128 repeated colors are encoded using an initial byte of "count -
	483	1" followed by the color value byte(s). 2 to 128 non-repeating
	484	colors are encoded using an initial byte of "257 - count"
	485	followed by the color value bytes.</P>
	486
	487
f301802f	488	<H2 CLASS="title"><A NAME="ENCODING">Pixel Value Coding</A></H2>
	489
	490	<P>The following sections describe the encoding and decoding of
	491	the color values in a CUPS raster file. In general, colors are
	492	packed into the minimum number of bytes, with special
	493	consideration provided for efficiency of encoding and access.
	494	Multi-byte values are stored in the native byte order and
	495	automatically swapped as needed when reading them using the CUPS
	496	imaging API.</P>
	497
	498	<H3>CUPS_ORDER_CHUNKED</H3>
	499
	500	<P>The chunked order provides the pixel value packed in a single
	501	place. Pixel values with 8 or more bits per color are stored as
	502	an array of colors in order, e.g. for
	503	<CODE>CUPS_CSPACE_RGB</CODE> you will see 8/16-bits of red, then
	504	blue, then green, then red, green, blue, etc. Pixel values with
	505	less than 8 bits per color are packed together as shown in Table
	506	4. <I>Multi-byte pixel values are stored in the native word
	507	order, just as for 16-bit color values.</I></P>
	508
	509	<DIV CLASS="table"><TABLE SUMMARY="Chunked Color Values">
	510	<CAPTION><A NAME="TABLE4">Table 4: Chunked Color Values</A></CAPTION>
	511	<THEAD>
	512	<TR>
	513	<TH>Bits</TH>
	514	<TH>1-color</TH>
	515	<TH>3-color</TH>
	516	<TH>4-color</TH>
	517	<TH>6-color</TH>
	518	</TR>
	519	</THEAD>
	520	<TBODY>
	521	<TR>
	522	<TD>1</TD>
	523	<TD>W/W/W/W/W/W/W/W</TD>
	524	<TD>0RGB/0RGB</TD>
	525	<TD>CMYK/CMYK</TD>
	526	<TD>00KCMYcm</TD>
	527	</TR>
	528	<TR>
	529	<TD>2</TD>
	530	<TD>WW/WW/WW/WW</TD>
	531	<TD>00RRGGBB</TD>
	532	<TD>CCMMYYKK</TD>
	533	<TD>N/A</TD>
	534	</TR>
	535	<TR>
	536	<TD>4</TD>
	537	<TD>WWWW/WWWW</TD>
	538	<TD>0000RRRRGGGGBBBB<BR>
	539	<I>(multi-byte)</I></TD>
	540	<TD>CCCCMMMMYYYYKKKK<BR>
	541	<I>(multi-byte)</I></TD>
	542	<TD>N/A</TD>
	543	</TR>
	544	</TBODY>
	545	</TABLE></DIV>
	546
	547	<H3>CUPS_ORDER_BANDED</H3>
	548
	549	<P>The banded order provides each color as a separate line of
	550	data. Each color plane for a line is written in sequence, e.g.
	551	for the <CODE>CUPS_CSPACE_CMYK</CODE> colorspace you would see
552	all of the cyan pixels for a line followed by the magenta,
553	yellow, and black pixels for that line. This is repeated for all
554	of the lines on the page. Color values are packed starting with
555	the most-significant bit (MSB) first.</P>
556
557	<H3>CUPS_ORDER_PLANAR</H3>
558
559	<P>The planar order provides each color as a separate page of
560	data using a shared page header. Each color plane for a page is
561	written in sequence, e.g. for the <CODE>CUPS_CSPACE_CMYK</CODE>
562	colorspace you would see all of the cyan pixels for a page
563	followed by the magenta, yellow, and black pixels for that page.
564	Color values are packed starting with the most-significant bit
565	(MSB) first. Each line starts on an 8-bit boundary.</P>
566
567	<H3>CUPS_CSPACE_W, CUPS_CSPACE_RGB, CUPS_CSPACE_RGBA, and
568	CUPS_CSPACE_RGBW</H3>
569
570	<P>These colorspaces use the sRGB colorspace definition and
571	whitepoint.</P>
572
573	<H3>CUPS_CSPACE_KCMYcm</H3>
574
575	<P>When <CODE>cupsBitsPerColor</CODE> is 1, 6 color planes are
576	provided - black, cyan, magenta, yellow, light cyan, and light
577	magenta. When <CODE>cupsBitsPerColor</CODE> is greater than 1, 4
578	color planes are provided using the <CODE>CUPS_CSPACE_KCMY</CODE>
579	colorspace instead.</P>
580
581	<P>When <CODE>cupsColorOrder</CODE> is
582	<CODE>CUPS_ORDER_CHUNKED</CODE>, bit 5 corresponds to black and
583	bit 0 corresponds to light magenta. For
584	<CODE>CUPS_ORDER_BANDED</CODE> and
585	<CODE>CUPS_ORDER_PLANAR</CODE>, each color plane is encoded
586	separately.</P>
587
588	<H3>CUPS_CSPACE_CIELab and CUPS_CSPACE_ICCn</H3>
589
590	<P>These colorspaces map a CIE Lab color value with a D65
591	whitepoint to either a 8- or 16-bit per color chunked
592	(<CODE>CUPS_ORDER_CHUNKED</CODE>) format; the banded
593	(<CODE>CUPS_ORDER_BANDED</CODE>) and planar
594	(<CODE>CUPS_ORDER_PLANAR</CODE>) color orders are not
595	supported.</P>
596
597	<P>The values are encoded and decoded using the following
598	formulas:</P>
599
600	<UL>
601
602	<LI>8-bit Encoding:<BR>
603	<I>L8 = 2.55 * L + 0.5<BR>
604	a8 = a + 128.5<BR>
605	b8 = b + 128.5<BR>
606	</I></LI>
607
608	<LI>8-bit Decoding:<BR>
609	<I>L = L8 / 2.55<BR>
610	a = a8 - 128<BR>
611	b = b8 - 128<BR>
612	</I></LI>
613
614	<LI>16-bit Encoding:<BR>
615	<I>L16 = 655.35 * L + 0.5<BR>
616	a16 = 256 * (a + 128) + 0.5<BR>
617	b16 = 256 * (b + 128) + 0.5<BR>
618	</I></LI>
619
620	<LI>16-bit Decoding:<BR>
621	<I>L = L16 / 655.35<BR>
622	a = a16 / 256 - 128<BR>
623	b = b16 / 256 - 128<BR>
624	</I></LI>
625
626	</UL>
627
628	<H3>CUPS_CSPACE_CIEXYZ</H3>
629
630	<P>These colorspaces map a CIE XYZ color value with a D65
631	whitepoint to either a 8- or 16-bit per color chunked
632	(<CODE>CUPS_ORDER_CHUNKED</CODE>) format; the banded
633	(<CODE>CUPS_ORDER_BANDED</CODE>) and planar
634	(<CODE>CUPS_ORDER_PLANAR</CODE>) color orders are not
635	supported.</P>
636
637	<P>The values are encoded and decoded using the following
638	formulas:</P>
639
640	<UL>
641
642	<LI>8-bit Encoding:<BR>
643	<I>X8 = 231.8181 * X + 0.5<BR>
644	Y8 = 231.8181 * Y + 0.5<BR>
645	Z8 = 231.8181 * Z + 0.5<BR>
646	</I></LI>
647
648	<LI>8-bit Decoding:<BR>
649	<I>X = X8 / 231.8181<BR>
650	Y = Y8 / 231.8181<BR>
651	Z = Z8 / 231.8181<BR>
652	</I></LI>
653
654	<LI>16-bit Encoding:<BR>
655	<I>X16 = 59577.2727 * X + 0.5<BR>
656	Y16 = 59577.2727 * Y + 0.5<BR>
657	Z16 = 59577.2727 * Z + 0.5<BR>
658	</I></LI>
659
660	<LI>16-bit Decoding:<BR>
661	<I>X = X16 / 59577.2727<BR>
662	Y = Y16 / 59577.2727<BR>
663	Z = Z16 / 59577.2727<BR>
664	</I></LI>
665
666	</UL>
667
668	<P>The scaling factor for XYZ values is 1/1.1, or 231.8181 for
669	8-bit values and 59577.2727 for 16-bit values. This allows for a
670	slight overflow of XYZ values when converting from RGB, improving
671	accuracy.</P>
672
4744bd90	673
	674	<H2 CLASS="title"><A NAME="HISTORY">Change History</A></H2>
	675
f301802f	676	<H3>Changes in CUPS 1.2.1</H3>
	677
	678	<ul>
	679
	680	<li>Added new sections on coding pixel values.</li>
	681
	682	<li>Clarified definitions of color spaces.</li>
	683
	684	</ul>
	685
	686
4744bd90	687	<H3>Changes in CUPS 1.2</H3>
	688
	689	<ul>
	690
	691	<li>Bumped raster version to 2</li>
	692
	693	<li>Added RGBW colorspace</li>
	694
	695	<li>Added 16 bit per color support</li>
	696
	697	<li>Added cupsNumColors, cupsBorderlessScalingFactor,
	698	cupsPageSize, cupsImagingBBox, cupsInteger, cupsReal,
	699	cupsString, cupsMarkerType, cupsRenderingIntent, and
	700	cupsPageSizeName attributes to the page device
	701	dictionary</li>
	702
	703	<li>Added raster data compression</li>
	704
	705	<li>Added data type column to device dictionary
	706	documentation.</li>
	707
	708	</ul>
	709
	710	<h3>Changes in CUPS 1.1.19</h3>
	711
	712	<ul>
	713
	714	<li>Added ICC and CIE colorspaces.</li>
	715
	716	</ul>
	717
	718	</BODY>
	719	</HTML>