1/*
2 * Raster file definitions for CUPS.
3 *
4 * Copyright 2007-2016 by Apple Inc.
5 * Copyright 1997-2006 by Easy Software Products.
6 *
7 * This file is part of the CUPS Imaging library.
8 *
9 * These coded instructions, statements, and computer programs are the
10 * property of Apple Inc. and are protected by Federal copyright
11 * law. Distribution and use rights are outlined in the file "LICENSE.txt"
12 * which should have been included with this file. If this file is
13 * missing or damaged, see the license at "http://www.cups.org/".
14 *
15 * This file is subject to the Apple OS-Developed Software exception.
16 */
17
18#ifndef _CUPS_RASTER_H_
19# define _CUPS_RASTER_H_
20
21/*
22 * Include necessary headers...
23 */
24
25# include "cups.h"
26
27
28# ifdef __cplusplus
29extern "C" {
30# endif /* __cplusplus */
31
32/*
33 * Every non-PostScript printer driver that supports raster images
34 * should use the application/vnd.cups-raster image file format.
35 * Since both the PostScript RIP (pstoraster, based on GNU/GPL
36 * Ghostscript) and Image RIP (imagetoraster, located in the filter
37 * directory) use it, using this format saves you a lot of work.
38 * Also, the PostScript RIP passes any printer options that are in
39 * a PS file to your driver this way as well...
40 */
41
42/*
43 * Constants...
44 */
45
46# define CUPS_RASTER_SYNC 0x52615333 /* RaS3 */
47# define CUPS_RASTER_REVSYNC 0x33536152 /* 3SaR */
48
49# define CUPS_RASTER_SYNCv1 0x52615374 /* RaSt */
50# define CUPS_RASTER_REVSYNCv1 0x74536152 /* tSaR */
51
52# define CUPS_RASTER_SYNCv2 0x52615332 /* RaS2 */
53# define CUPS_RASTER_REVSYNCv2 0x32536152 /* 2SaR */
54
55# define CUPS_RASTER_SYNCapple 0x554E4952 /* UNIR */
56# define CUPS_RASTER_REVSYNCapple 0x52494E55 /* RINU */
57
58# define CUPS_RASTER_SYNC_PWG CUPS_RASTER_SYNCv2
59
60/*
61 * The following definition can be used to determine if the
62 * colorimetric colorspaces (CIEXYZ, CIELAB, and ICCn) are
63 * defined...
64 */
65
66# define CUPS_RASTER_HAVE_COLORIMETRIC 1
67
68/*
69 * The following definition can be used to determine if the
70 * device colorspaces (DEVICEn) are defined...
71 */
72
73# define CUPS_RASTER_HAVE_DEVICE 1
74
75/*
76 * The following definition can be used to determine if PWG Raster is supported.
77 */
78
79# define CUPS_RASTER_HAVE_PWGRASTER 1
80
81/*
82 * The following definition can be used to determine if Apple Raster is
83 * supported (beta).
84 */
85
86# define CUPS_RASTER_HAVE_APPLERASTER 1
87
88/*
89 * The following PWG 5102.4 definitions specify indices into the
90 * cupsInteger[] array in the raster header.
91 */
92
93# define CUPS_RASTER_PWG_TotalPageCount 0
94# define CUPS_RASTER_PWG_CrossFeedTransform 1
95# define CUPS_RASTER_PWG_FeedTransform 2
96# define CUPS_RASTER_PWG_ImageBoxLeft 3
97# define CUPS_RASTER_PWG_ImageBoxTop 4
98# define CUPS_RASTER_PWG_ImageBoxRight 5
99# define CUPS_RASTER_PWG_ImageBoxBottom 6
100# define CUPS_RASTER_PWG_AlternatePrimary 7
101# define CUPS_RASTER_PWG_PrintQuality 8
102# define CUPS_RASTER_PWG_VendorIdentifier 14
103# define CUPS_RASTER_PWG_VendorLength 15
104
105
106
107
108/*
109 * Types...
110 */
111
112typedef enum cups_adv_e /**** AdvanceMedia attribute values ****/
113{
114 CUPS_ADVANCE_NONE = 0, /* Never advance the roll */
115 CUPS_ADVANCE_FILE = 1, /* Advance the roll after this file */
116 CUPS_ADVANCE_JOB = 2, /* Advance the roll after this job */
117 CUPS_ADVANCE_SET = 3, /* Advance the roll after this set */
118 CUPS_ADVANCE_PAGE = 4 /* Advance the roll after this page */
119} cups_adv_t;
120
121typedef enum cups_bool_e /**** Boolean type ****/
122{
123 CUPS_FALSE = 0, /* Logical false */
124 CUPS_TRUE = 1 /* Logical true */
125} cups_bool_t;
126
127typedef enum cups_cspace_e /**** cupsColorSpace attribute values ****/
128{
129 CUPS_CSPACE_W = 0, /* Luminance (DeviceGray, gamma 2.2 by default) */
130 CUPS_CSPACE_RGB = 1, /* Red, green, blue (DeviceRGB, sRGB by default) */
131 CUPS_CSPACE_RGBA = 2, /* Red, green, blue, alpha (DeviceRGB, sRGB by default) */
132 CUPS_CSPACE_K = 3, /* Black (DeviceK) */
133 CUPS_CSPACE_CMY = 4, /* Cyan, magenta, yellow (DeviceCMY) */
134 CUPS_CSPACE_YMC = 5, /* Yellow, magenta, cyan @deprecated@ */
135 CUPS_CSPACE_CMYK = 6, /* Cyan, magenta, yellow, black (DeviceCMYK) */
136 CUPS_CSPACE_YMCK = 7, /* Yellow, magenta, cyan, black @deprecated@ */
137 CUPS_CSPACE_KCMY = 8, /* Black, cyan, magenta, yellow @deprecated@ */
138 CUPS_CSPACE_KCMYcm = 9, /* Black, cyan, magenta, yellow, light-cyan, light-magenta @deprecated@ */
139 CUPS_CSPACE_GMCK = 10, /* Gold, magenta, yellow, black @deprecated@ */
140 CUPS_CSPACE_GMCS = 11, /* Gold, magenta, yellow, silver @deprecated@ */
141 CUPS_CSPACE_WHITE = 12, /* White ink (as black) @deprecated@ */
142 CUPS_CSPACE_GOLD = 13, /* Gold foil @deprecated@ */
143 CUPS_CSPACE_SILVER = 14, /* Silver foil @deprecated@ */
144
145 CUPS_CSPACE_CIEXYZ = 15, /* CIE XYZ @since CUPS 1.1.19/macOS 10.3@ */
146 CUPS_CSPACE_CIELab = 16, /* CIE Lab @since CUPS 1.1.19/macOS 10.3@ */
147 CUPS_CSPACE_RGBW = 17, /* Red, green, blue, white (DeviceRGB, sRGB by default) @since CUPS 1.2/macOS 10.5@ */
148 CUPS_CSPACE_SW = 18, /* Luminance (gamma 2.2) @since CUPS 1.4.5@ */
149 CUPS_CSPACE_SRGB = 19, /* Red, green, blue (sRGB) @since CUPS 1.4.5@ */
150 CUPS_CSPACE_ADOBERGB = 20, /* Red, green, blue (Adobe RGB) @since CUPS 1.4.5@ */
151
152 CUPS_CSPACE_ICC1 = 32, /* ICC-based, 1 color @since CUPS 1.1.19/macOS 10.3@ */
153 CUPS_CSPACE_ICC2 = 33, /* ICC-based, 2 colors @since CUPS 1.1.19/macOS 10.3@ */
154 CUPS_CSPACE_ICC3 = 34, /* ICC-based, 3 colors @since CUPS 1.1.19/macOS 10.3@ */
155 CUPS_CSPACE_ICC4 = 35, /* ICC-based, 4 colors @since CUPS 1.1.19/macOS 10.3@ */
156 CUPS_CSPACE_ICC5 = 36, /* ICC-based, 5 colors @since CUPS 1.1.19/macOS 10.3@ */
157 CUPS_CSPACE_ICC6 = 37, /* ICC-based, 6 colors @since CUPS 1.1.19/macOS 10.3@ */
158 CUPS_CSPACE_ICC7 = 38, /* ICC-based, 7 colors @since CUPS 1.1.19/macOS 10.3@ */
159 CUPS_CSPACE_ICC8 = 39, /* ICC-based, 8 colors @since CUPS 1.1.19/macOS 10.3@ */
160 CUPS_CSPACE_ICC9 = 40, /* ICC-based, 9 colors @since CUPS 1.1.19/macOS 10.3@ */
161 CUPS_CSPACE_ICCA = 41, /* ICC-based, 10 colors @since CUPS 1.1.19/macOS 10.3@ */
162 CUPS_CSPACE_ICCB = 42, /* ICC-based, 11 colors @since CUPS 1.1.19/macOS 10.3@ */
163 CUPS_CSPACE_ICCC = 43, /* ICC-based, 12 colors @since CUPS 1.1.19/macOS 10.3@ */
164 CUPS_CSPACE_ICCD = 44, /* ICC-based, 13 colors @since CUPS 1.1.19/macOS 10.3@ */
165 CUPS_CSPACE_ICCE = 45, /* ICC-based, 14 colors @since CUPS 1.1.19/macOS 10.3@ */
166 CUPS_CSPACE_ICCF = 46, /* ICC-based, 15 colors @since CUPS 1.1.19/macOS 10.3@ */
167
168 CUPS_CSPACE_DEVICE1 = 48, /* DeviceN, 1 color @since CUPS 1.4.5@ */
169 CUPS_CSPACE_DEVICE2 = 49, /* DeviceN, 2 colors @since CUPS 1.4.5@ */
170 CUPS_CSPACE_DEVICE3 = 50, /* DeviceN, 3 colors @since CUPS 1.4.5@ */
171 CUPS_CSPACE_DEVICE4 = 51, /* DeviceN, 4 colors @since CUPS 1.4.5@ */
172 CUPS_CSPACE_DEVICE5 = 52, /* DeviceN, 5 colors @since CUPS 1.4.5@ */
173 CUPS_CSPACE_DEVICE6 = 53, /* DeviceN, 6 colors @since CUPS 1.4.5@ */
174 CUPS_CSPACE_DEVICE7 = 54, /* DeviceN, 7 colors @since CUPS 1.4.5@ */
175 CUPS_CSPACE_DEVICE8 = 55, /* DeviceN, 8 colors @since CUPS 1.4.5@ */
176 CUPS_CSPACE_DEVICE9 = 56, /* DeviceN, 9 colors @since CUPS 1.4.5@ */
177 CUPS_CSPACE_DEVICEA = 57, /* DeviceN, 10 colors @since CUPS 1.4.5@ */
178 CUPS_CSPACE_DEVICEB = 58, /* DeviceN, 11 colors @since CUPS 1.4.5@ */
179 CUPS_CSPACE_DEVICEC = 59, /* DeviceN, 12 colors @since CUPS 1.4.5@ */
180 CUPS_CSPACE_DEVICED = 60, /* DeviceN, 13 colors @since CUPS 1.4.5@ */
181 CUPS_CSPACE_DEVICEE = 61, /* DeviceN, 14 colors @since CUPS 1.4.5@ */
182 CUPS_CSPACE_DEVICEF = 62 /* DeviceN, 15 colors @since CUPS 1.4.5@ */
183} cups_cspace_t;
184
185typedef enum cups_cut_e /**** CutMedia attribute values ****/
186{
187 CUPS_CUT_NONE = 0, /* Never cut the roll */
188 CUPS_CUT_FILE = 1, /* Cut the roll after this file */
189 CUPS_CUT_JOB = 2, /* Cut the roll after this job */
190 CUPS_CUT_SET = 3, /* Cut the roll after this set */
191 CUPS_CUT_PAGE = 4 /* Cut the roll after this page */
192} cups_cut_t;
193
194typedef enum cups_edge_e /**** LeadingEdge attribute values ****/
195{
196 CUPS_EDGE_TOP = 0, /* Leading edge is the top of the page */
197 CUPS_EDGE_RIGHT = 1, /* Leading edge is the right of the page */
198 CUPS_EDGE_BOTTOM = 2, /* Leading edge is the bottom of the page */
199 CUPS_EDGE_LEFT = 3 /* Leading edge is the left of the page */
200} cups_edge_t;
201
202typedef enum cups_jog_e /**** Jog attribute values ****/
203{
204 CUPS_JOG_NONE = 0, /* Never move pages */
205 CUPS_JOG_FILE = 1, /* Move pages after this file */
206 CUPS_JOG_JOB = 2, /* Move pages after this job */
207 CUPS_JOG_SET = 3 /* Move pages after this set */
208} cups_jog_t;
209
210enum cups_mode_e /**** cupsRasterOpen modes ****/
211{
212 CUPS_RASTER_READ = 0, /* Open stream for reading */
213 CUPS_RASTER_WRITE = 1, /* Open stream for writing */
214 CUPS_RASTER_WRITE_COMPRESSED = 2, /* Open stream for compressed writing @since CUPS 1.3/macOS 10.5@ */
215 CUPS_RASTER_WRITE_PWG = 3, /* Open stream for compressed writing in PWG Raster mode @since CUPS 1.5/macOS 10.7@ */
216 CUPS_RASTER_WRITE_APPLE = 4 /* Open stream for compressed writing in AppleRaster mode (beta) @private@ */
217};
218
219typedef enum cups_mode_e cups_mode_t; /**** cupsRasterOpen modes ****/
220
221typedef enum cups_order_e /**** cupsColorOrder attribute values ****/
222{
223 CUPS_ORDER_CHUNKED = 0, /* CMYK CMYK CMYK ... */
224 CUPS_ORDER_BANDED = 1, /* CCC MMM YYY KKK ... */
225 CUPS_ORDER_PLANAR = 2 /* CCC ... MMM ... YYY ... KKK ... */
226} cups_order_t;
227
228typedef enum cups_orient_e /**** Orientation attribute values ****/
229{
230 CUPS_ORIENT_0 = 0, /* Don't rotate the page */
231 CUPS_ORIENT_90 = 1, /* Rotate the page counter-clockwise */
232 CUPS_ORIENT_180 = 2, /* Turn the page upside down */
233 CUPS_ORIENT_270 = 3 /* Rotate the page clockwise */
234} cups_orient_t;
235
236
237/*
238 * The page header structure contains the standard PostScript page device
239 * dictionary, along with some CUPS-specific parameters that are provided
240 * by the RIPs...
241 *
242 * The API supports a "version 1" (from CUPS 1.0 and 1.1) and a "version 2"
243 * (from CUPS 1.2 and higher) page header, for binary compatibility.
244 */
245
246typedef struct cups_page_header_s /**** Version 1 page header @deprecated@ ****/
247{
248 /**** Standard Page Device Dictionary String Values ****/
249 char MediaClass[64]; /* MediaClass string */
250 char MediaColor[64]; /* MediaColor string */
251 char MediaType[64]; /* MediaType string */
252 char OutputType[64]; /* OutputType string */
253
254 /**** Standard Page Device Dictionary Integer Values ****/
255 unsigned AdvanceDistance; /* AdvanceDistance value in points */
256 cups_adv_t AdvanceMedia; /* AdvanceMedia value (@link cups_adv_t@) */
257 cups_bool_t Collate; /* Collated copies value */
258 cups_cut_t CutMedia; /* CutMedia value (@link cups_cut_t@) */
259 cups_bool_t Duplex; /* Duplexed (double-sided) value */
260 unsigned HWResolution[2]; /* Resolution in dots-per-inch */
261 unsigned ImagingBoundingBox[4]; /* Pixel region that is painted (points, left, bottom, right, top) */
262 cups_bool_t InsertSheet; /* InsertSheet value */
263 cups_jog_t Jog; /* Jog value (@link cups_jog_t@) */
264 cups_edge_t LeadingEdge; /* LeadingEdge value (@link cups_edge_t@) */
265 unsigned Margins[2]; /* Lower-lefthand margins in points */
266 cups_bool_t ManualFeed; /* ManualFeed value */
267 unsigned MediaPosition; /* MediaPosition value */
268 unsigned MediaWeight; /* MediaWeight value in grams/m^2 */
269 cups_bool_t MirrorPrint; /* MirrorPrint value */
270 cups_bool_t NegativePrint; /* NegativePrint value */
271 unsigned NumCopies; /* Number of copies to produce */
272 cups_orient_t Orientation; /* Orientation value (@link cups_orient_t@) */
273 cups_bool_t OutputFaceUp; /* OutputFaceUp value */
274 unsigned PageSize[2]; /* Width and length of page in points */
275 cups_bool_t Separations; /* Separations value */
276 cups_bool_t TraySwitch; /* TraySwitch value */
277 cups_bool_t Tumble; /* Tumble value */
278
279 /**** CUPS Page Device Dictionary Values ****/
280 unsigned cupsWidth; /* Width of page image in pixels */
281 unsigned cupsHeight; /* Height of page image in pixels */
282 unsigned cupsMediaType; /* Media type code */
283 unsigned cupsBitsPerColor; /* Number of bits for each color */
284 unsigned cupsBitsPerPixel; /* Number of bits for each pixel */
285 unsigned cupsBytesPerLine; /* Number of bytes per line */
286 cups_order_t cupsColorOrder; /* Order of colors */
287 cups_cspace_t cupsColorSpace; /* True colorspace */
288 unsigned cupsCompression; /* Device compression to use */
289 unsigned cupsRowCount; /* Rows per band */
290 unsigned cupsRowFeed; /* Feed between bands */
291 unsigned cupsRowStep; /* Spacing between lines */
292} cups_page_header_t;
293
294/**** New in CUPS 1.2 ****/
295typedef struct cups_page_header2_s /**** Version 2 page header @since CUPS 1.2/macOS 10.5@ ****/
296{
297 /**** Standard Page Device Dictionary String Values ****/
298 char MediaClass[64]; /* MediaClass string */
299 char MediaColor[64]; /* MediaColor string */
300 char MediaType[64]; /* MediaType string */
301 char OutputType[64]; /* OutputType string */
302
303 /**** Standard Page Device Dictionary Integer Values ****/
304 unsigned AdvanceDistance; /* AdvanceDistance value in points */
305 cups_adv_t AdvanceMedia; /* AdvanceMedia value (@link cups_adv_t@) */
306 cups_bool_t Collate; /* Collated copies value */
307 cups_cut_t CutMedia; /* CutMedia value (@link cups_cut_t@) */
308 cups_bool_t Duplex; /* Duplexed (double-sided) value */
309 unsigned HWResolution[2]; /* Resolution in dots-per-inch */
310 unsigned ImagingBoundingBox[4]; /* Pixel region that is painted (points, left, bottom, right, top) */
311 cups_bool_t InsertSheet; /* InsertSheet value */
312 cups_jog_t Jog; /* Jog value (@link cups_jog_t@) */
313 cups_edge_t LeadingEdge; /* LeadingEdge value (@link cups_edge_t@) */
314 unsigned Margins[2]; /* Lower-lefthand margins in points */
315 cups_bool_t ManualFeed; /* ManualFeed value */
316 unsigned MediaPosition; /* MediaPosition value */
317 unsigned MediaWeight; /* MediaWeight value in grams/m^2 */
318 cups_bool_t MirrorPrint; /* MirrorPrint value */
319 cups_bool_t NegativePrint; /* NegativePrint value */
320 unsigned NumCopies; /* Number of copies to produce */
321 cups_orient_t Orientation; /* Orientation value (@link cups_orient_t@) */
322 cups_bool_t OutputFaceUp; /* OutputFaceUp value */
323 unsigned PageSize[2]; /* Width and length of page in points */
324 cups_bool_t Separations; /* Separations value */
325 cups_bool_t TraySwitch; /* TraySwitch value */
326 cups_bool_t Tumble; /* Tumble value */
327
328 /**** CUPS Page Device Dictionary Values ****/
329 unsigned cupsWidth; /* Width of page image in pixels */
330 unsigned cupsHeight; /* Height of page image in pixels */
331 unsigned cupsMediaType; /* Media type code */
332 unsigned cupsBitsPerColor; /* Number of bits for each color */
333 unsigned cupsBitsPerPixel; /* Number of bits for each pixel */
334 unsigned cupsBytesPerLine; /* Number of bytes per line */
335 cups_order_t cupsColorOrder; /* Order of colors */
336 cups_cspace_t cupsColorSpace; /* True colorspace */
337 unsigned cupsCompression; /* Device compression to use */
338 unsigned cupsRowCount; /* Rows per band */
339 unsigned cupsRowFeed; /* Feed between bands */
340 unsigned cupsRowStep; /* Spacing between lines */
341
342 /**** Version 2 Dictionary Values ****/
343 unsigned cupsNumColors; /* Number of color compoents @since CUPS 1.2/macOS 10.5@ */
344 float cupsBorderlessScalingFactor;
345 /* Scaling that was applied to page data @since CUPS 1.2/macOS 10.5@ */
346 float cupsPageSize[2]; /* Floating point PageSize (scaling *
347 * factor not applied) @since CUPS 1.2/macOS 10.5@ */
348 float cupsImagingBBox[4]; /* Floating point ImagingBoundingBox
349 * (scaling factor not applied, left,
350 * bottom, right, top) @since CUPS 1.2/macOS 10.5@ */
351 unsigned cupsInteger[16]; /* User-defined integer values @since CUPS 1.2/macOS 10.5@ */
352 float cupsReal[16]; /* User-defined floating-point values @since CUPS 1.2/macOS 10.5@ */
353 char cupsString[16][64]; /* User-defined string values @since CUPS 1.2/macOS 10.5@ */
354 char cupsMarkerType[64]; /* Ink/toner type @since CUPS 1.2/macOS 10.5@ */
355 char cupsRenderingIntent[64];/* Color rendering intent @since CUPS 1.2/macOS 10.5@ */
356 char cupsPageSizeName[64]; /* PageSize name @since CUPS 1.2/macOS 10.5@ */
357} cups_page_header2_t;
358
359typedef struct _cups_raster_s cups_raster_t;
360 /**** Raster stream data ****/
361
362typedef int (*cups_interpret_cb_t)(cups_page_header2_t *header, int preferred_bits);
363 /**** cupsRasterInterpretPPD callback function
364 *
365 * This function is called by
366 * @link cupsRasterInterpretPPD@ to
367 * validate (and update, as needed)
368 * the page header attributes. The
369 * "preferred_bits" argument provides
370 * the value of the
371 * @code cupsPreferredBitsPerColor@
372 * key from the PostScript page device
373 * dictionary and is 0 if undefined.
374 ****/
375
376/**** New in CUPS 1.5 ****/
377typedef ssize_t (*cups_raster_iocb_t)(void *ctx, unsigned char *buffer, size_t length);
378 /**** cupsRasterOpenIO callback function
379 *
380 * This function is specified when
381 * creating a raster stream with
382 * @link cupsRasterOpenIO@ and handles
383 * generic reading and writing of raster
384 * data. It must return -1 on error or
385 * the number of bytes specified by
386 * "length" on success.
387 ****/
388
389
390/*
391 * Prototypes...
392 */
393
394extern void cupsRasterClose(cups_raster_t *r);
395extern cups_raster_t *cupsRasterOpen(int fd, cups_mode_t mode);
396extern unsigned cupsRasterReadHeader(cups_raster_t *r,
397 cups_page_header_t *h) _CUPS_DEPRECATED_MSG("Use cupsRasterReadHeader2 instead.");
398extern unsigned cupsRasterReadPixels(cups_raster_t *r,
399 unsigned char *p, unsigned len);
400extern unsigned cupsRasterWriteHeader(cups_raster_t *r,
401 cups_page_header_t *h) _CUPS_DEPRECATED_MSG("Use cupsRasterWriteHeader2 instead.");
402extern unsigned cupsRasterWritePixels(cups_raster_t *r,
403 unsigned char *p, unsigned len);
404
405/**** New in CUPS 1.2 ****/
406extern unsigned cupsRasterReadHeader2(cups_raster_t *r,
407 cups_page_header2_t *h) _CUPS_API_1_2;
408extern unsigned cupsRasterWriteHeader2(cups_raster_t *r,
409 cups_page_header2_t *h) _CUPS_API_1_2;
410
411/**** New in CUPS 1.3 ****/
412extern const char *cupsRasterErrorString(void) _CUPS_API_1_3;
413
414/**** New in CUPS 1.5 ****/
415extern cups_raster_t *cupsRasterOpenIO(cups_raster_iocb_t iocb, void *ctx,
416 cups_mode_t mode);
417
418/**** New in CUPS 2.2/macOS 10.12 ****/
419extern int cupsRasterInitPWGHeader(cups_page_header2_t *h, pwg_media_t *media, const char *type, int xdpi, int ydpi, const char *sides, const char *sheet_back) _CUPS_API_2_2;
420
421# ifdef __cplusplus
422}
423# endif /* __cplusplus */
424
425#endif /* !_CUPS_RASTER_H_ */
426