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>The Ghostscript library</title> 5*593dc095SDavid du Colombier<!-- $Id: Lib.htm,v 1.43 2005/10/20 19:46:23 ray Exp $ --> 67dd7cddfSDavid du Colombier<!-- Originally: lib.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>The Ghostscript Library</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 237dd7cddfSDavid du Colombier<blockquote><ul> 247dd7cddfSDavid du Colombier<li><a href="#GS_library">The Ghostscript library</a> 257dd7cddfSDavid du Colombier<li><a href="#PS_operator_API">PostScript operator API</a> 267dd7cddfSDavid du Colombier<ul> 277dd7cddfSDavid du Colombier<li><a href="#Patterns">Patterns</a> 287dd7cddfSDavid du Colombier<li><a href="#Lower_level_API">Lower-level API</a> 297dd7cddfSDavid du Colombier</ul> 30*593dc095SDavid du Colombier<li><a href="#Visual_trace">Visual Trace instructions</a> 317dd7cddfSDavid du Colombier<li><a href="#Full_example">A full example</a> 327dd7cddfSDavid du Colombier</ul></blockquote> 337dd7cddfSDavid du Colombier 347dd7cddfSDavid du Colombier<!-- [1.2 end table of contents] =========================================== --> 357dd7cddfSDavid du Colombier 367dd7cddfSDavid du Colombier<!-- [1.3 begin hint] ====================================================== --> 377dd7cddfSDavid du Colombier 387dd7cddfSDavid du Colombier<p>For other information, see the <a href="Readme.htm">Ghostscript 397dd7cddfSDavid du Colombieroverview</a>. 407dd7cddfSDavid du Colombier 417dd7cddfSDavid du Colombier<!-- [1.3 end hint] ======================================================== --> 427dd7cddfSDavid du Colombier 437dd7cddfSDavid du Colombier<hr> 447dd7cddfSDavid du Colombier 457dd7cddfSDavid du Colombier<!-- [1.0 end visible header] ============================================== --> 467dd7cddfSDavid du Colombier 477dd7cddfSDavid du Colombier<!-- [2.0 begin contents] ================================================== --> 487dd7cddfSDavid du Colombier 493ff48bf5SDavid du Colombier<h2><a name="GS_library"></a>The Ghostscript library</h2> 507dd7cddfSDavid du Colombier 517dd7cddfSDavid du Colombier<p> 527dd7cddfSDavid du ColombierThis document describes the Ghostscript library, a set of procedures 537dd7cddfSDavid du Colombierto implement the graphics and filtering capabilities that are primitive 547dd7cddfSDavid du Colombieroperations in the PostScript language and in Adobe Portable Document Format 557dd7cddfSDavid du Colombier(PDF). 567dd7cddfSDavid du Colombier 577dd7cddfSDavid du Colombier<p> 587dd7cddfSDavid du ColombierGhostscript is actually two programs: a language interpreter, and a 597dd7cddfSDavid du Colombiergraphics library. The library provides, in the form of C procedures, all 607dd7cddfSDavid du Colombierthe graphics functions of the language, that is, approximately those 613ff48bf5SDavid du Colombierfacilities listed in section 8.1 of the <cite>PostScript 623ff48bf5SDavid du ColombierLanguage Reference Manual</cite>, starting with the 637dd7cddfSDavid du Colombiergraphics state operators. In addition, the library provides some 647dd7cddfSDavid du Colombierlower-level graphics facilities that offer higher performance in exchange 657dd7cddfSDavid du Colombierfor less generality. 667dd7cddfSDavid du Colombier 677dd7cddfSDavid du Colombier<hr> 687dd7cddfSDavid du Colombier 693ff48bf5SDavid du Colombier<h2><a name="PS_operator_API"></a>PostScript operator API</h2> 707dd7cddfSDavid du Colombier 717dd7cddfSDavid du Colombier<p> 727dd7cddfSDavid du ColombierThe highest level of the library, which is the one that most clients will 737dd7cddfSDavid du Colombieruse, directly implements the PostScript graphics operators with procedures 747dd7cddfSDavid du Colombiernamed <b><tt>gs_XXX</tt></b>, for instance <b><tt>gs_moveto</tt></b> and 757dd7cddfSDavid du Colombier<b><tt>gs_fill</tt></b>. Nearly all of these procedures take graphics 767dd7cddfSDavid du Colombierstate objects as their first arguments, such as 777dd7cddfSDavid du Colombier 787dd7cddfSDavid du Colombier<blockquote><b><tt> 797dd7cddfSDavid du Colombierint gs_moveto(gs_state *, double, double); 807dd7cddfSDavid du Colombier</tt></b></blockquote> 817dd7cddfSDavid du Colombier 827dd7cddfSDavid du Colombier<p> 837dd7cddfSDavid du ColombierNearly every procedure returns an integer code which is >= 0 for a 847dd7cddfSDavid du Colombiersuccessful return or <0 for a failure. The failure codes correspond 857dd7cddfSDavid du Colombierdirectly to PostScript errors, and are defined in 867dd7cddfSDavid du Colombier<b><tt>gserrors.h</tt></b>. 877dd7cddfSDavid du Colombier 887dd7cddfSDavid du Colombier<p> 897dd7cddfSDavid du ColombierThe library implements all the operators in the following sections of the 903ff48bf5SDavid du Colombier<cite>PostScript Language Reference Manual</cite>, with the indicated 917dd7cddfSDavid du Colombieromissions and with the APIs defined in the indicated <b><tt>.h</tt></b> 927dd7cddfSDavid du Colombierfiles. A header of the form <b><em>A.h(B.h)</em></b> indicates that 937dd7cddfSDavid du Colombier<b><em>A.h</em></b> is included in <b><em>B.h</em></b>, so 947dd7cddfSDavid du Colombier<b><em>A.h</em></b> need not be included explicitly if <b><em>B.h</em></b> 957dd7cddfSDavid du Colombieris included. Operators marked with * in the "omissions" column are not 967dd7cddfSDavid du Colombierimplemented directly; the library provides lower-level procedures that can 977dd7cddfSDavid du Colombierbe used to implement the operator. 987dd7cddfSDavid du Colombier 997dd7cddfSDavid du Colombier<p> 1007dd7cddfSDavid du ColombierThere are slight differences in the operators that return multiple values, 1017dd7cddfSDavid du Colombiersince C's provisions for this are awkward. Also, the control structure for 1027dd7cddfSDavid du Colombierthe operators involving callback procedures (<b><tt>pathforall</tt></b>, 1037dd7cddfSDavid du Colombier<b><tt>image</tt></b>, <b><tt>colorimage</tt></b>, 1047dd7cddfSDavid du Colombier<b><tt>imagemask</tt></b>) is partly inverted: the client calls a procedure 1057dd7cddfSDavid du Colombierto set up an enumerator object, and then calls another procedure for each 1067dd7cddfSDavid du Colombieriteration. The <b><tt>...show</tt></b> operators, 1077dd7cddfSDavid du Colombier<b><tt>charpath</tt></b>, and <b><tt>stringwidth</tt></b> also use an 1087dd7cddfSDavid du Colombierinverted control structure. 1097dd7cddfSDavid du Colombier 1107dd7cddfSDavid du Colombier<blockquote><table cellpadding=0 cellspacing=0> 1117dd7cddfSDavid du Colombier<tr valign=bottom> 1127dd7cddfSDavid du Colombier <th align=left>Section<br>(operators) 1137dd7cddfSDavid du Colombier <td> 1147dd7cddfSDavid du Colombier <th align=left>Headers 1157dd7cddfSDavid du Colombier <td> 1167dd7cddfSDavid du Colombier <th align=left>Omissions 1177dd7cddfSDavid du Colombier<tr> <td colspan=5><hr> 1187dd7cddfSDavid du Colombier<tr valign=top> <td>Graphics state -- device-independent 1197dd7cddfSDavid du Colombier <td> 1207dd7cddfSDavid du Colombier <td><b><tt>gscolor.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gscolor1.h</tt></b><br><b><tt>gscolor2.h</tt></b><br><b><tt>gscspace.h</tt></b><br><b><tt>gshsb.h</tt></b><br><b><tt>gsline.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gsstate.h</tt></b> 1217dd7cddfSDavid du Colombier <td> 1227dd7cddfSDavid du Colombier <td> 1237dd7cddfSDavid du Colombier<tr> <td> 1247dd7cddfSDavid du Colombier<tr valign=top> <td>Graphics state -- device-dependent 1257dd7cddfSDavid du Colombier <td> 1267dd7cddfSDavid du Colombier <td><b><tt>gscolor.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gscolor1.h</tt></b><br><b><tt>gscolor2.h</tt></b><br><b><tt>gsht.h</tt></b>(<b><tt>gsht1.h</tt></b>,<b><tt>gsstate.h</tt></b>)<br><b><tt>gsht1.h</tt></b><br><b><tt>gsline.h</tt></b>(<b><tt>gsstate.h</tt></b>) 1277dd7cddfSDavid du Colombier <td> 1287dd7cddfSDavid du Colombier <td> 1297dd7cddfSDavid du Colombier<tr> <td> 1307dd7cddfSDavid du Colombier<tr valign=top> <td>Coordinate system and matrix 1317dd7cddfSDavid du Colombier <td> 1327dd7cddfSDavid du Colombier <td><b><tt>gscoord.h</tt></b><br><b><tt>gsmatrix.h</tt></b> 1337dd7cddfSDavid du Colombier <td> 1347dd7cddfSDavid du Colombier <td><b><tt>*matrix</tt></b>, <b><tt>*identmatrix</tt></b>, <b><tt>*concatmatrix</tt></b>, <b><tt>*invertmatrix</tt></b> 1357dd7cddfSDavid du Colombier<tr> <td> 1367dd7cddfSDavid du Colombier<tr valign=top> <td>Path construction 1377dd7cddfSDavid du Colombier <td> 1387dd7cddfSDavid du Colombier <td><b><tt>gspath.h</tt></b><br><b><tt>gspath2.h</tt></b> 1397dd7cddfSDavid du Colombier <td> 1407dd7cddfSDavid du Colombier <td><b><tt>*arct</tt></b>, <b><tt>*pathforall</tt></b>, <b><tt>ustrokepath</tt></b>, <b><tt>uappend</tt></b>, <b><tt>upath</tt></b>, <b><tt>ucache</tt></b> 1417dd7cddfSDavid du Colombier<tr> <td> 1427dd7cddfSDavid du Colombier<tr valign=top> <td>Painting 1437dd7cddfSDavid du Colombier <td> 1447dd7cddfSDavid du Colombier <td><b><tt>gsimage.h</tt></b><br><b><tt>gspaint.h</tt></b><br><b><tt>gspath2.h</tt></b> 1457dd7cddfSDavid du Colombier <td> 1467dd7cddfSDavid du Colombier <td><b><tt>*image</tt></b>, <b><tt>*colorimage</tt></b>, <b><tt>*imagemask</tt></b>, <b><tt>ufill</tt></b>, <b><tt>ueofill</tt></b>, <b><tt>ustroke</tt></b> 1477dd7cddfSDavid du Colombier<tr> <td> 1487dd7cddfSDavid du Colombier<tr valign=top> <td>Form and pattern 1497dd7cddfSDavid du Colombier <td> 1507dd7cddfSDavid du Colombier <td><b><tt>gscolor2.h</tt></b> 1517dd7cddfSDavid du Colombier <td> 1527dd7cddfSDavid du Colombier <td><b><tt>execform</tt></b> 1537dd7cddfSDavid du Colombier<tr> <td> 1547dd7cddfSDavid du Colombier<tr valign=top> <td>Device setup and output 1557dd7cddfSDavid du Colombier <td> 1567dd7cddfSDavid du Colombier <td><b><tt>gsdevice.h</tt></b> 1577dd7cddfSDavid du Colombier <td> 1587dd7cddfSDavid du Colombier <td><b><tt>*showpage</tt></b>, <b><tt>*set</tt></b>/<b><tt>currentpagedevice</tt></b> 1597dd7cddfSDavid du Colombier<tr> <td> 1607dd7cddfSDavid du Colombier<tr valign=top> <td>Character and font 1617dd7cddfSDavid du Colombier <td> 1627dd7cddfSDavid du Colombier <td><b><tt>gschar.h</tt></b><br><b><tt>gsfont.h</tt></b> 1637dd7cddfSDavid du Colombier <td> 1647dd7cddfSDavid du Colombier <td>*(all the <b><tt>show</tt></b> operators), <b><tt>definefont</tt></b>, <b><tt>undefinefont</tt></b>, <b><tt>findfont</tt></b>, <b><tt>*scalefont</tt></b>, <b><tt>*makefont</tt></b>, <b><tt>selectfont</tt></b>, <b><tt>[Global]FontDirectory</tt></b>, <b><tt>Standard</tt></b>/<b><tt>ISOLatin1Encoding</tt></b>, <b><tt>findencoding</tt></b> 1657dd7cddfSDavid du Colombier</table></blockquote> 1667dd7cddfSDavid du Colombier 1677dd7cddfSDavid du Colombier<p> 1687dd7cddfSDavid du ColombierThe following procedures from the list above operate differently from their 1697dd7cddfSDavid du ColombierPostScript operator counterparts, as explained here: 1707dd7cddfSDavid du Colombier 1717dd7cddfSDavid du Colombier<dl> 1727dd7cddfSDavid du Colombier<dt><b><tt>gs_makepattern(gscolor2.h)</tt></b> 1737dd7cddfSDavid du Colombier<dd>Takes an explicit current color, rather than using the current color in 1747dd7cddfSDavid du Colombierthe graphics state. Takes an explicit allocator for allocating the pattern 1757dd7cddfSDavid du Colombierimplementation. See below for more details on 1767dd7cddfSDavid du Colombier<b><tt>gs_makepattern</tt></b>. 1777dd7cddfSDavid du Colombier</dl> 1787dd7cddfSDavid du Colombier 1797dd7cddfSDavid du Colombier<dl> 1807dd7cddfSDavid du Colombier<dt><b><tt>gs_setpattern(gscolor2.h)</tt></b> 1817dd7cddfSDavid du Colombier<dt><b><tt>gs_setcolor(gscolor2.h)</tt></b> 1827dd7cddfSDavid du Colombier<dt><b><tt>gs_currentcolor(gscolor2.h)</tt></b> 1837dd7cddfSDavid du Colombier<dd>Use <b><tt>gs_client_color</tt></b> rather than a set of color 1847dd7cddfSDavid du Colombierparameter values. See below for more details on 1857dd7cddfSDavid du Colombier<b><tt>gs_setpattern</tt></b>. 1867dd7cddfSDavid du Colombier</dl> 1877dd7cddfSDavid du Colombier 1887dd7cddfSDavid du Colombier<dl> 1897dd7cddfSDavid du Colombier<dt><b><tt>gs_currentdash_length/pattern/offset(gsline.h)</tt></b> 1907dd7cddfSDavid du Colombier<dd>Splits up <b><tt>currentdash</tt></b> into three separate procedures. 1917dd7cddfSDavid du Colombier</dl> 1927dd7cddfSDavid du Colombier 1937dd7cddfSDavid du Colombier<dl> 1947dd7cddfSDavid du Colombier<dt><b><tt>gs_screen_init/currentpoint/next/install(gsht.h)</tt></b> 1957dd7cddfSDavid du Colombier<dd>Provide an "enumeration style" interface to <b><tt>setscreen</tt></b>. 1967dd7cddfSDavid du Colombier(<b><tt>gs_setscreen</tt></b> is also implemented.) 1977dd7cddfSDavid du Colombier</dl> 1987dd7cddfSDavid du Colombier 1997dd7cddfSDavid du Colombier<dl> 2007dd7cddfSDavid du Colombier<dt><b><tt>gs_rotate/scale/translate(gscoord.h)</tt></b> 2017dd7cddfSDavid du Colombier<dt><b><tt>gs_[i][d]transform(gscoord.h)</tt></b> 2027dd7cddfSDavid du Colombier<dd>These always operate on the graphics state CTM. The corresponding 2037dd7cddfSDavid du Colombieroperations on free-standing matrices are in <b><tt>gsmatrix.h</tt></b> and 2047dd7cddfSDavid du Colombierhave different names. 2057dd7cddfSDavid du Colombier</dl> 2067dd7cddfSDavid du Colombier 2077dd7cddfSDavid du Colombier<dl> 2087dd7cddfSDavid du Colombier<dt><b><tt>gs_path_enum_alloc/init/next/cleanup(gspath.h)</tt></b> 2097dd7cddfSDavid du Colombier<dd>Provide an "enumeration style" implementation of 2107dd7cddfSDavid du Colombier<b><tt>pathforall</tt></b>. 2117dd7cddfSDavid du Colombier</dl> 2127dd7cddfSDavid du Colombier 2137dd7cddfSDavid du Colombier<dl> 2147dd7cddfSDavid du Colombier<dt><b><tt>gs_image_enum_alloc(gsimage.h)</tt></b> 2157dd7cddfSDavid du Colombier<dt><b><tt>gs_image_init/next/cleanup(gsimage.h)</tt></b> 2167dd7cddfSDavid du Colombier<dd>Provide an "enumeration style" interface to the equivalent of 2177dd7cddfSDavid du Colombier<b><tt>image</tt></b>, <b><tt>imagemask</tt></b>, and 2187dd7cddfSDavid du Colombier<b><tt>colorimage</tt></b>. In the <b><tt>gs_image_t</tt></b>, 2197dd7cddfSDavid du Colombier<b><tt>ColorSpace</tt></b> provides an explicit color space, rather than 2207dd7cddfSDavid du Colombierusing the current color space in the graphics state; 2217dd7cddfSDavid du Colombier<b><tt>ImageMask</tt></b> distinguishes <b><tt>imagemask</tt></b> from 2227dd7cddfSDavid du Colombier<b><tt>[color]image</tt></b>. 2237dd7cddfSDavid du Colombier</dl> 2247dd7cddfSDavid du Colombier 2257dd7cddfSDavid du Colombier<dl> 2267dd7cddfSDavid du Colombier<dt><b><tt>gs_get/putdeviceparams(gsdevice.h)</tt></b> 2277dd7cddfSDavid du Colombier<dd>Take a <b><tt>gs_param_list</tt></b> for specifying or receiving the 2287dd7cddfSDavid du Colombierparameter values. See <b><tt>gsparam.h</tt></b> for more details. 2297dd7cddfSDavid du Colombier</dl> 2307dd7cddfSDavid du Colombier 2317dd7cddfSDavid du Colombier<dl> 2327dd7cddfSDavid du Colombier<dt><b><tt>gs_show_enum_alloc/release(gschar.h)</tt></b> 2337dd7cddfSDavid du Colombier<dt><b><tt>gs_xxxshow_[n_]init(gschar.h)</tt></b> 2347dd7cddfSDavid du Colombier<dt><b><tt>gs_show_next(gschar.h)</tt></b> 2357dd7cddfSDavid du Colombier<dd>Provide an "enumeration style" interface to writing text. Note that 2367dd7cddfSDavid du Colombiercontrol returns to the caller if the character must be rasterized. 2377dd7cddfSDavid du Colombier</dl> 2387dd7cddfSDavid du Colombier 2397dd7cddfSDavid du Colombier<p> 2407dd7cddfSDavid du ColombierThis level of the library also implements the following operators from other 2417dd7cddfSDavid du Colombiersections of the Manual: 2427dd7cddfSDavid du Colombier 2437dd7cddfSDavid du Colombier<blockquote><table cellpadding=0 cellspacing=0> 2447dd7cddfSDavid du Colombier<tr valign=bottom> 2457dd7cddfSDavid du Colombier <th align=left>Section<br>(operators) 2467dd7cddfSDavid du Colombier <td> 2477dd7cddfSDavid du Colombier <th align=left>Headers 2487dd7cddfSDavid du Colombier <td> 2497dd7cddfSDavid du Colombier <th align=left>Operators 2507dd7cddfSDavid du Colombier<tr> <td colspan=5><hr> 2517dd7cddfSDavid du Colombier<tr valign=top> <td>Interpreter parameter 2527dd7cddfSDavid du Colombier <td> 2537dd7cddfSDavid du Colombier <td><b><tt>gsfont.h</tt></b> 2547dd7cddfSDavid du Colombier <td> 2557dd7cddfSDavid du Colombier <td><b><tt>cachestatus</tt></b>, <b><tt>setcachelimit</tt></b>, <b><tt>*set/currentcacheparams</tt></b> 2567dd7cddfSDavid du Colombier<tr valign=top> <td>Display PostScript 2577dd7cddfSDavid du Colombier <td> 2587dd7cddfSDavid du Colombier <td><b><tt>gsstate.h</tt></b> 2597dd7cddfSDavid du Colombier <td> 2607dd7cddfSDavid du Colombier <td><b><tt>set/currenthalftonephase</tt></b> 2617dd7cddfSDavid du Colombier</table></blockquote> 2627dd7cddfSDavid du Colombier 2637dd7cddfSDavid du Colombier<p> 2647dd7cddfSDavid du ColombierIn order to obtain the full PostScript Level 2 functionality listed above, 2657dd7cddfSDavid du Colombier<b><tt>FEATURE_DEVS</tt></b> must be set in the makefile to include at least the following: 2667dd7cddfSDavid du Colombier 2677dd7cddfSDavid du Colombier<blockquote><b><tt> 2687dd7cddfSDavid du ColombierFEATURE_DEVS=patcore.dev cmykcore.dev psl2core.dev dps2core.dev ciecore.dev path1core.dev hsbcore.dev 2697dd7cddfSDavid du Colombier</tt></b></blockquote> 2707dd7cddfSDavid du Colombier 2717dd7cddfSDavid du Colombier<p> 2727dd7cddfSDavid du ColombierThe <b><tt>*lib.mak</tt></b> makefiles mentioned below do not always 2737dd7cddfSDavid du Colombierinclude all of these features. 2747dd7cddfSDavid du Colombier 2757dd7cddfSDavid du Colombier<p> 2767dd7cddfSDavid du ColombierFiles named <b><tt>gs*.c</tt></b> implement the higher level of the 2777dd7cddfSDavid du Colombiergraphics library. As might be expected, all procedures, variables, and 2787dd7cddfSDavid du Colombierstructures available at this level begin with "<b><tt>gs_</tt></b>". 2797dd7cddfSDavid du ColombierStructures that appear in these interfaces, but whose definitions may be 2807dd7cddfSDavid du Colombierhidden from clients, also have names beginning with "<b><tt>gs_</tt></b>", 2817dd7cddfSDavid du Colombierthat is, the prefix, not the implementation, reflects at what level the 2827dd7cddfSDavid du Colombierabstraction is made available. 2837dd7cddfSDavid du Colombier 2843ff48bf5SDavid du Colombier<h3><a name="Patterns"></a>Patterns</h3> 2857dd7cddfSDavid du Colombier 2867dd7cddfSDavid du Colombier<p> 2877dd7cddfSDavid du ColombierPatterns are the most complicated PostScript language objects that the 2887dd7cddfSDavid du Colombierlibrary API deals with. As in PostScript, defining a pattern color and 2897dd7cddfSDavid du Colombierusing the color are two separate operations. 2907dd7cddfSDavid du Colombier 2917dd7cddfSDavid du Colombier<p> 2927dd7cddfSDavid du Colombier<b><tt>gs_makepattern</tt></b> defines a pattern color. Its arguments are as follows: 2937dd7cddfSDavid du Colombier 2947dd7cddfSDavid du Colombier<blockquote><table cellpadding=0 cellspacing=0> 2957dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>gs_client_color *</tt></b> 2967dd7cddfSDavid du Colombier <td> 2977dd7cddfSDavid du Colombier <td>The resulting <b><tt>Pattern</tt></b> color is stored here. This is different from PostScript, which has no color objects <em>per se</em>, and hence returns a modified copy of the dictionary. 2987dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>const gs_client_pattern *</tt></b> 2997dd7cddfSDavid du Colombier <td> 3007dd7cddfSDavid du Colombier <td>The analogue of the original <b><tt>Pattern</tt></b> dictionary, described in detail just below. 3017dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>const gs_matrix *</tt></b> 3027dd7cddfSDavid du Colombier <td> 3037dd7cddfSDavid du Colombier <td>Corresponds to the matrix argument of the <b><tt>makepattern</tt></b> operator. 3047dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>gs_state *</tt></b> 3057dd7cddfSDavid du Colombier <td> 3067dd7cddfSDavid du Colombier <td>The current graphics state. 3077dd7cddfSDavid du Colombier<tr valign=top> <td><b><tt>gs_memory_t *</tt></b> 3087dd7cddfSDavid du Colombier <td> 3097dd7cddfSDavid du Colombier <td>The allocator to use for allocating the saved data for the 3107dd7cddfSDavid du Colombier <b><tt>Pattern</tt></b> color. If this is 3117dd7cddfSDavid du Colombier <b><tt>NULL</tt></b>, <b><tt>gs_makepattern</tt></b> uses the 3127dd7cddfSDavid du Colombier same allocator that allocated the graphics state. Library 3137dd7cddfSDavid du Colombier clients should probably always use <b><tt>NULL</tt></b>. 3147dd7cddfSDavid du Colombier 3157dd7cddfSDavid du Colombier</table></blockquote> 3167dd7cddfSDavid du Colombier 3177dd7cddfSDavid du Colombier<p> 3187dd7cddfSDavid du ColombierThe <b><tt>gs_client_pattern</tt></b> structure defined in 3197dd7cddfSDavid du Colombier<b><tt>gscolor2.h</tt></b> corresponds to the <b><tt>Pattern</tt></b> 3207dd7cddfSDavid du Colombierdictionary that is the argument to the PostScript language 3217dd7cddfSDavid du Colombier<b><tt>makepattern</tt></b> operator. This structure has one extra member, 3227dd7cddfSDavid du Colombier<b><tt>void *client_data</tt></b>, which is a place for clients to 3237dd7cddfSDavid du Colombierstore a pointer to additional data for the <b><tt>PaintProc</tt></b>; this 3247dd7cddfSDavid du Colombierprovides the same functionality as putting additional keys in the 3257dd7cddfSDavid du Colombier<b><tt>Pattern</tt></b> dictionary at the PostScript language level. The 3267dd7cddfSDavid du Colombier<b><tt>PaintProc</tt></b> is an ordinary C procedure that takes as 3277dd7cddfSDavid du Colombierparameters a <b><tt>gs_client_color *</tt></b>, which is the 3287dd7cddfSDavid du Colombier<b><tt>Pattern</tt></b> color that is being used for painting, and a 3297dd7cddfSDavid du Colombier<b><tt>gs_state *</tt></b>, which is the same graphics state that 3307dd7cddfSDavid du Colombierwould be presented to the <b><tt>PaintProc</tt></b> in PostScript. 3317dd7cddfSDavid du ColombierCurrently the <b><tt>gs_client_color *</tt></b> is always the current 3327dd7cddfSDavid du Colombiercolor in the graphics state, but the <b><tt>PaintProc</tt></b> should not 3337dd7cddfSDavid du Colombierrely on this. The <b><tt>PaintProc</tt></b> can retrieve the 3347dd7cddfSDavid du Colombier<b><tt>gs_client_pattern *</tt></b> from the 3357dd7cddfSDavid du Colombier<b><tt>gs_client_color *</tt></b> with the 3367dd7cddfSDavid du Colombier<b><tt>gs_getpattern</tt></b> procedure, also defined in 3377dd7cddfSDavid du Colombier<b><tt>gscolor2.h</tt></b>, and from there, it can retrieve the 3387dd7cddfSDavid du Colombier<b><tt>client_data</tt></b> pointer. 3397dd7cddfSDavid du Colombier 3407dd7cddfSDavid du Colombier<p> 3417dd7cddfSDavid du ColombierThe normal way to set a <b><tt>Pattern</tt></b> color is to call 3427dd7cddfSDavid du Colombier<b><tt>gs_setpattern</tt></b> with the graphics state and with the 3437dd7cddfSDavid du Colombier<b><tt>gs_client_color</tt></b> returned by <b><tt>gs_makepattern</tt></b>. 3447dd7cddfSDavid du ColombierAfter that, one can use <b><tt>gs_setcolor</tt></b> to set further 3457dd7cddfSDavid du Colombier<b><tt>Pattern</tt></b> colors (colored, or uncolored with the same 3467dd7cddfSDavid du Colombierunderlying color space); the rules are the same as those in PostScript. 3477dd7cddfSDavid du ColombierNote that for <b><tt>gs_setpattern</tt></b>, the 3487dd7cddfSDavid du Colombier<b><tt>paint.values</tt></b> in the <b><tt>gs_client_color</tt></b> must be 3497dd7cddfSDavid du Colombierfilled in for uncolored patterns; this corresponds to the additional 3507dd7cddfSDavid du Colombierarguments for the PostScript <b><tt>setpattern</tt></b> operator in the 3517dd7cddfSDavid du Colombieruncolored case. 3527dd7cddfSDavid du Colombier 3537dd7cddfSDavid du Colombier<p> 3547dd7cddfSDavid du ColombierThere is a special procedure <b><tt>gs_makebitmappattern</tt></b> for creating bitmap-based 3557dd7cddfSDavid du Colombierpatterns. Its API is documented in <b><tt>gscolor2.h</tt></b>; its implementation, in 3567dd7cddfSDavid du Colombier<b><tt>gspcolor.c</tt></b>, may be useful as an example of a pattern using a particularly 3577dd7cddfSDavid du Colombiersimple <b><tt>PaintProc.</tt></b> 3587dd7cddfSDavid du Colombier 3593ff48bf5SDavid du Colombier<h3><a name="Lower_level_API"></a>Lower-level API</h3> 3607dd7cddfSDavid du Colombier 3617dd7cddfSDavid du Colombier<p> 3627dd7cddfSDavid du ColombierFiles named <b><tt>gx*.c</tt></b> implement the lower level of the graphics 3637dd7cddfSDavid du Colombierlibrary. The interfaces at the <b><tt>gx</tt></b> level are less stable, 3647dd7cddfSDavid du Colombierand expose more of the implementation detail, than those at the 3657dd7cddfSDavid du Colombier<b><tt>gs</tt></b> level: in particular, the <b><tt>gx</tt></b> interfaces 3667dd7cddfSDavid du Colombiergenerally use device coordinates in an internal fixed-point representation, 3677dd7cddfSDavid du Colombieras opposed to the <b><tt>gs</tt></b> interfaces that use floating point 3687dd7cddfSDavid du Colombieruser coordinates. Named entities at this level begin with 3697dd7cddfSDavid du Colombier<b><tt>gx_</tt></b>. 3707dd7cddfSDavid du Colombier 3717dd7cddfSDavid du Colombier<p> 3727dd7cddfSDavid du ColombierFiles named <b><tt>gz*.c</tt></b> and <b><tt>gz*.h</tt></b> are internal to 3737dd7cddfSDavid du Colombierthe Ghostscript implementation, and are not designed to be called by 3747dd7cddfSDavid du Colombierclients. 3757dd7cddfSDavid du Colombier 3767dd7cddfSDavid du Colombier<hr> 3777dd7cddfSDavid du Colombier 378*593dc095SDavid du Colombier<h2><a name="Visual_trace"></a>Visual Trace instructions</h2> 379*593dc095SDavid du Colombier 380*593dc095SDavid du Colombier<p> 381*593dc095SDavid du ColombierVisual Trace instructions may be inserted in code to provide debug output in 382*593dc095SDavid du Colombiera graphical form. Graphics Library doesn't provide a rasterisation of the 383*593dc095SDavid du Colombieroutput, because it is platform dependent. Instead this, client application 384*593dc095SDavid du Colombiershpuld set <b><tt>vd_trace0</tt></b> external variable to Graphics Library, 385*593dc095SDavid du Colombierpassing a set of callbacks which provide the rasterization. 386*593dc095SDavid du Colombier 387*593dc095SDavid du Colombier<p> 388*593dc095SDavid du ColombierVisual Trace instructions are defined in <b><tt>vdtrace.h</tt></b>. 389*593dc095SDavid du ColombierDebug output must be opened with <b><tt>vd_get_dc</tt></b> instruction, 390*593dc095SDavid du Colombierwhich obtains a drawing context for the debug output, and must be closed 391*593dc095SDavid du Colombierwith <b><tt>vd_release_dc</tt></b> instruction. After opening the output, 392*593dc095SDavid du Colombierscale, origin and shift to be set for mapping the debugee coordinate space 393*593dc095SDavid du Colombierto window coordinate space. Than painting instructions to be used. 394*593dc095SDavid du ColombierPainting may be either immediate or indirect. 395*593dc095SDavid du Colombier 396*593dc095SDavid du Colombier<p> 397*593dc095SDavid du ColombierIndirect painting uses <b><tt>vd_beg_path</b></tt> before 398*593dc095SDavid du Colombierline output and <b><tt>vd_end_path</b></tt> after line output, 399*593dc095SDavid du Colombierto store a path into a temporary storage. After this 400*593dc095SDavid du Colombier<b><tt>vd_stroke</b></tt> may be used for stroking the path, 401*593dc095SDavid du Colombieror <b><tt>vd_fill</b></tt> may be used for filling the region inside the path. 402*593dc095SDavid du Colombier 403*593dc095SDavid du Colombier<p> 404*593dc095SDavid du ColombierImmediate painting happens when path construction instructions are 405*593dc095SDavid du Colombierinvolved without <b><tt>vd_beg_path</b></tt> and <b><tt>vd_end_path</b></tt>. 406*593dc095SDavid du ColombierIn this case lines and curves are being drawed immediately, when a path construction 407*593dc095SDavid du Colombierinstruction is executed. 408*593dc095SDavid du Colombier 409*593dc095SDavid du Colombier<p> 410*593dc095SDavid du ColombierThe following table explains the semantics of Visual Trace instructions. 411*593dc095SDavid du Colombier<p> 412*593dc095SDavid du Colombier 413*593dc095SDavid du Colombier<table cellpadding=0 cellspacing=0> 414*593dc095SDavid du Colombier<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Visual Trace instructions</font><hr> 415*593dc095SDavid du Colombier<tr> <th align=left>Instruction 416*593dc095SDavid du Colombier <td> 417*593dc095SDavid du Colombier <th align=left>Function 418*593dc095SDavid du Colombier <td> 419*593dc095SDavid du Colombier <th align=left>Parameters 420*593dc095SDavid du Colombier<tr> <td colspan=5><hr> 421*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_dc</tt></b> 422*593dc095SDavid du Colombier <td> 423*593dc095SDavid du Colombier <td>Obtain drawing context 424*593dc095SDavid du Colombier <td> 425*593dc095SDavid du Colombier <td><b><tt>-T</tt></b> option flag value, for which the subsequent output is enabled. 426*593dc095SDavid du Colombier<tr> <td><b><tt>vd_release_dc</tt></b> 427*593dc095SDavid du Colombier <td> 428*593dc095SDavid du Colombier <td>Release drawing context 429*593dc095SDavid du Colombier <td> 430*593dc095SDavid du Colombier <td> 431*593dc095SDavid du Colombier<tr> <td><b><tt>vd_enabled</tt></b> 432*593dc095SDavid du Colombier <td> 433*593dc095SDavid du Colombier <td>Is trace currently enabled ? 434*593dc095SDavid du Colombier <td> 435*593dc095SDavid du Colombier <td> 436*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_size_unscaled_x</tt></b> 437*593dc095SDavid du Colombier <td> 438*593dc095SDavid du Colombier <td>Get the horizontal size of the output window in pixels. 439*593dc095SDavid du Colombier <td> 440*593dc095SDavid du Colombier <td> 441*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_size_unscaled_y</tt></b> 442*593dc095SDavid du Colombier <td> 443*593dc095SDavid du Colombier <td>Get the vertical size of the output window in pixels. 444*593dc095SDavid du Colombier <td> 445*593dc095SDavid du Colombier <td> 446*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_size_caled_x</tt></b> 447*593dc095SDavid du Colombier <td> 448*593dc095SDavid du Colombier <td>Get the horizontal size of the output window in debuggee coordinate units. 449*593dc095SDavid du Colombier <td> 450*593dc095SDavid du Colombier <td> 451*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_size_caled_y</tt></b> 452*593dc095SDavid du Colombier <td> 453*593dc095SDavid du Colombier <td>Get the vertical size of the output window in debuggee coordinate units. 454*593dc095SDavid du Colombier <td> 455*593dc095SDavid du Colombier <td> 456*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_scale_x</tt></b> 457*593dc095SDavid du Colombier <td> 458*593dc095SDavid du Colombier <td>Get the horizontal scale. 459*593dc095SDavid du Colombier <td> 460*593dc095SDavid du Colombier <td> 461*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_scale_y</tt></b> 462*593dc095SDavid du Colombier <td> 463*593dc095SDavid du Colombier <td>Get the vertical scale. 464*593dc095SDavid du Colombier <td> 465*593dc095SDavid du Colombier <td> 466*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_origin_x</tt></b> 467*593dc095SDavid du Colombier <td> 468*593dc095SDavid du Colombier <td>Get the horizontal position of the draft origin in debuggee coordinate space. 469*593dc095SDavid du Colombier <td> 470*593dc095SDavid du Colombier <td> 471*593dc095SDavid du Colombier<tr> <td><b><tt>vd_get_origin_y</tt></b> 472*593dc095SDavid du Colombier <td> 473*593dc095SDavid du Colombier <td>Get the vertical position of the draft origin in debuggee coordinate space. 474*593dc095SDavid du Colombier <td> 475*593dc095SDavid du Colombier <td> 476*593dc095SDavid du Colombier<tr> <td><b><tt>vd_set_scale(s)</tt></b> 477*593dc095SDavid du Colombier <td> 478*593dc095SDavid du Colombier <td>Set isotripic scale. 479*593dc095SDavid du Colombier <td> 480*593dc095SDavid du Colombier <td>Debugee space to window space mapping scale, same for both dimentions. 481*593dc095SDavid du Colombier<tr> <td><b><tt>vd_set_scaleXY(sx,sy)</tt></b> 482*593dc095SDavid du Colombier <td> 483*593dc095SDavid du Colombier <td>Set anisotripic scale. 484*593dc095SDavid du Colombier <td> 485*593dc095SDavid du Colombier <td>Debugee space to window space mapping scale, one for each dimention. 486*593dc095SDavid du Colombier<tr> <td><b><tt>vd_set_origin(x,y)</tt></b> 487*593dc095SDavid du Colombier <td> 488*593dc095SDavid du Colombier <td>Set the draft origin. 489*593dc095SDavid du Colombier <td> 490*593dc095SDavid du Colombier <td>Origin of the draft in debugee space. 491*593dc095SDavid du Colombier<tr> <td><b><tt>vd_set_shift(x,y)</tt></b> 492*593dc095SDavid du Colombier <td> 493*593dc095SDavid du Colombier <td>Set the draft position. 494*593dc095SDavid du Colombier <td> 495*593dc095SDavid du Colombier <td>Position of the draft origin in window space (in pixels). 496*593dc095SDavid du Colombier<tr> <td><b><tt>vd_set_central_shift</tt></b> 497*593dc095SDavid du Colombier <td> 498*593dc095SDavid du Colombier <td>Set the draft position to window center. 499*593dc095SDavid du Colombier <td> 500*593dc095SDavid du Colombier <td> 501*593dc095SDavid du Colombier<tr> <td><b><tt>vd_erase(c)</tt></b> 502*593dc095SDavid du Colombier <td> 503*593dc095SDavid du Colombier <td>Fill entire window. 504*593dc095SDavid du Colombier <td> 505*593dc095SDavid du Colombier <td>Color to fill. 506*593dc095SDavid du Colombier<tr> <td><b><tt>vd_beg_path</tt></b> 507*593dc095SDavid du Colombier <td> 508*593dc095SDavid du Colombier <td>Begin path construction. 509*593dc095SDavid du Colombier <td> 510*593dc095SDavid du Colombier <td> 511*593dc095SDavid du Colombier<tr> <td><b><tt>vd_end_path</tt></b> 512*593dc095SDavid du Colombier <td> 513*593dc095SDavid du Colombier <td>End path construction. 514*593dc095SDavid du Colombier <td> 515*593dc095SDavid du Colombier <td> 516*593dc095SDavid du Colombier<tr> <td><b><tt>vd_moveto(x,y)</tt></b> 517*593dc095SDavid du Colombier <td> 518*593dc095SDavid du Colombier <td>Path construction : Set the draft current point. 519*593dc095SDavid du Colombier <td> 520*593dc095SDavid du Colombier <td>Debugee coordinates. 521*593dc095SDavid du Colombier<tr> <td><b><tt>vd_lineto(x,y)</tt></b> 522*593dc095SDavid du Colombier <td> 523*593dc095SDavid du Colombier <td>Path construction : Line from current point to specified point. 524*593dc095SDavid du Colombier <td> 525*593dc095SDavid du Colombier <td>Debugee coordinates. 526*593dc095SDavid du Colombier<tr> <td><b><tt>vd_lineto_mupti(p,n)</tt></b> 527*593dc095SDavid du Colombier <td> 528*593dc095SDavid du Colombier <td>Path construction : Poliline from current point to specified points. 529*593dc095SDavid du Colombier <td> 530*593dc095SDavid du Colombier <td>Array of points and its size, debugee coordinates. 531*593dc095SDavid du Colombier<tr> <td><b><tt>vd_curveto(x0,y0,x1,y1,x2,y2)</tt></b> 532*593dc095SDavid du Colombier <td> 533*593dc095SDavid du Colombier <td>Path construction : Curve (3d order Bezier) from current point to specified point, with specified poles. 534*593dc095SDavid du Colombier <td> 535*593dc095SDavid du Colombier <td>2 poles and the curve ending point, debuggee coordinates. 536*593dc095SDavid du Colombier<tr> <td><b><tt>vd_closepath</tt></b> 537*593dc095SDavid du Colombier <td> 538*593dc095SDavid du Colombier <td>Path construction : Close the path (is necessary for filling an area). 539*593dc095SDavid du Colombier <td> 540*593dc095SDavid du Colombier <td> 541*593dc095SDavid du Colombier<tr> <td><b><tt>vd_bar(x0,y0,x1,y1,w,c)</tt></b> 542*593dc095SDavid du Colombier <td> 543*593dc095SDavid du Colombier <td>Bar from point to point. 544*593dc095SDavid du Colombier <td> 545*593dc095SDavid du Colombier <td>2 points (debugee coordinates), width (in pixels) and color. 546*593dc095SDavid du Colombier<tr> <td><b><tt>vd_square(x0,y0,w,c)</tt></b> 547*593dc095SDavid du Colombier <td> 548*593dc095SDavid du Colombier <td>Square with specified center and size. 549*593dc095SDavid du Colombier <td> 550*593dc095SDavid du Colombier <td>The center (debugee coordinates), size (in pixels) and color. 551*593dc095SDavid du Colombier<tr> <td><b><tt>vd_rect(x0,y0,x1,y1,w,c)</tt></b> 552*593dc095SDavid du Colombier <td> 553*593dc095SDavid du Colombier <td>Canonic rectangle with specified coordinites. 554*593dc095SDavid du Colombier <td> 555*593dc095SDavid du Colombier <td>Coordinates of boundaries (debugee coordinates), line width (in pixels) and color. 556*593dc095SDavid du Colombier<tr> <td><b><tt>vd_quad(x0,y0,x1,y1,x2,y2,x3,y3,w,c)</tt></b> 557*593dc095SDavid du Colombier <td> 558*593dc095SDavid du Colombier <td>Quadrangle with specified coordinites. 559*593dc095SDavid du Colombier <td> 560*593dc095SDavid du Colombier <td>Coordinates of vertices (debugee coordinates), line width (in pixels) and color. 561*593dc095SDavid du Colombier<tr> <td><b><tt>vd_curve(x0,y0,x1,y1,x2,y2,x3,y3,c,w)</tt></b> 562*593dc095SDavid du Colombier <td> 563*593dc095SDavid du Colombier <td>Curve with width. 564*593dc095SDavid du Colombier <td> 565*593dc095SDavid du Colombier <td>4 curve poles (debugee coordinates), color, and width (in pixels). 566*593dc095SDavid du Colombier<tr> <td><b><tt>vd_circle(x,y,r,c)</tt></b> 567*593dc095SDavid du Colombier <td> 568*593dc095SDavid du Colombier <td>Circle. 569*593dc095SDavid du Colombier <td> 570*593dc095SDavid du Colombier <td>Center (debugee coordinates), radius (in pixels) and color. 571*593dc095SDavid du Colombier<tr> <td><b><tt>vd_round(x,y,r,c)</tt></b> 572*593dc095SDavid du Colombier <td> 573*593dc095SDavid du Colombier <td>Filled circle. 574*593dc095SDavid du Colombier <td> 575*593dc095SDavid du Colombier <td>Center (debugee coordinates), radius (in pixels) and color. 576*593dc095SDavid du Colombier<tr> <td><b><tt>vd_stroke</tt></b> 577*593dc095SDavid du Colombier <td> 578*593dc095SDavid du Colombier <td>Stroke a path constructed with vd_beg_path, vd_moveto, vd_lineto, 579*593dc095SDavid du Colombier vd_curveto, vd_closepath, vd_end_path. 580*593dc095SDavid du Colombier <td> 581*593dc095SDavid du Colombier <td> 582*593dc095SDavid du Colombier<tr> <td><b><tt>vd_fill</tt></b> 583*593dc095SDavid du Colombier <td> 584*593dc095SDavid du Colombier <td>Fill a path constructed with vd_beg_path, vd_moveto, vd_lineto, 585*593dc095SDavid du Colombier vd_curveto, vd_closepath, vd_end_path. 586*593dc095SDavid du Colombier <td> 587*593dc095SDavid du Colombier <td> 588*593dc095SDavid du Colombier<tr> <td><b><tt>vd_setcolor(c)</tt></b> 589*593dc095SDavid du Colombier <td> 590*593dc095SDavid du Colombier <td>Set a color. 591*593dc095SDavid du Colombier <td> 592*593dc095SDavid du Colombier <td>Color (an integer consisting of red, green, blue bytes). 593*593dc095SDavid du Colombier<tr> <td><b><tt>vd_setlinewidth(w)</tt></b> 594*593dc095SDavid du Colombier <td> 595*593dc095SDavid du Colombier <td>Set line width. 596*593dc095SDavid du Colombier <td> 597*593dc095SDavid du Colombier <td>Width (in pixels). 598*593dc095SDavid du Colombier<tr> <td><b><tt>vd_text(x,y,s,c)</tt></b> 599*593dc095SDavid du Colombier <td> 600*593dc095SDavid du Colombier <td>Paint a text. 601*593dc095SDavid du Colombier <td> 602*593dc095SDavid du Colombier <td>Origin point (debugee coordinates), a string, and a color. 603*593dc095SDavid du Colombier<tr> <td><b><tt>vd_wait</tt></b> 604*593dc095SDavid du Colombier <td> 605*593dc095SDavid du Colombier <td>Delay execution until a resuming command is entered through user interface. 606*593dc095SDavid du Colombier <td> 607*593dc095SDavid du Colombier <td> 608*593dc095SDavid du Colombier</table> 609*593dc095SDavid du Colombier 610*593dc095SDavid du Colombier 611*593dc095SDavid du Colombier<p> 612*593dc095SDavid du ColombierGraphics Library doesn't provide a rasterization of the debug output. 613*593dc095SDavid du ColombierInstead it calls callbacks, which are specified by a client, and which may 614*593dc095SDavid du Colombierhave a platform dependent implementation. The implementation must not 615*593dc095SDavid du Colombieruse Graphics Library to exclude recursive calls to it from Visual Trace 616*593dc095SDavid du Colombierinstructions. The callbacks and auxiliary data are collected in 617*593dc095SDavid du Colombierthe structure <b><tt>vd_trace_interface</b></tt>, explained in the table below. 618*593dc095SDavid du Colombier<p> 619*593dc095SDavid du Colombier 620*593dc095SDavid du Colombier<table cellpadding=0 cellspacing=0> 621*593dc095SDavid du Colombier<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">vd_trace_interface structure</font><hr> 622*593dc095SDavid du Colombier<tr> <th align=left>Field 623*593dc095SDavid du Colombier <td> 624*593dc095SDavid du Colombier <th align=left>Purpose 625*593dc095SDavid du Colombier <td> 626*593dc095SDavid du Colombier <th align=left>Parameters 627*593dc095SDavid du Colombier<tr> <td colspan=5><hr> 628*593dc095SDavid du Colombier<tr> <td><b><tt>host</tt></b> 629*593dc095SDavid du Colombier <td> 630*593dc095SDavid du Colombier <td>A pointer to the rasterizer control block - to be provided by client application. 631*593dc095SDavid du Colombier The type of the fild is client dependent. 632*593dc095SDavid du Colombier <td> 633*593dc095SDavid du Colombier <td> 634*593dc095SDavid du Colombier<tr> <td><b><tt>scale_x, scale_y</tt></b> 635*593dc095SDavid du Colombier <td> 636*593dc095SDavid du Colombier <td>Scale of debugee coordinate to window coordinate mapping - internal work data, don't change. 637*593dc095SDavid du Colombier <td> 638*593dc095SDavid du Colombier <td> 639*593dc095SDavid du Colombier<tr> <td><b><tt>orig_x, orig_y</tt></b> 640*593dc095SDavid du Colombier <td> 641*593dc095SDavid du Colombier <td>Draft origin in debugee coordinates - internal work data, don't change. 642*593dc095SDavid du Colombier <td> 643*593dc095SDavid du Colombier <td> 644*593dc095SDavid du Colombier<tr> <td><b><tt>shift_x, shift_y</tt></b> 645*593dc095SDavid du Colombier <td> 646*593dc095SDavid du Colombier <td>Draft shift in window coordinates - internal work data, don't change. 647*593dc095SDavid du Colombier <td> 648*593dc095SDavid du Colombier <td> 649*593dc095SDavid du Colombier<tr> <td><b><tt>get_size_x(I)</tt></b> 650*593dc095SDavid du Colombier <td> 651*593dc095SDavid du Colombier <td>Get window width in pixels. 652*593dc095SDavid du Colombier <td> 653*593dc095SDavid du Colombier <td> 654*593dc095SDavid du Colombier<tr> <td><b><tt>get_size_y(I)</tt></b> 655*593dc095SDavid du Colombier <td> 656*593dc095SDavid du Colombier <td>Get window height in pixels. 657*593dc095SDavid du Colombier <td> 658*593dc095SDavid du Colombier <td> 659*593dc095SDavid du Colombier<tr> <td><b><tt>get_dc(I,I1)</tt></b> 660*593dc095SDavid du Colombier <td> 661*593dc095SDavid du Colombier <td>Obtain drawing context. 662*593dc095SDavid du Colombier <td> 663*593dc095SDavid du Colombier <td>Pointer to interface block, and pointer to copy of the pointer. 664*593dc095SDavid du Colombier Implementation must set *I1 if it succeeds to get a drawing context. 665*593dc095SDavid du Colombier<tr> <td><b><tt>release_dc(I,I1)</tt></b> 666*593dc095SDavid du Colombier <td> 667*593dc095SDavid du Colombier <td>Release drawing context. 668*593dc095SDavid du Colombier <td> 669*593dc095SDavid du Colombier <td>Pointer to interface block, and pointer to copy of the pointer. 670*593dc095SDavid du Colombier Implementation must reset *I1 if it succeeds to release the drawing context. 671*593dc095SDavid du Colombier<tr> <td><b><tt>erase(I,c)</tt></b> 672*593dc095SDavid du Colombier <td> 673*593dc095SDavid du Colombier <td>Erase entire window. 674*593dc095SDavid du Colombier <td> 675*593dc095SDavid du Colombier <td>Background color. 676*593dc095SDavid du Colombier<tr> <td><b><tt>beg_path(I)</tt></b> 677*593dc095SDavid du Colombier <td> 678*593dc095SDavid du Colombier <td>Begin path construction. 679*593dc095SDavid du Colombier <td> 680*593dc095SDavid du Colombier <td> 681*593dc095SDavid du Colombier<tr> <td><b><tt>end_path(I)</tt></b> 682*593dc095SDavid du Colombier <td> 683*593dc095SDavid du Colombier <td>End path construction. 684*593dc095SDavid du Colombier <td> 685*593dc095SDavid du Colombier <td> 686*593dc095SDavid du Colombier<tr> <td><b><tt>moveto(I,x,y)</tt></b> 687*593dc095SDavid du Colombier <td> 688*593dc095SDavid du Colombier <td>Set current point. 689*593dc095SDavid du Colombier <td> 690*593dc095SDavid du Colombier <td>A point in window coordinates. 691*593dc095SDavid du Colombier<tr> <td><b><tt>lineto(I,x,y)</tt></b> 692*593dc095SDavid du Colombier <td> 693*593dc095SDavid du Colombier <td>Line from current point to specified point. 694*593dc095SDavid du Colombier <td> 695*593dc095SDavid du Colombier <td>A point in window coordinates. 696*593dc095SDavid du Colombier<tr> <td><b><tt>curveto(I,x0,y0,x1,y1,x2,y2)</tt></b> 697*593dc095SDavid du Colombier <td> 698*593dc095SDavid du Colombier <td>Curve from current point with specified poles to specified point. 699*593dc095SDavid du Colombier <td> 700*593dc095SDavid du Colombier <td>3 points in window coordinates. 701*593dc095SDavid du Colombier<tr> <td><b><tt>closepath(I)</tt></b> 702*593dc095SDavid du Colombier <td> 703*593dc095SDavid du Colombier <td>Close the path. 704*593dc095SDavid du Colombier <td> 705*593dc095SDavid du Colombier <td> 706*593dc095SDavid du Colombier<tr> <td><b><tt>circle(I,x,y,r)</tt></b> 707*593dc095SDavid du Colombier <td> 708*593dc095SDavid du Colombier <td>Circle. 709*593dc095SDavid du Colombier <td> 710*593dc095SDavid du Colombier <td>Center and radius, window coordinates. 711*593dc095SDavid du Colombier<tr> <td><b><tt>round(I,x,y,r)</tt></b> 712*593dc095SDavid du Colombier <td> 713*593dc095SDavid du Colombier <td>Filled circle. 714*593dc095SDavid du Colombier <td> 715*593dc095SDavid du Colombier <td>Center and radius, window coordinates. 716*593dc095SDavid du Colombier<tr> <td><b><tt>fill(I)</tt></b> 717*593dc095SDavid du Colombier <td> 718*593dc095SDavid du Colombier <td>Fill the path. 719*593dc095SDavid du Colombier <td> 720*593dc095SDavid du Colombier <td> 721*593dc095SDavid du Colombier<tr> <td><b><tt>stroke(I)</tt></b> 722*593dc095SDavid du Colombier <td> 723*593dc095SDavid du Colombier <td>Stroke the path. 724*593dc095SDavid du Colombier <td> 725*593dc095SDavid du Colombier <td> 726*593dc095SDavid du Colombier<tr> <td><b><tt>setcolor(I,c)</tt></b> 727*593dc095SDavid du Colombier <td> 728*593dc095SDavid du Colombier <td>Set color. 729*593dc095SDavid du Colombier <td> 730*593dc095SDavid du Colombier <td>An integer, consisting of red, green, blue bytes. 731*593dc095SDavid du Colombier<tr> <td><b><tt>setlinewidth(I,w)</tt></b> 732*593dc095SDavid du Colombier <td> 733*593dc095SDavid du Colombier <td>Set line width. 734*593dc095SDavid du Colombier <td> 735*593dc095SDavid du Colombier <td>Line width in pixels. 736*593dc095SDavid du Colombier<tr> <td><b><tt>text(I,x,y,s)</tt></b> 737*593dc095SDavid du Colombier <td> 738*593dc095SDavid du Colombier <td>Draw a text. 739*593dc095SDavid du Colombier <td> 740*593dc095SDavid du Colombier <td>Coodrinates in pixels, and a string. 741*593dc095SDavid du Colombier<tr> <td><b><tt>wait(I)</tt></b> 742*593dc095SDavid du Colombier <td> 743*593dc095SDavid du Colombier <td>Delay execution untill resume command is inputted from user. 744*593dc095SDavid du Colombier <td> 745*593dc095SDavid du Colombier <td> 746*593dc095SDavid du Colombier</table> 747*593dc095SDavid du Colombier 748*593dc095SDavid du Colombier 749*593dc095SDavid du Colombier 750*593dc095SDavid du Colombier<p> 751*593dc095SDavid du Colombier<hr> 752*593dc095SDavid du Colombier 7533ff48bf5SDavid du Colombier<h2><a name="Full_example"></a>A full example</h2> 7547dd7cddfSDavid du Colombier 7557dd7cddfSDavid du Colombier<p> 7567dd7cddfSDavid du ColombierThe file <b><tt>gslib.c</tt></b> in the Ghostscript fileset is a complete 7577dd7cddfSDavid du Colombierexample program that initializes the library and produces output using it; 7587dd7cddfSDavid du Colombierfiles named <b><tt>*lib.mak</tt></b> (such as <b><tt>ugcclib.mak</tt></b> 7597dd7cddfSDavid du Colombierand <b><tt>bclib.mak</tt></b>) are makefiles using <b><tt>gslib.c</tt></b> 7607dd7cddfSDavid du Colombieras the main program. The following annotated excerpts from this file are 7617dd7cddfSDavid du Colombierintended to provide a roadmap for applications that call the library. 7627dd7cddfSDavid du Colombier 7637dd7cddfSDavid du Colombier<blockquote><pre>/* Capture stdin/out/err before gs.h redefines them. */ 7647dd7cddfSDavid du Colombier#include <stdio.h> 7657dd7cddfSDavid du Colombierstatic FILE *real_stdin, *real_stdout, *real_stderr; 7667dd7cddfSDavid du Colombierstatic void 7677dd7cddfSDavid du Colombierget_real(void) 7687dd7cddfSDavid du Colombier{ real_stdin = stdin, real_stdout = stdout, real_stderr = stderr; 7697dd7cddfSDavid du Colombier}</pre></blockquote> 7707dd7cddfSDavid du Colombier 7717dd7cddfSDavid du Colombier<p> 7727dd7cddfSDavid du ColombierAny application using Ghostscript should include the fragment above at the 7737dd7cddfSDavid du Colombiervery beginning of the main program. 7747dd7cddfSDavid du Colombier 7757dd7cddfSDavid du Colombier<blockquote><pre>#include "gx.h"</pre></blockquote> 7767dd7cddfSDavid du Colombier 7777dd7cddfSDavid du Colombier<p> 7787dd7cddfSDavid du ColombierThe <b><tt>gx.h</tt></b> header includes a wealth of declarations related 7797dd7cddfSDavid du Colombierto the Ghostscript memory manager, portability machinery, debugging 7807dd7cddfSDavid du Colombierframework, and other substrate facilities. Any application file that calls 7817dd7cddfSDavid du Colombierany Ghostscript API functions should probably include <b><tt>gx.h</tt></b>. 7827dd7cddfSDavid du Colombier 7837dd7cddfSDavid du Colombier<blockquote><pre>/* Configuration information imported from gconfig.c. */ 7847dd7cddfSDavid du Colombierextern gx_device *gx_device_list[]; 7857dd7cddfSDavid du Colombier 7867dd7cddfSDavid du Colombier/* Other imported procedures */ 7877dd7cddfSDavid du Colombier /* from gsinit.c */ 7887dd7cddfSDavid du Colombierextern void gs_lib_init(P1(FILE *)); 7897dd7cddfSDavid du Colombierextern void gs_lib_finit(P2(int, int)); 7907dd7cddfSDavid du Colombier /* from gsalloc.c */ 7917dd7cddfSDavid du Colombierextern gs_ref_memory_t *ialloc_alloc_state(P2(gs_memory_t *, uint));</pre></blockquote> 7927dd7cddfSDavid du Colombier 7937dd7cddfSDavid du Colombier<p> 7947dd7cddfSDavid du ColombierThe externs above are needed for initializing the library. 7957dd7cddfSDavid du Colombier 7967dd7cddfSDavid du Colombier<blockquote><pre> gs_ref_memory_t *imem; 7977dd7cddfSDavid du Colombier#define mem ((gs_memory_t *)imem) 7987dd7cddfSDavid du Colombier gs_state *pgs; 7997dd7cddfSDavid du Colombier gx_device *dev = gx_device_list[0]; 8007dd7cddfSDavid du Colombier 8017dd7cddfSDavid du Colombier gp_init(); 8027dd7cddfSDavid du Colombier get_real(); 8037dd7cddfSDavid du Colombier gs_stdin = real_stdin; 8047dd7cddfSDavid du Colombier gs_stdout = real_stdout; 8057dd7cddfSDavid du Colombier gs_stderr = real_stderr; 8067dd7cddfSDavid du Colombier gs_lib_init(stdout); 8077dd7cddfSDavid du Colombier .... 8087dd7cddfSDavid du Colombier imem = ialloc_alloc_state(&gs_memory_default, 20000); 8097dd7cddfSDavid du Colombier imem->space = 0; 8107dd7cddfSDavid du Colombier .... 8117dd7cddfSDavid du Colombier pgs = gs_state_alloc(mem);</pre></blockquote> 8127dd7cddfSDavid du Colombier 8137dd7cddfSDavid du Colombier<p> 8147dd7cddfSDavid du ColombierThe code above initializes the library and its memory manager. <b><tt>pgs</tt></b> now 8157dd7cddfSDavid du Colombierpoints to the graphics state that will be passed to the drawing routines in 8167dd7cddfSDavid du Colombierthe library. 8177dd7cddfSDavid du Colombier 8187dd7cddfSDavid du Colombier<blockquote><pre> gs_setdevice_no_erase(pgs, dev); /* can't erase yet */ 8197dd7cddfSDavid du Colombier { gs_point dpi; 8207dd7cddfSDavid du Colombier gs_screen_halftone ht; 8217dd7cddfSDavid du Colombier gs_dtransform(pgs, 72.0, 72.0, &dpi); 8227dd7cddfSDavid du Colombier ht.frequency = min(fabs(dpi.x), fabs(dpi.y)) / 16.001; 8237dd7cddfSDavid du Colombier ht.angle = 0; 8247dd7cddfSDavid du Colombier ht.spot_function = odsf; 8257dd7cddfSDavid du Colombier gs_setscreen(pgs, &ht); 8267dd7cddfSDavid du Colombier }</pre></blockquote> 8277dd7cddfSDavid du Colombier 8287dd7cddfSDavid du Colombier<p> 8297dd7cddfSDavid du ColombierThe code above initializes the default device and sets a default halftone 8307dd7cddfSDavid du Colombierscreen. (For brevity, we have omitted the definition of odsf, the spot 8317dd7cddfSDavid du Colombierfunction.) 8327dd7cddfSDavid du Colombier 8337dd7cddfSDavid du Colombier<blockquote><pre> /* gsave and grestore (among other places) assume that */ 8347dd7cddfSDavid du Colombier /* there are at least 2 gstates on the graphics stack. */ 8357dd7cddfSDavid du Colombier /* Ensure that now. */ 8367dd7cddfSDavid du Colombier gs_gsave(pgs);</pre></blockquote> 8377dd7cddfSDavid du Colombier 8387dd7cddfSDavid du Colombier<p> 8397dd7cddfSDavid du ColombierThe call above completes initializing the graphics state. When the program 8407dd7cddfSDavid du Colombieris finished, it should execute: 8417dd7cddfSDavid du Colombier 8427dd7cddfSDavid du Colombier<blockquote><pre> gs_lib_finit(0, 0);</pre></blockquote> 8437dd7cddfSDavid du Colombier 8447dd7cddfSDavid du Colombier<!-- [2.0 end contents] ==================================================== --> 8457dd7cddfSDavid du Colombier 8467dd7cddfSDavid du Colombier<!-- [3.0 begin visible trailer] =========================================== --> 8477dd7cddfSDavid du Colombier<hr> 8487dd7cddfSDavid du Colombier 8493ff48bf5SDavid du Colombier<p> 8503ff48bf5SDavid du Colombier<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises. 8513ff48bf5SDavid du ColombierAll rights reserved.</small> 8527dd7cddfSDavid du Colombier 8537dd7cddfSDavid du Colombier<p> 854*593dc095SDavid du ColombierThis software is provided AS-IS with no warranty, either express or 855*593dc095SDavid du Colombierimplied. 856*593dc095SDavid du Colombier 857*593dc095SDavid du ColombierThis software is distributed under license and may not be copied, 858*593dc095SDavid du Colombiermodified or distributed except as expressly authorized under the terms 859*593dc095SDavid du Colombierof the license contained in the file LICENSE in this distribution. 860*593dc095SDavid du Colombier 861*593dc095SDavid du ColombierFor more information about licensing, please refer to 862*593dc095SDavid du Colombierhttp://www.ghostscript.com/licensing/. For information on 863*593dc095SDavid du Colombiercommercial licensing, go to http://www.artifex.com/licensing/ or 864*593dc095SDavid du Colombiercontact Artifex Software, Inc., 101 Lucas Valley Road #110, 865*593dc095SDavid du ColombierSan Rafael, CA 94903, U.S.A., +1(415)492-9861. 8667dd7cddfSDavid du Colombier 8673ff48bf5SDavid du Colombier<p> 868*593dc095SDavid du Colombier<small>Ghostscript version 8.53, 20 October 2005 8697dd7cddfSDavid du Colombier 8707dd7cddfSDavid du Colombier<!-- [3.0 end visible trailer] ============================================= --> 8717dd7cddfSDavid du Colombier 8727dd7cddfSDavid du Colombier</body> 8737dd7cddfSDavid du Colombier</html> 874