]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/help/raster-driver.html
projects / thirdparty / cups.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge changes from CUPS 1.4svn-r8177 (tentative CUPS 1.4b2)
[thirdparty/cups.git] / doc / help / raster-driver.html
CommitLineData
8b450588
MS		 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
2<html>
e4572d57 3<!-- SECTION: Programming -->
8b450588
MS		 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"><!--
9BODY {
10 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
11}
12
13H1, H2, H3, H4, H5, H6, P, TD, TH {
14 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
15}
16
17KBD {
18 font-family: monaco, courier, monospace;
19 font-weight: bold;
20}
21
22PRE {
23 font-family: monaco, courier, monospace;
24}
e4572d57 25
8b450588
MS		 26PRE.command {
27 margin-left: 36pt;
28}
29
30P.example {
31 font-style: italic;
32 margin-left: 36pt;
33}
34
35PRE.example {
36 background: #eeeeee;
37 border: dotted thin #999999;
38 margin-left: 36pt;
39 padding: 10px;
40}
41
42PRE.command EM, PRE.example EM {
43 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
44}
45
46P.command {
47 font-family: monaco, courier, monospace;
48 margin-left: 36pt;
49}
50
51P.formula {
52 font-style: italic;
53 margin-left: 36pt;
54}
55
56BLOCKQUOTE {
57 background: #cccccc;
58 border: solid thin #999999;
59 padding: 10pt;
60}
61
62A IMG {
63 border: none;
64}
65
66A:link:hover IMG {
67 background: #f0f0f0;
68 border-radius: 10px;
69 -moz-border-radius: 10px;
70}
71
72A:link, A:visited {
73 font-weight: normal;
74 text-decoration: none;
75}
76
77A:link:hover, A:visited:hover, A:active {
78 text-decoration: underline;
79}
80
81SUB, SUP {
82 font-size: 50%;
83}
84
85TR.data, TD.data, TR.data TD {
86 margin-top: 10pt;
87 padding: 5pt;
88 border-bottom: solid 1pt #999999;
89}
90
91TR.data TH {
92 border-bottom: solid 1pt #999999;
93 padding-top: 10pt;
94 padding-left: 5pt;
95 text-align: left;
96}
97
98DIV.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
106DIV.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
115DIV.table TABLE TD {
116 border: solid thin #cccccc;
117 padding-top: 5pt;
118}
119
120DIV.table TABLE TH {
121 background: #cccccc;
122 border: none;
123 border-bottom: solid thin #999999;
124}
125
126DIV.figure TABLE {
127 margin-left: auto;
128 margin-right: auto;
129}
130
131DIV.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
140TH.label {
141 text-align: right;
142 vertical-align: top;
143}
144
145TH.sublabel {
146 text-align: right;
147 font-weight: normal;
148}
149
150HR {
151 border: solid thin;
152}
153
154SPAN.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
164H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
165 float: right;
166 font-size: 100%;
167}
168
169H2.title, H3.title {
170 border-bottom: solid 2pt #000000;
171}
172
173DIV.indent, TABLE.indent {
174 margin-top: 2em;
175 margin-left: auto;
176 margin-right: auto;
177 width: 90%;
178}
179
180TABLE.indent {
181 border-collapse: collapse;
182}
183
184TABLE.indent TD, TABLE.indent TH {
185 padding: 0;
186}
187
188TABLE.list {
189 border-collapse: collapse;
190 margin-left: auto;
191 margin-right: auto;
192 width: 90%;
193}
194
195TABLE.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
206TABLE.list TH A {
207 color: #4444cc;
208}
209
210TABLE.list TD {
211 border-bottom: solid thin #eeeeee;
212 padding-top: 5pt;
213 padding-left: 5pt;
214}
215
216TABLE.list TR:nth-child(even) {
217 background: #f8f8f8;
218}
219
220TABLE.list TR:nth-child(odd) {
221 background: #f4f4f4;
222}
223
224DT {
225 margin-left: 36pt;
226 margin-top: 12pt;
227}
228
229DD {
230 margin-left: 54pt;
231}
232
233DL.category DT {
234 font-weight: bold;
235}
236
237P.summary {
238 margin-left: 36pt;
239 font-family: monaco, courier, monospace;
240}
241
242DIV.summary TABLE {
243 border: solid thin #999999;
244 border-collapse: collapse;
245 border-spacing: 0;
246 margin: 10px;
247}
248
249DIV.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
256DIV.summary TABLE THEAD TH {
257 background: #eeeeee;
258}
259
260/* API documentation styles... */
261div.body h1 {
262 margin: 0;
263}
264div.body h2 {
265 margin-top: 1.5em;
266}
267div.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}
279code, p.code, pre, ul.code li {
280 font-family: monaco, courier, monospace;
281 font-size: 90%;
282}
283ul.code, ul.contents, ul.subcontents {
284 list-style-type: none;
285 margin: 0;
286 padding-left: 0;
287}
288ul.code li {
289 margin: 0;
290}
291ul.contents > li {
292 margin-top: 1em;
293}
294ul.contents li ul.code, ul.contents li ul.subcontents {
295 padding-left: 2em;
296}
297div.body dl {
298 margin-left: 0;
299 margin-top: 0;
300}
301div.body dt {
302 font-style: italic;
303 margin-left: 0;
304 margin-top: 0;
305}
306div.body dd {
307 margin-bottom: 0.5em;
308}
309
310/* This is just for the HTML files generated with the framedhelp target */
311div.contents {
312 background: #e8e8e8;
313 border: solid thin black;
314 padding: 10px;
315}
316div.contents h1 {
317 font-size: 110%;
318}
319div.contents h2 {
320 font-size: 100%;
321}
322div.contents ul.contents {
323 font-size: 80%;
324}
325div.contents ul.subcontents li {
326 margin-left: 1em;
327 text-indent: -1em;
328}
329--></style>
330</head>
331<body>
332<div class='body'>
e4572d57
MS		 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>
8b450588
MS		 348<h2 class="title">Contents</h2>
349<ul class="contents">
426c6a59 350<ul class="subcontents">
8b450588
MS		 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>
e4572d57
MS		 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>
8b450588 527</div>
e4572d57
MS		 528</body>
529</html>
Unnamed repository; edit this file 'description' to name the repository.