]> 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-r8606.
[thirdparty/cups.git] / doc / help / raster-driver.html
CommitLineData
745129be 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
8b450588 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
f11a948a
MS		 30P.compact {
31 margin: 0;
32}
33
8b450588
MS		 34P.example {
35 font-style: italic;
36 margin-left: 36pt;
37}
38
39PRE.example {
40 background: #eeeeee;
41 border: dotted thin #999999;
42 margin-left: 36pt;
43 padding: 10px;
44}
45
46PRE.command EM, PRE.example EM {
47 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
48}
49
50P.command {
51 font-family: monaco, courier, monospace;
52 margin-left: 36pt;
53}
54
55P.formula {
56 font-style: italic;
57 margin-left: 36pt;
58}
59
60BLOCKQUOTE {
61 background: #cccccc;
62 border: solid thin #999999;
63 padding: 10pt;
64}
65
66A IMG {
67 border: none;
68}
69
70A:link:hover IMG {
71 background: #f0f0f0;
72 border-radius: 10px;
73 -moz-border-radius: 10px;
74}
75
76A:link, A:visited {
77 font-weight: normal;
78 text-decoration: none;
79}
80
81A:link:hover, A:visited:hover, A:active {
82 text-decoration: underline;
83}
84
85SUB, SUP {
86 font-size: 50%;
87}
88
89TR.data, TD.data, TR.data TD {
90 margin-top: 10pt;
91 padding: 5pt;
92 border-bottom: solid 1pt #999999;
93}
94
95TR.data TH {
96 border-bottom: solid 1pt #999999;
97 padding-top: 10pt;
98 padding-left: 5pt;
99 text-align: left;
100}
101
102DIV.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
110DIV.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
119DIV.table TABLE TD {
120 border: solid thin #cccccc;
121 padding-top: 5pt;
122}
123
124DIV.table TABLE TH {
125 background: #cccccc;
126 border: none;
127 border-bottom: solid thin #999999;
128}
129
130DIV.figure TABLE {
131 margin-left: auto;
132 margin-right: auto;
133}
134
135DIV.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
144TH.label {
145 text-align: right;
146 vertical-align: top;
147}
148
149TH.sublabel {
150 text-align: right;
151 font-weight: normal;
152}
153
154HR {
155 border: solid thin;
156}
157
158SPAN.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
168H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
169 float: right;
170 font-size: 100%;
171}
172
173H2.title, H3.title {
174 border-bottom: solid 2pt #000000;
175}
176
177DIV.indent, TABLE.indent {
178 margin-top: 2em;
179 margin-left: auto;
180 margin-right: auto;
181 width: 90%;
182}
183
184TABLE.indent {
185 border-collapse: collapse;
186}
187
188TABLE.indent TD, TABLE.indent TH {
189 padding: 0;
190}
191
192TABLE.list {
193 border-collapse: collapse;
194 margin-left: auto;
195 margin-right: auto;
196 width: 90%;
197}
198
199TABLE.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
210TABLE.list TH A {
211 color: #4444cc;
212}
213
214TABLE.list TD {
215 border-bottom: solid thin #eeeeee;
216 padding-top: 5pt;
217 padding-left: 5pt;
218}
219
220TABLE.list TR:nth-child(even) {
221 background: #f8f8f8;
222}
223
224TABLE.list TR:nth-child(odd) {
225 background: #f4f4f4;
226}
227
228DT {
229 margin-left: 36pt;
230 margin-top: 12pt;
231}
232
233DD {
234 margin-left: 54pt;
235}
236
237DL.category DT {
238 font-weight: bold;
239}
240
241P.summary {
242 margin-left: 36pt;
243 font-family: monaco, courier, monospace;
244}
245
246DIV.summary TABLE {
247 border: solid thin #999999;
248 border-collapse: collapse;
249 border-spacing: 0;
250 margin: 10px;
251}
252
253DIV.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
260DIV.summary TABLE THEAD TH {
261 background: #eeeeee;
262}
263
264/* API documentation styles... */
265div.body h1 {
266 margin: 0;
267}
268div.body h2 {
269 margin-top: 1.5em;
270}
271div.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}
283code, p.code, pre, ul.code li {
284 font-family: monaco, courier, monospace;
285 font-size: 90%;
286}
287ul.code, ul.contents, ul.subcontents {
288 list-style-type: none;
289 margin: 0;
290 padding-left: 0;
291}
292ul.code li {
293 margin: 0;
294}
295ul.contents > li {
296 margin-top: 1em;
297}
298ul.contents li ul.code, ul.contents li ul.subcontents {
299 padding-left: 2em;
300}
301div.body dl {
302 margin-left: 0;
303 margin-top: 0;
304}
305div.body dt {
306 font-style: italic;
307 margin-left: 0;
308 margin-top: 0;
309}
310div.body dd {
311 margin-bottom: 0.5em;
312}
313
314/* This is just for the HTML files generated with the framedhelp target */
315div.contents {
316 background: #e8e8e8;
317 border: solid thin black;
318 padding: 10px;
319}
320div.contents h1 {
321 font-size: 110%;
322}
323div.contents h2 {
324 font-size: 100%;
325}
326div.contents ul.contents {
327 font-size: 80%;
328}
329div.contents ul.subcontents li {
330 margin-left: 1em;
331 text-indent: -1em;
332}
333--></style>
334</head>
335<body>
336<div class='body'>
e4572d57
MS		 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>
8b450588
MS		 352<h2 class="title">Contents</h2>
353<ul class="contents">
426c6a59 354<ul class="subcontents">
8b450588
MS		 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>
e4572d57
MS		 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>
8b450588 531</div>
e4572d57
MS		 532</body>
533</html>
Unnamed repository; edit this file 'description' to name the repository.