Developing Raster Printer Drivers

Printer Driver Basics

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

Every time a user prints something the scheduler program, cupsd(8), 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. Figure 1 shows the data flow of a typical print job.

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). Table 1 shows the raster filters that are bundled with CUPS and the languages they support.

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

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.

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. Figure 2 shows the data flow of a typical command job.

Raster printer drivers must provide their own command filter.

Creating New PPD Files

We recommend using the CUPS PPD compiler, ppdc(1), 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 "Introduction to the PPD Compiler" document. Listing 1 shows a driver information file for several similar black-and-white HP-PCL5 laser printers.

Listing 1: "examples/laserjet-basic.drv"

// Include standard font and media definitions
#include <font.defs>
#include <media.defs>

// Include HP-PCL driver definitions
#include <pcl.h>

// Specify that this driver uses the HP-PCL driver...
DriverType pcl

// Specify the driver options via the model number...
ModelNumber ($PCL_PAPER_SIZE $PCL_PJL $PCL_PJL_RESOLUTION)

// List the fonts that are supported, in this case all standard fonts...
Font *

// Manufacturer and driver version
Manufacturer "HP"
Version 1.0

// Supported page sizes and their margins
HWMargins 18 12 18 12
*MediaSize Letter
MediaSize Legal
MediaSize Executive
MediaSize Monarch
MediaSize Statement
MediaSize FanFoldGermanLegal

HWMargins 18 12.72 18 12.72
MediaSize Env10

HWMargins 9.72 12 9.72 12
MediaSize A4
MediaSize A5
MediaSize B5
MediaSize EnvC5
MediaSize EnvDL
MediaSize EnvISOB5
MediaSize Postcard
MediaSize DoublePostcard

// Only black-and-white output with mode 3 compression...
ColorModel Gray k chunky 3

// Supported resolutions
Resolution - 1 0 0 0 "300dpi/300 DPI"
*Resolution - 8 0 0 0 "600dpi/600 DPI"

// Supported input slots
*InputSlot 7 "Auto/Automatic Selection"
InputSlot 2 "Manual/Tray 1 - Manual Feed"
InputSlot 4 "Upper/Tray 1"
InputSlot 1 "Lower/Tray 2"
InputSlot 5 "LargeCapacity/Tray 3"

// Tray 3 is an option...
Installable "OptionLargeCapacity/Tray 3 Installed"
UIConstraints "*OptionLargeCapacity False *InputSlot LargeCapacity"

{
  // HP LaserJet 2100 Series
  Throughput 10
  ModelName "LaserJet 2100 Series"
  PCFileName "hpljt211.ppd"
}

{
  // LaserJet 2200 and 2300 series have duplexer option...
  Duplex normal
  Installable "OptionDuplex/Duplexer Installed"
  UIConstraints "*OptionDuplex False *Duplex"

  {
    // HP LaserJet 2200 Series
    Throughput 19
    ModelName "LaserJet 2200 Series"
    PCFileName "hpljt221.ppd"
  }

  {
    // HP LaserJet 2300 Series
    Throughput 25
    ModelName "LaserJet 2300 Series"
    PCFileName "hpljt231.ppd"
  }
}

Using Filters

The standard CUPS raster filters can be specified using the DriverType directive, for example:

// Specify that this driver uses the HP-PCL driver...
DriverType pcl

Table 1 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 Filter directives:

DriverType custom
Filter application/vnd.cups-raster 100 /path/to/raster/filter
Filter application/vnd.cups-command 100 /path/to/command/filter

Implementing Color Management

CUPS uses ICC color profiles to provide more accurate color reproduction. The cupsICCProfile attribute defines the color profiles that are available for a given printer, for example:

Attribute cupsICCProfile "ColorModel.MediaType.Resolution/Description" /path/to/ICC/profile

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:

Attribute cupsICCProfile "Gray../Grayscale Profile" /path/to/ICC/gray-profile
Attribute cupsICCProfile "RGB../Full Color Profile" /path/to/ICC/rgb-profile

The options used for profile selection can be customized using the cupsICCQualifier2 and cupsICCQualifier3 attributes.

Since macOS 10.5Custom Color Matching Support

macOS 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 APSupportsCustomColorMatching and APDefaultCustomColorMatchingProfile attributes can be used to enable this mode:

Attribute APSupportsCustomColorMatching "" true
Attribute APDefaultCustomColorMatchingProfile "" sRGB

Adding macOS Features

macOS printer drivers can provide additional attributes to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:

Attribute APDialogExtension "" /Library/Printers/Vendor/filename.plugin
Attribute APHelpBook "" /Library/Printers/Vendor/filename.bundle
Attribute APPrinterIconPath "" /Library/Printers/Vendor/filename.icns
Attribute APPrinterPreset "name/text" "*option choice ..."