drivers.txt

实现并行算法

the point (x,y) is included in the rectangle, as are (x+w-1,y), (x,y+h-1),
and (x+w-1,y+h-1), but *not* (x+w,y), (x,y+h), or (x+w,y+h).  If width <=
0 or height <= 0, fill_rectangle should return 0 without drawing anything.

	Note that fill_rectangle is the only non-optional procedure in the
driver interface.

int (*draw_line)(P6(gx_device *, int x0, int y0, int x1, int y1,
  gx_color_index color)) [OPTIONAL]

	Draw a minimum-thickness line from (x0,y0) to (x1,y1).  The
precise set of points to be filled is defined as follows.  First, if y1 <
y0, swap (x0,y0) and (x1,y1).  Then the line includes the point (x0,y0)
but not the point (x1,y1).  If x0=x1 and y0=y1, draw_line should return 0
without drawing anything.

Bitmap imaging
--------------

Bitmap (or pixmap) images are stored in memory in a nearly standard way.
The first byte corresponds to (0,0) in the image coordinate system: bits
(or polybit color values) are packed into it left-to-right.  There may be
padding at the end of each scan line: the distance from one scan line to
the next is always passed as an explicit argument.

int (*copy_mono)(P11(gx_device *, const unsigned char *data, int data_x,
  int raster, gx_bitmap_id id, int x, int y, int width, int height,
  gx_color_index color0, gx_color_index color1)) [OPTIONAL]

	Copy a monochrome image (similar to the PostScript image
operator).  Each scan line is raster bytes wide.  Copying begins at
(data_x,0) and transfers a rectangle of the given width at height to the
device at device coordinate (x,y).  (If the transfer should start at some
non-zero y value in the data, the caller can adjust the data address by
the appropriate multiple of the raster.)  The copying operation writes
device color color0 at each 0-bit, and color1 at each 1-bit: if color0 or
color1 is gx_no_color_index, the device pixel is unaffected if the image
bit is 0 or 1 respectively.  If id is different from gx_no_bitmap_id, it
identifies the bitmap contents unambiguously; a call with the same id will
always have the same data, raster, and data contents.

	This operation, with color0 = gx_no_color_index, is the workhorse
for text display in Ghostscript, so implementing it efficiently is very
important.

int (*tile_rectangle)(P10(gx_device *, const gx_tile_bitmap *tile,
  int x, int y, int width, int height,
  gx_color_index color0, gx_color_index color1,
  int phase_x, int phase_y)) [OPTIONAL] [OBSOLETE]

	This procedure is still supported, but has been superseded by
strip_tile_rectangle.  New drivers should implement strip_tile_rectangle; if
they cannot cope with non-zero shift values, they should test for this
explicitly and call the default implementation
(gx_default_strip_tile_rectangle) if shift != 0.  Clients should call
strip_tile_rectangle, not tile_rectangle.

int (*strip_tile_rectangle)(P10(gx_device *, const gx_strip_bitmap *tile,
  int x, int y, int width, int height,
  gx_color_index color0, gx_color_index color1,
  int phase_x, int phase_y)) [OPTIONAL]

	Tile a rectangle.  Tiling consists of doing multiple copy_mono
operations to fill the rectangle with copies of the tile.  The tiles are
aligned with the device coordinate system, to avoid "seams".
Specifically, the (phase_x, phase_y) point of the tile is aligned with the
origin of the device coordinate system.  (Note that this is backwards from
the PostScript definition of halftone phase.)  phase_x and phase_y are
guaranteed to be in the range [0..tile->width) and [0..tile->height)
respectively.

	If color0 and color1 are both gx_no_color_index, then the tile is
a color pixmap, not a bitmap: see the next section.

	This operation is the workhorse for halftone filling in Ghostscript,
so implementing it efficiently for solid tiles (i.e., where either color0
and color1 are both gx_no_color_index, for colored halftones, or neither one
is gx_no_color_index, for monochrome halftones) is very important.

Pixmap imaging
--------------

Pixmaps are just like bitmaps, except that each pixel occupies more than
one bit.  All the bits for each pixel are grouped together (this is
sometimes called "chunky" or "Z" format).  For copy_color, the number of
bits per pixel is given by the color_info.depth parameter in the device
structure: the legal values are 1, 2, 4, 8, 16, 24, or 32.  The pixel
values are device color codes (i.e., whatever it is that map_rgb_color
returns).

int (*copy_color)(P9(gx_device *, const unsigned char *data, int data_x,
  int raster, gx_bitmap_id id, int x, int y, int width, int height))
  [OPTIONAL]

	Copy a color image with multiple bits per pixel.  The raster is in
