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.
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. 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 */ } /* 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
);
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
);
0 on success, -1 on failure
This function 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
cupsRasterInterpretPPD
- this allows you to do 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.
cups_raster_t *cupsRasterOpen (
int fd,
cups_mode_t mode
);
New stream
Read a raster page header and store it in a V1 page header structure.
unsigned cupsRasterReadHeader (
cups_raster_t *r,
cups_page_header_t *h
);
1 on success, 0 on fail
Read a raster page header and store it in a V2 page header structure.
unsigned cupsRasterReadHeader2 (
cups_raster_t *r,
cups_page_header2_t *h
);
1 on success, 0 on fail
Read raster pixels.
unsigned cupsRasterReadPixels (
cups_raster_t *r,
unsigned char *p,
unsigned len
);
Number of bytes read
Write a raster page header from a V1 page header structure.
unsigned cupsRasterWriteHeader (
cups_raster_t *r,
cups_page_header_t *h
);
1 on success, 0 on failure
Write a raster page header from a V2 page header structure.
unsigned cupsRasterWriteHeader2 (
cups_raster_t *r,
cups_page_header2_t *h
);
1 on success, 0 on failure
Write raster pixels.
unsigned cupsRasterWritePixels (
cups_raster_t *r,
unsigned char *p,
unsigned len
);
Number of bytes written
cupsRasterInterpretPPD callback function
typedef int (*cups_interpret_cb_t)(cups_page_header2_t *header, int preferred_bits);
cupsRasterOpen modes
typedef enum cups_mode_e cups_mode_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;
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;
};
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;
};
AdvanceMedia attribute values
Types...
cupsColorOrder attribute values