drivers.htm

GhostScript的源代码

int&nbsp;x1, int&nbsp;y1, gx_color_index&nbsp;color))</tt></b> <b><em>[OPTIONAL]</em></b>
<dd>Draw a minimum-thickness line from <em>(x0,y0)</em> to
<em>(x1,y1)</em>.  The precise set of points to be filled is defined as
follows.  First, if <b><tt>y1</tt></b>&nbsp;&lt;&nbsp;<b><tt>y0</tt></b>,
exchange <em>(x0,y0)</em> and <em>(x1,y1)</em>.  Then the line includes the
point <em>(x0,y0)</em> but not the point <em>(x1,y1)</em>.  If
<b><tt>x0</tt></b>&nbsp;=&nbsp;<b><tt>x1</tt></b> and
<b><tt>y0</tt></b>&nbsp;=&nbsp;<b><tt>y1</tt></b>,
<b><tt>draw_line</tt></b> should return 0 without drawing anything.
</dl>

<h2><a name="Bitmap_imaging"></a>Bitmap imaging</h2>

<p>
Bitmap (or pixmap) images are stored in memory in a nearly standard way.
The first byte corresponds to <em>(0,0)</em> 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.

<dl>
<dt><b><tt>int (*copy_mono)(P11(gx_device&nbsp;*,
const&nbsp;unsigned&nbsp;char&nbsp;*data, int&nbsp;data_x, int&nbsp;raster,
gx_bitmap_id&nbsp;id, int&nbsp;x, int&nbsp;y, int&nbsp;width,
int&nbsp;height, gx_color_index&nbsp;color0,
gx_color_index&nbsp;color1))</tt></b> <b><em>[OPTIONAL]</em></b>
<dd>Copy a monochrome image (similar to the PostScript image operator).
Each scan line is raster bytes wide.  Copying begins at
(<b><tt>data_x</tt></b>,0) and transfers a rectangle of the given width and
height to the device at device coordinate <em>(x,y)</em>.  (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 <b><tt>color0</tt></b> at each 0-bit, and
<b><tt>color1</tt></b> at each 1-bit: if <b><tt>color0</tt></b> or
<b><tt>color1</tt></b> is <b><tt>gx_no_color_index</tt></b>, the device
pixel is unaffected if the image bit is 0 or 1 respectively.  If
<b><tt>id</tt></b> is different from <b><tt>gx_no_bitmap_id</tt></b>, it
identifies the bitmap contents unambiguously; a call with the same
<b><tt>id</tt></b> will always have the same <b><tt>data</tt></b>,
<b><tt>raster</tt></b>, and data contents.

<p>
This operation, with
<b><tt>color0</tt></b>&nbsp;=&nbsp;<b><tt>gx_no_color_index</tt></b>, is
the workhorse for text display in Ghostscript, so implementing it
efficiently is very important.
</dl>

<dl>
<dt><b><tt>int (*tile_rectangle)(P10(gx_device&nbsp;*,
const&nbsp;gx_tile_bitmap&nbsp;*tile, int&nbsp;x, int&nbsp;y,
int&nbsp;width, int&nbsp;height, gx_color_index&nbsp;color0,
gx_color_index&nbsp;color1, int&nbsp;phase_x, int&nbsp;phase_y))</tt></b>
<b><em>[OPTIONAL] [OBSOLETE]</em></b>
<dd>This procedure is still supported, but has been superseded by
<b><tt>strip_tile_rectangle</tt></b>.  New drivers should implement
<b><tt>strip_tile_rectangle</tt></b>; if they cannot cope with non-zero
shift values, they should test for this explicitly and call the default
implementation (<b><tt>gx_default_strip_tile_rectangle</tt></b>) if
shift&nbsp;!=&nbsp;0.  Clients should call
<b><tt>strip_tile_rectangle</tt></b>, not <b><tt>tile_rectangle</tt></b>.
</dl>

<dl>
<dt><b><tt>int (*strip_tile_rectangle)(P10(gx_device&nbsp;*,
const&nbsp;gx_strip_bitmap&nbsp;*tile, int&nbsp;x, int&nbsp;y,
int&nbsp;width, int&nbsp;height, gx_color_index&nbsp;color0,
gx_color_index&nbsp;color1, int&nbsp;phase_x, int&nbsp;phase_y))</tt></b>
<b><em>[OPTIONAL]</em></b>
<dd>Tile a rectangle.  Tiling consists of doing multiple
<b><tt>copy_mono</tt></b> operations to fill the rectangle with copies of
the tile.  The tiles are aligned with the device coordinate system, to
avoid "seams".  Specifically, the (<b><tt>phase_x</tt></b>,
<b><tt>phase_y</tt></b>) 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.)  <b><tt>phase_x</tt></b> and
<b><tt>phase_y</tt></b> are guaranteed to be in the range
<em>[0..</em><b><tt>tile-&gt;width</tt></b><em>)</em> and
<em>[0..</em><b><tt>tile-&gt;height</tt></b><em>)</em> respectively.