bytes, but x and width are in pixels, not bits.  If id is different from
gx_no_bitmap_id, it identifies the bitmap contents unambiguously; a call
with the same id will always have the same data, raster, and data contents.

We do not provide a separate procedure for tiling with a pixmap; instead,
tile_rectangle can also take colored tiles.  This is indicated by the
color0 and color1 arguments both being gx_no_color_index.  In this case,
as for copy_color, the raster and height in the "bitmap" are interpreted
as for real bitmaps, but the x and width are in pixels, not bits.

int (*copy_alpha)(P11(gx_device *dev, const unsigned char *data, int data_x,
  int raster, gx_bitmap_id id, int x, int y, int width, int height,
  gx_color_index color, int depth)) [OPTIONAL]

	Fill a given region with a given color modified by an individual
alpha value for each pixel.  depth, the number of bits per pixel, is
either 2 or 4, and in any case is always a value returned by a previous
call on the get_alpha_bits procedure.  Note that if get_alpha_bits always
returns 1, this procedure will never be called.

Bitmap/pixmap imaging
---------------------

int (*copy_rop)(P15(gx_device *dev,
  const byte *sdata, int sourcex, uint sraster, gx_bitmap_id id,
  const gx_color_index *scolors,
  const gx_tile_bitmap *texture, const gx_color_index *tcolors,
  int x, int y, int width, int height,
  int phase_x, int phase_y, int command)) [OPTIONAL]

	This procedure is still supported, but has been superseded by
strip_copy_rop.  New drivers should implement strip_copy_rop; if they cannot
cope with non-zero shift values in the texture, they should test for this
explicitly and call the default implementation (gx_default_strip_copy_rop)
if shift != 0.  Clients should call strip_copy_rop, not copy_rop.

int (*strip_copy_rop)(P15(gx_device *dev,
  const byte *sdata, int sourcex, uint sraster, gx_bitmap_id id,
  const gx_color_index *scolors,
  const gx_strip_bitmap *texture, const gx_color_index *tcolors,
  int x, int y, int width, int height,
  int phase_x, int phase_y, int command)) [OPTIONAL]

	Combine an optional source image S (as for copy_mono or copy_color)
and an optional texture T (a tile, as for tile_rectangle) with the existing
bitmap or pixmap D held by the driver, pixel by pixel, using any 3-input
Boolean operation as modified by "transparency" flags: schematically, set D
= f(D,S,T), computing f in RGB space rather than using actual device pixel
values.  S and T may each (independently) be a solid color, a bitmap with
"foreground" and "background" colors, or a pixmap.  This is a complex (and
currently rather slow) operation.  The arguments are as follows:

	dev - the device, as for all driver procedures

	sdata, sourcex, sraster, id, scolors - specify S, see below

	texture, tcolors - specify T, see below

	x, y, width, height - as for the other copy/fill procedures

	phase_x, phase_y - part of T specification, see below

	command - see below

S specification
...............

As noted above, the source (S) may be a solid color, a bitmap, or a pixmap.

If S is a solid color:

	- sdata, sourcex, sraster, and id are irrelevant.

	- scolors points to two gx_color_index values; scolors[0] =
	scolors[1] = the color.

If S is a bitmap:

	- sdata, sourcex, sraster, and id arguments are as for copy_mono or
	copy_color (data, data_x, raster, id), and specify a source bitmap.

	- scolors points to two gx_color_index values; scolors[0] is the
	background color (the color corresponding to 0-bits in the bitmap),
	scolors[1] is the foreground color (the color corresponding to
	1-bits in the bitmap).

If S is a pixmap:

	- sdata, sourcex, sraster, and id arguments are as for copy_mono or
	copy_color (data, data_x, raster, id), and specify a source pixmap
	whose depth is the same as the depth of the destination.

	- scolors is NULL.

Note that if the source is a bitmap with background=0 and foreground=1, and
the destination is 1 bit deep, then the source can be treated as a pixmap
(scolors=NULL).

T specification
...............

Similar to the source, the texture (T) may be a solid color, a bitmap, or a
pixmap.

If T is a solid color:

	- The texture pointer is irrelevant.

	- tcolors points to two gx_color_index values; tcolors[0] =
	tcolors[1] = the color.

If T is a bitmap:

	- The texture argument points to a gx_tile_bitmap, as for the
	tile_rectangle procedure.  Similarly, phase_x and phase_y specify
	the offset of the texture relative to the device coordinate system
	origin, again as for tile_rectangle.  The tile is a bitmap (1 bit
	per pixel).

	- tcolors points to two gx_color_index values; tcolors[0] is the
	background color (the color corresponding to 0-bits in the bitmap),
	tcolors[1] is the foreground color (the color corresponding to
	1-bits in the bitmap).

