| 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 Interpreter Application Programming Interface (API)</title>
|
|
|
5 |
<!-- $Id: API.htm,v 1.53 2005/10/20 19:46:22 ray Exp $ -->
|
|
|
6 |
<!-- Supercedes the API in DLL.htm -->
|
|
|
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 Interpreter Application Programming Interface (API)</h1>
|
|
|
16 |
|
|
|
17 |
<!-- [1.1 end headline] ==================================================== -->
|
|
|
18 |
|
|
|
19 |
<!-- [1.2 begin table of contents] ========================================= -->
|
|
|
20 |
|
|
|
21 |
<h2>Table of contents</h2>
|
|
|
22 |
|
|
|
23 |
<ul>
|
|
|
24 |
<li><a href="#API">What is the Ghostscript Interpreter API?</a>
|
|
|
25 |
<li><a href="#Exported_functions ">Exported functions</a>
|
|
|
26 |
<ul>
|
|
|
27 |
<li><a href="#revision"><b><tt>gsapi_revision</tt></b></a>
|
|
|
28 |
<li><a href="#new_instance"><b><tt>gsapi_new_instance</tt></b></a>
|
|
|
29 |
<li><a href="#delete_instance"><b><tt>gsapi_delete_instance</tt></b></a>
|
|
|
30 |
<li><a href="#set_stdio"><b><tt>gsapi_set_stdio</tt></b></a>
|
|
|
31 |
<li><a href="#set_poll"><b><tt>gsapi_set_poll</tt></b></a>
|
|
|
32 |
<li><a href="#set_display_callback"><b><tt>gsapi_set_display_callback</tt></b></a>
|
|
|
33 |
<li><a href="#run"><b><tt>gsapi_run_string_begin</tt></b></a>
|
|
|
34 |
<li><a href="#run"><b><tt>gsapi_run_string_continue</tt></b></a>
|
|
|
35 |
<li><a href="#run"><b><tt>gsapi_run_string_end</tt></b></a>
|
|
|
36 |
<li><a href="#run"><b><tt>gsapi_run_string_with_length</tt></b></a>
|
|
|
37 |
<li><a href="#run"><b><tt>gsapi_run_string</tt></b></a>
|
|
|
38 |
<li><a href="#init"><b><tt>gsapi_init_with_args</tt></b></a>
|
|
|
39 |
<li><a href="#run"><b><tt>gsapi_run_*</tt></b></a>
|
|
|
40 |
<li><a href="#exit"><b><tt>gsapi_exit</tt></b></a>
|
|
|
41 |
<li><a href="#set_visual_tracer"><b><tt>gsapi_set_visual_tracer</tt></b></a>
|
|
|
42 |
<li><a href="#return_codes">Return codes</a>
|
|
|
43 |
</ul>
|
|
|
44 |
<li><a href="#Example_usage">Example usage</a>
|
|
|
45 |
<li><a href="#stdio">Standard input and output</a>
|
|
|
46 |
<li><a href="#display">Display device</a>
|
|
|
47 |
</ul>
|
|
|
48 |
|
|
|
49 |
<!-- [1.2 end table of contents] =========================================== -->
|
|
|
50 |
|
|
|
51 |
<!-- [1.3 begin hint] ====================================================== -->
|
|
|
52 |
|
|
|
53 |
<p>For other information, see the <a href="Readme.htm">Ghostscript
|
|
|
54 |
overview</a>.
|
|
|
55 |
|
|
|
56 |
<p>
|
|
|
57 |
<b>WARNING:</b> The API described in this document is subject to changes in
|
|
|
58 |
future releases, possibly ones that are not backward compatible with what
|
|
|
59 |
is described here.
|
|
|
60 |
|
|
|
61 |
<!-- [1.3 end hint] ======================================================== -->
|
|
|
62 |
|
|
|
63 |
<hr>
|
|
|
64 |
|
|
|
65 |
<!-- [1.0 end visible header] ============================================== -->
|
|
|
66 |
|
|
|
67 |
<!-- [2.0 begin contents] ================================================== -->
|
|
|
68 |
|
|
|
69 |
|
|
|
70 |
<h2><a name="API"></a>What is the Ghostscript Interpreter API?</h2>
|
|
|
71 |
|
|
|
72 |
<p>
|
|
|
73 |
The Ghostscript interpreter can be built as a dynamic link library
|
|
|
74 |
(DLL) on the Windows or OS/2 platforms, as a shared object on the
|
|
|
75 |
Linux platform and as a framework on MacOS X.
|
|
|
76 |
With some changes, it could be built as a static library.
|
|
|
77 |
This document describes the Application Programming Interface (API)
|
|
|
78 |
for the Ghostscript interpreter library.
|
|
|
79 |
This should not be confused with the
|
|
|
80 |
<a href="Lib.htm">Ghostscript library</a> which provides a graphics
|
|
|
81 |
library but not the interpreter.
|
|
|
82 |
<p>
|
|
|
83 |
This supercedes the old <a href="DLL.htm">DLL</a> interface.
|
|
|
84 |
<p>
|
|
|
85 |
To provide the interface described in the
|
|
|
86 |
<a href="Use.htm">usage documentation</a>, a smaller independent
|
|
|
87 |
executable loads the DLL/shared object.
|
|
|
88 |
This executable must provide all the interaction with the windowing system,
|
|
|
89 |
including image windows and, if necessary, a text window.
|
|
|
90 |
|
|
|
91 |
<p>
|
|
|
92 |
The Ghostscript interpreter library's name and characteristics differ
|
|
|
93 |
for each platform:
|
|
|
94 |
|
|
|
95 |
<ul>
|
|
|
96 |
<li>The Win32 DLL <b><tt>gsdll32.dll</tt></b> has
|
|
|
97 |
MULTIPLE NONSHARED data segments. Under Win32s it can be used by only one
|
|
|
98 |
program at a time, but under Windows 95/98 or Windows NT it can be called by
|
|
|
99 |
multiple programs simultaneously.
|
|
|
100 |
|
|
|
101 |
<li>The OS/2 DLL <b><tt>gsdll2.dll</tt></b> has
|
|
|
102 |
MULTIPLE NONSHARED data segments and can be called by multiple programs
|
|
|
103 |
simultaneously.
|
|
|
104 |
|
|
|
105 |
<li>The Linux shared object <b><tt>libgs.so</tt></b>
|
|
|
106 |
can be used by multiple programs simultaneously.
|
|
|
107 |
|
|
|
108 |
<li>The MacOS X <b><tt>Ghostscript.framework</tt></b> can also be used
|
|
|
109 |
by multiple applications at once.
|
|
|
110 |
</ul>
|
|
|
111 |
|
|
|
112 |
<p>
|
|
|
113 |
The source for the executable is in <b><tt>dw</tt></b>*.* (Windows),
|
|
|
114 |
<b><tt>dp</tt></b>*.* (OS/2) and <b><tt>dx</tt></b>*.* (Linux).
|
|
|
115 |
See these source files for examples of how to use the DLL. A similar
|
|
|
116 |
example for MacOS using the Carbon API is provided in <b><tt>dm</tt></b>*.*.
|
|
|
117 |
|
|
|
118 |
<p>
|
|
|
119 |
The source file <tt>dxmainc.c</tt> can also serve as an example of how to use the
|
|
|
120 |
framework shared component on MacOS X, providing the same command-line tool it does
|
|
|
121 |
on any linux, bsd or similar operating system. Just change the header includes to
|
|
|
122 |
use the Ghostscript namespace:
|
|
|
123 |
<blockquote><pre><tt>#include <Ghostscript/ierrors.h>
|
|
|
124 |
#include <Ghostscript/iapi.h></tt></pre></blockquote>
|
|
|
125 |
and link with:
|
|
|
126 |
<blockquote><pre><tt>cc -o gsc dxmainc.c -framework Ghostscript</tt></pre></blockquote>
|
|
|
127 |
To get a useable executable. <tt>Ghostscript.framework</tt> must be properly
|
|
|
128 |
installed in the search path for this to work.
|
|
|
129 |
|
|
|
130 |
<p>
|
|
|
131 |
At this stage, Ghostscript does not support multiple instances
|
|
|
132 |
of the interpreter within a single process.
|
|
|
133 |
|
|
|
134 |
<hr>
|
|
|
135 |
|
|
|
136 |
<h2><a name="Exported_functions"></a>Exported functions</h2>
|
|
|
137 |
|
|
|
138 |
<p>
|
|
|
139 |
The functions exported by the DLL/shared object are described
|
|
|
140 |
in the header file <a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>
|
|
|
141 |
and are summarised below. Omitted from the summary are
|
|
|
142 |
the calling convention (e.g. __stdcall), details of return
|
|
|
143 |
values and error handling.
|
|
|
144 |
|
|
|
145 |
|
|
|
146 |
<ul>
|
|
|
147 |
<li><b><tt>
|
|
|
148 |
int
|
|
|
149 |
<a href="#revision">gsapi_revision</a>
|
|
|
150 |
(gsapi_revision_t *pr, int len);
|
|
|
151 |
</tt></b>
|
|
|
152 |
|
|
|
153 |
<li><b><tt>
|
|
|
154 |
int
|
|
|
155 |
<a href="#new_instance">gsapi_new_instance</a>
|
|
|
156 |
(void **pinstance, void *caller_handle);
|
|
|
157 |
</tt></b>
|
|
|
158 |
|
|
|
159 |
<li><b><tt>
|
|
|
160 |
void
|
|
|
161 |
<a href="#delete_instance">gsapi_delete_instance</a>
|
|
|
162 |
(void *instance);
|
|
|
163 |
</tt></b>
|
|
|
164 |
|
|
|
165 |
<li><b><tt>
|
|
|
166 |
int
|
|
|
167 |
<a href="#set_stdio">gsapi_set_stdio</a>
|
|
|
168 |
(void *instance,
|
|
|
169 |
int(*stdin_fn)(void *caller_handle, char *buf, int len),
|
|
|
170 |
int(*stdout_fn)(void *caller_handle, const char *str, int len),
|
|
|
171 |
int(*stderr_fn)(void *caller_handle, const char *str, int len));
|
|
|
172 |
</tt></b>
|
|
|
173 |
|
|
|
174 |
<li><b><tt>
|
|
|
175 |
int
|
|
|
176 |
<a href="#set_poll">gsapi_set_poll</a>
|
|
|
177 |
(void *instance, int(*poll_fn)(void *caller_handle));
|
|
|
178 |
</tt></b>
|
|
|
179 |
|
|
|
180 |
<li><b><tt>
|
|
|
181 |
int
|
|
|
182 |
<a href="#set_display_callback">gsapi_set_display_callback</a>
|
|
|
183 |
(void *instance, display_callback *callback);
|
|
|
184 |
</tt></b>
|
|
|
185 |
|
|
|
186 |
<li><b><tt>
|
|
|
187 |
int
|
|
|
188 |
<a href="#init">gsapi_init_with_args</a>
|
|
|
189 |
(void *instance, int argc, char **argv);
|
|
|
190 |
</tt></b>
|
|
|
191 |
|
|
|
192 |
<li><b><tt>
|
|
|
193 |
int
|
|
|
194 |
<a href="#run">gsapi_run_string_begin</a>
|
|
|
195 |
(void *instance, int user_errors, int *pexit_code);
|
|
|
196 |
</tt></b>
|
|
|
197 |
|
|
|
198 |
<li><b><tt>
|
|
|
199 |
int
|
|
|
200 |
<a href="#run">gsapi_run_string_continue</a>
|
|
|
201 |
(void *instance,
|
|
|
202 |
const char *str, unsigned int length, int user_errors, int *pexit_code);
|
|
|
203 |
</tt></b>
|
|
|
204 |
|
|
|
205 |
<li><b><tt>
|
|
|
206 |
int
|
|
|
207 |
<a href="#run">gsapi_run_string_end</a>
|
|
|
208 |
(void *instance, int user_errors, int *pexit_code);
|
|
|
209 |
</tt></b>
|
|
|
210 |
|
|
|
211 |
<li><b><tt>
|
|
|
212 |
int
|
|
|
213 |
<a href="#run">gsapi_run_string_with_length</a>
|
|
|
214 |
(void *instance,
|
|
|
215 |
const char *str, unsigned int length, int user_errors, int *pexit_code);
|
|
|
216 |
</tt></b>
|
|
|
217 |
|
|
|
218 |
<li><b><tt>
|
|
|
219 |
int
|
|
|
220 |
<a href="#run">gsapi_run_string</a>
|
|
|
221 |
(void *instance,
|
|
|
222 |
const char *str, int user_errors, int *pexit_code);
|
|
|
223 |
</tt></b>
|
|
|
224 |
|
|
|
225 |
<li><b><tt>
|
|
|
226 |
int
|
|
|
227 |
<a href="#run">gsapi_run_file</a>
|
|
|
228 |
(void *instance,
|
|
|
229 |
const char *file_name, int user_errors, int *pexit_code);
|
|
|
230 |
</tt></b>
|
|
|
231 |
|
|
|
232 |
<li><b><tt>
|
|
|
233 |
int
|
|
|
234 |
<a href="#exit">gsapi_exit</a>
|
|
|
235 |
(void *instance);
|
|
|
236 |
</tt></b>
|
|
|
237 |
|
|
|
238 |
<li><b><tt>
|
|
|
239 |
int
|
|
|
240 |
<a href="#set_visual_tracer">gsapi_set_visual_tracer</a>
|
|
|
241 |
(gstruct vd_trace_interface_s *I);
|
|
|
242 |
</tt></b>
|
|
|
243 |
|
|
|
244 |
</ul>
|
|
|
245 |
|
|
|
246 |
<h3><a name="revision"></a><b><tt>gsapi_revision()</tt></b></h3>
|
|
|
247 |
|
|
|
248 |
<blockquote>
|
|
|
249 |
This function returns the revision numbers and strings of the Ghostscript
|
|
|
250 |
interpreter library; you should call it before any other interpreter
|
|
|
251 |
library functions to make sure that the correct version of the
|
|
|
252 |
Ghostscript interpreter has been loaded.
|
|
|
253 |
|
|
|
254 |
<blockquote>
|
|
|
255 |
<pre>
|
|
|
256 |
typedef struct gsapi_revision_s {
|
|
|
257 |
const char *product;
|
|
|
258 |
const char *copyright;
|
|
|
259 |
long revision;
|
|
|
260 |
long revisiondate;
|
|
|
261 |
} gsapi_revision_t;
|
|
|
262 |
gsapi_revision_t r;
|
|
|
263 |
|
|
|
264 |
if (gsapi_revision(&r, sizeof(r)) == 0) {
|
|
|
265 |
if (r.revision < 650)
|
|
|
266 |
printf("Need at least Ghostscript 6.50");
|
|
|
267 |
}
|
|
|
268 |
else {
|
|
|
269 |
printf("revision structure size is incorrect");
|
|
|
270 |
}
|
|
|
271 |
</pre></blockquote>
|
|
|
272 |
</blockquote>
|
|
|
273 |
|
|
|
274 |
|
|
|
275 |
<h3><a name="new_instance"></a><b><tt>gsapi_new_instance()</tt></b></h3>
|
|
|
276 |
<blockquote>
|
|
|
277 |
Create a new instance of Ghostscript.
|
|
|
278 |
This instance is passed to most other gsapi functions.
|
|
|
279 |
The caller_handle will be provided to callback functions.
|
|
|
280 |
<b>At this stage, Ghostscript supports only one instance</b>.
|
|
|
281 |
</blockquote>
|
|
|
282 |
|
|
|
283 |
|
|
|
284 |
<h3><a name="delete_instance"></a><b><tt>gsapi_delete_instance()</tt></b></h3>
|
|
|
285 |
<blockquote>
|
|
|
286 |
Destroy an instance of Ghostscript.
|
|
|
287 |
Before you call this, Ghostscript must have finished.
|
|
|
288 |
If Ghostscript has been initialised, you must call
|
|
|
289 |
<b><tt>gsapi_exit</tt></b> before <b><tt>gsapi_delete_instance</tt></b>.
|
|
|
290 |
</blockquote>
|
|
|
291 |
|
|
|
292 |
|
|
|
293 |
<h3><a name="set_stdio"></a><b><tt>gsapi_set_stdio()</tt></b></h3>
|
|
|
294 |
<blockquote>
|
|
|
295 |
Set the callback functions for stdio
|
|
|
296 |
The stdin callback function should return the number of
|
|
|
297 |
characters read, 0 for EOF, or -1 for error.
|
|
|
298 |
The stdout and stderr callback functions should return
|
|
|
299 |
the number of characters written.
|
|
|
300 |
</blockquote>
|
|
|
301 |
|
|
|
302 |
|
|
|
303 |
<h3><a name="set_poll"></a><b><tt>gsapi_set_poll()</tt></b></h3>
|
|
|
304 |
<blockquote>
|
|
|
305 |
Set the callback function for polling.
|
|
|
306 |
This is used for handling window events or cooperative
|
|
|
307 |
multitasking. This function will only be called if
|
|
|
308 |
the Ghostscript interpreter was compiled with <b><tt>CHECK_INTERRUPTS</tt></b>
|
|
|
309 |
as described in <b><tt><a href="../src/gpcheck.h">gpcheck.h</a></tt></b>.
|
|
|
310 |
The polling function should return zero if all is well,
|
|
|
311 |
and return negative if it wants ghostscript to abort.
|
|
|
312 |
The polling function must be fast.
|
|
|
313 |
</blockquote>
|
|
|
314 |
|
|
|
315 |
<h3><a name="set_display_callback"></a><b><tt>gsapi_set_display_callback()</tt></b></h3>
|
|
|
316 |
<blockquote>
|
|
|
317 |
Set the callback structure for the <a href="#display">display</a>
|
|
|
318 |
device. If the <a href="#display">display</a> device is used,
|
|
|
319 |
this must be called after
|
|
|
320 |
<b><tt>gsapi_new_instance()</tt></b>
|
|
|
321 |
and before <b><tt>gsapi_init_with_args()</tt></b>.
|
|
|
322 |
See <b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>
|
|
|
323 |
for more details.
|
|
|
324 |
</blockquote>
|
|
|
325 |
|
|
|
326 |
<h3><a name="init"></a><b><tt>gsapi_init_with_args()</tt></b></h3>
|
|
|
327 |
<blockquote>
|
|
|
328 |
Initialise the interpreter.
|
|
|
329 |
This calls <b><tt>gs_main_init_with_args()</tt></b> in
|
|
|
330 |
<b><tt><a href="../src/imainarg.c">imainarg.c</a></tt></b>.
|
|
|
331 |
See below for <a href="#return_codes">return codes</a>.
|
|
|
332 |
The arguments are the same as the "C" main function:
|
|
|
333 |
argv[0] is ignored and the user supplied arguments
|
|
|
334 |
are argv[1] to argv[argc-1].
|
|
|
335 |
</blockquote>
|
|
|
336 |
|
|
|
337 |
<h3><a name="run"></a><b><tt>gsapi_run_*()</tt></b></h3>
|
|
|
338 |
<blockquote>
|
|
|
339 |
The <b><tt>gsapi_run_*</tt></b> functions are like
|
|
|
340 |
<b><tt>gs_main_run_*</tt></b> except that the error_object is omitted.
|
|
|
341 |
If these functions return <= -100, either quit or a fatal
|
|
|
342 |
error has occured. You must call <b><tt>gsapi_exit()</tt></b> next.
|
|
|
343 |
The only exception is <b><tt>gsapi_run_string_continue()</tt></b>
|
|
|
344 |
which will return <b><tt>e_NeedInput</tt></b> if all is well.
|
|
|
345 |
See below for <a href="#return_codes">return codes</a>.
|
|
|
346 |
<p>
|
|
|
347 |
There is a 64 KB length limit on any buffer submitted to a
|
|
|
348 |
<tt>gsapi_run_*</tt> function for processing. If you have more
|
|
|
349 |
than 65535 bytes of input then you must split it into smaller
|
|
|
350 |
pieces and submit each in a separate
|
|
|
351 |
<tt>gsapi_run_string_continue()</tt> call.
|
|
|
352 |
</blockquote>
|
|
|
353 |
|
|
|
354 |
<h3><a name="exit"></a><b><tt>gsapi_exit()</tt></b></h3>
|
|
|
355 |
<blockquote>
|
|
|
356 |
Exit the interpreter.
|
|
|
357 |
This must be called on shutdown if <b><tt>gsapi_init_with_args()</tt></b>
|
|
|
358 |
has been called, and just before <b><tt>gsapi_delete_instance()</tt></b>.
|
|
|
359 |
</blockquote>
|
|
|
360 |
|
|
|
361 |
<h3><a name="set_visual_tracer"></a><b><tt>gsapi_set_visual_tracer()</tt></b></h3>
|
|
|
362 |
<blockquote>
|
|
|
363 |
Pass visual tracer interface block to Ghostscript.
|
|
|
364 |
See <a href="Lib.htm#Visual_trace"><b><tt>Lib.htm</tt></b></a> for reference about
|
|
|
365 |
the interface block structure.
|
|
|
366 |
This function is useful for debug clients only. Release clients must not call it.
|
|
|
367 |
</blockquote>
|
|
|
368 |
|
|
|
369 |
|
|
|
370 |
<h3><a name="return_codes"></a>Return codes</h3>
|
|
|
371 |
|
|
|
372 |
<p>
|
|
|
373 |
The <b><tt>gsapi_init_with_args</tt></b>, <b><tt>gsapi_run_*</tt></b> and
|
|
|
374 |
<b><tt>gsapi_exit</tt></b> functions return an integer code.
|
|
|
375 |
|
|
|
376 |
<p>
|
|
|
377 |
<table width="80%" align="center" cellpadding=0 cellspacing=0>
|
|
|
378 |
<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Return codes from <b><tt>gsapi_*()</tt></b></font><hr>
|
|
|
379 |
<tr valign=bottom>
|
|
|
380 |
<th align=left>Code
|
|
|
381 |
<td>
|
|
|
382 |
<th align=left>Status
|
|
|
383 |
<tr> <td colspan=3><hr>
|
|
|
384 |
<tr valign=top> <td align=left>0
|
|
|
385 |
<td>
|
|
|
386 |
<td>No errors
|
|
|
387 |
<tr valign=top> <td align=left>e_Quit
|
|
|
388 |
<td>
|
|
|
389 |
<td>"<b><tt>quit</tt></b>" has been executed.
|
|
|
390 |
This is not an error.
|
|
|
391 |
<b><tt>gsapi_exit()</tt></b> must be called next.
|
|
|
392 |
<tr valign=top> <td align=left>e_NeedInput
|
|
|
393 |
<td>
|
|
|
394 |
<td>More input is needed by
|
|
|
395 |
<b><tt>gsapi_run_string_continue()</tt></b>.
|
|
|
396 |
This is not an error.
|
|
|
397 |
<tr valign=top> <td align=left>e_Info
|
|
|
398 |
<td>
|
|
|
399 |
<td>"<b><tt>gs -h</tt></b>" has been executed.
|
|
|
400 |
This is not an error.
|
|
|
401 |
<b><tt>gsapi_exit()</tt></b> must be called next.
|
|
|
402 |
<tr valign=top> <td align=left>< 0
|
|
|
403 |
<td>
|
|
|
404 |
<td>Error
|
|
|
405 |
<tr valign=top> <td align=left><= -100
|
|
|
406 |
<td>
|
|
|
407 |
<td>Fatal error.
|
|
|
408 |
<b><tt>gsapi_exit()</tt></b> must be called next.
|
|
|
409 |
</table>
|
|
|
410 |
</blockquote>
|
|
|
411 |
|
|
|
412 |
<p>
|
|
|
413 |
The <b><tt>gsapi_run_*()</tt></b> functions do not flush stdio.
|
|
|
414 |
If you want to see output from Ghostscript you
|
|
|
415 |
must do this explicitly as shown in the example below.
|
|
|
416 |
|
|
|
417 |
<p>
|
|
|
418 |
When executing a string with <b><tt>gsapi_run_string_*()</tt></b>,
|
|
|
419 |
<b><tt>currentfile</tt></b> is the input from the string.
|
|
|
420 |
Reading from <b><tt>%stdin</tt></b> uses the stdin callback.
|
|
|
421 |
</blockquote>
|
|
|
422 |
|
|
|
423 |
|
|
|
424 |
|
|
|
425 |
<h2><a name="Example_usage"></a>Example Usage</h2>
|
|
|
426 |
Some overly simple examples of using the Ghostscript interpreter library
|
|
|
427 |
are below. Some more examples including other programming languages
|
|
|
428 |
may be found at
|
|
|
429 |
<a href="http://www.cs.wisc.edu/~ghost/doc/gsapi.htm">
|
|
|
430 |
http://www.cs.wisc.edu/~ghost/doc/gsapi.htm</a>.
|
|
|
431 |
|
|
|
432 |
<p>To use try out these examples in a development environment like Microsoft's
|
|
|
433 |
developer tools or Metrowerks Codewarrior, create a new project, save the example
|
|
|
434 |
source code as a <tt>.c</tt> file and add it, along with the Ghostscript dll or shared
|
|
|
435 |
library. You will also need to make sure the Ghostscript headers are available, either
|
|
|
436 |
by adding their location (the <tt>src</tt> directory in the Ghostscript source
|
|
|
437 |
distribution) to the project's search path, or by copying ierrors.h and iapi.h into the
|
|
|
438 |
same directory as the example source.</p>
|
|
|
439 |
|
|
|
440 |
<h3>Example 1</h3>
|
|
|
441 |
<pre>
|
|
|
442 |
/* Example of using GS DLL as a ps2pdf converter. */
|
|
|
443 |
|
|
|
444 |
#if defined(_WIN32) && !defined(_Windows)
|
|
|
445 |
# define _Windows
|
|
|
446 |
#endif
|
|
|
447 |
#ifdef _Windows
|
|
|
448 |
/* add this source to a project with gsdll32.dll, or compile it directly with:
|
|
|
449 |
* cl -D_Windows -Isrc -Febin\ps2pdf.exe ps2pdf.c bin\gsdll32.lib
|
|
|
450 |
*/
|
|
|
451 |
# include <windows.h>
|
|
|
452 |
# define GSDLLEXPORT __declspec(dllimport)
|
|
|
453 |
#endif
|
|
|
454 |
|
|
|
455 |
#include "ierrors.h"
|
|
|
456 |
#include "iapi.h"
|
|
|
457 |
|
|
|
458 |
void *minst;
|
|
|
459 |
|
|
|
460 |
int main(int argc, char *argv[])
|
|
|
461 |
{
|
|
|
462 |
int code, code1;
|
|
|
463 |
const char * gsargv[10];
|
|
|
464 |
int gsargc;
|
|
|
465 |
gsargv[0] = "ps2pdf"; /* actual value doesn't matter */
|
|
|
466 |
gsargv[1] = "-dNOPAUSE";
|
|
|
467 |
gsargv[2] = "-dBATCH";
|
|
|
468 |
gsargv[3] = "-dSAFER";
|
|
|
469 |
gsargv[4] = "-sDEVICE=pdfwrite";
|
|
|
470 |
gsargv[5] = "-sOutputFile=out.pdf";
|
|
|
471 |
gsargv[6] = "-c";
|
|
|
472 |
gsargv[7] = ".setpdfwrite";
|
|
|
473 |
gsargv[8] = "-f";
|
|
|
474 |
gsargv[9] = "input.ps";
|
|
|
475 |
gsargc=10;
|
|
|
476 |
|
|
|
477 |
code = gsapi_new_instance(&minst, NULL);
|
|
|
478 |
if (code < 0)
|
|
|
479 |
return 1;
|
|
|
480 |
code = gsapi_init_with_args(minst, gsargc, gsargv);
|
|
|
481 |
code1 = gsapi_exit(minst);
|
|
|
482 |
if ((code == 0) || (code == e_Quit))
|
|
|
483 |
code = code1;
|
|
|
484 |
|
|
|
485 |
gsapi_delete_instance(minst);
|
|
|
486 |
|
|
|
487 |
if ((code == 0) || (code == e_Quit))
|
|
|
488 |
return 0;
|
|
|
489 |
return 1;
|
|
|
490 |
}
|
|
|
491 |
</pre>
|
|
|
492 |
|
|
|
493 |
<h3>Example 2</h3>
|
|
|
494 |
<pre>
|
|
|
495 |
/* Similar to command line gs */
|
|
|
496 |
|
|
|
497 |
#if defined(_WIN32) && !defined(_Windows)
|
|
|
498 |
# define _Windows
|
|
|
499 |
#endif
|
|
|
500 |
#ifdef _Windows
|
|
|
501 |
/* Compile directly with:
|
|
|
502 |
* cl -D_Windows -Isrc -Febin\gstest.exe gstest.c bin\gsdll32.lib
|
|
|
503 |
*/
|
|
|
504 |
# include <windows.h>
|
|
|
505 |
# define GSDLLEXPORT __declspec(dllimport)
|
|
|
506 |
#endif
|
|
|
507 |
#include <stdio.h>
|
|
|
508 |
#include "ierrors.h"
|
|
|
509 |
#include "iapi.h"
|
|
|
510 |
|
|
|
511 |
/* stdio functions */
|
|
|
512 |
static int GSDLLCALL
|
|
|
513 |
gsdll_stdin(void *instance, char *buf, int len)
|
|
|
514 |
{
|
|
|
515 |
int ch;
|
|
|
516 |
int count = 0;
|
|
|
517 |
while (count < len) {
|
|
|
518 |
ch = fgetc(stdin);
|
|
|
519 |
if (ch == EOF)
|
|
|
520 |
return 0;
|
|
|
521 |
*buf++ = ch;
|
|
|
522 |
count++;
|
|
|
523 |
if (ch == '\n')
|
|
|
524 |
break;
|
|
|
525 |
}
|
|
|
526 |
return count;
|
|
|
527 |
}
|
|
|
528 |
|
|
|
529 |
static int GSDLLCALL
|
|
|
530 |
gsdll_stdout(void *instance, const char *str, int len)
|
|
|
531 |
{
|
|
|
532 |
fwrite(str, 1, len, stdout);
|
|
|
533 |
fflush(stdout);
|
|
|
534 |
return len;
|
|
|
535 |
}
|
|
|
536 |
|
|
|
537 |
static int GSDLLCALL
|
|
|
538 |
gsdll_stderr(void *instance, const char *str, int len)
|
|
|
539 |
{
|
|
|
540 |
fwrite(str, 1, len, stderr);
|
|
|
541 |
fflush(stderr);
|
|
|
542 |
return len;
|
|
|
543 |
}
|
|
|
544 |
|
|
|
545 |
void *minst;
|
|
|
546 |
const char start_string[] = "systemdict /start get exec\n";
|
|
|
547 |
|
|
|
548 |
int main(int argc, char *argv[])
|
|
|
549 |
{
|
|
|
550 |
int code, code1;
|
|
|
551 |
int exit_code;
|
|
|
552 |
|
|
|
553 |
code = gsapi_new_instance(&minst, NULL);
|
|
|
554 |
if (code < 0)
|
|
|
555 |
return 1;
|
|
|
556 |
gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr);
|
|
|
557 |
code = gsapi_init_with_args(minst, argc, argv);
|
|
|
558 |
if (code == 0)
|
|
|
559 |
code = gsapi_run_string(minst, start_string, 0, &exit_code);
|
|
|
560 |
code1 = gsapi_exit(minst);
|
|
|
561 |
if ((code == 0) || (code == e_Quit))
|
|
|
562 |
code = code1;
|
|
|
563 |
|
|
|
564 |
gsapi_delete_instance(minst);
|
|
|
565 |
|
|
|
566 |
if ((code == 0) || (code == e_Quit))
|
|
|
567 |
return 0;
|
|
|
568 |
return 1;
|
|
|
569 |
}
|
|
|
570 |
</pre>
|
|
|
571 |
|
|
|
572 |
<h3>Example 3</h3>
|
|
|
573 |
|
|
|
574 |
Replace main() in either of the above with the following code,
|
|
|
575 |
showing how you can feed Ghostscript piecemeal:
|
|
|
576 |
<pre>
|
|
|
577 |
const char *command = "1 2 add == flush\n";
|
|
|
578 |
|
|
|
579 |
int main(int argc, char *argv[])
|
|
|
580 |
{
|
|
|
581 |
int code, code1;
|
|
|
582 |
int exit_code;
|
|
|
583 |
|
|
|
584 |
code = gsapi_new_instance(&minst, NULL);
|
|
|
585 |
if (code < 0)
|
|
|
586 |
return 1;
|
|
|
587 |
code = gsapi_init_with_args(minst, argc, argv);
|
|
|
588 |
|
|
|
589 |
if (code == 0) {
|
|
|
590 |
gsapi_run_string_begin(minst, 0, &exit_code);
|
|
|
591 |
gsapi_run_string_continue(minst, command, strlen(command), 0, &exit_code);
|
|
|
592 |
gsapi_run_string_continue(minst, "qu", 2, 0, &exit_code);
|
|
|
593 |
gsapi_run_string_continue(minst, "it", 2, 0, &exit_code);
|
|
|
594 |
gsapi_run_string_end(minst, 0, &exit_code);
|
|
|
595 |
}
|
|
|
596 |
|
|
|
597 |
code1 = gsapi_exit(minst);
|
|
|
598 |
if ((code == 0) || (code == e_Quit))
|
|
|
599 |
code = code1;
|
|
|
600 |
|
|
|
601 |
gsapi_delete_instance(minst);
|
|
|
602 |
|
|
|
603 |
if ((code == 0) || (code == e_Quit))
|
|
|
604 |
return 0;
|
|
|
605 |
return 1;
|
|
|
606 |
}
|
|
|
607 |
</pre>
|
|
|
608 |
|
|
|
609 |
|
|
|
610 |
<h2><a name="Multiple_threads"></a>Multiple threads</h2>
|
|
|
611 |
The Ghostscript library should have been compiled with a
|
|
|
612 |
thread safe run time library.
|
|
|
613 |
Synchronisation of threads is entirely up to the caller.
|
|
|
614 |
The exported <a href="#Exported_functions "><b><tt>gsapi_*()</tt></b></a>
|
|
|
615 |
functions must be called from one thread only.
|
|
|
616 |
|
|
|
617 |
<h2><a name="stdio"></a>Standard input and output</h2>
|
|
|
618 |
<p>
|
|
|
619 |
When using the Ghostscript interpreter library interface, you have a
|
|
|
620 |
choice of two standard input/output methods.
|
|
|
621 |
<ul>
|
|
|
622 |
<li>If you do nothing, the "C" stdio will be used.
|
|
|
623 |
<li>If you use <b><tt>gsapi_set_stdio()</tt></b>, all stdio will
|
|
|
624 |
be redirected to the callback functions you provide.
|
|
|
625 |
This would be used in a graphical user interface environment
|
|
|
626 |
where stdio is not available, or where you wish to process
|
|
|
627 |
Ghostscript input or output.
|
|
|
628 |
</ul>
|
|
|
629 |
<p>
|
|
|
630 |
The callback functions are described in
|
|
|
631 |
<a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>.
|
|
|
632 |
|
|
|
633 |
|
|
|
634 |
<h2><a name="display"></a>Display device</h2>
|
|
|
635 |
<p>
|
|
|
636 |
The <b><tt>display</tt></b> device is available for use with
|
|
|
637 |
the Ghostscript interpreter library. This is described in the file
|
|
|
638 |
<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>.
|
|
|
639 |
This device provides you with access to the raster output of
|
|
|
640 |
Ghostscript. It is your responsibility to copy this raster
|
|
|
641 |
to a display window or printer.
|
|
|
642 |
<p>
|
|
|
643 |
To use this device, you must provide a callback structure
|
|
|
644 |
with addresses of a number of callback functions.
|
|
|
645 |
The address of the callback structure is provided using
|
|
|
646 |
<b><tt>gsapi_set_display_callback()</tt></b>.
|
|
|
647 |
This must be called after
|
|
|
648 |
<b><tt>gsapi_new_instance()</tt></b>
|
|
|
649 |
and before
|
|
|
650 |
<b><tt>gsapi_init_with_args()</tt></b>.
|
|
|
651 |
<p>
|
|
|
652 |
The callbacks are for device open, close, resize, sync, page,
|
|
|
653 |
memory allocation and updating.
|
|
|
654 |
Each callback function contains a handle can be set using
|
|
|
655 |
<blockquote>
|
|
|
656 |
-dDisplayHandle=1234
|
|
|
657 |
</blockquote>
|
|
|
658 |
<p>
|
|
|
659 |
The device raster format can be configured using
|
|
|
660 |
<blockquote>
|
|
|
661 |
-dDisplayFormat=NNNN
|
|
|
662 |
</blockquote>
|
|
|
663 |
Options include
|
|
|
664 |
<ul>
|
|
|
665 |
<li> native, gray, RGB, CMYK or separation color spaces.
|
|
|
666 |
<li> alpha byte (ignored).
|
|
|
667 |
<li> 1 to 16 bits/component.
|
|
|
668 |
<li> bigendian (RGB) or littleendian (BGR) order.
|
|
|
669 |
<li> top first or bottom first raster.
|
|
|
670 |
<li> 16 bits/pixel with 555 or 565 bitfields.
|
|
|
671 |
</ul>
|
|
|
672 |
The format values are described in
|
|
|
673 |
<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>.
|
|
|
674 |
The format is flexible enough to support common Windows, OS/2, Linux
|
|
|
675 |
and Mac raster formats. To select the display device with a
|
|
|
676 |
Windows 24-bit RGB raster:
|
|
|
677 |
<pre>
|
|
|
678 |
char **nargv;
|
|
|
679 |
char arg1[64];
|
|
|
680 |
char arg2[64];
|
|
|
681 |
char arg3[64];
|
|
|
682 |
code = gsapi_new_instance(&minst, NULL);
|
|
|
683 |
gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr);
|
|
|
684 |
code = gsapi_set_display_callback(minst, &display_callback);
|
|
|
685 |
sprintf(arg1, "-sDEVICE=display");
|
|
|
686 |
sprintf(arg2, "-dDisplayHandle=%d", 0);
|
|
|
687 |
sprintf(arg3, "-dDisplayFormat=%d",
|
|
|
688 |
DISPLAY_COLORS_RGB | DISPLAY_ALPHA_NONE | DISPLAY_DEPTH_8 |
|
|
|
689 |
DISPLAY_LITTLEENDIAN | DISPLAY_BOTTOMFIRST);
|
|
|
690 |
nargv = (char **)malloc((argc + 4) * sizeof(char *));
|
|
|
691 |
nargv[0] = argv[0];
|
|
|
692 |
nargv[1] = arg1;
|
|
|
693 |
nargv[2] = arg2;
|
|
|
694 |
nargv[3] = arg3;
|
|
|
695 |
memcpy(nargv + 4, argv + 1, argc * sizeof(char *));
|
|
|
696 |
argc += 3;
|
|
|
697 |
code = gsapi_init_with_args(minst, argc, nargv);
|
|
|
698 |
</pre>
|
|
|
699 |
|
|
|
700 |
<p>
|
|
|
701 |
The display device provides you with the address and size of the
|
|
|
702 |
raster using the <b><tt>display_size()</tt></b> callback.
|
|
|
703 |
You are then responsible for displaying this raster.
|
|
|
704 |
Some examples are in
|
|
|
705 |
<b><tt><a href="../src/dwmain.c">dwmain.c</a></tt></b> (Windows),
|
|
|
706 |
<b><tt><a href="../src/dpmain.c">dpmain.c</a></tt></b> (OS/2) and
|
|
|
707 |
<b><tt><a href="../src/dxmain.c">dxmain.c</a></tt></b> (X11/Linux), and
|
|
|
708 |
<b><tt><a href="../src/dmmain.c">dmmain.c</a></tt></b> (MacOS Classic or Carbon).
|
|
|
709 |
<p>
|
|
|
710 |
On some platforms, the calling convention for the display device callbacks in
|
|
|
711 |
<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>
|
|
|
712 |
is not the same as the exported
|
|
|
713 |
<a href="#Exported_functions "><b><tt>gsapi_*()</tt></b></a>
|
|
|
714 |
functions in <a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>.
|
|
|
715 |
|
|
|
716 |
<p>
|
|
|
717 |
|
|
|
718 |
<!-- [2.0 end contents] ==================================================== -->
|
|
|
719 |
|
|
|
720 |
<!-- [3.0 begin visible trailer] =========================================== -->
|
|
|
721 |
<hr>
|
|
|
722 |
|
|
|
723 |
|
|
|
724 |
<p>
|
|
|
725 |
<small>Copyright © 2000-2004 artofcode LLC. All rights reserved.</small>
|
|
|
726 |
|
|
|
727 |
<p>
|
|
|
728 |
This software is provided AS-IS with no warranty, either express or
|
|
|
729 |
implied.
|
|
|
730 |
|
|
|
731 |
This software is distributed under license and may not be copied,
|
|
|
732 |
modified or distributed except as expressly authorized under the terms
|
|
|
733 |
of the license contained in the file LICENSE in this distribution.
|
|
|
734 |
|
|
|
735 |
For more information about licensing, please refer to
|
|
|
736 |
http://www.ghostscript.com/licensing/. For information on
|
|
|
737 |
commercial licensing, go to http://www.artifex.com/licensing/ or
|
|
|
738 |
contact Artifex Software, Inc., 101 Lucas Valley Road #110,
|
|
|
739 |
San Rafael, CA 94903, U.S.A., +1(415)492-9861.
|
|
|
740 |
|
|
|
741 |
<p>
|
|
|
742 |
<small>Ghostscript version 8.53, 20 October 2005
|
|
|
743 |
|
|
|
744 |
|
|
|
745 |
<!-- [3.0 end visible trailer] ============================================= -->
|
|
|
746 |
|
|
|
747 |
</body>
|
|
|
748 |
</html>
|