| 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 Ghostscript library</title>
|
|
|
5 |
<!-- $Id: Lib.htm,v 1.43 2005/10/20 19:46:23 ray Exp $ -->
|
|
|
6 |
<!-- Originally: lib.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 Ghostscript Library</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="#GS_library">The Ghostscript library</a>
|
|
|
25 |
<li><a href="#PS_operator_API">PostScript operator API</a>
|
|
|
26 |
<ul>
|
|
|
27 |
<li><a href="#Patterns">Patterns</a>
|
|
|
28 |
<li><a href="#Lower_level_API">Lower-level API</a>
|
|
|
29 |
</ul>
|
|
|
30 |
<li><a href="#Visual_trace">Visual Trace instructions</a>
|
|
|
31 |
<li><a href="#Full_example">A full example</a>
|
|
|
32 |
</ul></blockquote>
|
|
|
33 |
|
|
|
34 |
<!-- [1.2 end table of contents] =========================================== -->
|
|
|
35 |
|
|
|
36 |
<!-- [1.3 begin hint] ====================================================== -->
|
|
|
37 |
|
|
|
38 |
<p>For other information, see the <a href="Readme.htm">Ghostscript
|
|
|
39 |
overview</a>.
|
|
|
40 |
|
|
|
41 |
<!-- [1.3 end hint] ======================================================== -->
|
|
|
42 |
|
|
|
43 |
<hr>
|
|
|
44 |
|
|
|
45 |
<!-- [1.0 end visible header] ============================================== -->
|
|
|
46 |
|
|
|
47 |
<!-- [2.0 begin contents] ================================================== -->
|
|
|
48 |
|
|
|
49 |
<h2><a name="GS_library"></a>The Ghostscript library</h2>
|
|
|
50 |
|
|
|
51 |
<p>
|
|
|
52 |
This document describes the Ghostscript library, a set of procedures
|
|
|
53 |
to implement the graphics and filtering capabilities that are primitive
|
|
|
54 |
operations in the PostScript language and in Adobe Portable Document Format
|
|
|
55 |
(PDF).
|
|
|
56 |
|
|
|
57 |
<p>
|
|
|
58 |
Ghostscript is actually two programs: a language interpreter, and a
|
|
|
59 |
graphics library. The library provides, in the form of C procedures, all
|
|
|
60 |
the graphics functions of the language, that is, approximately those
|
|
|
61 |
facilities listed in section 8.1 of the <cite>PostScript
|
|
|
62 |
Language Reference Manual</cite>, starting with the
|
|
|
63 |
graphics state operators. In addition, the library provides some
|
|
|
64 |
lower-level graphics facilities that offer higher performance in exchange
|
|
|
65 |
for less generality.
|
|
|
66 |
|
|
|
67 |
<hr>
|
|
|
68 |
|
|
|
69 |
<h2><a name="PS_operator_API"></a>PostScript operator API</h2>
|
|
|
70 |
|
|
|
71 |
<p>
|
|
|
72 |
The highest level of the library, which is the one that most clients will
|
|
|
73 |
use, directly implements the PostScript graphics operators with procedures
|
|
|
74 |
named <b><tt>gs_XXX</tt></b>, for instance <b><tt>gs_moveto</tt></b> and
|
|
|
75 |
<b><tt>gs_fill</tt></b>. Nearly all of these procedures take graphics
|
|
|
76 |
state objects as their first arguments, such as
|
|
|
77 |
|
|
|
78 |
<blockquote><b><tt>
|
|
|
79 |
int gs_moveto(gs_state *, double, double);
|
|
|
80 |
</tt></b></blockquote>
|
|
|
81 |
|
|
|
82 |
<p>
|
|
|
83 |
Nearly every procedure returns an integer code which is >= 0 for a
|
|
|
84 |
successful return or <0 for a failure. The failure codes correspond
|
|
|
85 |
directly to PostScript errors, and are defined in
|
|
|
86 |
<b><tt>gserrors.h</tt></b>.
|
|
|
87 |
|
|
|
88 |
<p>
|
|
|
89 |
The library implements all the operators in the following sections of the
|
|
|
90 |
<cite>PostScript Language Reference Manual</cite>, with the indicated
|
|
|
91 |
omissions and with the APIs defined in the indicated <b><tt>.h</tt></b>
|
|
|
92 |
files. A header of the form <b><em>A.h(B.h)</em></b> indicates that
|
|
|
93 |
<b><em>A.h</em></b> is included in <b><em>B.h</em></b>, so
|
|
|
94 |
<b><em>A.h</em></b> need not be included explicitly if <b><em>B.h</em></b>
|
|
|
95 |
is included. Operators marked with * in the "omissions" column are not
|
|
|
96 |
implemented directly; the library provides lower-level procedures that can
|
|
|
97 |
be used to implement the operator.
|
|
|
98 |
|
|
|
99 |
<p>
|
|
|
100 |
There are slight differences in the operators that return multiple values,
|
|
|
101 |
since C's provisions for this are awkward. Also, the control structure for
|
|
|
102 |
the operators involving callback procedures (<b><tt>pathforall</tt></b>,
|
|
|
103 |
<b><tt>image</tt></b>, <b><tt>colorimage</tt></b>,
|
|
|
104 |
<b><tt>imagemask</tt></b>) is partly inverted: the client calls a procedure
|
|
|
105 |
to set up an enumerator object, and then calls another procedure for each
|
|
|
106 |
iteration. The <b><tt>...show</tt></b> operators,
|
|
|
107 |
<b><tt>charpath</tt></b>, and <b><tt>stringwidth</tt></b> also use an
|
|
|
108 |
inverted control structure.
|
|
|
109 |
|
|
|
110 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
111 |
<tr valign=bottom>
|
|
|
112 |
<th align=left>Section<br>(operators)
|
|
|
113 |
<td>
|
|
|
114 |
<th align=left>Headers
|
|
|
115 |
<td>
|
|
|
116 |
<th align=left>Omissions
|
|
|
117 |
<tr> <td colspan=5><hr>
|
|
|
118 |
<tr valign=top> <td>Graphics state -- device-independent
|
|
|
119 |
<td>
|
|
|
120 |
<td><b><tt>gscolor.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gscolor1.h</tt></b><br><b><tt>gscolor2.h</tt></b><br><b><tt>gscspace.h</tt></b><br><b><tt>gshsb.h</tt></b><br><b><tt>gsline.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gsstate.h</tt></b>
|
|
|
121 |
<td>
|
|
|
122 |
<td>
|
|
|
123 |
<tr> <td>
|
|
|
124 |
<tr valign=top> <td>Graphics state -- device-dependent
|
|
|
125 |
<td>
|
|
|
126 |
<td><b><tt>gscolor.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gscolor1.h</tt></b><br><b><tt>gscolor2.h</tt></b><br><b><tt>gsht.h</tt></b>(<b><tt>gsht1.h</tt></b>,<b><tt>gsstate.h</tt></b>)<br><b><tt>gsht1.h</tt></b><br><b><tt>gsline.h</tt></b>(<b><tt>gsstate.h</tt></b>)
|
|
|
127 |
<td>
|
|
|
128 |
<td>
|
|
|
129 |
<tr> <td>
|
|
|
130 |
<tr valign=top> <td>Coordinate system and matrix
|
|
|
131 |
<td>
|
|
|
132 |
<td><b><tt>gscoord.h</tt></b><br><b><tt>gsmatrix.h</tt></b>
|
|
|
133 |
<td>
|
|
|
134 |
<td><b><tt>*matrix</tt></b>, <b><tt>*identmatrix</tt></b>, <b><tt>*concatmatrix</tt></b>, <b><tt>*invertmatrix</tt></b>
|
|
|
135 |
<tr> <td>
|
|
|
136 |
<tr valign=top> <td>Path construction
|
|
|
137 |
<td>
|
|
|
138 |
<td><b><tt>gspath.h</tt></b><br><b><tt>gspath2.h</tt></b>
|
|
|
139 |
<td>
|
|
|
140 |
<td><b><tt>*arct</tt></b>, <b><tt>*pathforall</tt></b>, <b><tt>ustrokepath</tt></b>, <b><tt>uappend</tt></b>, <b><tt>upath</tt></b>, <b><tt>ucache</tt></b>
|
|
|
141 |
<tr> <td>
|
|
|
142 |
<tr valign=top> <td>Painting
|
|
|
143 |
<td>
|
|
|
144 |
<td><b><tt>gsimage.h</tt></b><br><b><tt>gspaint.h</tt></b><br><b><tt>gspath2.h</tt></b>
|
|
|
145 |
<td>
|
|
|
146 |
<td><b><tt>*image</tt></b>, <b><tt>*colorimage</tt></b>, <b><tt>*imagemask</tt></b>, <b><tt>ufill</tt></b>, <b><tt>ueofill</tt></b>, <b><tt>ustroke</tt></b>
|
|
|
147 |
<tr> <td>
|
|
|
148 |
<tr valign=top> <td>Form and pattern
|
|
|
149 |
<td>
|
|
|
150 |
<td><b><tt>gscolor2.h</tt></b>
|
|
|
151 |
<td>
|
|
|
152 |
<td><b><tt>execform</tt></b>
|
|
|
153 |
<tr> <td>
|
|
|
154 |
<tr valign=top> <td>Device setup and output
|
|
|
155 |
<td>
|
|
|
156 |
<td><b><tt>gsdevice.h</tt></b>
|
|
|
157 |
<td>
|
|
|
158 |
<td><b><tt>*showpage</tt></b>, <b><tt>*set</tt></b>/<b><tt>currentpagedevice</tt></b>
|
|
|
159 |
<tr> <td>
|
|
|
160 |
<tr valign=top> <td>Character and font
|
|
|
161 |
<td>
|
|
|
162 |
<td><b><tt>gschar.h</tt></b><br><b><tt>gsfont.h</tt></b>
|
|
|
163 |
<td>
|
|
|
164 |
<td>*(all the <b><tt>show</tt></b> operators), <b><tt>definefont</tt></b>, <b><tt>undefinefont</tt></b>, <b><tt>findfont</tt></b>, <b><tt>*scalefont</tt></b>, <b><tt>*makefont</tt></b>, <b><tt>selectfont</tt></b>, <b><tt>[Global]FontDirectory</tt></b>, <b><tt>Standard</tt></b>/<b><tt>ISOLatin1Encoding</tt></b>, <b><tt>findencoding</tt></b>
|
|
|
165 |
</table></blockquote>
|
|
|
166 |
|
|
|
167 |
<p>
|
|
|
168 |
The following procedures from the list above operate differently from their
|
|
|
169 |
PostScript operator counterparts, as explained here:
|
|
|
170 |
|
|
|
171 |
<dl>
|
|
|
172 |
<dt><b><tt>gs_makepattern(gscolor2.h)</tt></b>
|
|
|
173 |
<dd>Takes an explicit current color, rather than using the current color in
|
|
|
174 |
the graphics state. Takes an explicit allocator for allocating the pattern
|
|
|
175 |
implementation. See below for more details on
|
|
|
176 |
<b><tt>gs_makepattern</tt></b>.
|
|
|
177 |
</dl>
|
|
|
178 |
|
|
|
179 |
<dl>
|
|
|
180 |
<dt><b><tt>gs_setpattern(gscolor2.h)</tt></b>
|
|
|
181 |
<dt><b><tt>gs_setcolor(gscolor2.h)</tt></b>
|
|
|
182 |
<dt><b><tt>gs_currentcolor(gscolor2.h)</tt></b>
|
|
|
183 |
<dd>Use <b><tt>gs_client_color</tt></b> rather than a set of color
|
|
|
184 |
parameter values. See below for more details on
|
|
|
185 |
<b><tt>gs_setpattern</tt></b>.
|
|
|
186 |
</dl>
|
|
|
187 |
|
|
|
188 |
<dl>
|
|
|
189 |
<dt><b><tt>gs_currentdash_length/pattern/offset(gsline.h)</tt></b>
|
|
|
190 |
<dd>Splits up <b><tt>currentdash</tt></b> into three separate procedures.
|
|
|
191 |
</dl>
|
|
|
192 |
|
|
|
193 |
<dl>
|
|
|
194 |
<dt><b><tt>gs_screen_init/currentpoint/next/install(gsht.h)</tt></b>
|
|
|
195 |
<dd>Provide an "enumeration style" interface to <b><tt>setscreen</tt></b>.
|
|
|
196 |
(<b><tt>gs_setscreen</tt></b> is also implemented.)
|
|
|
197 |
</dl>
|
|
|
198 |
|
|
|
199 |
<dl>
|
|
|
200 |
<dt><b><tt>gs_rotate/scale/translate(gscoord.h)</tt></b>
|
|
|
201 |
<dt><b><tt>gs_[i][d]transform(gscoord.h)</tt></b>
|
|
|
202 |
<dd>These always operate on the graphics state CTM. The corresponding
|
|
|
203 |
operations on free-standing matrices are in <b><tt>gsmatrix.h</tt></b> and
|
|
|
204 |
have different names.
|
|
|
205 |
</dl>
|
|
|
206 |
|
|
|
207 |
<dl>
|
|
|
208 |
<dt><b><tt>gs_path_enum_alloc/init/next/cleanup(gspath.h)</tt></b>
|
|
|
209 |
<dd>Provide an "enumeration style" implementation of
|
|
|
210 |
<b><tt>pathforall</tt></b>.
|
|
|
211 |
</dl>
|
|
|
212 |
|
|
|
213 |
<dl>
|
|
|
214 |
<dt><b><tt>gs_image_enum_alloc(gsimage.h)</tt></b>
|
|
|
215 |
<dt><b><tt>gs_image_init/next/cleanup(gsimage.h)</tt></b>
|
|
|
216 |
<dd>Provide an "enumeration style" interface to the equivalent of
|
|
|
217 |
<b><tt>image</tt></b>, <b><tt>imagemask</tt></b>, and
|
|
|
218 |
<b><tt>colorimage</tt></b>. In the <b><tt>gs_image_t</tt></b>,
|
|
|
219 |
<b><tt>ColorSpace</tt></b> provides an explicit color space, rather than
|
|
|
220 |
using the current color space in the graphics state;
|
|
|
221 |
<b><tt>ImageMask</tt></b> distinguishes <b><tt>imagemask</tt></b> from
|
|
|
222 |
<b><tt>[color]image</tt></b>.
|
|
|
223 |
</dl>
|
|
|
224 |
|
|
|
225 |
<dl>
|
|
|
226 |
<dt><b><tt>gs_get/putdeviceparams(gsdevice.h)</tt></b>
|
|
|
227 |
<dd>Take a <b><tt>gs_param_list</tt></b> for specifying or receiving the
|
|
|
228 |
parameter values. See <b><tt>gsparam.h</tt></b> for more details.
|
|
|
229 |
</dl>
|
|
|
230 |
|
|
|
231 |
<dl>
|
|
|
232 |
<dt><b><tt>gs_show_enum_alloc/release(gschar.h)</tt></b>
|
|
|
233 |
<dt><b><tt>gs_xxxshow_[n_]init(gschar.h)</tt></b>
|
|
|
234 |
<dt><b><tt>gs_show_next(gschar.h)</tt></b>
|
|
|
235 |
<dd>Provide an "enumeration style" interface to writing text. Note that
|
|
|
236 |
control returns to the caller if the character must be rasterized.
|
|
|
237 |
</dl>
|
|
|
238 |
|
|
|
239 |
<p>
|
|
|
240 |
This level of the library also implements the following operators from other
|
|
|
241 |
sections of the Manual:
|
|
|
242 |
|
|
|
243 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
244 |
<tr valign=bottom>
|
|
|
245 |
<th align=left>Section<br>(operators)
|
|
|
246 |
<td>
|
|
|
247 |
<th align=left>Headers
|
|
|
248 |
<td>
|
|
|
249 |
<th align=left>Operators
|
|
|
250 |
<tr> <td colspan=5><hr>
|
|
|
251 |
<tr valign=top> <td>Interpreter parameter
|
|
|
252 |
<td>
|
|
|
253 |
<td><b><tt>gsfont.h</tt></b>
|
|
|
254 |
<td>
|
|
|
255 |
<td><b><tt>cachestatus</tt></b>, <b><tt>setcachelimit</tt></b>, <b><tt>*set/currentcacheparams</tt></b>
|
|
|
256 |
<tr valign=top> <td>Display PostScript
|
|
|
257 |
<td>
|
|
|
258 |
<td><b><tt>gsstate.h</tt></b>
|
|
|
259 |
<td>
|
|
|
260 |
<td><b><tt>set/currenthalftonephase</tt></b>
|
|
|
261 |
</table></blockquote>
|
|
|
262 |
|
|
|
263 |
<p>
|
|
|
264 |
In order to obtain the full PostScript Level 2 functionality listed above,
|
|
|
265 |
<b><tt>FEATURE_DEVS</tt></b> must be set in the makefile to include at least the following:
|
|
|
266 |
|
|
|
267 |
<blockquote><b><tt>
|
|
|
268 |
FEATURE_DEVS=patcore.dev cmykcore.dev psl2core.dev dps2core.dev ciecore.dev path1core.dev hsbcore.dev
|
|
|
269 |
</tt></b></blockquote>
|
|
|
270 |
|
|
|
271 |
<p>
|
|
|
272 |
The <b><tt>*lib.mak</tt></b> makefiles mentioned below do not always
|
|
|
273 |
include all of these features.
|
|
|
274 |
|
|
|
275 |
<p>
|
|
|
276 |
Files named <b><tt>gs*.c</tt></b> implement the higher level of the
|
|
|
277 |
graphics library. As might be expected, all procedures, variables, and
|
|
|
278 |
structures available at this level begin with "<b><tt>gs_</tt></b>".
|
|
|
279 |
Structures that appear in these interfaces, but whose definitions may be
|
|
|
280 |
hidden from clients, also have names beginning with "<b><tt>gs_</tt></b>",
|
|
|
281 |
that is, the prefix, not the implementation, reflects at what level the
|
|
|
282 |
abstraction is made available.
|
|
|
283 |
|
|
|
284 |
<h3><a name="Patterns"></a>Patterns</h3>
|
|
|
285 |
|
|
|
286 |
<p>
|
|
|
287 |
Patterns are the most complicated PostScript language objects that the
|
|
|
288 |
library API deals with. As in PostScript, defining a pattern color and
|
|
|
289 |
using the color are two separate operations.
|
|
|
290 |
|
|
|
291 |
<p>
|
|
|
292 |
<b><tt>gs_makepattern</tt></b> defines a pattern color. Its arguments are as follows:
|
|
|
293 |
|
|
|
294 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
295 |
<tr valign=top> <td><b><tt>gs_client_color *</tt></b>
|
|
|
296 |
<td>
|
|
|
297 |
<td>The resulting <b><tt>Pattern</tt></b> color is stored here. This is different from PostScript, which has no color objects <em>per se</em>, and hence returns a modified copy of the dictionary.
|
|
|
298 |
<tr valign=top> <td><b><tt>const gs_client_pattern *</tt></b>
|
|
|
299 |
<td>
|
|
|
300 |
<td>The analogue of the original <b><tt>Pattern</tt></b> dictionary, described in detail just below.
|
|
|
301 |
<tr valign=top> <td><b><tt>const gs_matrix *</tt></b>
|
|
|
302 |
<td>
|
|
|
303 |
<td>Corresponds to the matrix argument of the <b><tt>makepattern</tt></b> operator.
|
|
|
304 |
<tr valign=top> <td><b><tt>gs_state *</tt></b>
|
|
|
305 |
<td>
|
|
|
306 |
<td>The current graphics state.
|
|
|
307 |
<tr valign=top> <td><b><tt>gs_memory_t *</tt></b>
|
|
|
308 |
<td>
|
|
|
309 |
<td>The allocator to use for allocating the saved data for the
|
|
|
310 |
<b><tt>Pattern</tt></b> color. If this is
|
|
|
311 |
<b><tt>NULL</tt></b>, <b><tt>gs_makepattern</tt></b> uses the
|
|
|
312 |
same allocator that allocated the graphics state. Library
|
|
|
313 |
clients should probably always use <b><tt>NULL</tt></b>.
|
|
|
314 |
|
|
|
315 |
</table></blockquote>
|
|
|
316 |
|
|
|
317 |
<p>
|
|
|
318 |
The <b><tt>gs_client_pattern</tt></b> structure defined in
|
|
|
319 |
<b><tt>gscolor2.h</tt></b> corresponds to the <b><tt>Pattern</tt></b>
|
|
|
320 |
dictionary that is the argument to the PostScript language
|
|
|
321 |
<b><tt>makepattern</tt></b> operator. This structure has one extra member,
|
|
|
322 |
<b><tt>void *client_data</tt></b>, which is a place for clients to
|
|
|
323 |
store a pointer to additional data for the <b><tt>PaintProc</tt></b>; this
|
|
|
324 |
provides the same functionality as putting additional keys in the
|
|
|
325 |
<b><tt>Pattern</tt></b> dictionary at the PostScript language level. The
|
|
|
326 |
<b><tt>PaintProc</tt></b> is an ordinary C procedure that takes as
|
|
|
327 |
parameters a <b><tt>gs_client_color *</tt></b>, which is the
|
|
|
328 |
<b><tt>Pattern</tt></b> color that is being used for painting, and a
|
|
|
329 |
<b><tt>gs_state *</tt></b>, which is the same graphics state that
|
|
|
330 |
would be presented to the <b><tt>PaintProc</tt></b> in PostScript.
|
|
|
331 |
Currently the <b><tt>gs_client_color *</tt></b> is always the current
|
|
|
332 |
color in the graphics state, but the <b><tt>PaintProc</tt></b> should not
|
|
|
333 |
rely on this. The <b><tt>PaintProc</tt></b> can retrieve the
|
|
|
334 |
<b><tt>gs_client_pattern *</tt></b> from the
|
|
|
335 |
<b><tt>gs_client_color *</tt></b> with the
|
|
|
336 |
<b><tt>gs_getpattern</tt></b> procedure, also defined in
|
|
|
337 |
<b><tt>gscolor2.h</tt></b>, and from there, it can retrieve the
|
|
|
338 |
<b><tt>client_data</tt></b> pointer.
|
|
|
339 |
|
|
|
340 |
<p>
|
|
|
341 |
The normal way to set a <b><tt>Pattern</tt></b> color is to call
|
|
|
342 |
<b><tt>gs_setpattern</tt></b> with the graphics state and with the
|
|
|
343 |
<b><tt>gs_client_color</tt></b> returned by <b><tt>gs_makepattern</tt></b>.
|
|
|
344 |
After that, one can use <b><tt>gs_setcolor</tt></b> to set further
|
|
|
345 |
<b><tt>Pattern</tt></b> colors (colored, or uncolored with the same
|
|
|
346 |
underlying color space); the rules are the same as those in PostScript.
|
|
|
347 |
Note that for <b><tt>gs_setpattern</tt></b>, the
|
|
|
348 |
<b><tt>paint.values</tt></b> in the <b><tt>gs_client_color</tt></b> must be
|
|
|
349 |
filled in for uncolored patterns; this corresponds to the additional
|
|
|
350 |
arguments for the PostScript <b><tt>setpattern</tt></b> operator in the
|
|
|
351 |
uncolored case.
|
|
|
352 |
|
|
|
353 |
<p>
|
|
|
354 |
There is a special procedure <b><tt>gs_makebitmappattern</tt></b> for creating bitmap-based
|
|
|
355 |
patterns. Its API is documented in <b><tt>gscolor2.h</tt></b>; its implementation, in
|
|
|
356 |
<b><tt>gspcolor.c</tt></b>, may be useful as an example of a pattern using a particularly
|
|
|
357 |
simple <b><tt>PaintProc.</tt></b>
|
|
|
358 |
|
|
|
359 |
<h3><a name="Lower_level_API"></a>Lower-level API</h3>
|
|
|
360 |
|
|
|
361 |
<p>
|
|
|
362 |
Files named <b><tt>gx*.c</tt></b> implement the lower level of the graphics
|
|
|
363 |
library. The interfaces at the <b><tt>gx</tt></b> level are less stable,
|
|
|
364 |
and expose more of the implementation detail, than those at the
|
|
|
365 |
<b><tt>gs</tt></b> level: in particular, the <b><tt>gx</tt></b> interfaces
|
|
|
366 |
generally use device coordinates in an internal fixed-point representation,
|
|
|
367 |
as opposed to the <b><tt>gs</tt></b> interfaces that use floating point
|
|
|
368 |
user coordinates. Named entities at this level begin with
|
|
|
369 |
<b><tt>gx_</tt></b>.
|
|
|
370 |
|
|
|
371 |
<p>
|
|
|
372 |
Files named <b><tt>gz*.c</tt></b> and <b><tt>gz*.h</tt></b> are internal to
|
|
|
373 |
the Ghostscript implementation, and are not designed to be called by
|
|
|
374 |
clients.
|
|
|
375 |
|
|
|
376 |
<hr>
|
|
|
377 |
|
|
|
378 |
<h2><a name="Visual_trace"></a>Visual Trace instructions</h2>
|
|
|
379 |
|
|
|
380 |
<p>
|
|
|
381 |
Visual Trace instructions may be inserted in code to provide debug output in
|
|
|
382 |
a graphical form. Graphics Library doesn't provide a rasterisation of the
|
|
|
383 |
output, because it is platform dependent. Instead this, client application
|
|
|
384 |
shpuld set <b><tt>vd_trace0</tt></b> external variable to Graphics Library,
|
|
|
385 |
passing a set of callbacks which provide the rasterization.
|
|
|
386 |
|
|
|
387 |
<p>
|
|
|
388 |
Visual Trace instructions are defined in <b><tt>vdtrace.h</tt></b>.
|
|
|
389 |
Debug output must be opened with <b><tt>vd_get_dc</tt></b> instruction,
|
|
|
390 |
which obtains a drawing context for the debug output, and must be closed
|
|
|
391 |
with <b><tt>vd_release_dc</tt></b> instruction. After opening the output,
|
|
|
392 |
scale, origin and shift to be set for mapping the debugee coordinate space
|
|
|
393 |
to window coordinate space. Than painting instructions to be used.
|
|
|
394 |
Painting may be either immediate or indirect.
|
|
|
395 |
|
|
|
396 |
<p>
|
|
|
397 |
Indirect painting uses <b><tt>vd_beg_path</b></tt> before
|
|
|
398 |
line output and <b><tt>vd_end_path</b></tt> after line output,
|
|
|
399 |
to store a path into a temporary storage. After this
|
|
|
400 |
<b><tt>vd_stroke</b></tt> may be used for stroking the path,
|
|
|
401 |
or <b><tt>vd_fill</b></tt> may be used for filling the region inside the path.
|
|
|
402 |
|
|
|
403 |
<p>
|
|
|
404 |
Immediate painting happens when path construction instructions are
|
|
|
405 |
involved without <b><tt>vd_beg_path</b></tt> and <b><tt>vd_end_path</b></tt>.
|
|
|
406 |
In this case lines and curves are being drawed immediately, when a path construction
|
|
|
407 |
instruction is executed.
|
|
|
408 |
|
|
|
409 |
<p>
|
|
|
410 |
The following table explains the semantics of Visual Trace instructions.
|
|
|
411 |
<p>
|
|
|
412 |
|
|
|
413 |
<table cellpadding=0 cellspacing=0>
|
|
|
414 |
<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Visual Trace instructions</font><hr>
|
|
|
415 |
<tr> <th align=left>Instruction
|
|
|
416 |
<td>
|
|
|
417 |
<th align=left>Function
|
|
|
418 |
<td>
|
|
|
419 |
<th align=left>Parameters
|
|
|
420 |
<tr> <td colspan=5><hr>
|
|
|
421 |
<tr> <td><b><tt>vd_get_dc</tt></b>
|
|
|
422 |
<td>
|
|
|
423 |
<td>Obtain drawing context
|
|
|
424 |
<td>
|
|
|
425 |
<td><b><tt>-T</tt></b> option flag value, for which the subsequent output is enabled.
|
|
|
426 |
<tr> <td><b><tt>vd_release_dc</tt></b>
|
|
|
427 |
<td>
|
|
|
428 |
<td>Release drawing context
|
|
|
429 |
<td>
|
|
|
430 |
<td>
|
|
|
431 |
<tr> <td><b><tt>vd_enabled</tt></b>
|
|
|
432 |
<td>
|
|
|
433 |
<td>Is trace currently enabled ?
|
|
|
434 |
<td>
|
|
|
435 |
<td>
|
|
|
436 |
<tr> <td><b><tt>vd_get_size_unscaled_x</tt></b>
|
|
|
437 |
<td>
|
|
|
438 |
<td>Get the horizontal size of the output window in pixels.
|
|
|
439 |
<td>
|
|
|
440 |
<td>
|
|
|
441 |
<tr> <td><b><tt>vd_get_size_unscaled_y</tt></b>
|
|
|
442 |
<td>
|
|
|
443 |
<td>Get the vertical size of the output window in pixels.
|
|
|
444 |
<td>
|
|
|
445 |
<td>
|
|
|
446 |
<tr> <td><b><tt>vd_get_size_caled_x</tt></b>
|
|
|
447 |
<td>
|
|
|
448 |
<td>Get the horizontal size of the output window in debuggee coordinate units.
|
|
|
449 |
<td>
|
|
|
450 |
<td>
|
|
|
451 |
<tr> <td><b><tt>vd_get_size_caled_y</tt></b>
|
|
|
452 |
<td>
|
|
|
453 |
<td>Get the vertical size of the output window in debuggee coordinate units.
|
|
|
454 |
<td>
|
|
|
455 |
<td>
|
|
|
456 |
<tr> <td><b><tt>vd_get_scale_x</tt></b>
|
|
|
457 |
<td>
|
|
|
458 |
<td>Get the horizontal scale.
|
|
|
459 |
<td>
|
|
|
460 |
<td>
|
|
|
461 |
<tr> <td><b><tt>vd_get_scale_y</tt></b>
|
|
|
462 |
<td>
|
|
|
463 |
<td>Get the vertical scale.
|
|
|
464 |
<td>
|
|
|
465 |
<td>
|
|
|
466 |
<tr> <td><b><tt>vd_get_origin_x</tt></b>
|
|
|
467 |
<td>
|
|
|
468 |
<td>Get the horizontal position of the draft origin in debuggee coordinate space.
|
|
|
469 |
<td>
|
|
|
470 |
<td>
|
|
|
471 |
<tr> <td><b><tt>vd_get_origin_y</tt></b>
|
|
|
472 |
<td>
|
|
|
473 |
<td>Get the vertical position of the draft origin in debuggee coordinate space.
|
|
|
474 |
<td>
|
|
|
475 |
<td>
|
|
|
476 |
<tr> <td><b><tt>vd_set_scale(s)</tt></b>
|
|
|
477 |
<td>
|
|
|
478 |
<td>Set isotripic scale.
|
|
|
479 |
<td>
|
|
|
480 |
<td>Debugee space to window space mapping scale, same for both dimentions.
|
|
|
481 |
<tr> <td><b><tt>vd_set_scaleXY(sx,sy)</tt></b>
|
|
|
482 |
<td>
|
|
|
483 |
<td>Set anisotripic scale.
|
|
|
484 |
<td>
|
|
|
485 |
<td>Debugee space to window space mapping scale, one for each dimention.
|
|
|
486 |
<tr> <td><b><tt>vd_set_origin(x,y)</tt></b>
|
|
|
487 |
<td>
|
|
|
488 |
<td>Set the draft origin.
|
|
|
489 |
<td>
|
|
|
490 |
<td>Origin of the draft in debugee space.
|
|
|
491 |
<tr> <td><b><tt>vd_set_shift(x,y)</tt></b>
|
|
|
492 |
<td>
|
|
|
493 |
<td>Set the draft position.
|
|
|
494 |
<td>
|
|
|
495 |
<td>Position of the draft origin in window space (in pixels).
|
|
|
496 |
<tr> <td><b><tt>vd_set_central_shift</tt></b>
|
|
|
497 |
<td>
|
|
|
498 |
<td>Set the draft position to window center.
|
|
|
499 |
<td>
|
|
|
500 |
<td>
|
|
|
501 |
<tr> <td><b><tt>vd_erase(c)</tt></b>
|
|
|
502 |
<td>
|
|
|
503 |
<td>Fill entire window.
|
|
|
504 |
<td>
|
|
|
505 |
<td>Color to fill.
|
|
|
506 |
<tr> <td><b><tt>vd_beg_path</tt></b>
|
|
|
507 |
<td>
|
|
|
508 |
<td>Begin path construction.
|
|
|
509 |
<td>
|
|
|
510 |
<td>
|
|
|
511 |
<tr> <td><b><tt>vd_end_path</tt></b>
|
|
|
512 |
<td>
|
|
|
513 |
<td>End path construction.
|
|
|
514 |
<td>
|
|
|
515 |
<td>
|
|
|
516 |
<tr> <td><b><tt>vd_moveto(x,y)</tt></b>
|
|
|
517 |
<td>
|
|
|
518 |
<td>Path construction : Set the draft current point.
|
|
|
519 |
<td>
|
|
|
520 |
<td>Debugee coordinates.
|
|
|
521 |
<tr> <td><b><tt>vd_lineto(x,y)</tt></b>
|
|
|
522 |
<td>
|
|
|
523 |
<td>Path construction : Line from current point to specified point.
|
|
|
524 |
<td>
|
|
|
525 |
<td>Debugee coordinates.
|
|
|
526 |
<tr> <td><b><tt>vd_lineto_mupti(p,n)</tt></b>
|
|
|
527 |
<td>
|
|
|
528 |
<td>Path construction : Poliline from current point to specified points.
|
|
|
529 |
<td>
|
|
|
530 |
<td>Array of points and its size, debugee coordinates.
|
|
|
531 |
<tr> <td><b><tt>vd_curveto(x0,y0,x1,y1,x2,y2)</tt></b>
|
|
|
532 |
<td>
|
|
|
533 |
<td>Path construction : Curve (3d order Bezier) from current point to specified point, with specified poles.
|
|
|
534 |
<td>
|
|
|
535 |
<td>2 poles and the curve ending point, debuggee coordinates.
|
|
|
536 |
<tr> <td><b><tt>vd_closepath</tt></b>
|
|
|
537 |
<td>
|
|
|
538 |
<td>Path construction : Close the path (is necessary for filling an area).
|
|
|
539 |
<td>
|
|
|
540 |
<td>
|
|
|
541 |
<tr> <td><b><tt>vd_bar(x0,y0,x1,y1,w,c)</tt></b>
|
|
|
542 |
<td>
|
|
|
543 |
<td>Bar from point to point.
|
|
|
544 |
<td>
|
|
|
545 |
<td>2 points (debugee coordinates), width (in pixels) and color.
|
|
|
546 |
<tr> <td><b><tt>vd_square(x0,y0,w,c)</tt></b>
|
|
|
547 |
<td>
|
|
|
548 |
<td>Square with specified center and size.
|
|
|
549 |
<td>
|
|
|
550 |
<td>The center (debugee coordinates), size (in pixels) and color.
|
|
|
551 |
<tr> <td><b><tt>vd_rect(x0,y0,x1,y1,w,c)</tt></b>
|
|
|
552 |
<td>
|
|
|
553 |
<td>Canonic rectangle with specified coordinites.
|
|
|
554 |
<td>
|
|
|
555 |
<td>Coordinates of boundaries (debugee coordinates), line width (in pixels) and color.
|
|
|
556 |
<tr> <td><b><tt>vd_quad(x0,y0,x1,y1,x2,y2,x3,y3,w,c)</tt></b>
|
|
|
557 |
<td>
|
|
|
558 |
<td>Quadrangle with specified coordinites.
|
|
|
559 |
<td>
|
|
|
560 |
<td>Coordinates of vertices (debugee coordinates), line width (in pixels) and color.
|
|
|
561 |
<tr> <td><b><tt>vd_curve(x0,y0,x1,y1,x2,y2,x3,y3,c,w)</tt></b>
|
|
|
562 |
<td>
|
|
|
563 |
<td>Curve with width.
|
|
|
564 |
<td>
|
|
|
565 |
<td>4 curve poles (debugee coordinates), color, and width (in pixels).
|
|
|
566 |
<tr> <td><b><tt>vd_circle(x,y,r,c)</tt></b>
|
|
|
567 |
<td>
|
|
|
568 |
<td>Circle.
|
|
|
569 |
<td>
|
|
|
570 |
<td>Center (debugee coordinates), radius (in pixels) and color.
|
|
|
571 |
<tr> <td><b><tt>vd_round(x,y,r,c)</tt></b>
|
|
|
572 |
<td>
|
|
|
573 |
<td>Filled circle.
|
|
|
574 |
<td>
|
|
|
575 |
<td>Center (debugee coordinates), radius (in pixels) and color.
|
|
|
576 |
<tr> <td><b><tt>vd_stroke</tt></b>
|
|
|
577 |
<td>
|
|
|
578 |
<td>Stroke a path constructed with vd_beg_path, vd_moveto, vd_lineto,
|
|
|
579 |
vd_curveto, vd_closepath, vd_end_path.
|
|
|
580 |
<td>
|
|
|
581 |
<td>
|
|
|
582 |
<tr> <td><b><tt>vd_fill</tt></b>
|
|
|
583 |
<td>
|
|
|
584 |
<td>Fill a path constructed with vd_beg_path, vd_moveto, vd_lineto,
|
|
|
585 |
vd_curveto, vd_closepath, vd_end_path.
|
|
|
586 |
<td>
|
|
|
587 |
<td>
|
|
|
588 |
<tr> <td><b><tt>vd_setcolor(c)</tt></b>
|
|
|
589 |
<td>
|
|
|
590 |
<td>Set a color.
|
|
|
591 |
<td>
|
|
|
592 |
<td>Color (an integer consisting of red, green, blue bytes).
|
|
|
593 |
<tr> <td><b><tt>vd_setlinewidth(w)</tt></b>
|
|
|
594 |
<td>
|
|
|
595 |
<td>Set line width.
|
|
|
596 |
<td>
|
|
|
597 |
<td>Width (in pixels).
|
|
|
598 |
<tr> <td><b><tt>vd_text(x,y,s,c)</tt></b>
|
|
|
599 |
<td>
|
|
|
600 |
<td>Paint a text.
|
|
|
601 |
<td>
|
|
|
602 |
<td>Origin point (debugee coordinates), a string, and a color.
|
|
|
603 |
<tr> <td><b><tt>vd_wait</tt></b>
|
|
|
604 |
<td>
|
|
|
605 |
<td>Delay execution until a resuming command is entered through user interface.
|
|
|
606 |
<td>
|
|
|
607 |
<td>
|
|
|
608 |
</table>
|
|
|
609 |
|
|
|
610 |
|
|
|
611 |
<p>
|
|
|
612 |
Graphics Library doesn't provide a rasterization of the debug output.
|
|
|
613 |
Instead it calls callbacks, which are specified by a client, and which may
|
|
|
614 |
have a platform dependent implementation. The implementation must not
|
|
|
615 |
use Graphics Library to exclude recursive calls to it from Visual Trace
|
|
|
616 |
instructions. The callbacks and auxiliary data are collected in
|
|
|
617 |
the structure <b><tt>vd_trace_interface</b></tt>, explained in the table below.
|
|
|
618 |
<p>
|
|
|
619 |
|
|
|
620 |
<table cellpadding=0 cellspacing=0>
|
|
|
621 |
<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">vd_trace_interface structure</font><hr>
|
|
|
622 |
<tr> <th align=left>Field
|
|
|
623 |
<td>
|
|
|
624 |
<th align=left>Purpose
|
|
|
625 |
<td>
|
|
|
626 |
<th align=left>Parameters
|
|
|
627 |
<tr> <td colspan=5><hr>
|
|
|
628 |
<tr> <td><b><tt>host</tt></b>
|
|
|
629 |
<td>
|
|
|
630 |
<td>A pointer to the rasterizer control block - to be provided by client application.
|
|
|
631 |
The type of the fild is client dependent.
|
|
|
632 |
<td>
|
|
|
633 |
<td>
|
|
|
634 |
<tr> <td><b><tt>scale_x, scale_y</tt></b>
|
|
|
635 |
<td>
|
|
|
636 |
<td>Scale of debugee coordinate to window coordinate mapping - internal work data, don't change.
|
|
|
637 |
<td>
|
|
|
638 |
<td>
|
|
|
639 |
<tr> <td><b><tt>orig_x, orig_y</tt></b>
|
|
|
640 |
<td>
|
|
|
641 |
<td>Draft origin in debugee coordinates - internal work data, don't change.
|
|
|
642 |
<td>
|
|
|
643 |
<td>
|
|
|
644 |
<tr> <td><b><tt>shift_x, shift_y</tt></b>
|
|
|
645 |
<td>
|
|
|
646 |
<td>Draft shift in window coordinates - internal work data, don't change.
|
|
|
647 |
<td>
|
|
|
648 |
<td>
|
|
|
649 |
<tr> <td><b><tt>get_size_x(I)</tt></b>
|
|
|
650 |
<td>
|
|
|
651 |
<td>Get window width in pixels.
|
|
|
652 |
<td>
|
|
|
653 |
<td>
|
|
|
654 |
<tr> <td><b><tt>get_size_y(I)</tt></b>
|
|
|
655 |
<td>
|
|
|
656 |
<td>Get window height in pixels.
|
|
|
657 |
<td>
|
|
|
658 |
<td>
|
|
|
659 |
<tr> <td><b><tt>get_dc(I,I1)</tt></b>
|
|
|
660 |
<td>
|
|
|
661 |
<td>Obtain drawing context.
|
|
|
662 |
<td>
|
|
|
663 |
<td>Pointer to interface block, and pointer to copy of the pointer.
|
|
|
664 |
Implementation must set *I1 if it succeeds to get a drawing context.
|
|
|
665 |
<tr> <td><b><tt>release_dc(I,I1)</tt></b>
|
|
|
666 |
<td>
|
|
|
667 |
<td>Release drawing context.
|
|
|
668 |
<td>
|
|
|
669 |
<td>Pointer to interface block, and pointer to copy of the pointer.
|
|
|
670 |
Implementation must reset *I1 if it succeeds to release the drawing context.
|
|
|
671 |
<tr> <td><b><tt>erase(I,c)</tt></b>
|
|
|
672 |
<td>
|
|
|
673 |
<td>Erase entire window.
|
|
|
674 |
<td>
|
|
|
675 |
<td>Background color.
|
|
|
676 |
<tr> <td><b><tt>beg_path(I)</tt></b>
|
|
|
677 |
<td>
|
|
|
678 |
<td>Begin path construction.
|
|
|
679 |
<td>
|
|
|
680 |
<td>
|
|
|
681 |
<tr> <td><b><tt>end_path(I)</tt></b>
|
|
|
682 |
<td>
|
|
|
683 |
<td>End path construction.
|
|
|
684 |
<td>
|
|
|
685 |
<td>
|
|
|
686 |
<tr> <td><b><tt>moveto(I,x,y)</tt></b>
|
|
|
687 |
<td>
|
|
|
688 |
<td>Set current point.
|
|
|
689 |
<td>
|
|
|
690 |
<td>A point in window coordinates.
|
|
|
691 |
<tr> <td><b><tt>lineto(I,x,y)</tt></b>
|
|
|
692 |
<td>
|
|
|
693 |
<td>Line from current point to specified point.
|
|
|
694 |
<td>
|
|
|
695 |
<td>A point in window coordinates.
|
|
|
696 |
<tr> <td><b><tt>curveto(I,x0,y0,x1,y1,x2,y2)</tt></b>
|
|
|
697 |
<td>
|
|
|
698 |
<td>Curve from current point with specified poles to specified point.
|
|
|
699 |
<td>
|
|
|
700 |
<td>3 points in window coordinates.
|
|
|
701 |
<tr> <td><b><tt>closepath(I)</tt></b>
|
|
|
702 |
<td>
|
|
|
703 |
<td>Close the path.
|
|
|
704 |
<td>
|
|
|
705 |
<td>
|
|
|
706 |
<tr> <td><b><tt>circle(I,x,y,r)</tt></b>
|
|
|
707 |
<td>
|
|
|
708 |
<td>Circle.
|
|
|
709 |
<td>
|
|
|
710 |
<td>Center and radius, window coordinates.
|
|
|
711 |
<tr> <td><b><tt>round(I,x,y,r)</tt></b>
|
|
|
712 |
<td>
|
|
|
713 |
<td>Filled circle.
|
|
|
714 |
<td>
|
|
|
715 |
<td>Center and radius, window coordinates.
|
|
|
716 |
<tr> <td><b><tt>fill(I)</tt></b>
|
|
|
717 |
<td>
|
|
|
718 |
<td>Fill the path.
|
|
|
719 |
<td>
|
|
|
720 |
<td>
|
|
|
721 |
<tr> <td><b><tt>stroke(I)</tt></b>
|
|
|
722 |
<td>
|
|
|
723 |
<td>Stroke the path.
|
|
|
724 |
<td>
|
|
|
725 |
<td>
|
|
|
726 |
<tr> <td><b><tt>setcolor(I,c)</tt></b>
|
|
|
727 |
<td>
|
|
|
728 |
<td>Set color.
|
|
|
729 |
<td>
|
|
|
730 |
<td>An integer, consisting of red, green, blue bytes.
|
|
|
731 |
<tr> <td><b><tt>setlinewidth(I,w)</tt></b>
|
|
|
732 |
<td>
|
|
|
733 |
<td>Set line width.
|
|
|
734 |
<td>
|
|
|
735 |
<td>Line width in pixels.
|
|
|
736 |
<tr> <td><b><tt>text(I,x,y,s)</tt></b>
|
|
|
737 |
<td>
|
|
|
738 |
<td>Draw a text.
|
|
|
739 |
<td>
|
|
|
740 |
<td>Coodrinates in pixels, and a string.
|
|
|
741 |
<tr> <td><b><tt>wait(I)</tt></b>
|
|
|
742 |
<td>
|
|
|
743 |
<td>Delay execution untill resume command is inputted from user.
|
|
|
744 |
<td>
|
|
|
745 |
<td>
|
|
|
746 |
</table>
|
|
|
747 |
|
|
|
748 |
|
|
|
749 |
|
|
|
750 |
<p>
|
|
|
751 |
<hr>
|
|
|
752 |
|
|
|
753 |
<h2><a name="Full_example"></a>A full example</h2>
|
|
|
754 |
|
|
|
755 |
<p>
|
|
|
756 |
The file <b><tt>gslib.c</tt></b> in the Ghostscript fileset is a complete
|
|
|
757 |
example program that initializes the library and produces output using it;
|
|
|
758 |
files named <b><tt>*lib.mak</tt></b> (such as <b><tt>ugcclib.mak</tt></b>
|
|
|
759 |
and <b><tt>bclib.mak</tt></b>) are makefiles using <b><tt>gslib.c</tt></b>
|
|
|
760 |
as the main program. The following annotated excerpts from this file are
|
|
|
761 |
intended to provide a roadmap for applications that call the library.
|
|
|
762 |
|
|
|
763 |
<blockquote><pre>/* Capture stdin/out/err before gs.h redefines them. */
|
|
|
764 |
#include <stdio.h>
|
|
|
765 |
static FILE *real_stdin, *real_stdout, *real_stderr;
|
|
|
766 |
static void
|
|
|
767 |
get_real(void)
|
|
|
768 |
{ real_stdin = stdin, real_stdout = stdout, real_stderr = stderr;
|
|
|
769 |
}</pre></blockquote>
|
|
|
770 |
|
|
|
771 |
<p>
|
|
|
772 |
Any application using Ghostscript should include the fragment above at the
|
|
|
773 |
very beginning of the main program.
|
|
|
774 |
|
|
|
775 |
<blockquote><pre>#include "gx.h"</pre></blockquote>
|
|
|
776 |
|
|
|
777 |
<p>
|
|
|
778 |
The <b><tt>gx.h</tt></b> header includes a wealth of declarations related
|
|
|
779 |
to the Ghostscript memory manager, portability machinery, debugging
|
|
|
780 |
framework, and other substrate facilities. Any application file that calls
|
|
|
781 |
any Ghostscript API functions should probably include <b><tt>gx.h</tt></b>.
|
|
|
782 |
|
|
|
783 |
<blockquote><pre>/* Configuration information imported from gconfig.c. */
|
|
|
784 |
extern gx_device *gx_device_list[];
|
|
|
785 |
|
|
|
786 |
/* Other imported procedures */
|
|
|
787 |
/* from gsinit.c */
|
|
|
788 |
extern void gs_lib_init(P1(FILE *));
|
|
|
789 |
extern void gs_lib_finit(P2(int, int));
|
|
|
790 |
/* from gsalloc.c */
|
|
|
791 |
extern gs_ref_memory_t *ialloc_alloc_state(P2(gs_memory_t *, uint));</pre></blockquote>
|
|
|
792 |
|
|
|
793 |
<p>
|
|
|
794 |
The externs above are needed for initializing the library.
|
|
|
795 |
|
|
|
796 |
<blockquote><pre> gs_ref_memory_t *imem;
|
|
|
797 |
#define mem ((gs_memory_t *)imem)
|
|
|
798 |
gs_state *pgs;
|
|
|
799 |
gx_device *dev = gx_device_list[0];
|
|
|
800 |
|
|
|
801 |
gp_init();
|
|
|
802 |
get_real();
|
|
|
803 |
gs_stdin = real_stdin;
|
|
|
804 |
gs_stdout = real_stdout;
|
|
|
805 |
gs_stderr = real_stderr;
|
|
|
806 |
gs_lib_init(stdout);
|
|
|
807 |
....
|
|
|
808 |
imem = ialloc_alloc_state(&gs_memory_default, 20000);
|
|
|
809 |
imem->space = 0;
|
|
|
810 |
....
|
|
|
811 |
pgs = gs_state_alloc(mem);</pre></blockquote>
|
|
|
812 |
|
|
|
813 |
<p>
|
|
|
814 |
The code above initializes the library and its memory manager. <b><tt>pgs</tt></b> now
|
|
|
815 |
points to the graphics state that will be passed to the drawing routines in
|
|
|
816 |
the library.
|
|
|
817 |
|
|
|
818 |
<blockquote><pre> gs_setdevice_no_erase(pgs, dev); /* can't erase yet */
|
|
|
819 |
{ gs_point dpi;
|
|
|
820 |
gs_screen_halftone ht;
|
|
|
821 |
gs_dtransform(pgs, 72.0, 72.0, &dpi);
|
|
|
822 |
ht.frequency = min(fabs(dpi.x), fabs(dpi.y)) / 16.001;
|
|
|
823 |
ht.angle = 0;
|
|
|
824 |
ht.spot_function = odsf;
|
|
|
825 |
gs_setscreen(pgs, &ht);
|
|
|
826 |
}</pre></blockquote>
|
|
|
827 |
|
|
|
828 |
<p>
|
|
|
829 |
The code above initializes the default device and sets a default halftone
|
|
|
830 |
screen. (For brevity, we have omitted the definition of odsf, the spot
|
|
|
831 |
function.)
|
|
|
832 |
|
|
|
833 |
<blockquote><pre> /* gsave and grestore (among other places) assume that */
|
|
|
834 |
/* there are at least 2 gstates on the graphics stack. */
|
|
|
835 |
/* Ensure that now. */
|
|
|
836 |
gs_gsave(pgs);</pre></blockquote>
|
|
|
837 |
|
|
|
838 |
<p>
|
|
|
839 |
The call above completes initializing the graphics state. When the program
|
|
|
840 |
is finished, it should execute:
|
|
|
841 |
|
|
|
842 |
<blockquote><pre> gs_lib_finit(0, 0);</pre></blockquote>
|
|
|
843 |
|
|
|
844 |
<!-- [2.0 end contents] ==================================================== -->
|
|
|
845 |
|
|
|
846 |
<!-- [3.0 begin visible trailer] =========================================== -->
|
|
|
847 |
<hr>
|
|
|
848 |
|
|
|
849 |
<p>
|
|
|
850 |
<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises.
|
|
|
851 |
All rights reserved.</small>
|
|
|
852 |
|
|
|
853 |
<p>
|
|
|
854 |
This software is provided AS-IS with no warranty, either express or
|
|
|
855 |
implied.
|
|
|
856 |
|
|
|
857 |
This software is distributed under license and may not be copied,
|
|
|
858 |
modified or distributed except as expressly authorized under the terms
|
|
|
859 |
of the license contained in the file LICENSE in this distribution.
|
|
|
860 |
|
|
|
861 |
For more information about licensing, please refer to
|
|
|
862 |
http://www.ghostscript.com/licensing/. For information on
|
|
|
863 |
commercial licensing, go to http://www.artifex.com/licensing/ or
|
|
|
864 |
contact Artifex Software, Inc., 101 Lucas Valley Road #110,
|
|
|
865 |
San Rafael, CA 94903, U.S.A., +1(415)492-9861.
|
|
|
866 |
|
|
|
867 |
<p>
|
|
|
868 |
<small>Ghostscript version 8.53, 20 October 2005
|
|
|
869 |
|
|
|
870 |
<!-- [3.0 end visible trailer] ============================================= -->
|
|
|
871 |
|
|
|
872 |
</body>
|
|
|
873 |
</html>
|