]> git.ipfire.org Git - thirdparty/cups.git/blob - doc/help/postscript-driver.html
Merge changes from CUPS 1.4svn-r8329.
[thirdparty/cups.git] / doc / help / postscript-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 PostScript 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 PostScript printers. Topics include: <a href='#BASICS'>printer driver basics</a>, <a href='#CREATE'>creating new PPD files</a>, <a href='#IMPORT'>importing existing PPD files</a>, <a href='#FILTERS'>using custom 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='raster-driver.html'>Developing Raster 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><ul class="subcontents">
353 <li><a href="#IMPORT">Importing Existing PPD Files</a></li>
354 </ul></li>
355 <li><a href="#FILTERS">Using Custom Filters</a></li>
356 <li><a href="#COLOR">Implementing Color Management</a></li>
357 <li><a href="#MACOSX">Adding Mac OS X Features</a></li>
358 <li><a href="#DEPLOY">Deploying Your Driver</a></li>
359 <h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2>
360
361 <p>A CUPS PostScript printer driver consists of a PostScript Printer Description (PPD) file that describes the features and capabilities of the device, zero 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>
362
363 <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 device-independent PostScript, and then from device-independent PostScript to device-dependent PostScript. <a href='#FIGURE_1'>Figure 1</a> shows the data flow of a typical print job.</p>
364
365 <div class='figure'><table summary='PostScript Filter Chain'>
366 <caption>Figure 1: <a name='FIGURE_1'>PostScript Filter Chain</a></caption>
367 <tr><td><img src='/images/cups-postscript-chain.png' width='700' height='150' alt='PostScript Filter Chain'></td></tr>
368 </table></div>
369
370 <p>The optional PostScript filter can be provided to add printer-specific commands to the PostScript output that cannot be represented in the PPD file or to reorganize the output for special printer features. Typically this is used to support advanced job management or finishing functions on the printer. CUPS includes a generic PostScript filter that handles all PPD-defined commands.</p>
371
372 <p>The optional port monitor handles interface-specific protocol or encoding issues. For example, many PostScript printers support the Binary Communications Protocol (BCP) and Tagged Binary Communications Protocol (TBCP) to allow applications to print 8-bit ("binary") PostScript jobs. CUPS includes port monitors for BCP and TBCP, and you can supply your own port monitors as needed.</p>
373
374 <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>
375
376 <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>
377
378 <div class='figure'><table summary='Command Filter Chain'>
379 <caption>Figure 2: <a name='FIGURE_2'>Command Filter Chain</a></caption>
380 <tr><td><img src='/images/cups-command-chain.png' width='575' height='150' alt='Command Filter Chain'></td></tr>
381 </table></div>
382
383 <p>PostScript printer drivers typically do not require their own command filter since CUPS includes a generic PostScript command filter that supports all of the standard functions using PPD-defined commands.</p>
384
385
386 <h2 class='title'><a name='CREATING'>Creating New PPD Files</a></h2>
387
388 <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 a black-and-white PostScript printer.</p>
389
390 <p class='example'>Listing 1: <a name='LISTING_1'>"examples/postscript.drv"</a></p>
391
392 <pre class='example'>
393 // Include standard font and media definitions
394 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
395 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
396
397 // Specify this is a PostScript printer driver
398 <a href='ref-ppdcfile.html#DriverType'>DriverType</a> ps
399
400 // List the fonts that are supported, in this case all standard fonts
401 <a href='ref-ppdcfile.html#Font'>Font</a> *
402
403 // Manufacturer, model name, and version
404 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
405 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "Foo LaserProofer 2000"
406 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
407
408 // PostScript printer attributes
409 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> DefaultColorSpace "" Gray
410 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LandscapeOrientation "" Minus90
411 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LanguageLevel "" "3"
412 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> Product "" "(Foo LaserProofer 2000)"
413 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> PSVersion "" "(3010) 0"
414 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> TTRasterizer "" Type42
415
416 // Supported page sizes
417 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
418 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Legal
419 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
420
421 // Query command for page size
422 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> "?PageSize" "" "
423 save
424 currentpagedevice /PageSize get aload pop
425 2 copy gt {exch} if (Unknown)
426 23 dict
427 dup [612 792] (Letter) put
428 dup [612 1008] (Legal) put
429 dup [595 842] (A4) put
430 {exch aload pop 4 index sub abs 5 le exch
431 5 index sub abs 5 le and
432 {exch pop exit} {pop} ifelse
433 } bind forall = flush pop pop
434 restore"
435
436 // Specify the name of the PPD file we want to generate
437 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "fooproof.ppd"
438 </pre>
439
440 <h3>Required Attributes</h3>
441
442 <p>PostScript drivers require the attributes listed in <a href='#TABLE_1'>Table 1</a>. If not specified, the defaults for CUPS drivers are used. A typical PostScript driver information file would include the following attributes:</p>
443
444 <pre class='example'>
445 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> DefaultColorSpace "" Gray
446 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LandscapeOrientation "" Minus90
447 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LanguageLevel "" "3"
448 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> Product "" "(Foo LaserProofer 2000)"
449 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> PSVersion "" "(3010) 0"
450 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> TTRasterizer "" Type42
451 </pre>
452
453 <div class='table'><table summary='Required PostScript Printer Driver Attributes'>
454 <caption>Table 1: <a name='TABLE_1'>Required PostScript Printer Driver Attributes</a></caption>
455 <thead>
456 <tr>
457 <th>Attribute</th>
458 <th>Description</th>
459 </tr>
460 </thead>
461 <tbody>
462 <tr>
463 <td><tt>DefaultColorSpace</tt></td>
464 <td>The default colorspace:
465 <tt>Gray</tt>, <tt>RGB</tt>, <tt>CMY</tt>, or
466 <tt>CMYK</tt>. If not specified, then <tt>RGB</tt> is
467 assumed.</td>
468 </tr>
469 <tr>
470 <td><tt>LandscapeOrientation</tt></td>
471 <td>The preferred landscape
472 orientation: <tt>Plus90</tt>, <tt>Minus90</tt>, or
473 <tt>Any</tt>. If not specified, <tt>Plus90</tt> is
474 assumed.</td>
475 </tr>
476 <tr>
477 <td><tt>LanguageLevel</tt></td>
478 <td>The PostScript language
479 level supported by the device: 1, 2, or 3. If not
480 specified, 2 is assumed.</td>
481 </tr>
482 <tr>
483 <td><tt>Product</tt></td>
484 <td>The string returned by
485 the PostScript <tt>product</tt> operator, which
486 <i>must</i> include parenthesis to conform with
487 PostScript syntax rules for strings. Multiple
488 <tt>Product</tt> attributes may be specified to support
489 multiple products with the same PPD file. If not
490 specified, "(ESP Ghostscript)" and "(GNU Ghostscript)"
491 are assumed.</td>
492 </tr>
493 <tr>
494 <td><tt>PSVersion</tt></td>
495 <td>The PostScript
496 interpreter version numbers as returned by the
497 <tt>version</tt> and <tt>revision</tt> operators. The
498 required format is "(version) revision". Multiple
499 <tt>PSVersion</tt> attributes may be specified to
500 support multiple interpreter version numbers. If not
501 specified, "(3010) 705" and "(3010) 707" are
502 assumed.</td>
503 </tr>
504 <tr>
505 <td><tt>TTRasterizer</tt></td>
506 <td>The type of TrueType
507 font rasterizer supported by the device, if any. The
508 supported values are <tt>None</tt>, <tt>Accept68k</tt>,
509 <tt>Type42</tt>, and <tt>TrueImage</tt>. If not
510 specified, <tt>None</tt> is assumed.</td>
511 </tr>
512 </table></div>
513
514 <h3>Query Commands</h3>
515
516 <p>Most PostScript printer PPD files include query commands (<tt>?PageSize</tt>, etc.) that allow applications to query the printer for its current settings and configuration. Query commands are included in driver information files as attributes. For example, the example in <a href='#LISTING_1'>Listing 1</a> uses the following definition for the <tt>PageSize</tt> query command:</p>
517
518 <pre class='example'>
519 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> "?PageSize" "" "
520 save
521 currentpagedevice /PageSize get aload pop
522 2 copy gt {exch} if (Unknown)
523 23 dict
524 dup [612 792] (Letter) put
525 dup [612 1008] (Legal) put
526 dup [595 842] (A4) put
527 {exch aload pop 4 index sub abs 5 le exch
528 5 index sub abs 5 le and
529 {exch pop exit} {pop} ifelse
530 } bind forall = flush pop pop
531 restore"
532 </pre>
533
534 <p>Query commands can span multiple lines, however no single line may contain more than 255 characters.</p>
535
536 <h3><a name='IMPORT'>Importing Existing PPD Files</a></h3>
537
538 <P>CUPS includes a utility called <a href='man-ppdi.html'>ppdi(1)</a>
539 which allows you to import existing PPD files into the driver information file
540 format used by the PPD compiler <a href='man-ppdc.html'>ppdc(1)</a>. Once
541 imported, you can modify, localize, and regenerate the PPD files easily. Type
542 the following command to import the PPD file <VAR>mydevice.ppd</VAR> into the
543 driver information file <VAR>mydevice.drv</VAR>:</P>
544
545 <pre class='command'>
546 ppdi -o mydevice.drv mydevice.ppd
547 </pre>
548
549 <P>If you have a whole directory of PPD files that you would like to import,
550 you can list multiple filenames or use shell wildcards to import more than one
551 PPD file on the command-line:</P>
552
553 <pre class='command'>
554 ppdi -o mydevice.drv mydevice1.ppd mydevice2.ppd
555 ppdi -o mydevice.drv *.ppd
556 </pre>
557
558 <P>If the driver information file already exists, the new PPD
559 file entries are appended to the end of the file. Each PPD file
560 is placed in its own group of curly braces within the driver
561 information file.</P>
562
563
564 <h2 class='title'><a name='FILTERS'>Using Custom Filters</a></h2>
565
566 <p>Normally a PostScript printer driver will not utilize any additional print filters. For drivers that provide additional filters such as a CUPS command file filter for doing printer maintenance, you must also list the following <tt>Filter</tt> directive to handle printing PostScript files:</p>
567
568 <pre class='example'>
569 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-postscript 0 -
570 </pre>
571
572 <h3>Custom Command Filters</h3>
573
574 <p>The <tt>application/vnd.cups-command</tt> file type is used for CUPS command files. Use the following <tt>Filter</tt> directive to handle CUPS command files:</p>
575
576 <pre class='example'>
577 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-command 100 /path/to/command/filter
578 </pre>
579
580 <p>To use the standard PostScript command filter, specify <var>commandtops</var> as the path to the command filter.</p>
581
582 <h3>Custom PDF Filters</h3>
583
584 <p>The <tt>application/pdf</tt> file type is used for unfiltered PDF files while the <tt>application/vnd.cups-pdf</tt> file type is used for filtered PDF files. Use the following <tt>Filter</tt> directive to handle filtered PDF files:</p>
585
586 <pre class='example'>
587 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-pdf 100 /path/to/pdf/filter
588 </pre>
589
590 <p>For unfiltered PDF files, use:</p>
591
592 <pre class='example'>
593 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/pdf 100 /path/to/pdf/filter
594 </pre>
595
596 <p>Custom PDF filters that accept filtered data do not need to perform number-up processing and other types of page imposition, while those that accept unfiltered data MUST do the number-up processing themselves.</p>
597
598 <h3>Custom PostScript Filters</h3>
599
600 <p>The <tt>application/vnd.cups-postscript</tt> file type is used for filtered PostScript files. Use the following <tt>Filter</tt> directive to handle PostScript files:</p>
601
602 <pre class='example'>
603 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-postscript 100 /path/to/postscript/filter
604 </pre>
605
606
607 <h2 class='title'><a name='COLOR'>Implementing Color Management</a></h2>
608
609 <p>Talk about ICC color profiles and sRGB as two best options.</p>
610
611
612 <h2 class='title'><a name='MACOSX'>Adding Mac OS X Features</a></h2>
613
614 <p>Talk about help books, icons, and PDEs.</p>
615
616
617 <h2 class='title'><a name='DEPLOY'>Deploying Your Driver</a></h2>
618
619 <p>Talk about install locations, etc.</p>
620 </div>
621 </body>
622 </html>