summaryrefslogtreecommitdiff
path: root/Master/xemtex/doc/ghostscript/API.htm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/xemtex/doc/ghostscript/API.htm')
-rw-r--r--Master/xemtex/doc/ghostscript/API.htm671
1 files changed, 671 insertions, 0 deletions
diff --git a/Master/xemtex/doc/ghostscript/API.htm b/Master/xemtex/doc/ghostscript/API.htm
new file mode 100644
index 00000000000..01eff34f577
--- /dev/null
+++ b/Master/xemtex/doc/ghostscript/API.htm
@@ -0,0 +1,671 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<title>The Ghostscript Interpreter Application Programming Interface (API)</title>
+<!-- $Id: API.htm,v 1.11.2.13.2.6 2003/05/17 14:38:59 giles Exp $ -->
+<!-- Supercedes the API in DLL.htm -->
+<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
+</head>
+
+<body>
+<!-- [1.0 begin visible header] ============================================ -->
+
+<!-- [1.1 begin headline] ================================================== -->
+
+<h1>The Ghostscript Interpreter Application Programming Interface (API)</h1>
+
+<!-- [1.1 end headline] ==================================================== -->
+
+<!-- [1.2 begin table of contents] ========================================= -->
+
+<h2>Table of contents</h2>
+
+<ul>
+<li><a href="#API">What is the Ghostscript Interpreter API?</a>
+<li><a href="#Exported_functions ">Exported functions</a>
+<ul>
+<li><a href="#revision"><b><tt>gsapi_revision</tt></b></a>
+<li><a href="#new_instance"><b><tt>gsapi_new_instance</tt></b></a>
+<li><a href="#delete_instance"><b><tt>gsapi_delete_instance</tt></b></a>
+<li><a href="#set_stdio"><b><tt>gsapi_set_stdio</tt></b></a>
+<li><a href="#set_poll"><b><tt>gsapi_set_poll</tt></b></a>
+<li><a href="#set_display_callback"><b><tt>gsapi_set_display_callback</tt></b></a>
+<li><a href="#init"><b><tt>gsapi_init_with_args</tt></b></a>
+<li><a href="#run"><b><tt>gsapi_run_*</tt></b></a>
+<li><a href="#exit"><b><tt>gsapi_exit</tt></b></a>
+<li><a href="#return_codes">Return codes</a>
+</ul>
+<li><a href="#Example_usage">Example usage</a>
+<li><a href="#stdio">Standard input and output</a>
+<li><a href="#display">Display device</a>
+</ul>
+
+<!-- [1.2 end table of contents] =========================================== -->
+
+<!-- [1.3 begin hint] ====================================================== -->
+
+<p>For other information, see the <a href="Readme.htm">Ghostscript
+overview</a>.
+
+<p>
+<b>WARNING:</b> The API described in this document is subject to changes in
+future releases, possibly ones that are not backward compatible with what
+is described here.
+
+<!-- [1.3 end hint] ======================================================== -->
+
+<hr>
+
+<!-- [1.0 end visible header] ============================================== -->
+
+<!-- [2.0 begin contents] ================================================== -->
+
+
+<h2><a name="API"></a>What is the Ghostscript Interpreter API?</h2>
+
+<p>
+The Ghostscript interpreter can be built as a dynamic link library
+(DLL) on the Windows or OS/2 platforms, as a shared object on the
+GNU/Linux platform and as a framework on MacOS X.
+With some changes, it could be built as a static library.
+This document describes the Application Programming Interface (API)
+for the Ghostscript interpreter library.
+This should not be confused with the
+<a href="Lib.htm">Ghostscript library</a> which provides a graphics
+library but not the interpreter.
+<p>
+This supercedes the old <a href="DLL.htm">DLL</a> interface.
+<p>
+To provide the interface described in the
+<a href="Use.htm">usage documentation</a>, a smaller independent
+executable loads the DLL/shared object.
+This executable provides all the interaction with the windowing system,
+including image windows and, if necessary, a text window.
+
+<p>
+The Ghostscript interpreter library's name and characteristics differ
+for each platform:
+
+<ul>
+<li>The Win32 DLL <b><tt>gsdll32.dll</tt></b> has
+MULTIPLE NONSHARED data segments. Under Win32s it can be used by only one
+program at a time, but under Windows 95/98 or Windows NT it can be called by
+multiple programs simultaneously.
+
+<li>The OS/2 DLL <b><tt>gsdll2.dll</tt></b> has
+MULTIPLE NONSHARED data segments and can be called by multiple programs
+simultaneously.
+
+<li>The GNU/Linux shared object <b><tt>libgs.so</tt></b>
+can be used by multiple programs simultaneously.
+
+<li>The MacOS X <b><tt>Ghostscript.framework</tt></b> can also be used
+by multiple applications at once.
+</ul>
+
+<p>
+The source for the executable is in <b><tt>dw</tt></b>*.* (Windows),
+<b><tt>dp</tt></b>*.* (OS/2) and <b><tt>dx</tt></b>*.* (GNU/Linux).
+See these source files for examples of how to use the DLL.
+
+<p>
+The source file <tt>dxmainc.c</tt> can serve as an example of how to use the
+framework shared component on MacOS X. Just change the header includes to use
+the Ghostscript namespace:
+<blockquote><pre><tt>#include &lt;Ghostscript/errors.h&gt;
+#include &lt;Ghostscript/iapi.h&gt;</tt></pre></blockquote>
+and link with:
+<blockquote><pre><tt>cc -o gsc dxmainc.c -framework Ghostscript</tt></pre></blockquote>
+To get a useable executable. <tt>Ghostscript.framework</tt> must be properly
+installed in the search path for this to work.
+
+<p>
+At this stage, Ghostscript does not support multiple instances
+of the interpreter within a single process.
+
+<hr>
+
+<h2><a name="Exported_functions"></a>Exported functions</h2>
+
+<p>
+The functions exported by the DLL/shared object are described
+in the header file <a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>
+and are summarised below. Omitted from the summary are
+the calling convention (e.g. __stdcall), details of return
+values and error handling.
+
+
+<ul>
+<li><b><tt>
+int
+<a href="#revision">gsapi_revision</a>
+ (gsapi_revision_t *pr, int len));
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#new_instance">gsapi_new_instance</a>
+(gs_main_instance **pinstance, void *caller_handle);
+</tt></b>
+
+<li><b><tt>
+void
+<a href="#delete_instance">gsapi_delete_instance</a>
+(gs_main_instance *instance);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#set_stdio">gsapi_set_stdio</a>
+(gs_main_instance *instance,
+ int(*stdin_fn)(void *caller_handle, char *buf, int len),
+ int(*stdout_fn)(void *caller_handle, const char *str, int len),
+ int(*stderr_fn)(void *caller_handle, const char *str, int len));
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#set_poll">gsapi_set_poll</a>
+(gs_main_instance *instance, int(*poll_fn)(void *caller_handle));
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#set_display_callback">gsapi_set_display_callback</a>
+(gs_main_instance *instance, display_callback *callback);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#init">gsapi_init_with_args</a>
+(gs_main_instance *instance, int argc, char **argv);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#run">gsapi_run_string_begin</a>
+(gs_main_instance *instance, int user_errors, int *pexit_code);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#run">gsapi_run_string_continue</a>
+(gs_main_instance *instance,
+ const char *str, unsigned int length, int user_errors, int *pexit_code);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#run">gsapi_run_string_end</a>
+(gs_main_instance *instance, int user_errors, int *pexit_code);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#run">gsapi_run_string_with_length</a>
+(gs_main_instance *instance,
+ const char *str, unsigned int length, int user_errors, int *pexit_code);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#run">gsapi_run_string</a>
+(gs_main_instance *instance,
+ const char *str, int user_errors, int *pexit_code);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#run">gsapi_run_file</a>
+(gs_main_instance *instance,
+ const char *file_name, int user_errors, int *pexit_code);
+</tt></b>
+
+<li><b><tt>
+int
+<a href="#exit">gsapi_exit</a>
+(gs_main_instance *instance);
+</tt></b>
+
+</ul>
+
+<h3><a name="revision"></a><b><tt>gsapi_revision()</tt></b></h3>
+
+<blockquote>
+This function returns the revision numbers and strings of the Ghostscript
+interpreter library; you should call it before any other interpreter
+library functions to make sure that the correct version of the
+Ghostscript interpreter has been loaded.
+
+<blockquote>
+<pre>
+typedef struct gsapi_revision_s {
+ const char *product;
+ const char *copyright;
+ long revision;
+ long revisiondate;
+} gsapi_revision_t;
+gsapi_revision_t r;
+
+if (gsapi_revision(&amp;r, sizeof(r)) == 0) {
+ if (r.revision < 650)
+ printf("Need at least Ghostscript 6.50");
+}
+else {
+ printf("revision structure size is incorrect");
+}
+</pre></blockquote>
+</blockquote>
+
+
+<h3><a name="new_instance"></a><b><tt>gsapi_new_instance()</tt></b></h3>
+<blockquote>
+Create a new instance of Ghostscript.
+This instance is passed to most other gsapi functions.
+The caller_handle will be provided to callback functions.
+<b>At this stage, Ghostscript supports only one instance</b>.
+</blockquote>
+
+
+<h3><a name="delete_instance"></a><b><tt>gsapi_delete_instance()</tt></b></h3>
+<blockquote>
+Destroy an instance of Ghostscript.
+Before you call this, Ghostscript must have finished.
+If Ghostscript has been initialised, you must call
+<b><tt>gsapi_exit</tt></b> before <b><tt>gsapi_delete_instance</tt></b>.
+</blockquote>
+
+
+<h3><a name="set_stdio"></a><b><tt>gsapi_set_stdio()</tt></b></h3>
+<blockquote>
+Set the callback functions for stdio
+The stdin callback function should return the number of
+characters read, 0 for EOF, or -1 for error.
+The stdout and stderr callback functions should return
+the number of characters written.
+</blockquote>
+
+
+<h3><a name="set_poll"></a><b><tt>gsapi_set_poll()</tt></b></h3>
+<blockquote>
+Set the callback function for polling.
+This is used for handling window events or cooperative
+multitasking. This function will only be called if
+the Ghostscript interpreter was compiled with <b><tt>CHECK_INTERRUPTS</tt></b>
+as described in <b><tt><a href="../src/gpcheck.h">gpcheck.h</a></tt></b>.
+</blockquote>
+
+<h3><a name="set_display_callback"></a><b><tt>gsapi_set_display_callback()</tt></b></h3>
+<blockquote>
+Set the callback structure for the <a href="#display">display</a>
+device. If the <a href="#display">display</a> device is used,
+this must be called after
+<b><tt>gsapi_new_instance()</tt></b>
+and before <b><tt>gsapi_init_with_args()</tt></b>.
+See <b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>
+for more details.
+</blockquote>
+
+<h3><a name="init"></a><b><tt>gsapi_init_with_args()</tt></b></h3>
+<blockquote>
+Initialise the interpreter.
+This calls <b><tt>gs_main_init_with_args()</tt></b> in
+<b><tt><a href="../src/imainarg.c">imainarg.c</a></tt></b>.
+See below for <a href="#return_codes">return codes</a>.
+The arguments are the same as the "C" main function:
+argv[0] is ignored and the user supplied arguments
+are argv[1] to argv[argc-1].
+</blockquote>
+
+<h3><a name="run"></a><b><tt>gsapi_run_*()</tt></b></h3>
+<blockquote>
+The <b><tt>gsapi_run_*</tt></b> functions are like
+<b><tt>gs_main_run_*</tt></b> except that the error_object is omitted.
+If these functions return <= -100, either quit or a fatal
+error has occured. You must call <b><tt>gsapi_exit()</tt></b> next.
+The only exception is <b><tt>gsapi_run_string_continue()</tt></b>
+which will return <b><tt>e_NeedInput</tt></b> if all is well.
+See below for <a href="#return_codes">return codes</a>.
+</blockquote>
+
+<h3><a name="exit"></a><b><tt>gsapi_exit()</tt></b></h3>
+<blockquote>
+Exit the interpreter.
+This must be called on shutdown if <b><tt>gsapi_init_with_args()</tt></b>
+has been called, and just before <b><tt>gsapi_delete_instance()</tt></b>.
+</blockquote>
+
+<h3><a name="return_codes"></a>Return codes</h3>
+
+<p>
+The <b><tt>gsapi_init_with_args</tt></b>, <b><tt>gsapi_run_*</tt></b> and
+<b><tt>gsapi_exit</tt></b> functions return an integer code.
+
+<p>
+<table width="80%" align="center" cellpadding=0 cellspacing=0>
+<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Return codes from <b><tt>gsapi_*()</tt></b></font><hr>
+<tr valign=bottom>
+ <th align=left>Code
+ <td>&nbsp;&nbsp;&nbsp;&nbsp;
+ <th align=left>Status
+<tr> <td colspan=3><hr>
+<tr valign=top> <td align=left>0
+ <td>&nbsp;
+ <td>No errors
+<tr valign=top> <td align=left>e_Quit
+ <td>&nbsp;
+ <td>"<b><tt>quit</tt></b>" has been executed.
+ This is not an error.
+ <b><tt>gsapi_exit()</tt></b> must be called next.
+<tr valign=top> <td align=left>e_NeedInput
+ <td>&nbsp;
+ <td>More input is needed by
+ <b><tt>gsapi_run_string_continue()</tt></b>.
+ This is not an error.
+<tr valign=top> <td align=left>e_Info
+ <td>&nbsp;
+ <td>"<b><tt>gs -h</tt></b>" has been executed.
+ This is not an error.
+ <b><tt>gsapi_exit()</tt></b> must be called next.
+<tr valign=top> <td align=left>&lt; 0
+ <td>&nbsp;
+ <td>Error
+<tr valign=top> <td align=left>&lt;= -100
+ <td>&nbsp;
+ <td>Fatal error.
+<b><tt>gsapi_exit()</tt></b> must be called next.
+</table>
+</blockquote>
+
+<p>
+The <b><tt>gsapi_run_*()</tt></b> functions do not flush stdio.
+If you want to see output from Ghostscript you
+must do this explicitly as shown in the example below.
+
+<p>
+When executing a string with <b><tt>gsapi_run_string_*()</tt></b>,
+<b><tt>currentfile</tt></b> is the input from the string.
+Reading from <b><tt>%stdin</tt></b> uses the stdin callback.
+</blockquote>
+
+
+
+<h2><a name="Example_usage"></a>Example Usage</h2>
+Some overly simple examples of using the Ghostscript interpreter library are:
+
+<h3>Example 1</h3>
+<pre>
+/* Example of using GS DLL as a ps2pdf converter. */
+
+#ifdef _Windows
+/* Compile with:
+ * cl -D_Windows -Isrc -Febin\ps2pdf.exe ps2pdf.c bin\gsdll32.lib
+ */
+#include &lt;windows.h&gt;
+#define GSDLLEXPORT __declspec(dllimport)
+#endif
+
+#include "errors.h"
+#include "iapi.h"
+
+gs_main_instance *minst;
+
+int main(int argc, char *argv[])
+{
+ int code;
+ int exit_code;
+ const char * gsargv[10];
+ int gsargc;
+ gsargv[0] = "ps2pdf"; /* actual value doesn't matter */
+ gsargv[1] = "-dNOPAUSE";
+ gsargv[2] = "-dBATCH";
+ gsargv[3] = "-dSAFER";
+ gsargv[4] = "-sDEVICE=pdfwrite";
+ gsargv[5] = "-sOutputFile=out.pdf";
+ gsargv[6] = "-c";
+ gsargv[7] = ".setpdfwrite";
+ gsargv[8] = "-f";
+ gsargv[9] = "input.ps";
+ gsargc=10;
+
+ code = gsapi_new_instance(&minst, NULL);
+ if (code &lt; 0)
+ return 1;
+ code = gsapi_init_with_args(minst, gsargc, gsargv);
+ gsapi_exit(minst);
+
+ gsapi_delete_instance(minst);
+
+ if ((code == 0) || (code == e_Quit))
+ return 0;
+ return 1;
+}
+</pre>
+
+<h3>Example 2</h3>
+<pre>
+/* Similar to command line gs */
+
+#include &lt;stdio.h&gt;
+#include "errors.h"
+#include "iapi.h"
+
+/* stdio functions */
+static int GSDLLCALL
+gsdll_stdin(void *instance, char *buf, int len)
+{
+ int ch;
+ int count = 0;
+ while (count &lt; len) {
+ ch = fgetc(stdin);
+ if (ch == EOF)
+ return 0;
+ *buf++ = ch;
+ count++;
+ if (ch == '\n')
+ break;
+ }
+ return count;
+}
+
+static int GSDLLCALL
+gsdll_stdout(void *instance, const char *str, int len)
+{
+ fwrite(str, 1, len, stdout);
+ fflush(stdout);
+ return len;
+}
+
+static int GSDLLCALL
+gsdll_stderr(void *instance, const char *str, int len)
+{
+ fwrite(str, 1, len, stderr);
+ fflush(stderr);
+ return len;
+}
+
+gs_main_instance *minst;
+const char start_string[] = "systemdict /start get exec\n";
+
+int main(int argc, char *argv[])
+{
+ int code;
+ int exit_code;
+
+ code = gsapi_new_instance(&minst, NULL);
+ if (code < 0)
+ return 1;
+ gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr);
+ code = gsapi_init_with_args(minst, argc, argv);
+ if (code == 0)
+ code = gsapi_run_string(minst, start_string, 0, &exit_code);
+ gsapi_exit(minst);
+
+ gsapi_delete_instance(minst);
+
+ if ((code == 0) || (code == e_Quit))
+ return 0;
+ return 1;
+}
+</pre>
+
+<h3>Example 3</h3>
+
+Replace main() in either of the above with the following code,
+showing how you can feed Ghostscript piecemeal:
+<pre>
+const char *command = "1 2 add == flush\n";
+
+int main(int argc, char *argv[])
+{
+ int code;
+ int exit_code;
+
+ code = gsapi_new_instance(&minst, NULL);
+ if (code < 0)
+ return 1;
+ code = gsapi_init_with_args(minst, argc, argv);
+
+ if (code == 0) {
+ gsapi_run_string_begin(minst, 0, &exit_code);
+ gsapi_run_string_continue(minst, command, strlen(command), 0, &exit_code);
+ gsapi_run_string_continue(minst, "qu", 2, 0, &exit_code);
+ gsapi_run_string_continue(minst, "it", 2, 0, &exit_code);
+ gsapi_run_string_end(minst, 0, &exit_code);
+ }
+
+ gsapi_exit(minst);
+
+ gsapi_delete_instance(minst);
+
+ if ((code == 0) || (code == e_Quit))
+ return 0;
+ return 1;
+}
+</pre>
+
+
+<h2><a name="Multiple_threads"></a>Multiple threads</h2>
+The Ghostscript library should have been compiled with a
+thread safe run time library.
+Synchronisation of threads is entirely up to the caller.
+
+<h2><a name="stdio"></a>Standard input and output</h2>
+<p>
+When using the Ghostscript interpreter library interface, you have a
+choice of two standard input/output methods.
+<ul>
+<li>If you do nothing, the "C" stdio will be used.
+<li>If you use <b><tt>gsapi_set_stdio()</tt></b>, all stdio will
+ be redirected to the callback functions you provide.
+ This would be used in a graphical user interface environment
+ where stdio is not available, or where you wish to process
+ Ghostscript input or output.
+</ul>
+<p>
+The callback functions are described in
+<a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>.
+
+
+<h2><a name="display"></a>Display device</h2>
+<p>
+The <b><tt>display</tt></b> device is available for use with
+the Ghostscript interpreter library. This is described in the file
+<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>.
+This device provides you with access to the raster output of
+Ghostscript. It is your responsibility to copy this raster
+to a display window or printer.
+<p>
+To use this device, you must provide a callback structure
+with addresses of a number of callback functions.
+The address of the callback structure is provided using
+<b><tt>gsapi_set_display_callback()</tt></b>.
+This must be called after
+<b><tt>gsapi_new_instance()</tt></b>
+and before
+<b><tt>gsapi_init_with_args()</tt></b>.
+<p>
+The callbacks are for device open, close, resize, sync, page,
+memory allocation and updating.
+Each callback function contains a handle can be set using
+<blockquote>
+ -dDisplayHandle=1234
+</blockquote>
+<p>
+The device raster format can be configured using
+<blockquote>
+ -dDisplayFormat=NNNN
+</blockquote>
+Options include
+<ul>
+<li> native, gray, RGB or CMYK color spaces.
+<li> alpha byte (ignored).
+<li> 1 to 16 bits/component.
+<li> bigendian (RGB) or littleendian (BGR) order.
+<li> top first or bottom first raster.
+<li> 16 bits/pixel with 555 or 565 bitfields.
+</ul>
+The format values are described in
+<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>.
+The format is flexible enough to support common Windows, OS/2, GNU/Linux
+and Mac raster formats. To select the display device with a
+Windows 24-bit RGB raster:
+<pre>
+ char **nargv;
+ char arg1[64];
+ char arg2[64];
+ char arg3[64];
+ code = gsapi_new_instance(&minst, NULL);
+ gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr);
+ code = gsapi_set_display_callback(minst, &display_callback);
+ sprintf(arg1, "-sDEVICE=display");
+ sprintf(arg2, "-dDisplayHandle=%d", 0);
+ sprintf(arg3, "-dDisplayFormat=%d",
+ DISPLAY_COLORS_RGB | DISPLAY_ALPHA_NONE | DISPLAY_DEPTH_8 |
+ DISPLAY_LITTLEENDIAN | DISPLAY_BOTTOMFIRST);
+ nargv = (char **)malloc((argc + 4) * sizeof(char *));
+ nargv[0] = argv[0];
+ nargv[1] = arg1;
+ nargv[2] = arg2;
+ nargv[3] = arg3;
+ memcpy(nargv + 4, argv + 1, argc * sizeof(char *));
+ argc += 3;
+ code = gsapi_init_with_args(minst, argc, nargv);
+</pre>
+
+<p>
+The display device provides you with the address and size of the
+raster using the <b><tt>display_size()</tt></b> callback.
+You are then responsible for displaying this raster.
+Some examples are in
+<b><tt><a href="../src/dwmain.c">dwmain.c</a></tt></b> (Windows),
+<b><tt><a href="../src/dpmain.c">dpmain.c</a></tt></b> (OS/2) and
+<b><tt><a href="../src/dxmain.c">dxmain.c</a></tt></b> (X11/GNU/Linux).
+
+<p>
+
+<!-- [2.0 end contents] ==================================================== -->
+
+<!-- [3.0 begin visible trailer] =========================================== -->
+<hr>
+
+
+<p>
+<small>Copyright &copy; 2001 artofcode LLC. All rights reserved.</small>
+
+<p>
+This software is provided AS-IS with no warranty, either express or
+implied.
+
+This software is distributed under license and may not be copied,
+modified or distributed except as expressly authorized under the terms
+of the license contained in the file LICENSE in this distribution.
+
+<p>
+<small>Ghostscript version 7.07, 17 May 2003
+
+
+<!-- [3.0 end visible trailer] ============================================= -->
+
+</body>
+</html>