<p>
If <b><tt>color0</tt></b> and <b><tt>color1</tt></b> are both
<b><tt>gx_no_color_index</tt></b>, then the tile is a color pixmap, not a
bitmap: see the next section.

<p>
This operation is the workhorse for halftone filling in Ghostscript, so
implementing it efficiently for solid tiles (that is, where either
<b><tt>color0</tt></b> and <b><tt>color1</tt></b> are both
<b><tt>gx_no_color_index</tt></b>, for colored halftones, or neither one is
<b><tt>gx_no_color_index</tt></b>, for monochrome halftones) is very
important.
</dl>

<h2><a name="Pixmap_imaging"></a>Pixmap imaging</h2>

<p>
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 <b><tt>copy_color</tt></b>,
the number of bits per pixel is given by the
<b><tt>color_info.depth</tt></b> parameter in the device structure: the
legal values are 1, 2, 4, 8, 16, 24, or 32.  The pixel values are device
color codes (that is, whatever it is that <b><tt>map_rgb_color</tt></b>
returns).

<dl>
<dt><b><tt>int (*copy_color)(P9(gx_device&nbsp;*,
const&nbsp;unsigned&nbsp;char&nbsp;*data, int&nbsp;data_x, int&nbsp;raster,
gx_bitmap_id&nbsp;id, int&nbsp;x, int&nbsp;y, int&nbsp;width,
int&nbsp;height))</tt></b> <b><em>[OPTIONAL]</em></b>
<dd>Copy a color image with multiple bits per pixel.  The raster is in
bytes, but <b><tt>x</tt></b> and <b><tt>width</tt></b> are in pixels, not
bits.  If <b><tt>id</tt></b> is different from
<b><tt>gx_no_bitmap_id</tt></b>, it identifies the bitmap contents
unambiguously; a call with the same <b><tt>id</tt></b> will always have the
same <b><tt>data</tt></b>, <b><tt>raster</tt></b>, and data contents.

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

<h2><a name="Compositing"></a>Compositing</h2>

<p>
In addition to direct writing of opaque pixels, devices must also support
compositing.  Currently two kinds of compositing are defined
(<b><tt>RasterOp</tt></b> and alpha-based), but more may be added in the
future.

<blockquote>
<b><em>THIS AREA OF THE INTERFACE IS SOMEWHAT UNSTABLE: USE AT YOUR OWN
RISK.</em></b>
</blockquote>

<dl>
<dt><b><tt>int (*copy_alpha)(P11(gx_device&nbsp;*dev,
const&nbsp;unsigned&nbsp;char&nbsp;*data, int&nbsp;data_x, int&nbsp;raster,
gx_bitmap_id&nbsp;id, int&nbsp;x, int&nbsp;y, int&nbsp;width,
int&nbsp;height, gx_color_index&nbsp;color, int&nbsp;depth))</tt></b>
<b><em>[OPTIONAL]</em></b>
<dd>This procedure is somewhat misnamed: it was added to the interface
before we really understood alpha channel and compositing.

