| Header | cups/raster.h |
|---|---|
| Library | -lcupsimage |
| See Also | Programming: Introduction to CUPS Programming Programming: CUPS API Programming: PPD API References: CUPS PPD Specification |
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
(OS X) 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);
Close a raster stream.
void cupsRasterClose (
cups_raster_t *r
);
The file descriptor associated with the raster stream must be closed separately as needed.
Interpret PPD commands to create a page header.
int cupsRasterInterpretPPD (
cups_page_header2_t *h,
ppd_file_t *ppd,
int num_options,
cups_option_t *options,
cups_interpret_cb_t func
);
NULL for none)0 on success, -1 on failure
This function is used by raster image processing (RIP) filters like
cgpdftoraster and imagetoraster when writing CUPS raster data for a page.
It is not used by raster printer driver filters which only read CUPS
raster data.
cupsRasterInterpretPPD does not mark the options in the PPD using
the "num_options" and "options" arguments. Instead, mark the options with
cupsMarkOptions and ppdMarkOption prior to calling it -
this allows for per-page options without manipulating the options array.
The "func" argument specifies an optional callback function that is
called prior to the computation of the final raster data. The function
can make changes to the cups_page_header2_t data as needed to use a
supported raster format and then returns 0 on success and -1 if the
requested attributes cannot be supported.
cupsRasterInterpretPPD supports a subset of the PostScript language.
Currently only the [, ], <<, >>, {,
}, cleartomark, copy, dup, index,
pop, roll, setpagedevice, and stopped operators
are supported.
Open a raster stream using a file descriptor.
cups_raster_t *cupsRasterOpen (
int fd,
cups_mode_t mode
);
CUPS_RASTER_READ,
CUPS_RASTER_WRITE,
CUPS_RASTER_WRITE_COMPRESSED,
or CUPS_RASTER_WRITE_PWGNew stream
This function associates a raster stream with the given file descriptor.
For most printer driver filters, "fd" will be 0 (stdin). For most raster
image processor (RIP) filters that generate raster data, "fd" will be 1
(stdout).
When writing raster data, the CUPS_RASTER_WRITE,
CUPS_RASTER_WRITE_COMPRESS, or CUPS_RASTER_WRITE_PWG mode can
be used - compressed and PWG output is generally 25-50% smaller but adds a
100-300% execution time overhead.
Open a raster stream using a callback function.
cups_raster_t *cupsRasterOpenIO (
cups_raster_iocb_t iocb,
void *ctx,
cups_mode_t mode
);
CUPS_RASTER_READ,
CUPS_RASTER_WRITE,
CUPS_RASTER_WRITE_COMPRESSED,
or CUPS_RASTER_WRITE_PWGNew stream
This function associates a raster stream with the given callback function and
context pointer.
When writing raster data, the CUPS_RASTER_WRITE,
CUPS_RASTER_WRITE_COMPRESS, or CUPS_RASTER_WRITE_PWG mode can
be used - compressed and PWG output is generally 25-50% smaller but adds a
100-300% execution time overhead.
Read a raster page header and store it in a version 1 page header structure.
unsigned cupsRasterReadHeader (
cups_raster_t *r,
cups_page_header_t *h
);
1 on success, 0 on failure/end-of-file
This function is deprecated. Use cupsRasterReadHeader2 instead.
Version 1 page headers were used in CUPS 1.0 and 1.1 and contain a subset
of the version 2 page header data. This function handles reading version 2
page headers and copying only the version 1 data into the provided buffer.
Read a raster page header and store it in a version 2 page header structure.
unsigned cupsRasterReadHeader2 (
cups_raster_t *r,
cups_page_header2_t *h
);
1 on success, 0 on failure/end-of-file
Read raster pixels.
unsigned cupsRasterReadPixels (
cups_raster_t *r,
unsigned char *p,
unsigned len
);
Number of bytes read
For best performance, filters should read one or more whole lines. The "cupsBytesPerLine" value from the page header can be used to allocate the line buffer and as the number of bytes to read.
Write a raster page header from a version 1 page header structure.
unsigned cupsRasterWriteHeader (
cups_raster_t *r,
cups_page_header_t *h
);
1 on success, 0 on failure
This function is deprecated. Use cupsRasterWriteHeader2 instead.
Write a raster page header from a version 2 page header structure.
unsigned cupsRasterWriteHeader2 (
cups_raster_t *r,
cups_page_header2_t *h
);
1 on success, 0 on failure
The page header can be initialized using cupsRasterInterpretPPD.
Write raster pixels.
unsigned cupsRasterWritePixels (
cups_raster_t *r,
unsigned char *p,
unsigned len
);
Number of bytes written
For best performance, filters should write one or more whole lines. The "cupsBytesPerLine" value from the page header can be used to allocate the line buffer and as the number of bytes to write.
AdvanceMedia attribute values
typedef enum cups_adv_e cups_adv_t;
Boolean type
typedef enum cups_bool_e cups_bool_t;
cupsColorSpace attribute values
typedef enum cups_cspace_e cups_cspace_t;
CutMedia attribute values
typedef enum cups_cut_e cups_cut_t;
LeadingEdge attribute values
typedef enum cups_edge_e cups_edge_t;
cupsRasterInterpretPPD callback function
typedef int (*cups_interpret_cb_t)(cups_page_header2_t *header, int preferred_bits);
Jog attribute values
typedef enum cups_jog_e cups_jog_t;
cupsRasterOpen modes
typedef enum cups_mode_e cups_mode_t;
cupsColorOrder attribute values
typedef enum cups_order_e cups_order_t;
Orientation attribute values
typedef enum cups_orient_e cups_orient_t;
Version 2 page header
typedef struct cups_page_header2_s cups_page_header2_t;
Version 1 page header
typedef struct cups_page_header_s cups_page_header_t;
cupsRasterOpenIO callback function
typedef ssize_t (*cups_raster_iocb_t)(void *ctx, unsigned char *buffer, size_t length);
Raster stream data
typedef struct _cups_raster_s cups_raster_t;
Version 2 page header
struct cups_page_header2_s {
unsigned AdvanceDistance;
cups_adv_t AdvanceMedia;
cups_bool_t Collate;
cups_cut_t CutMedia;
cups_bool_t Duplex;
unsigned HWResolution[2];
unsigned ImagingBoundingBox[4];
cups_bool_t InsertSheet;
cups_jog_t Jog;
cups_edge_t LeadingEdge;
cups_bool_t ManualFeed;
unsigned Margins[2];
char MediaClass[64];
char MediaColor[64];
unsigned MediaPosition;
char MediaType[64];
unsigned MediaWeight;
cups_bool_t MirrorPrint;
cups_bool_t NegativePrint;
unsigned NumCopies;
cups_orient_t Orientation;
cups_bool_t OutputFaceUp;
char OutputType[64];
unsigned PageSize[2];
cups_bool_t Separations;
cups_bool_t TraySwitch;
cups_bool_t Tumble;
unsigned cupsBitsPerColor;
unsigned cupsBitsPerPixel;
float cupsBorderlessScalingFactor;
unsigned cupsBytesPerLine;
cups_order_t cupsColorOrder;
cups_cspace_t cupsColorSpace;
unsigned cupsCompression;
unsigned cupsHeight;
float cupsImagingBBox[4];
unsigned cupsInteger[16];
char cupsMarkerType[64];
unsigned cupsMediaType;
unsigned cupsNumColors;
char cupsPageSizeName[64];
float cupsPageSize[2];
float cupsReal[16];
char cupsRenderingIntent[64];
unsigned cupsRowCount;
unsigned cupsRowFeed;
unsigned cupsRowStep;
char cupsString[16][64];
unsigned cupsWidth;
};
cups_adv_t)cups_cut_t)cups_jog_t)cups_edge_t)cups_orient_t)Version 1 page header
struct cups_page_header_s {
unsigned AdvanceDistance;
cups_adv_t AdvanceMedia;
cups_bool_t Collate;
cups_cut_t CutMedia;
cups_bool_t Duplex;
unsigned HWResolution[2];
unsigned ImagingBoundingBox[4];
cups_bool_t InsertSheet;
cups_jog_t Jog;
cups_edge_t LeadingEdge;
cups_bool_t ManualFeed;
unsigned Margins[2];
char MediaClass[64];
char MediaColor[64];
unsigned MediaPosition;
char MediaType[64];
unsigned MediaWeight;
cups_bool_t MirrorPrint;
cups_bool_t NegativePrint;
unsigned NumCopies;
cups_orient_t Orientation;
cups_bool_t OutputFaceUp;
char OutputType[64];
unsigned PageSize[2];
cups_bool_t Separations;
cups_bool_t TraySwitch;
cups_bool_t Tumble;
unsigned cupsBitsPerColor;
unsigned cupsBitsPerPixel;
unsigned cupsBytesPerLine;
cups_order_t cupsColorOrder;
cups_cspace_t cupsColorSpace;
unsigned cupsCompression;
unsigned cupsHeight;
unsigned cupsMediaType;
unsigned cupsRowCount;
unsigned cupsRowFeed;
unsigned cupsRowStep;
unsigned cupsWidth;
};
cups_adv_t)cups_cut_t)cups_jog_t)cups_edge_t)cups_orient_t)AdvanceMedia attribute values
Boolean type
cupsColorSpace attribute values
CutMedia attribute values
LeadingEdge attribute values
Jog attribute values
cupsRasterOpen modes
cupsColorOrder attribute values
Orientation attribute values