drivers.txt

实现并行算法

--------

In addition to the lowest-level drawing operations that take integer device
coordinates and pure device colors, the driver interface includes
higher-level operations that draw polygons using fixed-point coordinates,
possibly halftoned colors, and possibly a non-default logical operation.

The fill_* drawing operations all use the center-of-pixel rule: a pixel is
colored iff its center falls within the polygonal region being filled.  If a
pixel center (X+0.5,Y+0.5) falls exactly on the boundary, the pixel is
filled iff the boundary is horizontal and the filled region is above it, or
the boundary is not horizontal and the filled region is to the right of it.

int (*fill_trapezoid)(P10(gx_device *dev,
  fixed fx0, fixed fw0, fixed fy0,
  fixed fx1, fixed fw1, fixed fh, bool swap_axes,
  const gx_drawing_color *pdcolor, gs_logical_operation_t lop)) [OPTIONAL]

	Fill a trapezoid whose parallel sides are parallel to a coordinate
axis.  The corners are (fx0,fy0), (fx0+fw0,fy0), (fx1,fy0+fh), and
(fx1+fw1,fy0+fy).  We require fw0 >= 0, fw1 >= 0, and fh >= 0; if fw0 = 0 or
fw1 = 0, the trapezoid is actually a triangle.  If swap_axes is set, the
meanings of X and Y are interchanged.

int (*fill_parallelogram)(P9(gx_device *dev,
  fixed px, fixed py, fixed ax, fixed ay, fixed bx, fixed by,
  const gx_drawing_color *pdcolor, gs_logical_operation_t lop)) [OPTIONAL]

	Fill a parallelogram whose corners are (px,py), (px+ax,py+ay),
(px+bx,py+by), and (px+ax+bx,py+ay+by).  There are no constraints on the
values of any of the parameters, so the parallelogram may have any
orientation relative to the coordinate axes.

int (*fill_triangle)(P9(gx_device *dev,
  fixed px, fixed py, fixed ax, fixed ay, fixed bx, fixed by,
  const gx_drawing_color *pdcolor, gs_logical_operation_t lop)) [OPTIONAL]

	Fill a triangle whose corners are (px,py), (px+ax,py+ay), and
(px+bx,py+by).

int (*draw_thin_line)(P7(gx_device *dev,
  fixed fx0, fixed fy0, fixed fx1, fixed fy1,
  const gx_drawing_color *pdcolor, gs_logical_operation_t lop)) [OPTIONAL]

	Draw a one-pixel-wide line from (fx0,fy0) to (fx1,fy1).  This
replaces the older draw_line procedure, which required integer coordinates,
a pure color, and no logical operation.

High-level drawing
------------------

In addition to the low-level drawing operations described above, the driver
interface provides a set of high-level operations.  Normally these will have
their default implementation, which converts the high-level operation to the
low-level ones just described; however, drivers that generate high-level
output formats such as CGM, or communicate with devices that have firmware
for higher-level operations such as polygon fills, may implement these
high-level operations directly.

For more details, please consult the source code, specifically:
	gxpaint.h - defines gx_fill_params, gx_stroke_params
	gxfixed.h - defines fixed, gs_fixed_point (used by gx_*_params)
	gxistate.h - defines gs_imager_state (used by gx_*_params)
	gxline.h - defines gx_line_params (used by gs_imager_state)
	gslparam.h - defines line cap/join values (used by gx_line_params)
	gxmatrix.h - defines gs_matrix_fixed (used by gs_imager_state)
	g[s,x,z]path.h - defines gx_path
	g[x,z]cpath.h - defines gx_clip_path

int (*fill_path)(P6(gx_device *dev,
  const gx_imager_state *pis, gx_path *ppath, const gx_fill_params *params,
  const gx_drawing_color *pdcolor, const gx_clip_path *pcpath)) [OPTIONAL]

	Fill the given path, clipped by the given clip path, according to
the given parameters, with the given color.  The clip path pointer may be
NULL, meaning do not clip.

int (*stroke_path)(P6(gx_device *dev,
  const gx_imager_state *pis, gx_path *ppath, const gx_stroke_params *params,
  const gx_drawing_color *pdcolor, const gx_clip_path *pcpath)) [OPTIONAL]

	Stroke the given path, clipped by the given clip path, according to
the given parameters, with the given color.  The clip path pointer may be
NULL, meaning do not clip.

int (*fill_mask)(P13(gx_device *dev,
  const byte *data, int data_x, int raster, gx_bitmap_id id,
  int x, int y, int width, int height,
  const gx_drawing_color *pdcolor, int depth,
  int command, const gx_clip_path *pcpath)) [OPTIONAL]

	Color the 1-bits in the given mask (or according to the alpha
values, if depth > 1), clipped by the given clip path, with the given color
and logical operation.  The clip path pointer may be NULL, meaning do not
clip.  The parameters data, ..., height are as for copy_mono; depth is as
for copy_alpha; command is as for copy_rop.

