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