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