# Developing Raster Printer Drivers

This document describes how to develop printer drivers for raster printers. Topics include: printer driver basics, creating new PPD files, using filters, implementing color management, and adding macOS features.

See Also | Programming: Developing PostScript Printer Drivers Programming: Filter and Backend Programming Programming: Introduction to the PPD Compiler Programming: Raster API References: PPD Compiler Driver Information File Reference Specifications: CUPS PPD Extensions

## Contents

- Printer Driver Basics
- Creating New PPD Files
- Using Filters
- Implementing Color Management
- Adding macOS Features

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

Figure 1: Raster Filter Chain

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.

Table 1: Standard CUPS Raster Filters
Filter | PDLs | ppdc DriverType | ppdc #include file
--- | --- | --- | ---
rastertoepson | ESC/P, ESC/P2 | epson | epson.h
rastertoescpx | ESC/P, ESC/P2, EPSON Remote Mode | escp | escp.h
rastertohp | HP-PCL3, HP-PCL5 | hp | hp.h
rastertolabel | CPCL, Dymo, EPL1, EPL2, Intellitech PCL, ZPL | label | label.h
rastertopclx | HP-RTL, HP-PCL3, HP-PCL3GUI, HP-PCL5, HP-PCL5c, HP-PCL5e | pcl | pcl.h

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.

Figure 2: Command Filter Chain

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