[thirdparty/cups.git] / doc / help / raster-driver.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
<title>Developing Raster Printer Drivers</title>
<meta name="keywords" content="Programming">
<meta name="creator" content="Mini-XML v2.6">
<style type="text/css"><!--
BODY {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

H1, H2, H3, H4, H5, H6, P, TD, TH {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

KBD {
  font-family: monaco, courier, monospace;
  font-weight: bold;
}

PRE {
  font-family: monaco, courier, monospace;
}

PRE.command {
  margin-left: 36pt;
}

P.compact {
  margin: 0;
}

P.example {
  font-style: italic;
  margin-left: 36pt;
}
  
PRE.example {
  background: #eeeeee;
  border: dotted thin #999999;
  margin-left: 36pt;
  padding: 10pt;
}

PRE.command EM, PRE.example EM {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

P.command {
  font-family: monaco, courier, monospace;
  margin-left: 36pt;
}

P.formula {
  font-style: italic;
  margin-left: 36pt;
}

BLOCKQUOTE {
  background: #eeeeee;
  border: solid thin #999999;
  padding: 10pt;
}

A IMG {
  border: none;
}

A:link:hover IMG {
  background: #f0f0f0;
  border-radius: 10px;
  -moz-border-radius: 10px;
}

A:link, A:visited {
  font-weight: normal;
  text-decoration: none;
}

A:link:hover, A:visited:hover, A:active {
  text-decoration: underline;
}

SUB, SUP {
  font-size: 50%;
}

TR.data, TD.data, TR.data TD {
  margin-top: 10pt;
  padding: 5pt;
  border-bottom: solid 1pt #999999;
}

TR.data TH {
  border-bottom: solid 1pt #999999;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
}

DIV.table TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin-left: auto;
  margin-right: auto;
}

DIV.table CAPTION {
  caption-side: top;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

DIV.table TABLE TD {
  border: solid thin #cccccc;
  padding-top: 5pt;
}

DIV.table TABLE TH {
  background: #cccccc;
  border: none;
  border-bottom: solid thin #999999;
}

DIV.figure TABLE {
  margin-left: auto;
  margin-right: auto;
}

DIV.figure CAPTION {
  caption-side: bottom;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

TH.label {
  text-align: right;
  vertical-align: top;
}

TH.sublabel {
  text-align: right;
  font-weight: normal;
}

HR {
  border: solid thin;
}

SPAN.info {
  background: black;
  border: thin solid black;
  color: white;
  font-size: 80%;
  font-style: italic;
  font-weight: bold;
  white-space: nowrap;
}

H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
  float: right;
  font-size: 100%;
}

H1.title {
}

H2.title, H3.title {
  border-bottom: solid 2pt #000000;
}

DIV.indent, TABLE.indent {
  margin-top: 2em;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.indent {
  border-collapse: collapse;
}

TABLE.indent TD, TABLE.indent TH {
  padding: 0;
}

TABLE.list {
  border-collapse: collapse;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.list TH {
  background: white;
  border-bottom: solid thin #cccccc;
  color: #444444;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
  vertical-align: bottom;
  white-space: nowrap;
}

TABLE.list TH A {
  color: #4444cc;
}

TABLE.list TD {
  border-bottom: solid thin #eeeeee;
  padding-top: 5pt;
  padding-left: 5pt;
}

TABLE.list TR:nth-child(even) {
  background: #f8f8f8;
}

TABLE.list TR:nth-child(odd) {
  background: #f4f4f4;
}

DT {
  margin-left: 36pt;
  margin-top: 12pt;
}

DD {
  margin-left: 54pt;
}

DL.category DT {
  font-weight: bold;
}

P.summary {
  margin-left: 36pt;
  font-family: monaco, courier, monospace;
}

DIV.summary TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin: 10px;
}

DIV.summary TABLE TD, DIV.summary TABLE TH {
  border: solid thin #999999;
  padding: 5px;
  text-align: left;
  vertical-align: top;
}

DIV.summary TABLE THEAD TH {
  background: #eeeeee;
}

/* API documentation styles... */
div.body h1 {
  margin: 0;
}
div.body h2 {
  margin-top: 1.5em;
}
div.body h3, div.body h4, div.body h5 {
  margin-bottom: 0.5em;
  margin-top: 1.5em;
}
.class, .enumeration, .function, .struct, .typedef, .union {
  border-bottom: solid thin #999999;
  margin-bottom: 0;
  margin-top: 2em;
}
.description {
  margin-top: 0.5em;
}
code, p.code, pre, ul.code li {
  font-family: monaco, courier, monospace;
  font-size: 90%;
}
ul.code, ul.contents, ul.subcontents {
  list-style-type: none;
  margin: 0;
  padding-left: 0;
}
ul.code li {
  margin: 0;
}
ul.contents > li {
  margin-top: 1em;
}
ul.contents li ul.code, ul.contents li ul.subcontents {
  padding-left: 2em;
}
div.body dl {
  margin-left: 0;
  margin-top: 0;
}
div.body dt {
  font-style: italic;
  margin-left: 0;
  margin-top: 0;
}
div.body dd {
  margin-bottom: 0.5em;
}

/* This is just for the HTML files generated with the framedhelp target */
div.contents {
  background: #e8e8e8;
  border: solid thin black;
  padding: 10px;
}
div.contents h1 {
  font-size: 110%;
}
div.contents h2 {
  font-size: 100%;
}
div.contents ul.contents {
  font-size: 80%;
}
div.contents ul.subcontents li {
  margin-left: 1em;
  text-indent: -1em;
}
--></style>
</head>
<body>
<div class='body'>
<h1 class='title'>Developing Raster Printer Drivers</h1>

<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>, and <a href='#MACOSX'>adding Mac OS X features</a>.</p>

<div class='summary'><table summary='General Information'>
<tbody>
<tr>
	<th>See Also</th>
	<td>Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br>
	Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br>
	Programming: <a href='ppd-compiler.html'>Introduction to the PPD Compiler</a><br>
	Programming: <a href='api-raster.html'>Raster API</a><br>
	References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a><br>
	Specifications: <a href='spec-ppd.html'>CUPS PPD Extensions</a></td>
</tr>
</tbody>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
<ul class="subcontents">
<li><a href="#BASICS">Printer Driver Basics</a></li>
<li><a href="#CREATING">Creating New PPD Files</a></li>
<li><a href="#FILTERS">Using Filters</a></li>
<li><a href="#COLOR">Implementing Color Management</a></li>
<li><a href="#MACOSX">Adding Mac OS X Features</a></li>
<h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2>

<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>

<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>

<div class='figure'><table summary='Raster Filter Chain'>
<caption>Figure 1: <a name='FIGURE_1'>Raster Filter Chain</a></caption>
<tr><td><img src='/images/cups-raster-chain.png' width='700' height='150' alt='Raster Filter Chain'></td></tr>
</table></div>

<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>

<div class='table'><table summary='Standard CUPS Raster Filters'>
<caption>Table 1: <a name='TABLE_1'>Standard CUPS Raster Filters</a></caption>
<thead>
<tr><th>Filter</th><th>PDLs</th><th>ppdc DriverType</th><th>ppdc #include file</th></tr>
</thead>
<tbody>
<tr><td>rastertoepson</td><td>ESC/P, ESC/P2</td><td>epson</td><td>epson.h</td></tr>
<tr><td>rastertoescpx</td><td>ESC/P, ESC/P2, EPSON Remote Mode</td><td>escp</td><td>escp.h</td></tr>
<tr><td>rastertohp</td><td>HP-PCL3, HP-PCL5</td><td>hp</td><td>hp.h</td></tr>
<tr><td>rastertolabel</td><td>CPCL, Dymo, EPL1, EPL2, Intellitech PCL, ZPL</td><td>label</td><td>label.h</td></tr>
<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>
</tbody>
</table></div>

<p>The optional port monitor handles interface-specific protocol or encoding issues. For example, some raster printers use the 1284.4 communications protocol.</p>

<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>

<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>

<div class='figure'><table summary='Command Filter Chain'>
<caption>Figure 2: <a name='FIGURE_2'>Command Filter Chain</a></caption>
<tr><td><img src='/images/cups-command-chain.png' width='575' height='150' alt='Command Filter Chain'></td></tr>
</table></div>

<p>Raster printer drivers must provide their own command filter.</p>


<h2 class='title'><a name='CREATING'>Creating New PPD Files</a></h2>

<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>

<p class='example'>Listing 1: <a name='LISTING_1'>"examples/laserjet-basic.drv"</a></p>

<pre class='example'>
<I>// Include standard font and media definitions</I>
<a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
<a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;

<I>// Include HP-PCL driver definitions</I>
<a href='ref-ppdcfile.html#_include'>#include</a> &lt;pcl.h&gt;

<I>// Specify that this driver uses the HP-PCL driver...</I>
<a href='ref-ppdcfile.html#DriverType'>DriverType</a> pcl

<I>// Specify the driver options via the model number...</I>
<a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> ($PCL_PAPER_SIZE $PCL_PJL $PCL_PJL_RESOLUTION)

<I>// List the fonts that are supported, in this case all standard fonts...</I>
<a href='ref-ppdcfile.html#Font'>Font</a> *

<I>// Manufacturer and driver version</I>
<a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "HP"
<a href='ref-ppdcfile.html#Version'>Version</a> 1.0

<I>// Supported page sizes and their margins</I>
<a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 18 12 18 12
*<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Legal
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Executive
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Monarch
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Statement
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> FanFoldGermanLegal

<a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 18 12.72 18 12.72
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Env10

<a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 9.72 12 9.72 12
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A5
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> B5
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvC5
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvDL
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvISOB5
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Postcard
<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> DoublePostcard

<I>// Only black-and-white output with mode 3 compression...</I>
<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray k chunky 3

<I>// Supported resolutions</I>
<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 1 0 0 0 "300dpi/300 DPI"
*<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "600dpi/600 DPI"

<I>// Supported input slots</I>
*<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 7 "Auto/Automatic Selection"
<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 2 "Manual/Tray 1 - Manual Feed"
<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 4 "Upper/Tray 1"
<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 1 "Lower/Tray 2"
<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 5 "LargeCapacity/Tray 3"

<I>// Tray 3 is an option...</I>
<a href='ref-ppdcfile.html#Installable'>Installable</a> "OptionLargeCapacity/Tray 3 Installed"
<a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*OptionLargeCapacity False *InputSlot LargeCapacity"

{
  <I>// HP LaserJet 2100 Series</I>
  <a href='ref-ppdcfile.html#Throughput'>Throughput</a> 10
  <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2100 Series"
  <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt211.ppd"
}

{
  <I>// LaserJet 2200 and 2300 series have duplexer option...</I>
  <a href='ref-ppdcfile.html#Duplex'>Duplex</a> normal
  <a href='ref-ppdcfile.html#Installable'>Installable</a> "OptionDuplex/Duplexer Installed"
  <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*OptionDuplex False *Duplex"

  {
    <I>// HP LaserJet 2200 Series</I>
    <a href='ref-ppdcfile.html#Throughput'>Throughput</a> 19
    <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2200 Series"
    <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt221.ppd"
  }

  {
    <I>// HP LaserJet 2300 Series</I>
    <a href='ref-ppdcfile.html#Throughput'>Throughput</a> 25
    <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2300 Series"
    <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt231.ppd"
  }
}
</pre>


<h2 class='title'><a name='FILTERS'>Using Filters</a></h2>

<p>The standard CUPS raster filters can be specified using the
<a href='ref-ppdcfile.html#DriverType'><tt>DriverType</tt></a> directive, for example:</p>

<pre class='example'>
<I>// Specify that this driver uses the HP-PCL driver...</I>
<a href='ref-ppdcfile.html#DriverType'>DriverType</a> pcl
</pre>

<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>

<pre class='example'>
<a href='ref-ppdcfile.html#DriverType'>DriverType</a> custom
<a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 /path/to/raster/filter
<a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-command 100 /path/to/command/filter
</pre>


<h2 class='title'><a name='COLOR'>Implementing Color Management</a></h2>

<p>CUPS uses ICC color profiles to provide more accurate color reproduction. The <a href='spec-ppd.html#cupsICCProfile'><tt>cupsICCProfile</tt></a> attribute defines the color profiles that are available for a given printer, for example:</p>

<pre class='example'>
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "ColorModel.MediaType.Resolution/Description" /path/to/ICC/profile
</pre>

<p>where "ColorModel.MediaType.Resolution" defines a selector based on the corresponding option selections. A simple driver might only define profiles for the color models that are supported, for example a printer supporting Gray and RGB might use:</p>

<pre class='example'>
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "Gray../Grayscale Profile" /path/to/ICC/gray-profile
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "RGB../Full Color Profile" /path/to/ICC/rgb-profile
</pre>

<p>The options used for profile selection can be customized using the <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> attributes.</p>

<h3><span class='info'>Since Mac OS X 10.5</span>Custom Color Matching Support</h3>

<p>Mac OS X printer drivers that are based on an existing standard RGB colorspace can tell the system to use the corresponding colorspace instead of an arbitrary ICC color profile when doing color management. The <a href='#APCustom'><tt>APSupportsCustomColorMatching</tt></a> and <tt>APDefaultCustomColorMatchingProfile</tt> attributes can be used to enable this mode:</p>

<pre class='example'>
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APSupportsCustomColorMatching "" true
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APDefaultCustomColorMatchingProfile "" sRGB
</pre>


<h2 class='title'><a name='MACOSX'>Adding Mac OS X Features</a></h2>

<p>Mac OS X printer drivers can provide <a href='spec-ppd.html#MACOSX'>additional attributes</a> to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:</p>

<pre class='example'>
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APDialogExtension "" /Library/Printers/Vendor/filename.plugin
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APHelpBook "" /Library/Printers/Vendor/filename.bundle
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APPrinterIconPath "" /Library/Printers/Vendor/filename.icns
<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APPrinterPreset "name/text" "*option choice ..."
</pre>
</div>
</body>
</html>
Commit	Line	Data
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"><!--
	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	}
e4572d57	25
8b450588 MS	26	PRE.command {
	27	margin-left: 36pt;
	28	}
	29
f11a948a MS	30	P.compact {
	31	margin: 0;
	32	}
	33
8b450588 MS	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;
178cb736	43	padding: 10pt;
8b450588 MS	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 {
178cb736	61	background: #eeeeee;
8b450588 MS	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
178cb736 MS	173	H1.title {
	174	}
	175
8b450588 MS	176	H2.title, H3.title {
	177	border-bottom: solid 2pt #000000;
	178	}
	179
	180	DIV.indent, TABLE.indent {
	181	margin-top: 2em;
	182	margin-left: auto;
	183	margin-right: auto;
	184	width: 90%;
	185	}
	186
	187	TABLE.indent {
	188	border-collapse: collapse;
	189	}
	190
	191	TABLE.indent TD, TABLE.indent TH {
	192	padding: 0;
	193	}
	194
	195	TABLE.list {
	196	border-collapse: collapse;
	197	margin-left: auto;
	198	margin-right: auto;
	199	width: 90%;
	200	}
	201
	202	TABLE.list TH {
	203	background: white;
	204	border-bottom: solid thin #cccccc;
	205	color: #444444;
	206	padding-top: 10pt;
	207	padding-left: 5pt;
	208	text-align: left;
	209	vertical-align: bottom;
	210	white-space: nowrap;
	211	}
	212
	213	TABLE.list TH A {
	214	color: #4444cc;
	215	}
	216
	217	TABLE.list TD {
	218	border-bottom: solid thin #eeeeee;
	219	padding-top: 5pt;
	220	padding-left: 5pt;
	221	}
	222
	223	TABLE.list TR:nth-child(even) {
	224	background: #f8f8f8;
	225	}
	226
	227	TABLE.list TR:nth-child(odd) {
	228	background: #f4f4f4;
	229	}
	230
	231	DT {
	232	margin-left: 36pt;
	233	margin-top: 12pt;
	234	}
	235
	236	DD {
	237	margin-left: 54pt;
	238	}
	239
240	DL.category DT {
241	font-weight: bold;
242	}
243
244	P.summary {
245	margin-left: 36pt;
246	font-family: monaco, courier, monospace;
247	}
248
249	DIV.summary TABLE {
250	border: solid thin #999999;
251	border-collapse: collapse;
252	border-spacing: 0;
253	margin: 10px;
254	}
255
256	DIV.summary TABLE TD, DIV.summary TABLE TH {
257	border: solid thin #999999;
258	padding: 5px;
259	text-align: left;
260	vertical-align: top;
261	}
262
263	DIV.summary TABLE THEAD TH {
264	background: #eeeeee;
265	}
266
267	/* API documentation styles... */
268	div.body h1 {
269	margin: 0;
270	}
271	div.body h2 {
272	margin-top: 1.5em;
273	}
274	div.body h3, div.body h4, div.body h5 {
275	margin-bottom: 0.5em;
276	margin-top: 1.5em;
277	}
278	.class, .enumeration, .function, .struct, .typedef, .union {
279	border-bottom: solid thin #999999;
280	margin-bottom: 0;
281	margin-top: 2em;
282	}
283	.description {
284	margin-top: 0.5em;
285	}
286	code, p.code, pre, ul.code li {
287	font-family: monaco, courier, monospace;
288	font-size: 90%;
289	}
290	ul.code, ul.contents, ul.subcontents {
291	list-style-type: none;
292	margin: 0;
293	padding-left: 0;
294	}
295	ul.code li {
296	margin: 0;
297	}
298	ul.contents > li {
299	margin-top: 1em;
300	}
301	ul.contents li ul.code, ul.contents li ul.subcontents {
302	padding-left: 2em;
303	}
304	div.body dl {
305	margin-left: 0;
306	margin-top: 0;
307	}
308	div.body dt {
309	font-style: italic;
310	margin-left: 0;
311	margin-top: 0;
312	}
313	div.body dd {
314	margin-bottom: 0.5em;
315	}
316
317	/* This is just for the HTML files generated with the framedhelp target */
318	div.contents {
319	background: #e8e8e8;
320	border: solid thin black;
321	padding: 10px;
322	}
323	div.contents h1 {
324	font-size: 110%;
325	}
326	div.contents h2 {
327	font-size: 100%;
328	}
329	div.contents ul.contents {
330	font-size: 80%;
331	}
332	div.contents ul.subcontents li {
333	margin-left: 1em;
334	text-indent: -1em;
335	}
336	--></style>
337	</head>
338	<body>
339	<div class='body'>
178cb736 MS	340	<h1 class='title'>Developing Raster Printer Drivers</h1>
	341
	342	<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>, and <a href='#MACOSX'>adding Mac OS X features</a>.</p>
e4572d57 MS	343
	344	<div class='summary'><table summary='General Information'>
	345	<tbody>
	346	<tr>
	347	<th>See Also</th>
	348	<td>Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br>
	349	Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br>
	350	Programming: <a href='ppd-compiler.html'>Introduction to the PPD Compiler</a><br>
	351	Programming: <a href='api-raster.html'>Raster API</a><br>
	352	References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a><br>
	353	Specifications: <a href='spec-ppd.html'>CUPS PPD Extensions</a></td>
	354	</tr>
	355	</tbody>
	356	</table></div>
8b450588 MS	357	<h2 class="title">Contents</h2>
8b450588 MS	358	<ul class="contents">
426c6a59	359	<ul class="subcontents">
8b450588 MS	360	<li><a href="#BASICS">Printer Driver Basics</a></li>
	361	<li><a href="#CREATING">Creating New PPD Files</a></li>
	362	<li><a href="#FILTERS">Using Filters</a></li>
	363	<li><a href="#COLOR">Implementing Color Management</a></li>
	364	<li><a href="#MACOSX">Adding Mac OS X Features</a></li>
e4572d57 MS	365	<h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2>
	366
	367	<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>
	368
	369	<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>
	370
	371	<div class='figure'><table summary='Raster Filter Chain'>
	372	<caption>Figure 1: <a name='FIGURE_1'>Raster Filter Chain</a></caption>
	373	<tr><td><img src='/images/cups-raster-chain.png' width='700' height='150' alt='Raster Filter Chain'></td></tr>
	374	</table></div>
	375
	376	<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>
	377
	378	<div class='table'><table summary='Standard CUPS Raster Filters'>
	379	<caption>Table 1: <a name='TABLE_1'>Standard CUPS Raster Filters</a></caption>
	380	<thead>
	381	<tr><th>Filter</th><th>PDLs</th><th>ppdc DriverType</th><th>ppdc #include file</th></tr>
	382	</thead>
	383	<tbody>
	384	<tr><td>rastertoepson</td><td>ESC/P, ESC/P2</td><td>epson</td><td>epson.h</td></tr>
	385	<tr><td>rastertoescpx</td><td>ESC/P, ESC/P2, EPSON Remote Mode</td><td>escp</td><td>escp.h</td></tr>
	386	<tr><td>rastertohp</td><td>HP-PCL3, HP-PCL5</td><td>hp</td><td>hp.h</td></tr>
	387	<tr><td>rastertolabel</td><td>CPCL, Dymo, EPL1, EPL2, Intellitech PCL, ZPL</td><td>label</td><td>label.h</td></tr>
	388	<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>
	389	</tbody>
	390	</table></div>
	391
	392	<p>The optional port monitor handles interface-specific protocol or encoding issues. For example, some raster printers use the 1284.4 communications protocol.</p>
	393
	394	<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>
	395
	396	<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>
	397
	398	<div class='figure'><table summary='Command Filter Chain'>
	399	<caption>Figure 2: <a name='FIGURE_2'>Command Filter Chain</a></caption>
	400	<tr><td><img src='/images/cups-command-chain.png' width='575' height='150' alt='Command Filter Chain'></td></tr>
	401	</table></div>
	402
	403	<p>Raster printer drivers must provide their own command filter.</p>
	404
	405
	406	<h2 class='title'><a name='CREATING'>Creating New PPD Files</a></h2>
	407
	408	<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>
	409
	410	<p class='example'>Listing 1: <a name='LISTING_1'>"examples/laserjet-basic.drv"</a></p>
	411
	412	<pre class='example'>
	413	<I>// Include standard font and media definitions</I>
	414	<a href='ref-ppdcfile.html#_include'>#include</a> <font.defs>
	415	<a href='ref-ppdcfile.html#_include'>#include</a> <media.defs>
	416
	417	<I>// Include HP-PCL driver definitions</I>
	418	<a href='ref-ppdcfile.html#_include'>#include</a> <pcl.h>
	419
	420	<I>// Specify that this driver uses the HP-PCL driver...</I>
	421	<a href='ref-ppdcfile.html#DriverType'>DriverType</a> pcl
	422
	423	<I>// Specify the driver options via the model number...</I>
	424	<a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> ($PCL_PAPER_SIZE $PCL_PJL $PCL_PJL_RESOLUTION)
	425
	426	<I>// List the fonts that are supported, in this case all standard fonts...</I>
	427	<a href='ref-ppdcfile.html#Font'>Font</a> *
	428
429	<I>// Manufacturer and driver version</I>
430	<a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "HP"
431	<a href='ref-ppdcfile.html#Version'>Version</a> 1.0
432
433	<I>// Supported page sizes and their margins</I>
434	<a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 18 12 18 12
435	*<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
436	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Legal
437	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Executive
438	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Monarch
439	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Statement
440	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> FanFoldGermanLegal
441
442	<a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 18 12.72 18 12.72
443	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Env10
444
445	<a href='ref-ppdcfile.html#HWMargins'>HWMargins</a> 9.72 12 9.72 12
446	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
447	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A5
448	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> B5
449	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvC5
450	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvDL
451	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> EnvISOB5
452	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Postcard
453	<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> DoublePostcard
454
455	<I>// Only black-and-white output with mode 3 compression...</I>
456	<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray k chunky 3
457
458	<I>// Supported resolutions</I>
459	<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 1 0 0 0 "300dpi/300 DPI"
460	*<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "600dpi/600 DPI"
461
462	<I>// Supported input slots</I>
463	*<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 7 "Auto/Automatic Selection"
464	<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 2 "Manual/Tray 1 - Manual Feed"
465	<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 4 "Upper/Tray 1"
466	<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 1 "Lower/Tray 2"
467	<a href='ref-ppdcfile.html#InputSlot'>InputSlot</a> 5 "LargeCapacity/Tray 3"
468
469	<I>// Tray 3 is an option...</I>
470	<a href='ref-ppdcfile.html#Installable'>Installable</a> "OptionLargeCapacity/Tray 3 Installed"
471	<a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "OptionLargeCapacity False InputSlot LargeCapacity"
472
473	{
474	<I>// HP LaserJet 2100 Series</I>
475	<a href='ref-ppdcfile.html#Throughput'>Throughput</a> 10
476	<a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2100 Series"
477	<a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt211.ppd"
478	}
479
480	{
481	<I>// LaserJet 2200 and 2300 series have duplexer option...</I>
482	<a href='ref-ppdcfile.html#Duplex'>Duplex</a> normal
483	<a href='ref-ppdcfile.html#Installable'>Installable</a> "OptionDuplex/Duplexer Installed"
484	<a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "OptionDuplex False Duplex"
485
486	{
487	<I>// HP LaserJet 2200 Series</I>
488	<a href='ref-ppdcfile.html#Throughput'>Throughput</a> 19
489	<a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2200 Series"
490	<a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt221.ppd"
491	}
492
493	{
494	<I>// HP LaserJet 2300 Series</I>
495	<a href='ref-ppdcfile.html#Throughput'>Throughput</a> 25
496	<a href='ref-ppdcfile.html#ModelName'>ModelName</a> "LaserJet 2300 Series"
497	<a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "hpljt231.ppd"
498	}
499	}
500	</pre>
501
502
503	<h2 class='title'><a name='FILTERS'>Using Filters</a></h2>
504
505	<p>The standard CUPS raster filters can be specified using the
506	<a href='ref-ppdcfile.html#DriverType'><tt>DriverType</tt></a> directive, for example:</p>
507
508	<pre class='example'>
509	<I>// Specify that this driver uses the HP-PCL driver...</I>
510	<a href='ref-ppdcfile.html#DriverType'>DriverType</a> pcl
511	</pre>
512
513	<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>
514
515	<pre class='example'>
516	<a href='ref-ppdcfile.html#DriverType'>DriverType</a> custom
517	<a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 /path/to/raster/filter
518	<a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-command 100 /path/to/command/filter
519	</pre>
520
521
522	<h2 class='title'><a name='COLOR'>Implementing Color Management</a></h2>
523
178cb736	524	<p>CUPS uses ICC color profiles to provide more accurate color reproduction. The <a href='spec-ppd.html#cupsICCProfile'><tt>cupsICCProfile</tt></a> attribute defines the color profiles that are available for a given printer, for example:</p>
e4572d57	525
178cb736 MS	526	<pre class='example'>
	527	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "ColorModel.MediaType.Resolution/Description" /path/to/ICC/profile
	528	</pre>
e4572d57	529
178cb736 MS	530	<p>where "ColorModel.MediaType.Resolution" defines a selector based on the corresponding option selections. A simple driver might only define profiles for the color models that are supported, for example a printer supporting Gray and RGB might use:</p>
	531
	532	<pre class='example'>
	533	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "Gray../Grayscale Profile" /path/to/ICC/gray-profile
	534	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "RGB../Full Color Profile" /path/to/ICC/rgb-profile
	535	</pre>
	536
	537	<p>The options used for profile selection can be customized using the <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> attributes.</p>
e4572d57	538
178cb736	539	<h3><span class='info'>Since Mac OS X 10.5</span>Custom Color Matching Support</h3>
e4572d57	540
178cb736 MS	541	<p>Mac OS X printer drivers that are based on an existing standard RGB colorspace can tell the system to use the corresponding colorspace instead of an arbitrary ICC color profile when doing color management. The <a href='#APCustom'><tt>APSupportsCustomColorMatching</tt></a> and <tt>APDefaultCustomColorMatchingProfile</tt> attributes can be used to enable this mode:</p>
	542
	543	<pre class='example'>
	544	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APSupportsCustomColorMatching "" true
	545	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APDefaultCustomColorMatchingProfile "" sRGB
	546	</pre>
e4572d57	547
e4572d57	548
178cb736 MS	549	<h2 class='title'><a name='MACOSX'>Adding Mac OS X Features</a></h2>
	550
	551	<p>Mac OS X printer drivers can provide <a href='spec-ppd.html#MACOSX'>additional attributes</a> to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:</p>
	552
	553	<pre class='example'>
	554	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APDialogExtension "" /Library/Printers/Vendor/filename.plugin
	555	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APHelpBook "" /Library/Printers/Vendor/filename.bundle
	556	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APPrinterIconPath "" /Library/Printers/Vendor/filename.icns
	557	<a href='ref-ppdcfile.html#Attribute'>Attribute</a> APPrinterPreset "name/text" "*option choice ..."
	558	</pre>
8b450588	559	</div>
e4572d57 MS	560	</body>
e4572d57 MS	561	</html>