⟦fcedb2ed3⟧

TextFile

   Copyright (C) 1989 Aladdin Enterprises.  All rights reserved.
   Distributed by Free Software Foundation, Inc.

This file is part of Ghostscript.

Ghostscript is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY.  No author or distributor accepts responsibility
to anyone for the consequences of using it or for whether it serves any
particular purpose or works at all, unless he says so in writing.  Refer
to the Ghostscript General Public License for full details.

Everyone is granted permission to copy, modify and redistribute
Ghostscript, but only under the conditions described in the Ghostscript
General Public License.  A copy of this license is supposed to have been
given to you along with Ghostscript so you can know your rights and
responsibilities.  It should be in a file named COPYING.  Among other
things, the copyright notice and this notice must be preserved on all
copies.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

This file, drivers.doc, describes the interface between Ghostscript and
device drivers.

This file applies to version 1.3 of Ghostscript.  For an overview of
Ghostscript and a list of the documentation files, see README.

********
******** Driver structure ********
********

A device is represented by a structure divided into three parts:
	- procedures that are shared by all instances of each device;
	- parameters that are present in all devices but may be different
	  for each instance; and
	- device-specific parameters.
Normally, the procedure structure is defined and initialized at compile
time.  A prototype of the parameter structure is defined and initialized
at compile time, but is copied and filled in when an instance of the
device is created.

The gx_device_common macro defines the common structure elements, with the
intent that devices define and export a structure along the following
lines:

	typedef struct my_device_s {
		gx_device_common;
		... device-specific parameters ...
	} my_device;
	my_device foo_device = {
		sizeof(my_device),		* params_size
		{ ... procedures ... },		* procs
		... generic parameter values ...
		... device-specific parameter values ...
	};

All the device procedures are called with the device as the first
argument.  Since each device type is actually a different structure type,
the device procedures must be declared as taking a gx_device * as their
first argument, and must cast it to my_device * internally.

Structure definition
--------------------

This essentially duplicates the structure definition in gxdevice.h.

typedef struct gx_device_s {
	int params_size;		/* size of this structure */
	gx_device_procs *procs;		/* pointer to procedure structure */
	gs_matrix initial_matrix;	/* initial transformation */
	int width;			/* width in pixels */
	int height;			/* height in pixels */
	int has_color;			/* true if device supports color */
	unsigned short max_rgb_value;	/* max r, g, b value */
	int bits_per_color_pixel;	/* for copy_color */
	int bits_from_MSB;		/* true if bit-big-endian */
	int is_open;			/* true if device has been opened */
} gx_device;

gx_device_common is a macro consisting of just the element definitions.

********
******** Driver procedures ********
********

All the procedures except map_rgb_color return 0 on success, or -1 on
invalid arguments.

Some procedures are optional.  If a device doesn't supply an optional
procedure proc, the entry in the procedure structure should be
gx_default_proc, e.g. gx_default_tile_rectangle.  The device procedure can
also call this procedure if it doesn't implement the function for
particular values of the arguments.

Open/close/sync
---------------

int (*open_device)(P1(struct gx_device_s *)) [OPTIONAL]

	Open the device: do any initialization associated with making the
device instance valid.  This must be done before any output to the device.

int (*close_device)(P1(struct gx_device_s *)) [OPTIONAL]

	Close the device: release any associated resources.  After this,
output to the device is no longer allowed.

int (*sync_output)(P1(struct gx_device_s *)) [OPTIONAL]

	Synchronize the device.  If any output to the device has been
buffered, send / write it now.

Color mapping
-------------

Ghostscript represents colors internally as RGB values.  In communicating
with devices, however, it assumes that each device has a fixed palette of
colors identified by integers (to be precise, elements of type
gx_color_index).  Aside from assuming that the palette includes white,
black, and (on color devices) pure red, green, and blue, Ghostscript makes
no assumptions about the contents of the palette: it will use spatial
halftones to approximate unavailable colors or gray levels.

gx_color_index (*map_rgb_color)(P4(struct gx_device_s *, unsigned short red,
  unsigned short green, unsigned short blue)) [OPTIONAL]

	Map a RGB color to a device color.  The default algorithm simply
returns the brightness, i.e. max(red, green, blue).  The range of legal
values of the RGB arguments is given by the max_rgb_value element of the
device parameter structure.

int (*map_color_rgb)(P3(struct gx_device_s *, gx_color_index color,
  unsigned short rgb[3])) [OPTIONAL]

	Map a device color code to RGB values.  The default algorithm
simply sets all three elements of the result to the color.

Drawing
-------

All drawing operations use device coordinates and device color values.

int (*fill_rectangle)(P6(struct gx_device_s *, int x, int y,
  int width, int height, gx_color_index color))

	Fill a rectangle with a color.  If width <= 0 or height <= 0,
nothing should be drawn.

int (*draw_line)(P6(struct gx_device_s *, 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).

int (*fill_trapezoid)(P8(struct gx_device_s *, int x0, int y0, int width0,
  int x1, int y1, int width1, gx_color_index color)) [OPTIONAL]

	Fill a trapezoid whose parallel sides are parallel to the X axis.
If width0 < 0, width1 < 0, or width0 = width1 = 0, nothing should be
drawn; however, width0 = 0 or width1 = 0 is valid, and should result in a
triangle being filled.  The points (x0+width0,y0) and (*,y1) are not
included.

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:
whether bits (or polybit color values) are packed into it left-to-right or
right-to-left is given by the bits_from_MSB flag in the device structure.
(0 means right-to-left, 1 means left-to-right.)  Each scan line is padded
to a byte boundary, and is followed immediately by the next scan line.

int (*copy_mono)(P10(struct gx_device_s *, unsigned char *data, int data_x,
  int raster, int x, int y, int width, int height,
  gx_color_index color0, gx_color_index color1))

	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.

	This operation is the workhorse for most of Ghostscript, so
implementing it efficiently is very important.

int (*copy_color)(P8(struct gx_device_s *, unsigned char *data, int data_x,
  int raster, int x, int y, int width, int height))

	Copy a color image with multiple bits per pixel.  All the bits for
each pixel are grouped together.  The number of bits per pixel is given by
the bits_per_color_pixel parameter in the device structure: it must be a
power of 2 or a multiple of 8.  The pixel values are device color codes.

int (*tile_rectangle)(P8(struct gx_device_s *, gx_bitmap *tile,
  int x, int y, int width, int height,
  gx_color_index color0, gx_color_index color1)) [OPTIONAL]

	Tile a rectangle.  The gx_bitmap structure encapsulates a data
pointer, a raster value, and a width and height.  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".

int (*tile_trapezoid)(P10(struct gx_device_s *, gx_bitmap *tile,
  int x0, int y0, int width0, int x1, int y1, int width1,
  gx_color_index color0, gx_color_index color1)) [OPTIONAL]

	Tile a trapezoid similarly.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦fcedb2ed3⟧ TextFile

Derivation

TextFile