High-level bitmap imaging
-------------------------

Similar to the high-level interface for fill/stroke graphics, a high-level
interface exists for bitmap images.  All of the procedures in this part of
the interface are optional; however, if any one of them is defined, they all
must be.  THIS INTERFACE IS NOT FULLY DEFINED YET, AND THE INFORMATION
PRESENTED HERE IS SUBJECT TO CHANGE.

A bitmap image is defined by a gs_image_t structure.  We only summarize this
structure here.

typedef struct gs_image_s {
	int Width;		/* Width of source image in pixels */
	int Height;		/* Height ditto */
	gs_matrix ImageMatrix;	/* transformation from 1x1 image space to */
				/* user space defined by imager CTM */
	int BitsPerComponent;
	const gs_color_space *ColorSpace;
	float Decode[8];	/* linear remapping of input values */
	bool Interpolate;	/* smooth image if true */
	bool ImageMask;		/* true = mask, false = solid image */
	bool adjust;		/* expand bits if mask */
	bool CombineWithColor;	/* use drawing color as RasterOp texture */
} gs_image_t;
typedef enum {
	gs_image_format_chunky = 0,
	gs_image_format_component_planar = 1
} gs_image_format_t;

For more details, consult the source code in
	gsiparam.h - defines parameters for an image

int (*begin_image)(P9(gx_device *dev,
  const gs_imager_state *pis, const gs_image_t *pim, gs_image_format_t format,
  gs_image_shape_t shape, const gx_drawing_color *pdcolor,
  const gx_clip_path *pcpath, gs_memory_t *memory, void **pinfo)) [OPTIONAL]

	Begin the transmission of an image.  Zero or more calls of
image_data will follow, and then a call of end_image.  The parameters of
begin_image are as follows:

	pis - pointer to an imager state.  The only relevant elements of the
imager state are the CTM (coordinate transformation matrix), the logical
operation (RasterOp/transparency), and the color rendering information.

	pim - pointer to the gs_image_t structure that defines the image
parameters.

	format - defines how pixels are represented for image_data.  See the
description of image_data below.

	shape - a bit mask that defines whether the client promises to
supply the full Width x Height array of pixels, or whether only a
subrectangle or irregular subset may be supplied; see the source code for
details.

	pdcolor - defines a drawing color, only needed for masks or if
CombineWithColor is true.

	pcpath - defines an optional clipping path, may be NULL.

	memory - defines the allocator to be used for allocating bookkeeping
information.

	pinfo - the implementation should return a pointer to its
bookkeeping structure here.

	begin_image is expected to allocate a structure for its bookkeeping
needs, using the allocator defined by the memory parameter, and return it in
*pinfo.  begin_image should not assume that the structures in *pim or
*pdcolor will survive the call on begin_image (except for the color space in
*pim->ColorSpace): it should copy any necessary parts of them into its own
bookkeeping structure.  It may, however, assume that *pis, *pcpath, and of
course *memory will live at least until end_image is called.

int (*image_data)(P8(gx_device *dev,
  void *info, const byte **planes, uint raster,
  int x, int y, int width, int height)) [OPTIONAL]

	This call provides more of the image source data.  Because of
banding, image_data will not necessarily receive complete rows, or all the
rows of an image; that is why the call supplies the source x, y, width, and
height parameters.  However, if x1/y1/w1/h1 and x2/y2/w2/h2 are the values
of these parameters for two successive calls on image_data, the following
properties are guaranteed:

	- 0 <= xi <= xi + wi <= params->Width.
	- 0 <= yi <= yi + hi <= params->Height.

	- If h1 > 1, then y2 = y1 + h1.

	- If h1 = 1, then either y2 = y1 + h1, or y2 = y1 and
	x2 = x1 + w1 and h2 = 1.

In other words, either a call passes 1 or more consecutive rows, or several
calls pass adjacent parts of a single row.  Note that the x/y/width/height
values refer to the source image data, not to the destination as they do for
copy_mono, copy_color, etc.

	The data for each row are packed big-endian within each byte.  The
raster (number of bytes per row) may include some padding at the end of each
row.  Note that for non-mask images, the input data may be in any color
space and may have any number of bits per component (1, 2, 4, 8, 12).
(Currently mask images always have 1 bit per component, but in the future,
they might allow multiple bits of alpha.)  Note also that each call of
image_data passes complete pixels: e.g., for a chunky image with 24 bits per
pixel, each call of image_data passes 3N bytes of data (specifically, 3 *
width * height).

	The interpretation of planes depends on the format argument of
