doc/help/spec-raster.html

   1 <HTML>
   2 <!-- SECTION: Specifications -->
   3 <HEAD>
   4         <TITLE>CUPS Raster Format</TITLE>
   5 </HEAD>
   6 <BODY>
   7
   8 <P>CUPS raster files are device-dependent raster image files that
   9 contain a PostScript page device dictionary and device-dependent
  10 raster imagery for each page in the document. These files are
  11 used to transfer raster data from the PostScript and image file
  12 RIPs to device-dependent filters that convert the raster data to
  13 a printable format.</P>
  14
  15 <P>CUPS 1.0 and 1.1 used a version 1 raster format. CUPS 1.2
  16 introduces a version 2 format that is a superset of the version 1
  17 format. Applications using the CUPS Imaging API (the cupsRaster*
  18 functions) can read both formats without code changes.</P>
  19
  20 <P>The registered MIME media type for CUPS raster files is
  21 <CODE>application/vnd.cups-raster</CODE>.</P>
  22
  23
  24 <H2 CLASS="title"><A NAME="V1">Version 1 Raster File Format</A></H2>
  25
  26 <P>A version 1 raster file begins with a 32-bit synchronization
  27 word: 0x52615374 ("RaSt") for big-endian architectures and
  28 0x74536152 ("tSaR") for little-endian architectures. The writer
  29 of the raster file will use the native word order, and the reader
  30 is responsible for detecting a reversed word order file and
  31 swapping bytes as needed. The CUPS Imaging API raster functions
  32 perform this function automatically.</P>
  33
  34 <P>Following the synchronization word are a series of raster
  35 pages. Each page starts with a page device dictionary header and
  36 is followed immediately by the (uncompressed, raw) raster data
  37 for that page.</P>
  38
  39 <DIV CLASS="table"><TABLE SUMMARY="CUPS Version 1 Raster Page Device Dictionary">
  40 <CAPTION>Table 1: CUPS Version 1 Raster Page Device Dictionary</CAPTION>
  41 <TR>
  42         <TH>Bytes</TH>
  43         <TH>Type</TH>
  44         <TH>Description</TH>
  45         <TH>Values</TH>
  46 </TR>
  47 <TR>
  48         <TD>0-63</TD>
  49         <TD>C String</TD>
  50         <TD>MediaClass</TD>
  51         <TD>Media class string</TD>
  52 </TR>
  53 <TR>
  54         <TD>64-127</TD>
  55         <TD>C String</TD>
  56         <TD>MediaColor</TD>
  57         <TD>Media color string</TD>
  58 </TR>
  59 <TR>
  60         <TD>128-191</TD>
  61         <TD>C String</TD>
  62         <TD>MediaType</TD>
  63         <TD>Media type string</TD>
  64 </TR>
  65 <TR>
  66         <TD>192-255</TD>
  67         <TD>C String</TD>
  68         <TD>OutputType</TD>
  69         <TD>Output type string</TD>
  70 </TR>
  71 <TR>
  72         <TD>256-259</TD>
  73         <TD>Unsigned Integer</TD>
  74         <TD>AdvanceDistance</TD>
  75         <TD>0 to 2<SUP>32</SUP> - 1 points</TD>
  76 </TR>
  77 <TR>
  78         <TD>260-263</TD>
  79         <TD>Unsigned Integer</TD>
  80         <TD>AdvanceMedia</TD>
  81         <TD>0 = Never advance roll<BR>
  82         1 = Advance roll after file<BR>
  83         2 = Advance roll after job<BR>
  84         3 = Advance roll after set<BR>
  85         4 = Advance roll after page</TD>
  86 </TR>
  87 <TR>
  88         <TD>264-267</TD>
  89         <TD>Unsigned Integer</TD>
  90         <TD>Collate</TD>
  91         <TD>0 = do not collate copies<BR>
  92         1 = collate copies</TD>
  93 </TR>
  94 <TR>
  95         <TD>268-271</TD>
  96         <TD>Unsigned Integer</TD>
  97         <TD>CutMedia</TD>
  98         <TD>0 = Never cut media<BR>
  99         1 = Cut roll after file<BR>
 100         2 = Cut roll after job<BR>
 101         3 = Cut roll after set<BR>
 102         4 = Cut roll after page</TD>
 103 </TR>
 104 <TR>
 105         <TD>272-275</TD>
 106         <TD>Unsigned Integer</TD>
 107         <TD>Duplex</TD>
 108         <TD>0 = Print single-sided<BR>
 109         1 = Print double-sided</TD>
 110 </TR>
 111 <TR>
 112         <TD>276-283</TD>
 113         <TD>Unsigned Integers (2)</TD>
 114         <TD>HWResolution</TD>
 115         <TD>Horizontal and vertical resolution in dots-per-inch.</TD>
 116 </TR>
 117 <TR>
 118         <TD>284-299</TD>
 119         <TD>Unsigned Integers (4)</TD>
 120         <TD>ImagingBoundingBox</TD>
 121         <TD>Four integers giving the left, bottom, right, and top positions
 122         of the page bounding box in points</TD>
 123 </TR>
 124 <TR>
 125         <TD>300-303</TD>
 126         <TD>Unsigned Integer</TD>
 127         <TD>InsertSheet</TD>
 128         <TD>0 = Do not insert separator sheets<BR>
 129         1 = Insert separator sheets</TD>
 130 </TR>
 131 <TR>
 132         <TD>304-307</TD>
 133         <TD>Unsigned Integer</TD>
 134         <TD>Jog</TD>
 135         <TD>0 = Do no jog pages<BR>
 136         1 = Jog pages after file<BR>
 137         2 = Jog pages after job<BR>
 138         3 = Jog pages after set</TD>
 139 </TR>
 140 <TR>
 141         <TD>308-311</TD>
 142         <TD>Unsigned Integer</TD>
 143         <TD>LeadingEdge</TD>
 144         <TD>0 = Top edge is first<BR>
 145         1 = Right edge is first<BR>
 146         2 = Bottom edge is first<BR>
 147         3 = Left edge is first</TD>
 148 </TR>
 149 <TR>
 150         <TD>312-319</TD>
 151         <TD>Unsigned Integers (2)</TD>
 152         <TD>Margins</TD>
 153         <TD>Left and bottom origin of image in points</TD>
 154 </TR>
 155 <TR>
 156         <TD>320-323</TD>
 157         <TD>Unsigned Integer</TD>
 158         <TD>ManualFeed</TD>
 159         <TD>0 = Do not manually feed media<BR>
 160         1 = Manually feed media</TD>
 161 </TR>
 162 <TR>
 163         <TD>324-327</TD>
 164         <TD>Unsigned Integer</TD>
 165         <TD>MediaPosition</TD>
 166         <TD>Input slot position from 0 to N</TD>
 167 </TR>
 168 <TR>
 169         <TD>328-331</TD>
 170         <TD>Unsigned Integer</TD>
 171         <TD>MediaWeight</TD>
 172         <TD>Media weight in grams per meter squared</TD>
 173 </TR>
 174 <TR>
 175         <TD>332-335</TD>
 176         <TD>Unsigned Integer</TD>
 177         <TD>MirrorPrint</TD>
 178         <TD>0 = Do not mirror prints<BR>
 179         1 = Mirror prints</TD>
 180 </TR>
 181 <TR>
 182         <TD>336-339</TD>
 183         <TD>Unsigned Integer</TD>
 184         <TD>NegativePrint</TD>
 185         <TD>0 = Do not invert prints<BR>
 186         1 = Invert prints</TD>
 187 </TR>
 188 <TR>
 189         <TD>340-343</TD>
 190         <TD>Unsigned Integer</TD>
 191         <TD>NumCopies</TD>
 192         <TD>1 to 2<SUP>32</SUP> - 1</TD>
 193 </TR>
 194 <TR>
 195         <TD>344-347</TD>
 196         <TD>Unsigned Integer</TD>
 197         <TD>Orientation</TD>
 198         <TD>0 = Do not rotate page<BR>
 199         1 = Rotate page counter-clockwise<BR>
 200         2 = Turn page upside down<BR>
 201         3 = Rotate page clockwise</TD>
 202 </TR>
 203 <TR>
 204         <TD>348-351</TD>
 205         <TD>Unsigned Integer</TD>
 206         <TD>OutputFaceUp</TD>
 207         <TD>0 = Output face down<BR>
 208         1 = Output face up</TD>
 209 </TR>
 210 <TR>
 211         <TD>352-359</TD>
 212         <TD>Unsigned Integers (2)</TD>
 213         <TD>PageSize</TD>
 214         <TD>Width and length in points</TD>
 215 </TR>
 216 <TR>
 217         <TD>360-363</TD>
 218         <TD>Unsigned Integer</TD>
 219         <TD>Separations</TD>
 220         <TD>0 = Print composite image<BR>
 221         1 = Print color separations</TD>
 222 </TR>
 223 <TR>
 224         <TD>364-367</TD>
 225         <TD>Unsigned Integer</TD>
 226         <TD>TraySwitch</TD>
 227         <TD>0 = Do not change trays if selected tray is empty<BR>
 228         1 = Change trays if selected tray is empty</TD>
 229 </TR>
 230 <TR>
 231         <TD>368-371</TD>
 232         <TD>Unsigned Integer</TD>
 233         <TD>Tumble</TD>
 234         <TD>0 = Do not rotate even pages when duplexing<BR>
 235         1 = Rotate even pages when duplexing</TD>
 236 </TR>
 237 <TR>
 238         <TD>372-375</TD>
 239         <TD>Unsigned Integer</TD>
 240         <TD>cupsWidth</TD>
 241         <TD>Width of page image in pixels</TD>
 242 </TR>
 243 <TR>
 244         <TD>376-379</TD>
 245         <TD>Unsigned Integer</TD>
 246         <TD>cupsHeight</TD>
 247         <TD>Height of page image in pixels</TD>
 248 </TR>
 249 <TR>
 250         <TD>380-383</TD>
 251         <TD>Unsigned Integer</TD>
 252         <TD>cupsMediaType</TD>
 253         <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
 254 </TR>
 255 <TR>
 256         <TD>384-387</TD>
 257         <TD>Unsigned Integer</TD>
 258         <TD>cupsBitsPerColor</TD>
 259         <TD>1, 2, 4, 8 bits for version 1 raster files<BR>
 260         1, 2, 4, 8, and 16 bits for version 2 raster files</TD>
 261 </TR>
 262 <TR>
 263         <TD>388-391</TD>
 264         <TD>Unsigned Integer</TD>
 265         <TD>cupsBitsPerPixel</TD>
 266         <TD>1 to 32 bits for version 1 raster files<BR>
 267         1 to 64 bits for version 2 raster files</TD>
 268 </TR>
 269 <TR>
 270         <TD>392-395</TD>
 271         <TD>Unsigned Integer</TD>
 272         <TD>cupsBytesPerLine</TD>
 273         <TD>1 to 2<SUP>32</SUP> - 1 bytes</TD>
 274 </TR>
 275 <TR>
 276         <TD>396-399</TD>
 277         <TD>Unsigned Integer</TD>
 278         <TD>cupsColorOrder</TD>
 279         <TD>0 = chunky pixels (CMYK CMYK CMYK)<BR>
 280         1 = banded pixels (CCC MMM YYY KKK)<BR>
 281         2 = planar pixels (CCC... MMM... YYY... KKK...)</TD>
 282 </TR>
 283 <TR>
 284         <TD>400-403</TD>
 285         <TD>Unsigned Integer</TD>
 286         <TD>cupsColorSpace</TD>
 287         <TD>0 = white<BR>
 288         1 = RGB<BR>
 289         2 = RGBA<BR>
 290         3 = black<BR>
 291         4 = CMY<BR>
 292         5 = YMC<BR>
 293         6 = CMYK<BR>
 294         7 = YMCK<BR>
 295         8 = KCMY<BR>
 296         9 = KCMYcm<BR>
 297         10 = GMCK<BR>
 298         11 = GMCS<BR>
 299         12 = WHITE<BR>
 300         13 = GOLD<BR>
 301         14 = SILVER<BR>
 302         15 = CIE XYZ<BR>
 303         16 = CIE Lab<BR>
 304         17 = RGBW<BR>
 305         32 = ICC1<BR>
 306         33 = ICC2<BR>
 307         34 = ICC3<BR>
 308         35 = ICC4<BR>
 309         36 = ICC5<BR>
 310         37 = ICC6<BR>
 311         38 = ICC7<BR>
 312         39 = ICC8<BR>
 313         40 = ICC9<BR>
 314         41 = ICCA (10)<BR>
 315         42 = ICCB (11)<BR>
 316         43 = ICCC (12)<BR>
 317         44 = ICCD (13)<BR>
 318         45 = ICCE (14)<BR>
 319         46 = ICCF (15)<BR>
 320         </TD>
 321 </TR>
 322 <TR>
 323         <TD>404-407</TD>
 324         <TD>Unsigned Integer</TD>
 325         <TD>cupsCompression</TD>
 326         <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
 327 </TR>
 328 <TR>
 329         <TD>408-411</TD>
 330         <TD>Unsigned Integer</TD>
 331         <TD>cupsRowCount</TD>
 332         <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
 333 </TR>
 334 <TR>
 335         <TD>412-415</TD>
 336         <TD>Unsigned Integer</TD>
 337         <TD>cupsRowFeed</TD>
 338         <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
 339 </TR>
 340 <TR>
 341         <TD>416-419</TD>
 342         <TD>Unsigned Integer</TD>
 343         <TD>cupsRowStep</TD>
 344         <TD>Driver-specific 0 to 2<SUP>32</SUP> - 1</TD>
 345 </TR>
 346 </TABLE></DIV>
 347
 348
 349 <H2 CLASS="title"><A NAME="V2">Version 2 Raster File Format</A></H2>
 350
 351 <P>A version 2 raster file begins with a 32-bit synchronization
 352 word: 0x52615332 ("RaS2") for big-endian architectures and
 353 0x32536152 ("2SaR") for little-endian architectures. The writer
 354 of the raster file will use the native word order, and the reader
 355 is responsible for detecting a reversed word order file and
 356 swapping bytes as needed. The CUPS Imaging API raster functions
 357 perform this function automatically.</P>
 358
 359 <P>Following the synchronization word are a series of raster
 360 pages. Each page starts with a version 2 page device dictionary
 361 header and is followed immediately by the compressed raster data
 362 for that page.</P>
 363
 364 <DIV CLASS="table"><TABLE SUMMARY="CUPS Version 2 Raster Page Device Dictionary">
 365 <CAPTION>Table 2: CUPS Version 2 Raster Page Device Dictionary</CAPTION>
 366 <TR>
 367         <TH>Bytes</TH>
 368         <TH>Type</TH>
 369         <TH>Description</TH>
 370         <TH>Values</TH>
 371 </TR>
 372 <TR>
 373         <TD>0-419</TD>
 374         <TD>Version 1 header data</TD>
 375         <TD>See Table 1</TD>
 376 </TR>
 377 <TR>
 378         <TD>420-423</TD>
 379         <TD>Unsigned Integer</TD>
 380         <TD>cupsNumColors</TD>
 381         <TD>1 to 6 colors</TD>
 382 </TR>
 383 <TR>
 384         <TD>424-427</TD>
 385         <TD>IEEE Single Precision</TD>
 386         <TD>cupsBorderlessScalingFactor</TD>
 387         <TD>0.0 or 1.0 or greater</TD>
 388 </TR>
 389 <TR>
 390         <TD>428-435</TD>
 391         <TD>IEEE Single Precision (2)</TD>
 392         <TD>cupsPageSize</TD>
 393         <TD>Width and length in points</TD>
 394 </TR>
 395 <TR>
 396         <TD>436-451</TD>
 397         <TD>IEEE Single Precision (4)</TD>
 398         <TD>cupsImagingBBox</TD>
 399         <TD>Four floating point numbers giving the left, bottom,
 400         right, and top positions of the page bounding box in
 401         points</TD>
 402 </TR>
 403 <TR>
 404         <TD>452-515</TD>
 405         <TD>Unsigned Integers (16)</TD>
 406         <TD>cupsInteger</TD>
 407         <TD>16 driver-defined integer values</TD>
 408 </TR>
 409 <TR>
 410         <TD>516-579</TD>
 411         <TD>IEEE Single Precision (16)</TD>
 412         <TD>cupsReal</TD>
 413         <TD>16 driver-defined floating point values</TD>
 414 </TR>
 415 <TR>
 416         <TD>580-1603</TD>
 417         <TD>C Strings (16x64)</TD>
 418         <TD>cupsString</TD>
 419         <TD>16 driver-defined strings</TD>
 420 </TR>
 421 <TR>
 422         <TD>1604-1667</TD>
 423         <TD>C String</TD>
 424         <TD>cupsMarkerType</TD>
 425         <TD>Ink/toner type string</TD>
 426 </TR>
 427 <TR>
 428         <TD>1668-1731</TD>
 429         <TD>C String</TD>
 430         <TD>cupsRenderingIntent</TD>
 431         <TD>Color rendering intent string</TD>
 432 </TR>
 433 <TR>
 434         <TD>1732-1795</TD>
 435         <TD>C String</TD>
 436         <TD>cupsPageSizeName</TD>
 437         <TD>Page size name/keyword string from PPD</TD>
 438 </TR>
 439 </TABLE></DIV>
 440
 441 <H3><A NAME="COMPRESSION">Compressed Raster Data Format</A></H3>
 442
 443 <P>The version 2 raster data is compressed using a modified TIFF
 444 packbits algorithm. Lines are grouped into an integral number of
 445 color values based upon the <CODE>cupsColorOrder</CODE>
 446 setting:</P>
 447
 448 <DIV CLASS="table"><TABLE SUMMARY="Color Value Sizes">
 449 <TR>
 450         <TH>cupsColorOrder</TH>
 451         <TH>Bytes per color value</TH>
 452 </TR>
 453 <TR>
 454         <TD>0 (chunky)</TD>
 455         <TD>(<CODE>cupsBitsPerPixel</CODE> + 7) / 8</TD>
 456 </TR>
 457 <TR>
 458         <TD>1 (banded)</TD>
 459         <TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD>
 460 </TR>
 461 <TR>
 462         <TD>2 (planar)</TD>
 463         <TD>(<CODE>cupsBitsPerColor</CODE> + 7) / 8</TD>
 464 </TR>
 465 </TABLE></DIV>
 466
 467 <P>Each line of raster data begins with a repetition count from 1
 468 to 256 that is encoded using a single byte of "count - 1".</P>
 469
 470 <P>After the repetition count, whole color values for that line
 471 are run-length encoded using the TIFF packbits algorithm. 1 to
 472 128 repeated colors are encoded using an initial byte of "count -
 473 1" followed by the color value byte(s). 2 to 128 non-repeating
 474 colors are encoded using an initial byte of "257 - count"
 475 followed by the color value bytes.</P>
 476
 477
 478
 479 <H2 CLASS="title"><A NAME="HISTORY">Change History</A></H2>
 480
 481 <H3>Changes in CUPS 1.2</H3>
 482
 483 <ul>
 484
 485         <li>Bumped raster version to 2</li>
 486
 487         <li>Added RGBW colorspace</li>
 488
 489         <li>Added 16 bit per color support</li>
 490
 491         <li>Added cupsNumColors, cupsBorderlessScalingFactor,
 492         cupsPageSize, cupsImagingBBox, cupsInteger, cupsReal,
 493         cupsString, cupsMarkerType, cupsRenderingIntent, and
 494         cupsPageSizeName attributes to the page device
 495         dictionary</li>
 496
 497         <li>Added raster data compression</li>
 498
 499         <li>Added data type column to device dictionary
 500         documentation.</li>
 501
 502 </ul>
 503
 504 <h3>Changes in CUPS 1.1.19</h3>
 505
 506 <ul>
 507
 508         <li>Added ICC and CIE colorspaces.</li>
 509
 510 </ul>
 511
 512 </BODY>
 513 </HTML>