Overview

The CUPS raster API provides a standard interface for reading and writing CUPS raster streams which are used for printing to raster printers. Because the raster format is updated from time to time, it is important to use this API to avoid incompatibilities with newer versions of CUPS.

Two kinds of CUPS filters use the CUPS raster API - raster image processor (RIP) filters such as pstoraster and cgpdftoraster (macOS) that produce CUPS raster files and printer driver filters that convert CUPS raster files into a format usable by the printer. Printer driver filters are by far the most common.

CUPS raster files (application/vnd.cups-raster) consists of a stream of raster page descriptions produced by one of the RIP filters such as pstoraster, imagetoraster, or cgpdftoraster. CUPS raster files are referred to using the cups_raster_t type and are opened using the cupsRasterOpen function. For example, to read raster data from the standard input, open file descriptor 0:

#include <cups/raster.h>

cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);

Each page of data begins with a page dictionary structure called cups_page_header2_t. This structure contains the colorspace, bits per color, media size, media type, hardware resolution, and so forth used for the page.

Note:

Do not confuse the colorspace in the page header with the PPD ColorModel keyword. ColorModel refers to the general type of color used for a device (Gray, RGB, CMYK, DeviceN) and is often used to select a particular colorspace for the page header along with the associate color profile. The page header colorspace (cupsColorSpace) describes both the type and organization of the color data, for example KCMY (black first) instead of CMYK and RGBA (RGB + alpha) instead of RGB.

You read the page header using the cupsRasterReadHeader2 function:

#include <cups/raster.h>

cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
cups_page_header2_t header;

while (cupsRasterReadHeader2(ras, &header))
{
  /* setup this page */

  /* read raster data */

  /* finish this page */
}

After the page dictionary comes the page data which is a full-resolution, possibly compressed bitmap representing the page in the printer's output colorspace. You read uncompressed raster data using the cupsRasterReadPixels function. A for loop is normally used to read the page one line at a time:

#include <cups/raster.h>

cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
cups_page_header2_t header;
int page = 0;
int y;
char *buffer;

while (cupsRasterReadHeader2(ras, &header))
{
  /* setup this page */
  page ++;
  fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies);

  /* allocate memory for 1 line */
  buffer = malloc(header.cupsBytesPerLine);

  /* read raster data */
  for (y = 0; y < header.cupsHeight; y ++)
  {
    if (cupsRasterReadPixels(ras, buffer, header.cupsBytesPerLine) == 0)
      break;

    /* write raster data to printer on stdout */
  }

  /* finish this page */
}

When you are done reading the raster data, call the cupsRasterClose function to free the memory used to read the raster file:

cups_raster_t *ras;

cupsRasterClose(ras);

Functions by Task

Opening and Closing Raster Streams

Reading Raster Streams

Writing Raster Streams