begin_image.  If format is gs_image_format_chunky, planes[0] points to data
in "chunky" format, in which the components follow each other (e.g.,
RGBRGBRGB....)  If format is gs_image_format_component_planar, planes[0
.. N-1] point to data for the N components (e.g., N=3 for RGB data); each
plane contains samples for a single component, e.g., RR..., GG..., BB....
Note that the planes are divided by component, not by bit: for example, for
24-bit RGB data, N=3, with 8-bit values in each plane of data.  Someday we
may add gs_image_format_bit_planar, specifying that each plane would contain
only a single bit of the pixel value, but this is not currently implemented.

	image_data, unlike most other driver procedures that take bitmaps as
arguments, does not require the data to be aligned in any way.

int end_image(P3(gx_device *dev,
  void *info, bool draw_last)) [OPTIONAL]

	Finish processing an image, either because all data have been
supplied or because the caller has decided to abandon this image.  end_image
may be called at any time after begin_image.  It should free the info
structure and any subsidiary structures.  If draw_last is true, it should
finish drawing any buffered lines of the image.

	While there will almost never be more than one image enumeration in
progress -- i.e., after a begin_image, end_image will almost always be
called before the next begin_image -- driver code should not rely on this
property; in particular, it should store all information regarding the image
in the info structure, not in the driver structure.

	Note that if begin_image saves its parameters in the info structure,
it can decide on each call whether to use its own algorithms or to use the
default implementation.  (It may need to call gx_default_begin/end_image
partway through.)  [A later revision of this document may include an example
here.]

Reading bits back
-----------------

int (*get_bits)(P4(gx_device *, int y, byte *str, byte **actual_data))
  [OPTIONAL]

	Read one scan line of bits back from the device into the area
starting at str, namely, scan line y.  If the bits cannot be read back
(e.g., from a printer), return -1; otherwise return 0.  The contents of the
bits beyond the last valid bit in the scan line (as defined by the device
width) are unpredictable.  str need not be aligned in any particular way.

	If actual_data is NULL, the bits are always returned at str.  If
actual_data is not NULL, get_bits may either copy the bits to str and set
*actual_data = str, or it may leave the bits where they are and return a
pointer to them in *actual_data.  In the latter case, the bits are
guaranteed to start on a 32-bit boundary and to be padded to a multiple of
32 bits; also in this case, the bits are not guaranteed to still be there
after the next call on get_bits.

Parameters
----------

Devices may have an open-ended set of parameters, which are simply pairs
consisting of a name and a value.  The value may be of various types:
integer (int or long), boolean, float, string, name, null, array of integer,
or array of float.  For example, the Name of a device is a string; the
Margins of a device is an array of 2 floats.  See gsparam.h for more
details.

If a device has parameters other than the ones applicable to all devices
(or, in the case of printer devices, all printer devices), it must provide
get_params and put_params procedures.  If your device has parameters beyond
those of a straightforward display or printer, we strongly advise using the
_get_params and _put_params procedures in an existing device (for example,
gdevcdj.c or gdevbit.c) as a model for your own code.

int (*get_params)(P2(gx_device *dev, gs_param_list *plist)) [OPTIONAL]

	Read the parameters of the device into the parameter list at plist,
using the param_write_* macros/procedures defined in gsparam.h.
    
int (*put_params)(P2(gx_device *dev, gs_param_list *plist)) [OPTIONAL]

	Set the parameters of the device from the parameter list at plist,
using the param_read_* macros/procedures defined in gsparam.h.  All
put_params procedures must use a "two-phase commit" algorithm; see gsparam.h
for details.

External fonts
--------------

Drivers may include the ability to display text.  More precisely, they may
supply a set of procedures that in turn implement some font and text
handling capabilities.  These procedures are documented in another file,
xfonts.txt.  The link between the two is the driver procedure that
supplies the font/text procedures:

xfont_procs *(*get_xfont_procs)(P1(gx_device *dev)) [OPTIONAL]

	Return a structure of procedures for handling external fonts and
text display.  A NULL value means that this driver doesn't provide this
capability.

For technical reasons, a second procedure is also needed:

gx_device *(*get_xfont_device)(P1(gx_device *dev)) [OPTIONAL]

	Return the device that implements get_xfont_procs in a non-default
way for this device, if any.  Except for certain special internal devices,
this is always the device argument.

Page devices
------------

gx_device *(*get_page_device)(P1(gx_device *dev)) [OPTIONAL]

	According to the Adobe specifications, some devices are "page
devices" and some are not.  This procedure returns NULL if the device is
not a page device, or the device itself if it is a page device.  In the
case of forwarding devices, get_page_device returns the underlying page
device (or NULL if the underlying device is not a page device).

Miscellaneous
-------------

int (*get_band)(P3(gx_device *dev, int y, int *band_start)) [OPTIONAL]

	If the device is a band device, this procedure stores in *band_start
the scan line (device Y coordinate) of the band that includes the given Y
coordinate, and returns the number of scan lines in the band.  If the device
is not a band device, this procedure returns 0.  The latter is the default
implementation.