If T is a pixmap:

	- The texture argument pointer to a gx_tile_bitmap whose depth is
	the same as the depth of the destination.

	- tcolors is NULL.

Again, if the texture is a bitmap with background=0 and foreground=1, and
the destination depth is 1, the texture bitmap can be treated as a pixmap
(tcolors=NULL).

Note that while a source bitmap or pixmap has the same width and height as
the destination, a texture bitmap or pixmap has its own width and height
specified in the gx_tile_bitmap structure, and is replicated and/or clipped
as needed.

f specification
...............

Command indicates the raster operation and transparency as follows:

	bits 7-0: raster op
	bit 8: 0 if source opaque, 1 if source transparent
	bit 9: 0 if texture opaque, 1 if texture transparent
	bits ?-10: unused, must be 0

The raster operation follows the Microsoft and H-P specification.  It is an
8-element truth table that specifies the output value for each of the
possible 2x2x2 input values as follows:

	Bit	Texture	Source	Destination
	7	1	1	1
	6	1	1	0
	5	1	0	1
	4	1	0	0
	3	0	1	1
	2	0	1	0
	1	0	0	1
	0	0	0	0

Transparency affects the output in the following way.  A source or texture
pixel is considered transparent if its value is all 1's (e.g., 1 for
bitmaps, 0xffffff for 24-bit RGB pixmaps) *and* the corresponding
transparency bit is set in the command.  For each pixel, the result of the
Boolean operation is written into the destination iff neither the source nor
the texture pixel is transparent.  (Note that the H-P RasterOp
specification, on which this is based, specifies that if the source and
texture are both all 1's and the command specifies transparent source and
opaque texture, the result *should* be written in the output.  We think this
is an error in the documentation.)

Notes
.....

Note that copy_rop is defined to operate on pixels in RGB space, again
following the H-P and Microsoft specification.  For devices that don't use
RGB (or gray-scale with black=0, white=all 1's) as their native color
representation, the implementation of copy_rop must convert to RGB or gray
space, do the operation, and convert back (or do the equivalent of this).

Here are the copy_rop equivalents of the most important previous imaging
calls.  Note that rop3_S may be replaced by any other Boolean operation.
For monobit devices, we assume that black = 1.  We assume the following
declaration:
	static const gx_color_index white2[2] = { 1, 1 };

/* For all devices: */
(*fill_rectangle)(dev, x, y, w, h, color) ==>

	{ gx_color_index colors[2];
	  colors[0] = colors[1] = color;
	  (*dev_proc(dev, copy_rop))(dev, NULL, 0, 0, gx_no_bitmap_id, colors,
				     NULL, colors /*irrelevant*/,
				     x, y, w, h, 0, 0, rop3_S);
	}

/* For black-and-white devices only: */
(*copy_mono)(dev, base, sourcex, sraster, id,
	     x, y, w, h, (gx_color_index)0, (gx_color_index)1) ==>

	(*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, NULL,
				   NULL, white2 /*irrelevant*/,
				   x, y, w, h, 0, 0, rop3_S);

/* For color devices, where neither color0 nor color1 is gx_no_color_index: */
(*copy_mono)(dev, base, sourcex, sraster, id,
	     x, y, w, h, color0, color1) ==>

	{ gx_color_index colors[2];
	  colors[0] = color0, colors[1] = color1;
	  (*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, colors,
				     NULL, white2 /*irrelevant*/,
				     x, y, w, h, 0, 0, rop3_S);
	}

/* For black-and-white devices only: */
(*copy_mono)(dev, base, sourcex, sraster, id,
	     x, y, w, h, gx_no_color_index, (gx_color_index)1) ==>

	(*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, NULL,
				   NULL, white2 /*irrelevant*/,
				   x, y, w, h, 0, 0,
				   rop3_S | lop_S_transparent);

/* For all devices: */
(*copy_color)(dev, base, sourcex, sraster, id,
	      x, y, w, h) ==> [same as first copy_mono above]

/* For black-and-white devices only: */
(*tile_rectangle)(dev, tile, x, y, w, h,
		  (gx_color_index)0, (gx_color_index)1, px, py) ==>

	(*dev_proc(dev, copy_rop))(dev, NULL, 0, 0, gx_no_bitmap_id,
				   white2 /*irrelevant*/,
				   tile, NULL,
				   x, y, w, h, px, py, rop3_T)

Polygons