diff options
Diffstat (limited to 'Master/xemtex/doc/ghostscript/API.htm')
-rw-r--r-- | Master/xemtex/doc/ghostscript/API.htm | 671 |
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 <Ghostscript/errors.h> +#include <Ghostscript/iapi.h></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(&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> + <th align=left>Status +<tr> <td colspan=3><hr> +<tr valign=top> <td align=left>0 + <td> + <td>No errors +<tr valign=top> <td align=left>e_Quit + <td> + <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> + <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> + <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>< 0 + <td> + <td>Error +<tr valign=top> <td align=left><= -100 + <td> + <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 <windows.h> +#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 < 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 <stdio.h> +#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 < 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 © 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> |