doc/help/raster-driver.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- SECTION: Programming -->
   4 <head>
   5 <title>Developing Raster Printer Drivers</title>
   6 <meta name="keywords" content="Programming">
   7 <meta name="creator" content="Mini-XML v2.6">
   8 <style type="text/css"><!--
   9 BODY {
  10   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  11 }
  12
  13 H1, H2, H3, H4, H5, H6, P, TD, TH {
  14   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  15 }
  16
  17 KBD {
  18   font-family: monaco, courier, monospace;
  19   font-weight: bold;
  20 }
  21
  22 PRE {
  23   font-family: monaco, courier, monospace;
  24 }
  25
  26 PRE.command {
  27   margin-left: 36pt;
  28 }
  29
  30 P.example {
  31   font-style: italic;
  32   margin-left: 36pt;
  33 }
  34
  35 PRE.example {
  36   background: #eeeeee;
  37   border: dotted thin #999999;
  38   margin-left: 36pt;
  39   padding: 10px;
  40 }
  41
  42 PRE.command EM, PRE.example EM {
  43   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  44 }
  45
  46 P.command {
  47   font-family: monaco, courier, monospace;
  48   margin-left: 36pt;
  49 }
  50
  51 P.formula {
  52   font-style: italic;
  53   margin-left: 36pt;
  54 }
  55
  56 BLOCKQUOTE {
  57   background: #cccccc;
  58   border: solid thin #999999;
  59   padding: 10pt;
  60 }
  61
  62 A IMG {
  63   border: none;
  64 }
  65
  66 A:link:hover IMG {
  67   background: #f0f0f0;
  68   border-radius: 10px;
  69   -moz-border-radius: 10px;
  70 }
  71
  72 A:link, A:visited {
  73   font-weight: normal;
  74   text-decoration: none;
  75 }
  76
  77 A:link:hover, A:visited:hover, A:active {
  78   text-decoration: underline;
  79 }
  80
  81 SUB, SUP {
  82   font-size: 50%;
  83 }
  84
  85 TR.data, TD.data, TR.data TD {
  86   margin-top: 10pt;
  87   padding: 5pt;
  88   border-bottom: solid 1pt #999999;
  89 }
  90
  91 TR.data TH {
  92   border-bottom: solid 1pt #999999;
  93   padding-top: 10pt;
  94   padding-left: 5pt;
  95   text-align: left;
  96 }
  97
  98 DIV.table TABLE {
  99   border: solid thin #999999;
 100   border-collapse: collapse;
 101   border-spacing: 0;
 102   margin-left: auto;
 103   margin-right: auto;
 104 }
 105
 106 DIV.table CAPTION {
 107   caption-side: top;
 108   font-size: 120%;
 109   font-style: italic;
 110   font-weight: bold;
 111   margin-left: auto;
 112   margin-right: auto;
 113 }
 114
 115 DIV.table TABLE TD {
 116   border: solid thin #cccccc;
 117   padding-top: 5pt;
 118 }
 119
 120 DIV.table TABLE TH {
 121   background: #cccccc;
 122   border: none;
 123   border-bottom: solid thin #999999;
 124 }
 125
 126 DIV.figure TABLE {
 127   margin-left: auto;
 128   margin-right: auto;
 129 }
 130
 131 DIV.figure CAPTION {
 132   caption-side: bottom;
 133   font-size: 120%;
 134   font-style: italic;
 135   font-weight: bold;
 136   margin-left: auto;
 137   margin-right: auto;
 138 }
 139
 140 TH.label {
 141   text-align: right;
 142   vertical-align: top;
 143 }
 144
 145 TH.sublabel {
 146   text-align: right;
 147   font-weight: normal;
 148 }
 149
 150 HR {
 151   border: solid thin;
 152 }
 153
 154 SPAN.info {
 155   background: black;
 156   border: thin solid black;
 157   color: white;
 158   font-size: 80%;
 159   font-style: italic;
 160   font-weight: bold;
 161   white-space: nowrap;
 162 }
 163
 164 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 165   float: right;
 166   font-size: 100%;
 167 }
 168
 169 H2.title, H3.title {
 170   border-bottom: solid 2pt #000000;
 171 }
 172
 173 DIV.indent, TABLE.indent {
 174   margin-top: 2em;
 175   margin-left: auto;
 176   margin-right: auto;
 177   width: 90%;
 178 }
 179
 180 TABLE.indent {
 181   border-collapse: collapse;
 182 }
 183
 184 TABLE.indent TD, TABLE.indent TH {
 185   padding: 0;
 186 }
 187
 188 TABLE.list {
 189   border-collapse: collapse;
 190   margin-left: auto;
 191   margin-right: auto;
 192   width: 90%;
 193 }
 194
 195 TABLE.list TH {
 196   background: white;
 197   border-bottom: solid thin #cccccc;
 198   color: #444444;
 199   padding-top: 10pt;
 200   padding-left: 5pt;
 201   text-align: left;
 202   vertical-align: bottom;
 203   white-space: nowrap;
 204 }
 205
 206 TABLE.list TH A {
 207   color: #4444cc;
 208 }
 209
 210 TABLE.list TD {
 211   border-bottom: solid thin #eeeeee;
 212   padding-top: 5pt;
 213   padding-left: 5pt;
 214 }
 215
 216 TABLE.list TR:nth-child(even) {
 217   background: #f8f8f8;
 218 }
 219
 220 TABLE.list TR:nth-child(odd) {
 221   background: #f4f4f4;
 222 }
 223
 224 DT {
 225   margin-left: 36pt;
 226   margin-top: 12pt;
 227 }
 228
 229 DD {
 230   margin-left: 54pt;
 231 }
 232
 233 DL.category DT {
 234   font-weight: bold;
 235 }
 236
 237 P.summary {
 238   margin-left: 36pt;
 239   font-family: monaco, courier, monospace;
 240 }
 241
 242 DIV.summary TABLE {
 243   border: solid thin #999999;
 244   border-collapse: collapse;
 245   border-spacing: 0;
 246   margin: 10px;
 247 }
 248
 249 DIV.summary TABLE TD, DIV.summary TABLE TH {
 250   border: solid thin #999999;
 251   padding: 5px;
 252   text-align: left;
 253   vertical-align: top;
 254 }
 255
 256 DIV.summary TABLE THEAD TH {
 257   background: #eeeeee;
 258 }
 259
 260 /* API documentation styles... */
 261 div.body h1 {
 262   margin: 0;
 263 }
 264 div.body h2 {
 265   margin-top: 1.5em;
 266 }
 267 div.body h3, div.body h4, div.body h5 {
 268   margin-bottom: 0.5em;
 269   margin-top: 1.5em;
 270 }
 271 .class, .enumeration, .function, .struct, .typedef, .union {
 272   border-bottom: solid thin #999999;
 273   margin-bottom: 0;
 274   margin-top: 2em;
 275 }
 276 .description {
 277   margin-top: 0.5em;
 278 }
 279 code, p.code, pre, ul.code li {
 280   font-family: monaco, courier, monospace;
 281   font-size: 90%;
 282 }
 283 ul.code, ul.contents, ul.subcontents {
 284   list-style-type: none;
 285   margin: 0;
 286   padding-left: 0;
 287 }
 288 ul.code li {
 289   margin: 0;
 290 }
 291 ul.contents > li {
 292   margin-top: 1em;
 293 }
 294 ul.contents li ul.code, ul.contents li ul.subcontents {
 295   padding-left: 2em;
 296 }
 297 div.body dl {
 298   margin-left: 0;
 299   margin-top: 0;
 300 }
 301 div.body dt {
 302   font-style: italic;
 303   margin-left: 0;
 304   margin-top: 0;
 305 }
 306 div.body dd {
 307   margin-bottom: 0.5em;
 308 }
 309
 310 /* This is just for the HTML files generated with the framedhelp target */
 311 div.contents {
 312   background: #e8e8e8;
 313   border: solid thin black;
 314   padding: 10px;
 315 }
 316 div.contents h1 {
 317   font-size: 110%;
 318 }
 319 div.contents h2 {
 320   font-size: 100%;
 321 }
 322 div.contents ul.contents {
 323   font-size: 80%;
 324 }
 325 div.contents ul.subcontents li {
 326   margin-left: 1em;
 327   text-indent: -1em;
 328 }
 329 --></style>
 330 </head>
 331 <body>
 332 <div class='body'>
 333 <p>This document describes how to develop printer drivers for raster printers. Topics include: <a href='#BASICS'>printer driver basics</a>, <a href='#CREATE'>creating new PPD files</a>, <a href='#FILTERS'>using filters</a>, <a href='#COLOR'>implementing color management</a>, <a href='#MACOSX'>adding Mac OS X features</a>, and <a href='#DEPLOY'>deploying your driver</a>.</p>
 334
 335 <div class='summary'><table summary='General Information'>
 336 <tbody>
 337 <tr>
 338         <th>See Also</th>
 339         <td>Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br>
 340         Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br>
 341         Programming: <a href='ppd-compiler.html'>Introduction to the PPD Compiler</a><br>
 342         Programming: <a href='api-raster.html'>Raster API</a><br>
 343         References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a><br>
 344         Specifications: <a href='spec-ppd.html'>CUPS PPD Extensions</a></td>
 345 </tr>
 346 </tbody>
 347 </table></div>
 348 <h2 class="title">Contents</h2>
 349 <ul class="contents">
 350 <ul class="subcontents">
 351 <li><a href="#BASICS">Printer Driver Basics</a></li>
 352 <li><a href="#CREATING">Creating New PPD Files</a></li>
 353 <li><a href="#FILTERS">Using Filters</a></li>
 354 <li><a href="#COLOR">Implementing Color Management</a></li>
 355 <li><a href="#MACOSX">Adding Mac OS X Features</a></li>
 356 <li><a href="#DEPLOY">Deploying Your Driver</a></li>
 357 <h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2>
 358
 359 <p>A CUPS raster printer driver consists of a PostScript Printer Description (PPD) file that describes the features and capabilities of the device, one or more <em>filter</em> programs that prepare print data for the device, and zero or more support files for color management, online help, and so forth. The PPD file includes references to all of the filters and support files used by the driver.</p>
 360
 361 <p>Every time a user prints something the scheduler program, <a href='man-cupsd.html'>cupsd(8)</a>, determines the format of the print job and the programs required to convert that job into something the printer understands. CUPS includes filter programs for many common formats, for example to convert Portable Document Format (PDF) files into CUPS raster data. <a href='#FIGURE_1'>Figure 1</a> shows the data flow of a typical print job.</p>
 362
 363 <div class='figure'><table summary='Raster Filter Chain'>
 364 <caption>Figure 1: <a name='FIGURE_1'>Raster Filter Chain</a></caption>
 365 <tr><td><img src='/images/cups-raster-chain.png' width='700' height='150' alt='Raster Filter Chain'></td></tr>
 366 </table></div>
 367
 368 <p>The raster filter converts CUPS raster data into a format the printer understands, for example HP-PCL. CUPS includes several sample raster filters supporting standard page description languages (PDLs). <a href='#TABLE_1'>Table 1</a> shows the raster filters that are bundled with CUPS and the languages they support.</p>
 369
 370 <div class='table'><table summary='Standard CUPS Raster Filters'>
 371 <caption>Table 1: <a name='TABLE_1'>Standard CUPS Raster Filters</a></caption>
 372 <thead>
 373 <tr><th>Filter</th><th>PDLs</th><th>ppdc DriverType</th><th>ppdc #include file</th></tr>
 374 </thead>
 375 <tbody>
 376 <tr><td>rastertoepson</td><td>ESC/P, ESC/P2</td><td>epson</td><td>epson.h</td></tr>
 377 <tr><td>rastertoescpx</td><td>ESC/P, ESC/P2, EPSON Remote Mode</td><td>escp</td><td>escp.h</td></tr>
 378 <tr><td>rastertohp</td><td>HP-PCL3, HP-PCL5</td><td>hp</td><td>hp.h</td></tr>
 379 <tr><td>rastertolabel</td><td>CPCL, Dymo, EPL1, EPL2, Intellitech PCL, ZPL</td><td>label</td><td>label.h</td></tr>
 380 <tr><td>rastertopclx</td><td>HP-RTL, HP-PCL3, HP-PCL3GUI, HP-PCL5, HP-PCL5c, HP-PCL5e</td><td>pcl</td><td>pcl.h</td></tr>
 381 </tbody>
 382 </table></div>
 383
 384 <p>The optional port monitor handles interface-specific protocol or encoding issues. For example, some raster printers use the 1284.4 communications protocol.</p>
 385
 386 <p>The backend handles communications with the printer, sending print data from the last filter to the printer and relaying back-channel data from the printer to the upstream filters. CUPS includes backend programs for common direct-connect interfaces and network protocols, and you can provide your own backend to support custom interfaces and protocols.</p>
 387
 388 <p>The scheduler also supports a special "command" file format for sending maintenance commands and status queries to a printer or printer driver. Command print jobs typically use a single command filter program defined in the PPD file to generate the appropriate printer commands and handle any responses from the printer. <a href='#FIGURE_2'>Figure 2</a> shows the data flow of a typical command job.</p>
 389
 390 <div class='figure'><table summary='Command Filter Chain'>
 391 <caption>Figure 2: <a name='FIGURE_2'>Command Filter Chain</a></caption>
 392 <tr><td><img src='/images/cups-command-chain.png' width='575' height='150' alt='Command Filter Chain'></td></tr>
 393 </table></div>
 394
 395 <p>Raster printer drivers must provide their own command filter.</p>
 396
 397
 398 <h2 class='title'><a name='CREATING'>Creating New PPD Files</a></h2>
 399
 400 <p>We recommend using the CUPS PPD compiler, <a href='man-ppdc.html'>ppdc(1)</a>, to create new PPD files since it manages many of the tedious (and error-prone!) details of paper sizes and localization for you. It also allows you to easily support multiple devices from a single source file. For more information see the "<a href='ppd-compiler.html'>Introduction to the PPD Compiler</a>" document. <a href='#LISTING_1'>Listing 1</a> shows a driver information file for several similar black-and-white HP-PCL5 laser printers.</p>
 401
 402 <p class='example'>Listing 1: <a name='LISTING_1'>"examples/laserjet-basic.drv"</a></p>
 403
 404 <pre class='example'>
 405 <I>// Include standard font and media definitions</I>
 406 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 407 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 408
 409 <I>// Include HP-PCL driver definitions</I>
 410 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;pcl.h&gt;
 411
 412 <I>// Specify that this driver uses the HP-PCL driver...</I>
 413 <a href='ref-ppdcfile.html#DriverType'>DriverType</a> pcl
 414
 415 <I>// Specify the driver options via the model number...</I>
 416 <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> ($PCL_PAPER_SIZE $PCL_PJL $PCL_PJL_RESOLUTION)
 417
 418 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 419 <a href='ref-ppdcfile.html#Font'>Font</a> *
 420
 421 <I>// Manufacturer and driver version</I>
 422 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "HP"
 423 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 424
 425 <I>// Supported page sizes and their margins</I>
 426 <a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 18 12 18 12
 427 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 428 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Legal
 429 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Executive
 430 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Monarch
 431 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Statement
 432 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> FanFoldGermanLegal
 433
 434 <a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 18 12.72 18 12.72
 435 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Env10
 436
 437 <a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 9.72 12 9.72 12
 438 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 439 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A5
 440 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> B5
 441 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvC5
 442 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvDL
 443 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvISOB5
 444 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Postcard
 445 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> DoublePostcard
 446
 447 <I>// Only black-and-white output with mode 3 compression...</I>
 448 <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray k chunky 3
 449
 450 <I>// Supported resolutions</I>
 451 <a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 1 0 0 0 "300dpi/300 DPI"
 452 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "600dpi/600 DPI"
 453
 454 <I>// Supported input slots</I>
 455 *<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 7 "Auto/Automatic Selection"
 456 <a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 2 "Manual/Tray 1 - Manual Feed"
 457 <a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 4 "Upper/Tray 1"
 458 <a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 1 "Lower/Tray 2"
 459 <a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 5 "LargeCapacity/Tray 3"
 460
 461 <I>// Tray 3 is an option...</I>
 462 <a href='ref-ppdcfile.html#Installable'>Installable</a> "OptionLargeCapacity/Tray 3 Installed"
 463 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*OptionLargeCapacity False *InputSlot LargeCapacity"
 464
 465 {
 466   <I>// HP LaserJet 2100 Series</I>
 467   <a href='ref-ppdcfile.html#Throughput'>Throughput</a> 10
 468   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2100 Series"
 469   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt211.ppd"
 470 }
 471
 472 {
 473   <I>// LaserJet 2200 and 2300 series have duplexer option...</I>
 474   <a href='ref-ppdcfile.html#Duplex'>Duplex</a> normal
 475   <a href='ref-ppdcfile.html#Installable'>Installable</a> "OptionDuplex/Duplexer Installed"
 476   <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*OptionDuplex False *Duplex"
 477
 478   {
 479     <I>// HP LaserJet 2200 Series</I>
 480     <a href='ref-ppdcfile.html#Throughput'>Throughput</a> 19
 481     <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2200 Series"
 482     <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt221.ppd"
 483   }
 484
 485   {
 486     <I>// HP LaserJet 2300 Series</I>
 487     <a href='ref-ppdcfile.html#Throughput'>Throughput</a> 25
 488     <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2300 Series"
 489     <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt231.ppd"
 490   }
 491 }
 492 </pre>
 493
 494
 495 <h2 class='title'><a name='FILTERS'>Using Filters</a></h2>
 496
 497 <p>The standard CUPS raster filters can be specified using the
 498 <a href='ref-ppdcfile.html#DriverType'><tt>DriverType</tt></a> directive, for example:</p>
 499
 500 <pre class='example'>
 501 <I>// Specify that this driver uses the HP-PCL driver...</I>
 502 <a href='ref-ppdcfile.html#DriverType'>DriverType</a> pcl
 503 </pre>
 504
 505 <p><a href='#TABLE_1'>Table 1</a> shows the driver types for each of the standard CUPS raster filters. For drivers that do not use the standard raster filters, the "custom" type is used with <a href='ref-ppdcfile.html#Filter'><tt>Filter</tt></a> directives:</p>
 506
 507 <pre class='example'>
 508 <a href='ref-ppdcfile.html#DriverType'>DriverType</a> custom
 509 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 /path/to/raster/filter
 510 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-command 100 /path/to/command/filter
 511 </pre>
 512
 513
 514 <h2 class='title'><a name='COLOR'>Implementing Color Management</a></h2>
 515
 516 <p>Talk about ICC color profiles and sRGB as two best options.</p>
 517
 518
 519 <h2 class='title'><a name='MACOSX'>Adding Mac OS X Features</a></h2>
 520
 521 <p>Talk about help books, icons, and PDEs.</p>
 522
 523
 524 <h2 class='title'><a name='DEPLOY'>Deploying Your Driver</a></h2>
 525
 526 <p>Talk about install locations, etc.</p>
 527 </div>
 528 </body>
 529 </html>