<html><head><title>The Ghostscript library</title><!-- $Id: Lib.htm,v 1.1 2000/03/09 08:40:39 lpd Exp $ --><!-- Originally: lib.txt --></head> <body><!-- [1.0 begin visible header] ============================================ --> <!-- [1.1 begin headline] ================================================== --> <table width="100%" border="0"><tr><th align="center" bgcolor="#CCCC00"><font size=6>The Ghostscript library</font></table> <!-- [1.1 end headline] ==================================================== --> <!-- [1.2 begin table of contents] ========================================= --> <h2>Table of contents</h2> <blockquote><ul><li><a href="#GS_library">The Ghostscript library</a><li><a href="#PS_operator_API">PostScript operator API</a><ul><li><a href="#Patterns">Patterns</a><li><a href="#Lower_level_API">Lower-level API</a></ul><li><a href="#Full_example">A full example</a></ul></blockquote> <!-- [1.2 end table of contents] =========================================== --> <!-- [1.3 begin hint] ====================================================== --> <p>For other information, see the <a href="Readme.htm">Ghostscriptoverview</a>. <!-- [1.3 end hint] ======================================================== --> <hr> <!-- [1.0 end visible header] ============================================== --> <!-- [2.0 begin contents] ================================================== --> <h1><a name="GS_library"></a>The Ghostscript library</h1> <p>This document describes the Ghostscript library, a set of proceduresto implement the graphics and filtering capabilities that are primitiveoperations in the PostScript language and in Adobe Portable Document Format(PDF). <p>Ghostscript is actually two programs: a language interpreter, and agraphics library.  The library provides, in the form of C procedures, allthe graphics functions of the language, that is, approximately thosefacilities listed in section 8.1 of the<em><a href="http://cseng.awl.com/bookdetail.qry?ISBN=0-201-18127-4&amp;ptype=0">PostScriptLanguage Reference Manual</a></em>, Second Edition, starting with thegraphics state operators.  In addition, the library provides somelower-level graphics facilities that offer higher performance in exchangefor less generality. <hr> <h1><a name="PS_operator_API"></a>PostScript operator API</h1> <p>The highest level of the library, which is the one that most clients willuse, directly implements the PostScript graphics operators with proceduresnamed <b><tt>gs_XXX</tt></b>, for instance <b><tt>gs_moveto</tt></b> and<b><tt>gs_fill</tt></b>.  Nearly all of these procedures take graphicsstate objects as their first arguments, such as <blockquote><b><tt>int gs_moveto(gs_state *, double, double);</tt></b></blockquote> <p>Nearly every procedure returns an integer code which is &gt;= 0 for asuccessful return or &lt;0 for a failure.  The failure codes corresponddirectly to PostScript errors, and are defined in<b><tt>gserrors.h</tt></b>. <p>The library implements all the operators in the following sections of the<em><a href="http://cseng.awl.com/bookdetail.qry?ISBN=0-201-18127-4&amp;ptype=0">PostScriptLanguage Reference Manual</a></em>, Second Edition, with the indicatedomissions and with the APIs defined in the indicated <b><tt>.h</tt></b>files.  A header of the form <b><em>A.h(B.h)</em></b> indicates that<b><em>A.h</em></b> is included in <b><em>B.h</em></b>, so<b><em>A.h</em></b> need not be included explicitly if <b><em>B.h</em></b>is included.  Operators marked with * in the "omissions" column are notimplemented directly; the library provides lower-level procedures that canbe used to implement the operator. <p>There are slight differences in the operators that return multiple values,since C's provisions for this are awkward.  Also, the control structure forthe operators involving callback procedures (<b><tt>pathforall</tt></b>,<b><tt>image</tt></b>, <b><tt>colorimage</tt></b>,<b><tt>imagemask</tt></b>) is partly inverted: the client calls a procedureto set up an enumerator object, and then calls another procedure for eachiteration.  The <b><tt>...show</tt></b> operators,<b><tt>charpath</tt></b>, and <b><tt>stringwidth</tt></b> also use aninverted control structure. <blockquote><table cellpadding=0 cellspacing=0><tr valign=bottom>	<th align=left>Section<br>(operators)	<td>&nbsp;&nbsp;	<th align=left>Headers	<td>&nbsp;&nbsp;	<th align=left>Omissions<tr>	<td colspan=5><hr><tr valign=top>	<td>Graphics state -- device-independent	<td>&nbsp;	<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>	<td>&nbsp;	<td>&nbsp;<tr>	<td>&nbsp;<tr valign=top>	<td>Graphics state -- device-dependent	<td>&nbsp;	<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>)	<td>&nbsp;	<td>&nbsp;<tr>	<td>&nbsp;<tr valign=top>	<td>Coordinate system and matrix	<td>&nbsp;	<td><b><tt>gscoord.h</tt></b><br><b><tt>gsmatrix.h</tt></b>	<td>&nbsp;	<td><b><tt>*matrix</tt></b>, <b><tt>*identmatrix</tt></b>, <b><tt>*concatmatrix</tt></b>, <b><tt>*invertmatrix</tt></b><tr>	<td>&nbsp;<tr valign=top>	<td>Path construction	<td>&nbsp;	<td><b><tt>gspath.h</tt></b><br><b><tt>gspath2.h</tt></b>	<td>&nbsp;	<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><tr>	<td>&nbsp;<tr valign=top>	<td>Painting	<td>&nbsp;	<td><b><tt>gsimage.h</tt></b><br><b><tt>gspaint.h</tt></b><br><b><tt>gspath2.h</tt></b>	<td>&nbsp;	<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><tr>	<td>&nbsp;<tr valign=top>	<td>Form and pattern	<td>&nbsp;	<td><b><tt>gscolor2.h</tt></b>	<td>&nbsp;	<td><b><tt>execform</tt></b><tr>	<td>&nbsp;<tr valign=top>	<td>Device setup and output	<td>&nbsp;	<td><b><tt>gsdevice.h</tt></b>	<td>&nbsp;	<td><b><tt>*showpage</tt></b>, <b><tt>*set</tt></b>/<b><tt>currentpagedevice</tt></b><tr>	<td>&nbsp;<tr valign=top>	<td>Character and font	<td>&nbsp;	<td><b><tt>gschar.h</tt></b><br><b><tt>gsfont.h</tt></b>	<td>&nbsp;	<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></table></blockquote> <p>The following procedures from the list above operate differently from theirPostScript operator counterparts, as explained here: <dl><dt><b><tt>gs_makepattern(gscolor2.h)</tt></b><dd>Takes an explicit current color, rather than using the current color inthe graphics state.  Takes an explicit allocator for allocating the patternimplementation.  See below for more details on<b><tt>gs_makepattern</tt></b>.</dl> <dl><dt><b><tt>gs_setpattern(gscolor2.h)</tt></b><dt><b><tt>gs_setcolor(gscolor2.h)</tt></b><dt><b><tt>gs_currentcolor(gscolor2.h)</tt></b><dd>Use <b><tt>gs_client_color</tt></b> rather than a set of colorparameter values.  See below for more details on<b><tt>gs_setpattern</tt></b>.</dl> <dl><dt><b><tt>gs_currentdash_length/pattern/offset(gsline.h)</tt></b><dd>Splits up <b><tt>currentdash</tt></b> into three separate procedures.</dl> <dl><dt><b><tt>gs_screen_init/currentpoint/next/install(gsht.h)</tt></b><dd>Provide an "enumeration style" interface to <b><tt>setscreen</tt></b>.(<b><tt>gs_setscreen</tt></b> is also implemented.)</dl> <dl><dt><b><tt>gs_rotate/scale/translate(gscoord.h)</tt></b><dt><b><tt>gs_[i][d]transform(gscoord.h)</tt></b><dd>These always operate on the graphics state CTM.  The correspondingoperations on free-standing matrices are in <b><tt>gsmatrix.h</tt></b> andhave different names.</dl> <dl><dt><b><tt>gs_path_enum_alloc/init/next/cleanup(gspath.h)</tt></b><dd>Provide an "enumeration style" implementation of<b><tt>pathforall</tt></b>.</dl> <dl><dt><b><tt>gs_image_enum_alloc(gsimage.h)</tt></b><dt><b><tt>gs_image_init/next/cleanup(gsimage.h)</tt></b><dd>Provide an "enumeration style" interface to the equivalent of<b><tt>image</tt></b>, <b><tt>imagemask</tt></b>, and<b><tt>colorimage</tt></b>.  In the <b><tt>gs_image_t</tt></b>,<b><tt>ColorSpace</tt></b> provides an explicit color space, rather thanusing the current color space in the graphics state;<b><tt>ImageMask</tt></b> distinguishes <b><tt>imagemask</tt></b> from<b><tt>[color]image</tt></b>.</dl> <dl><dt><b><tt>gs_get/putdeviceparams(gsdevice.h)</tt></b><dd>Take a <b><tt>gs_param_list</tt></b> for specifying or receiving theparameter values.  See <b><tt>gsparam.h</tt></b> for more details.</dl> <dl><dt><b><tt>gs_show_enum_alloc/release(gschar.h)</tt></b><dt><b><tt>gs_xxxshow_[n_]init(gschar.h)</tt></b><dt><b><tt>gs_show_next(gschar.h)</tt></b><dd>Provide an "enumeration style" interface to writing text.  Note thatcontrol returns to the caller if the character must be rasterized.</dl> <p>This level of the library also implements the following operators from othersections of the Manual: <blockquote><table cellpadding=0 cellspacing=0><tr valign=bottom>	<th align=left>Section<br>(operators)	<td>&nbsp;&nbsp;	<th align=left>Headers	<td>&nbsp;&nbsp;	<th align=left>Operators<tr>	<td colspan=5><hr><tr valign=top>	<td>Interpreter parameter	<td>&nbsp;	<td><b><tt>gsfont.h</tt></b>	<td>&nbsp;	<td><b><tt>cachestatus</tt></b>, <b><tt>setcachelimit</tt></b>, <b><tt>*set/currentcacheparams</tt></b><tr valign=top>	<td>Display PostScript	<td>&nbsp;	<td><b><tt>gsstate.h</tt></b>	<td>&nbsp;	<td><b><tt>set/currenthalftonephase</tt></b></table></blockquote> <p>In order to obtain the full PostScript Level 2 functionality listed above,<b><tt>FEATURE_DEVS</tt></b> must be set in the makefile to include at least the following: <blockquote><b><tt>FEATURE_DEVS=patcore.dev cmykcore.dev psl2core.dev dps2core.dev ciecore.dev path1core.dev hsbcore.dev</tt></b></blockquote> <p>The <b><tt>*lib.mak</tt></b> makefiles mentioned below do not alwaysinclude all of these features. <p>Files named <b><tt>gs*.c</tt></b> implement the higher level of thegraphics library.  As might be expected, all procedures, variables, andstructures available at this level begin with "<b><tt>gs_</tt></b>".Structures that appear in these interfaces, but whose definitions may behidden from clients, also have names beginning with "<b><tt>gs_</tt></b>",that is, the prefix, not the implementation, reflects at what level theabstraction is made available. <h2><a name="Patterns"></a>Patterns</h2> <p>Patterns are the most complicated PostScript language objects that thelibrary API deals with.  As in PostScript, defining a pattern color andusing the color are two separate operations. <p><b><tt>gs_makepattern</tt></b> defines a pattern color.  Its arguments are as follows: <blockquote><table cellpadding=0 cellspacing=0><tr valign=top>	<td><b><tt>gs_client_color *</tt></b>	<td>&nbsp;&nbsp;&nbsp;	<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.<tr valign=top>	<td><b><tt>const gs_client_pattern *</tt></b>	<td>&nbsp;	<td>The analogue of the original <b><tt>Pattern</tt></b> dictionary, described in detail just below.<tr valign=top>	<td><b><tt>const gs_matrix *</tt></b>	<td>&nbsp;	<td>Corresponds to the matrix argument of the <b><tt>makepattern</tt></b> operator.<tr valign=top>	<td><b><tt>gs_state *</tt></b>	<td>&nbsp;	<td>The current graphics state.<tr valign=top>	<td><b><tt>gs_memory_t *</tt></b>	<td>&nbsp;	<td>The allocator to use for allocating the saved data for the	    <b><tt>Pattern</tt></b> color.  If this is	    <b><tt>NULL</tt></b>, <b><tt>gs_makepattern</tt></b> uses the	    same allocator that allocated the graphics state.  Library	    clients should probably always use <b><tt>NULL</tt></b>. </table></blockquote> <p>The <b><tt>gs_client_pattern</tt></b> structure defined in<b><tt>gscolor2.h</tt></b> corresponds to the <b><tt>Pattern</tt></b>dictionary that is the argument to the PostScript language<b><tt>makepattern</tt></b> operator.  This structure has one extra member,<b><tt>void&nbsp;*client_data</tt></b>, which is a place for clients tostore a pointer to additional data for the <b><tt>PaintProc</tt></b>; thisprovides the same functionality as putting additional keys in the<b><tt>Pattern</tt></b> dictionary at the PostScript language level.  The<b><tt>PaintProc</tt></b> is an ordinary C procedure that takes asparameters a <b><tt>gs_client_color&nbsp;*</tt></b>, which is the<b><tt>Pattern</tt></b> color that is being used for painting, and a<b><tt>gs_state&nbsp;*</tt></b>, which is the same graphics state thatwould be presented to the <b><tt>PaintProc</tt></b> in PostScript.Currently the <b><tt>gs_client_color&nbsp;*</tt></b> is always the currentcolor in the graphics state, but the <b><tt>PaintProc</tt></b> should notrely on this.  The <b><tt>PaintProc</tt></b> can retrieve the<b><tt>gs_client_pattern&nbsp;*</tt></b> from the<b><tt>gs_client_color&nbsp;*</tt></b> with the<b><tt>gs_getpattern</tt></b> procedure, also defined in<b><tt>gscolor2.h</tt></b>, and from there, it can retrieve the<b><tt>client_data</tt></b> pointer. <p>The normal way to set a <b><tt>Pattern</tt></b> color is to call<b><tt>gs_setpattern</tt></b> with the graphics state and with the<b><tt>gs_client_color</tt></b> returned by <b><tt>gs_makepattern</tt></b>.After that, one can use <b><tt>gs_setcolor</tt></b> to set further<b><tt>Pattern</tt></b> colors (colored, or uncolored with the sameunderlying color space); the rules are the same as those in PostScript.Note that for <b><tt>gs_setpattern</tt></b>, the<b><tt>paint.values</tt></b> in the <b><tt>gs_client_color</tt></b> must befilled in for uncolored patterns; this corresponds to the additionalarguments for the PostScript <b><tt>setpattern</tt></b> operator in theuncolored case. <p>There is a special procedure <b><tt>gs_makebitmappattern</tt></b> for creating bitmap-basedpatterns.  Its API is documented in <b><tt>gscolor2.h</tt></b>; its implementation, in<b><tt>gspcolor.c</tt></b>, may be useful as an example of a pattern using a particularlysimple <b><tt>PaintProc.</tt></b> <h2><a name="Lower_level_API"></a>Lower-level API</h2> <p>Files named <b><tt>gx*.c</tt></b> implement the lower level of the graphicslibrary.  The interfaces at the <b><tt>gx</tt></b> level are less stable,and expose more of the implementation detail, than those at the<b><tt>gs</tt></b> level: in particular, the <b><tt>gx</tt></b> interfacesgenerally use device coordinates in an internal fixed-point representation,as opposed to the <b><tt>gs</tt></b> interfaces that use floating pointuser coordinates.  Named entities at this level begin with<b><tt>gx_</tt></b>. <p>Files named <b><tt>gz*.c</tt></b> and <b><tt>gz*.h</tt></b> are internal tothe Ghostscript implementation, and are not designed to be called byclients. <hr> <h1><a name="Full_example"></a>A full example</h1> <p>The file <b><tt>gslib.c</tt></b> in the Ghostscript fileset is a completeexample program that initializes the library and produces output using it;files named <b><tt>*lib.mak</tt></b> (such as <b><tt>ugcclib.mak</tt></b>and <b><tt>bclib.mak</tt></b>) are makefiles using <b><tt>gslib.c</tt></b>as the main program.  The following annotated excerpts from this file areintended to provide a roadmap for applications that call the library. <blockquote><pre>/* Capture stdin/out/err before gs.h redefines them. */#include &lt;stdio.h&gt;static FILE *real_stdin, *real_stdout, *real_stderr;static voidget_real(void){       real_stdin = stdin, real_stdout = stdout, real_stderr = stderr;}</pre></blockquote> <p>Any application using Ghostscript should include the fragment above at thevery beginning of the main program. <blockquote><pre>#include "gx.h"</pre></blockquote> <p>The <b><tt>gx.h</tt></b> header includes a wealth of declarations relatedto the Ghostscript memory manager, portability machinery, debuggingframework, and other substrate facilities.  Any application file that callsany Ghostscript API functions should probably include <b><tt>gx.h</tt></b>. <blockquote><pre>/* Configuration information imported from gconfig.c. */extern gx_device *gx_device_list[]; /* Other imported procedures */        /* from gsinit.c */extern void gs_lib_init(P1(FILE *));extern void gs_lib_finit(P2(int, int));        /* from gsalloc.c */extern gs_ref_memory_t *ialloc_alloc_state(P2(gs_memory_t *, uint));</pre></blockquote> <p>The externs above are needed for initializing the library. <blockquote><pre>        gs_ref_memory_t *imem;#define mem ((gs_memory_t *)imem)        gs_state *pgs;        gx_device *dev = gx_device_list[0];         gp_init();        get_real();        gs_stdin = real_stdin;        gs_stdout = real_stdout;        gs_stderr = real_stderr;        gs_lib_init(stdout);        ....        imem = ialloc_alloc_state(&amp;gs_memory_default, 20000);        imem-&gt;space = 0;        ....        pgs = gs_state_alloc(mem);</pre></blockquote> <p>The code above initializes the library and its memory manager.  <b><tt>pgs</tt></b> nowpoints to the graphics state that will be passed to the drawing routines inthe library. <blockquote><pre>        gs_setdevice_no_erase(pgs, dev);    /* can't erase yet */        {   gs_point dpi;            gs_screen_halftone ht;            gs_dtransform(pgs, 72.0, 72.0, &amp;dpi);            ht.frequency = min(fabs(dpi.x), fabs(dpi.y)) / 16.001;            ht.angle = 0;            ht.spot_function = odsf;            gs_setscreen(pgs, &amp;ht);        }</pre></blockquote> <p>The code above initializes the default device and sets a default halftonescreen.  (For brevity, we have omitted the definition of odsf, the spotfunction.) <blockquote><pre>        /* gsave and grestore (among other places) assume that */        /* there are at least 2 gstates on the graphics stack. */        /* Ensure that now. */        gs_gsave(pgs);</pre></blockquote> <p>The call above completes initializing the graphics state.  When the programis finished, it should execute: <blockquote><pre>        gs_lib_finit(0, 0);</pre></blockquote> <!-- [2.0 end contents] ==================================================== --> <!-- [3.0 begin visible trailer] =========================================== --><hr> <font size=2> <p>Copyright &copy; 1996, 1997, 1998 Aladdin Enterprises.  All rights reserved. <p>This file is part of Aladdin Ghostscript.  See the<a href="Public.htm">Aladdin Free Public License</a> (the "License") forfull details of the terms of using, copying, modifying, and redistributingAladdin Ghostscript. <p>Ghostscript version 6.0, 3 February 2000 </font> <!-- [3.0 end visible trailer] ============================================= --> </body></html>