13ff48bf5SDavid du Colombier<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 23ff48bf5SDavid du Colombier<html> 33ff48bf5SDavid du Colombier<head> 43ff48bf5SDavid du Colombier<title>The Ghostscript Interpreter Application Programming Interface (API)</title> 5*593dc095SDavid du Colombier<!-- $Id: API.htm,v 1.53 2005/10/20 19:46:22 ray Exp $ --> 63ff48bf5SDavid du Colombier<!-- Supercedes the API in DLL.htm --> 73ff48bf5SDavid du Colombier<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 83ff48bf5SDavid du Colombier</head> 93ff48bf5SDavid du Colombier 103ff48bf5SDavid du Colombier<body> 113ff48bf5SDavid du Colombier<!-- [1.0 begin visible header] ============================================ --> 123ff48bf5SDavid du Colombier 133ff48bf5SDavid du Colombier<!-- [1.1 begin headline] ================================================== --> 143ff48bf5SDavid du Colombier 153ff48bf5SDavid du Colombier<h1>The Ghostscript Interpreter Application Programming Interface (API)</h1> 163ff48bf5SDavid du Colombier 173ff48bf5SDavid du Colombier<!-- [1.1 end headline] ==================================================== --> 183ff48bf5SDavid du Colombier 193ff48bf5SDavid du Colombier<!-- [1.2 begin table of contents] ========================================= --> 203ff48bf5SDavid du Colombier 213ff48bf5SDavid du Colombier<h2>Table of contents</h2> 223ff48bf5SDavid du Colombier 233ff48bf5SDavid du Colombier<ul> 243ff48bf5SDavid du Colombier<li><a href="#API">What is the Ghostscript Interpreter API?</a> 253ff48bf5SDavid du Colombier<li><a href="#Exported_functions ">Exported functions</a> 263ff48bf5SDavid du Colombier<ul> 273ff48bf5SDavid du Colombier<li><a href="#revision"><b><tt>gsapi_revision</tt></b></a> 283ff48bf5SDavid du Colombier<li><a href="#new_instance"><b><tt>gsapi_new_instance</tt></b></a> 293ff48bf5SDavid du Colombier<li><a href="#delete_instance"><b><tt>gsapi_delete_instance</tt></b></a> 303ff48bf5SDavid du Colombier<li><a href="#set_stdio"><b><tt>gsapi_set_stdio</tt></b></a> 313ff48bf5SDavid du Colombier<li><a href="#set_poll"><b><tt>gsapi_set_poll</tt></b></a> 323ff48bf5SDavid du Colombier<li><a href="#set_display_callback"><b><tt>gsapi_set_display_callback</tt></b></a> 33*593dc095SDavid du Colombier<li><a href="#run"><b><tt>gsapi_run_string_begin</tt></b></a> 34*593dc095SDavid du Colombier<li><a href="#run"><b><tt>gsapi_run_string_continue</tt></b></a> 35*593dc095SDavid du Colombier<li><a href="#run"><b><tt>gsapi_run_string_end</tt></b></a> 36*593dc095SDavid du Colombier<li><a href="#run"><b><tt>gsapi_run_string_with_length</tt></b></a> 37*593dc095SDavid du Colombier<li><a href="#run"><b><tt>gsapi_run_string</tt></b></a> 383ff48bf5SDavid du Colombier<li><a href="#init"><b><tt>gsapi_init_with_args</tt></b></a> 393ff48bf5SDavid du Colombier<li><a href="#run"><b><tt>gsapi_run_*</tt></b></a> 403ff48bf5SDavid du Colombier<li><a href="#exit"><b><tt>gsapi_exit</tt></b></a> 41*593dc095SDavid du Colombier<li><a href="#set_visual_tracer"><b><tt>gsapi_set_visual_tracer</tt></b></a> 423ff48bf5SDavid du Colombier<li><a href="#return_codes">Return codes</a> 433ff48bf5SDavid du Colombier</ul> 44*593dc095SDavid du Colombier<li><a href="#Example_usage">Example usage</a> 453ff48bf5SDavid du Colombier<li><a href="#stdio">Standard input and output</a> 463ff48bf5SDavid du Colombier<li><a href="#display">Display device</a> 473ff48bf5SDavid du Colombier</ul> 483ff48bf5SDavid du Colombier 493ff48bf5SDavid du Colombier<!-- [1.2 end table of contents] =========================================== --> 503ff48bf5SDavid du Colombier 513ff48bf5SDavid du Colombier<!-- [1.3 begin hint] ====================================================== --> 523ff48bf5SDavid du Colombier 533ff48bf5SDavid du Colombier<p>For other information, see the <a href="Readme.htm">Ghostscript 543ff48bf5SDavid du Colombieroverview</a>. 553ff48bf5SDavid du Colombier 563ff48bf5SDavid du Colombier<p> 573ff48bf5SDavid du Colombier<b>WARNING:</b> The API described in this document is subject to changes in 583ff48bf5SDavid du Colombierfuture releases, possibly ones that are not backward compatible with what 593ff48bf5SDavid du Colombieris described here. 603ff48bf5SDavid du Colombier 613ff48bf5SDavid du Colombier<!-- [1.3 end hint] ======================================================== --> 623ff48bf5SDavid du Colombier 633ff48bf5SDavid du Colombier<hr> 643ff48bf5SDavid du Colombier 653ff48bf5SDavid du Colombier<!-- [1.0 end visible header] ============================================== --> 663ff48bf5SDavid du Colombier 673ff48bf5SDavid du Colombier<!-- [2.0 begin contents] ================================================== --> 683ff48bf5SDavid du Colombier 693ff48bf5SDavid du Colombier 703ff48bf5SDavid du Colombier<h2><a name="API"></a>What is the Ghostscript Interpreter API?</h2> 713ff48bf5SDavid du Colombier 723ff48bf5SDavid du Colombier<p> 733ff48bf5SDavid du ColombierThe Ghostscript interpreter can be built as a dynamic link library 743ff48bf5SDavid du Colombier(DLL) on the Windows or OS/2 platforms, as a shared object on the 753ff48bf5SDavid du ColombierLinux platform and as a framework on MacOS X. 763ff48bf5SDavid du ColombierWith some changes, it could be built as a static library. 773ff48bf5SDavid du ColombierThis document describes the Application Programming Interface (API) 783ff48bf5SDavid du Colombierfor the Ghostscript interpreter library. 793ff48bf5SDavid du ColombierThis should not be confused with the 803ff48bf5SDavid du Colombier<a href="Lib.htm">Ghostscript library</a> which provides a graphics 813ff48bf5SDavid du Colombierlibrary but not the interpreter. 823ff48bf5SDavid du Colombier<p> 833ff48bf5SDavid du ColombierThis supercedes the old <a href="DLL.htm">DLL</a> interface. 843ff48bf5SDavid du Colombier<p> 853ff48bf5SDavid du ColombierTo provide the interface described in the 863ff48bf5SDavid du Colombier<a href="Use.htm">usage documentation</a>, a smaller independent 873ff48bf5SDavid du Colombierexecutable loads the DLL/shared object. 88*593dc095SDavid du ColombierThis executable must provide all the interaction with the windowing system, 893ff48bf5SDavid du Colombierincluding image windows and, if necessary, a text window. 903ff48bf5SDavid du Colombier 913ff48bf5SDavid du Colombier<p> 923ff48bf5SDavid du ColombierThe Ghostscript interpreter library's name and characteristics differ 933ff48bf5SDavid du Colombierfor each platform: 943ff48bf5SDavid du Colombier 953ff48bf5SDavid du Colombier<ul> 963ff48bf5SDavid du Colombier<li>The Win32 DLL <b><tt>gsdll32.dll</tt></b> has 973ff48bf5SDavid du ColombierMULTIPLE NONSHARED data segments. Under Win32s it can be used by only one 983ff48bf5SDavid du Colombierprogram at a time, but under Windows 95/98 or Windows NT it can be called by 993ff48bf5SDavid du Colombiermultiple programs simultaneously. 1003ff48bf5SDavid du Colombier 1013ff48bf5SDavid du Colombier<li>The OS/2 DLL <b><tt>gsdll2.dll</tt></b> has 1023ff48bf5SDavid du ColombierMULTIPLE NONSHARED data segments and can be called by multiple programs 1033ff48bf5SDavid du Colombiersimultaneously. 1043ff48bf5SDavid du Colombier 1053ff48bf5SDavid du Colombier<li>The Linux shared object <b><tt>libgs.so</tt></b> 1063ff48bf5SDavid du Colombiercan be used by multiple programs simultaneously. 1073ff48bf5SDavid du Colombier 1083ff48bf5SDavid du Colombier<li>The MacOS X <b><tt>Ghostscript.framework</tt></b> can also be used 1093ff48bf5SDavid du Colombierby multiple applications at once. 1103ff48bf5SDavid du Colombier</ul> 1113ff48bf5SDavid du Colombier 1123ff48bf5SDavid du Colombier<p> 1133ff48bf5SDavid du ColombierThe source for the executable is in <b><tt>dw</tt></b>*.* (Windows), 1143ff48bf5SDavid du Colombier<b><tt>dp</tt></b>*.* (OS/2) and <b><tt>dx</tt></b>*.* (Linux). 115*593dc095SDavid du ColombierSee these source files for examples of how to use the DLL. A similar 116*593dc095SDavid du Colombierexample for MacOS using the Carbon API is provided in <b><tt>dm</tt></b>*.*. 1173ff48bf5SDavid du Colombier 118*593dc095SDavid du Colombier<p> 119*593dc095SDavid du ColombierThe source file <tt>dxmainc.c</tt> can also serve as an example of how to use the 120*593dc095SDavid du Colombierframework shared component on MacOS X, providing the same command-line tool it does 121*593dc095SDavid du Colombieron any linux, bsd or similar operating system. Just change the header includes to 122*593dc095SDavid du Colombieruse the Ghostscript namespace: 123*593dc095SDavid du Colombier<blockquote><pre><tt>#include <Ghostscript/ierrors.h> 1243ff48bf5SDavid du Colombier#include <Ghostscript/iapi.h></tt></pre></blockquote> 1253ff48bf5SDavid du Colombierand link with: 1263ff48bf5SDavid du Colombier<blockquote><pre><tt>cc -o gsc dxmainc.c -framework Ghostscript</tt></pre></blockquote> 1273ff48bf5SDavid du ColombierTo get a useable executable. <tt>Ghostscript.framework</tt> must be properly 1283ff48bf5SDavid du Colombierinstalled in the search path for this to work. 1293ff48bf5SDavid du Colombier 1303ff48bf5SDavid du Colombier<p> 1313ff48bf5SDavid du ColombierAt this stage, Ghostscript does not support multiple instances 1323ff48bf5SDavid du Colombierof the interpreter within a single process. 1333ff48bf5SDavid du Colombier 1343ff48bf5SDavid du Colombier<hr> 1353ff48bf5SDavid du Colombier 1363ff48bf5SDavid du Colombier<h2><a name="Exported_functions"></a>Exported functions</h2> 1373ff48bf5SDavid du Colombier 1383ff48bf5SDavid du Colombier<p> 1393ff48bf5SDavid du ColombierThe functions exported by the DLL/shared object are described 1403ff48bf5SDavid du Colombierin the header file <a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a> 1413ff48bf5SDavid du Colombierand are summarised below. Omitted from the summary are 1423ff48bf5SDavid du Colombierthe calling convention (e.g. __stdcall), details of return 1433ff48bf5SDavid du Colombiervalues and error handling. 1443ff48bf5SDavid du Colombier 1453ff48bf5SDavid du Colombier 1463ff48bf5SDavid du Colombier<ul> 1473ff48bf5SDavid du Colombier<li><b><tt> 1483ff48bf5SDavid du Colombierint 1493ff48bf5SDavid du Colombier<a href="#revision">gsapi_revision</a> 150*593dc095SDavid du Colombier (gsapi_revision_t *pr, int len); 1513ff48bf5SDavid du Colombier</tt></b> 1523ff48bf5SDavid du Colombier 1533ff48bf5SDavid du Colombier<li><b><tt> 1543ff48bf5SDavid du Colombierint 1553ff48bf5SDavid du Colombier<a href="#new_instance">gsapi_new_instance</a> 156*593dc095SDavid du Colombier(void **pinstance, void *caller_handle); 1573ff48bf5SDavid du Colombier</tt></b> 1583ff48bf5SDavid du Colombier 1593ff48bf5SDavid du Colombier<li><b><tt> 1603ff48bf5SDavid du Colombiervoid 1613ff48bf5SDavid du Colombier<a href="#delete_instance">gsapi_delete_instance</a> 162*593dc095SDavid du Colombier(void *instance); 1633ff48bf5SDavid du Colombier</tt></b> 1643ff48bf5SDavid du Colombier 1653ff48bf5SDavid du Colombier<li><b><tt> 1663ff48bf5SDavid du Colombierint 1673ff48bf5SDavid du Colombier<a href="#set_stdio">gsapi_set_stdio</a> 168*593dc095SDavid du Colombier(void *instance, 1693ff48bf5SDavid du Colombier int(*stdin_fn)(void *caller_handle, char *buf, int len), 1703ff48bf5SDavid du Colombier int(*stdout_fn)(void *caller_handle, const char *str, int len), 1713ff48bf5SDavid du Colombier int(*stderr_fn)(void *caller_handle, const char *str, int len)); 1723ff48bf5SDavid du Colombier</tt></b> 1733ff48bf5SDavid du Colombier 1743ff48bf5SDavid du Colombier<li><b><tt> 1753ff48bf5SDavid du Colombierint 1763ff48bf5SDavid du Colombier<a href="#set_poll">gsapi_set_poll</a> 177*593dc095SDavid du Colombier(void *instance, int(*poll_fn)(void *caller_handle)); 1783ff48bf5SDavid du Colombier</tt></b> 1793ff48bf5SDavid du Colombier 1803ff48bf5SDavid du Colombier<li><b><tt> 1813ff48bf5SDavid du Colombierint 1823ff48bf5SDavid du Colombier<a href="#set_display_callback">gsapi_set_display_callback</a> 183*593dc095SDavid du Colombier(void *instance, display_callback *callback); 1843ff48bf5SDavid du Colombier</tt></b> 1853ff48bf5SDavid du Colombier 1863ff48bf5SDavid du Colombier<li><b><tt> 1873ff48bf5SDavid du Colombierint 1883ff48bf5SDavid du Colombier<a href="#init">gsapi_init_with_args</a> 189*593dc095SDavid du Colombier(void *instance, int argc, char **argv); 1903ff48bf5SDavid du Colombier</tt></b> 1913ff48bf5SDavid du Colombier 1923ff48bf5SDavid du Colombier<li><b><tt> 1933ff48bf5SDavid du Colombierint 1943ff48bf5SDavid du Colombier<a href="#run">gsapi_run_string_begin</a> 195*593dc095SDavid du Colombier(void *instance, int user_errors, int *pexit_code); 1963ff48bf5SDavid du Colombier</tt></b> 1973ff48bf5SDavid du Colombier 1983ff48bf5SDavid du Colombier<li><b><tt> 1993ff48bf5SDavid du Colombierint 2003ff48bf5SDavid du Colombier<a href="#run">gsapi_run_string_continue</a> 201*593dc095SDavid du Colombier(void *instance, 2023ff48bf5SDavid du Colombier const char *str, unsigned int length, int user_errors, int *pexit_code); 2033ff48bf5SDavid du Colombier</tt></b> 2043ff48bf5SDavid du Colombier 2053ff48bf5SDavid du Colombier<li><b><tt> 2063ff48bf5SDavid du Colombierint 2073ff48bf5SDavid du Colombier<a href="#run">gsapi_run_string_end</a> 208*593dc095SDavid du Colombier(void *instance, int user_errors, int *pexit_code); 2093ff48bf5SDavid du Colombier</tt></b> 2103ff48bf5SDavid du Colombier 2113ff48bf5SDavid du Colombier<li><b><tt> 2123ff48bf5SDavid du Colombierint 2133ff48bf5SDavid du Colombier<a href="#run">gsapi_run_string_with_length</a> 214*593dc095SDavid du Colombier(void *instance, 2153ff48bf5SDavid du Colombier const char *str, unsigned int length, int user_errors, int *pexit_code); 2163ff48bf5SDavid du Colombier</tt></b> 2173ff48bf5SDavid du Colombier 2183ff48bf5SDavid du Colombier<li><b><tt> 2193ff48bf5SDavid du Colombierint 2203ff48bf5SDavid du Colombier<a href="#run">gsapi_run_string</a> 221*593dc095SDavid du Colombier(void *instance, 2223ff48bf5SDavid du Colombier const char *str, int user_errors, int *pexit_code); 2233ff48bf5SDavid du Colombier</tt></b> 2243ff48bf5SDavid du Colombier 2253ff48bf5SDavid du Colombier<li><b><tt> 2263ff48bf5SDavid du Colombierint 2273ff48bf5SDavid du Colombier<a href="#run">gsapi_run_file</a> 228*593dc095SDavid du Colombier(void *instance, 2293ff48bf5SDavid du Colombier const char *file_name, int user_errors, int *pexit_code); 2303ff48bf5SDavid du Colombier</tt></b> 2313ff48bf5SDavid du Colombier 2323ff48bf5SDavid du Colombier<li><b><tt> 2333ff48bf5SDavid du Colombierint 2343ff48bf5SDavid du Colombier<a href="#exit">gsapi_exit</a> 235*593dc095SDavid du Colombier(void *instance); 236*593dc095SDavid du Colombier</tt></b> 237*593dc095SDavid du Colombier 238*593dc095SDavid du Colombier<li><b><tt> 239*593dc095SDavid du Colombierint 240*593dc095SDavid du Colombier<a href="#set_visual_tracer">gsapi_set_visual_tracer</a> 241*593dc095SDavid du Colombier(gstruct vd_trace_interface_s *I); 2423ff48bf5SDavid du Colombier</tt></b> 2433ff48bf5SDavid du Colombier 2443ff48bf5SDavid du Colombier</ul> 2453ff48bf5SDavid du Colombier 2463ff48bf5SDavid du Colombier<h3><a name="revision"></a><b><tt>gsapi_revision()</tt></b></h3> 2473ff48bf5SDavid du Colombier 2483ff48bf5SDavid du Colombier<blockquote> 2493ff48bf5SDavid du ColombierThis function returns the revision numbers and strings of the Ghostscript 2503ff48bf5SDavid du Colombierinterpreter library; you should call it before any other interpreter 2513ff48bf5SDavid du Colombierlibrary functions to make sure that the correct version of the 2523ff48bf5SDavid du ColombierGhostscript interpreter has been loaded. 2533ff48bf5SDavid du Colombier 2543ff48bf5SDavid du Colombier<blockquote> 2553ff48bf5SDavid du Colombier<pre> 2563ff48bf5SDavid du Colombiertypedef struct gsapi_revision_s { 2573ff48bf5SDavid du Colombier const char *product; 2583ff48bf5SDavid du Colombier const char *copyright; 2593ff48bf5SDavid du Colombier long revision; 2603ff48bf5SDavid du Colombier long revisiondate; 2613ff48bf5SDavid du Colombier} gsapi_revision_t; 2623ff48bf5SDavid du Colombiergsapi_revision_t r; 2633ff48bf5SDavid du Colombier 2643ff48bf5SDavid du Colombierif (gsapi_revision(&r, sizeof(r)) == 0) { 2653ff48bf5SDavid du Colombier if (r.revision < 650) 2663ff48bf5SDavid du Colombier printf("Need at least Ghostscript 6.50"); 2673ff48bf5SDavid du Colombier} 2683ff48bf5SDavid du Colombierelse { 2693ff48bf5SDavid du Colombier printf("revision structure size is incorrect"); 2703ff48bf5SDavid du Colombier} 2713ff48bf5SDavid du Colombier</pre></blockquote> 2723ff48bf5SDavid du Colombier</blockquote> 2733ff48bf5SDavid du Colombier 2743ff48bf5SDavid du Colombier 2753ff48bf5SDavid du Colombier<h3><a name="new_instance"></a><b><tt>gsapi_new_instance()</tt></b></h3> 2763ff48bf5SDavid du Colombier<blockquote> 2773ff48bf5SDavid du ColombierCreate a new instance of Ghostscript. 2783ff48bf5SDavid du ColombierThis instance is passed to most other gsapi functions. 2793ff48bf5SDavid du ColombierThe caller_handle will be provided to callback functions. 2803ff48bf5SDavid du Colombier<b>At this stage, Ghostscript supports only one instance</b>. 2813ff48bf5SDavid du Colombier</blockquote> 2823ff48bf5SDavid du Colombier 2833ff48bf5SDavid du Colombier 2843ff48bf5SDavid du Colombier<h3><a name="delete_instance"></a><b><tt>gsapi_delete_instance()</tt></b></h3> 2853ff48bf5SDavid du Colombier<blockquote> 2863ff48bf5SDavid du ColombierDestroy an instance of Ghostscript. 2873ff48bf5SDavid du ColombierBefore you call this, Ghostscript must have finished. 2883ff48bf5SDavid du ColombierIf Ghostscript has been initialised, you must call 2893ff48bf5SDavid du Colombier<b><tt>gsapi_exit</tt></b> before <b><tt>gsapi_delete_instance</tt></b>. 2903ff48bf5SDavid du Colombier</blockquote> 2913ff48bf5SDavid du Colombier 2923ff48bf5SDavid du Colombier 2933ff48bf5SDavid du Colombier<h3><a name="set_stdio"></a><b><tt>gsapi_set_stdio()</tt></b></h3> 2943ff48bf5SDavid du Colombier<blockquote> 2953ff48bf5SDavid du ColombierSet the callback functions for stdio 2963ff48bf5SDavid du ColombierThe stdin callback function should return the number of 2973ff48bf5SDavid du Colombiercharacters read, 0 for EOF, or -1 for error. 2983ff48bf5SDavid du ColombierThe stdout and stderr callback functions should return 2993ff48bf5SDavid du Colombierthe number of characters written. 3003ff48bf5SDavid du Colombier</blockquote> 3013ff48bf5SDavid du Colombier 3023ff48bf5SDavid du Colombier 3033ff48bf5SDavid du Colombier<h3><a name="set_poll"></a><b><tt>gsapi_set_poll()</tt></b></h3> 3043ff48bf5SDavid du Colombier<blockquote> 3053ff48bf5SDavid du ColombierSet the callback function for polling. 3063ff48bf5SDavid du ColombierThis is used for handling window events or cooperative 3073ff48bf5SDavid du Colombiermultitasking. This function will only be called if 3083ff48bf5SDavid du Colombierthe Ghostscript interpreter was compiled with <b><tt>CHECK_INTERRUPTS</tt></b> 3093ff48bf5SDavid du Colombieras described in <b><tt><a href="../src/gpcheck.h">gpcheck.h</a></tt></b>. 310*593dc095SDavid du ColombierThe polling function should return zero if all is well, 311*593dc095SDavid du Colombierand return negative if it wants ghostscript to abort. 312*593dc095SDavid du ColombierThe polling function must be fast. 3133ff48bf5SDavid du Colombier</blockquote> 3143ff48bf5SDavid du Colombier 3153ff48bf5SDavid du Colombier<h3><a name="set_display_callback"></a><b><tt>gsapi_set_display_callback()</tt></b></h3> 3163ff48bf5SDavid du Colombier<blockquote> 3173ff48bf5SDavid du ColombierSet the callback structure for the <a href="#display">display</a> 3183ff48bf5SDavid du Colombierdevice. If the <a href="#display">display</a> device is used, 3193ff48bf5SDavid du Colombierthis must be called after 3203ff48bf5SDavid du Colombier<b><tt>gsapi_new_instance()</tt></b> 3213ff48bf5SDavid du Colombierand before <b><tt>gsapi_init_with_args()</tt></b>. 3223ff48bf5SDavid du ColombierSee <b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b> 3233ff48bf5SDavid du Colombierfor more details. 3243ff48bf5SDavid du Colombier</blockquote> 3253ff48bf5SDavid du Colombier 3263ff48bf5SDavid du Colombier<h3><a name="init"></a><b><tt>gsapi_init_with_args()</tt></b></h3> 3273ff48bf5SDavid du Colombier<blockquote> 3283ff48bf5SDavid du ColombierInitialise the interpreter. 3293ff48bf5SDavid du ColombierThis calls <b><tt>gs_main_init_with_args()</tt></b> in 3303ff48bf5SDavid du Colombier<b><tt><a href="../src/imainarg.c">imainarg.c</a></tt></b>. 3313ff48bf5SDavid du ColombierSee below for <a href="#return_codes">return codes</a>. 332*593dc095SDavid du ColombierThe arguments are the same as the "C" main function: 333*593dc095SDavid du Colombierargv[0] is ignored and the user supplied arguments 334*593dc095SDavid du Colombierare argv[1] to argv[argc-1]. 3353ff48bf5SDavid du Colombier</blockquote> 3363ff48bf5SDavid du Colombier 3373ff48bf5SDavid du Colombier<h3><a name="run"></a><b><tt>gsapi_run_*()</tt></b></h3> 3383ff48bf5SDavid du Colombier<blockquote> 3393ff48bf5SDavid du ColombierThe <b><tt>gsapi_run_*</tt></b> functions are like 3403ff48bf5SDavid du Colombier<b><tt>gs_main_run_*</tt></b> except that the error_object is omitted. 3413ff48bf5SDavid du ColombierIf these functions return <= -100, either quit or a fatal 3423ff48bf5SDavid du Colombiererror has occured. You must call <b><tt>gsapi_exit()</tt></b> next. 3433ff48bf5SDavid du ColombierThe only exception is <b><tt>gsapi_run_string_continue()</tt></b> 3443ff48bf5SDavid du Colombierwhich will return <b><tt>e_NeedInput</tt></b> if all is well. 3453ff48bf5SDavid du ColombierSee below for <a href="#return_codes">return codes</a>. 346*593dc095SDavid du Colombier<p> 347*593dc095SDavid du ColombierThere is a 64 KB length limit on any buffer submitted to a 348*593dc095SDavid du Colombier<tt>gsapi_run_*</tt> function for processing. If you have more 349*593dc095SDavid du Colombierthan 65535 bytes of input then you must split it into smaller 350*593dc095SDavid du Colombierpieces and submit each in a separate 351*593dc095SDavid du Colombier<tt>gsapi_run_string_continue()</tt> call. 3523ff48bf5SDavid du Colombier</blockquote> 3533ff48bf5SDavid du Colombier 3543ff48bf5SDavid du Colombier<h3><a name="exit"></a><b><tt>gsapi_exit()</tt></b></h3> 3553ff48bf5SDavid du Colombier<blockquote> 3563ff48bf5SDavid du ColombierExit the interpreter. 3573ff48bf5SDavid du ColombierThis must be called on shutdown if <b><tt>gsapi_init_with_args()</tt></b> 3583ff48bf5SDavid du Colombierhas been called, and just before <b><tt>gsapi_delete_instance()</tt></b>. 3593ff48bf5SDavid du Colombier</blockquote> 3603ff48bf5SDavid du Colombier 361*593dc095SDavid du Colombier<h3><a name="set_visual_tracer"></a><b><tt>gsapi_set_visual_tracer()</tt></b></h3> 362*593dc095SDavid du Colombier<blockquote> 363*593dc095SDavid du ColombierPass visual tracer interface block to Ghostscript. 364*593dc095SDavid du ColombierSee <a href="Lib.htm#Visual_trace"><b><tt>Lib.htm</tt></b></a> for reference about 365*593dc095SDavid du Colombierthe interface block structure. 366*593dc095SDavid du ColombierThis function is useful for debug clients only. Release clients must not call it. 367*593dc095SDavid du Colombier</blockquote> 368*593dc095SDavid du Colombier 369*593dc095SDavid du Colombier 3703ff48bf5SDavid du Colombier<h3><a name="return_codes"></a>Return codes</h3> 3713ff48bf5SDavid du Colombier 3723ff48bf5SDavid du Colombier<p> 3733ff48bf5SDavid du ColombierThe <b><tt>gsapi_init_with_args</tt></b>, <b><tt>gsapi_run_*</tt></b> and 3743ff48bf5SDavid du Colombier<b><tt>gsapi_exit</tt></b> functions return an integer code. 3753ff48bf5SDavid du Colombier 3763ff48bf5SDavid du Colombier<p> 3773ff48bf5SDavid du Colombier<table width="80%" align="center" cellpadding=0 cellspacing=0> 3783ff48bf5SDavid du Colombier<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Return codes from <b><tt>gsapi_*()</tt></b></font><hr> 3793ff48bf5SDavid du Colombier<tr valign=bottom> 3803ff48bf5SDavid du Colombier <th align=left>Code 3813ff48bf5SDavid du Colombier <td> 3823ff48bf5SDavid du Colombier <th align=left>Status 3833ff48bf5SDavid du Colombier<tr> <td colspan=3><hr> 3843ff48bf5SDavid du Colombier<tr valign=top> <td align=left>0 3853ff48bf5SDavid du Colombier <td> 3863ff48bf5SDavid du Colombier <td>No errors 3873ff48bf5SDavid du Colombier<tr valign=top> <td align=left>e_Quit 3883ff48bf5SDavid du Colombier <td> 3893ff48bf5SDavid du Colombier <td>"<b><tt>quit</tt></b>" has been executed. 3903ff48bf5SDavid du Colombier This is not an error. 3913ff48bf5SDavid du Colombier <b><tt>gsapi_exit()</tt></b> must be called next. 3923ff48bf5SDavid du Colombier<tr valign=top> <td align=left>e_NeedInput 3933ff48bf5SDavid du Colombier <td> 3943ff48bf5SDavid du Colombier <td>More input is needed by 3953ff48bf5SDavid du Colombier <b><tt>gsapi_run_string_continue()</tt></b>. 3963ff48bf5SDavid du Colombier This is not an error. 3973ff48bf5SDavid du Colombier<tr valign=top> <td align=left>e_Info 3983ff48bf5SDavid du Colombier <td> 3993ff48bf5SDavid du Colombier <td>"<b><tt>gs -h</tt></b>" has been executed. 4003ff48bf5SDavid du Colombier This is not an error. 4013ff48bf5SDavid du Colombier <b><tt>gsapi_exit()</tt></b> must be called next. 4023ff48bf5SDavid du Colombier<tr valign=top> <td align=left>< 0 4033ff48bf5SDavid du Colombier <td> 4043ff48bf5SDavid du Colombier <td>Error 4053ff48bf5SDavid du Colombier<tr valign=top> <td align=left><= -100 4063ff48bf5SDavid du Colombier <td> 4073ff48bf5SDavid du Colombier <td>Fatal error. 4083ff48bf5SDavid du Colombier<b><tt>gsapi_exit()</tt></b> must be called next. 4093ff48bf5SDavid du Colombier</table> 4103ff48bf5SDavid du Colombier</blockquote> 4113ff48bf5SDavid du Colombier 4123ff48bf5SDavid du Colombier<p> 4133ff48bf5SDavid du ColombierThe <b><tt>gsapi_run_*()</tt></b> functions do not flush stdio. 4143ff48bf5SDavid du ColombierIf you want to see output from Ghostscript you 4153ff48bf5SDavid du Colombiermust do this explicitly as shown in the example below. 4163ff48bf5SDavid du Colombier 4173ff48bf5SDavid du Colombier<p> 4183ff48bf5SDavid du ColombierWhen executing a string with <b><tt>gsapi_run_string_*()</tt></b>, 4193ff48bf5SDavid du Colombier<b><tt>currentfile</tt></b> is the input from the string. 4203ff48bf5SDavid du ColombierReading from <b><tt>%stdin</tt></b> uses the stdin callback. 4213ff48bf5SDavid du Colombier</blockquote> 4223ff48bf5SDavid du Colombier 4233ff48bf5SDavid du Colombier 4243ff48bf5SDavid du Colombier 425*593dc095SDavid du Colombier<h2><a name="Example_usage"></a>Example Usage</h2> 426*593dc095SDavid du ColombierSome overly simple examples of using the Ghostscript interpreter library 427*593dc095SDavid du Colombierare below. Some more examples including other programming languages 428*593dc095SDavid du Colombiermay be found at 429*593dc095SDavid du Colombier<a href="http://www.cs.wisc.edu/~ghost/doc/gsapi.htm"> 430*593dc095SDavid du Colombierhttp://www.cs.wisc.edu/~ghost/doc/gsapi.htm</a>. 4313ff48bf5SDavid du Colombier 432*593dc095SDavid du Colombier<p>To use try out these examples in a development environment like Microsoft's 433*593dc095SDavid du Colombierdeveloper tools or Metrowerks Codewarrior, create a new project, save the example 434*593dc095SDavid du Colombiersource code as a <tt>.c</tt> file and add it, along with the Ghostscript dll or shared 435*593dc095SDavid du Colombierlibrary. You will also need to make sure the Ghostscript headers are available, either 436*593dc095SDavid du Colombierby adding their location (the <tt>src</tt> directory in the Ghostscript source 437*593dc095SDavid du Colombierdistribution) to the project's search path, or by copying ierrors.h and iapi.h into the 438*593dc095SDavid du Colombiersame directory as the example source.</p> 439*593dc095SDavid du Colombier 440*593dc095SDavid du Colombier<h3>Example 1</h3> 4413ff48bf5SDavid du Colombier<pre> 442*593dc095SDavid du Colombier/* Example of using GS DLL as a ps2pdf converter. */ 443*593dc095SDavid du Colombier 444*593dc095SDavid du Colombier#if defined(_WIN32) && !defined(_Windows) 445*593dc095SDavid du Colombier# define _Windows 446*593dc095SDavid du Colombier#endif 447*593dc095SDavid du Colombier#ifdef _Windows 448*593dc095SDavid du Colombier/* add this source to a project with gsdll32.dll, or compile it directly with: 449*593dc095SDavid du Colombier * cl -D_Windows -Isrc -Febin\ps2pdf.exe ps2pdf.c bin\gsdll32.lib 450*593dc095SDavid du Colombier */ 451*593dc095SDavid du Colombier# include <windows.h> 452*593dc095SDavid du Colombier# define GSDLLEXPORT __declspec(dllimport) 453*593dc095SDavid du Colombier#endif 454*593dc095SDavid du Colombier 455*593dc095SDavid du Colombier#include "ierrors.h" 456*593dc095SDavid du Colombier#include "iapi.h" 457*593dc095SDavid du Colombier 458*593dc095SDavid du Colombiervoid *minst; 459*593dc095SDavid du Colombier 460*593dc095SDavid du Colombierint main(int argc, char *argv[]) 461*593dc095SDavid du Colombier{ 462*593dc095SDavid du Colombier int code, code1; 463*593dc095SDavid du Colombier const char * gsargv[10]; 464*593dc095SDavid du Colombier int gsargc; 465*593dc095SDavid du Colombier gsargv[0] = "ps2pdf"; /* actual value doesn't matter */ 466*593dc095SDavid du Colombier gsargv[1] = "-dNOPAUSE"; 467*593dc095SDavid du Colombier gsargv[2] = "-dBATCH"; 468*593dc095SDavid du Colombier gsargv[3] = "-dSAFER"; 469*593dc095SDavid du Colombier gsargv[4] = "-sDEVICE=pdfwrite"; 470*593dc095SDavid du Colombier gsargv[5] = "-sOutputFile=out.pdf"; 471*593dc095SDavid du Colombier gsargv[6] = "-c"; 472*593dc095SDavid du Colombier gsargv[7] = ".setpdfwrite"; 473*593dc095SDavid du Colombier gsargv[8] = "-f"; 474*593dc095SDavid du Colombier gsargv[9] = "input.ps"; 475*593dc095SDavid du Colombier gsargc=10; 476*593dc095SDavid du Colombier 477*593dc095SDavid du Colombier code = gsapi_new_instance(&minst, NULL); 478*593dc095SDavid du Colombier if (code < 0) 479*593dc095SDavid du Colombier return 1; 480*593dc095SDavid du Colombier code = gsapi_init_with_args(minst, gsargc, gsargv); 481*593dc095SDavid du Colombier code1 = gsapi_exit(minst); 482*593dc095SDavid du Colombier if ((code == 0) || (code == e_Quit)) 483*593dc095SDavid du Colombier code = code1; 484*593dc095SDavid du Colombier 485*593dc095SDavid du Colombier gsapi_delete_instance(minst); 486*593dc095SDavid du Colombier 487*593dc095SDavid du Colombier if ((code == 0) || (code == e_Quit)) 488*593dc095SDavid du Colombier return 0; 489*593dc095SDavid du Colombier return 1; 490*593dc095SDavid du Colombier} 491*593dc095SDavid du Colombier</pre> 492*593dc095SDavid du Colombier 493*593dc095SDavid du Colombier<h3>Example 2</h3> 494*593dc095SDavid du Colombier<pre> 495*593dc095SDavid du Colombier/* Similar to command line gs */ 496*593dc095SDavid du Colombier 497*593dc095SDavid du Colombier#if defined(_WIN32) && !defined(_Windows) 498*593dc095SDavid du Colombier# define _Windows 499*593dc095SDavid du Colombier#endif 500*593dc095SDavid du Colombier#ifdef _Windows 501*593dc095SDavid du Colombier/* Compile directly with: 502*593dc095SDavid du Colombier * cl -D_Windows -Isrc -Febin\gstest.exe gstest.c bin\gsdll32.lib 503*593dc095SDavid du Colombier */ 504*593dc095SDavid du Colombier# include <windows.h> 505*593dc095SDavid du Colombier# define GSDLLEXPORT __declspec(dllimport) 506*593dc095SDavid du Colombier#endif 5073ff48bf5SDavid du Colombier#include <stdio.h> 508*593dc095SDavid du Colombier#include "ierrors.h" 5093ff48bf5SDavid du Colombier#include "iapi.h" 5103ff48bf5SDavid du Colombier 5113ff48bf5SDavid du Colombier/* stdio functions */ 512*593dc095SDavid du Colombierstatic int GSDLLCALL 5133ff48bf5SDavid du Colombiergsdll_stdin(void *instance, char *buf, int len) 5143ff48bf5SDavid du Colombier{ 5153ff48bf5SDavid du Colombier int ch; 5163ff48bf5SDavid du Colombier int count = 0; 5173ff48bf5SDavid du Colombier while (count < len) { 5183ff48bf5SDavid du Colombier ch = fgetc(stdin); 5193ff48bf5SDavid du Colombier if (ch == EOF) 5203ff48bf5SDavid du Colombier return 0; 5213ff48bf5SDavid du Colombier *buf++ = ch; 5223ff48bf5SDavid du Colombier count++; 5233ff48bf5SDavid du Colombier if (ch == '\n') 5243ff48bf5SDavid du Colombier break; 5253ff48bf5SDavid du Colombier } 5263ff48bf5SDavid du Colombier return count; 5273ff48bf5SDavid du Colombier} 5283ff48bf5SDavid du Colombier 529*593dc095SDavid du Colombierstatic int GSDLLCALL 5303ff48bf5SDavid du Colombiergsdll_stdout(void *instance, const char *str, int len) 5313ff48bf5SDavid du Colombier{ 5323ff48bf5SDavid du Colombier fwrite(str, 1, len, stdout); 5333ff48bf5SDavid du Colombier fflush(stdout); 5343ff48bf5SDavid du Colombier return len; 5353ff48bf5SDavid du Colombier} 5363ff48bf5SDavid du Colombier 537*593dc095SDavid du Colombierstatic int GSDLLCALL 5383ff48bf5SDavid du Colombiergsdll_stderr(void *instance, const char *str, int len) 5393ff48bf5SDavid du Colombier{ 5403ff48bf5SDavid du Colombier fwrite(str, 1, len, stderr); 5413ff48bf5SDavid du Colombier fflush(stderr); 5423ff48bf5SDavid du Colombier return len; 5433ff48bf5SDavid du Colombier} 5443ff48bf5SDavid du Colombier 545*593dc095SDavid du Colombiervoid *minst; 5463ff48bf5SDavid du Colombierconst char start_string[] = "systemdict /start get exec\n"; 5473ff48bf5SDavid du Colombier 5483ff48bf5SDavid du Colombierint main(int argc, char *argv[]) 5493ff48bf5SDavid du Colombier{ 550*593dc095SDavid du Colombier int code, code1; 5513ff48bf5SDavid du Colombier int exit_code; 5523ff48bf5SDavid du Colombier 5533ff48bf5SDavid du Colombier code = gsapi_new_instance(&minst, NULL); 5543ff48bf5SDavid du Colombier if (code < 0) 5553ff48bf5SDavid du Colombier return 1; 5563ff48bf5SDavid du Colombier gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr); 5573ff48bf5SDavid du Colombier code = gsapi_init_with_args(minst, argc, argv); 5583ff48bf5SDavid du Colombier if (code == 0) 5593ff48bf5SDavid du Colombier code = gsapi_run_string(minst, start_string, 0, &exit_code); 560*593dc095SDavid du Colombier code1 = gsapi_exit(minst); 561*593dc095SDavid du Colombier if ((code == 0) || (code == e_Quit)) 562*593dc095SDavid du Colombier code = code1; 563*593dc095SDavid du Colombier 564*593dc095SDavid du Colombier gsapi_delete_instance(minst); 565*593dc095SDavid du Colombier 566*593dc095SDavid du Colombier if ((code == 0) || (code == e_Quit)) 567*593dc095SDavid du Colombier return 0; 568*593dc095SDavid du Colombier return 1; 569*593dc095SDavid du Colombier} 570*593dc095SDavid du Colombier</pre> 571*593dc095SDavid du Colombier 572*593dc095SDavid du Colombier<h3>Example 3</h3> 573*593dc095SDavid du Colombier 574*593dc095SDavid du ColombierReplace main() in either of the above with the following code, 575*593dc095SDavid du Colombiershowing how you can feed Ghostscript piecemeal: 576*593dc095SDavid du Colombier<pre> 577*593dc095SDavid du Colombierconst char *command = "1 2 add == flush\n"; 578*593dc095SDavid du Colombier 579*593dc095SDavid du Colombierint main(int argc, char *argv[]) 580*593dc095SDavid du Colombier{ 581*593dc095SDavid du Colombier int code, code1; 582*593dc095SDavid du Colombier int exit_code; 583*593dc095SDavid du Colombier 584*593dc095SDavid du Colombier code = gsapi_new_instance(&minst, NULL); 585*593dc095SDavid du Colombier if (code < 0) 586*593dc095SDavid du Colombier return 1; 587*593dc095SDavid du Colombier code = gsapi_init_with_args(minst, argc, argv); 588*593dc095SDavid du Colombier 589*593dc095SDavid du Colombier if (code == 0) { 590*593dc095SDavid du Colombier gsapi_run_string_begin(minst, 0, &exit_code); 591*593dc095SDavid du Colombier gsapi_run_string_continue(minst, command, strlen(command), 0, &exit_code); 592*593dc095SDavid du Colombier gsapi_run_string_continue(minst, "qu", 2, 0, &exit_code); 593*593dc095SDavid du Colombier gsapi_run_string_continue(minst, "it", 2, 0, &exit_code); 594*593dc095SDavid du Colombier gsapi_run_string_end(minst, 0, &exit_code); 595*593dc095SDavid du Colombier } 596*593dc095SDavid du Colombier 597*593dc095SDavid du Colombier code1 = gsapi_exit(minst); 598*593dc095SDavid du Colombier if ((code == 0) || (code == e_Quit)) 599*593dc095SDavid du Colombier code = code1; 6003ff48bf5SDavid du Colombier 6013ff48bf5SDavid du Colombier gsapi_delete_instance(minst); 6023ff48bf5SDavid du Colombier 6033ff48bf5SDavid du Colombier if ((code == 0) || (code == e_Quit)) 6043ff48bf5SDavid du Colombier return 0; 6053ff48bf5SDavid du Colombier return 1; 6063ff48bf5SDavid du Colombier} 6073ff48bf5SDavid du Colombier</pre> 6083ff48bf5SDavid du Colombier 6093ff48bf5SDavid du Colombier 6103ff48bf5SDavid du Colombier<h2><a name="Multiple_threads"></a>Multiple threads</h2> 6113ff48bf5SDavid du ColombierThe Ghostscript library should have been compiled with a 6123ff48bf5SDavid du Colombierthread safe run time library. 6133ff48bf5SDavid du ColombierSynchronisation of threads is entirely up to the caller. 614*593dc095SDavid du ColombierThe exported <a href="#Exported_functions "><b><tt>gsapi_*()</tt></b></a> 615*593dc095SDavid du Colombierfunctions must be called from one thread only. 6163ff48bf5SDavid du Colombier 6173ff48bf5SDavid du Colombier<h2><a name="stdio"></a>Standard input and output</h2> 6183ff48bf5SDavid du Colombier<p> 6193ff48bf5SDavid du ColombierWhen using the Ghostscript interpreter library interface, you have a 6203ff48bf5SDavid du Colombierchoice of two standard input/output methods. 6213ff48bf5SDavid du Colombier<ul> 6223ff48bf5SDavid du Colombier<li>If you do nothing, the "C" stdio will be used. 6233ff48bf5SDavid du Colombier<li>If you use <b><tt>gsapi_set_stdio()</tt></b>, all stdio will 6243ff48bf5SDavid du Colombier be redirected to the callback functions you provide. 6253ff48bf5SDavid du Colombier This would be used in a graphical user interface environment 6263ff48bf5SDavid du Colombier where stdio is not available, or where you wish to process 6273ff48bf5SDavid du Colombier Ghostscript input or output. 6283ff48bf5SDavid du Colombier</ul> 6293ff48bf5SDavid du Colombier<p> 6303ff48bf5SDavid du ColombierThe callback functions are described in 6313ff48bf5SDavid du Colombier<a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>. 6323ff48bf5SDavid du Colombier 6333ff48bf5SDavid du Colombier 6343ff48bf5SDavid du Colombier<h2><a name="display"></a>Display device</h2> 6353ff48bf5SDavid du Colombier<p> 6363ff48bf5SDavid du ColombierThe <b><tt>display</tt></b> device is available for use with 6373ff48bf5SDavid du Colombierthe Ghostscript interpreter library. This is described in the file 6383ff48bf5SDavid du Colombier<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>. 6393ff48bf5SDavid du ColombierThis device provides you with access to the raster output of 6403ff48bf5SDavid du ColombierGhostscript. It is your responsibility to copy this raster 6413ff48bf5SDavid du Colombierto a display window or printer. 6423ff48bf5SDavid du Colombier<p> 6433ff48bf5SDavid du ColombierTo use this device, you must provide a callback structure 6443ff48bf5SDavid du Colombierwith addresses of a number of callback functions. 6453ff48bf5SDavid du ColombierThe address of the callback structure is provided using 6463ff48bf5SDavid du Colombier<b><tt>gsapi_set_display_callback()</tt></b>. 6473ff48bf5SDavid du ColombierThis must be called after 6483ff48bf5SDavid du Colombier<b><tt>gsapi_new_instance()</tt></b> 6493ff48bf5SDavid du Colombierand before 6503ff48bf5SDavid du Colombier<b><tt>gsapi_init_with_args()</tt></b>. 6513ff48bf5SDavid du Colombier<p> 6523ff48bf5SDavid du ColombierThe callbacks are for device open, close, resize, sync, page, 6533ff48bf5SDavid du Colombiermemory allocation and updating. 6543ff48bf5SDavid du ColombierEach callback function contains a handle can be set using 6553ff48bf5SDavid du Colombier<blockquote> 6563ff48bf5SDavid du Colombier -dDisplayHandle=1234 6573ff48bf5SDavid du Colombier</blockquote> 6583ff48bf5SDavid du Colombier<p> 6593ff48bf5SDavid du ColombierThe device raster format can be configured using 6603ff48bf5SDavid du Colombier<blockquote> 6613ff48bf5SDavid du Colombier -dDisplayFormat=NNNN 6623ff48bf5SDavid du Colombier</blockquote> 6633ff48bf5SDavid du ColombierOptions include 6643ff48bf5SDavid du Colombier<ul> 665*593dc095SDavid du Colombier<li> native, gray, RGB, CMYK or separation color spaces. 6663ff48bf5SDavid du Colombier<li> alpha byte (ignored). 6673ff48bf5SDavid du Colombier<li> 1 to 16 bits/component. 6683ff48bf5SDavid du Colombier<li> bigendian (RGB) or littleendian (BGR) order. 6693ff48bf5SDavid du Colombier<li> top first or bottom first raster. 6703ff48bf5SDavid du Colombier<li> 16 bits/pixel with 555 or 565 bitfields. 6713ff48bf5SDavid du Colombier</ul> 6723ff48bf5SDavid du ColombierThe format values are described in 6733ff48bf5SDavid du Colombier<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>. 6743ff48bf5SDavid du ColombierThe format is flexible enough to support common Windows, OS/2, Linux 6753ff48bf5SDavid du Colombierand Mac raster formats. To select the display device with a 6763ff48bf5SDavid du ColombierWindows 24-bit RGB raster: 6773ff48bf5SDavid du Colombier<pre> 6783ff48bf5SDavid du Colombier char **nargv; 6793ff48bf5SDavid du Colombier char arg1[64]; 6803ff48bf5SDavid du Colombier char arg2[64]; 6813ff48bf5SDavid du Colombier char arg3[64]; 6823ff48bf5SDavid du Colombier code = gsapi_new_instance(&minst, NULL); 6833ff48bf5SDavid du Colombier gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr); 6843ff48bf5SDavid du Colombier code = gsapi_set_display_callback(minst, &display_callback); 6853ff48bf5SDavid du Colombier sprintf(arg1, "-sDEVICE=display"); 6863ff48bf5SDavid du Colombier sprintf(arg2, "-dDisplayHandle=%d", 0); 6873ff48bf5SDavid du Colombier sprintf(arg3, "-dDisplayFormat=%d", 6883ff48bf5SDavid du Colombier DISPLAY_COLORS_RGB | DISPLAY_ALPHA_NONE | DISPLAY_DEPTH_8 | 6893ff48bf5SDavid du Colombier DISPLAY_LITTLEENDIAN | DISPLAY_BOTTOMFIRST); 6903ff48bf5SDavid du Colombier nargv = (char **)malloc((argc + 4) * sizeof(char *)); 6913ff48bf5SDavid du Colombier nargv[0] = argv[0]; 6923ff48bf5SDavid du Colombier nargv[1] = arg1; 6933ff48bf5SDavid du Colombier nargv[2] = arg2; 6943ff48bf5SDavid du Colombier nargv[3] = arg3; 6953ff48bf5SDavid du Colombier memcpy(nargv + 4, argv + 1, argc * sizeof(char *)); 6963ff48bf5SDavid du Colombier argc += 3; 6973ff48bf5SDavid du Colombier code = gsapi_init_with_args(minst, argc, nargv); 6983ff48bf5SDavid du Colombier</pre> 6993ff48bf5SDavid du Colombier 7003ff48bf5SDavid du Colombier<p> 7013ff48bf5SDavid du ColombierThe display device provides you with the address and size of the 7023ff48bf5SDavid du Colombierraster using the <b><tt>display_size()</tt></b> callback. 7033ff48bf5SDavid du ColombierYou are then responsible for displaying this raster. 7043ff48bf5SDavid du ColombierSome examples are in 7053ff48bf5SDavid du Colombier<b><tt><a href="../src/dwmain.c">dwmain.c</a></tt></b> (Windows), 7063ff48bf5SDavid du Colombier<b><tt><a href="../src/dpmain.c">dpmain.c</a></tt></b> (OS/2) and 707*593dc095SDavid du Colombier<b><tt><a href="../src/dxmain.c">dxmain.c</a></tt></b> (X11/Linux), and 708*593dc095SDavid du Colombier<b><tt><a href="../src/dmmain.c">dmmain.c</a></tt></b> (MacOS Classic or Carbon). 709*593dc095SDavid du Colombier<p> 710*593dc095SDavid du ColombierOn some platforms, the calling convention for the display device callbacks in 711*593dc095SDavid du Colombier<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b> 712*593dc095SDavid du Colombieris not the same as the exported 713*593dc095SDavid du Colombier<a href="#Exported_functions "><b><tt>gsapi_*()</tt></b></a> 714*593dc095SDavid du Colombierfunctions in <a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>. 7153ff48bf5SDavid du Colombier 7163ff48bf5SDavid du Colombier<p> 7173ff48bf5SDavid du Colombier 7183ff48bf5SDavid du Colombier<!-- [2.0 end contents] ==================================================== --> 7193ff48bf5SDavid du Colombier 7203ff48bf5SDavid du Colombier<!-- [3.0 begin visible trailer] =========================================== --> 7213ff48bf5SDavid du Colombier<hr> 7223ff48bf5SDavid du Colombier 7233ff48bf5SDavid du Colombier 7243ff48bf5SDavid du Colombier<p> 725*593dc095SDavid du Colombier<small>Copyright © 2000-2004 artofcode LLC. All rights reserved.</small> 7263ff48bf5SDavid du Colombier 7273ff48bf5SDavid du Colombier<p> 728*593dc095SDavid du ColombierThis software is provided AS-IS with no warranty, either express or 729*593dc095SDavid du Colombierimplied. 730*593dc095SDavid du Colombier 731*593dc095SDavid du ColombierThis software is distributed under license and may not be copied, 732*593dc095SDavid du Colombiermodified or distributed except as expressly authorized under the terms 733*593dc095SDavid du Colombierof the license contained in the file LICENSE in this distribution. 734*593dc095SDavid du Colombier 735*593dc095SDavid du ColombierFor more information about licensing, please refer to 736*593dc095SDavid du Colombierhttp://www.ghostscript.com/licensing/. For information on 737*593dc095SDavid du Colombiercommercial licensing, go to http://www.artifex.com/licensing/ or 738*593dc095SDavid du Colombiercontact Artifex Software, Inc., 101 Lucas Valley Road #110, 739*593dc095SDavid du ColombierSan Rafael, CA 94903, U.S.A., +1(415)492-9861. 7403ff48bf5SDavid du Colombier 7413ff48bf5SDavid du Colombier<p> 742*593dc095SDavid du Colombier<small>Ghostscript version 8.53, 20 October 2005 7433ff48bf5SDavid du Colombier 7443ff48bf5SDavid du Colombier 7453ff48bf5SDavid du Colombier<!-- [3.0 end visible trailer] ============================================= --> 7463ff48bf5SDavid du Colombier 7473ff48bf5SDavid du Colombier</body> 7483ff48bf5SDavid du Colombier</html> 749