| 4744bd90 |
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> |
projects / thirdparty / cups.git / blame