| 2 |
- |
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<title>The interface between Ghostscript and device drivers</title>
|
|
|
5 |
<!-- $Id: Drivers.htm,v 1.58 2005/10/20 19:46:23 ray Exp $ -->
|
|
|
6 |
<!-- Originally: drivers.txt -->
|
|
|
7 |
<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
|
|
|
8 |
</head>
|
|
|
9 |
|
|
|
10 |
<body>
|
|
|
11 |
<!-- [1.0 begin visible header] ============================================ -->
|
|
|
12 |
|
|
|
13 |
<!-- [1.1 begin headline] ================================================== -->
|
|
|
14 |
|
|
|
15 |
<h1>The interface between Ghostscript and device drivers</h1>
|
|
|
16 |
|
|
|
17 |
<!-- [1.1 end headline] ==================================================== -->
|
|
|
18 |
|
|
|
19 |
<!-- [1.2 begin table of contents] ========================================= -->
|
|
|
20 |
|
|
|
21 |
<h2>Table of contents</h2>
|
|
|
22 |
|
|
|
23 |
<blockquote><ul>
|
|
|
24 |
<li><a href="#Adding_drivers">Adding a driver</a>
|
|
|
25 |
<li><a href="#KISS">Keeping things simple</a>
|
|
|
26 |
<li><a href="#Structure">Driver structure</a>
|
|
|
27 |
<ul>
|
|
|
28 |
<li><a href="#Structure_definition">Structure definition</a>
|
|
|
29 |
<li><a href="#Sophisticated">For sophisticated developers only</a>
|
|
|
30 |
</ul>
|
|
|
31 |
<li><a href="#coordinates_and_types">Coordinates and types</a>
|
|
|
32 |
<ul>
|
|
|
33 |
<li><a href="#Coordinate_system">Coordinate system</a>
|
|
|
34 |
<li><a href="#Color_definition">Color definition</a>
|
|
|
35 |
<ul>
|
|
|
36 |
<li><a href="#sep_and_linear_fields">Separable and linear fields</a>
|
|
|
37 |
<li><a href="#Changing_color_info_data">Changing color_info data</a>
|
|
|
38 |
</ul>
|
|
|
39 |
<li><a href="#Types">Types</a>
|
|
|
40 |
</ul>
|
|
|
41 |
<li><a href="#Coding_conventions">Coding conventions</a>
|
|
|
42 |
<ul>
|
|
|
43 |
<li><a href="#Allocating_storage">Allocating storage</a>
|
|
|
44 |
<li><a href="#Driver_instance_allocation">Driver instance allocation</a>
|
|
|
45 |
</ul>
|
|
|
46 |
<li><a href="#Printer_drivers">Printer drivers</a>
|
|
|
47 |
<li><a href="#Driver_procedures">Driver procedures</a>
|
|
|
48 |
<ul>
|
|
|
49 |
<li><a href="#Life_cycle">Life cycle</a>
|
|
|
50 |
<li><a href="#Open_close">Open, close, sync, copy</a>
|
|
|
51 |
<li><a href="#Color_mapping">Color and alpha mapping</a>
|
|
|
52 |
<li><a href="#Pixel_level_drawing">Pixel-level drawing</a>
|
|
|
53 |
<ul>
|
|
|
54 |
<li><a href="#Bitmap_imaging">Bitmap imaging</a>
|
|
|
55 |
<li><a href="#Pixmap_imaging">Pixmap imaging</a>
|
|
|
56 |
<li><a href="#Compositing">Compositing</a>
|
|
|
57 |
[<a href="#S_spec">S</a>, <a href="#T_spec">T</a>, <a href="#F_spec">f</a>,
|
|
|
58 |
<a href="#Compositing_notes">Notes</a>]
|
|
|
59 |
</ul>
|
|
|
60 |
<li><a href="#Polygon_level_drawing">Polygon-level drawing</a>
|
|
|
61 |
<li><a href="#Linear_color_drawing">Linear color drawing</a>
|
|
|
62 |
<li><a href="#High_level_drawing">High-level drawing</a>
|
|
|
63 |
<ul>
|
|
|
64 |
<li><a href="#Paths">Paths</a>
|
|
|
65 |
<li><a href="#Images">Images</a> [<a href="#Images_notes">Notes</a>]
|
|
|
66 |
<li><a href="#Text">Text</a> [<a href="#Text_notes">Notes</a>]
|
|
|
67 |
<li><a href="#Unicode">Unicode support for high level devices</a>
|
|
|
68 |
</ul>
|
|
|
69 |
<li><a href="#Reading_bits_back">Reading bits back</a>
|
|
|
70 |
<li><a href="#Parameters">Parameters</a>
|
|
|
71 |
<ul>
|
|
|
72 |
<li><a href="#Default_CRD_parameters">Default color rendering dictionary (CRD) parameters</a>
|
|
|
73 |
</ul>
|
|
|
74 |
<li><a href="#External_fonts">External fonts</a>
|
|
|
75 |
<li><a href="#Page_devices">Page devices</a>
|
|
|
76 |
<li><a href="#Miscellaneous">Miscellaneous</a>
|
|
|
77 |
</ul>
|
|
|
78 |
</ul></blockquote>
|
|
|
79 |
|
|
|
80 |
<!-- [1.2 end table of contents] =========================================== -->
|
|
|
81 |
|
|
|
82 |
<!-- [1.3 begin hint] ====================================================== -->
|
|
|
83 |
|
|
|
84 |
<p>For other information, see the <a href="Readme.htm">Ghostscript
|
|
|
85 |
overview</a> and the documentation on <a href="Make.htm">how to build
|
|
|
86 |
Ghostscript</a>.
|
|
|
87 |
|
|
|
88 |
<!-- [1.3 end hint] ======================================================== -->
|
|
|
89 |
|
|
|
90 |
<hr>
|
|
|
91 |
|
|
|
92 |
<!-- [1.0 end visible header] ============================================== -->
|
|
|
93 |
|
|
|
94 |
<!-- [2.0 begin contents] ================================================== -->
|
|
|
95 |
|
|
|
96 |
<h2><a name="Adding_drivers"></a>Adding a driver</h2>
|
|
|
97 |
|
|
|
98 |
<p>
|
|
|
99 |
To add a driver to Ghostscript, first pick a name for your device, say
|
|
|
100 |
"<b><tt>smurf</tt></b>". (Device names must be 1 to 8 characters, begin
|
|
|
101 |
with a letter, and consist only of letters, digits, and underscores. Case
|
|
|
102 |
is significant: all current device names are lower case.) Then all you
|
|
|
103 |
need do is edit <b><tt>contrib.mak</tt></b> in two places.
|
|
|
104 |
|
|
|
105 |
<ol>
|
|
|
106 |
<li>The list of devices, in the section headed "Catalog". Add
|
|
|
107 |
<b><tt>smurf</tt></b> to the list.
|
|
|
108 |
|
|
|
109 |
<li>The section headed "Device drivers".
|
|
|
110 |
|
|
|
111 |
<p>
|
|
|
112 |
Suppose the files containing the smurf driver are called
|
|
|
113 |
"<b><tt>joe</tt></b>" and "<b><tt>fred</tt></b>". Then you should add the
|
|
|
114 |
following lines:
|
|
|
115 |
|
|
|
116 |
<blockquote>
|
|
|
117 |
<pre># ------ The SMURF device ------ #
|
|
|
118 |
|
|
|
119 |
smurf_=$(GLOBJ)joe.$(OBJ) $(GLOBJ)fred.$(OBJ)
|
|
|
120 |
$(DD)smurf.dev: $(smurf_)
|
|
|
121 |
$(SETDEV) $(DD)smurf $(smurf_)
|
|
|
122 |
|
|
|
123 |
$(GLOBJ)joe.$(OBJ) : $(GLSRC)joe.c
|
|
|
124 |
$(GLCC) $(GLO_)joe.$(OBJ) $(C_) $(GLSRC)joe.c
|
|
|
125 |
|
|
|
126 |
$(GLOBJ)fred.$(OBJ) : $(GLSRC)fred.c
|
|
|
127 |
$(GLCC) $(GLO_)fred.$(OBJ) $(C_) $(GLSRC)fred.c</pre>
|
|
|
128 |
</blockquote>
|
|
|
129 |
|
|
|
130 |
<p>
|
|
|
131 |
and whatever <b><tt>joe.c</tt></b> and <b><tt>fred.c</tt></b> depend on.
|
|
|
132 |
If the smurf driver also needs special libraries, for instance a library
|
|
|
133 |
named "<b><tt>gorf</tt></b>", then the entry should look like this:
|
|
|
134 |
|
|
|
135 |
<blockquote>
|
|
|
136 |
<pre>$(DD)smurf.dev : $(smurf_)
|
|
|
137 |
$(SETDEV) $(DD)smurf $(smurf_)
|
|
|
138 |
$(ADDMOD) $(DD)smurf -lib gorf</pre>
|
|
|
139 |
</blockquote>
|
|
|
140 |
|
|
|
141 |
<p>
|
|
|
142 |
If, as will usually be the case, your driver is a printer driver (as
|
|
|
143 |
<a href="#Printer_drivers">discussed below</a>), the device entry should
|
|
|
144 |
look like this:
|
|
|
145 |
|
|
|
146 |
<blockquote>
|
|
|
147 |
<pre>$(DD)smurf.dev : $(smurf_) $(GLD)page.dev
|
|
|
148 |
$(SETPDEV) $(DD)smurf $(smurf_)</pre>
|
|
|
149 |
</blockquote>
|
|
|
150 |
|
|
|
151 |
<p>
|
|
|
152 |
or
|
|
|
153 |
|
|
|
154 |
<blockquote>
|
|
|
155 |
<pre>$(DD)smurf.dev : $(smurf_) $(GLD)page.dev
|
|
|
156 |
$(SETPDEV) $(DD)smurf $(smurf_)
|
|
|
157 |
$(ADDMOD) $(DD)smurf -lib gorf</pre>
|
|
|
158 |
</blockquote>
|
|
|
159 |
|
|
|
160 |
<p>
|
|
|
161 |
Note that the space before the :, and the explicit compilation rules for the
|
|
|
162 |
.c files, are required for portability,
|
|
|
163 |
</ol>
|
|
|
164 |
|
|
|
165 |
<hr>
|
|
|
166 |
|
|
|
167 |
<h2><a name="KISS"></a>Keeping things simple</h2>
|
|
|
168 |
|
|
|
169 |
<p>
|
|
|
170 |
If you want to add a simple device (specifically, a monochrome printer), you
|
|
|
171 |
probably don't need to read the rest of this document; just use the code in
|
|
|
172 |
an existing driver as a guide. The Epson and Canon BubbleJet drivers <a
|
|
|
173 |
href="../src/gdevepsn.c">gdevepsn.c</a> and <a
|
|
|
174 |
href="../src/gdevbj10.c">gdevbj10.c</a> are good models for dot-matrix
|
|
|
175 |
printers, which require presenting the data for many scan lines at once; the
|
|
|
176 |
DeskJet/LaserJet drivers in <a href="../src/gdevdjet.c">gdevdjet.c</a> are
|
|
|
177 |
good models for laser printers, which take a single scan line at a time but
|
|
|
178 |
support data compression. For color printers, there are unfortunately no
|
|
|
179 |
good models: the two major color inkjet printer drivers, <a
|
|
|
180 |
href="../src/gdevcdj.c">gdevcdj.c</a> and <a
|
|
|
181 |
href="../src/gdevstc.c">gdevstc.c</a>, are far too complex to read.
|
|
|
182 |
|
|
|
183 |
<p>
|
|
|
184 |
On the other hand, if you're writing a driver for some more esoteric
|
|
|
185 |
device, you probably do need at least some of the information in the rest
|
|
|
186 |
of this document. It might be a good idea for you to read it in
|
|
|
187 |
conjunction with one of the existing drivers.
|
|
|
188 |
|
|
|
189 |
<p>
|
|
|
190 |
Duplication of code, and sheer volume of code, is a serious maintenance and
|
|
|
191 |
distribution problem for Ghostscript. If your device is similar to an
|
|
|
192 |
existing one, try to implement your driver by adding some parameterization
|
|
|
193 |
to an existing driver rather than by copying code to create an entirely new
|
|
|
194 |
source module. <a href="../src/gdevepsn.c">gdevepsn.c</a> and <a
|
|
|
195 |
href="../src/gdevdjet.c">gdevdjet.c</a> are good examples of this approach.
|
|
|
196 |
|
|
|
197 |
<hr>
|
|
|
198 |
|
|
|
199 |
<h2><a name="Structure"></a>Driver structure</h2>
|
|
|
200 |
|
|
|
201 |
<p>
|
|
|
202 |
A device is represented by a structure divided into three parts:
|
|
|
203 |
|
|
|
204 |
<ul>
|
|
|
205 |
<li>procedures that are (normally) shared by all instances of each device;
|
|
|
206 |
|
|
|
207 |
<li>parameters that are present in all devices but may be different for
|
|
|
208 |
each device or instance; and
|
|
|
209 |
|
|
|
210 |
<li>device-specific parameters that may be different for each instance.
|
|
|
211 |
</ul>
|
|
|
212 |
|
|
|
213 |
<p>
|
|
|
214 |
Normally the procedure structure is defined and initialized at compile
|
|
|
215 |
time. A prototype of the parameter structure (including both generic and
|
|
|
216 |
device-specific parameters) is defined and initialized at compile time, but
|
|
|
217 |
is copied and filled in when an instance of the device is created. Both of
|
|
|
218 |
these structures should be declared as <b><tt>const</tt></b>, but for backward
|
|
|
219 |
compatibility reasons the latter is not.
|
|
|
220 |
|
|
|
221 |
<p>
|
|
|
222 |
The <b><tt>gx_device_common</tt></b> macro defines the common structure
|
|
|
223 |
elements, with the intent that devices define and export a structure along
|
|
|
224 |
the following lines. Do not fill in the individual generic parameter values
|
|
|
225 |
in the usual way for C structures: use the macros defined for this purpose
|
|
|
226 |
in <a href="../src/gxdevice.h">gxdevice.h</a> or, if applicable, <a
|
|
|
227 |
href="../src/gdevprn.h">gdevprn.h</a>.
|
|
|
228 |
|
|
|
229 |
<blockquote>
|
|
|
230 |
<pre>typedef struct smurf_device_s {
|
|
|
231 |
gx_device_common;
|
|
|
232 |
<b><em>... device-specific parameters ...</em></b>
|
|
|
233 |
} smurf_device;
|
|
|
234 |
smurf_device gs_smurf_device = {
|
|
|
235 |
<b><em>... macro for generic parameter values ...,</em></b>
|
|
|
236 |
{ <b><em>... procedures ...</em></b> }, /* std_procs */
|
|
|
237 |
<b><em>... device-specific parameter values if any ...</em></b>
|
|
|
238 |
};</pre>
|
|
|
239 |
</blockquote>
|
|
|
240 |
<p>
|
|
|
241 |
The device structure instance <b>must</b> have the name
|
|
|
242 |
<b><tt>gs_smurf_device</tt></b>, where <b><tt>smurf</tt></b> is the device
|
|
|
243 |
name used in <b><tt>contrib.mak</tt></b>. <b><tt>gx_device_common</tt></b>
|
|
|
244 |
is a macro consisting only of the element definitions.
|
|
|
245 |
<p>
|
|
|
246 |
All the device procedures are called with the device as the first argument.
|
|
|
247 |
Since each device type is actually a different structure type, the device
|
|
|
248 |
procedures must be declared as taking a <b><tt>gx_device *</tt></b> as
|
|
|
249 |
their first argument, and must cast it to
|
|
|
250 |
<b><tt>smurf_device *</tt></b> internally. For example, in the code
|
|
|
251 |
for the "memory" device, the first argument to all routines is called
|
|
|
252 |
<b><tt>dev</tt></b>, but the routines actually use <b><tt>mdev</tt></b> to
|
|
|
253 |
refer to elements of the full structure, using the following standard
|
|
|
254 |
initialization statement at the beginning of each procedure:
|
|
|
255 |
|
|
|
256 |
<blockquote>
|
|
|
257 |
<pre>gx_memory_device *const mdev = (gx_device_memory *)dev;</pre>
|
|
|
258 |
</blockquote>
|
|
|
259 |
|
|
|
260 |
<p>
|
|
|
261 |
(This is a cheap version of "object-oriented" programming: in C++, for
|
|
|
262 |
example, the cast would be unnecessary, and in fact the procedure table
|
|
|
263 |
would be constructed by the compiler.)
|
|
|
264 |
|
|
|
265 |
<h3><a name="Structure_definition"></a>Structure definition</h3>
|
|
|
266 |
|
|
|
267 |
<p>
|
|
|
268 |
You should consult the definition of struct <b><tt>gx_device_s</tt></b> in
|
|
|
269 |
<a href="../src/gxdevice.h">gxdevice.h</a> for the complete details of the
|
|
|
270 |
generic device structure. Some of the most important members of this
|
|
|
271 |
structure for ordinary drivers are:
|
|
|
272 |
|
|
|
273 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
274 |
<tr valign=top> <td><b><tt>const char *dname;</tt></b>
|
|
|
275 |
<td>
|
|
|
276 |
<td>The device name
|
|
|
277 |
<tr valign=top> <td><b><tt>bool is_open;</tt></b>
|
|
|
278 |
<td>
|
|
|
279 |
<td>True if device has been opened
|
|
|
280 |
<tr valign=top> <td><b><tt>gx_device_color_info color_info;</tt></b>
|
|
|
281 |
<td>
|
|
|
282 |
<td>Color information
|
|
|
283 |
<tr valign=top> <td><b><tt>int width;</tt></b>
|
|
|
284 |
<td>
|
|
|
285 |
<td>Width in pixels
|
|
|
286 |
<tr valign=top> <td><b><tt>int height;</tt></b>
|
|
|
287 |
<td>
|
|
|
288 |
<td>Height in pixels
|
|
|
289 |
</table></blockquote>
|
|
|
290 |
|
|
|
291 |
<p>
|
|
|
292 |
The name in the structure (<b><tt>dname</tt></b>) should be the same as the
|
|
|
293 |
name in <a href="../src/contrib.mak">contrib.mak</a>.
|
|
|
294 |
|
|
|
295 |
<h3><a name="Sophisticated"></a>For sophisticated developers only</h3>
|
|
|
296 |
|
|
|
297 |
<p>
|
|
|
298 |
If for any reason you need to change the definition of the basic device
|
|
|
299 |
structure, or to add procedures, you must change the following places:
|
|
|
300 |
|
|
|
301 |
<blockquote><ul>
|
|
|
302 |
<li>This document and the <a href="News.htm">news document</a> (if you want
|
|
|
303 |
to keep the documentation up to date).
|
|
|
304 |
<li>The definition of <b><tt>gx_device_common</tt></b> and the procedures
|
|
|
305 |
in <a href="../src/gxdevcli.h">gxdevcli.h</a>.
|
|
|
306 |
<li>Possibly, the default forwarding procedures declared in
|
|
|
307 |
<a href="../src/gxdevice.h">gxdevice.h</a> and implemented in
|
|
|
308 |
<a href="../src/gdevnfwd.c">gdevnfwd.c</a>.
|
|
|
309 |
<li>The device procedure record completion routines in
|
|
|
310 |
<a href="../src/gdevdflt.c">gdevdflt.c</a>.
|
|
|
311 |
<li>Possibly, the default device implementation in
|
|
|
312 |
<a href="../src/gdevdflt.c">gdevdflt.c</a>,
|
|
|
313 |
<a href="../src/gdevddrw.c">gdevddrw.c</a>, and
|
|
|
314 |
<a href="../src/gxcmap.c">gxcmap.c</a>.
|
|
|
315 |
<li>The bounding box device in <a href="../src/gdevbbox.c">gdevbbox.c</a>
|
|
|
316 |
(probably just adding <b><tt>NULL</tt></b> procedure entries if the
|
|
|
317 |
new procedures don't produce output).
|
|
|
318 |
<li>These devices that must have complete (non-defaulted) procedure vectors:
|
|
|
319 |
<ul>
|
|
|
320 |
<li>The null device in <a href="../src/gdevnfwd.c">gdevnfwd.c</a>.
|
|
|
321 |
<li>The command list "device" in <a href="../src/gxclist.c">gxclist.c</a>.
|
|
|
322 |
This is not an actual device; it only defines procedures.
|
|
|
323 |
<li>The "memory" devices in <a href="../src/gdevmem.h">gdevmem.h</a> and
|
|
|
324 |
<b><tt>gdevm*.c</tt></b>.
|
|
|
325 |
</ul>
|
|
|
326 |
<li>The clip list accumulation "device" in
|
|
|
327 |
<a href="../src/gxacpath.c">gxacpath.c</a>.
|
|
|
328 |
<li>The clipping "devices" <a href="../src/gxclip.c">gxclip.c</a>,
|
|
|
329 |
<a href="../src/gxclip2.c">gxclip2.c</a>,
|
|
|
330 |
and <a href="../src/gxclipm.c">gxclipm.c</a>.
|
|
|
331 |
<li>The pattern accumulation "device" in
|
|
|
332 |
<a href="../src/gxpcmap.c">gxpcmap.c</a>.
|
|
|
333 |
<li>The hit detection "device" in <a href="../src/gdevhit.c">gdevhit.c</a>.
|
|
|
334 |
<li>The generic printer device macros in
|
|
|
335 |
<a href="../src/gdevprn.h">gdevprn.h</a>.
|
|
|
336 |
<li>The generic printer device code in
|
|
|
337 |
<a href="../src/gdevprn.c">gdevprn.c</a>.
|
|
|
338 |
<li>The RasterOp source device in
|
|
|
339 |
<a href="../src/gdevrops.c">gdevrops.c</a>.
|
|
|
340 |
</ul></blockquote>
|
|
|
341 |
|
|
|
342 |
<p>
|
|
|
343 |
You may also have to change the code for
|
|
|
344 |
<b><tt>gx_default_get_params</tt></b> or
|
|
|
345 |
<b><tt>gx_default_put_params</tt></b> in <a
|
|
|
346 |
href="../src/gsdparam.c">gsdparam.c</a>.
|
|
|
347 |
|
|
|
348 |
<p>
|
|
|
349 |
You should not have to change any of the real devices in the standard
|
|
|
350 |
Ghostscript distribution (listed in <a href="../src/devs.mak">devs.mak</a>
|
|
|
351 |
and <a href="../src/contrib.mak">contrib.mak</a>) or any of your own
|
|
|
352 |
devices, because all of them are supposed to use the macros in <a
|
|
|
353 |
href="../src/gxdevice.h">gxdevice.h</a> or <a
|
|
|
354 |
href="../src/gdevprn.h">gdevprn.h</a> to define and initialize their state.
|
|
|
355 |
|
|
|
356 |
<hr>
|
|
|
357 |
|
|
|
358 |
<h2><a name="coordinates_and_types"></a>Coordinates and types</h2>
|
|
|
359 |
|
|
|
360 |
<h3><a name="Coordinate_system"></a>Coordinate system</h3>
|
|
|
361 |
|
|
|
362 |
<p>
|
|
|
363 |
Since each driver specifies the initial transformation from user
|
|
|
364 |
coordinates to device coordinates, the driver can use any coordinate system
|
|
|
365 |
it wants, as long as a device coordinate will fit in an
|
|
|
366 |
<b><tt>int</tt></b>. (This is only an issue on DOS systems, where ints are
|
|
|
367 |
only 16 bits. User coordinates are represented as floats.) Most current
|
|
|
368 |
drivers use a coordinate system with (0,0) in the upper left corner, with
|
|
|
369 |
<b><em>X</em></b> increasing to the right and <b><em>Y</em></b> increasing
|
|
|
370 |
toward the bottom. However, there is supposed to be nothing in the rest of
|
|
|
371 |
Ghostscript that assumes this, and indeed some drivers use a coordinate
|
|
|
372 |
system with (0,0) in the lower left corner.
|
|
|
373 |
|
|
|
374 |
<p>
|
|
|
375 |
Drivers must check (and, if necessary, clip) the coordinate parameters given
|
|
|
376 |
to them: they should not assume the coordinates will be in bounds. The
|
|
|
377 |
<b><tt>fit_fill</tt></b> and <b><tt>fit_copy</tt></b> macros in <a
|
|
|
378 |
href="../src/gxdevice.h">gxdevice.h</a> are very helpful in doing this.
|
|
|
379 |
|
|
|
380 |
<h3><a name="Color_definition"></a>Color definition</h3>
|
|
|
381 |
|
|
|
382 |
<p>
|
|
|
383 |
Between the Ghostscript graphics library and the device, colors are
|
|
|
384 |
represented in three forms. Color components in a color space (Gray, RGB,
|
|
|
385 |
DeviceN, etc.) represented as <b><tt>frac</tt></b> values. Device colorants
|
|
|
386 |
are represented as <b><tt>gx_color_value</tt></b> values. For many
|
|
|
387 |
procedures, colors are represented in a type called
|
|
|
388 |
<b><tt>gx_color_index</tt></b>.
|
|
|
389 |
All three types are described in more detail in <a href="#Types">Types</a>
|
|
|
390 |
|
|
|
391 |
<p>
|
|
|
392 |
The <b><tt>color_info</tt></b> member of the device structure defines the
|
|
|
393 |
color and gray-scale capabilities of the device. Its type is defined as
|
|
|
394 |
follows:
|
|
|
395 |
|
|
|
396 |
<blockquote>
|
|
|
397 |
<pre>
|
|
|
398 |
/*
|
|
|
399 |
* The enlarged color model information structure: Some of the
|
|
|
400 |
* information that was implicit in the component number in
|
|
|
401 |
* the earlier conventions (component names, polarity, mapping
|
|
|
402 |
* functions) are now explicitly provided.
|
|
|
403 |
*
|
|
|
404 |
* Also included is some information regarding the encoding of
|
|
|
405 |
* color information into gx_color_index. Some of this information
|
|
|
406 |
* was previously gathered indirectly from the mapping
|
|
|
407 |
* functions in the existing code, specifically to speed up the
|
|
|
408 |
* halftoned color rendering operator (see
|
|
|
409 |
* gx_dc_ht_colored_fill_rectangle in gxcht.c). The information
|
|
|
410 |
* is now provided explicitly because such optimizations are
|
|
|
411 |
* more critical when the number of color components is large.
|
|
|
412 |
*
|
|
|
413 |
* Note: no pointers have been added to this structure, so there
|
|
|
414 |
* is no requirement for a structure descriptor.
|
|
|
415 |
*/
|
|
|
416 |
typedef struct gx_device_color_info_s {
|
|
|
417 |
|
|
|
418 |
/*
|
|
|
419 |
* max_components is the maximum number of components for all
|
|
|
420 |
* color models supported by this device. This does not include
|
|
|
421 |
* any alpha components.
|
|
|
422 |
*/
|
|
|
423 |
int max_components;
|
|
|
424 |
|
|
|
425 |
/*
|
|
|
426 |
* The number of color components. This does not include any
|
|
|
427 |
* alpha-channel information, which may be integrated into
|
|
|
428 |
* the gx_color_index but is otherwise passed as a separate
|
|
|
429 |
* component.
|
|
|
430 |
*/
|
|
|
431 |
int num_components;
|
|
|
432 |
|
|
|
433 |
/*
|
|
|
434 |
* Polarity of the components of the color space, either
|
|
|
435 |
* additive or subtractive. This is used to interpret transfer
|
|
|
436 |
* functions and halftone threshold arrays. Possible values
|
|
|
437 |
* are GX_CM_POLARITY_ADDITIVE or GX_CM_POLARITY_SUBTRACTIVE
|
|
|
438 |
*/
|
|
|
439 |
gx_color_polarity_t polarity;
|
|
|
440 |
|
|
|
441 |
/*
|
|
|
442 |
* The number of bits of gx_color_index actually used.
|
|
|
443 |
* This must be <= sizeof(gx_color_index), which is usually 64.
|
|
|
444 |
*/
|
|
|
445 |
byte depth;
|
|
|
446 |
|
|
|
447 |
/*
|
|
|
448 |
* Index of the gray color component, if any. The max_gray and
|
|
|
449 |
* dither_gray values apply to this component only; all other
|
|
|
450 |
* components use the max_color and dither_color values.
|
|
|
451 |
*
|
|
|
452 |
* This will be GX_CINFO_COMP_NO_INDEX if there is no gray
|
|
|
453 |
* component.
|
|
|
454 |
*/
|
|
|
455 |
byte gray_index;
|
|
|
456 |
|
|
|
457 |
/*
|
|
|
458 |
* max_gray and max_color are the number of distinct native
|
|
|
459 |
* intensity levels, less 1, for the gray and all other color
|
|
|
460 |
* components, respectively. For nearly all current devices
|
|
|
461 |
* that support both gray and non-gray components, the two
|
|
|
462 |
* parameters have the same value.
|
|
|
463 |
*
|
|
|
464 |
* dither_grays and dither_colors are the number of intensity
|
|
|
465 |
* levels between which halftoning can occur, for the gray and
|
|
|
466 |
* all other color components, respectively. This is
|
|
|
467 |
* essentially redundant information: in all reasonable cases,
|
|
|
468 |
* dither_grays = max_gray + 1 and dither_colors = max_color + 1.
|
|
|
469 |
* These parameters are, however, extensively used in the
|
|
|
470 |
* current code, and thus have been retained.
|
|
|
471 |
*
|
|
|
472 |
* Note that the non-gray values may now be relevant even if
|
|
|
473 |
* num_components == 1. This simplifies the handling of devices
|
|
|
474 |
* with configurable color models which may be set for a single
|
|
|
475 |
* non-gray color model.
|
|
|
476 |
*/
|
|
|
477 |
gx_color_value max_gray; /* # of distinct color levels -1 */
|
|
|
478 |
gx_color_value max_color;
|
|
|
479 |
|
|
|
480 |
gx_color_value dither_grays;
|
|
|
481 |
gx_color_value dither_colors;
|
|
|
482 |
|
|
|
483 |
/*
|
|
|
484 |
* Information to control super-sampling of objects to support
|
|
|
485 |
* anti-aliasing.
|
|
|
486 |
*/
|
|
|
487 |
gx_device_anti_alias_info anti_alias;
|
|
|
488 |
|
|
|
489 |
/*
|
|
|
490 |
* Flag to indicate if gx_color_index for this device may be divided
|
|
|
491 |
* into individual fields for each component. This is almost always
|
|
|
492 |
* the case for printers, and is the case for most modern displays
|
|
|
493 |
* as well. When this is the case, halftoning may be performed
|
|
|
494 |
* separately for each component, which greatly simplifies processing
|
|
|
495 |
* when the number of color components is large.
|
|
|
496 |
*
|
|
|
497 |
* If the gx_color_index is separable in this manner, the comp_shift
|
|
|
498 |
* array provides the location of the low-order bit for each
|
|
|
499 |
* component. This may be filled in by the client, but need not be.
|
|
|
500 |
* If it is not provided, it will be calculated based on the values
|
|
|
501 |
* in the max_gray and max_color fields as follows:
|
|
|
502 |
*
|
|
|
503 |
* comp_shift[num_components - 1] = 0,
|
|
|
504 |
* comp_shift[i] = comp_shift[i + 1]
|
|
|
505 |
* + ( i == gray_index ? ceil(log2(max_gray + 1))
|
|
|
506 |
* : ceil(log2(max_color + 1)) )
|
|
|
507 |
*
|
|
|
508 |
* The comp_mask and comp_bits fields should be left empty by the client.
|
|
|
509 |
* They will be filled in during initialization using the following
|
|
|
510 |
* mechanism:
|
|
|
511 |
*
|
|
|
512 |
* comp_bits[i] = ( i == gray_index ? ceil(log2(max_gray + 1))
|
|
|
513 |
* : ceil(log2(max_color + 1)) )
|
|
|
514 |
*
|
|
|
515 |
* comp_mask[i] = (((gx_color_index)1 << comp_bits[i]) - 1)
|
|
|
516 |
* << comp_shift[i]
|
|
|
517 |
*
|
|
|
518 |
* (For current devices, it is almost always the case that
|
|
|
519 |
* max_gray == max_color, if the color model contains both gray and
|
|
|
520 |
* non-gray components.)
|
|
|
521 |
*
|
|
|
522 |
* If separable_and_linear is not set, the data in the other fields
|
|
|
523 |
* is unpredictable and should be ignored.
|
|
|
524 |
*/
|
|
|
525 |
gx_color_enc_sep_lin_t separable_and_linear;
|
|
|
526 |
byte comp_shift[GX_DEVICE_COLOR_MAX_COMPONENTS];
|
|
|
527 |
byte comp_bits[GX_DEVICE_COLOR_MAX_COMPONENTS];
|
|
|
528 |
gx_color_index comp_mask[GX_DEVICE_COLOR_MAX_COMPONENTS];
|
|
|
529 |
/*
|
|
|
530 |
* Pointer to name for the process color model.
|
|
|
531 |
*/
|
|
|
532 |
const char * cm_name;
|
|
|
533 |
|
|
|
534 |
} gx_device_color_info;
|
|
|
535 |
</pre>
|
|
|
536 |
</blockquote>
|
|
|
537 |
|
|
|
538 |
<p>
|
|
|
539 |
Note: See <a href="#Changing_color_info_data">Changing color_info data</a> before changing
|
|
|
540 |
any information in the <b><tt>color_info structure</tt></b> for a device.
|
|
|
541 |
|
|
|
542 |
<p>
|
|
|
543 |
It is recommended that the values for this structure be defined using one
|
|
|
544 |
of the standard macros provided for this purpose. This allows for future
|
|
|
545 |
changes to be made to the structure without changes being required in the
|
|
|
546 |
actual device code.
|
|
|
547 |
|
|
|
548 |
<p>
|
|
|
549 |
The following macros (in <a href="../src/gxdevcli.h">gxdevcli.h</a>) provide
|
|
|
550 |
convenient shorthands for initializing this structure for ordinary
|
|
|
551 |
black-and-white or color devices:
|
|
|
552 |
|
|
|
553 |
<blockquote>
|
|
|
554 |
<b><tt>#define dci_black_and_white</tt></b> ...<br>
|
|
|
555 |
<b><tt>#define dci_color(depth,maxv,dither)</tt></b> ...
|
|
|
556 |
</blockquote>
|
|
|
557 |
|
|
|
558 |
<p>
|
|
|
559 |
The <b><tt>#define dci_black_and_white</tt></b> macro defines a
|
|
|
560 |
single bit monochrome device (For example: a typical monochrome printer device.)
|
|
|
561 |
|
|
|
562 |
<p>
|
|
|
563 |
The <b><tt>#define dci_color(depth,maxv,dither)</tt></b> macro can be used
|
|
|
564 |
to define a 24 bit RGB device or a 4 or 32 bit CMYK device.
|
|
|
565 |
|
|
|
566 |
<p>
|
|
|
567 |
The <b><tt>#define dci_extended_alpha_values</tt></b> macro (in
|
|
|
568 |
<a href="../src/gxdevcli.h">gxdevcli.h</a>)
|
|
|
569 |
specifies most of the current fields in the structure. However this macro allows
|
|
|
570 |
only the default setting for the comp_shift, comp_bits, and comp_mask fields
|
|
|
571 |
to be set. Any device which requires a non-default setting for these fields
|
|
|
572 |
has to correctly these fields during the device open procedure.
|
|
|
573 |
See
|
|
|
574 |
<a href="#sep_and_linear_fields">Separable and linear fields></a> and
|
|
|
575 |
<a href="#Changing_color_info_data">Changing color_info data</a>.
|
|
|
576 |
|
|
|
577 |
<p>
|
|
|
578 |
The idea is that a device has a certain number of gray levels
|
|
|
579 |
(<b><tt>max_gray</tt></b>+1) and a certain number of colors
|
|
|
580 |
(<b><tt>max_rgb</tt></b>+1) that it can produce directly. When Ghostscript
|
|
|
581 |
wants to render a given color space color value as a device color, it first tests
|
|
|
582 |
whether the color is a gray level and if so:
|
|
|
583 |
|
|
|
584 |
<blockquote>
|
|
|
585 |
If <b><tt>max_gray</tt></b> is large (>= 31), Ghostscript asks the
|
|
|
586 |
device to approximate the gray level directly. If the device returns a
|
|
|
587 |
valid <b><tt>gx_color_index</tt></b>, Ghostscript uses it. Otherwise,
|
|
|
588 |
Ghostscript assumes that the device can represent
|
|
|
589 |
<b><tt>dither_gray</tt></b> distinct gray levels, equally spaced along the
|
|
|
590 |
diagonal of the color cube, and uses the two nearest ones to the desired
|
|
|
591 |
color for halftoning.
|
|
|
592 |
</blockquote>
|
|
|
593 |
|
|
|
594 |
<p>
|
|
|
595 |
If the color is not a gray level:
|
|
|
596 |
|
|
|
597 |
<blockquote>
|
|
|
598 |
If <b><tt>max_rgb</tt></b> is large (>= 31), Ghostscript asks the device
|
|
|
599 |
to approximate the color directly. If the device returns a valid
|
|
|
600 |
<b><tt>gx_color_index</tt></b>, Ghostscript uses it. Otherwise,
|
|
|
601 |
Ghostscript assumes that the device can represent
|
|
|
602 |
|
|
|
603 |
<blockquote>
|
|
|
604 |
<b><tt>dither_rgb</tt></b> × <b><tt>dither_rgb</tt></b> × <b><tt>dither_rgb</tt></b>
|
|
|
605 |
</blockquote>
|
|
|
606 |
|
|
|
607 |
<p>
|
|
|
608 |
distinct colors, equally spaced throughout the color cube, and uses two of
|
|
|
609 |
the nearest ones to the desired color for halftoning.
|
|
|
610 |
</blockquote>
|
|
|
611 |
|
|
|
612 |
<h4><a name="sep_and_linear_fields"></a>Separable and linear fields</h4>
|
|
|
613 |
<p>
|
|
|
614 |
The three fields <b><tt>comp_shift</tt></b>, <b><tt>comp_bits</tt></b>, and
|
|
|
615 |
<b><tt>comp_mask</tt></b> are only used if the <b><tt>separable_and_linear</tt></b>
|
|
|
616 |
field is set to <b><tt>GX_CINFO_SEP_LIN</tt></b>. In this situation a <b><tt>gx_color_index</tt></b>
|
|
|
617 |
value must represent a combination created by or'ing bits for each of the devices's
|
|
|
618 |
output colorants. The <b><tt>comp_shift</tt></b> array defines the location
|
|
|
619 |
(shift count) of each colorants bits in the output gx_color_index value. The
|
|
|
620 |
<b><tt>comp_bits</tt></b> array defines the number of bits for each colorant.
|
|
|
621 |
The <b><tt>comp_mask</tt></b> array contains a mask which can be used to isolate
|
|
|
622 |
the bits for each colorant. These fields must be set if the device supports
|
|
|
623 |
more than four colorants.
|
|
|
624 |
|
|
|
625 |
<h4><a name="Changing_color_info_data"></a>Changing color_info data</h4>
|
|
|
626 |
|
|
|
627 |
<p> For most devices, the information in the device's <tt><b>color_info</b></tt>
|
|
|
628 |
structure is defined by the various device definition macros and the data remains
|
|
|
629 |
constant during the entire existence of the device. In general the Ghostscript
|
|
|
630 |
graphics assumes that the information is constant. However some devices want
|
|
|
631 |
to modify the data in this structure.
|
|
|
632 |
|
|
|
633 |
<p>
|
|
|
634 |
The device's <b><tt>put_params</tt></b> procedure may change
|
|
|
635 |
<b><tt>color_info</tt></b> field values.
|
|
|
636 |
After the data has been modified then the
|
|
|
637 |
device should be closed (via a call to <tt><b>gs_closedevice</b></tt>). Closing
|
|
|
638 |
the device will erase the current page so these changes should only be made
|
|
|
639 |
before anything has been drawn on a page.
|
|
|
640 |
|
|
|
641 |
<p> The device's <tt><b>open_device</b></tt> procedure may change
|
|
|
642 |
<b><tt>color_info</tt></b> field values. These changes should be done before
|
|
|
643 |
calling any other procedures are called.
|
|
|
644 |
|
|
|
645 |
<p>
|
|
|
646 |
The Ghostscript graphics library
|
|
|
647 |
uses some of the data in <b><tt>color_info</tt></b> to set the default
|
|
|
648 |
procedures for the
|
|
|
649 |
<b><tt>get_color_mapping_procs</tt></b>,
|
|
|
650 |
<b><tt>get_color_comp_index</tt></b>,
|
|
|
651 |
<b><tt>encode_color</tt></b>, and
|
|
|
652 |
<b><tt>decode_color</tt></b> procedures.
|
|
|
653 |
These default procedures are set when the
|
|
|
654 |
device is originally created. If any changes are made to the
|
|
|
655 |
<b><tt>color_info</tt></b> fields then the device's <b><tt>open_device</tt></b>
|
|
|
656 |
procedure
|
|
|
657 |
has responsibility for insuring that the correct procedures are contained
|
|
|
658 |
in the device structure. (For an example, see the display device open procedure
|
|
|
659 |
<b><tt>display_open</tt></b> and its subroutine <b><tt>display_set_color_format
|
|
|
660 |
</tt></b> (in <a href="../src/gdevdisp.c">gdevdisp</a>).
|
|
|
661 |
|
|
|
662 |
|
|
|
663 |
<h3><a name="Types"></a>Types</h3>
|
|
|
664 |
|
|
|
665 |
<p>
|
|
|
666 |
Here is a brief explanation of the various types that appear as parameters
|
|
|
667 |
or results of the drivers.
|
|
|
668 |
|
|
|
669 |
<dl>
|
|
|
670 |
<dt><b><tt>frac</tt></b> (defined in <a href="../src/gxfrac.h">gxfrac.h</a>)
|
|
|
671 |
<dd>This is the type used to represent color values for the input to the
|
|
|
672 |
color model mapping procedures. It is currently defined as a short. It has a
|
|
|
673 |
range of <b><tt>frac_0</tt></b> to <b><tt>frac_1</tt></b>.
|
|
|
674 |
</dl>
|
|
|
675 |
|
|
|
676 |
<dl>
|
|
|
677 |
<dt><b><tt>gx_color_value</tt></b> (defined in
|
|
|
678 |
<a href="../src/gxdevice.h">gxdevice.h</a>)
|
|
|
679 |
<dd>This is the type used to represent RGB or CMYK color values. It is
|
|
|
680 |
currently equivalent to unsigned short. However, Ghostscript may use less
|
|
|
681 |
than the full range of the type to represent color values:
|
|
|
682 |
<b><tt>gx_color_value_bits</tt></b> is the number of bits actually used,
|
|
|
683 |
and <b><tt>gx_max_color_value</tt></b> is the maximum value, equal to
|
|
|
684 |
(2^<small><sup><b><tt>gx_max_color_value_bits</tt></b></sup></small>)-1.
|
|
|
685 |
</dl>
|
|
|
686 |
|
|
|
687 |
<dl>
|
|
|
688 |
<dt><b><tt>gx_device</tt></b> (defined in
|
|
|
689 |
<a href="../src/gxdevice.h">gxdevice.h</a>)
|
|
|
690 |
<dd>This is the device structure, as explained above.
|
|
|
691 |
</dl>
|
|
|
692 |
|
|
|
693 |
<dl>
|
|
|
694 |
<dt><b><tt>gs_matrix</tt></b> (defined in
|
|
|
695 |
<a href="../src/gsmatrix.h">gsmatrix.h</a>)
|
|
|
696 |
<dd>This is a 2-D homogeneous coordinate transformation matrix, used by
|
|
|
697 |
many Ghostscript operators.
|
|
|
698 |
</dl>
|
|
|
699 |
|
|
|
700 |
<dl>
|
|
|
701 |
<dt><b><tt>gx_color_index</tt></b> (defined in
|
|
|
702 |
<a href="../src/gxcindex.h">gxcindex.h</a>)
|
|
|
703 |
<dd>This is meant to be whatever the driver uses to represent a device
|
|
|
704 |
color. For example, it might be an index in a color map, or it might be R,
|
|
|
705 |
G, and B values packed into a single integer. The Ghostscript graphics library
|
|
|
706 |
gets <b><tt>gx_color_index</tt></b> values from the device's
|
|
|
707 |
<b><tt>encode_color</tt></b> and hands them back as arguments to several other
|
|
|
708 |
procedures. If the <b><tt>separable_and_linear</tt></b> field in the device's
|
|
|
709 |
<b><tt>color_info</tt></b> structure is not set to
|
|
|
710 |
<b><tt>GX_CINFO_SEP_LIN</tt></b> then Ghostscript does not do
|
|
|
711 |
any computations with <b><tt>gx_color_index</tt></b> values.
|
|
|
712 |
|
|
|
713 |
<p>
|
|
|
714 |
The special
|
|
|
715 |
value <b><tt>gx_no_color_index</tt></b> (defined as
|
|
|
716 |
<b><tt>(~(gx_color_index)(0))</tt></b> ) means "transparent" for some of
|
|
|
717 |
the procedures.
|
|
|
718 |
|
|
|
719 |
<p>
|
|
|
720 |
The size of <b><tt>gx_color_index</tt></b> can be either 32 or 64 bits. The
|
|
|
721 |
choice depends upon the architecture of the CPU and the compiler. The default
|
|
|
722 |
type definition is simply:
|
|
|
723 |
|
|
|
724 |
<blockquote><b><tt>
|
|
|
725 |
typedef unsigned long gx_color_index;
|
|
|
726 |
</tt></b></blockquote>
|
|
|
727 |
|
|
|
728 |
However if <b><tt>GX_COLOR_INDEX_TYPE</tt></b> is defined, then it is used
|
|
|
729 |
as the type for <b><tt>gx_color_index</tt></b>.
|
|
|
730 |
|
|
|
731 |
<blockquote><b><tt>
|
|
|
732 |
typedef GX_COLOR_INDEX_TYPE gx_color_index;
|
|
|
733 |
</tt></b></blockquote>
|
|
|
734 |
|
|
|
735 |
The smaller size (32 bits) may produce more efficient or faster executing
|
|
|
736 |
code. The larger size (64 bits) is needed for representing either more
|
|
|
737 |
bits per component or more components. An example of the later case is
|
|
|
738 |
a device that supports 8 bit contone colorants using a DeviceCMYK process
|
|
|
739 |
color model with its four colorants and also supports additional spot
|
|
|
740 |
colorants.
|
|
|
741 |
|
|
|
742 |
<p>
|
|
|
743 |
Currently autoconf attempts to find a 64 bit type definition for the
|
|
|
744 |
compiler being used, and if a 64 bit type is found then
|
|
|
745 |
<b><tt>GX_COLOR_INDEX_TYPE</tt></b> is set to the type.
|
|
|
746 |
|
|
|
747 |
<p>
|
|
|
748 |
For Microsoft and the MSVC compiler, <b><tt>GX_COLOR_INDEX_TYPE</tt></b> will
|
|
|
749 |
be set to <b><tt>unsigned _int64</tt></b> if <b><tt>USE_LARGE_COLOR_INDEX</tt></b>
|
|
|
750 |
is set to 1 either on the make command line or by editing the definition
|
|
|
751 |
in <a href="../src/msvc32.mak">msvc32.mak</a>
|
|
|
752 |
</dl>
|
|
|
753 |
|
|
|
754 |
<dl>
|
|
|
755 |
<dt><b><tt>gs_param_list</tt></b> (defined in <a
|
|
|
756 |
href="../src/gsparam.h">gsparam.h</a>)
|
|
|
757 |
<dd>This is a parameter list, which is used to read and set attributes in a
|
|
|
758 |
device. See the comments in <a href="../src/gsparam.h">gsparam.h</a>, and
|
|
|
759 |
the <a href="#Parameters">description of the <b><tt>get_params</tt></b> and
|
|
|
760 |
<b><tt>put_params</tt></b> procedures</a> below, for more detail.
|
|
|
761 |
</dl>
|
|
|
762 |
|
|
|
763 |
<dl>
|
|
|
764 |
<dt><b><tt>gx_tile_bitmap</tt></b> (defined in
|
|
|
765 |
<a href="../src/gxbitmap.h">gxbitmap.h</a>)
|
|
|
766 |
<br><b><tt>gx_strip_bitmap</tt></b> (defined in
|
|
|
767 |
<a href="../src/gxbitmap.h">gxbitmap.h</a>)
|
|
|
768 |
<dd>These structure types represent bitmaps to be used as a tile for
|
|
|
769 |
filling a region (rectangle). <b><tt>gx_tile_bitmap</tt></b> is an older
|
|
|
770 |
type lacking <b><tt>shift</tt></b> and <b><tt>rep_shift</tt></b>;
|
|
|
771 |
<b><tt>gx_strip_bitmap</tt></b> has superseded it, and it should not be
|
|
|
772 |
used in new code. Here is a copy of the relevant part of the file:
|
|
|
773 |
|
|
|
774 |
<blockquote>
|
|
|
775 |
<pre>
|
|
|
776 |
/*
|
|
|
777 |
* Structure for describing stored bitmaps.
|
|
|
778 |
* Bitmaps are stored bit-big-endian (i.e., the 2^7 bit of the first
|
|
|
779 |
* byte corresponds to x=0), as a sequence of bytes (i.e., you can't
|
|
|
780 |
* do word-oriented operations on them if you're on a little-endian
|
|
|
781 |
* platform like the Intel 80x86 or VAX). Each scan line must start on
|
|
|
782 |
* a (32-bit) word boundary, and hence is padded to a word boundary,
|
|
|
783 |
* although this should rarely be of concern, since the raster and width
|
|
|
784 |
* are specified individually. The first scan line corresponds to y=0
|
|
|
785 |
* in whatever coordinate system is relevant.
|
|
|
786 |
*
|
|
|
787 |
* For bitmaps used as halftone tiles, we may replicate the tile in
|
|
|
788 |
* X and/or Y, but it is still valuable to know the true tile dimensions
|
|
|
789 |
* (i.e., the dimensions prior to replication). Requirements:
|
|
|
790 |
* width % rep_width = 0
|
|
|
791 |
* height % rep_height = 0
|
|
|
792 |
*
|
|
|
793 |
* For halftones at arbitrary angles, we provide for storing the halftone
|
|
|
794 |
* data as a strip that must be shifted in X for different values of Y.
|
|
|
795 |
* For an ordinary (non-shifted) halftone that has a repetition width of
|
|
|
796 |
* W and a repetition height of H, the pixel at coordinate (X,Y)
|
|
|
797 |
* corresponds to halftone pixel (X mod W, Y mod H), ignoring phase;
|
|
|
798 |
* for a shifted halftone with shift S, the pixel at (X,Y) corresponds
|
|
|
799 |
* to halftone pixel ((X + S * floor(Y/H)) mod W, Y mod H). Requirements:
|
|
|
800 |
* strip_shift < rep_width
|
|
|
801 |
* strip_height % rep_height = 0
|
|
|
802 |
* shift = (strip_shift * (size.y / strip_height)) % rep_width
|
|
|
803 |
*/
|
|
|
804 |
typedef struct gx_strip_bitmap_s {
|
|
|
805 |
byte *data;
|
|
|
806 |
int raster; /* bytes per scan line */
|
|
|
807 |
gs_int_point size; /* width, height */
|
|
|
808 |
gx_bitmap_id id;
|
|
|
809 |
ushort rep_width, rep_height; /* true size of tile */
|
|
|
810 |
ushort strip_height;
|
|
|
811 |
ushort strip_shift;
|
|
|
812 |
ushort shift;
|
|
|
813 |
} gx_strip_bitmap;</pre>
|
|
|
814 |
</blockquote>
|
|
|
815 |
</dl>
|
|
|
816 |
|
|
|
817 |
<hr>
|
|
|
818 |
|
|
|
819 |
<h2><a name="Coding_conventions"></a>Coding conventions</h2>
|
|
|
820 |
|
|
|
821 |
<p>
|
|
|
822 |
All the driver procedures defined below that return <b><tt>int</tt></b>
|
|
|
823 |
results return 0 on success, or an appropriate negative error code in the
|
|
|
824 |
case of error conditions. The error codes are defined in <a
|
|
|
825 |
href="../src/gserrors.h">gserrors.h</a>; they correspond directly to the
|
|
|
826 |
errors defined in the PostScript language reference manuals. The most
|
|
|
827 |
common ones for drivers are:
|
|
|
828 |
|
|
|
829 |
<blockquote><dl>
|
|
|
830 |
<dt><b><tt>gs_error_invalidfileaccess</tt></b>
|
|
|
831 |
<dd>An attempt to open a file failed.
|
|
|
832 |
|
|
|
833 |
<dt><b><tt>gs_error_ioerror</tt></b>
|
|
|
834 |
<dd>An error occurred in reading or writing a file.
|
|
|
835 |
|
|
|
836 |
<dt><b><tt>gs_error_limitcheck</tt></b>
|
|
|
837 |
<dd>An otherwise valid parameter value was too large for the
|
|
|
838 |
implementation.
|
|
|
839 |
|
|
|
840 |
<dt><b><tt>gs_error_rangecheck</tt></b>
|
|
|
841 |
<dd>A parameter was outside the valid range.
|
|
|
842 |
|
|
|
843 |
<dt><b><tt>gs_error_VMerror</tt></b>
|
|
|
844 |
<dd>An attempt to allocate memory failed. (If this happens, the procedure
|
|
|
845 |
should release all memory it allocated before it returns.)
|
|
|
846 |
</dl></blockquote>
|
|
|
847 |
|
|
|
848 |
<p>
|
|
|
849 |
If a driver does return an error, rather than a simple return statement it
|
|
|
850 |
should use the <b><tt>return_error</tt></b> macro defined in <a
|
|
|
851 |
href="../src/gx.h">gx.h</a>, which is automatically included by <a
|
|
|
852 |
href="../src/gdevprn.h">gdevprn.h</a> but not by <a
|
|
|
853 |
href="../src/gserrors.h">gserrors.h</a>. For example
|
|
|
854 |
|
|
|
855 |
<blockquote>
|
|
|
856 |
<b><tt> return_error(gs_error_VMerror);
|
|
|
857 |
</tt></b></blockquote>
|
|
|
858 |
|
|
|
859 |
<h3><a name="Allocating_storage"></a>Allocating storage</h3>
|
|
|
860 |
|
|
|
861 |
<p>
|
|
|
862 |
While most drivers (especially printer drivers) follow a very similar
|
|
|
863 |
template, there is one important coding convention that is not obvious from
|
|
|
864 |
reading the code for existing drivers: driver procedures must not use
|
|
|
865 |
<b><tt>malloc</tt></b> to allocate any storage that stays around after the
|
|
|
866 |
procedure returns. Instead, they must use <b><tt>gs_malloc</tt></b> and
|
|
|
867 |
<b><tt>gs_free</tt></b>, which have slightly different calling conventions.
|
|
|
868 |
(The prototypes for these are in <a href="../src/gsmemory.h">gsmemory.h</a>,
|
|
|
869 |
which is included in <a href="../src/gx.h">gx.h</a>, which is included in <a
|
|
|
870 |
href="../src/gdevprn.h">gdevprn.h</a>.) This is necessary so that
|
|
|
871 |
Ghostscript can clean up all allocated memory before exiting, which is
|
|
|
872 |
essential in environments that provide only single-address-space
|
|
|
873 |
multi-tasking (some versions of Microsoft Windows).
|
|
|
874 |
|
|
|
875 |
<blockquote>
|
|
|
876 |
<pre>char *gs_malloc(uint num_elements, uint element_size,
|
|
|
877 |
const char *client_name);</pre>
|
|
|
878 |
</blockquote>
|
|
|
879 |
|
|
|
880 |
<p>
|
|
|
881 |
Like <b><tt>calloc</tt></b>, but unlike <b><tt>malloc</tt></b>,
|
|
|
882 |
<b><tt>gs_malloc</tt></b> takes an element count and an element size. For
|
|
|
883 |
structures, <b><tt>num_elements</tt></b> is 1 andi
|
|
|
884 |
<b><tt>element_size</tt></b> is <b><tt>sizeof</tt></b> the structure; for
|
|
|
885 |
byte arrays, <b><tt>num_elements</tt></b> is the number of bytes and
|
|
|
886 |
<b><tt>element_size</tt></b> is 1. Unlike <b><tt>calloc</tt></b>,
|
|
|
887 |
<b><tt>gs_malloc</tt></b> does <b>not</b> clear the block of storage.
|
|
|
888 |
|
|
|
889 |
<p>
|
|
|
890 |
The <b><tt>client_name</tt></b> is used for tracing and debugging. It must
|
|
|
891 |
be a real string, not <b><tt>NULL</tt></b>. Normally it is the name of the
|
|
|
892 |
procedure in which the call occurs.
|
|
|
893 |
|
|
|
894 |
<blockquote>
|
|
|
895 |
<pre>void gs_free(char *data, uint num_elements, uint element_size,
|
|
|
896 |
const char *client_name);</pre>
|
|
|
897 |
</blockquote>
|
|
|
898 |
|
|
|
899 |
<p>
|
|
|
900 |
Unlike <b><tt>free</tt></b>, <b><tt>gs_free</tt></b> demands that
|
|
|
901 |
<b><tt>num_elements</tt></b> and element_size be supplied. It also
|
|
|
902 |
requires a client name, like <b><tt>gs_malloc</tt></b>.
|
|
|
903 |
|
|
|
904 |
<h3><a name="Driver_instance_allocation"></a>Driver instance allocation</h3>
|
|
|
905 |
|
|
|
906 |
<p>i
|
|
|
907 |
All driver instances allocated by Ghostscript's standard allocator must
|
|
|
908 |
point to a "structure descriptor" that tells the garbage collector how to
|
|
|
909 |
trace pointers in the structure. For drivers registered in the normal way
|
|
|
910 |
(using the makefile approach described above), no special care is needed as
|
|
|
911 |
long as instances are created only by calling the
|
|
|
912 |
<b><tt>gs_copydevice</tt></b> procedure defined in <a
|
|
|
913 |
href="../src/gsdevice.h">gsdevice.h</a>. If you have a need to define
|
|
|
914 |
devices that are not registered in this way, you must fill in the stype
|
|
|
915 |
member in any dynamically allocated instances with a pointer to the same
|
|
|
916 |
structure descriptor used to allocate the instance. For more information
|
|
|
917 |
about structure descriptors, see <a href="../src/gsmemory.h">gsmemory.h</a>
|
|
|
918 |
and <a href="../src/gsstruct.h">gsstruct.h</a>.
|
|
|
919 |
|
|
|
920 |
<hr>
|
|
|
921 |
|
|
|
922 |
<h2><a name="Printer_drivers"></a>Printer drivers</h2>
|
|
|
923 |
|
|
|
924 |
<p>
|
|
|
925 |
Printer drivers (which include drivers that write some kind of raster file)
|
|
|
926 |
are especially simple to implement.
|
|
|
927 |
The printer driver must implement a <b><tt>print_page</tt></b> or
|
|
|
928 |
<b><tt>print_page_copies</tt></b> procedure. There are macros in <a
|
|
|
929 |
href="../src/gdevprn.h">gdevprn.h</a> that generate the device structure for
|
|
|
930 |
such devices, of which the simplest is <b><tt>prn_device</tt></b>; for an
|
|
|
931 |
example, see <a href="../src/gdevbj10.c">gdevbj10.c</a>. If you are writing
|
|
|
932 |
a printer driver, we suggest you start by reading <a
|
|
|
933 |
href="../src/gdevprn.h">gdevprn.h</a> and the <a
|
|
|
934 |
href="#Color_mapping">subsection on "Color mapping"</a> below; you may be
|
|
|
935 |
able to ignore all the rest of the driver procedures.
|
|
|
936 |
|
|
|
937 |
<p>
|
|
|
938 |
The <b><tt>print_page</tt></b> procedures are defined as follows:
|
|
|
939 |
|
|
|
940 |
<blockquote>
|
|
|
941 |
<pre>int (*print_page)(gx_device_printer *, FILE *)
|
|
|
942 |
int (*print_page_copies)(gx_device_printer *, FILE *, int)</pre>
|
|
|
943 |
</blockquote>
|
|
|
944 |
|
|
|
945 |
<p>
|
|
|
946 |
This procedure must read out the rendered image from the device and write
|
|
|
947 |
whatever is appropriate to the file. To read back one or more scan lines
|
|
|
948 |
of the image, the <b><tt>print_page</tt></b> procedure must call one of the
|
|
|
949 |
following procedures:
|
|
|
950 |
|
|
|
951 |
<blockquote>
|
|
|
952 |
<pre>int gdev_prn_copy_scan_lines(gx_device_printer *pdev, int y, byte *str,
|
|
|
953 |
uint size)</pre>
|
|
|
954 |
</blockquote>
|
|
|
955 |
|
|
|
956 |
<p>
|
|
|
957 |
For this procedure, <b><tt>str</tt></b> is where the data should be copied to, and <b><tt>size</tt></b> is
|
|
|
958 |
the size of the buffer starting at <b><tt>str</tt></b>. This procedure returns the number
|
|
|
959 |
of scan lines copied, or <0 for an error. <b><tt>str</tt></b> need not be aligned.
|
|
|
960 |
|
|
|
961 |
<blockquote>
|
|
|
962 |
<pre>int gdev_prn_get_bits(gx_device_printer *pdev, int y, byte *str,
|
|
|
963 |
byte **actual_data)</pre>
|
|
|
964 |
</blockquote>
|
|
|
965 |
|
|
|
966 |
<p>
|
|
|
967 |
This procedure reads out exactly one scan line. If the scan line is
|
|
|
968 |
available in the correct format already, <b><tt>*actual_data</tt></b> is
|
|
|
969 |
set to point to it; otherwise, the scan line is copied to the buffer
|
|
|
970 |
starting at <b><tt>str</tt></b>, and <b><tt>*actual_data</tt></b> is set to
|
|
|
971 |
<b><tt>str</tt></b>. This saves a copying step most of the time.
|
|
|
972 |
<b><tt>str</tt></b> need not be aligned; however, if
|
|
|
973 |
<b><tt>*actual_data</tt></b> is set to point to an existing scan line, it
|
|
|
974 |
will be aligned. (See the description of the <b><tt>get_bits</tt></b>
|
|
|
975 |
procedure below for more details.)
|
|
|
976 |
|
|
|
977 |
<p>
|
|
|
978 |
In either case, each row of the image is stored in the form described in
|
|
|
979 |
the comment under <b><tt>gx_tile_bitmap</tt></b> above; each pixel takes
|
|
|
980 |
the number of bits specified as <b><tt>color_info.depth</tt></b> in the
|
|
|
981 |
device structure, and holds values returned by the device's
|
|
|
982 |
<b><tt>encode_color</tt></b> procedure.
|
|
|
983 |
|
|
|
984 |
<p>
|
|
|
985 |
The <b><tt>print_page</tt></b> procedure can determine the number of bytes
|
|
|
986 |
required to hold a scan line by calling:
|
|
|
987 |
|
|
|
988 |
<blockquote>
|
|
|
989 |
<pre>uint gdev_prn_raster(gx_device_printer *)</pre>
|
|
|
990 |
</blockquote>
|
|
|
991 |
|
|
|
992 |
<p>
|
|
|
993 |
For a very simple concrete example, we suggest reading the code in
|
|
|
994 |
<b><tt>bit_print_page</tt></b> in <a href="../src/gdevbit.c">gdevbit.c</a>.
|
|
|
995 |
|
|
|
996 |
<p>
|
|
|
997 |
If the device provides <b><tt>print_page</tt></b>, Ghostscript will call
|
|
|
998 |
<b><tt>print_page</tt></b> the requisite number of times to print the
|
|
|
999 |
desired number of copies; if the device provides
|
|
|
1000 |
<b><tt>print_page_copies</tt></b>, Ghostscript will call
|
|
|
1001 |
<b><tt>print_page_copies</tt></b> once per page, passing it the desired
|
|
|
1002 |
number of copies.
|
|
|
1003 |
|
|
|
1004 |
<hr>
|
|
|
1005 |
|
|
|
1006 |
<h2><a name="Driver_procedures"></a>Driver procedures</h2>
|
|
|
1007 |
|
|
|
1008 |
<p>
|
|
|
1009 |
Most of the procedures that a driver may implement are optional. If a
|
|
|
1010 |
device doesn't supply an optional procedure <b><tt>WXYZ</tt></b>, the entry
|
|
|
1011 |
in the procedure structure may be either <b><tt>gx_default_WXYZ</tt></b>,
|
|
|
1012 |
for instance <b><tt>gx_default_tile_rectangle</tt></b>, or
|
|
|
1013 |
<b><tt>NULL</tt></b> or 0. (The device procedure must also call the
|
|
|
1014 |
<b><tt>gx_default_</tt></b> procedure if it doesn't implement the function
|
|
|
1015 |
for particular values of the arguments.) Since C compilers supply 0 as the
|
|
|
1016 |
value for omitted structure elements, this convention means that statically
|
|
|
1017 |
initialized procedure structures continue to work even if new (optional)
|
|
|
1018 |
members are added.
|
|
|
1019 |
|
|
|
1020 |
<h3><a name="Life_cycle"></a>Life cycle</h3>
|
|
|
1021 |
|
|
|
1022 |
<p>
|
|
|
1023 |
A device instance begins life in a closed state. In this state, no output
|
|
|
1024 |
operations will occur. Only the following procedures may be called:
|
|
|
1025 |
|
|
|
1026 |
<blockquote><b><tt>
|
|
|
1027 |
open_device<br>
|
|
|
1028 |
finish_copydevice<br>
|
|
|
1029 |
get_initial_matrix<br>
|
|
|
1030 |
get_params<br>
|
|
|
1031 |
put_params<br>
|
|
|
1032 |
get_hardware_params
|
|
|
1033 |
</tt></b></blockquote>
|
|
|
1034 |
|
|
|
1035 |
<p>
|
|
|
1036 |
When <b><tt>setdevice</tt></b> installs a device instance in the graphics
|
|
|
1037 |
state, it checks whether the instance is closed or open. If the instance
|
|
|
1038 |
is closed, <b><tt>setdevice</tt></b> calls the open routine, and then sets
|
|
|
1039 |
the state to open.
|
|
|
1040 |
|
|
|
1041 |
<p>
|
|
|
1042 |
There is no user-accessible operation to close a device instance. This is
|
|
|
1043 |
not an oversight -- it is required in order to enforce the following
|
|
|
1044 |
invariant:
|
|
|
1045 |
|
|
|
1046 |
<blockquote>
|
|
|
1047 |
If a device instance is the current device in <em>any</em> graphics state,
|
|
|
1048 |
it must be open (have <b><tt>is_open</tt></b> set to true).
|
|
|
1049 |
</blockquote>
|
|
|
1050 |
|
|
|
1051 |
<p>
|
|
|
1052 |
Device instances are only closed when they are about to
|
|
|
1053 |
be freed, which occurs in three situations:
|
|
|
1054 |
|
|
|
1055 |
<ul>
|
|
|
1056 |
<li>When a <b><tt>restore</tt></b> occurs, if the instance was created since
|
|
|
1057 |
the corresponding <b><tt>save</tt></b> and is in a VM being restored. I.e.,
|
|
|
1058 |
if the instance was created in local VM since a <b><tt>save</tt></b>, it
|
|
|
1059 |
will always be closed and freed by the corresponding
|
|
|
1060 |
<b><tt>restore</tt></b>; if it was created in global VM, it will only be
|
|
|
1061 |
closed by the outermost <b><tt>restore</tt></b>, regardless of the save
|
|
|
1062 |
level at the time the instance was created.
|
|
|
1063 |
|
|
|
1064 |
<li>By the garbage collector, if the instance is no longer accessible.
|
|
|
1065 |
|
|
|
1066 |
<li>When Ghostscript exits (terminates).
|
|
|
1067 |
</ul>
|
|
|
1068 |
|
|
|
1069 |
<h3><a name="Open_close"></a>Open, close, sync, copy</h3>
|
|
|
1070 |
|
|
|
1071 |
<dl>
|
|
|
1072 |
<dt><b><tt>int (*open_device)(gx_device *)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1073 |
<dd>Open the device: do any initialization associated with making the device
|
|
|
1074 |
instance valid. This must be done before any output to the device. The
|
|
|
1075 |
default implementation does nothing. <b>NOTE</b>: Clients should never call
|
|
|
1076 |
a device's <b><tt>open_device</tt></b> procedure directly: they should
|
|
|
1077 |
always call <b><tt>gs_opendevice</tt></b> instead.
|
|
|
1078 |
</dl>
|
|
|
1079 |
|
|
|
1080 |
<dl>
|
|
|
1081 |
<dt><b><tt>int (*finish_copydevice)(gx_device *dev, const gx_device
|
|
|
1082 |
*from_dev)</tt></b> <b><em>[OPTIONAL]</em></b> <dd>Perform any cleanup
|
|
|
1083 |
required after <b><tt>copydevice</tt></b> has created a new device instance
|
|
|
1084 |
by copying <b><tt>from_dev</tt></b>. If the copy operation should not be
|
|
|
1085 |
allowed, this procedure should return an error; the copy will be freed. The
|
|
|
1086 |
default implementation allows copying the device prototype, but does not
|
|
|
1087 |
allow copying device instances, because instances may contain internal
|
|
|
1088 |
pointers that should not be shared between copies, and there is no way to
|
|
|
1089 |
determine this from outside the device. <b>NOTE</b>: Clients should never
|
|
|
1090 |
call a device's <b><tt>finish_copydevice</tt></b> procedure: this procedure
|
|
|
1091 |
is only intended for use by <b><tt>gs_copydevice[2]</tt></b>.
|
|
|
1092 |
</dl>
|
|
|
1093 |
|
|
|
1094 |
<dl>
|
|
|
1095 |
<dt><b><tt>void (*get_initial_matrix)(gx_device *, gs_matrix *)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1096 |
<dd>Construct the initial transformation matrix mapping user coordinates
|
|
|
1097 |
(nominally 1/72 inch per unit) to device coordinates. The default
|
|
|
1098 |
procedure computes this from width, height, and
|
|
|
1099 |
[<b><tt>xy</tt></b>]<b><tt>_pixels_per_inch</tt></b> on the assumption that
|
|
|
1100 |
the origin is in the upper left corner, that is
|
|
|
1101 |
<blockquote>
|
|
|
1102 |
<b><tt>xx</tt></b> = <b><tt>x_pixels_per_inch</tt></b>/72, <b><tt>xy</tt></b> = 0,<br>
|
|
|
1103 |
<b><tt>yx = 0, yy = -y_pixels_per_inch</tt></b>/72,<br>
|
|
|
1104 |
<b><tt>tx = 0, ty = height</tt></b>.
|
|
|
1105 |
</blockquote>
|
|
|
1106 |
</dl>
|
|
|
1107 |
|
|
|
1108 |
<dl>
|
|
|
1109 |
<dt><b><tt>int (*sync_output)(gx_device *)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1110 |
<dd>Synchronize the device. If any output to the device has been
|
|
|
1111 |
buffered, send or write it now. Note that this may be called several times
|
|
|
1112 |
in the process of constructing a page, so printer drivers should <b>not</b>
|
|
|
1113 |
implement this by printing the page. The default implementation does
|
|
|
1114 |
nothing.
|
|
|
1115 |
</dl>
|
|
|
1116 |
|
|
|
1117 |
<dl>
|
|
|
1118 |
<dt><b><tt>int (*output_page)(gx_device *, int num_copies, int flush)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1119 |
<dd>Output a fully composed page to the device. The
|
|
|
1120 |
<b><tt>num_copies</tt></b> argument is the number of copies that should be
|
|
|
1121 |
produced for a hardcopy device. (This may be ignored if the driver has
|
|
|
1122 |
some other way to specify the number of copies.) The <b><tt>flush</tt></b>
|
|
|
1123 |
argument is true for <b><tt>showpage</tt></b>, false for
|
|
|
1124 |
<b><tt>copypage</tt></b>. The default definition just calls
|
|
|
1125 |
<b><tt>sync_output</tt></b>. Printer drivers should implement this by
|
|
|
1126 |
printing and ejecting the page.
|
|
|
1127 |
</dl>
|
|
|
1128 |
|
|
|
1129 |
<dl>
|
|
|
1130 |
<dt><b><tt>int (*close_device)(gx_device *)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1131 |
<dd>Close the device: release any associated resources. After this, output
|
|
|
1132 |
to the device is no longer allowed. The default implementation does
|
|
|
1133 |
nothing. <b>NOTE</b>: Clients should never call a device's
|
|
|
1134 |
<b><tt>close_device</tt></b> procedure directly: they should always call
|
|
|
1135 |
<b><tt>gs_closedevice</tt></b> instead.
|
|
|
1136 |
</dl>
|
|
|
1137 |
<h3><a name="Color_mapping"></a>Color and alpha mapping</h3>
|
|
|
1138 |
|
|
|
1139 |
<p>
|
|
|
1140 |
Note that code in the Ghostscript library may cache the results of calling
|
|
|
1141 |
one or more of the color mapping procedures. If the result returned by any
|
|
|
1142 |
of these procedures would change (other than as a result of a change made by
|
|
|
1143 |
the driver's <b><tt>put_params</tt></b> procedure), the driver must call
|
|
|
1144 |
<b><tt>gx_device_decache_colors(dev)</tt></b>.
|
|
|
1145 |
|
|
|
1146 |
<p>
|
|
|
1147 |
The <b><tt>map_rgb_color</tt></b>, <b><tt>map_color_rgb</tt></b>, and
|
|
|
1148 |
<b><tt>map_cmyk_color</tt></b> are obsolete. They have been left
|
|
|
1149 |
in the device procedure list for backward compatibility. See the
|
|
|
1150 |
<b><tt>encode_color</tt></b> and <b><tt>decode_color</tt></b> procedures
|
|
|
1151 |
below. To insure that older device drivers are changed to use the new
|
|
|
1152 |
<b><tt>encode_color</tt></b> and <b><tt>decode_color</tt></b>
|
|
|
1153 |
procedures,
|
|
|
1154 |
the parameters for the older procedures have been changed to
|
|
|
1155 |
match the new procedures. To minimize changes in devices that have
|
|
|
1156 |
already been written, the map_rgb_color and map_cmyk_color routines
|
|
|
1157 |
are used as the default value for the encode_color routine. The
|
|
|
1158 |
map_cmyk_color routine is used if the number of components is four.
|
|
|
1159 |
The map_rgb_color routine is used if the number of components is one
|
|
|
1160 |
or three. This works okay for RGB and CMYK process color model devices.
|
|
|
1161 |
However this does not work properly for gray devices. The encode_color
|
|
|
1162 |
routine for a gray device is only passed one component. Thus the
|
|
|
1163 |
map_rgb_color routine must be modified to only use a single input (instead
|
|
|
1164 |
of three). (See the encode_color and decode_color routines below.)
|
|
|
1165 |
|
|
|
1166 |
|
|
|
1167 |
<p>
|
|
|
1168 |
Colors can be specified to the Ghostscript graphics library in a variety
|
|
|
1169 |
of forms. For example, there are a wide variety of color spaces that can
|
|
|
1170 |
be used such as Gray, RGB, CMYK, DeviceN, Separation, Indexed, CIEbasedABC,
|
|
|
1171 |
etc. The graphics library converts the various input color space
|
|
|
1172 |
values into four base color spaces: Gray, RGB, CMYK, and DeviceN. The
|
|
|
1173 |
DeviceN color space allows for specifying values for individual device
|
|
|
1174 |
colorants or spot colors.
|
|
|
1175 |
|
|
|
1176 |
<p>
|
|
|
1177 |
Colors are converted by the device in a two step process. The first step
|
|
|
1178 |
is to convert a color in one of the base color spaces (Gray, RGB, CMYK,
|
|
|
1179 |
or DeviceN) into values for each device colorant. This transformation is
|
|
|
1180 |
done via a set of procedures provided by the device. These procedures are
|
|
|
1181 |
provided by the <b><tt>get_color_mapping_procs</tt></b> device procedure.
|
|
|
1182 |
|
|
|
1183 |
<p>
|
|
|
1184 |
Between the first and second steps, the graphics library applies transfer
|
|
|
1185 |
functions to the device colorants. Where needed, the output of the results
|
|
|
1186 |
after the transfer functions is used by the graphics library for halftoning.
|
|
|
1187 |
|
|
|
1188 |
<p>
|
|
|
1189 |
In the second step, the device procedure <b><tt>encode_color</tt></b> is
|
|
|
1190 |
used to convert the transfer function results into a
|
|
|
1191 |
<b><tt>gx_color_index</tt></b> value.
|
|
|
1192 |
The <b><tt>gx_color_index</tt></b> values are passed to specify colors
|
|
|
1193 |
to various routines.
|
|
|
1194 |
The choice of the encoding for a <b><tt>gx_color_index</tt></b> is
|
|
|
1195 |
up to the device. Common choices are indexes into a color palette or
|
|
|
1196 |
several integers packed together into a single value. The manner of this
|
|
|
1197 |
encoding is usually opaque to the graphics library. The only exception to this
|
|
|
1198 |
statement occurs when halftoning 5 or more colorants. In this case the
|
|
|
1199 |
graphics library assumes that if a colorant values is zero then the
|
|
|
1200 |
bits associated with the colorant in the <b><tt>gx_color_index</tt></b>
|
|
|
1201 |
value are zero.
|
|
|
1202 |
|
|
|
1203 |
<dl>
|
|
|
1204 |
<dt><b><tt>int get_color_comp_index(const gx_device * dev, const char * pname,
|
|
|
1205 |
int name_size, int src_index)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1206 |
<dd>This procedure returns the device colorant number of the given name.
|
|
|
1207 |
The possible return values are -1, 0 to
|
|
|
1208 |
<b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS - 1</tt></b>, or
|
|
|
1209 |
<b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS</tt></b>. A value of -1 indicates that
|
|
|
1210 |
the specified name is not a colorant for the device. A value of 0 to
|
|
|
1211 |
<b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS - 1</tt></b> indicates the colorant number
|
|
|
1212 |
of the given name. A value of <b><tt>GX_DEVICE_COLOR_MAX_COMPONENTS</tt></b>
|
|
|
1213 |
indicates that the given name is a valid colorant name for the device but the
|
|
|
1214 |
colorant is not currently being used. This is used for implementing names
|
|
|
1215 |
which are in SeparationColorNames but not in SeparationOrder.
|
|
|
1216 |
|
|
|
1217 |
<p>
|
|
|
1218 |
The default procedure returns results based upon process color model
|
|
|
1219 |
of DeviceGray, DeviceRGB, or DeviceCMYK selected by
|
|
|
1220 |
<b><tt>color_info.num_components</tt></b>. This procedure must be
|
|
|
1221 |
defined if another process color model is used by the device or spot colors are
|
|
|
1222 |
supported by the device.
|
|
|
1223 |
</dd>
|
|
|
1224 |
</dl>
|
|
|
1225 |
|
|
|
1226 |
<dl>
|
|
|
1227 |
<dt><b><tt>const gx_cm_color_map_procs * get_color_mapping_procs(const
|
|
|
1228 |
gx_device * dev)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1229 |
<dd>This procedure returns a list of three procedures. These procedures
|
|
|
1230 |
are used to translate values in either Gray, RGB, or CMYK color spaces
|
|
|
1231 |
into device colorant values. A separate procedure is not required for the
|
|
|
1232 |
DeviceN and Separation color spaces since these already represent
|
|
|
1233 |
device colorants.
|
|
|
1234 |
|
|
|
1235 |
<p>
|
|
|
1236 |
The default procedure returns a list of procedures based upon
|
|
|
1237 |
<b><tt>color_info.num_components</tt></b>. These procedures are appropriate
|
|
|
1238 |
for DeviceGray, DeviceRGB, or DeviceCMYK process color model devices. A
|
|
|
1239 |
procedure must be defined if another process color model is used by the
|
|
|
1240 |
device or spot colors are to be supported.
|
|
|
1241 |
</dd>
|
|
|
1242 |
</dl>
|
|
|
1243 |
|
|
|
1244 |
<dl>
|
|
|
1245 |
<dt><b><tt>gx_color_index (*encode_color)(gx_device * dev,
|
|
|
1246 |
gx_color_value * cv)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1247 |
<dd>Map a set of device color values into a <b><tt>gx_color_index</tt></b>
|
|
|
1248 |
value. The range of legal values of the
|
|
|
1249 |
arguments is 0 to <b><tt>gx_max_color_value</tt></b>. The default procedure
|
|
|
1250 |
packs bits into a <b><tt>gx_color_index</tt></b> value based upon the
|
|
|
1251 |
values in <b><tt>color_info.depth</tt></b> and
|
|
|
1252 |
<b><tt>color_info.num_components</tt></b>.
|
|
|
1253 |
|
|
|
1254 |
<p>
|
|
|
1255 |
Note that the <b><tt>encode_color</tt></b> procedure
|
|
|
1256 |
must not return <b><tt>gx_no_color_index</tt></b> (all 1s).
|
|
|
1257 |
</dl>
|
|
|
1258 |
|
|
|
1259 |
<dl>
|
|
|
1260 |
<dt><b><tt>int (*decode_color)(gx_device *, gx_color_index color,
|
|
|
1261 |
gx_color_value * CV)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1262 |
<dd>This is the inverse of the <b><tt>encode_color</tt></b> procedure.
|
|
|
1263 |
Map a <b><tt>gx_color_index</tt></b> value to color values. The default
|
|
|
1264 |
procedure unpacks bits from the <b><tt>gx_color_index</tt></b> value based upon
|
|
|
1265 |
the values in <b><tt>color_info.depth</tt></b> and
|
|
|
1266 |
<b><tt>color_info.num_components</tt></b>.
|
|
|
1267 |
</dl>
|
|
|
1268 |
|
|
|
1269 |
<dl>
|
|
|
1270 |
<dt><b><tt>gx_color_index (*map_rgb_alpha_color)(gx_device *,
|
|
|
1271 |
gx_color_value red, gx_color_value green,
|
|
|
1272 |
gx_color_value blue, gx_color_value alpha)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1273 |
<dd>Map a RGB color and an opacity value to a device color. The range of
|
|
|
1274 |
legal values of the RGB and alpha arguments is 0 to
|
|
|
1275 |
<b><tt>gx_max_color_value</tt></b>; <b><tt>alpha</tt></b> = 0 means
|
|
|
1276 |
transparent, <b><tt>alpha</tt></b> = <b><tt>gx_max_color_value</tt></b>
|
|
|
1277 |
means fully opaque. The default is to use the
|
|
|
1278 |
<b><tt>encode_color</tt></b> procedure and ignore alpha.
|
|
|
1279 |
|
|
|
1280 |
<p>
|
|
|
1281 |
Note that if a driver implements <b><tt>map_rgb_alpha_color</tt></b>, it
|
|
|
1282 |
must also implement <b><tt>encode_color</tt></b>, and must implement them
|
|
|
1283 |
in such a way that
|
|
|
1284 |
<b><tt>map_rgb_alpha_color(dev, r, g, b, gx_max_color_value)</tt></b>
|
|
|
1285 |
returns the same value as
|
|
|
1286 |
<b><tt>encode_color(dev, CV)</tt></b>.
|
|
|
1287 |
</dl>
|
|
|
1288 |
|
|
|
1289 |
<dl>
|
|
|
1290 |
<dt><b><tt>int (*map_color_rgb_alpha)(gx_device *,
|
|
|
1291 |
gx_color_index color, gx_color_value rgba[4])</tt></b>
|
|
|
1292 |
<b><em>[OPTIONAL]</em></b>
|
|
|
1293 |
<dd>Map a device color code to RGB and alpha values. The default
|
|
|
1294 |
implementation calls <b><tt>map_color_rgb</tt></b> and fills in
|
|
|
1295 |
<b><tt>gx_max_color_value</tt></b> for alpha.
|
|
|
1296 |
|
|
|
1297 |
<p>
|
|
|
1298 |
Note that if a driver implements <b><tt>map_color_rgb_alpha</tt></b>, it
|
|
|
1299 |
must also implement <b><tt>decode_color</tt></b>, and must implement them
|
|
|
1300 |
in such a way that the first 3 values returned by
|
|
|
1301 |
<b><tt>map_color_rgb_alpha</tt></b> are the same as the values returned by
|
|
|
1302 |
<b><tt>decode_color</tt></b>.
|
|
|
1303 |
|
|
|
1304 |
<p>
|
|
|
1305 |
Note that only RGB devices currently support variable opacity; alpha is ignored
|
|
|
1306 |
on other devices. The PDF 1.4 transparency features are supported on all devices.
|
|
|
1307 |
</dl>
|
|
|
1308 |
|
|
|
1309 |
<dl>
|
|
|
1310 |
<dt><b><tt>typedef enum { go_text,
|
|
|
1311 |
go_graphics } graphic_object_type; int
|
|
|
1312 |
(*get_alpha_bits)(gx_device *dev,
|
|
|
1313 |
graphic_object_type type)</tt></b> <b><em>[OPTIONAL] [OBSOLETE]</em></b>
|
|
|
1314 |
<dd>This procedure is no longer used: it is replaced by the
|
|
|
1315 |
color_info.anti_alias member of the driver structure. However, it still
|
|
|
1316 |
appears in the driver procedure vector for backward compatibility. It
|
|
|
1317 |
should never be called, and drivers should not implement it.
|
|
|
1318 |
</dl>
|
|
|
1319 |
|
|
|
1320 |
<dl>
|
|
|
1321 |
<dt><b><tt>void (*update_spot_equivalent_colors)(gx_device *,
|
|
|
1322 |
const gs_state *)</tt></b>
|
|
|
1323 |
<b><em>[OPTIONAL]</em></b>
|
|
|
1324 |
<dd>This routine provides a method for the device to gather an equivalent
|
|
|
1325 |
color for spot colorants. This routine is called when a Separation or DeviceN
|
|
|
1326 |
color space is installed. See comments at the start of
|
|
|
1327 |
<a href="../src/gsequivc.c">gsequivc.c</a>. Note: This procedure is only needed
|
|
|
1328 |
for devices that support spot colorants and also need to have an equivalent
|
|
|
1329 |
color for simulating the appearance of the spot colorants.
|
|
|
1330 |
</dl>
|
|
|
1331 |
|
|
|
1332 |
<h3><a name="Pixel_level_drawing"></a>Pixel-level drawing</h3>
|
|
|
1333 |
|
|
|
1334 |
<p>
|
|
|
1335 |
This group of drawing operations specifies data at the pixel level. All
|
|
|
1336 |
drawing operations use device coordinates and device color values.
|
|
|
1337 |
|
|
|
1338 |
<dl>
|
|
|
1339 |
<dt><b><tt>int (*fill_rectangle)(gx_device *, int x,
|
|
|
1340 |
int y, int width, int height,
|
|
|
1341 |
gx_color_index color)</tt></b>
|
|
|
1342 |
<dd>Fill a rectangle with a color. The set of pixels filled is {(px,py) |
|
|
|
1343 |
x <= px < x + width and y <= py < y + height}. In other words,
|
|
|
1344 |
the point <em>(x,y)</em> is included in the rectangle, as are
|
|
|
1345 |
<em>(x+w-1,y)</em>, <em>(x,y+h-1)</em>, and <em>(x+w-1,y+h-1)</em>, but
|
|
|
1346 |
<b><em>not</em></b> <em>(x+w,y)</em>, <em>(x,y+h)</em>, or
|
|
|
1347 |
<em>(x+w,y+h)</em>. If <b><tt>width</tt></b> <= 0 or
|
|
|
1348 |
height <= 0, <b><tt>fill_rectangle</tt></b> should return 0
|
|
|
1349 |
without drawing anything.
|
|
|
1350 |
|
|
|
1351 |
<p>
|
|
|
1352 |
Note that <b><tt>fill_rectangle</tt></b> is the only non-optional procedure
|
|
|
1353 |
in the driver interface.
|
|
|
1354 |
</dl>
|
|
|
1355 |
|
|
|
1356 |
<h4><a name="Bitmap_imaging"></a>Bitmap imaging</h4>
|
|
|
1357 |
|
|
|
1358 |
<p>
|
|
|
1359 |
Bitmap (or pixmap) images are stored in memory in a nearly standard way.
|
|
|
1360 |
The first byte corresponds to <em>(0,0)</em> in the image coordinate
|
|
|
1361 |
system: bits (or polybit color values) are packed into it left to right.
|
|
|
1362 |
There may be padding at the end of each scan line: the distance from one
|
|
|
1363 |
scan line to the next is always passed as an explicit argument.
|
|
|
1364 |
|
|
|
1365 |
<dl>
|
|
|
1366 |
<dt><b><tt>int (*copy_mono)(gx_device *,
|
|
|
1367 |
const unsigned char *data, int data_x, int raster,
|
|
|
1368 |
gx_bitmap_id id, int x, int y, int width,
|
|
|
1369 |
int height, gx_color_index color0,
|
|
|
1370 |
gx_color_index color1)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1371 |
<dd>Copy a monochrome image (similar to the PostScript image operator).
|
|
|
1372 |
Each scan line is raster bytes wide. Copying begins at
|
|
|
1373 |
(<b><tt>data_x</tt></b>,0) and transfers a rectangle of the given width and
|
|
|
1374 |
height to the device at device coordinate <em>(x,y)</em>. (If the transfer
|
|
|
1375 |
should start at some non-zero y value in the data, the caller can adjust
|
|
|
1376 |
the data address by the appropriate multiple of the raster.) The copying
|
|
|
1377 |
operation writes device color <b><tt>color0</tt></b> at each 0-bit, and
|
|
|
1378 |
<b><tt>color1</tt></b> at each 1-bit: if <b><tt>color0</tt></b> or
|
|
|
1379 |
<b><tt>color1</tt></b> is <b><tt>gx_no_color_index</tt></b>, the device
|
|
|
1380 |
pixel is unaffected if the image bit is 0 or 1 respectively. If
|
|
|
1381 |
<b><tt>id</tt></b> is different from <b><tt>gx_no_bitmap_id</tt></b>, it
|
|
|
1382 |
identifies the bitmap contents unambiguously; a call with the same
|
|
|
1383 |
<b><tt>id</tt></b> will always have the same <b><tt>data</tt></b>,
|
|
|
1384 |
<b><tt>raster</tt></b>, and data contents.
|
|
|
1385 |
|
|
|
1386 |
<p>
|
|
|
1387 |
This operation, with
|
|
|
1388 |
<b><tt>color0</tt></b> = <b><tt>gx_no_color_index</tt></b>, is
|
|
|
1389 |
the workhorse for text display in Ghostscript, so implementing it
|
|
|
1390 |
efficiently is very important.
|
|
|
1391 |
</dl>
|
|
|
1392 |
|
|
|
1393 |
<dl>
|
|
|
1394 |
<dt><b><tt>int (*tile_rectangle)(gx_device *,
|
|
|
1395 |
const gx_tile_bitmap *tile, int x, int y,
|
|
|
1396 |
int width, int height, gx_color_index color0,
|
|
|
1397 |
gx_color_index color1, int phase_x, int phase_y)</tt></b>
|
|
|
1398 |
<b><em>[OPTIONAL] [OBSOLETE]</em></b>
|
|
|
1399 |
<dd>This procedure is still supported, but has been superseded by
|
|
|
1400 |
<b><tt>strip_tile_rectangle</tt></b>. New drivers should implement
|
|
|
1401 |
<b><tt>strip_tile_rectangle</tt></b>; if they cannot cope with non-zero
|
|
|
1402 |
shift values, they should test for this explicitly and call the default
|
|
|
1403 |
implementation (<b><tt>gx_default_strip_tile_rectangle</tt></b>) if
|
|
|
1404 |
shift != 0. Clients should call
|
|
|
1405 |
<b><tt>strip_tile_rectangle</tt></b>, not <b><tt>tile_rectangle</tt></b>.
|
|
|
1406 |
</dl>
|
|
|
1407 |
|
|
|
1408 |
<dl>
|
|
|
1409 |
<dt><b><tt>int (*strip_tile_rectangle)(gx_device *,
|
|
|
1410 |
const gx_strip_bitmap *tile, int x, int y,
|
|
|
1411 |
int width, int height, gx_color_index color0,
|
|
|
1412 |
gx_color_index color1, int phase_x, int phase_y)</tt></b>
|
|
|
1413 |
<b><em>[OPTIONAL]</em></b>
|
|
|
1414 |
<dd>Tile a rectangle. Tiling consists of doing multiple
|
|
|
1415 |
<b><tt>copy_mono</tt></b> operations to fill the rectangle with copies of
|
|
|
1416 |
the tile. The tiles are aligned with the device coordinate system, to
|
|
|
1417 |
avoid "seams". Specifically, the (<b><tt>phase_x</tt></b>,
|
|
|
1418 |
<b><tt>phase_y</tt></b>) point of the tile is aligned with the origin of
|
|
|
1419 |
the device coordinate system. (Note that this is backwards from the
|
|
|
1420 |
PostScript definition of halftone phase.) <b><tt>phase_x</tt></b> and
|
|
|
1421 |
<b><tt>phase_y</tt></b> are guaranteed to be in the range
|
|
|
1422 |
<em>[0..</em><b><tt>tile->width</tt></b><em>)</em> and
|
|
|
1423 |
<em>[0..</em><b><tt>tile->height</tt></b><em>)</em> respectively.
|
|
|
1424 |
|
|
|
1425 |
<p>
|
|
|
1426 |
If <b><tt>color0</tt></b> and <b><tt>color1</tt></b> are both
|
|
|
1427 |
<b><tt>gx_no_color_index</tt></b>, then the tile is a color pixmap, not a
|
|
|
1428 |
bitmap: see the next section.
|
|
|
1429 |
|
|
|
1430 |
<p>
|
|
|
1431 |
This operation is the workhorse for halftone filling in Ghostscript, so
|
|
|
1432 |
implementing it efficiently for solid tiles (that is, where either
|
|
|
1433 |
<b><tt>color0</tt></b> and <b><tt>color1</tt></b> are both
|
|
|
1434 |
<b><tt>gx_no_color_index</tt></b>, for colored halftones, or neither one is
|
|
|
1435 |
<b><tt>gx_no_color_index</tt></b>, for monochrome halftones) is very
|
|
|
1436 |
important.
|
|
|
1437 |
</dl>
|
|
|
1438 |
|
|
|
1439 |
<h4><a name="Pixmap_imaging"></a>Pixmap imaging</h4>
|
|
|
1440 |
|
|
|
1441 |
<p>
|
|
|
1442 |
Pixmaps are just like bitmaps, except that each pixel occupies more than
|
|
|
1443 |
one bit. All the bits for each pixel are grouped together (this is
|
|
|
1444 |
sometimes called "chunky" or "Z" format). For <b><tt>copy_color</tt></b>,
|
|
|
1445 |
the number of bits per pixel is given by the
|
|
|
1446 |
<b><tt>color_info.depth</tt></b> parameter in the device structure: the
|
|
|
1447 |
legal values are 1, 2, 4, 8, 16, 24, 32, 40, 48, 56, or 64. The pixel
|
|
|
1448 |
values are device color codes (that is, whatever it is that
|
|
|
1449 |
<b><tt>encode_color</tt></b> returns).
|
|
|
1450 |
|
|
|
1451 |
<dl>
|
|
|
1452 |
<dt><b><tt>int (*copy_color)(gx_device *,
|
|
|
1453 |
const unsigned char *data, int data_x, int raster,
|
|
|
1454 |
gx_bitmap_id id, int x, int y, int width,
|
|
|
1455 |
int height)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1456 |
<dd>Copy a color image with multiple bits per pixel. The raster is in
|
|
|
1457 |
bytes, but <b><tt>x</tt></b> and <b><tt>width</tt></b> are in pixels, not
|
|
|
1458 |
bits. If <b><tt>id</tt></b> is different from
|
|
|
1459 |
<b><tt>gx_no_bitmap_id</tt></b>, it identifies the bitmap contents
|
|
|
1460 |
unambiguously; a call with the same <b><tt>id</tt></b> will always have the
|
|
|
1461 |
same <b><tt>data</tt></b>, <b><tt>raster</tt></b>, and data contents.
|
|
|
1462 |
|
|
|
1463 |
<p>
|
|
|
1464 |
We do not provide a separate procedure for tiling with a pixmap; instead,
|
|
|
1465 |
<b><tt>tile_rectangle</tt></b> can also take colored tiles. This is
|
|
|
1466 |
indicated by the <b><tt>color0</tt></b> and <b><tt>color1</tt></b>
|
|
|
1467 |
arguments' both being <b><tt>gx_no_color_index</tt></b>. In this case, as
|
|
|
1468 |
for <b><tt>copy_color</tt></b>, the <b><tt>raster</tt></b> and
|
|
|
1469 |
<b><tt>height</tt></b> in the "bitmap" are interpreted as for real bitmaps,
|
|
|
1470 |
but the <b><tt>x</tt></b> and <b><tt>width</tt></b> are in pixels, not
|
|
|
1471 |
bits.
|
|
|
1472 |
</dl>
|
|
|
1473 |
|
|
|
1474 |
<h4><a name="Compositing"></a>Compositing</h4>
|
|
|
1475 |
|
|
|
1476 |
<p>
|
|
|
1477 |
In addition to direct writing of opaque pixels, devices must also support
|
|
|
1478 |
compositing. Currently two kinds of compositing are defined
|
|
|
1479 |
(<b><tt>RasterOp</tt></b> and alpha-based), but more may be added in the
|
|
|
1480 |
future.
|
|
|
1481 |
|
|
|
1482 |
<blockquote>
|
|
|
1483 |
<b><em>THIS AREA OF THE INTERFACE IS SOMEWHAT UNSTABLE: USE AT YOUR OWN
|
|
|
1484 |
RISK.</em></b>
|
|
|
1485 |
</blockquote>
|
|
|
1486 |
|
|
|
1487 |
<dl>
|
|
|
1488 |
<dt><b><tt>int (*copy_alpha)(gx_device *dev,
|
|
|
1489 |
const unsigned char *data, int data_x, int raster,
|
|
|
1490 |
gx_bitmap_id id, int x, int y, int width,
|
|
|
1491 |
int height, gx_color_index color, int depth)</tt></b>
|
|
|
1492 |
<b><em>[OPTIONAL]</em></b>
|
|
|
1493 |
<dd>This procedure is somewhat misnamed: it was added to the interface
|
|
|
1494 |
before we really understood alpha channel and compositing.
|
|
|
1495 |
|
|
|
1496 |
<p>
|
|
|
1497 |
Fill a given region with a given color modified by an individual alpha
|
|
|
1498 |
value for each pixel. For each pixel, this is equivalent to
|
|
|
1499 |
alpha-compositing with a source pixel whose alpha value is obtained from
|
|
|
1500 |
the pixmap (<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, and
|
|
|
1501 |
<b><tt>raster</tt></b>) and whose color is the given color (which has
|
|
|
1502 |
<b><em>not</em></b> been premultiplied by the alpha value), using the Sover
|
|
|
1503 |
rule. <b><tt>depth</tt></b>, the number of bits per alpha value, is either
|
|
|
1504 |
2 or 4, and in any case is always a value returned by a previous call on
|
|
|
1505 |
the <b><tt>get_alpha_bits</tt></b> procedure. Note that if
|
|
|
1506 |
<b><tt>get_alpha_bits</tt></b> always returns 1, this procedure will never
|
|
|
1507 |
be called.
|
|
|
1508 |
</dl>
|
|
|
1509 |
|
|
|
1510 |
<dl>
|
|
|
1511 |
<dt><b><tt>int (*create_compositor)(dev_t *dev,
|
|
|
1512 |
gx_device_t **pcdev, const gs_composite_t *pcte,
|
|
|
1513 |
const gs_imager_state *pis, gs_memory_t *memory)</tt></b>
|
|
|
1514 |
<b><em>[OPTIONAL]</em></b>
|
|
|
1515 |
<dd>Create a new device (called a "compositing device" or "compositor")
|
|
|
1516 |
that will composite data written to it with the device's existing data,
|
|
|
1517 |
according to the compositing function defined by <b><tt>*pcte</tt></b>.
|
|
|
1518 |
Devices will normally implement this in one of the following standard ways:
|
|
|
1519 |
|
|
|
1520 |
<ul>
|
|
|
1521 |
<li>Devices that don't do any imaging and don't forward any imaging
|
|
|
1522 |
operations (for example, the null device, the hit detection device, and the
|
|
|
1523 |
clipping list accumulation device) simply return themselves, which
|
|
|
1524 |
effectively ignores the compositing function.
|
|
|
1525 |
|
|
|
1526 |
<li>"Leaf" devices that do imaging and have no special optimizations for
|
|
|
1527 |
compositing (for example, some memory devices) ask the
|
|
|
1528 |
<b><tt>gs_composite_t</tt></b> to create a default compositor.
|
|
|
1529 |
|
|
|
1530 |
<li>Leaf devices that can implement some kinds of compositing operation
|
|
|
1531 |
efficiently (for example, monobit memory devices and RasterOp) inspect the
|
|
|
1532 |
type and values of <b><tt>*pcte</tt></b> to determine whether it specifies
|
|
|
1533 |
such an operation: if so, they create a specialized compositor, and if not,
|
|
|
1534 |
they ask the <b><tt>gs_composite_t</tt></b> to create a default compositor.
|
|
|
1535 |
</ul>
|
|
|
1536 |
|
|
|
1537 |
<p>
|
|
|
1538 |
Other kinds of forwarding devices, which don't fall into any of these
|
|
|
1539 |
categories, require special treatment. In principle, what they do is ask
|
|
|
1540 |
their target to create a compositor, and then create and return a copy of
|
|
|
1541 |
themselves with the target's new compositor as the target of the copy.
|
|
|
1542 |
There is a possible default implementation of this approach: if the
|
|
|
1543 |
original device was <b>D</b> with target <b>T</b>, and <b>T</b> creates a
|
|
|
1544 |
compositor <b>C</b>, then the default implementation creates a device
|
|
|
1545 |
<b>F</b> that for each operation temporarily changes <b>D</b>'s target to
|
|
|
1546 |
<b>C</b>, forwards the operation to <b>D</b>, and then changes <b>D</b>'s
|
|
|
1547 |
target back to <b>T</b>. However, the Ghostscript library currently only
|
|
|
1548 |
creates a compositor with an imaging forwarding device as target in a few
|
|
|
1549 |
specialized situations (banding, and bounding box computation), and these
|
|
|
1550 |
are handled as special cases.
|
|
|
1551 |
|
|
|
1552 |
<p>
|
|
|
1553 |
Note that the compositor may have a different color space, color
|
|
|
1554 |
representation, or bit depth from the device to which it is compositing.
|
|
|
1555 |
For example, alpha-compositing devices use standard-format chunky color
|
|
|
1556 |
even if the underlying device doesn't.
|
|
|
1557 |
|
|
|
1558 |
<p>
|
|
|
1559 |
Closing a compositor frees all of its storage, including the compositor
|
|
|
1560 |
itself. However, since the <b><tt>create_compositor</tt></b> call may
|
|
|
1561 |
return the same device, clients must check for this case, and only call the
|
|
|
1562 |
close procedure if a separate device was created.
|
|
|
1563 |
</dl>
|
|
|
1564 |
|
|
|
1565 |
<p>
|
|
|
1566 |
<font size="+1">
|
|
|
1567 |
<b><em>[strip_]copy_rop WILL BE SUPERSEDED BY COMPOSITORS</em></b>
|
|
|
1568 |
</font>
|
|
|
1569 |
|
|
|
1570 |
<dl>
|
|
|
1571 |
<dt><b><tt>int (*copy_rop)(gx_device *dev,
|
|
|
1572 |
const byte *sdata, int sourcex, uint sraster,
|
|
|
1573 |
gx_bitmap_id id, const gx_color_index *scolors,
|
|
|
1574 |
const gx_tile_bitmap *texture,
|
|
|
1575 |
const gx_color_index *tcolors, int x, int y,
|
|
|
1576 |
int width, int height, int phase_x, int phase_y,
|
|
|
1577 |
int command)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1578 |
<dd>This procedure is still supported, but has been superseded by
|
|
|
1579 |
<b><tt>strip_copy_rop</tt></b>. New drivers should implement
|
|
|
1580 |
<b><tt>strip_copy_rop</tt></b>; if they cannot cope with non-zero shift
|
|
|
1581 |
values in the texture, they should test for this explicitly and call the
|
|
|
1582 |
default implementation (<b><tt>gx_default_strip_copy_rop</tt></b>) if
|
|
|
1583 |
shift != 0. Clients should call <b><tt>strip_copy_rop</tt></b>,
|
|
|
1584 |
not <b><tt>copy_rop</tt></b>.
|
|
|
1585 |
</dl>
|
|
|
1586 |
|
|
|
1587 |
<dl>
|
|
|
1588 |
<dt><b><tt>int (*strip_copy_rop)(gx_device *dev,
|
|
|
1589 |
const byte *sdata, int sourcex, uint sraster,
|
|
|
1590 |
gx_bitmap_id id, const gx_color_index *scolors,
|
|
|
1591 |
const gx_strip_bitmap *texture,
|
|
|
1592 |
const gx_color_index *tcolors, int x, int y,
|
|
|
1593 |
int width, int height, int phase_x, int phase_y,
|
|
|
1594 |
int command)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1595 |
<dd>Combine an optional source image <b>S</b> (as for
|
|
|
1596 |
<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b>) and an optional
|
|
|
1597 |
texture <b>T</b> (a tile, as for <b><tt>tile_rectangle</tt></b>) with the
|
|
|
1598 |
existing bitmap or pixmap <b>D</b> held by the driver, pixel by pixel,
|
|
|
1599 |
using any 3-input Boolean operation as modified by "transparency" flags:
|
|
|
1600 |
schematically, set <b>D = f(D,S,T)</b>, computing <b>f</b> in RGB
|
|
|
1601 |
space rather than using actual device pixel values. <b>S</b> and <b>T</b>
|
|
|
1602 |
may each (independently) be a solid color, a bitmap with "foreground" and
|
|
|
1603 |
"background" colors, or a pixmap. This is a complex (and currently rather
|
|
|
1604 |
slow) operation. The arguments are as follows:
|
|
|
1605 |
|
|
|
1606 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
1607 |
<tr valign=top> <td><b><tt>dev</tt></b>
|
|
|
1608 |
<td>
|
|
|
1609 |
<td>the device, as for all driver procedures
|
|
|
1610 |
<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>
|
|
|
1611 |
<td>
|
|
|
1612 |
<td>specify <b>S</b>, <a href="#S_spec">see below</a>
|
|
|
1613 |
<tr valign=top> <td><b><tt>texture</tt></b>, <b><tt>tcolors</tt></b>
|
|
|
1614 |
<td>
|
|
|
1615 |
<td>specify <b>T</b>, <a href="#T_spec">see below</a>
|
|
|
1616 |
<tr valign=top> <td><b><tt>x</tt></b>, <b><tt>y</tt></b>, <b><tt>width</tt></b>, <b><tt>height</tt></b>
|
|
|
1617 |
<td>
|
|
|
1618 |
<td>as for the other copy and fill procedures
|
|
|
1619 |
<tr valign=top> <td><b><tt>phase_x</tt></b>, <b><tt>phase_y</tt></b>
|
|
|
1620 |
<td>
|
|
|
1621 |
<td>part of <b>T</b> specification, <a href="#T_spec">see below</a>
|
|
|
1622 |
<tr valign=top> <td><b><tt>command</tt></b>
|
|
|
1623 |
<td>
|
|
|
1624 |
<td><a href="#F_spec">see below</a>
|
|
|
1625 |
</table></blockquote>
|
|
|
1626 |
</dl>
|
|
|
1627 |
|
|
|
1628 |
<h5><a name="S_spec"></a>The source specification S</h5>
|
|
|
1629 |
|
|
|
1630 |
<p>
|
|
|
1631 |
As noted above, the source <b>S</b> may be a solid color, a bitmap, or a
|
|
|
1632 |
pixmap. If <b>S</b> is a solid color:
|
|
|
1633 |
|
|
|
1634 |
<ul>
|
|
|
1635 |
<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>,
|
|
|
1636 |
<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> are irrelevant.
|
|
|
1637 |
|
|
|
1638 |
<li><b><tt>scolors</tt></b> points to two <b><tt>gx_color_index</tt></b>
|
|
|
1639 |
values; <b><tt>scolors[0]</tt></b> = <b><tt>scolors[1]</tt></b> = the
|
|
|
1640 |
color.
|
|
|
1641 |
</ul>
|
|
|
1642 |
|
|
|
1643 |
<p>
|
|
|
1644 |
If <b>S</b> is a bitmap:
|
|
|
1645 |
|
|
|
1646 |
<ul>
|
|
|
1647 |
<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>,
|
|
|
1648 |
<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> arguments are as for
|
|
|
1649 |
<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b>
|
|
|
1650 |
(<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, <b><tt>raster</tt></b>,
|
|
|
1651 |
<b><tt>id</tt></b>), and specify a source bitmap.
|
|
|
1652 |
|
|
|
1653 |
<li><b><tt>scolors</tt></b> points to two <b><tt>gx_color_index</tt></b>
|
|
|
1654 |
values; <b><tt>scolors[0]</tt></b> is the background color (the color
|
|
|
1655 |
corresponding to 0-bits in the bitmap), <b><tt>scolors[1]</tt></b> is the
|
|
|
1656 |
foreground color (the color corresponding to 1-bits in the bitmap).
|
|
|
1657 |
</ul>
|
|
|
1658 |
|
|
|
1659 |
<p>
|
|
|
1660 |
If <b>S</b> is a pixmap:
|
|
|
1661 |
|
|
|
1662 |
<ul>
|
|
|
1663 |
<li><b><tt>sdata</tt></b>, <b><tt>sourcex</tt></b>,
|
|
|
1664 |
<b><tt>sraster</tt></b>, and <b><tt>id</tt></b> arguments are as for
|
|
|
1665 |
<b><tt>copy_mono</tt></b> or <b><tt>copy_color</tt></b>
|
|
|
1666 |
(<b><tt>data</tt></b>, <b><tt>data_x</tt></b>, <b><tt>raster</tt></b>,
|
|
|
1667 |
<b><tt>id</tt></b>), and specify a source pixmap whose depth is the same as
|
|
|
1668 |
the depth of the destination.
|
|
|
1669 |
|
|
|
1670 |
<li><b><tt>scolors</tt></b> is <b><tt>NULL</tt></b>.
|
|
|
1671 |
</ul>
|
|
|
1672 |
|
|
|
1673 |
<p>
|
|
|
1674 |
Note that if the source is a bitmap with background=0 and foreground=1, and
|
|
|
1675 |
the destination is 1 bit deep, then the source can be treated as a pixmap
|
|
|
1676 |
(scolors=<b><tt>NULL</tt></b>).
|
|
|
1677 |
|
|
|
1678 |
<h5><a name="T_spec"></a>The texture specification T</h5>
|
|
|
1679 |
|
|
|
1680 |
<p>
|
|
|
1681 |
Similar to the source, the texture <b>T</b> may be a solid color, a bitmap,
|
|
|
1682 |
or a pixmap. If <b>T</b> is a solid color:
|
|
|
1683 |
|
|
|
1684 |
<ul>
|
|
|
1685 |
<li>The texture pointer is irrelevant.
|
|
|
1686 |
|
|
|
1687 |
<li><b><tt>tcolors</tt></b> points to two <b><tt>gx_color_index</tt></b>
|
|
|
1688 |
values; <b><tt>tcolors[0]</tt></b> = <b><tt>tcolors[1]</tt></b> = the
|
|
|
1689 |
color.
|
|
|
1690 |
</ul>
|
|
|
1691 |
|
|
|
1692 |
<p>
|
|
|
1693 |
If <b>T</b> is a bitmap:
|
|
|
1694 |
|
|
|
1695 |
<ul>
|
|
|
1696 |
<li>The texture argument points to a <b><tt>gx_tile_bitmap</tt></b>, as for
|
|
|
1697 |
the <b><tt>tile_rectangle</tt></b> procedure. Similarly,
|
|
|
1698 |
<b><tt>phase_x</tt></b> and <b><tt>phase_y</tt></b> specify the offset of
|
|
|
1699 |
the texture relative to the device coordinate system origin, again as for
|
|
|
1700 |
<b><tt>tile_rectangle</tt></b>. The tile is a bitmap (1 bit per pixel).
|
|
|
1701 |
|
|
|
1702 |
<li><b><tt>tcolors</tt></b> points to two <b><tt>gx_color_index</tt></b>
|
|
|
1703 |
values; <b><tt>tcolors[0]</tt></b> is the background color (the color
|
|
|
1704 |
corresponding to 0-bits in the bitmap), <b><tt>tcolors[1]</tt></b> is the
|
|
|
1705 |
foreground color (the color corresponding to 1-bits in the bitmap).
|
|
|
1706 |
</ul>
|
|
|
1707 |
|
|
|
1708 |
<p>
|
|
|
1709 |
If <b>T</b> is a pixmap:
|
|
|
1710 |
|
|
|
1711 |
<ul>
|
|
|
1712 |
<li>The texture argument points to a <b><tt>gx_tile_bitmap</tt></b> whose
|
|
|
1713 |
depth is the same as the depth of the destination.
|
|
|
1714 |
|
|
|
1715 |
<li>tcolors is <b><tt>NULL</tt></b>.
|
|
|
1716 |
</ul>
|
|
|
1717 |
|
|
|
1718 |
<p>
|
|
|
1719 |
Again, if the texture is a bitmap with background=0 and foreground=1, and
|
|
|
1720 |
the destination depth is 1, the texture bitmap can be treated as a pixmap
|
|
|
1721 |
(tcolors=<b><tt>NULL</tt></b>).
|
|
|
1722 |
|
|
|
1723 |
<p>
|
|
|
1724 |
Note that while a source bitmap or pixmap has the same width and height as
|
|
|
1725 |
the destination, a texture bitmap or pixmap has its own width and height
|
|
|
1726 |
specified in the <b><tt>gx_tile_bitmap</tt></b> structure, and is
|
|
|
1727 |
replicated or clipped as needed.
|
|
|
1728 |
|
|
|
1729 |
<h5><a name="F_spec"></a>The function specification f</h5>
|
|
|
1730 |
|
|
|
1731 |
<p>
|
|
|
1732 |
"Command" indicates the raster operation and transparency as follows:
|
|
|
1733 |
|
|
|
1734 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
1735 |
<tr valign=bottom>
|
|
|
1736 |
<th>Bits
|
|
|
1737 |
<td>
|
|
|
1738 |
<td>
|
|
|
1739 |
<tr valign=top> <td>7-0
|
|
|
1740 |
<td>
|
|
|
1741 |
<td>raster op
|
|
|
1742 |
<tr valign=top> <td>8
|
|
|
1743 |
<td>
|
|
|
1744 |
<td>0 if source opaque, 1 if source transparent
|
|
|
1745 |
<tr valign=top> <td>9
|
|
|
1746 |
<td>
|
|
|
1747 |
<td>0 if texture opaque, 1 if texture transparent
|
|
|
1748 |
<tr valign=top> <td>?-10
|
|
|
1749 |
<td>
|
|
|
1750 |
<td>unused, must be 0
|
|
|
1751 |
</table></blockquote>
|
|
|
1752 |
|
|
|
1753 |
<p>
|
|
|
1754 |
The raster operation follows the Microsoft and H-P specification. It is an
|
|
|
1755 |
8-element truth table that specifies the output value for each of the
|
|
|
1756 |
possible 2×2×2 input values as follows:
|
|
|
1757 |
|
|
|
1758 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
1759 |
<tr valign=bottom>
|
|
|
1760 |
<th>Bit
|
|
|
1761 |
<td>
|
|
|
1762 |
<th>Texture
|
|
|
1763 |
<td>
|
|
|
1764 |
<th>Source
|
|
|
1765 |
<td>
|
|
|
1766 |
<th>Destination
|
|
|
1767 |
<tr> <td colspan=7><hr>
|
|
|
1768 |
<tr valign=top> <td align=center>7
|
|
|
1769 |
<td>
|
|
|
1770 |
<td align=center>1
|
|
|
1771 |
<td>
|
|
|
1772 |
<td align=center>1
|
|
|
1773 |
<td>
|
|
|
1774 |
<td align=center>1
|
|
|
1775 |
<tr valign=top> <td align=center>6
|
|
|
1776 |
<td>
|
|
|
1777 |
<td align=center>1
|
|
|
1778 |
<td>
|
|
|
1779 |
<td align=center>1
|
|
|
1780 |
<td>
|
|
|
1781 |
<td align=center>0
|
|
|
1782 |
<tr valign=top> <td align=center>5
|
|
|
1783 |
<td>
|
|
|
1784 |
<td align=center>1
|
|
|
1785 |
<td>
|
|
|
1786 |
<td align=center>0
|
|
|
1787 |
<td>
|
|
|
1788 |
<td align=center>1
|
|
|
1789 |
<tr valign=top> <td align=center>4
|
|
|
1790 |
<td>
|
|
|
1791 |
<td align=center>1
|
|
|
1792 |
<td>
|
|
|
1793 |
<td align=center>0
|
|
|
1794 |
<td>
|
|
|
1795 |
<td align=center>0
|
|
|
1796 |
<tr valign=top> <td align=center>3
|
|
|
1797 |
<td>
|
|
|
1798 |
<td align=center>0
|
|
|
1799 |
<td>
|
|
|
1800 |
<td align=center>1
|
|
|
1801 |
<td>
|
|
|
1802 |
<td align=center>1
|
|
|
1803 |
<tr valign=top> <td align=center>2
|
|
|
1804 |
<td>
|
|
|
1805 |
<td align=center>0
|
|
|
1806 |
<td>
|
|
|
1807 |
<td align=center>1
|
|
|
1808 |
<td>
|
|
|
1809 |
<td align=center>0
|
|
|
1810 |
<tr valign=top> <td align=center>1
|
|
|
1811 |
<td>
|
|
|
1812 |
<td align=center>0
|
|
|
1813 |
<td>
|
|
|
1814 |
<td align=center>0
|
|
|
1815 |
<td>
|
|
|
1816 |
<td align=center>1
|
|
|
1817 |
<tr valign=top> <td align=center>0
|
|
|
1818 |
<td>
|
|
|
1819 |
<td align=center>0
|
|
|
1820 |
<td>
|
|
|
1821 |
<td align=center>0
|
|
|
1822 |
<td>
|
|
|
1823 |
<td align=center>0
|
|
|
1824 |
</table></blockquote>
|
|
|
1825 |
|
|
|
1826 |
<p>
|
|
|
1827 |
Transparency affects the output in the following way. A source or texture
|
|
|
1828 |
pixel is considered transparent if its value is all 1s (for instance, 1 for
|
|
|
1829 |
bitmaps, <tt>0xffffff</tt> for 24-bit RGB pixmaps) <b><em>and</em></b> the
|
|
|
1830 |
corresponding transparency bit is set in the command. For each pixel, the
|
|
|
1831 |
result of the Boolean operation is written into the destination iff neither
|
|
|
1832 |
the source nor the texture pixel is transparent. (Note that the HP
|
|
|
1833 |
RasterOp specification, on which this is based, specifies that if the
|
|
|
1834 |
source and texture are both all 1s and the command specifies transparent
|
|
|
1835 |
source and opaque texture, the result <b><em>should</em></b> be written in
|
|
|
1836 |
the output. We think this is an error in the documentation.)
|
|
|
1837 |
|
|
|
1838 |
<h5><a name="Compositing_notes"></a>Notes</h5>
|
|
|
1839 |
|
|
|
1840 |
<p>
|
|
|
1841 |
<b><tt>copy_rop</tt></b> is defined to operate on pixels in RGB space,
|
|
|
1842 |
again following the HP and Microsoft specification. For devices that
|
|
|
1843 |
don't use RGB (or gray-scale with black = 0, white = all 1s) as their
|
|
|
1844 |
native color representation, the implementation of <b><tt>copy_rop</tt></b>
|
|
|
1845 |
must convert to RGB or gray space, do the operation, and convert back (or
|
|
|
1846 |
do the equivalent of this). Here are the <b><tt>copy_rop</tt></b>
|
|
|
1847 |
equivalents of the most important previous imaging calls. We assume the
|
|
|
1848 |
declaration:
|
|
|
1849 |
|
|
|
1850 |
<blockquote><b><tt>
|
|
|
1851 |
static const gx_color_index white2[2] = { 1, 1 };
|
|
|
1852 |
</tt></b></blockquote>
|
|
|
1853 |
|
|
|
1854 |
<p>
|
|
|
1855 |
Note that <b><tt>rop3_S</tt></b> may be replaced by any other Boolean operation.
|
|
|
1856 |
For monobit devices, we assume that black = 1.
|
|
|
1857 |
|
|
|
1858 |
<blockquote>
|
|
|
1859 |
<pre>/* For all devices: */
|
|
|
1860 |
(*fill_rectangle)(dev, x, y, w, h, color) ==>
|
|
|
1861 |
|
|
|
1862 |
{ gx_color_index colors[2];
|
|
|
1863 |
colors[0] = colors[1] = color;
|
|
|
1864 |
(*dev_proc(dev, copy_rop))(dev, NULL, 0, 0, gx_no_bitmap_id, colors,
|
|
|
1865 |
NULL, colors /*irrelevant*/,
|
|
|
1866 |
x, y, w, h, 0, 0, rop3_S);
|
|
|
1867 |
}
|
|
|
1868 |
|
|
|
1869 |
/* For black-and-white devices only: */
|
|
|
1870 |
(*copy_mono)(dev, base, sourcex, sraster, id,
|
|
|
1871 |
x, y, w, h, (gx_color_index)0, (gx_color_index)1) ==>
|
|
|
1872 |
|
|
|
1873 |
(*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, NULL,
|
|
|
1874 |
NULL, white2 /*irrelevant*/,
|
|
|
1875 |
x, y, w, h, 0, 0, rop3_S);
|
|
|
1876 |
|
|
|
1877 |
/* For color devices, where neither color0 nor color1 is gx_no_color_index: */
|
|
|
1878 |
(*copy_mono)(dev, base, sourcex, sraster, id,
|
|
|
1879 |
x, y, w, h, color0, color1) ==>
|
|
|
1880 |
|
|
|
1881 |
{ gx_color_index colors[2];
|
|
|
1882 |
colors[0] = color0, colors[1] = color1;
|
|
|
1883 |
(*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, colors,
|
|
|
1884 |
NULL, white2 /*irrelevant*/,
|
|
|
1885 |
x, y, w, h, 0, 0, rop3_S);
|
|
|
1886 |
}
|
|
|
1887 |
|
|
|
1888 |
/* For black-and-white devices only: */
|
|
|
1889 |
(*copy_mono)(dev, base, sourcex, sraster, id,
|
|
|
1890 |
x, y, w, h, gx_no_color_index, (gx_color_index)1) ==>
|
|
|
1891 |
|
|
|
1892 |
(*dev_proc(dev, copy_rop))(dev, base, sourcex, sraster, id, NULL,
|
|
|
1893 |
NULL, white2 /*irrelevant*/,
|
|
|
1894 |
x, y, w, h, 0, 0,
|
|
|
1895 |
rop3_S | lop_S_transparent);
|
|
|
1896 |
|
|
|
1897 |
/* For all devices: */
|
|
|
1898 |
(*copy_color)(dev, base, sourcex, sraster, id,
|
|
|
1899 |
x, y, w, h) ==> [same as first copy_mono above]
|
|
|
1900 |
|
|
|
1901 |
/* For black-and-white devices only: */
|
|
|
1902 |
(*tile_rectangle)(dev, tile, x, y, w, h,
|
|
|
1903 |
(gx_color_index)0, (gx_color_index)1, px, py) ==>
|
|
|
1904 |
|
|
|
1905 |
(*dev_proc(dev, copy_rop))(dev, NULL, 0, 0, gx_no_bitmap_id,
|
|
|
1906 |
white2 /*irrelevant*/,
|
|
|
1907 |
tile, NULL,
|
|
|
1908 |
x, y, w, h, px, py, rop3_T)
|
|
|
1909 |
</pre></blockquote>
|
|
|
1910 |
|
|
|
1911 |
<h3><a name="Polygon_level_drawing"></a>Polygon-level drawing</h3>
|
|
|
1912 |
|
|
|
1913 |
<p>
|
|
|
1914 |
In addition to the pixel-level drawing operations that take integer device
|
|
|
1915 |
coordinates and pure device colors, the driver interface includes
|
|
|
1916 |
higher-level operations that draw polygons using fixed-point coordinates,
|
|
|
1917 |
possibly halftoned colors, and possibly a non-default logical operation.
|
|
|
1918 |
|
|
|
1919 |
<p>
|
|
|
1920 |
The <b><tt>fill_</tt></b>* drawing operations all use the center-of-pixel
|
|
|
1921 |
rule: a pixel is colored iff its center falls within the polygonal region
|
|
|
1922 |
being filled. If a pixel center <em>(X+0.5,Y+0.5)</em> falls exactly on
|
|
|
1923 |
the boundary, the pixel is filled iff the boundary is horizontal and the
|
|
|
1924 |
filled region is above it, or the boundary is not horizontal and the filled
|
|
|
1925 |
region is to the right of it.
|
|
|
1926 |
|
|
|
1927 |
<dl>
|
|
|
1928 |
<dt><b><tt>int (*fill_trapezoid)(gx_device *dev, const
|
|
|
1929 |
gs_fixed_edge *left, const gs_fixed_edge *right,
|
|
|
1930 |
fixed ybot, fixed ytop, bool swap_axes,
|
|
|
1931 |
const gx_drawing_color *pdcolor,
|
|
|
1932 |
gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1933 |
<dd>Fill a trapezoid. The bottom and top edges are parallel to the x
|
|
|
1934 |
axis, and are defined by <b><tt>ybot</tt></b> and <b><tt>ytop</tt></b>,
|
|
|
1935 |
respectively. The left and right edges are defined by <b><tt>left</tt></b>
|
|
|
1936 |
and <b><tt>right</tt></b>. Both of these represent lines (<b><tt>gs_fixed_edge</tt></b>
|
|
|
1937 |
is defined in <a href="../src/gxdevcli.h">gxdevcli.h</a> and consists
|
|
|
1938 |
of <b><tt>gs_fixed_point</tt></b> <b><tt>start</tt></b> and <b><tt>end</tt></b> points).
|
|
|
1939 |
The y coordinates of these lines need not have any specific relation to
|
|
|
1940 |
<b><tt>ybot</tt></b> and <b><tt>ytop</tt></b>. The routine is defined this way so
|
|
|
1941 |
that the filling algorithm can subdivide edges and still guarantee
|
|
|
1942 |
that the exact same pixels will be filled. If
|
|
|
1943 |
<b><tt>swap_axes</tt></b> is set, the meanings of X and Y are
|
|
|
1944 |
interchanged.
|
|
|
1945 |
</dl>
|
|
|
1946 |
<dt><b><tt>int (*fill_parallelogram)(gx_device *dev,
|
|
|
1947 |
fixed px, fixed py, fixed ax, fixed ay, fixed bx,
|
|
|
1948 |
fixed by, const gx_drawing_color *pdcolor,
|
|
|
1949 |
gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1950 |
<dd>Fill a parallelogram whose corners are <em>(px,py)</em>,
|
|
|
1951 |
<em>(px+ax,py+ay)</em>, <em>(px+bx,py+by)</em>, and
|
|
|
1952 |
<em>(px+ax+bx,py+ay+by)</em>. There are no constraints on the values of
|
|
|
1953 |
any of the parameters, so the parallelogram may have any orientation
|
|
|
1954 |
relative to the coordinate axes.
|
|
|
1955 |
|
|
|
1956 |
|
|
|
1957 |
<dl>
|
|
|
1958 |
<dt><b><tt>int (*fill_triangle)(gx_device *dev, fixed px,
|
|
|
1959 |
fixed py, fixed ax, fixed ay, fixed bx, fixed by,
|
|
|
1960 |
const gx_drawing_color *pdcolor,
|
|
|
1961 |
gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1962 |
<dd>Fill a triangle whose corners are <em>(px,py)</em>,
|
|
|
1963 |
<em>(px+ax,py+ay)</em>, and <em>(px+bx,py+by)</em>.
|
|
|
1964 |
</dl>
|
|
|
1965 |
|
|
|
1966 |
<dl>
|
|
|
1967 |
<dt><b><tt>int (*draw_thin_line)(gx_device *dev,
|
|
|
1968 |
fixed fx0, fixed fy0, fixed fx1, fixed fy1,
|
|
|
1969 |
const gx_drawing_color *pdcolor,
|
|
|
1970 |
gs_logical_operation_t lop)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
1971 |
<dd>Draw a one-pixel-wide line from <em>(fx0,fy0)</em> to
|
|
|
1972 |
<em>(fx1,fy1)</em>.
|
|
|
1973 |
</dl>
|
|
|
1974 |
|
|
|
1975 |
<dl>
|
|
|
1976 |
<dt><b><tt>int (*draw_line)(gx_device *dev, int x0, int y0,
|
|
|
1977 |
int x1, int y1, gx_color_index color)</tt></b>
|
|
|
1978 |
<b><em>[OPTIONAL] [OBSOLETE]</em></b>
|
|
|
1979 |
<dd>This procedure is no longer used: it is replaced by the draw_thin_line
|
|
|
1980 |
procedure. However, still appears in the driver procedure vector for
|
|
|
1981 |
backward compatibility. It should never be called, and drivers should not
|
|
|
1982 |
implement it.
|
|
|
1983 |
</dl>
|
|
|
1984 |
|
|
|
1985 |
<h3><a name="Linear_color_drawing"></a>Linear color drawing</h3>
|
|
|
1986 |
|
|
|
1987 |
<p>
|
|
|
1988 |
Linear color functions allow fast high quality rendering of
|
|
|
1989 |
shadings on continuous tone devices. They implement filling simple areas
|
|
|
1990 |
with a lineary varying color. These functions are not called if the device applies halftones,
|
|
|
1991 |
or uses a non-separable or a non-linear color model.
|
|
|
1992 |
|
|
|
1993 |
<dl>
|
|
|
1994 |
<dt><b><tt> int (*fill_linear_color_triangle)
|
|
|
1995 |
(dev_t *dev, const gs_fill_attributes *fa,
|
|
|
1996 |
const gs_fixed_point *p0, const gs_fixed_point *p1,
|
|
|
1997 |
const gs_fixed_point *p2,
|
|
|
1998 |
const frac31 *c0, const frac31 *c1, const frac31 *c2)
|
|
|
1999 |
</tt></b>
|
|
|
2000 |
<b><em>[OPTIONAL]</em></b>
|
|
|
2001 |
<dd>This function is the highest level one within the linear color function group.
|
|
|
2002 |
It fills a triangle with a linearly varying color.
|
|
|
2003 |
Arguments specify 3 points in the device space - vertices of a triangle, and their colors.
|
|
|
2004 |
The colors are represented as vectors of positive fractional numbers, each of which
|
|
|
2005 |
represents a color component value in the interval <b><tt>[0,1]</tt></b>.
|
|
|
2006 |
The number of components in a vector in the number of color
|
|
|
2007 |
components in the device (process) color model.
|
|
|
2008 |
<dd>
|
|
|
2009 |
The implementation fills entire triangle.
|
|
|
2010 |
The filling rule is same as for <a href="#Polygon_level_drawing">Polygon-level drawing</a>.
|
|
|
2011 |
A color for each pixel within the triangle to be computed as a linear interpolation
|
|
|
2012 |
of vertex colors.
|
|
|
2013 |
<dd>
|
|
|
2014 |
The implementation may reject the request if the area or the color appears too complex
|
|
|
2015 |
for filling in a single action. For doing that the implementation returns 0 and must not
|
|
|
2016 |
paint any pixel. In this case the graphics library will perform a subdivision of the area
|
|
|
2017 |
into smaller triangles and call the function again with smaller areas.
|
|
|
2018 |
<dd>
|
|
|
2019 |
<b><em>Important note :</em></b> Do not try to decompose the area within
|
|
|
2020 |
the implementation of <b><tt> fill_linear_color_triangle </tt></b>, because
|
|
|
2021 |
it can break the plane coverage contiguity and cause a dropout.
|
|
|
2022 |
Instead that request graphics library to perform the decomposition.
|
|
|
2023 |
The graphics libary is smart enough to do that properly.
|
|
|
2024 |
<dd>
|
|
|
2025 |
<b><em>Important note :</em></b>
|
|
|
2026 |
The implementation must handle a special case, when only 2 colors are specified.
|
|
|
2027 |
It happens if <b><tt>p3</tt></b> one is <b><tt>NULL</tt></b>.
|
|
|
2028 |
This means that the color does not depend on the X coordinate,
|
|
|
2029 |
i.e. it forms a linear gradient along the Y axis.
|
|
|
2030 |
The implementation must not reject (return 0) such cases.
|
|
|
2031 |
<dd>
|
|
|
2032 |
<b><em>Important note :</em></b>The device color component
|
|
|
2033 |
value 1 may be represented with several hexadecimal values :
|
|
|
2034 |
<b><tt>0x7FFF0000</tt></b>, <b><tt>0x7FFFF000</tt></b>, <b><tt>0x7FFFFF00</tt></b>, etc.,
|
|
|
2035 |
because the precision here exceeds the color precision of the device.
|
|
|
2036 |
To convert a <b><tt>frac31</tt></b> value into a device color component value,
|
|
|
2037 |
fist drop (ignore) the sign bit, then drop least significant bits -
|
|
|
2038 |
so many ones as you need to fit the device color precision.
|
|
|
2039 |
<dd>
|
|
|
2040 |
<b><em>Important note :</em></b> The <b><tt>fa</tt></b> argument may contain
|
|
|
2041 |
the <b><tt>swap_axes</tt></b> bit set. In this case the implementation must swap (transpoze)
|
|
|
2042 |
<b><tt>X</tt></b> and <b><tt>Y</tt></b> axes.
|
|
|
2043 |
<dd>
|
|
|
2044 |
<b><em>Important note :</em></b> The implementation must not paint outside the
|
|
|
2045 |
clipping rectangle specified in the <b><tt>fa</tt></b> argument.
|
|
|
2046 |
If <b><tt>fa->swap_axes</tt></b> is true, the clipping rectangle is transposed.
|
|
|
2047 |
<dd>
|
|
|
2048 |
See <b><tt> gx_default_fill_linear_color_triangle </tt></b>
|
|
|
2049 |
in <b><tt>gdevddrw.c</tt></b> as a sample code.
|
|
|
2050 |
</dl>
|
|
|
2051 |
|
|
|
2052 |
|
|
|
2053 |
<dl>
|
|
|
2054 |
<dt><b><tt> int (*fill_linear_color_trapezoid)
|
|
|
2055 |
(dev_t *dev, const gs_fill_attributes *fa,
|
|
|
2056 |
const gs_fixed_point *p0, const gs_fixed_point *p1,
|
|
|
2057 |
const gs_fixed_point *p2, const gs_fixed_point *p3,
|
|
|
2058 |
const frac31 *c0, const frac31 *c1,
|
|
|
2059 |
const frac31 *c2, const frac31 *c2)
|
|
|
2060 |
</tt></b>
|
|
|
2061 |
<b><em>[OPTIONAL]</em></b>
|
|
|
2062 |
<dd>This function is a lower level one within the linear color function group.
|
|
|
2063 |
The default implementation of <b><tt> fill_linear_color_triangle </tt></b>
|
|
|
2064 |
calls this function 1-2 times per triangle. Besides that,
|
|
|
2065 |
this function may be called by the graphics library for other special cases,
|
|
|
2066 |
when a decomposition into triangles appears undiserable.
|
|
|
2067 |
<dd>
|
|
|
2068 |
Rather the prototype can specify a bilinear color,
|
|
|
2069 |
we assume that the implementation handles linear colors only.
|
|
|
2070 |
This means that the implementation can ignore any of <b><tt> c0, c1, c2, c3 </tt></b>.
|
|
|
2071 |
The graphics library takes a special care of the color linearity
|
|
|
2072 |
when calling this function. The reason for passing all 4 color arguments
|
|
|
2073 |
is to avoid color precision problems.
|
|
|
2074 |
<dd>
|
|
|
2075 |
Similarly to <b><tt> fill_linear_color_triangle </tt></b>,
|
|
|
2076 |
this function may be called with only 2 colors, and may reject too comple areas.
|
|
|
2077 |
All those important notes are applicable here.
|
|
|
2078 |
<dd>
|
|
|
2079 |
A sample code may be found in in <b><tt>gxdtfill.h</tt></b>, rather it's a kind of complicated.
|
|
|
2080 |
A linear color function is generated from it as <b><tt> gx_fill_trapezoid_ns_lc </tt></b>
|
|
|
2081 |
with the following template parametres :
|
|
|
2082 |
|
|
|
2083 |
<pre>
|
|
|
2084 |
#define LINEAR_COLOR 1
|
|
|
2085 |
#define EDGE_TYPE gs_linear_color_edge
|
|
|
2086 |
#define FILL_ATTRS const gs_fill_attributes *
|
|
|
2087 |
#define CONTIGUOUS_FILL 0
|
|
|
2088 |
#define SWAP_AXES 0
|
|
|
2089 |
#define FILL_DIRECT 1
|
|
|
2090 |
</pre>
|
|
|
2091 |
See the helplers <b><tt>init_gradient</tt></b>,
|
|
|
2092 |
<b><tt>step_gradient</tt></b> (defined in in <b><tt>gdevddrw.c</tt></b>), how to manage colors.
|
|
|
2093 |
See <b><tt>check_gradient_overflow</tt></b>
|
|
|
2094 |
(defined in in <b><tt>gdevddrw.c</tt></b>), as an example of an area
|
|
|
2095 |
that can't be painted in a single action due to 64-bits fixed overflows.
|
|
|
2096 |
|
|
|
2097 |
</dl>
|
|
|
2098 |
|
|
|
2099 |
<dl>
|
|
|
2100 |
<dt><b><tt> int (*fill_linear_color_scanline)
|
|
|
2101 |
(dev_t *dev, const gs_fill_attributes *fa,
|
|
|
2102 |
int i, int j, int w,
|
|
|
2103 |
const frac31 *c0,
|
|
|
2104 |
const int32_t *c0_f,
|
|
|
2105 |
const int32_t *cg_num,
|
|
|
2106 |
int32_t cg_den)
|
|
|
2107 |
</tt></b>
|
|
|
2108 |
<b><em>[OPTIONAL]</em></b>
|
|
|
2109 |
<dd>This function is the lowest level one within the linear color function group.
|
|
|
2110 |
It implements filling a scanline with a linearly varying color.
|
|
|
2111 |
The default implementation for <b><tt> fill_linear_color_trapezoid </tt></b>
|
|
|
2112 |
calls this function, and there are no other calls to it from the graphics libary.
|
|
|
2113 |
Thus if the device implements <b><tt> fill_linear_color_triangle </tt></b> and
|
|
|
2114 |
<b><tt> fill_linear_color_trapezoid </tt></b> by own means,
|
|
|
2115 |
this function may be left unimplemented.
|
|
|
2116 |
<dd>
|
|
|
2117 |
<b><tt>i</tt></b> and <b><tt>j</tt></b> specify device coordinates (indices)
|
|
|
2118 |
of the starting pixel of the scanline, <b><tt>w</tt></b> specifies the
|
|
|
2119 |
width of the scanline, i.e. the number of pixels to be painted to the right from
|
|
|
2120 |
the starting pixel, including the starting pixel.
|
|
|
2121 |
<dd>
|
|
|
2122 |
<b><tt>c0</tt></b> specifies the color for the starting pixel
|
|
|
2123 |
as a vector of fraction values, each of which represents
|
|
|
2124 |
a color value in the interval <b><tt>[0,1]</tt></b>.
|
|
|
2125 |
<dd>
|
|
|
2126 |
<b><tt>c0_f</tt></b> specify a fraction part of the color for the starting pixel.
|
|
|
2127 |
See the formula below about using it.
|
|
|
2128 |
<dd>
|
|
|
2129 |
<b><tt>cg_num</tt></b> specify a numerator for the color gradient -
|
|
|
2130 |
a vector of values in <b><tt>[-1,1]</tt></b>, each of which correspond to a color component.
|
|
|
2131 |
<dd>
|
|
|
2132 |
<b><tt>cg_den</tt></b> specify the denominator for the color gradient -
|
|
|
2133 |
a value in <b><tt>[-1,1]</tt></b>.
|
|
|
2134 |
<dd><p>
|
|
|
2135 |
The color for the pixel <b><tt>[i + k, j]</tt></b> to be computed like this :
|
|
|
2136 |
<pre><b><tt>
|
|
|
2137 |
(double)(c0[n] + (c0_f[n] + cg_num[n] * k) / cg_den) / (1 ^ 31 - 1)
|
|
|
2138 |
</tt></b></pre>
|
|
|
2139 |
<dd>where <b><tt>0 <= k <= w </tt></b>, and <b><tt>n</tt></b> is a device color component index.
|
|
|
2140 |
|
|
|
2141 |
<dd>
|
|
|
2142 |
<b><em>Important note :</em></b> The <b><tt>fa</tt></b> argument may contain
|
|
|
2143 |
the <b><tt>swap_axes</tt></b> bit set. In this case the implementation must swap (transpose)
|
|
|
2144 |
<b><tt>X</tt></b> and <b><tt>Y</tt></b> axes.
|
|
|
2145 |
<dd>
|
|
|
2146 |
<b><em>Important note :</em></b> The implementation must not paint outside the
|
|
|
2147 |
clipping rectangle specified in the <b><tt>fa</tt></b> argument.
|
|
|
2148 |
If <b><tt>fa->swap_axes</tt></b> is true, the clipping rectangle is transposed.
|
|
|
2149 |
<dd>
|
|
|
2150 |
See <b><tt> gx_default_fill_linear_color_scanline</tt></b>
|
|
|
2151 |
in <b><tt>gdevdsha.c</tt></b> as a sample code.
|
|
|
2152 |
</dl>
|
|
|
2153 |
|
|
|
2154 |
|
|
|
2155 |
<h3><a name="High_level_drawing"></a>High-level drawing</h3>
|
|
|
2156 |
|
|
|
2157 |
<p>
|
|
|
2158 |
In addition to the lower-level drawing operations described above, the
|
|
|
2159 |
driver interface provides a set of high-level operations. Normally these
|
|
|
2160 |
will have their default implementation, which converts the high-level
|
|
|
2161 |
operation to the low-level ones just described; however, drivers that
|
|
|
2162 |
generate high-level output formats such as CGM, or communicate with devices
|
|
|
2163 |
that have firmware for higher-level operations such as polygon fills, may
|
|
|
2164 |
implement these high-level operations directly. For more details, please
|
|
|
2165 |
consult the source code, specifically:
|
|
|
2166 |
|
|
|
2167 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
2168 |
<tr valign=top> <th align=left>Header
|
|
|
2169 |
<td>
|
|
|
2170 |
<th align=left>Defines
|
|
|
2171 |
<tr valign=top> <td><a href="../src/gxpaint.h">gxpaint.h</a>
|
|
|
2172 |
<td>
|
|
|
2173 |
<td><b><tt>gx_fill_params</tt></b>, <b><tt>gx_stroke_params</tt></b>
|
|
|
2174 |
<tr valign=top> <td><a href="../src/gxfixed.h">gxfixed.h</a>
|
|
|
2175 |
<td>
|
|
|
2176 |
<td><b><tt>fixed</tt></b>, <b><tt>gs_fixed_point</tt></b> (used by
|
|
|
2177 |
<b><tt>gx_*_params</tt></b>)
|
|
|
2178 |
<tr valign=top> <td><a href="../src/gxistate.h">gxistate.h</a>
|
|
|
2179 |
<td>
|
|
|
2180 |
<td><b><tt>gs_imager_state</tt></b> (used by <b><tt>gx_*_params</tt></b>)
|
|
|
2181 |
<tr valign=top> <td><a href="../src/gxline.h">gxline.h</a>
|
|
|
2182 |
<td>
|
|
|
2183 |
<td><b><tt>gx_line_params</tt></b> (used by <b><tt>gs_imager_state</tt></b>)
|
|
|
2184 |
<tr valign=top> <td><a href="../src/gslparam.h">gslparam.h</a>
|
|
|
2185 |
<td>
|
|
|
2186 |
<td>line cap/join values (used by <b><tt>gx_line_params</tt></b>)
|
|
|
2187 |
<tr valign=top> <td><a href="../src/gxmatrix.h">gxmatrix.h</a>
|
|
|
2188 |
<td>
|
|
|
2189 |
<td><b><tt>gs_matrix_fixed</tt></b> (used by <b><tt>gs_imager_state</tt></b>)
|
|
|
2190 |
<tr valign=top> <td><a href="../src/gspath.h">gspath.h</a>, <a href="../src/gxpath.h">gxpath.h</a>, <a href="../src/gzpath.h">gzpath.h</a>
|
|
|
2191 |
<td>
|
|
|
2192 |
<td><b><tt>gx_path</tt></b>
|
|
|
2193 |
<tr valign=top> <td><a href="../src/gxcpath.h">gxcpath.h</a>, <a href="../src/gzcpath.h">gzcpath.h</a>
|
|
|
2194 |
<td>
|
|
|
2195 |
<td><b><tt>gx_clip_path</tt></b>
|
|
|
2196 |
</table></blockquote>
|
|
|
2197 |
|
|
|
2198 |
<p>
|
|
|
2199 |
For a minimal example of how to implement the high-level drawing operations,
|
|
|
2200 |
see <a href="../src/gdevtrac.c">gdevtrac.c</a>.
|
|
|
2201 |
|
|
|
2202 |
<h4><a name="Paths"></a>Paths</h4>
|
|
|
2203 |
|
|
|
2204 |
<dl>
|
|
|
2205 |
<dt><b><tt>int (*fill_path)(gx_device *dev,
|
|
|
2206 |
const gs_imager_state *pis, gx_path *ppath,
|
|
|
2207 |
const gx_fill_params *params,
|
|
|
2208 |
const gx_drawing_color *pdcolor,
|
|
|
2209 |
const gx_clip_path *pcpath)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2210 |
<dd>Fill the given path, clipped by the given clip path, according to the
|
|
|
2211 |
given parameters, with the given color. The clip path pointer may be
|
|
|
2212 |
<b><tt>NULL</tt></b>, meaning do not clip.
|
|
|
2213 |
<dd>
|
|
|
2214 |
The implementation must paint the path with the specified device color,
|
|
|
2215 |
which may be either a pure color, or a pattern. If the device can't
|
|
|
2216 |
handle non-pure colors, it should check the color type and
|
|
|
2217 |
call the default implementation gx_default_fill_path for cases,
|
|
|
2218 |
which the device can't handle. The default implementation will perform
|
|
|
2219 |
a subdivision of the area to be painted, and will
|
|
|
2220 |
call other device virtual functions (such as fill_linear_color_triangle)
|
|
|
2221 |
with simpler areas.
|
|
|
2222 |
|
|
|
2223 |
</dl>
|
|
|
2224 |
|
|
|
2225 |
<dl>
|
|
|
2226 |
<dt><b><tt>int (*stroke_path)(gx_device *dev,
|
|
|
2227 |
const gs_imager_state *pis, gx_path *ppath,
|
|
|
2228 |
const gx_stroke_params *params,
|
|
|
2229 |
const gx_drawing_color *pdcolor,
|
|
|
2230 |
const gx_clip_path *pcpath)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2231 |
<dd>Stroke the given path, clipped by the given clip path, according to the
|
|
|
2232 |
given parameters, with the given color. The clip path pointer may be
|
|
|
2233 |
<b><tt>NULL</tt></b>, meaning not to clip.
|
|
|
2234 |
</dl>
|
|
|
2235 |
|
|
|
2236 |
<dl>
|
|
|
2237 |
<dt><b><tt>int (*fill_mask)(gx_device *dev,
|
|
|
2238 |
const byte *data, int data_x, int raster,
|
|
|
2239 |
gx_bitmap_id id, int x, int y, int width,
|
|
|
2240 |
int height, const gx_drawing_color *pdcolor, int depth,
|
|
|
2241 |
int command, const gx_clip_path *pcpath)</tt></b>
|
|
|
2242 |
<b><em>[OPTIONAL]</em></b>
|
|
|
2243 |
<dd>Color the 1-bits in the given mask (or according to the alpha values,
|
|
|
2244 |
if <b><tt>depth</tt></b> > 1), clipped by the given clip path,
|
|
|
2245 |
with the given color and logical operation. The clip path pointer may be
|
|
|
2246 |
<b><tt>NULL</tt></b>, meaning do not clip. The parameters
|
|
|
2247 |
<b><tt>data</tt></b>, ..., <b><tt>height</tt></b> are as for
|
|
|
2248 |
<b><tt>copy_mono</tt></b>; depth is as for <b><tt>copy_alpha</tt></b>;
|
|
|
2249 |
command is as for <b><tt>copy_rop</tt></b>.
|
|
|
2250 |
</dl>
|
|
|
2251 |
|
|
|
2252 |
<h4><a name="Images"></a>Images</h4>
|
|
|
2253 |
|
|
|
2254 |
<p>
|
|
|
2255 |
Similar to the high-level interface for fill and stroke graphics, a high-level
|
|
|
2256 |
interface exists for bitmap images. The procedures in this part of the
|
|
|
2257 |
interface are optional.
|
|
|
2258 |
|
|
|
2259 |
<p>
|
|
|
2260 |
Bitmap images come in a variety of types, corresponding closely (but not
|
|
|
2261 |
precisely) to the PostScript ImageTypes. The generic or common part of all
|
|
|
2262 |
bitmap images is defined by:
|
|
|
2263 |
|
|
|
2264 |
<blockquote>
|
|
|
2265 |
<pre>typedef struct {
|
|
|
2266 |
const gx_image_type_t *type;
|
|
|
2267 |
gs_matrix ImageMatrix;
|
|
|
2268 |
} gs_image_common_t;</pre>
|
|
|
2269 |
</blockquote>
|
|
|
2270 |
|
|
|
2271 |
<p>
|
|
|
2272 |
Bitmap images that supply data (all image types except
|
|
|
2273 |
<b><tt>image_type_from_device</tt></b> (2)) are defined by:
|
|
|
2274 |
|
|
|
2275 |
<blockquote>
|
|
|
2276 |
<pre>#define gs_image_max_components 5
|
|
|
2277 |
typedef struct {
|
|
|
2278 |
<< gs_image_common_t >>
|
|
|
2279 |
int Width;
|
|
|
2280 |
int Height;
|
|
|
2281 |
int BitsPerComponent;
|
|
|
2282 |
float Decode[gs_image_max_components * 2];
|
|
|
2283 |
bool Interpolate;
|
|
|
2284 |
} gs_data_image_t;</pre>
|
|
|
2285 |
</blockquote>
|
|
|
2286 |
|
|
|
2287 |
<p>
|
|
|
2288 |
Images that supply pixel (as opposed to mask) data are defined by:
|
|
|
2289 |
|
|
|
2290 |
<blockquote>
|
|
|
2291 |
<pre>typedef enum {
|
|
|
2292 |
/* Single plane, chunky pixels. */
|
|
|
2293 |
gs_image_format_chunky = 0,
|
|
|
2294 |
/* num_components planes, chunky components. */
|
|
|
2295 |
gs_image_format_component_planar = 1,
|
|
|
2296 |
/* BitsPerComponent * num_components planes, 1 bit per plane */
|
|
|
2297 |
gs_image_format_bit_planar = 2
|
|
|
2298 |
} gs_image_format_t;
|
|
|
2299 |
typedef struct {
|
|
|
2300 |
<< gs_data_image_t >>
|
|
|
2301 |
const gs_color_space *ColorSpace;
|
|
|
2302 |
bool CombineWithColor;
|
|
|
2303 |
} gs_pixel_image_t;</pre>
|
|
|
2304 |
</blockquote>
|
|
|
2305 |
|
|
|
2306 |
<p>
|
|
|
2307 |
Ordinary PostScript Level 1 or Level 2 (<b><tt>ImageType</tt></b> 1) images
|
|
|
2308 |
are defined by:
|
|
|
2309 |
|
|
|
2310 |
<blockquote>
|
|
|
2311 |
<pre>typedef enum {
|
|
|
2312 |
/* No alpha. */
|
|
|
2313 |
gs_image_alpha_none = 0,
|
|
|
2314 |
/* Alpha precedes color components. */
|
|
|
2315 |
gs_image_alpha_first,
|
|
|
2316 |
/* Alpha follows color components. */
|
|
|
2317 |
gs_image_alpha_last
|
|
|
2318 |
} gs_image_alpha_t;
|
|
|
2319 |
typedef struct {
|
|
|
2320 |
<< gs_pixel_image_t >>
|
|
|
2321 |
bool ImageMask;
|
|
|
2322 |
bool adjust;
|
|
|
2323 |
gs_image_alpha_t Alpha;
|
|
|
2324 |
} gs_image1_t;
|
|
|
2325 |
typedef gs_image1_t gs_image_t;</pre>
|
|
|
2326 |
</blockquote>
|
|
|
2327 |
|
|
|
2328 |
<p>
|
|
|
2329 |
Of course, standard PostScript images don't have an alpha component. For
|
|
|
2330 |
more details, consult the source code in <a
|
|
|
2331 |
href="../src/gsiparam.h">gsiparam.h</a> and <b><tt>gsiparm*.h</tt></b>,
|
|
|
2332 |
which define parameters for an image.
|
|
|
2333 |
|
|
|
2334 |
<p>
|
|
|
2335 |
The <b><tt>begin[_typed_]image</tt></b> driver procedures create image
|
|
|
2336 |
enumeration structures. The common part of these structures consists of:
|
|
|
2337 |
|
|
|
2338 |
<blockquote>
|
|
|
2339 |
<pre>typedef struct gx_image_enum_common_s {
|
|
|
2340 |
const gx_image_type_t *image_type;
|
|
|
2341 |
const gx_image_enum_procs_t *procs;
|
|
|
2342 |
gx_device *dev;
|
|
|
2343 |
gs_id id;
|
|
|
2344 |
int num_planes;
|
|
|
2345 |
int plane_depths[gs_image_max_planes]; /* [num_planes] */
|
|
|
2346 |
int plane_widths[gs_image_max_planes] /* [num_planes] */
|
|
|
2347 |
} gx_image_enum_common_t;</pre>
|
|
|
2348 |
</blockquote>
|
|
|
2349 |
|
|
|
2350 |
<p>
|
|
|
2351 |
where <b><tt>procs</tt></b> consists of:
|
|
|
2352 |
|
|
|
2353 |
<blockquote>
|
|
|
2354 |
<pre>typedef struct gx_image_enum_procs_s {
|
|
|
2355 |
|
|
|
2356 |
/*
|
|
|
2357 |
* Pass the next batch of data for processing.
|
|
|
2358 |
*/
|
|
|
2359 |
#define image_enum_proc_plane_data(proc)\
|
|
|
2360 |
int proc(gx_device *dev,\
|
|
|
2361 |
gx_image_enum_common_t *info, const gx_image_plane_t *planes,\
|
|
|
2362 |
int height)
|
|
|
2363 |
|
|
|
2364 |
image_enum_proc_plane_data((*plane_data));
|
|
|
2365 |
|
|
|
2366 |
/*
|
|
|
2367 |
* End processing an image, freeing the enumerator.
|
|
|
2368 |
*/
|
|
|
2369 |
#define image_enum_proc_end_image(proc)\
|
|
|
2370 |
int proc(gx_device *dev,\
|
|
|
2371 |
gx_image_enum_common_t *info, bool draw_last)
|
|
|
2372 |
|
|
|
2373 |
image_enum_proc_end_image((*end_image));
|
|
|
2374 |
|
|
|
2375 |
/*
|
|
|
2376 |
* Flush any intermediate buffers to the target device.
|
|
|
2377 |
* We need this for situations where two images interact
|
|
|
2378 |
* (currently, only the mask and the data of ImageType 3).
|
|
|
2379 |
* This procedure is optional (may be 0).
|
|
|
2380 |
*/
|
|
|
2381 |
#define image_enum_proc_flush(proc)\
|
|
|
2382 |
int proc(gx_image_enum_common_t *info)
|
|
|
2383 |
|
|
|
2384 |
image_enum_proc_flush((*flush));
|
|
|
2385 |
|
|
|
2386 |
} gx_image_enum_procs_t;</pre>
|
|
|
2387 |
</blockquote>
|
|
|
2388 |
|
|
|
2389 |
<p> In other words, <b><tt>begin[_typed]_image</tt></b> sets up an
|
|
|
2390 |
enumeration structure that contains the procedures that will process the
|
|
|
2391 |
image data, together with all variables needed to maintain the state of the
|
|
|
2392 |
process. Since this is somewhat tricky to get right, if you plan to create
|
|
|
2393 |
one of your own you should probably read an existing implementation of
|
|
|
2394 |
<b><tt>begin[_typed]_image</tt></b>, such as the one in <a
|
|
|
2395 |
href="../src/gdevbbox.c">gdevbbox.c</a> or <a
|
|
|
2396 |
href="../src/gdevps.c">gdevps.c</a>.
|
|
|
2397 |
|
|
|
2398 |
<p>
|
|
|
2399 |
The data passed at each call of <b><tt>image_plane_data</tt></b> consists of
|
|
|
2400 |
one or more planes, as appropriate for the type of image.
|
|
|
2401 |
<b><tt>begin[_typed]_image</tt></b> must initialize the
|
|
|
2402 |
<b><tt>plane_depths</tt></b> array in the enumeration structure with the
|
|
|
2403 |
depths (bits per element) of the planes. The array of
|
|
|
2404 |
<b><tt>gx_image_plane_t</tt></b> structures passed to each call of
|
|
|
2405 |
<b><tt>image_plane_data</tt></b> then defines where the data are stored, as
|
|
|
2406 |
follows:
|
|
|
2407 |
|
|
|
2408 |
<blockquote>
|
|
|
2409 |
<pre>typedef struct gx_image_plane_s {
|
|
|
2410 |
const byte *data;
|
|
|
2411 |
int data_x;
|
|
|
2412 |
uint raster;
|
|
|
2413 |
} gx_image_plane_t;</pre>
|
|
|
2414 |
</blockquote>
|
|
|
2415 |
|
|
|
2416 |
<dl>
|
|
|
2417 |
<dt><b><tt>int (*begin_image)(gx_device *dev,
|
|
|
2418 |
const gs_imager_state *pis, const gs_image_t *pim,
|
|
|
2419 |
gs_image_format_t format, gs_int_rect *prect,
|
|
|
2420 |
const gx_drawing_color *pdcolor,
|
|
|
2421 |
const gx_clip_path *pcpath, gs_memory_t *memory,
|
|
|
2422 |
gx_image_enum_common_t **pinfo)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2423 |
<dd>Begin the transmission of an image. Zero or more calls of
|
|
|
2424 |
<b><tt>image_plane_data</tt></b> will follow, and then a call of
|
|
|
2425 |
<b><tt>end_image</tt></b>. The parameters of <b><tt>begin_image</tt></b>
|
|
|
2426 |
are as follows:
|
|
|
2427 |
|
|
|
2428 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
2429 |
<tr valign=top> <td><b><tt>pis</tt></b>
|
|
|
2430 |
<td>
|
|
|
2431 |
<td>pointer to an imager state. The only relevant elements of the
|
|
|
2432 |
imager state are the CTM (coordinate transformation matrix),
|
|
|
2433 |
the logical operation (<b><tt>RasterOp</tt></b> or
|
|
|
2434 |
transparency), and the color rendering information.
|
|
|
2435 |
<tr valign=top> <td><b><tt>pim</tt></b>
|
|
|
2436 |
<td>
|
|
|
2437 |
<td>pointer to the <b><tt>gs_image_t</tt></b> structure that
|
|
|
2438 |
defines the image parameters
|
|
|
2439 |
<tr valign=top> <td><b><tt>format</tt></b>
|
|
|
2440 |
<td>
|
|
|
2441 |
<td>defines how pixels are represented for
|
|
|
2442 |
<b><tt>image_plane_data</tt></b>. See the description of
|
|
|
2443 |
<b><tt>image_plane_data</tt></b> below
|
|
|
2444 |
<tr valign=top> <td><b><tt>prect</tt></b>
|
|
|
2445 |
<td>
|
|
|
2446 |
<td>if not <b><tt>NULL</tt></b>, defines a subrectangle of the
|
|
|
2447 |
image; only the data for this subrectangle will be passed to
|
|
|
2448 |
<b><tt>image_plane_data</tt></b>, and only this subrectangle should
|
|
|
2449 |
be drawn
|
|
|
2450 |
<tr valign=top> <td><b><tt>pdcolor</tt></b>
|
|
|
2451 |
<td>
|
|
|
2452 |
<td>defines a drawing color, only needed for masks or if
|
|
|
2453 |
<b><tt>CombineWithColor</tt></b> is true
|
|
|
2454 |
<tr valign=top> <td><b><tt>pcpath</tt></b>
|
|
|
2455 |
<td>
|
|
|
2456 |
<td>if not <b><tt>NULL</tt></b>, defines an optional clipping path
|
|
|
2457 |
<tr valign=top> <td><b><tt>memory</tt></b>
|
|
|
2458 |
<td>
|
|
|
2459 |
<td>defines the allocator to be used for allocating bookkeeping
|
|
|
2460 |
information
|
|
|
2461 |
<tr valign=top> <td><b><tt>pinfo</tt></b>
|
|
|
2462 |
<td>
|
|
|
2463 |
<td>the implementation should return a pointer to its state
|
|
|
2464 |
structure here
|
|
|
2465 |
</table></blockquote>
|
|
|
2466 |
|
|
|
2467 |
<p>
|
|
|
2468 |
<b><tt>begin_image</tt></b> is expected to allocate a structure for its
|
|
|
2469 |
bookkeeping needs, using the allocator defined by the memory parameter, and
|
|
|
2470 |
return it in <b><tt>*pinfo</tt></b>. <b><tt>begin_image</tt></b> should not assume that
|
|
|
2471 |
the structures in <b><tt>*pim</tt></b>, <b><tt>*prect</tt></b>, or
|
|
|
2472 |
<b><tt>*pdcolor</tt></b> will survive the call on
|
|
|
2473 |
<b><tt>begin_image</tt></b> (except for the color space in
|
|
|
2474 |
<b><tt>*pim->ColorSpace</tt></b>): it should copy any necessary parts of
|
|
|
2475 |
them into its own bookkeeping structure. It may, however, assume that
|
|
|
2476 |
<b><tt>*pis</tt></b>, <b><tt>*pcpath</tt></b>, and of course
|
|
|
2477 |
<b><tt>*memory</tt></b> will live at least until <b><tt>end_image</tt></b>
|
|
|
2478 |
is called.
|
|
|
2479 |
|
|
|
2480 |
<p>
|
|
|
2481 |
<b><tt>begin_image</tt></b> returns 0 normally, or 1 if the image does not
|
|
|
2482 |
need any data. In the latter case, <b><tt>begin_image</tt></b> does not
|
|
|
2483 |
allocate an enumeration structure.
|
|
|
2484 |
</dl>
|
|
|
2485 |
|
|
|
2486 |
<dl>
|
|
|
2487 |
<dt><b><tt>int (*begin_typed_image)(gx_device *dev,
|
|
|
2488 |
const gs_imager_state *pis, const gs_matrix *pmat,
|
|
|
2489 |
const gs_image_common_t *pim, gs_int_rect *prect,
|
|
|
2490 |
const gx_drawing_color *pdcolor,
|
|
|
2491 |
const gx_clip_path *pcpath, gs_memory_t *memory,
|
|
|
2492 |
gx_image_enum_common_t **pinfo)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2493 |
<dd>This has the same function as <b><tt>begin_image</tt></b>, except
|
|
|
2494 |
<ul>
|
|
|
2495 |
<li>The image may be of any <b><tt>ImageType</tt></b>, not only
|
|
|
2496 |
<b><tt>image_type_simple</tt></b> (1);
|
|
|
2497 |
|
|
|
2498 |
<li>The image format is included in the image structure, not supplied as a
|
|
|
2499 |
separate argument;
|
|
|
2500 |
|
|
|
2501 |
<li>The optional <b><tt>pmat</tt></b> argument provides a matrix that
|
|
|
2502 |
substitutes for the one in the imager state;
|
|
|
2503 |
|
|
|
2504 |
<li>For mask images, if <b><tt>pmat</tt></b> is not <b><tt>NULL</tt></b>
|
|
|
2505 |
and the color is pure, <b><tt>pis</tt></b> may be <b><tt>NULL</tt></b>.
|
|
|
2506 |
</ul>
|
|
|
2507 |
</dl>
|
|
|
2508 |
|
|
|
2509 |
<p>
|
|
|
2510 |
The actual transmission of data uses the procedures in the enumeration
|
|
|
2511 |
structure, not driver procedures, since the handling of the data usually
|
|
|
2512 |
depends on the image type and parameters rather than the device. These
|
|
|
2513 |
procedures are specified as follows.
|
|
|
2514 |
|
|
|
2515 |
<dl>
|
|
|
2516 |
<dt><b><tt>int (*image_plane_data)(gx_device *dev,
|
|
|
2517 |
gx_image_enum_common_t *info,
|
|
|
2518 |
const gx_image_plane_t *planes, int height)</tt></b>
|
|
|
2519 |
<dd>This call provides more of the image source data: specifically,
|
|
|
2520 |
<b><tt>height</tt></b> rows, with <b><tt>Width</tt></b> pixels supplied for
|
|
|
2521 |
each row.
|
|
|
2522 |
|
|
|
2523 |
<p>
|
|
|
2524 |
The data for each row are packed big-endian within each byte, as for
|
|
|
2525 |
<b><tt>copy_color</tt></b>. The <b><tt>data_x</tt></b> (starting X position
|
|
|
2526 |
within the row) and <b><tt>raster</tt></b> (number of bytes per row) are
|
|
|
2527 |
specified separately for each plane, and may include some padding at the
|
|
|
2528 |
beginning or end of each row. Note that for non-mask images, the input data
|
|
|
2529 |
may be in any color space and may have any number of bits per component (1,
|
|
|
2530 |
2, 4, 8, 12); currently mask images always have 1 bit per component, but in
|
|
|
2531 |
the future, they might allow multiple bits of alpha. Note also that each
|
|
|
2532 |
call of <b><tt>image_plane_data</tt></b> passes complete pixels: for example, for
|
|
|
2533 |
a chunky image with 24 bits per pixel, each call of
|
|
|
2534 |
<b><tt>image_plane_data</tt></b> passes 3N bytes of data (specifically,
|
|
|
2535 |
3 × Width × height).
|
|
|
2536 |
|
|
|
2537 |
<p>
|
|
|
2538 |
The interpretation of planes depends on the <b><tt>format</tt></b> member of
|
|
|
2539 |
the <b><tt>gs_image[_common]_t</tt></b> structure:
|
|
|
2540 |
|
|
|
2541 |
<ul>
|
|
|
2542 |
<li>If the format is <b><tt>gs_image_format_chunky</tt></b>,
|
|
|
2543 |
<b><tt>planes[0].data</tt></b> points to data in "chunky" format, in which
|
|
|
2544 |
the components follow each other (for instance, RGBRGBRGB....)
|
|
|
2545 |
|
|
|
2546 |
<li>If the format is <b><tt>gs_image_format_component_planar</tt></b>,
|
|
|
2547 |
<b><tt>planes[0 .. N-1].data</tt></b> point to data for the
|
|
|
2548 |
<b><em>N</em></b> components (for example, <b><em>N</em></b>=3 for RGB
|
|
|
2549 |
data); each plane contains samples for a single component, for instance,
|
|
|
2550 |
RR..., GG..., BB.... Note that the planes are divided by component, not by
|
|
|
2551 |
bit: for example, for 24-bit RGB data, <b><em>N</em></b>=3, with 8-bit
|
|
|
2552 |
values in each plane of data.
|
|
|
2553 |
|
|
|
2554 |
<li>If the format is <b><tt>gs_image_format_bit_planar</tt></b>,
|
|
|
2555 |
<b><tt>planes[0 .. N*B-1].data</tt></b> point to data for the
|
|
|
2556 |
<b><em>N</em></b> components of <b><em>B</em></b> bits each (for example,
|
|
|
2557 |
<b><em>N</em></b>=3 and <b><em>B</em></b>=4 for RGB data with 4 bits per
|
|
|
2558 |
component); each plane contains samples for a single bit, for instance, R0
|
|
|
2559 |
R1 R2 R3 G0 G1 G2 G3 B0 B1 B2 B3. Note that the most significant bit of
|
|
|
2560 |
each plane comes first.
|
|
|
2561 |
</ul>
|
|
|
2562 |
|
|
|
2563 |
<p>
|
|
|
2564 |
If, as a result of this call, <b><tt>image_plane_data</tt></b> has been called with all
|
|
|
2565 |
the data for the (sub-)image, it returns 1; otherwise, it returns 0 or an
|
|
|
2566 |
error code as usual.
|
|
|
2567 |
|
|
|
2568 |
<p>
|
|
|
2569 |
<b><tt>image_plane_data</tt></b>, unlike most other procedures that take bitmaps as
|
|
|
2570 |
arguments, does not require the data to be aligned in any way.
|
|
|
2571 |
|
|
|
2572 |
<p>
|
|
|
2573 |
Note that for some image types, different planes may have different
|
|
|
2574 |
numbers of bits per pixel, as defined in the <b><tt>plane_depths</tt></b> array.
|
|
|
2575 |
</dl>
|
|
|
2576 |
|
|
|
2577 |
<dl>
|
|
|
2578 |
<dt><b><tt>int (*end_image)(gx_device *dev, void *info,
|
|
|
2579 |
bool draw_last)</tt></b>
|
|
|
2580 |
<dd>Finish processing an image, either because all data have been supplied
|
|
|
2581 |
or because the caller has decided to abandon this image.
|
|
|
2582 |
<b><tt>end_image</tt></b> may be called at any time after
|
|
|
2583 |
<b><tt>begin_image</tt></b>. It should free the info structure and any
|
|
|
2584 |
subsidiary structures. If <b><tt>draw_last</tt></b> is true, it should
|
|
|
2585 |
finish drawing any buffered lines of the image.
|
|
|
2586 |
</dl>
|
|
|
2587 |
|
|
|
2588 |
<h5><a name="Images_notes"></a>Notes</h5>
|
|
|
2589 |
|
|
|
2590 |
<p>
|
|
|
2591 |
While there will almost never be more than one image enumeration in
|
|
|
2592 |
progress -- that is, after a <b><tt>begin_image</tt></b>,
|
|
|
2593 |
<b><tt>end_image</tt></b> will almost always be called before the next
|
|
|
2594 |
<b><tt>begin_image</tt></b> -- driver code should not rely on this
|
|
|
2595 |
property; in particular, it should store all information regarding the
|
|
|
2596 |
image in the info structure, not in the driver structure.
|
|
|
2597 |
|
|
|
2598 |
<p>
|
|
|
2599 |
Note that if <b><tt>begin_[typed_]image</tt></b> saves its parameters in
|
|
|
2600 |
the info structure, it can decide on each call whether to use its own
|
|
|
2601 |
algorithms or to use the default implementation. (It may need to call
|
|
|
2602 |
<b><tt>gx_default_begin</tt></b>/<b><tt>end_image</tt></b> partway
|
|
|
2603 |
through.) [A later revision of this document may include an example here.]
|
|
|
2604 |
|
|
|
2605 |
<h4><a name="Text"></a>Text</h4>
|
|
|
2606 |
|
|
|
2607 |
<p>
|
|
|
2608 |
The third high-level interface handles text. As for images, the interface
|
|
|
2609 |
is based on creating an enumerator which then may execute the operation in
|
|
|
2610 |
multiple steps. As for the other high-level interfaces, the procedures are
|
|
|
2611 |
optional.
|
|
|
2612 |
|
|
|
2613 |
<dl>
|
|
|
2614 |
<dt><b><tt>int (*text_begin)(gx_device *dev,
|
|
|
2615 |
gs_imager_state *pis, const gs_text_params_t *text,
|
|
|
2616 |
gs_font *font, gx_path *path,
|
|
|
2617 |
const gx_device_color *pdcolor,
|
|
|
2618 |
const gx_clip_path *pcpath, gs_memory_t *memory,
|
|
|
2619 |
gs_text_enum_t **ppte)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2620 |
|
|
|
2621 |
<dd>
|
|
|
2622 |
Begin processing text, by creating a state structure and storing it in
|
|
|
2623 |
<b><tt>*ppte</tt></b>. The parameters of <b><tt>text_begin</tt></b> are as
|
|
|
2624 |
follows:
|
|
|
2625 |
</dl>
|
|
|
2626 |
|
|
|
2627 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
2628 |
<tr valign=top> <td><b><tt>dev</tt></b>
|
|
|
2629 |
<td>
|
|
|
2630 |
<td>The usual pointer to the device.
|
|
|
2631 |
<tr valign=top> <td><b><tt>pis</tt></b>
|
|
|
2632 |
<td>
|
|
|
2633 |
<td>A pointer to an imager state. All elements may be relevant,
|
|
|
2634 |
depending on how the text is rendered.
|
|
|
2635 |
<tr valign=top> <td><b><tt>text</tt></b>
|
|
|
2636 |
<td>
|
|
|
2637 |
<td>A pointer to the structure that defines the text operation
|
|
|
2638 |
and parameters. See <a href="../src/gstext.h">gstext.h</a> for details.
|
|
|
2639 |
<tr valign=top> <td><b><tt>font</tt></b>
|
|
|
2640 |
<td>
|
|
|
2641 |
<td>Defines the font for drawing.
|
|
|
2642 |
<tr valign=top> <td><b><tt>path</tt></b>
|
|
|
2643 |
<td>
|
|
|
2644 |
<td>Defines the path where the character outline will be appended
|
|
|
2645 |
(if the text operation includes <b><tt>TEXT_DO_...PATH</tt></b>),
|
|
|
2646 |
and whose current point indicates where drawing should occur
|
|
|
2647 |
and will be updated by the string width (unless the text
|
|
|
2648 |
operation includes <b><tt>TEXT_DO_NONE</tt></b>).
|
|
|
2649 |
<tr valign=top> <td><b><tt>pdcolor</tt></b>
|
|
|
2650 |
<td>
|
|
|
2651 |
<td>Defines the drawing color for the text. Only relevant if
|
|
|
2652 |
the text operation includes <b><tt>TEXT_DO_DRAW</tt></b>.
|
|
|
2653 |
<tr valign=top> <td><b><tt>pcpath</tt></b>
|
|
|
2654 |
<td>
|
|
|
2655 |
<td>If not <b><tt>NULL</tt></b>, defines an optional clipping path.
|
|
|
2656 |
Only relevant if the text operation includes
|
|
|
2657 |
<b><tt>TEXT_DO_DRAW</tt></b>.
|
|
|
2658 |
<tr valign=top> <td><b><tt>memory</tt></b>
|
|
|
2659 |
<td>
|
|
|
2660 |
<td>Defines the allocator to be used for allocating bookkeeping
|
|
|
2661 |
information.
|
|
|
2662 |
<tr valign=top> <td><b><tt>ppte</tt></b>
|
|
|
2663 |
<td>
|
|
|
2664 |
<td>The implementation should return a pointer to its state
|
|
|
2665 |
structure here.
|
|
|
2666 |
</table></blockquote>
|
|
|
2667 |
|
|
|
2668 |
<p>
|
|
|
2669 |
<b><tt>text_begin</tt></b> must allocate a structure for its bookkeeping
|
|
|
2670 |
needs, using the allocator defined by the <b><tt>memory</tt></b> parameter,
|
|
|
2671 |
and return it in <b><tt>*ppte</tt></b>. <b><tt>text_begin</tt></b> may
|
|
|
2672 |
assume that the structures passed as parameters will survive until text
|
|
|
2673 |
processing is complete.
|
|
|
2674 |
|
|
|
2675 |
<p>
|
|
|
2676 |
Clients should not call the driver <b><tt>text_begin</tt></b> procedure
|
|
|
2677 |
directly. Instead, they should call <b><tt>gx_device_text_begin</tt></b>,
|
|
|
2678 |
which takes the same parameters and also initializes certain common elements
|
|
|
2679 |
of the text enumeration structure, or <b><tt>gs_text_begin</tt></b>, which
|
|
|
2680 |
takes many of the parameters from a graphics state structure. For details,
|
|
|
2681 |
see <a href="../src/gstext.h">gstext.h</a>.
|
|
|
2682 |
|
|
|
2683 |
<p>
|
|
|
2684 |
The actual processing of text uses the procedures in the enumeration
|
|
|
2685 |
structure, not driver procedures, since the handling of the text may depend
|
|
|
2686 |
on the font and parameters rather than the device. Text processing may also
|
|
|
2687 |
require the client to take action between characters, either because the
|
|
|
2688 |
client requested it (<b><tt>TEXT_INTERVENE</tt></b> in the operation) or
|
|
|
2689 |
because rendering a character requires suspending text processing to call an
|
|
|
2690 |
external package such as the PostScript interpreter. (It is a deliberate
|
|
|
2691 |
design decision to handle this by returning to the client, rather than
|
|
|
2692 |
calling out of the text renderer, in order to avoid potentially unknown
|
|
|
2693 |
stack requirements.) Specifically, the client must call the following
|
|
|
2694 |
procedures, which in turn call the procedures in the text enumerator.
|
|
|
2695 |
|
|
|
2696 |
<dl>
|
|
|
2697 |
<dt><b><tt>int gs_text_process(gs_text_enum_t *pte)</tt></b>
|
|
|
2698 |
<dd>Continue processing text. This procedure may return 0 or a negative
|
|
|
2699 |
error code as usual, or one of the following values (see
|
|
|
2700 |
<a href="../src/gstext.h">gstext.h</a> for details).
|
|
|
2701 |
|
|
|
2702 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
2703 |
<tr valign=top> <td><b><tt>TEXT_PROCESS_RENDER</tt></b>
|
|
|
2704 |
<td>The client must cause the current character to be rendered.
|
|
|
2705 |
This currently only is used for PostScript Type 0-4 fonts
|
|
|
2706 |
and their CID-keyed relatives.
|
|
|
2707 |
<tr valign=top> <td><b><tt>TEXT_PROCESS_INTERVENE</tt></b>
|
|
|
2708 |
<td>The client has asked to intervene between characters.
|
|
|
2709 |
This is used for <b><tt>cshow</tt></b> and <b><tt>kshow</tt></b>.
|
|
|
2710 |
</table></blockquote>
|
|
|
2711 |
</dl>
|
|
|
2712 |
|
|
|
2713 |
<dl>
|
|
|
2714 |
<dt><b><tt>int gs_text_release(gs_text_enum_t *pte,
|
|
|
2715 |
client_name_t cname)</tt></b> <dd>Finish processing text and release
|
|
|
2716 |
all associated structures. Clients must call this procedure after
|
|
|
2717 |
<b><tt>gs_text_process</tt></b> returns 0 or an error, and may call it at
|
|
|
2718 |
any time.
|
|
|
2719 |
</dl>
|
|
|
2720 |
|
|
|
2721 |
<p>
|
|
|
2722 |
There are numerous other procedures that clients may call during text
|
|
|
2723 |
processing. See <a href="../src/gstext.h">gstext.h</a> for details.
|
|
|
2724 |
|
|
|
2725 |
<h5><a name="Text_notes"></a>Notes</h5>
|
|
|
2726 |
|
|
|
2727 |
<p>
|
|
|
2728 |
Note that unlike many other optional procedures, the default implementation
|
|
|
2729 |
of <b><tt>text_begin</tt></b> cannot simply return: like the default
|
|
|
2730 |
implementation of <b><tt>begin[_typed]_image</tt></b>, it must create and
|
|
|
2731 |
return an enumerator. Furthermore, the implementation of the
|
|
|
2732 |
<b><tt>process</tt></b> procedure (in the enumerator structure, called by
|
|
|
2733 |
<b><tt>gs_text_process</tt></b>) cannot simply return without doing
|
|
|
2734 |
anything, even if it doesn't want to draw anything on the output. See the
|
|
|
2735 |
comments in <a href="../src/gxtext.h">gxtext.h</a> for details.
|
|
|
2736 |
|
|
|
2737 |
<h4><a name="Unicode"></a>Unicode support for high level devices</h4>
|
|
|
2738 |
|
|
|
2739 |
<p>
|
|
|
2740 |
<p>Implementing a new high level device, one may need to translate <b><tt>Postscript</tt></b>
|
|
|
2741 |
character codes into <b><tt>Unicode</tt></b>. This can be done pretty simply.
|
|
|
2742 |
|
|
|
2743 |
<p>For translating a <b><tt>Postscript</tt></b> text you need to inplement the device
|
|
|
2744 |
virtual function <b><tt>text_begin</tt></b>. It should create a new instance of
|
|
|
2745 |
<b><tt>gs_text_enum_t</tt></b> in the heap (let its pointer be <b><tt>pte</tt></b>),
|
|
|
2746 |
and assign a special function to <b><tt>gs_text_enum_t::procs.process</tt></b>.
|
|
|
2747 |
The function will receive <b><tt>pte</tt></b>. It should take the top level font from
|
|
|
2748 |
<b><tt>pte->orig_font</tt></b>,
|
|
|
2749 |
and iterate with <b><tt>font->procs.next_char_glyph(pte, ..., &glyph)</tt></b>.
|
|
|
2750 |
The last argument receives a <b><tt>gs_glyph</tt></b> value, which encodes a
|
|
|
2751 |
<b><tt>Postscript</tt></b> character name or CID (and also stores it into
|
|
|
2752 |
<b><tt>pte->returned.current_glyph</tt></b>).
|
|
|
2753 |
Then obtain the current subfont with <b><tt>gs_text_current_font(pte)</tt></b>
|
|
|
2754 |
(it can differ from the font)
|
|
|
2755 |
and call <b><tt>subfont->procs.decode_glyph(subfont, glyph)</tt></b>.
|
|
|
2756 |
The return value will be an <b><tt>Unicode</tt></b> code, or <b><tt>GS_NO_CHAR</tt></b>
|
|
|
2757 |
if the glyph can't be translated to Unicode.
|
|
|
2758 |
|
|
|
2759 |
<h3><a name="Reading_bits_back"></a>Reading bits back</h3>
|
|
|
2760 |
|
|
|
2761 |
<dl>
|
|
|
2762 |
<dt><b><tt>int (*get_bits_rectangle)(gx_device *dev,
|
|
|
2763 |
const gs_int_rect *prect, gs_get_bits_params_t *params,
|
|
|
2764 |
gs_int_rect **unread)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2765 |
|
|
|
2766 |
<dd>
|
|
|
2767 |
Read a rectangle of bits back from the device. The <b><tt>params</tt></b>
|
|
|
2768 |
structure consists of:
|
|
|
2769 |
|
|
|
2770 |
<table cellpadding=0 cellspacing=0>
|
|
|
2771 |
<tr valign=top> <td><b><tt>options</tt></b>
|
|
|
2772 |
<td>
|
|
|
2773 |
<td>the allowable formats for returning the data
|
|
|
2774 |
<tr valign=top> <td><b><tt>data[32]</tt></b>
|
|
|
2775 |
<td>
|
|
|
2776 |
<td>pointers to the returned data
|
|
|
2777 |
<tr valign=top> <td><b><tt>x_offset</tt></b>
|
|
|
2778 |
<td>
|
|
|
2779 |
<td>the X offset of the first returned pixel in data
|
|
|
2780 |
<tr valign=top> <td><b><tt>raster</tt></b>
|
|
|
2781 |
<td>
|
|
|
2782 |
<td>the distance between scan lines in the returned data
|
|
|
2783 |
</table>
|
|
|
2784 |
|
|
|
2785 |
<p>
|
|
|
2786 |
<b><tt>options</tt></b> is a bit mask specifying what formats the client is
|
|
|
2787 |
willing to accept. (If the client has more flexibility, the implementation
|
|
|
2788 |
may be able to return the data more efficiently, by avoiding representation
|
|
|
2789 |
conversions.) The options are divided into groups.
|
|
|
2790 |
|
|
|
2791 |
<blockquote><dl>
|
|
|
2792 |
<dt><b><em>alignment</em></b>
|
|
|
2793 |
<dd>Specifies whether the returned data must be aligned in the normal
|
|
|
2794 |
manner for bitmaps, or whether unaligned data are acceptable.
|
|
|
2795 |
|
|
|
2796 |
<dt><b><em>pointer or copy</em></b>
|
|
|
2797 |
<dd>Specifies whether the data may be copied into storage provided by the
|
|
|
2798 |
client and/or returned as pointers to existing storage. (Note that if
|
|
|
2799 |
copying is not allowed, it is much more likely that the implementation will
|
|
|
2800 |
return an error, since this requires that the client accept the data in the
|
|
|
2801 |
implementation's internal format.)
|
|
|
2802 |
|
|
|
2803 |
<dt><b><em>X offset</em></b>
|
|
|
2804 |
<dd>Specifies whether the returned data must have a specific X offset
|
|
|
2805 |
(usually zero, but possibly other values to avoid skew at some later stage
|
|
|
2806 |
of processing) or whether it may have any X offset (which may avoid skew in
|
|
|
2807 |
the <b><tt>get_bits_rectangle</tt></b> operation itself).
|
|
|
2808 |
|
|
|
2809 |
<dt><b><em>raster</em></b>
|
|
|
2810 |
<dd>Specifies whether the raster (distance between returned scan lines)
|
|
|
2811 |
must have its standard value, must have some other specific value, or may
|
|
|
2812 |
have any value. The standard value for the raster is the device width
|
|
|
2813 |
padded out to the alignment modulus when using pointers, or the minimum
|
|
|
2814 |
raster to accommodate the X offset + width when copying (padded out to the
|
|
|
2815 |
alignment modulus if standard alignment is required).
|
|
|
2816 |
|
|
|
2817 |
<dt><b><em>format</em></b>
|
|
|
2818 |
<dd>Specifies whether the data are returned in chunky (all components of a
|
|
|
2819 |
single pixel together), component-planar (each component has its own scan
|
|
|
2820 |
lines), or bit-planar (each bit has its own scan lines) format.
|
|
|
2821 |
|
|
|
2822 |
<dt><b><em>color space</em></b>
|
|
|
2823 |
<dd>Specifies whether the data are returned as native device pixels, or in
|
|
|
2824 |
a standard color space. Currently the only supported standard space is
|
|
|
2825 |
RGB.
|
|
|
2826 |
|
|
|
2827 |
<dt><b><em>standard component depth</em></b>
|
|
|
2828 |
<dd>Specifies the number of bits per component if the data are returned in
|
|
|
2829 |
the standard color space. (Native device pixels use
|
|
|
2830 |
<b><tt>dev</tt></b>-><b><tt>color_info.depth</tt></b> bits per pixel.)
|
|
|
2831 |
|
|
|
2832 |
<dt><b><em>alpha</em></b>
|
|
|
2833 |
<dd>Specifies whether alpha channel information should be returned as the
|
|
|
2834 |
first component, the last component, or not at all. Note that for devices
|
|
|
2835 |
that have no alpha capability, the returned alpha values will be all 1s.
|
|
|
2836 |
</dl></blockquote>
|
|
|
2837 |
|
|
|
2838 |
<p>
|
|
|
2839 |
The client may set more than one option in each of the above groups; the
|
|
|
2840 |
implementation will choose one of the selected options in each group to
|
|
|
2841 |
determine the actual form of the returned data, and will update
|
|
|
2842 |
<b><tt>params[].options</tt></b> to indicate the form. The returned
|
|
|
2843 |
<b><tt>params[].options</tt></b> will normally have only one option set per
|
|
|
2844 |
group.
|
|
|
2845 |
|
|
|
2846 |
<p>
|
|
|
2847 |
For further details on <b><tt>params</tt></b>, see <a
|
|
|
2848 |
href="../src/gxgetbit.h">gxgetbit.h</a>. For further details on
|
|
|
2849 |
<b><tt>options</tt></b>, see <a href="../src/gxbitfmt.h">gxbitfmt.h</a>.
|
|
|
2850 |
|
|
|
2851 |
<p>
|
|
|
2852 |
Define w = <b><tt>prect</tt></b>->q.x - <b><tt>prect</tt></b>->p.x, h
|
|
|
2853 |
= <b><tt>prect</tt></b>->q.y - <b><tt>prect</tt></b>->p.y. If the
|
|
|
2854 |
bits cannot be read back (for example, from a printer), return
|
|
|
2855 |
<b><tt>gs_error_unknownerror</tt></b>; if raster bytes is not enough space
|
|
|
2856 |
to hold <b><tt>offset_x</tt></b> + w pixels, or if the source rectangle
|
|
|
2857 |
goes outside the device dimensions (p.x < 0 || p.y < 0 || q.x >
|
|
|
2858 |
<b><tt>dev</tt></b>->width || q.y > <b><tt>dev</tt></b>->height),
|
|
|
2859 |
return <b><tt>gs_error_rangecheck</tt></b>; if any regions could not be
|
|
|
2860 |
read, return <b><tt>gs_error_ioerror</tt></b> if unpainted is
|
|
|
2861 |
<b><tt>NULL</tt></b>, otherwise the number of rectangles (see below);
|
|
|
2862 |
otherwise return 0.
|
|
|
2863 |
|
|
|
2864 |
<p>
|
|
|
2865 |
The caller supplies a buffer of <b><tt>raster</tt></b> × h
|
|
|
2866 |
bytes starting at <b><tt>data[0]</tt></b> for the returned data in chunky
|
|
|
2867 |
format, or <b><em>N</em></b> buffers of
|
|
|
2868 |
<b><tt>raster</tt></b> × h bytes starting at
|
|
|
2869 |
<b><tt>data[0]</tt></b> through
|
|
|
2870 |
<b><tt>data[</tt></b><b><em>N-1</em></b><b><tt>]</tt></b> in planar format
|
|
|
2871 |
where <b><em>N</em></b> is the number of components or bits. The contents
|
|
|
2872 |
of the bits beyond the last valid bit in each scan line (as defined by w)
|
|
|
2873 |
are unpredictable. data need not be aligned in any way. If
|
|
|
2874 |
<b><tt>x_offset</tt></b> is non-zero, the bits before the first valid bit
|
|
|
2875 |
in each scan line are undefined. If the implementation returns pointers to
|
|
|
2876 |
the data, it stores them into <b><tt>data[0]</tt></b> or
|
|
|
2877 |
<b><tt>data[</tt></b><b><em>0..N-1</em></b><b><tt>]</tt></b>.
|
|
|
2878 |
|
|
|
2879 |
<p>
|
|
|
2880 |
If not all the source data are available (for example, because the source
|
|
|
2881 |
was a partially obscured window and backing store was not available or not
|
|
|
2882 |
used), or if the rectangle does not fall completely within the device's
|
|
|
2883 |
coordinate system, any unread bits are undefined, and the value returned
|
|
|
2884 |
depends on whether unread is <b><tt>NULL</tt></b>. If unread is
|
|
|
2885 |
<b><tt>NULL</tt></b>, return <b><tt>gs_error_ioerror</tt></b>; in this case,
|
|
|
2886 |
some bits may or may not have been read. If unread is not
|
|
|
2887 |
<b><tt>NULL</tt></b>, allocate (using <b><tt>dev</tt></b>->memory) and
|
|
|
2888 |
fill in a list of rectangles that could not be read, store the pointer to
|
|
|
2889 |
the list in <b><tt>*unread</tt></b>, and return the number of rectangles; in
|
|
|
2890 |
this case, all bits not listed in the rectangle list have been read back
|
|
|
2891 |
properly. The list is not sorted in any particular order, but the
|
|
|
2892 |
rectangles do not overlap. Note that the rectangle list may cover a
|
|
|
2893 |
superset of the region actually obscured: for example, a lazy implementation
|
|
|
2894 |
could return a single rectangle that was the bounding box of the region.
|
|
|
2895 |
</dl>
|
|
|
2896 |
|
|
|
2897 |
<dl>
|
|
|
2898 |
<dt><b><tt>int (*get_bits)(gx_device *dev, int y,
|
|
|
2899 |
byte *data, byte **actual_data)</tt></b>
|
|
|
2900 |
<b><em>[OPTIONAL]</em></b>
|
|
|
2901 |
<dd>Read scan line <b><tt>y</tt></b> of bits back from the device into the
|
|
|
2902 |
area starting at data. This call is functionally equivalent to
|
|
|
2903 |
|
|
|
2904 |
<blockquote>
|
|
|
2905 |
<pre>(*get_bits_rectangle)
|
|
|
2906 |
(dev, {0, y, dev->width, y+1},
|
|
|
2907 |
{(GB_ALIGN_ANY | (GB_RETURN_COPY | GB_RETURN_POINTER) | GB_OFFSET_0 |
|
|
|
2908 |
GB_RASTER_STANDARD | GB_FORMAT_CHUNKY | GB_COLORS_NATIVE |
|
|
|
2909 |
GB_ALPHA_NONE),
|
|
|
2910 |
{data}})</pre></blockquote>
|
|
|
2911 |
|
|
|
2912 |
<p>
|
|
|
2913 |
with the returned value of
|
|
|
2914 |
<b><tt>params</tt></b>-><b><tt>data[0]</tt></b> stored in
|
|
|
2915 |
<b><tt>*actual_data</tt></b>, and will in fact be implemented this way if
|
|
|
2916 |
the device defines a <b><tt>get_bits_rectangle</tt></b> procedure and does
|
|
|
2917 |
not define one for <b><tt>get_bits</tt></b>. (If
|
|
|
2918 |
<b><tt>actual_data</tt></b> is <b><tt>NULL</tt></b>,
|
|
|
2919 |
<b><tt>GB_RETURN_POINTER</tt></b> is omitted from the options.)
|
|
|
2920 |
</dl>
|
|
|
2921 |
|
|
|
2922 |
<h3><a name="Parameters"></a>Parameters</h3>
|
|
|
2923 |
|
|
|
2924 |
<p>
|
|
|
2925 |
Devices may have an open-ended set of parameters, which are simply pairs
|
|
|
2926 |
consisting of a name and a value. The value may be of various types:
|
|
|
2927 |
integer (int or long), boolean, float, string, name, <b><tt>NULL</tt></b>,
|
|
|
2928 |
array of integer, array of float, or arrays or dictionaries of mixed types.
|
|
|
2929 |
For example, the <b><tt>Name</tt></b> of a device is a string; the
|
|
|
2930 |
<b><tt>Margins</tt></b> of a device is an array of two floats. See
|
|
|
2931 |
<a href="../src/gsparam.h">gsparam.h</a> for more details.
|
|
|
2932 |
|
|
|
2933 |
<p>
|
|
|
2934 |
If a device has parameters other than the ones applicable to all devices
|
|
|
2935 |
(or, in the case of printer devices, all printer devices), it must provide
|
|
|
2936 |
<b><tt>get_params</tt></b> and <b><tt>put_params</tt></b> procedures. If
|
|
|
2937 |
your device has parameters beyond those of a straightforward display or
|
|
|
2938 |
printer, we strongly advise using the <b><tt>_get_params</tt></b> and
|
|
|
2939 |
<b><tt>_put_params</tt></b> procedures in an existing device (for example,
|
|
|
2940 |
<a href="../src/gdevcdj.c">gdevcdj.c</a> or <a
|
|
|
2941 |
href="../src/gdevbit.c">gdevbit.c</a>) as a model for your own code.
|
|
|
2942 |
|
|
|
2943 |
<dl>
|
|
|
2944 |
<dt><b><tt>int (*get_params)(gx_device *dev,
|
|
|
2945 |
gs_param_list *plist)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2946 |
<dd>Read the parameters of the device into the parameter list at
|
|
|
2947 |
<b><tt>plist</tt></b>, using the <b><tt>param_write_*</tt></b>
|
|
|
2948 |
macros or procedures defined in <a href="../src/gsparam.h">gsparam.h</a>.
|
|
|
2949 |
</dl>
|
|
|
2950 |
|
|
|
2951 |
<dl>
|
|
|
2952 |
<dt><b><tt>int (*get_hardware_params)(gx_device *dev,
|
|
|
2953 |
gs_param_list *plist)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2954 |
<dd>Read the hardware-related parameters of the device into the parameter
|
|
|
2955 |
list at plist. These are any parameters whose values are under control of
|
|
|
2956 |
external forces rather than the program -- for example, front panel
|
|
|
2957 |
switches, paper jam or tray empty sensors, etc. If a parameter involves
|
|
|
2958 |
significant delay or hardware action, the driver should only determine the
|
|
|
2959 |
value of the parameter if it is "requested" by the
|
|
|
2960 |
<b><tt>gs_param_list</tt></b> [<b><tt>param_requested</tt></b>(plist,
|
|
|
2961 |
<b><tt>key_name</tt></b>)]. This function may cause the asynchronous
|
|
|
2962 |
rendering pipeline (if enabled) to be drained, so it should be used
|
|
|
2963 |
sparingly.
|
|
|
2964 |
</dl>
|
|
|
2965 |
|
|
|
2966 |
<dl>
|
|
|
2967 |
<dt><b><tt>int (*put_params)(gx_device *dev,
|
|
|
2968 |
gs_param_list *plist)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
2969 |
<dd>Set the parameters of the device from the parameter list at
|
|
|
2970 |
<b><tt>plist</tt></b>, using the <b><tt>param_read_</tt></b>*
|
|
|
2971 |
macros/procedures defined in <a href="../src/gsparam.h">gsparam.h</a>. All
|
|
|
2972 |
<b><tt>put_params</tt></b> procedures must use a "two-phase commit"
|
|
|
2973 |
algorithm; see <a href="../src/gsparam.h">gsparam.h</a> for details.
|
|
|
2974 |
</dl>
|
|
|
2975 |
|
|
|
2976 |
<h4><a name="Default_CRD_parameters"></a>Default color rendering
|
|
|
2977 |
dictionary (CRD) parameters</h4>
|
|
|
2978 |
|
|
|
2979 |
<p>
|
|
|
2980 |
Drivers that want to provide one or more default CIE color rendering
|
|
|
2981 |
dictionaries (CRDs) can do so through <b><tt>get_params</tt></b>. To do
|
|
|
2982 |
this, they create the CRD in the usual way (normally using the
|
|
|
2983 |
<b><tt>gs_cie_render1_build</tt></b> and <b><tt>_initialize</tt></b>
|
|
|
2984 |
procedures defined in <a href="../src/gscrd.h">gscrd.h</a>), and then write
|
|
|
2985 |
it as a parameter using <b><tt>param_write_cie_render1</tt></b> defined in
|
|
|
2986 |
<a href="../src/gscrdp.h">gscrdp.h</a>. However, the TransformPQR procedure
|
|
|
2987 |
requires special handling. If the CRD uses a TransformPQR procedure
|
|
|
2988 |
different from the default (identity), the driver must do the following:
|
|
|
2989 |
|
|
|
2990 |
<ul>
|
|
|
2991 |
<li>The TransformPQR element of the CRD must include a
|
|
|
2992 |
<b><tt>proc_name</tt></b>, and optionally <b><tt>proc_data</tt></b>. The
|
|
|
2993 |
<b><tt>proc_name</tt></b> is an arbitrary name chosen by the driver to
|
|
|
2994 |
designate the particular TransformPQR function. It must not be the same as
|
|
|
2995 |
any device parameter name; we strongly suggest it include the device name,
|
|
|
2996 |
for instance, "<b><tt>bitTPQRDefault</tt></b>".
|
|
|
2997 |
|
|
|
2998 |
<li>For each such named TransformPQR procedure, the driver's
|
|
|
2999 |
<b><tt>get_param</tt></b> procedure must provide a parameter of the same
|
|
|
3000 |
name. The parameter value must be a string whose bytes are the actual
|
|
|
3001 |
procedure address.
|
|
|
3002 |
</ul>
|
|
|
3003 |
|
|
|
3004 |
<p>
|
|
|
3005 |
For a complete example, see the <b><tt>bit_get_params</tt></b> procedure in
|
|
|
3006 |
<a href="../src/gdevbit.c">gdevbit.c</a>. Note that it is essential that
|
|
|
3007 |
the driver return the CRD or the procedure address only if specifically
|
|
|
3008 |
requested (<b><tt>param_requested(...)</tt></b> > 0); otherwise, errors
|
|
|
3009 |
will occur.
|
|
|
3010 |
|
|
|
3011 |
<h3><a name="External_fonts"></a>External fonts</h3>
|
|
|
3012 |
|
|
|
3013 |
<p>
|
|
|
3014 |
Drivers may include the ability to display text. More precisely, they may
|
|
|
3015 |
supply a set of procedures that in turn implement some font and text
|
|
|
3016 |
handling capabilities, described in <a href="Xfonts.htm">a separate
|
|
|
3017 |
document</a>. The link between the two is the driver procedure that
|
|
|
3018 |
supplies the font and text procedures:
|
|
|
3019 |
|
|
|
3020 |
<dl>
|
|
|
3021 |
<dt><b><tt>xfont_procs *(*get_xfont_procs)(gx_device *dev)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
3022 |
<dd>Return a structure of procedures for handling external fonts and text
|
|
|
3023 |
display. A <b><tt>NULL</tt></b> value means that this driver doesn't
|
|
|
3024 |
provide this capability.
|
|
|
3025 |
</dl>
|
|
|
3026 |
|
|
|
3027 |
<p>
|
|
|
3028 |
For technical reasons, a second procedure is also needed:
|
|
|
3029 |
|
|
|
3030 |
<dl>
|
|
|
3031 |
<dt><b><tt>gx_device *(*get_xfont_device)(gx_device *dev)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
3032 |
<dd>Return the device that implements <b><tt>get_xfont_procs</tt></b> in a
|
|
|
3033 |
non-default way for this device, if any. Except for certain special
|
|
|
3034 |
internal devices, this is always the device argument.
|
|
|
3035 |
</dl>
|
|
|
3036 |
|
|
|
3037 |
<h3><a name="Page_devices"></a>Page devices</h3>
|
|
|
3038 |
|
|
|
3039 |
<dl>
|
|
|
3040 |
<dt><b><tt>gx_device *(*get_page_device)(gx_device *dev)</tt></b>
|
|
|
3041 |
<b><em>[OPTIONAL]</em></b>
|
|
|
3042 |
<dd>According to the Adobe specifications, some devices are "page devices"
|
|
|
3043 |
and some are not. This procedure returns <b><tt>NULL</tt></b> if the
|
|
|
3044 |
device is not a page device, or the device itself if it is a page device.
|
|
|
3045 |
In the case of forwarding devices, <b><tt>get_page_device</tt></b> returns
|
|
|
3046 |
the underlying page device (or <b><tt>NULL</tt></b> if the underlying
|
|
|
3047 |
device is not a page device).
|
|
|
3048 |
</dl>
|
|
|
3049 |
|
|
|
3050 |
<h3><a name="Miscellaneous"></a>Miscellaneous</h3>
|
|
|
3051 |
|
|
|
3052 |
<dl>
|
|
|
3053 |
<dt><b><tt>int (*get_band)(gx_device *dev, int y,
|
|
|
3054 |
int *band_start)</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
3055 |
<dd>If the device is a band device, this procedure stores in
|
|
|
3056 |
<b><tt>*band_start</tt></b> the scan line (device Y coordinate) of the band
|
|
|
3057 |
that includes the given Y coordinate, and returns the number of scan lines
|
|
|
3058 |
in the band. If the device is not a band device, this procedure returns 0.
|
|
|
3059 |
The latter is the default implementation.
|
|
|
3060 |
</dl>
|
|
|
3061 |
|
|
|
3062 |
<dl>
|
|
|
3063 |
<dt><b><tt>void (*get_clipping_box)(gx_device *dev,
|
|
|
3064 |
gs_fixed_rect *pbox))</tt></b> <b><em>[OPTIONAL]</em></b>
|
|
|
3065 |
<dd>Stores in <b><tt>*pbox</tt></b> a rectangle that defines the device's
|
|
|
3066 |
clipping region. For all but a few specialized devices, this is
|
|
|
3067 |
<em>((0,0),(width,height))</em>.
|
|
|
3068 |
</dl>
|
|
|
3069 |
|
|
|
3070 |
<!-- [2.0 end contents] ==================================================== -->
|
|
|
3071 |
|
|
|
3072 |
<!-- [3.0 begin visible trailer] =========================================== -->
|
|
|
3073 |
<hr>
|
|
|
3074 |
|
|
|
3075 |
<p>
|
|
|
3076 |
<small>Copyright © 1996, 2000 Aladdin Enterprises.
|
|
|
3077 |
All rights reserved.</small>
|
|
|
3078 |
|
|
|
3079 |
<p>
|
|
|
3080 |
This software is provided AS-IS with no warranty, either express or
|
|
|
3081 |
implied.
|
|
|
3082 |
|
|
|
3083 |
This software is distributed under license and may not be copied,
|
|
|
3084 |
modified or distributed except as expressly authorized under the terms
|
|
|
3085 |
of the license contained in the file LICENSE in this distribution.
|
|
|
3086 |
|
|
|
3087 |
For more information about licensing, please refer to
|
|
|
3088 |
http://www.ghostscript.com/licensing/. For information on
|
|
|
3089 |
commercial licensing, go to http://www.artifex.com/licensing/ or
|
|
|
3090 |
contact Artifex Software, Inc., 101 Lucas Valley Road #110,
|
|
|
3091 |
San Rafael, CA 94903, U.S.A., +1(415)492-9861.
|
|
|
3092 |
|
|
|
3093 |
<p>
|
|
|
3094 |
<small>Ghostscript version 8.53, 20 October 2005
|
|
|
3095 |
|
|
|
3096 |
<!-- [3.0 end visible trailer] ============================================= -->
|
|
|
3097 |
|
|
|
3098 |
</small></body>
|
|
|
3099 |
</html>
|