13ff48bf5SDavid du Colombier<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 27dd7cddfSDavid du Colombier<html> 37dd7cddfSDavid du Colombier<head> 47dd7cddfSDavid du Colombier<title>How to use the Ghostscript Dynamic Link Library (DLL)</title> 5*593dc095SDavid du Colombier<!-- $Id: DLL.htm,v 1.43 2005/10/20 19:46:23 ray Exp $ --> 67dd7cddfSDavid du Colombier<!-- Originally: dll.txt --> 73ff48bf5SDavid du Colombier<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 87dd7cddfSDavid du Colombier</head> 97dd7cddfSDavid du Colombier 107dd7cddfSDavid du Colombier<body> 117dd7cddfSDavid du Colombier<!-- [1.0 begin visible header] ============================================ --> 127dd7cddfSDavid du Colombier 137dd7cddfSDavid du Colombier<!-- [1.1 begin headline] ================================================== --> 147dd7cddfSDavid du Colombier 153ff48bf5SDavid du Colombier<h1>How to use the Ghostscript Dynamic Link Library (DLL)</h1> 167dd7cddfSDavid du Colombier 177dd7cddfSDavid du Colombier<!-- [1.1 end headline] ==================================================== --> 187dd7cddfSDavid du Colombier 197dd7cddfSDavid du Colombier<!-- [1.2 begin table of contents] ========================================= --> 207dd7cddfSDavid du Colombier 217dd7cddfSDavid du Colombier<h2>Table of contents</h2> 227dd7cddfSDavid du Colombier 233ff48bf5SDavid du Colombier<ul> 247dd7cddfSDavid du Colombier<li><a href="#DLL">What is the Ghostscript DLL?</a> 257dd7cddfSDavid du Colombier<li><a href="#Common_functions">Platform-independent DLL functions</a> 267dd7cddfSDavid du Colombier<ul> 277dd7cddfSDavid du Colombier<li><a href="#revision"><b><tt>gsdll_revision()</tt></b></a> 287dd7cddfSDavid du Colombier<li><a href="#init"><b><tt>gsdll_init()</tt></b></a> 297dd7cddfSDavid du Colombier<li><a href="#execute_begin"><b><tt>gsdll_execute_begin()</tt></b></a> 307dd7cddfSDavid du Colombier<li><a href="#execute_cont"><b><tt>gsdll_execute_cont()</tt></b></a> 317dd7cddfSDavid du Colombier<li><a href="#execute_end"><b><tt>gsdll_execute_end()</tt></b></a> 327dd7cddfSDavid du Colombier<li><a href="#exit"><b><tt>gsdll_exit()</tt></b></a> 337dd7cddfSDavid du Colombier<li><a href="#lock_device"><b><tt>gsdll_lock_device()</tt></b></a> 347dd7cddfSDavid du Colombier</ul> 357dd7cddfSDavid du Colombier<li><a href="#Callback">Callback function</a> 367dd7cddfSDavid du Colombier<li><a href="#OS2_device">Ghostscript DLL device for OS/2</a> 377dd7cddfSDavid du Colombier<ul> 387dd7cddfSDavid du Colombier<li><a href="#OS2_bmp"><b><tt>gsdll_get_bitmap()</tt></b></a> 397dd7cddfSDavid du Colombier<li><a href="#OS2_example">Example DLL usage for OS/2</a> 407dd7cddfSDavid du Colombier</ul> 417dd7cddfSDavid du Colombier<li><a href="#Win_device">Ghostscript DLL device for MS Windows</a> 427dd7cddfSDavid du Colombier<ul> 437dd7cddfSDavid du Colombier<li><a href="#Win_copydib"><b><tt>gsdll_copy_dib()</tt></b></a> 447dd7cddfSDavid du Colombier<li><a href="#Win_copypalette"><b><tt>gsdll_copy_palette()</tt></b></a> 457dd7cddfSDavid du Colombier<li><a href="#Win_draw"><b><tt>gsdll_draw()</tt></b></a> 467dd7cddfSDavid du Colombier<li><a href="#Win_get_row"><b><tt>gsdll_get_bitmap_row()</tt></b></a> 477dd7cddfSDavid du Colombier</ul> 487dd7cddfSDavid du Colombier<li><a href="#Win16">Ghostscript DLL Device for 16-bit MS Windows</a> 493ff48bf5SDavid du Colombier</ul> 507dd7cddfSDavid du Colombier 517dd7cddfSDavid du Colombier<!-- [1.2 end table of contents] =========================================== --> 527dd7cddfSDavid du Colombier 537dd7cddfSDavid du Colombier<!-- [1.3 begin hint] ====================================================== --> 547dd7cddfSDavid du Colombier 557dd7cddfSDavid du Colombier<p>For other information, see the <a href="Readme.htm">Ghostscript 567dd7cddfSDavid du Colombieroverview</a>. 577dd7cddfSDavid du Colombier 587dd7cddfSDavid du Colombier<p> 593ff48bf5SDavid du Colombier<b>WARNING: The API described in this document is obsolete and will 603ff48bf5SDavid du Colombierbe removed in the future.</b> 613ff48bf5SDavid du ColombierThe current Ghostscript Interpreter API 623ff48bf5SDavid du Colombieris described in <a href="API.htm">API.htm</a>. 637dd7cddfSDavid du Colombier 647dd7cddfSDavid du Colombier<!-- [1.3 end hint] ======================================================== --> 657dd7cddfSDavid du Colombier 667dd7cddfSDavid du Colombier<hr> 677dd7cddfSDavid du Colombier 687dd7cddfSDavid du Colombier<!-- [1.0 end visible header] ============================================== --> 697dd7cddfSDavid du Colombier 707dd7cddfSDavid du Colombier<!-- [2.0 begin contents] ================================================== --> 717dd7cddfSDavid du Colombier 723ff48bf5SDavid du Colombier<h2><a name="DLL"></a>What is the Ghostscript DLL?</h2> 737dd7cddfSDavid du Colombier 747dd7cddfSDavid du Colombier<p> 757dd7cddfSDavid du ColombierFor the OS/2, Win16 and Win32 platforms, Ghostscript is built as a dynamic 767dd7cddfSDavid du Colombierlink library (DLL), and to provide the interface described in the <a 777dd7cddfSDavid du Colombierhref="Use.htm">usage documentation</a>, a smaller independent executable 787dd7cddfSDavid du Colombier(<b><tt>.EXE</tt></b>) loads this DLL, which provides all the interaction 797dd7cddfSDavid du Colombierwith the windowing system, including image windows and, if necessary, a 807dd7cddfSDavid du Colombiertext window. This document describes the DLL interface, which consists of 817dd7cddfSDavid du Colombiereight main functions, <a href="#functions">seven platform-independent 827dd7cddfSDavid du Colombierones</a> provided by the DLL and one, <a href="#Callback">the callback 837dd7cddfSDavid du Colombierfunction</a>, provided by the caller. The DLL provides some other 847dd7cddfSDavid du Colombierplatform-specific functions for display devices. 857dd7cddfSDavid du Colombier 867dd7cddfSDavid du Colombier<p> 877dd7cddfSDavid du ColombierThe DLL's name and characteristics differ among the three platforms: 887dd7cddfSDavid du Colombier 897dd7cddfSDavid du Colombier<ul> 907dd7cddfSDavid du Colombier<li>The <a href="#OS2_device">OS/2 DLL <b><tt>GSDLL2.DLL</tt></b></a> has 917dd7cddfSDavid du ColombierMULTIPLE NONSHARED data segments and can be called by multiple programs 927dd7cddfSDavid du Colombiersimultaneously. 937dd7cddfSDavid du Colombier 947dd7cddfSDavid du Colombier<li>The <a href="#Win_device">Win32 DLL <b><tt>GSDLL32.DLL</tt></b></a> has 957dd7cddfSDavid du ColombierMULTIPLE NONSHARED data segments. Under Win32s it can be used by only one 967dd7cddfSDavid du Colombierprogram at a time, but under Windows 95/98 or Windows NT it can be called by 977dd7cddfSDavid du Colombiermultiple programs simultaneously. 987dd7cddfSDavid du Colombier 997dd7cddfSDavid du Colombier<li>The <a href="#Win16">Win16 DLL <b><tt>GSDLL16.DLL</tt></b></a> is a 1007dd7cddfSDavid du Colombierlarge-memory model DLL with far static data. Due to the limitations of 1017dd7cddfSDavid du Colombier16-bit MS Windows -- Windows 3.n -- the DLL can be used by only one program 1027dd7cddfSDavid du Colombierat a time. 1037dd7cddfSDavid du Colombier</ul> 1047dd7cddfSDavid du Colombier 1057dd7cddfSDavid du Colombier<p> 1067dd7cddfSDavid du ColombierThe source for the executable is in <b><tt>dp</tt></b>*.* (OS/2) and 1077dd7cddfSDavid du Colombier<b><tt>dw</tt></b>*.* (Windows). See these source files for examples of 1087dd7cddfSDavid du Colombierhow to use the DLL. 1097dd7cddfSDavid du Colombier 1107dd7cddfSDavid du Colombier<hr> 1117dd7cddfSDavid du Colombier 1123ff48bf5SDavid du Colombier<h2><a name="Common_functions"></a>Platform-independent DLL functions</h2> 1137dd7cddfSDavid du Colombier 1147dd7cddfSDavid du Colombier<p> 1157dd7cddfSDavid du ColombierThe seven functions provided by the DLL are 1167dd7cddfSDavid du Colombier<ul> 1177dd7cddfSDavid du Colombier<li><b><tt>int GSDLLAPI <a href="#revision">gsdll_revision</a>(char **product, char **copyright, long *gs_revision, long *gs_revisiondate)</tt></b> 1187dd7cddfSDavid du Colombier<li><b><tt>int GSDLLAPI <a href="#init">gsdll_init</a>(GSDLL_CALLBACK callback, HWND hwnd, int argc, char *argv[]);</tt></b> 1197dd7cddfSDavid du Colombier<li><b><tt>int GSDLLAPI <a href="#execute_begin">gsdll_execute_begin</a>(void);</tt></b> 1207dd7cddfSDavid du Colombier<li><b><tt>int GSDLLAPI <a href="#execute_cont">gsdll_execute_cont</a>(const char *str, int len);</tt></b> 1217dd7cddfSDavid du Colombier<li><b><tt>int GSDLLAPI <a href="#execute_end">gsdll_execute_end</a>(void);</tt></b> 1227dd7cddfSDavid du Colombier<li><b><tt>int GSDLLAPI <a href="#exit">gsdll_exit</a>(void);</tt></b> 1237dd7cddfSDavid du Colombier<li><b><tt>int GSDLLAPI <a href="#lock_device">gsdll_lock_device</a>(unsigned char *device, int flag);</tt></b> 1247dd7cddfSDavid du Colombier 1257dd7cddfSDavid du Colombier<p> 1267dd7cddfSDavid du Colombierwhere <b><tt>GSDLLAPI</tt></b> is defined under OS/2 as 1277dd7cddfSDavid du Colombier 1287dd7cddfSDavid du Colombier<blockquote><b><tt> 1297dd7cddfSDavid du Colombier#define GSDLLAPI 1307dd7cddfSDavid du Colombier</tt></b></blockquote> 1317dd7cddfSDavid du Colombier 1327dd7cddfSDavid du Colombier<p> 1337dd7cddfSDavid du Colombierand under MS Windows as 1347dd7cddfSDavid du Colombier 1357dd7cddfSDavid du Colombier<blockquote><b><tt> 1367dd7cddfSDavid du Colombier#define GSDLLAPI CALLBACK _export 1377dd7cddfSDavid du Colombier</tt></b></blockquote> 1387dd7cddfSDavid du Colombier</ul> 1397dd7cddfSDavid du Colombier 1403ff48bf5SDavid du Colombier<h3><a name="revision"></a><b><tt>gsdll_revision()</tt></b></h3> 1417dd7cddfSDavid du Colombier 1427dd7cddfSDavid du Colombier<blockquote> 1437dd7cddfSDavid du ColombierThis function returns the revision numbers and strings of the Ghostscript 1447dd7cddfSDavid du ColombierDLL; you should call it before <b><tt>gsdll_init()</tt></b> to make sure 1457dd7cddfSDavid du Colombierthat the correct version of the Ghostscript DLL has been loaded. For 1467dd7cddfSDavid du Colombierexample 1477dd7cddfSDavid du Colombier 1487dd7cddfSDavid du Colombier<blockquote> 1497dd7cddfSDavid du Colombier<pre>char *product; 1507dd7cddfSDavid du Colombierchar *copyright; 1517dd7cddfSDavid du Colombierlong revision; 1527dd7cddfSDavid du Colombierlong revisiondate; 1537dd7cddfSDavid du Colombiergsdll_revision(&product, &copyright, &revision, &revisiondate); 1547dd7cddfSDavid du Colombier</pre></blockquote> 1557dd7cddfSDavid du Colombier 1567dd7cddfSDavid du Colombier<p> 1577dd7cddfSDavid du ColombierYou may use <b><tt>NULL</tt></b> pointers if you do not want a particular 1587dd7cddfSDavid du Colombiervalue. 1597dd7cddfSDavid du Colombier</blockquote> 1607dd7cddfSDavid du Colombier 1613ff48bf5SDavid du Colombier<h3><a name="init"></a><b><tt>gsdll_init()</tt></b></h3> 1627dd7cddfSDavid du Colombier 1637dd7cddfSDavid du Colombier<blockquote> 1647dd7cddfSDavid du Colombier<b><tt>gsdll_init()</tt></b> must be called after loading the DLL and 1657dd7cddfSDavid du Colombierbefore executing any Ghostscript commands. The arguments are the address 1667dd7cddfSDavid du Colombierof the callback function, a parent window handle, the count of arguments 1677dd7cddfSDavid du Colombierand an array of pointers to the arguments. For example 1687dd7cddfSDavid du Colombier 1697dd7cddfSDavid du Colombier<blockquote> 1707dd7cddfSDavid du Colombier<pre>char *argv[5]; 1717dd7cddfSDavid du Colombierargv[0] = "gswin.exe"; 1727dd7cddfSDavid du Colombierargv[1] = "-Ic:\\gs;c:\gs\\fonts"; 1737dd7cddfSDavid du Colombierargv[2] = "-dNOPAUSE", 1747dd7cddfSDavid du Colombierargv[3] = "-sDEVICE=djet500", 1757dd7cddfSDavid du Colombierargv[4] = NULL; 1767dd7cddfSDavid du Colombierargc = 4; 1777dd7cddfSDavid du Colombier 1787dd7cddfSDavid du Colombiercode = gsdll_init(gsdll_callback, hwnd, argc, argv); 1797dd7cddfSDavid du Colombier</pre></blockquote> 1807dd7cddfSDavid du Colombier 1817dd7cddfSDavid du Colombier<p> 1827dd7cddfSDavid du Colombier<b><tt>hwnd</tt></b> is used as the parent window handle for any windows 1837dd7cddfSDavid du Colombiercreated by Ghostscript. <b><tt>hwnd</tt></b> may be <b><tt>NULL</tt></b> 1847dd7cddfSDavid du Colombierif the caller has no windows, but if it is <b><tt>NULL</tt></b>, you should 1857dd7cddfSDavid du Colombieravoid using devices which may open windows. 1867dd7cddfSDavid du Colombier 1877dd7cddfSDavid du Colombier<p> 1887dd7cddfSDavid du ColombierA return code of 0 (zero) indicates no errors, and the code may now call 1897dd7cddfSDavid du Colombier<b><tt>gsdll_execute_begin()</tt></b> or <b><tt>gsdll_exit()</tt></b>. If 1907dd7cddfSDavid du Colombierthe return value is non-zero then <b><tt>gsdll_exit()</tt></b> must not be 1917dd7cddfSDavid du Colombiercalled. 1927dd7cddfSDavid du Colombier 1937dd7cddfSDavid du Colombier<p> 1947dd7cddfSDavid du ColombierA return value of <b><tt>GSDLL_INIT_QUIT</tt></b> indicates that one of the 1957dd7cddfSDavid du Colombiercommand line files or arguments called "<b><tt>quit</tt></b>", or that 1967dd7cddfSDavid du ColombierGhostscript was reading stdin and reached end-of-file. This is not an 1977dd7cddfSDavid du Colombiererror. <b><tt>gsdll_exit()</tt></b> must not be called. 1987dd7cddfSDavid du Colombier 1997dd7cddfSDavid du Colombier<p> 2007dd7cddfSDavid du ColombierA return value of <b><tt>GSDLL_INIT_IN_USE</tt></b> indicates that the DLL 2017dd7cddfSDavid du Colombieris in use by another application (Windows 3.1 only). The DLL should be 2027dd7cddfSDavid du Colombierimmediately unloaded (or the caller terminated). 2037dd7cddfSDavid du Colombier<b><tt>gsdll_exit()</tt></b> must not be called. 2047dd7cddfSDavid du Colombier</blockquote> 2057dd7cddfSDavid du Colombier 2063ff48bf5SDavid du Colombier<h3><a name="execute_begin"></a><b><tt>gsdll_execute_begin()</tt></b></h3> 2077dd7cddfSDavid du Colombier 2087dd7cddfSDavid du Colombier<blockquote> 2097dd7cddfSDavid du ColombierThis must be called after <b><tt>gsdll_init()</tt></b> and before 2107dd7cddfSDavid du Colombier<b><tt>gsdll_execute_cont()</tt></b>. 2117dd7cddfSDavid du Colombier</blockquote> 2127dd7cddfSDavid du Colombier 2133ff48bf5SDavid du Colombier<h3><a name="execute_cont"></a><b><tt>gsdll_execute_cont()</tt></b></h3> 2147dd7cddfSDavid du Colombier 2157dd7cddfSDavid du Colombier<blockquote> 2167dd7cddfSDavid du ColombierAfter successfully calling <b><tt>gsdll_init()</tt></b> and 2177dd7cddfSDavid du Colombier<b><tt>gsdll_execute_begin()</tt></b>, commands may be given to Ghostscript 2187dd7cddfSDavid du Colombierwith <b><tt>gsdll_execute_cont()</tt></b>. Examples are: 2197dd7cddfSDavid du Colombier 2207dd7cddfSDavid du Colombier<blockquote> 2217dd7cddfSDavid du Colombier<pre>char *command = "1 2 add == flush\n"; 2227dd7cddfSDavid du Colombiercode = gsdll_execute_cont(command, strlen(command)); 2237dd7cddfSDavid du Colombiercommand = "qu" 2247dd7cddfSDavid du Colombiercode = gsdll_execute_cont(command, strlen(command)); 2257dd7cddfSDavid du Colombiercommand = "it\n" 2267dd7cddfSDavid du Colombiercode = gsdll_execute_cont(command, strlen(command)); 2277dd7cddfSDavid du Colombier</pre> 2287dd7cddfSDavid du Colombier 2297dd7cddfSDavid du Colombier<a name="cont_returns"></a> 2307dd7cddfSDavid du Colombier<table cellpadding=0 cellspacing=0> 2317dd7cddfSDavid du Colombier<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Return codes from <b><tt>gsdll_execute_cont()</tt></b></font><hr> 2327dd7cddfSDavid du Colombier<tr valign=bottom> 2337dd7cddfSDavid du Colombier <th align=left>Code 2347dd7cddfSDavid du Colombier <td> 2357dd7cddfSDavid du Colombier <th align=left>Status 2367dd7cddfSDavid du Colombier<tr> <td colspan=3><hr> 2377dd7cddfSDavid du Colombier<tr valign=top> <td align=left>0 2387dd7cddfSDavid du Colombier <td> 2397dd7cddfSDavid du Colombier <td>No errors 2407dd7cddfSDavid du Colombier<tr valign=top> <td align=left>< 0 2417dd7cddfSDavid du Colombier <td> 2427dd7cddfSDavid du Colombier <td>Error 2437dd7cddfSDavid du Colombier<tr valign=top> <td align=left><= -100 2447dd7cddfSDavid du Colombier <td> 2457dd7cddfSDavid du Colombier <td>"<b><tt>quit</tt></b>" has been executed, or fatal error. 2467dd7cddfSDavid du Colombier<b><tt>gsdll_exit()</tt></b> must then be called: do not call 2477dd7cddfSDavid du Colombier<b><tt>gsdll_execute_end()</tt></b>. 2487dd7cddfSDavid du Colombier</table> 2497dd7cddfSDavid du Colombier</blockquote> 2507dd7cddfSDavid du Colombier 2517dd7cddfSDavid du Colombier<b><tt>gsdll_execute_cont()</tt></b> 2527dd7cddfSDavid du Colombierdoes not flush stdio, so if you want to see output from Ghostscript you 2537dd7cddfSDavid du Colombiermust do this explicitly as shown in the example above. 2547dd7cddfSDavid du Colombier 2557dd7cddfSDavid du Colombier<p> 2567dd7cddfSDavid du ColombierWhen executing a string with <b><tt>gsdll_execute_cont()</tt></b>, 2577dd7cddfSDavid du Colombier<b><tt>currentfile</tt></b> is the input from 2587dd7cddfSDavid du Colombier<b><tt>gsdll_execute_cont()</tt></b>. Reading from <b><tt>%stdin</tt></b> 2597dd7cddfSDavid du Colombieruses the callback. 2603ff48bf5SDavid du Colombier 261*593dc095SDavid du Colombier<p> 262*593dc095SDavid du ColombierPlease note that there is a 64 KB length limit on the passed string. 263*593dc095SDavid du ColombierIf you have more than 65535 bytes of input to process at a given time, 264*593dc095SDavid du Colombierit must be split into separate smaller buffers, each passed on a 265*593dc095SDavid du Colombierseparate call. 266*593dc095SDavid du Colombier 2677dd7cddfSDavid du Colombier</blockquote> 2687dd7cddfSDavid du Colombier 2693ff48bf5SDavid du Colombier<h3><a name="execute_end"></a><b><tt>gsdll_execute_end()</tt></b></h3> 2707dd7cddfSDavid du Colombier 2717dd7cddfSDavid du Colombier<blockquote> 2727dd7cddfSDavid du ColombierIf <b><tt>gsdll_execute_cont()</tt></b> did not return an error, then 2737dd7cddfSDavid du Colombier<b><tt>gsdll_execute_end()</tt></b> must be called after 2747dd7cddfSDavid du Colombier<b><tt>gsdll_execute_cont()</tt></b> and before 2757dd7cddfSDavid du Colombier<b><tt>gsdll_exit()</tt></b>. 2767dd7cddfSDavid du Colombier</blockquote> 2777dd7cddfSDavid du Colombier 2783ff48bf5SDavid du Colombier<h3><a name="exit"></a><b><tt>gsdll_exit()</tt></b></h3> 2797dd7cddfSDavid du Colombier 2807dd7cddfSDavid du Colombier<blockquote> 2817dd7cddfSDavid du ColombierCall gsdll_exit() to terminate the Ghostscript DLL. It must be called if a 2827dd7cddfSDavid du Colombierfatal error has occurred; see the <a href="#cont_returns">return value 2837dd7cddfSDavid du Colombierof <b><tt>gsdll_execute_cont()</tt></b></a>. After calling 2847dd7cddfSDavid du Colombier<b><tt>gsdll_exit()</tt></b>, there are two options: 2857dd7cddfSDavid du Colombier 2867dd7cddfSDavid du Colombier<ul> 2877dd7cddfSDavid du Colombier<li>Unload the DLL, either by terminating the application or by 2887dd7cddfSDavid du Colombiercalling <b><tt>DosFreeModule</tt></b> (OS/2) or <b><tt>FreeLibrary</tt></b> (MS Windows). 2897dd7cddfSDavid du Colombier 2907dd7cddfSDavid du Colombier<li>Call <b><tt>gsdll_init()</tt></b> again to restart Ghostscript. 2917dd7cddfSDavid du Colombier</ul> 2927dd7cddfSDavid du Colombier</blockquote> 2937dd7cddfSDavid du Colombier 2943ff48bf5SDavid du Colombier<h3><a name="lock_device"></a><b><tt>gsdll_lock_device()</tt></b></h3> 2957dd7cddfSDavid du Colombier 2967dd7cddfSDavid du Colombier<blockquote> 2977dd7cddfSDavid du ColombierSince the caller may be multithreaded, a lock is needed to control access 2987dd7cddfSDavid du Colombierto the display device, and <b><tt>gsdll_lock_device()</tt></b> provides that 2997dd7cddfSDavid du Colombierlocking. 3007dd7cddfSDavid du Colombier 3017dd7cddfSDavid du Colombier<blockquote> 3027dd7cddfSDavid du Colombier<pre>int gsdll_lock_device(unsigned char *device, int flag); 3037dd7cddfSDavid du Colombier /* Lock the device if flag = TRUE */ 3047dd7cddfSDavid du Colombier /* Unlock the device if flag = FALSE */ 3057dd7cddfSDavid du Colombier /* device is a pointer to Ghostscript os2dll or mswindll device */ 3067dd7cddfSDavid du Colombier /* from GSDLL_DEVICE message. */ 3077dd7cddfSDavid du Colombier /* Return value is the lock count. */ 3087dd7cddfSDavid du Colombier</pre> 3097dd7cddfSDavid du Colombier 3107dd7cddfSDavid du Colombier<table cellpadding=0 cellspacing=0> 3117dd7cddfSDavid du Colombier<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Locking and unlocking devices</font><hr> 3127dd7cddfSDavid du Colombier<tr valign=top> <td>To lock a device 3137dd7cddfSDavid du Colombier <td> 3147dd7cddfSDavid du Colombier <td><b><tt>gsdll_lock_device(device, 1)</tt></b>; 3157dd7cddfSDavid du Colombier<tr valign=top> <td>To unlock a device 3167dd7cddfSDavid du Colombier <td> 3177dd7cddfSDavid du Colombier <td><b><tt>gsdll_lock_device(device, 0)</tt></b>; 3187dd7cddfSDavid du Colombier</table> 3197dd7cddfSDavid du Colombier</blockquote> 3207dd7cddfSDavid du Colombier 3217dd7cddfSDavid du Colombier<p> 3227dd7cddfSDavid du ColombierThis function is typically used to lock the device while repainting a 3237dd7cddfSDavid du Colombierwindow or copying the device bitmap to the clipboard. Ghostscript may draw 3247dd7cddfSDavid du Colombierinto the device bitmap or update the palette entries while the device is 3257dd7cddfSDavid du Colombierlocked by the caller, but locking the device prevents the Ghostscript DLL 3267dd7cddfSDavid du Colombierfrom closing the device or changing its size or depth. 3277dd7cddfSDavid du Colombier 3287dd7cddfSDavid du Colombier<p> 3297dd7cddfSDavid du ColombierUnder OS/2, Windows 95/98 and Windows NT, this lock is implemented using a 3307dd7cddfSDavid du Colombiermutual exclusion semaphore (mutex). The return value is the lock count, 3317dd7cddfSDavid du Colombierwhich is either 0 ("unlocked") or 1 ("locked"). The function blocks until 3327dd7cddfSDavid du Colombierthe device is locked by the caller. 3337dd7cddfSDavid du Colombier 3347dd7cddfSDavid du Colombier<p> 3357dd7cddfSDavid du ColombierUnder Win16 or Win32s, <b><tt>gsdll_lock_device()</tt></b> always returns 3367dd7cddfSDavid du Colombierimmediately with a lock count as its return value. A lock count of 2 or 3377dd7cddfSDavid du Colombiermore is definite indication of an error, probably calling the function 3387dd7cddfSDavid du Colombiertwice. Access to the device should be controlled by checking the Windows 3397dd7cddfSDavid du Colombiermessage queue only when the bitmap is not being accessed. 3407dd7cddfSDavid du Colombier</blockquote> 3417dd7cddfSDavid du Colombier 3427dd7cddfSDavid du Colombier<hr> 3437dd7cddfSDavid du Colombier 3443ff48bf5SDavid du Colombier<h2><a name="Callback"></a>Callback function</h2> 3457dd7cddfSDavid du Colombier 3467dd7cddfSDavid du Colombier<blockquote> 3477dd7cddfSDavid du ColombierAs an argument to <a href="#init"><b><tt>gsdll_init()</tt></b></a> the 3487dd7cddfSDavid du Colombiercaller must provide a callback function which the DLL invokes for stdio and 3497dd7cddfSDavid du Colombierto notify the caller about device events. The function provided by the 3507dd7cddfSDavid du Colombiercaller has this prototype: 3517dd7cddfSDavid du Colombier 3527dd7cddfSDavid du Colombier<blockquote><b><tt> 3537dd7cddfSDavid du Colombierint gsdll_callback(int message, char *str, unsigned long count); 3547dd7cddfSDavid du Colombier</tt></b></blockquote> 3557dd7cddfSDavid du Colombier 3567dd7cddfSDavid du Colombier<p> 3577dd7cddfSDavid du ColombierThe Pascal calling convention is not used. An example callback function 3587dd7cddfSDavid du Colombieris: 3597dd7cddfSDavid du Colombier 3607dd7cddfSDavid du Colombier<blockquote> 3613ff48bf5SDavid du Colombier<pre>int 3627dd7cddfSDavid du Colombiergsdll_callback(int message, char *str, unsigned long count) 3637dd7cddfSDavid du Colombier{ 3647dd7cddfSDavid du Colombierchar *p; 3657dd7cddfSDavid du Colombier switch (message) { 3667dd7cddfSDavid du Colombier case GSDLL_STDIN: 3677dd7cddfSDavid du Colombier p = fgets(str, count, stdin); 3687dd7cddfSDavid du Colombier if (p) 3697dd7cddfSDavid du Colombier return strlen(str); 3707dd7cddfSDavid du Colombier else 3717dd7cddfSDavid du Colombier return 0; 3727dd7cddfSDavid du Colombier case GSDLL_STDOUT: 3737dd7cddfSDavid du Colombier if (str != (char *)NULL) 3747dd7cddfSDavid du Colombier fwrite(str, 1, count, stdout); 3757dd7cddfSDavid du Colombier return count; 3767dd7cddfSDavid du Colombier case GSDLL_DEVICE: 3777dd7cddfSDavid du Colombier fprintf(stdout,"Callback: DEVICE %p %s\n", str, 3787dd7cddfSDavid du Colombier count ? "open" : "close"); 3797dd7cddfSDavid du Colombier break; 3807dd7cddfSDavid du Colombier case GSDLL_SYNC: 3817dd7cddfSDavid du Colombier fprintf(stdout,"Callback: SYNC %p\n", str); 3827dd7cddfSDavid du Colombier break; 3837dd7cddfSDavid du Colombier case GSDLL_PAGE: 3847dd7cddfSDavid du Colombier fprintf(stdout,"Callback: PAGE %p\n", str); 3857dd7cddfSDavid du Colombier break; 3867dd7cddfSDavid du Colombier case GSDLL_SIZE: 3877dd7cddfSDavid du Colombier fprintf(stdout,"Callback: SIZE %p width=%d height=%d\n", str, 3887dd7cddfSDavid du Colombier (int)(count & 0xffff), (int)((count>>16) & 0xffff) ); 3897dd7cddfSDavid du Colombier break; 3907dd7cddfSDavid du Colombier case GSDLL_POLL: 3917dd7cddfSDavid du Colombier return 0; /* no error */ 3927dd7cddfSDavid du Colombier default: 3937dd7cddfSDavid du Colombier fprintf(stdout,"Callback: Unknown message=%d\n",message); 3947dd7cddfSDavid du Colombier break; 3957dd7cddfSDavid du Colombier } 3967dd7cddfSDavid du Colombier return 0; 3977dd7cddfSDavid du Colombier} 3983ff48bf5SDavid du Colombier</pre> 3997dd7cddfSDavid du Colombier 4007dd7cddfSDavid du Colombier<table cellpadding=0 cellspacing=0> 4017dd7cddfSDavid du Colombier<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Messages used by callback</font><hr> 4027dd7cddfSDavid du Colombier<tr valign=bottom> 4037dd7cddfSDavid du Colombier <th align=left>Symbol 4047dd7cddfSDavid du Colombier <td> 4057dd7cddfSDavid du Colombier <th align=left> 4067dd7cddfSDavid du Colombier <td> 4077dd7cddfSDavid du Colombier <th align=left>Use 4087dd7cddfSDavid du Colombier<tr> <td colspan=5><hr> 4097dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>GSDLL_STDIN</tt></b> 4107dd7cddfSDavid du Colombier <td> 4117dd7cddfSDavid du Colombier <td>1 4127dd7cddfSDavid du Colombier <td> 4137dd7cddfSDavid du Colombier <td>get <b><tt>count</tt></b> characters to <b><tt>str</tt></b> from stdin, return number of characters read 4147dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>GSDLL_STDOUT</tt></b> 4157dd7cddfSDavid du Colombier <td> 4167dd7cddfSDavid du Colombier <td>2 4177dd7cddfSDavid du Colombier <td> 4187dd7cddfSDavid du Colombier <td>put <b><tt>count</tt></b> characters from <b><tt>str</tt></b> 4197dd7cddfSDavid du Colombier to stdout, return number of characters written 4207dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>GSDLL_DEVICE</tt></b> 4217dd7cddfSDavid du Colombier <td> 4227dd7cddfSDavid du Colombier <td>3 4237dd7cddfSDavid du Colombier <td> 4247dd7cddfSDavid du Colombier <td>device <b><tt>str</tt></b> has been opened if 4257dd7cddfSDavid du Colombier <b><tt>count</tt></b> = 1, closed if 4267dd7cddfSDavid du Colombier <b><tt>count</tt></b> = 0 4277dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>GSDLL_SYNC</tt></b> 4287dd7cddfSDavid du Colombier <td> 4297dd7cddfSDavid du Colombier <td>4 4307dd7cddfSDavid du Colombier <td> 4317dd7cddfSDavid du Colombier <td>sync_output for device <b><tt>str</tt></b> 4327dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>GSDLL_PAGE</tt></b> 4337dd7cddfSDavid du Colombier <td> 4347dd7cddfSDavid du Colombier <td>5 4357dd7cddfSDavid du Colombier <td> 4367dd7cddfSDavid du Colombier <td>output_page for device <b><tt>str</tt></b> 4377dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>GSDLL_SIZE</tt></b> 4387dd7cddfSDavid du Colombier <td> 4397dd7cddfSDavid du Colombier <td>6 4407dd7cddfSDavid du Colombier <td> 4417dd7cddfSDavid du Colombier <td>resize for device <b><tt>str</tt></b>: 4427dd7cddfSDavid du Colombier LOWORD(<b><tt>count</tt></b>) is new <b><tt>xsize</tt></b>, 4437dd7cddfSDavid du Colombier HIWORD(<b><tt>count</tt></b>) is new <b><tt>ysize</tt></b> 4447dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>GSDLL_POLL</tt></b> 4457dd7cddfSDavid du Colombier <td> 4467dd7cddfSDavid du Colombier <td>7 4477dd7cddfSDavid du Colombier <td> 4487dd7cddfSDavid du Colombier <td>Called from <b><tt>gp_check_interrupt()</tt></b><br> 4497dd7cddfSDavid du Colombier Can be used by the caller to poll the message queue. 4507dd7cddfSDavid du Colombier Normally returns 0. To abort 4517dd7cddfSDavid du Colombier <b><tt>gsdll_execute_cont()</tt></b>, return a non-zero 4527dd7cddfSDavid du Colombier error code until <b><tt>gsdll_execute_cont()</tt></b> 4537dd7cddfSDavid du Colombier returns. 4547dd7cddfSDavid du Colombier</table> 4557dd7cddfSDavid du Colombier</blockquote> 4567dd7cddfSDavid du Colombier</blockquote> 4577dd7cddfSDavid du Colombier 4587dd7cddfSDavid du Colombier<hr> 4597dd7cddfSDavid du Colombier 4603ff48bf5SDavid du Colombier<h2><a name="OS2_device"></a>Ghostscript DLL device for OS/2</h2> 4617dd7cddfSDavid du Colombier 4627dd7cddfSDavid du Colombier<p> 4637dd7cddfSDavid du ColombierThe <b><tt>os2dll</tt></b> device is provided in the Ghostscript DLL for 4647dd7cddfSDavid du Colombieruse by the caller. No drawing facilities are provided by the DLL because 4657dd7cddfSDavid du Colombierthe DLL may be loaded by a text-only (non-PM) application. The caller is 4667dd7cddfSDavid du Colombiernotified via the <b><tt>gsdll_callback()</tt></b> when a new 4677dd7cddfSDavid du Colombier<b><tt>os2dll</tt></b> device is opened or closed 4687dd7cddfSDavid du Colombier(<b><tt>GSDLL_DEVICE</tt></b>), when the window should be redrawn 4697dd7cddfSDavid du Colombier(<b><tt>GSDLL_SYNC</tt></b> or <b><tt>GSDLL_PAGE</tt></b>) or when the 4707dd7cddfSDavid du Colombierbitmap size changes (<b><tt>GSDLL_SIZE</tt></b>). 4717dd7cddfSDavid du ColombierNote that more than one <b><tt>os2dll</tt></b> device may be opened. 4727dd7cddfSDavid du Colombier 4733ff48bf5SDavid du Colombier<h3><a name="OS2_bmp"></a><b><tt>gsdll_get_bitmap()</tt></b></h3> 4747dd7cddfSDavid du Colombier 4757dd7cddfSDavid du Colombier<blockquote> 4767dd7cddfSDavid du Colombier<b><tt>gsdll_get_bitmap()</tt></b> returns a pointer to a bitmap in BMP 4777dd7cddfSDavid du Colombierformat. The <b><tt>os2dll</tt></b> device draws into this bitmap. 4787dd7cddfSDavid du Colombier 4797dd7cddfSDavid du Colombier<blockquote> 4807dd7cddfSDavid du Colombier<pre>unsigned long gsdll_get_bitmap(unsigned char *device, unsigned char **pbitmap); 4817dd7cddfSDavid du Colombier /* return in pbitmap the address of the bitmap */ 4827dd7cddfSDavid du Colombier /* device is a pointer to Ghostscript os2dll device from GSDLL_DEVICE message */ 4837dd7cddfSDavid du Colombier</pre></blockquote> 4847dd7cddfSDavid du Colombier 4857dd7cddfSDavid du Colombier<p> 4867dd7cddfSDavid du ColombierThe caller can then display the bitmap however it likes, but should lock 4877dd7cddfSDavid du Colombierthe bitmap with <b><tt>gsdll_lock_device()</tt></b> before painting from 4887dd7cddfSDavid du Colombierit, and unlock it afterwards. The bitmap address does not change until the 4897dd7cddfSDavid du Colombier<b><tt>os2dll</tt></b> device is closed; however the bitmap size and 4907dd7cddfSDavid du Colombierpalette may change whenever the bitmap is not locked. 4917dd7cddfSDavid du Colombier</blockquote> 4927dd7cddfSDavid du Colombier 4933ff48bf5SDavid du Colombier<h3><a name="OS2_example"></a>Example DLL usage for OS/2</h3> 4947dd7cddfSDavid du Colombier 4957dd7cddfSDavid du Colombier<p> 4967dd7cddfSDavid du ColombierThe example here shows a minimal usage of the Ghostscript DLL under OS/2. 4977dd7cddfSDavid du ColombierThe sample callback function above is needed. 4987dd7cddfSDavid du Colombier 4997dd7cddfSDavid du Colombier<blockquote> 5003ff48bf5SDavid du Colombier<pre>#define INCL_DOS 5017dd7cddfSDavid du Colombier#include <os2.h> 5027dd7cddfSDavid du Colombier#include <stdio.h> 5037dd7cddfSDavid du Colombier#include "gsdll.h" 5047dd7cddfSDavid du Colombier 5057dd7cddfSDavid du ColombierPFN_gsdll_init pgsdll_init; 5067dd7cddfSDavid du ColombierPFN_gsdll_execute_begin pgsdll_execute_begin; 5077dd7cddfSDavid du ColombierPFN_gsdll_execute_cont pgsdll_execute_cont; 5087dd7cddfSDavid du ColombierPFN_gsdll_execute_end pgsdll_execute_end; 5097dd7cddfSDavid du ColombierPFN_gsdll_exit pgsdll_exit; 5107dd7cddfSDavid du Colombier 5117dd7cddfSDavid du ColombierHMODULE hmodule_gsdll; 5127dd7cddfSDavid du Colombierchar buf[256]; 5137dd7cddfSDavid du Colombier 5147dd7cddfSDavid du Colombierint 5157dd7cddfSDavid du Colombiermain(int argc, char *argv[]) 5167dd7cddfSDavid du Colombier{ 5177dd7cddfSDavid du Colombierint code; 5187dd7cddfSDavid du ColombierAPIRET rc; 5197dd7cddfSDavid du Colombier if (!DosLoadModule(buf, sizeof(buf), "GSDLL2", &hmodule_gsdll)) { 5207dd7cddfSDavid du Colombier fprintf(stderr, "Loaded GSDLL2\n"); 5217dd7cddfSDavid du Colombier DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_init", (PFN *)(&pgsdll_init)); 5227dd7cddfSDavid du Colombier DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_execute_begin", (PFN *)(&pgsdll_execute_begin)); 5237dd7cddfSDavid du Colombier DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_execute_cont", (PFN *)(&pgsdll_execute_cont)); 5247dd7cddfSDavid du Colombier DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_execute_end", (PFN *)(&pgsdll_execute_end)); 5257dd7cddfSDavid du Colombier DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_exit", (PFN *)(&pgsdll_exit)); 5267dd7cddfSDavid du Colombier } 5277dd7cddfSDavid du Colombier else { 5287dd7cddfSDavid du Colombier fprintf(stderr, "Can't load GSDLL2\n"); 5297dd7cddfSDavid du Colombier } 5307dd7cddfSDavid du Colombier 5317dd7cddfSDavid du Colombier code = (*pgsdll_init)(gsdll_callback, NULL, argc, argv); 5327dd7cddfSDavid du Colombier fprintf(stdout,"gsdll_init returns %d\n", code); 5337dd7cddfSDavid du Colombier code = (*pgsdll_execute_begin)(); 5347dd7cddfSDavid du Colombier if (code==0) { 5357dd7cddfSDavid du Colombier while (fgets(buf, sizeof(buf), stdin)) { 5367dd7cddfSDavid du Colombier code = (*pgsdll_execute_cont)(buf, strlen(buf)); 5377dd7cddfSDavid du Colombier fprintf(stdout,"gsdll_execute returns %d\n", code); 5387dd7cddfSDavid du Colombier if (code < 0) 5397dd7cddfSDavid du Colombier break; 5407dd7cddfSDavid du Colombier } 5417dd7cddfSDavid du Colombier if (!code) 5427dd7cddfSDavid du Colombier code = (*pgsdll_execute_end)(); 5437dd7cddfSDavid du Colombier code = (*pgsdll_exit)(); 5447dd7cddfSDavid du Colombier fprintf(stdout,"gsdll_exit returns %d\n", code); 5457dd7cddfSDavid du Colombier } 5467dd7cddfSDavid du Colombier rc = DosFreeModule(hmodule_gsdll); 5477dd7cddfSDavid du Colombier fprintf(stdout,"DosFreeModule returns %d\n", rc); 5487dd7cddfSDavid du Colombier return 0; 5497dd7cddfSDavid du Colombier} 5503ff48bf5SDavid du Colombier</pre></blockquote> 5517dd7cddfSDavid du Colombier 5527dd7cddfSDavid du Colombier<hr> 5537dd7cddfSDavid du Colombier 5543ff48bf5SDavid du Colombier<h2><a name="Win_device"></a>Ghostscript DLL device for MS Windows</h2> 5557dd7cddfSDavid du Colombier 5567dd7cddfSDavid du Colombier<p> 5577dd7cddfSDavid du ColombierThe <b><tt>mswindll</tt></b> device is provided in the Ghostscript DLL for 5587dd7cddfSDavid du Colombieruse by the caller. The caller is notified via the 5597dd7cddfSDavid du Colombier<b><tt>gsdll_callback()</tt></b> when a new <b><tt>mswindll</tt></b> device 5607dd7cddfSDavid du Colombieris opened or closed (<b><tt>GSDLL_DEVICE</tt></b>), when the window should 5617dd7cddfSDavid du Colombierbe redrawn (<b><tt>GSDLL_SYNC</tt></b> or <b><tt>GSDLL_PAGE</tt></b>) or 5627dd7cddfSDavid du Colombierwhen the bitmap size changes (<b><tt>GSDLL_SIZE</tt></b>). Note that more 5637dd7cddfSDavid du Colombierthan one <b><tt>mswindll</tt></b> device may be opened. 5647dd7cddfSDavid du Colombier 5657dd7cddfSDavid du Colombier<p> 5667dd7cddfSDavid du ColombierFour DLL functions are available to use the <b><tt>mswindll</tt></b> 5677dd7cddfSDavid du Colombierdevice. 5687dd7cddfSDavid du Colombier 5693ff48bf5SDavid du Colombier<h3><a name="Win_copydib"></a><b><tt>gsdll_copy_dib()</tt></b></h3> 5707dd7cddfSDavid du Colombier 5717dd7cddfSDavid du Colombier<blockquote> 5727dd7cddfSDavid du ColombierCopy the <b><tt>mswindll</tt></b> bitmap to the clipboard. 5737dd7cddfSDavid du Colombier 5747dd7cddfSDavid du Colombier<blockquote> 5757dd7cddfSDavid du Colombier<pre>HGLOBAL GSDLLAPI gsdll_copy_dib(unsigned char *device); 5767dd7cddfSDavid du Colombier /* make a copy of the device bitmap and return shared memory handle to it */ 5777dd7cddfSDavid du Colombier /* device is a pointer to Ghostscript device from GSDLL_DEVICE message */ 5787dd7cddfSDavid du Colombier</pre></blockquote> 5797dd7cddfSDavid du Colombier</blockquote> 5807dd7cddfSDavid du Colombier 5813ff48bf5SDavid du Colombier<h3><a name="Win_copypalette"></a><b><tt>gsdll_copy_palette()</tt></b></h3> 5827dd7cddfSDavid du Colombier 5837dd7cddfSDavid du Colombier<blockquote> 5847dd7cddfSDavid du ColombierCopy the <b><tt>mswindll</tt></b> palette to the clipboard. 5857dd7cddfSDavid du Colombier 5867dd7cddfSDavid du Colombier<blockquote> 5877dd7cddfSDavid du Colombier<pre>HPALETTE GSDLLAPI gsdll_copy_palette(unsigned char *device); 5887dd7cddfSDavid du Colombier/* make a copy of the device palette and return a handle to it */ 5897dd7cddfSDavid du Colombier/* device is a pointer to Ghostscript device from GSDLL_DEVICE message */ 5907dd7cddfSDavid du Colombier</pre></blockquote> 5917dd7cddfSDavid du Colombier</blockquote> 5927dd7cddfSDavid du Colombier 5933ff48bf5SDavid du Colombier<h3><a name="Win_draw"></a><b><tt>gsdll_draw()</tt></b></h3> 5947dd7cddfSDavid du Colombier 5957dd7cddfSDavid du Colombier<blockquote> 5967dd7cddfSDavid du ColombierDisplay output from the <b><tt>mswindll</tt></b> device. The caller should 5977dd7cddfSDavid du Colombiercreate a window and call <b><tt>gsdll_draw()</tt></b> in response to the 5987dd7cddfSDavid du Colombier<b><tt>WM_PAINT</tt></b> message. The device context <b><tt>hdc</tt></b> 5997dd7cddfSDavid du Colombiermust be for a device because <b><tt>SetDIBitsToDevice()</tt></b> is used. 6007dd7cddfSDavid du Colombier 6017dd7cddfSDavid du Colombier<blockquote> 6027dd7cddfSDavid du Colombier<pre>void GSDLLAPI gsdll_draw(unsigned char *device, HDC hdc, 6037dd7cddfSDavid du Colombier LPRECT dest, LPRECT src); 6047dd7cddfSDavid du Colombier/* copy the rectangle src from the device bitmap */ 6057dd7cddfSDavid du Colombier/* to the rectangle dest on the device given by hdc */ 6067dd7cddfSDavid du Colombier/* hdc must be a device context for a device (NOT a bitmap) */ 6077dd7cddfSDavid du Colombier/* device is a pointer to Ghostscript device from GSDLL_DEVICE message */ 6087dd7cddfSDavid du Colombier</pre></blockquote> 6097dd7cddfSDavid du Colombier</blockquote> 6107dd7cddfSDavid du Colombier 6113ff48bf5SDavid du Colombier<h3><a name="Win_get_row"></a><b><tt>gsdll_get_bitmap_row()</tt></b></h3> 6127dd7cddfSDavid du Colombier 6137dd7cddfSDavid du Colombier<blockquote> 6147dd7cddfSDavid du ColombierGet a BMP header, a palette, and a pointer to a row in the bitmap. This 6157dd7cddfSDavid du Colombierfunction exists to allow the bitmap to be copied to a file or structured 6167dd7cddfSDavid du Colombierstorage without the overhead of having two copies of the bitmap in memory 6177dd7cddfSDavid du Colombierat the same time. 6187dd7cddfSDavid du Colombier 6197dd7cddfSDavid du Colombier<p> 6207dd7cddfSDavid du ColombierGhostscript can change the palette while the device is locked. Do not call 6217dd7cddfSDavid du Colombierthis function while Ghostscript is busy. 6227dd7cddfSDavid du Colombier 6237dd7cddfSDavid du Colombier<blockquote> 6247dd7cddfSDavid du Colombier<pre>int GSDLLAPI gsdll_get_bitmap_row(unsigned char *device, LPBITMAPINFOHEADER pbmih, 6257dd7cddfSDavid du Colombier LPRGBQUAD prgbquad, LPBYTE *ppbyte, unsigned int row) 6267dd7cddfSDavid du Colombier/* If pbmih nonzero, copy the BITMAPINFOHEADER. 6277dd7cddfSDavid du Colombier * If prgbquad nonzero, copy the palette. 6287dd7cddfSDavid du Colombier * number of entries copied is given by pbmih->biClrUsed 6297dd7cddfSDavid du Colombier * If ppbyte nonzero, return pointer to row. 6307dd7cddfSDavid du Colombier * pointer is only valid while device is locked 6317dd7cddfSDavid du Colombier */ 6327dd7cddfSDavid du Colombier</pre></blockquote> 6337dd7cddfSDavid du Colombier</blockquote> 6347dd7cddfSDavid du Colombier 6357dd7cddfSDavid du Colombier<hr> 6367dd7cddfSDavid du Colombier 6373ff48bf5SDavid du Colombier<h2><a name="Win16"></a>Ghostscript DLL Device for 16-bit MS Windows</h2> 6387dd7cddfSDavid du Colombier 6397dd7cddfSDavid du Colombier<p> 6407dd7cddfSDavid du ColombierThis platform has the most problems of the three. Support for it may be 6417dd7cddfSDavid du Colombierdropped in future. 6427dd7cddfSDavid du Colombier 6437dd7cddfSDavid du Colombier<p> 6447dd7cddfSDavid du ColombierThe Win16 DLL <b><tt>GSDLL16.DLL</tt></b> is a large-memory model DLL with 6457dd7cddfSDavid du Colombierfar static data. Due to the limitations of 16-bit MS Windows, the DLL can 6467dd7cddfSDavid du Colombierbe used by only one program at a time. 6477dd7cddfSDavid du Colombier 6487dd7cddfSDavid du Colombier<p> 6497dd7cddfSDavid du ColombierHowever, <b><tt>GSDLL16</tt></b> is marked as having SINGLE SHARED data 6507dd7cddfSDavid du Colombiersegments, allowing multiple applications to load it with no error 6517dd7cddfSDavid du Colombierindication. (The DLL wouldn't load at all if MULTIPLE NONSHARED was used). 6527dd7cddfSDavid du ColombierNonetheless, <b>it cannot be used by more than one application at a 6537dd7cddfSDavid du Colombiertime</b>, so applications loading <b><tt>GSDLL16</tt></b> should check the 6547dd7cddfSDavid du Colombierreturn value of <b><tt>gsdll_init()</tt></b>: if this value is non-zero, 6557dd7cddfSDavid du Colombierthen <b><tt>GSDLL16</tt></b> is already in use by another application and 6567dd7cddfSDavid du Colombiershould <b><em>not</em></b> be used: <b><tt>GSDLL16</tt></b> should be 6577dd7cddfSDavid du Colombierunloaded immediately using <b><tt>FreeLibrary()</tt></b>, or the calling 6587dd7cddfSDavid du Colombierprogram should quit without attempting to use the library.. 6597dd7cddfSDavid du Colombier 6607dd7cddfSDavid du Colombier<p> 6617dd7cddfSDavid du ColombierThe segmented architecture of the Intel 80286 causes the usual amount of 6627dd7cddfSDavid du Colombiergrief when using <b><tt>GSDLL16</tt></b>. Because the callback is called 6637dd7cddfSDavid du Colombierfrom the DLL, which is using a different data segment, the callback must be 6647dd7cddfSDavid du Colombierdeclared as <b><tt>_far _export</tt></b>: 6657dd7cddfSDavid du Colombier 6667dd7cddfSDavid du Colombier<blockquote> 6677dd7cddfSDavid du Colombier<pre>int _far _export gsdll_callback(int message, char *str, unsigned long count); 6687dd7cddfSDavid du Colombier</pre></blockquote> 6697dd7cddfSDavid du Colombier 6707dd7cddfSDavid du Colombier<p> 6717dd7cddfSDavid du ColombierInstead of giving <b><tt>gsdll_init()</tt></b> the address of 6727dd7cddfSDavid du Colombier<b><tt>gsdll_callback()</tt></b>, it should instead be given the address of 6737dd7cddfSDavid du Colombiera thunk created by <b><tt>MakeProcInstance</tt></b>. This thunk changes 6747dd7cddfSDavid du Colombierthe data segment back to that used by the caller: 6757dd7cddfSDavid du Colombier 6767dd7cddfSDavid du Colombier<blockquote> 6777dd7cddfSDavid du Colombier<pre>FARPROC lpfnCallback; 6787dd7cddfSDavid du ColombierlpfnCallback = (FARPROC)MakeProcInstance((FARPROC)gsdll_callback, hInstance); 6797dd7cddfSDavid du Colombiercode = (*pgsdll_init)((GSDLL_CALLBACK)lpfnCallback, NULL, argc, argv); 6807dd7cddfSDavid du Colombierif (!code) { 6817dd7cddfSDavid du Colombier fprintf(stderr, "GSDLL16 is already in use\n"); 6827dd7cddfSDavid du Colombier return -1; 6837dd7cddfSDavid du Colombier} 6847dd7cddfSDavid du Colombier</pre></blockquote> 6857dd7cddfSDavid du Colombier 6867dd7cddfSDavid du Colombier<!-- [2.0 end contents] ==================================================== --> 6877dd7cddfSDavid du Colombier 6887dd7cddfSDavid du Colombier<!-- [3.0 begin visible trailer] =========================================== --> 6897dd7cddfSDavid du Colombier<hr> 6907dd7cddfSDavid du Colombier 6913ff48bf5SDavid du Colombier<p> 6923ff48bf5SDavid du Colombier<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises. 6933ff48bf5SDavid du ColombierAll rights reserved.</small> 6947dd7cddfSDavid du Colombier 6957dd7cddfSDavid du Colombier<p> 696*593dc095SDavid du ColombierThis software is provided AS-IS with no warranty, either express or 697*593dc095SDavid du Colombierimplied. 698*593dc095SDavid du Colombier 699*593dc095SDavid du ColombierThis software is distributed under license and may not be copied, 700*593dc095SDavid du Colombiermodified or distributed except as expressly authorized under the terms 701*593dc095SDavid du Colombierof the license contained in the file LICENSE in this distribution. 702*593dc095SDavid du Colombier 703*593dc095SDavid du ColombierFor more information about licensing, please refer to 704*593dc095SDavid du Colombierhttp://www.ghostscript.com/licensing/. For information on 705*593dc095SDavid du Colombiercommercial licensing, go to http://www.artifex.com/licensing/ or 706*593dc095SDavid du Colombiercontact Artifex Software, Inc., 101 Lucas Valley Road #110, 707*593dc095SDavid du ColombierSan Rafael, CA 94903, U.S.A., +1(415)492-9861. 7087dd7cddfSDavid du Colombier 7093ff48bf5SDavid du Colombier<p> 710*593dc095SDavid du Colombier<small>Ghostscript version 8.53, 20 October 2005 7117dd7cddfSDavid du Colombier 7127dd7cddfSDavid du Colombier<!-- [3.0 end visible trailer] ============================================= --> 7137dd7cddfSDavid du Colombier 7147dd7cddfSDavid du Colombier</body> 7157dd7cddfSDavid du Colombier</html> 716