1
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
4
<meta http-equiv="content-type" content="text/html; charset=us-ascii">
4
5
<title>The Ghostscript library</title>
5
<!-- $Id: Lib.htm 12320 2011-03-30 08:51:40Z chrisl $ -->
6
7
<!-- Originally: lib.txt -->
7
8
<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
72
73
The highest level of the library, which is the one that most clients will
73
74
use, directly implements the PostScript graphics operators with procedures
74
named <code>gs_XXX</code>, for instance <b><tt>gs_moveto</tt></b> and
75
named <code>gs_XXX</code>, for instance <code>gs_moveto</code> and
75
76
<code>gs_fill</code>. Nearly all of these procedures take graphics
76
77
state objects as their first arguments, such as
100
101
There are slight differences in the operators that return multiple values,
101
102
since C's provisions for this are awkward. Also, the control structure for
102
103
the operators involving callback procedures (<code>pathforall</code>,
103
<code>image</code>, <b><tt>colorimage</tt></b>,
104
<code>image</code>, <code>colorimage</code>,
104
105
<code>imagemask</code>) is partly inverted: the client calls a procedure
105
106
to set up an enumerator object, and then calls another procedure for each
106
107
iteration. The <code>...show</code> operators,
107
<code>charpath</code>, and <b><tt>stringwidth</tt></b> also use an
108
<code>charpath</code>, and <code>stringwidth</code> also use an
108
109
inverted control structure.
110
111
<blockquote><table cellpadding=0 cellspacing=0>
117
118
<tr> <td colspan=5><hr>
118
119
<tr valign=top> <td>Graphics state -- device-independent
120
<td><code>gscolor.h</code>(<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><code>gscolor.h</code>(<code>gsstate.h</code>)<br><code>gscolor1.h</code><br><code>gscolor2.h</code><br><code>gscspace.h</code><br><code>gshsb.h</code><br><code>gsline.h</code>(<code>gsstate.h</code>)<br><code>gsstate.h</code>
124
125
<tr valign=top> <td>Graphics state -- device-dependent
126
<td><code>gscolor.h</code>(<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><code>gscolor.h</code>(<code>gsstate.h</code>)<br><code>gscolor1.h</code><br><code>gscolor2.h</code><br><code>gsht.h</code>(<code>gsht1.h</code>,<code>gsstate.h</code>)<br><code>gsht1.h</code><br><code>gsline.h</code>(<code>gsstate.h</code>)
130
131
<tr valign=top> <td>Coordinate system and matrix
132
<td><code>gscoord.h</code><br><b><tt>gsmatrix.h</tt></b>
133
<td><code>gscoord.h</code><br><code>gsmatrix.h</code>
134
<td><code>*matrix</code>, <b><tt>*identmatrix</tt></b>, <b><tt>*concatmatrix</tt></b>, <b><tt>*invertmatrix</tt></b>
135
<td><code>*matrix</code>, <code>*identmatrix</code>, <code>*concatmatrix</code>, <code>*invertmatrix</code>
136
137
<tr valign=top> <td>Path construction
138
<td><code>gspath.h</code><br><b><tt>gspath2.h</tt></b>
139
<td><code>gspath.h</code><br><code>gspath2.h</code>
140
<td><code>*arct</code>, <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
<td><code>*arct</code>, <code>*pathforall</code>, <code>ustrokepath</code>, <code>uappend</code>, <code>upath</code>, <code>ucache</code>
142
143
<tr valign=top> <td>Painting
144
<td><code>gsimage.h</code><br><b><tt>gspaint.h</tt></b><br><b><tt>gspath2.h</tt></b>
145
<td><code>gsimage.h</code><br><code>gspaint.h</code><br><code>gspath2.h</code>
146
<td><code>*image</code>, <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
<td><code>*image</code>, <code>*colorimage</code>, <code>*imagemask</code>, <code>ufill</code>, <code>ueofill</code>, <code>ustroke</code>
148
149
<tr valign=top> <td>Form and pattern
156
157
<td><code>gsdevice.h</code>
158
<td><code>*showpage</code>, <b><tt>*set</tt></b>/<b><tt>currentpagedevice</tt></b>
159
<td><code>*showpage</code>, <code>*set</code>/<code>currentpagedevice</code>
160
161
<tr valign=top> <td>Character and font
162
<td><code>gschar.h</code><br><b><tt>gsfont.h</tt></b>
163
<td><code>gschar.h</code><br><code>gsfont.h</code>
164
<td>*(all the <code>show</code> 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
<td>*(all the <code>show</code> operators), <code>definefont</code>, <code>undefinefont</code>, <code>findfont</code>, <code>*scalefont</code>, <code>*makefont</code>, <code>selectfont</code>, <code>[Global]FontDirectory</code>, <code>Standard</code>/<code>ISOLatin1Encoding</code>, <code>findencoding</code>
165
166
</table></blockquote>
214
215
<dt><code>gs_image_enum_alloc(gsimage.h)</code>
215
216
<dt><code>gs_image_init/next/cleanup(gsimage.h)</code>
216
217
<dd>Provide an "enumeration style" interface to the equivalent of
217
<code>image</code>, <b><tt>imagemask</tt></b>, and
218
<code>colorimage</code>. In the <b><tt>gs_image_t</tt></b>,
218
<code>image</code>, <code>imagemask</code>, and
219
<code>colorimage</code>. In the <code>gs_image_t</code>,
219
220
<code>ColorSpace</code> provides an explicit color space, rather than
220
221
using the current color space in the graphics state;
221
<code>ImageMask</code> distinguishes <b><tt>imagemask</tt></b> from
222
<code>ImageMask</code> distinguishes <code>imagemask</code> from
222
223
<code>[color]image</code>.
253
254
<td><code>gsfont.h</code>
255
<td><code>cachestatus</code>, <b><tt>setcachelimit</tt></b>, <b><tt>*set/currentcacheparams</tt></b>
256
<td><code>cachestatus</code>, <code>setcachelimit</code>, <code>*set/currentcacheparams</code>
256
257
<tr valign=top> <td>Display PostScript
258
259
<td><code>gsstate.h</code>
309
310
<td>The allocator to use for allocating the saved data for the
310
311
<code>Pattern</code> color. If this is
311
<code>NULL</code>, <b><tt>gs_makepattern</tt></b> uses the
312
<code>NULL</code>, <code>gs_makepattern</code> uses the
312
313
same allocator that allocated the graphics state. Library
313
314
clients should probably always use <code>NULL</code>.
318
319
The <code>gs_client_pattern</code> structure defined in
319
<code>gscolor2.h</code> corresponds to the <b><tt>Pattern</tt></b>
320
<code>gscolor2.h</code> corresponds to the <code>Pattern</code>
320
321
dictionary that is the argument to the PostScript language
321
322
<code>makepattern</code> operator. This structure has one extra member,
322
323
<code>void *client_data</code>, which is a place for clients to
341
342
The normal way to set a <code>Pattern</code> color is to call
342
343
<code>gs_setpattern</code> with the graphics state and with the
343
<code>gs_client_color</code> returned by <b><tt>gs_makepattern</tt></b>.
344
<code>gs_client_color</code> returned by <code>gs_makepattern</code>.
344
345
After that, one can use <code>gs_setcolor</code> to set further
345
346
<code>Pattern</code> colors (colored, or uncolored with the same
346
347
underlying color space); the rules are the same as those in PostScript.
347
348
Note that for <code>gs_setpattern</code>, the
348
<code>paint.values</code> in the <b><tt>gs_client_color</tt></b> must be
349
<code>paint.values</code> in the <code>gs_client_color</code> must be
349
350
filled in for uncolored patterns; this corresponds to the additional
350
351
arguments for the PostScript <code>setpattern</code> operator in the
362
363
Files named <code>gx*.c</code> implement the lower level of the graphics
363
364
library. The interfaces at the <code>gx</code> level are less stable,
364
365
and expose more of the implementation detail, than those at the
365
<code>gs</code> level: in particular, the <b><tt>gx</tt></b> interfaces
366
<code>gs</code> level: in particular, the <code>gx</code> interfaces
366
367
generally use device coordinates in an internal fixed-point representation,
367
368
as opposed to the <code>gs</code> interfaces that use floating point
368
369
user coordinates. Named entities at this level begin with
369
370
<code>gx_</code>.
372
Files named <code>gz*.c</code> and <b><tt>gz*.h</tt></b> are internal to
373
Files named <code>gz*.c</code> and <code>gz*.h</code> are internal to
373
374
the Ghostscript implementation, and are not designed to be called by
757
758
The file <code>gslib.c</code> in the Ghostscript fileset is a complete
758
759
example program that initializes the library and produces output using it;
759
files named <code>*lib.mak</code> (such as <b><tt>ugcclib.mak</tt></b>
760
and <code>bclib.mak</code>) are makefiles using <b><tt>gslib.c</tt></b>
760
files named <code>*lib.mak</code> (such as <code>ugcclib.mak</code>
761
and <code>bclib.mak</code>) are makefiles using <code>gslib.c</code>
761
762
as the main program. The following annotated excerpts from this file are
762
763
intended to provide a roadmap for applications that call the library.
861
862
San Rafael, CA 94903, U.S.A., +1(415)492-9861, for further information.
864
<small>Ghostscript version 9.02, 30 March 2011
865
<small>Ghostscript version 9.02, 30 March 2011</small>
866
867
<!-- [3.0 end visible trailer] ============================================= -->
added
removed
doc/Lib.htm