<p>
Fill a given region with a given color modified by an individual alpha
value for each pixel.  For each pixel, this is equivalent to
alpha-compositing with a source pixel whose alpha value is obtained from
the pixmap (<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, and
<b><tt>raster</tt></b>) and whose color is the given color (which has
<b><em>not</em></b> been premultiplied by the alpha value), using the Sover
rule.  <b><tt>depth</tt></b>, the number of bits per alpha value, is either
2 or 4, and in any case is always a value returned by a previous call on
the <b><tt>get_alpha_bits</tt></b> procedure.  Note that if
<b><tt>get_alpha_bits</tt></b> always returns 1, this procedure will never
be called.
</dl>

<dl>
<dt><b><tt>int (*create_compositor)(P5(dev_t&nbsp;*dev,
gx_device_t&nbsp;**pcdev, const&nbsp;gs_composite_t&nbsp;*pcte,
const&nbsp;gs_imager_state&nbsp;*pis, gs_memory_t&nbsp;*memory))</tt></b>
<b><em>[OPTIONAL]</em></b>
<dd>Create a new device (called a "compositing device" or "compositor")
that will composite data written to it with the device's existing data,
according to the compositing function defined by <b><tt>*pcte</tt></b>.
Devices will normally implement this in one of the following standard ways:

<ul>
<li>Devices that don't do any imaging and don't forward any imaging
operations (for example, the null device, the hit detection device, and the
clipping list accumulation device) simply return themselves, which
effectively ignores the compositing function.

<li>"Leaf" devices that do imaging and have no special optimizations for
compositing (for example, some memory devices) ask the
<b><tt>gs_composite_t</tt></b> to create a default compositor.

<li>Leaf devices that can implement some kinds of compositing operation
efficiently (for example, monobit memory devices and RasterOp) inspect the
type and values of <b><tt>*pcte</tt></b> to determine whether it specifies
such an operation: if so, they create a specialized compositor, and if not,
they ask the <b><tt>gs_composite_t</tt></b> to create a default compositor.
</ul>

<p>
Other kinds of forwarding devices, which don't fall into any of these
categories, require special treatment.  In principle, what they do is ask
their target to create a compositor, and then create and return a copy of
themselves with the target's new compositor as the target of the copy.
There is a possible default implementation of this approach: if the
original device was <b>D</b> with target <b>T</b>, and <b>T</b> creates a
compositor <b>C</b>, then the default implementation creates a device
<b>F</b> that for each operation temporarily changes <b>D</b>'s target to
<b>C</b>, forwards the operation to <b>D</b>, and then changes <b>D</b>'s
target back to <b>T</b>.  However, the Ghostscript library currently only
creates a compositor with an imaging forwarding device as target in a few
specialized situations (banding, and bounding box computation), and these
are handled as special cases.

<p>
Note that the compositor may have a different color space, color
representation, or bit depth from the device to which it is compositing.
For example, alpha-compositing devices use standard-format chunky color
even if the underlying device doesn't.

<p>
Closing a compositor frees all of its storage, including the compositor
itself.  However, since the <b><tt>create_compositor</tt></b> call may
return the same device, clients must check for this case, and only call the
close procedure if a separate device was created.
</dl>

<p>
<font size="+1">
<b><em>[strip_]copy_rop WILL BE SUPERSEDED BY COMPOSITORS</em></b>
</font>

<dl>
<dt><b><tt>int (*copy_rop)(P15(gx_device&nbsp;*dev,
const&nbsp;byte&nbsp;*sdata, int&nbsp;sourcex, uint&nbsp;sraster,
gx_bitmap_id&nbsp;id, const&nbsp;gx_color_index&nbsp;*scolors,
const&nbsp;gx_tile_bitmap&nbsp;*texture,
const&nbsp;gx_color_index&nbsp;*tcolors, int&nbsp;x, int&nbsp;y,
int&nbsp;width, int&nbsp;height, int&nbsp;phase_x, int&nbsp;phase_y,
int&nbsp;command))</tt></b> <b><em>[OPTIONAL]</em></b>
<dd>This procedure is still supported, but has been superseded by
<b><tt>strip_copy_rop</tt></b>.  New drivers should implement
<b><tt>strip_copy_rop</tt></b>; if they cannot cope with non-zero shift
values in the texture, they should test for this explicitly and call the
default implementation (<b><tt>gx_default_strip_copy_rop</tt></b>) if
shift&nbsp;!=&nbsp;0.  Clients should call <b><tt>strip_copy_rop</tt></b>,
not <b><tt>copy_rop</tt></b>.
</dl>

<dl>
<dt><b><tt>int (*strip_copy_rop)(P15(gx_device&nbsp;*dev,
const&nbsp;byte&nbsp;*sdata, int&nbsp;sourcex, uint&nbsp;sraster,
gx_bitmap_id&nbsp;id, const&nbsp;gx_color_index&nbsp;*scolors,
const&nbsp;gx_strip_bitmap&nbsp;*texture,
const&nbsp;gx_color_index&nbsp;*tcolors, int&nbsp;x, int&nbsp;y,
int&nbsp;width, int&nbsp;height, int&nbsp;phase_x, int&nbsp;phase_y,
int&nbsp;command))</tt></b> <b><em>[OPTIONAL]</em></b>
<dd>Combine an optional source image <b>S</b> (as for
<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b>) and an optional
texture <b>T</b> (a tile, as for <b><tt>tile_rectangle</tt></b>) with the
existing bitmap or pixmap <b>D</b> held by the driver, pixel by pixel,
using any 3-input Boolean operation as modified by "transparency" flags:
schematically, set <b>D&nbsp;=&nbsp;f(D,S,T)</b>, computing <b>f</b> in RGB
space rather than using actual device pixel values.  <b>S</b> and <b>T</b>
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:

<blockquote><table cellpadding=0 cellspacing=0>
<tr valign=top>	<td><b><tt>dev</tt></b>
	<td>&nbsp;
	<td>the device, as for all driver procedures
<tr valign=top>	<td><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>, <b><tt>sraster</tt></b>, <b><tt>id</tt></b>, <b><tt>scolors</tt></b>
	<td>&nbsp;
	<td>specify <b>S</b>, <a href="#S_spec">see below</a>
<tr valign=top>	<td><b><tt>texture</tt></b>, <b><tt>tcolors</tt></b>
	<td>&nbsp;
	<td>specify <b>T</b>, <a href="#T_spec">see below</a>
<tr valign=top>	<td><b><tt>x</tt></b>, <b><tt>y</tt></b>, <b><tt>width</tt></b>, <b><tt>height</tt></b>
	<td>&nbsp;
	<td>as for the other copy and fill procedures
<tr valign=top>	<td><b><tt>phase_x</tt></b>, <b><tt>phase_y</tt></b>
	<td>&nbsp;
	<td>part of <b>T</b> specification, <a href="#T_spec">see below</a>
<tr valign=top>	<td><b><tt>command</tt></b>
	<td>&nbsp;
	<td><a href="#F_spec">see below</a>
</table></blockquote>
</dl>

<h3><a name="S_spec"></a>The source specification S</h3>

<p>
As noted above, the source <b>S</b> may be a solid color, a bitmap, or a
pixmap.  If <b>S</b> is a solid color:

<ul>
<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>,
<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> are irrelevant.

<li><b><tt>scolors</tt></b> points to two <b><tt>gx_color_index</tt></b>
values; <b><tt>scolors[0]</tt></b> = <b><tt>scolors[1]</tt></b> = the
color.
</ul>

<p>
If <b>S</b> is a bitmap:

<ul>
<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>,
<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> arguments are as for
<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b>
(<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, <b><tt>raster</tt></b>,
<b><tt>id</tt></b>), and specify a source bitmap.

<li><b><tt>scolors</tt></b> points to two <b><tt>gx_color_index</tt></b>
values; <b><tt>scolors[0]</tt></b> is the background color (the color
corresponding to 0-bits in the bitmap), <b><tt>scolors[1]</tt></b> is the
foreground color (the color corresponding to 1-bits in the bitmap).
</ul>

<p>
If <b>S</b> is a pixmap: