diff options
Diffstat (limited to 'Master/xemtex/doc/ghostscript/Lib.htm')
-rw-r--r-- | Master/xemtex/doc/ghostscript/Lib.htm | 491 |
1 files changed, 491 insertions, 0 deletions
diff --git a/Master/xemtex/doc/ghostscript/Lib.htm b/Master/xemtex/doc/ghostscript/Lib.htm new file mode 100644 index 00000000000..d3377b6238b --- /dev/null +++ b/Master/xemtex/doc/ghostscript/Lib.htm @@ -0,0 +1,491 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<title>The Ghostscript library</title> +<!-- $Id: Lib.htm,v 1.14.2.11.2.5 2003/05/17 14:39:00 giles Exp $ --> +<!-- Originally: lib.txt --> +<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> +</head> + +<body> +<!-- [1.0 begin visible header] ============================================ --> + +<!-- [1.1 begin headline] ================================================== --> + +<h1>The Ghostscript Library</h1> + +<!-- [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">Ghostscript +overview</a>. + +<!-- [1.3 end hint] ======================================================== --> + +<hr> + +<!-- [1.0 end visible header] ============================================== --> + +<!-- [2.0 begin contents] ================================================== --> + +<h2><a name="GS_library"></a>The Ghostscript library</h2> + +<p> +This document describes the Ghostscript library, a set of procedures +to implement the graphics and filtering capabilities that are primitive +operations in the PostScript language and in Adobe Portable Document Format +(PDF). + +<p> +Ghostscript is actually two programs: a language interpreter, and a +graphics library. The library provides, in the form of C procedures, all +the graphics functions of the language, that is, approximately those +facilities listed in section 8.1 of the <cite>PostScript +Language Reference Manual</cite>, starting with the +graphics state operators. In addition, the library provides some +lower-level graphics facilities that offer higher performance in exchange +for less generality. + +<hr> + +<h2><a name="PS_operator_API"></a>PostScript operator API</h2> + +<p> +The highest level of the library, which is the one that most clients will +use, directly implements the PostScript graphics operators with procedures +named <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 graphics +state 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 >= 0 for a +successful return or <0 for a failure. The failure codes correspond +directly 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 +<cite>PostScript Language Reference Manual</cite>, with the indicated +omissions 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 not +implemented directly; the library provides lower-level procedures that can +be 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 for +the 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 procedure +to set up an enumerator object, and then calls another procedure for each +iteration. The <b><tt>...show</tt></b> operators, +<b><tt>charpath</tt></b>, and <b><tt>stringwidth</tt></b> also use an +inverted control structure. + +<blockquote><table cellpadding=0 cellspacing=0> +<tr valign=bottom> + <th align=left>Section<br>(operators) + <td> + <th align=left>Headers + <td> + <th align=left>Omissions +<tr> <td colspan=5><hr> +<tr valign=top> <td>Graphics state -- device-independent + <td> + <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> + <td> +<tr> <td> +<tr valign=top> <td>Graphics state -- device-dependent + <td> + <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> + <td> +<tr> <td> +<tr valign=top> <td>Coordinate system and matrix + <td> + <td><b><tt>gscoord.h</tt></b><br><b><tt>gsmatrix.h</tt></b> + <td> + <td><b><tt>*matrix</tt></b>, <b><tt>*identmatrix</tt></b>, <b><tt>*concatmatrix</tt></b>, <b><tt>*invertmatrix</tt></b> +<tr> <td> +<tr valign=top> <td>Path construction + <td> + <td><b><tt>gspath.h</tt></b><br><b><tt>gspath2.h</tt></b> + <td> + <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> +<tr valign=top> <td>Painting + <td> + <td><b><tt>gsimage.h</tt></b><br><b><tt>gspaint.h</tt></b><br><b><tt>gspath2.h</tt></b> + <td> + <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> +<tr valign=top> <td>Form and pattern + <td> + <td><b><tt>gscolor2.h</tt></b> + <td> + <td><b><tt>execform</tt></b> +<tr> <td> +<tr valign=top> <td>Device setup and output + <td> + <td><b><tt>gsdevice.h</tt></b> + <td> + <td><b><tt>*showpage</tt></b>, <b><tt>*set</tt></b>/<b><tt>currentpagedevice</tt></b> +<tr> <td> +<tr valign=top> <td>Character and font + <td> + <td><b><tt>gschar.h</tt></b><br><b><tt>gsfont.h</tt></b> + <td> + <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 their +PostScript 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 in +the graphics state. Takes an explicit allocator for allocating the pattern +implementation. 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 color +parameter 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 corresponding +operations on free-standing matrices are in <b><tt>gsmatrix.h</tt></b> and +have 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 than +using 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 the +parameter 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 that +control returns to the caller if the character must be rasterized. +</dl> + +<p> +This level of the library also implements the following operators from other +sections of the Manual: + +<blockquote><table cellpadding=0 cellspacing=0> +<tr valign=bottom> + <th align=left>Section<br>(operators) + <td> + <th align=left>Headers + <td> + <th align=left>Operators +<tr> <td colspan=5><hr> +<tr valign=top> <td>Interpreter parameter + <td> + <td><b><tt>gsfont.h</tt></b> + <td> + <td><b><tt>cachestatus</tt></b>, <b><tt>setcachelimit</tt></b>, <b><tt>*set/currentcacheparams</tt></b> +<tr valign=top> <td>Display PostScript + <td> + <td><b><tt>gsstate.h</tt></b> + <td> + <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 always +include all of these features. + +<p> +Files named <b><tt>gs*.c</tt></b> implement the higher level of the +graphics library. As might be expected, all procedures, variables, and +structures available at this level begin with "<b><tt>gs_</tt></b>". +Structures that appear in these interfaces, but whose definitions may be +hidden from clients, also have names beginning with "<b><tt>gs_</tt></b>", +that is, the prefix, not the implementation, reflects at what level the +abstraction is made available. + +<h3><a name="Patterns"></a>Patterns</h3> + +<p> +Patterns are the most complicated PostScript language objects that the +library API deals with. As in PostScript, defining a pattern color and +using 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> + <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> + <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> + <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> + <td>The current graphics state. +<tr valign=top> <td><b><tt>gs_memory_t *</tt></b> + <td> + <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 *client_data</tt></b>, which is a place for clients to +store a pointer to additional data for the <b><tt>PaintProc</tt></b>; this +provides 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 as +parameters a <b><tt>gs_client_color *</tt></b>, which is the +<b><tt>Pattern</tt></b> color that is being used for painting, and a +<b><tt>gs_state *</tt></b>, which is the same graphics state that +would be presented to the <b><tt>PaintProc</tt></b> in PostScript. +Currently the <b><tt>gs_client_color *</tt></b> is always the current +color in the graphics state, but the <b><tt>PaintProc</tt></b> should not +rely on this. The <b><tt>PaintProc</tt></b> can retrieve the +<b><tt>gs_client_pattern *</tt></b> from the +<b><tt>gs_client_color *</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 same +underlying 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 be +filled in for uncolored patterns; this corresponds to the additional +arguments for the PostScript <b><tt>setpattern</tt></b> operator in the +uncolored case. + +<p> +There is a special procedure <b><tt>gs_makebitmappattern</tt></b> for creating bitmap-based +patterns. 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 particularly +simple <b><tt>PaintProc.</tt></b> + +<h3><a name="Lower_level_API"></a>Lower-level API</h3> + +<p> +Files named <b><tt>gx*.c</tt></b> implement the lower level of the graphics +library. 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> interfaces +generally use device coordinates in an internal fixed-point representation, +as opposed to the <b><tt>gs</tt></b> interfaces that use floating point +user 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 to +the Ghostscript implementation, and are not designed to be called by +clients. + +<hr> + +<h2><a name="Full_example"></a>A full example</h2> + +<p> +The file <b><tt>gslib.c</tt></b> in the Ghostscript fileset is a complete +example 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 are +intended to provide a roadmap for applications that call the library. + +<blockquote><pre>/* Capture stdin/out/err before gs.h redefines them. */ +#include <stdio.h> +static FILE *real_stdin, *real_stdout, *real_stderr; +static void +get_real(void) +{ real_stdin = stdin, real_stdout = stdout, real_stderr = stderr; +}</pre></blockquote> + +<p> +Any application using Ghostscript should include the fragment above at the +very 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 related +to the Ghostscript memory manager, portability machinery, debugging +framework, and other substrate facilities. Any application file that calls +any 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(&gs_memory_default, 20000); + imem->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> now +points to the graphics state that will be passed to the drawing routines in +the 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, &dpi); + ht.frequency = min(fabs(dpi.x), fabs(dpi.y)) / 16.001; + ht.angle = 0; + ht.spot_function = odsf; + gs_setscreen(pgs, &ht); + }</pre></blockquote> + +<p> +The code above initializes the default device and sets a default halftone +screen. (For brevity, we have omitted the definition of odsf, the spot +function.) + +<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 program +is finished, it should execute: + +<blockquote><pre> gs_lib_finit(0, 0);</pre></blockquote> + +<!-- [2.0 end contents] ==================================================== --> + +<!-- [3.0 begin visible trailer] =========================================== --> +<hr> + +<p> +<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises. +All rights reserved.</small> + +<p> +This software is provided AS-IS with no warranty, either express or +implied. + +This software is distributed under license and may not be copied, +modified or distributed except as expressly authorized under the terms +of the license contained in the file LICENSE in this distribution. + +<p> +<small>Ghostscript version 7.07, 17 May 2003 + +<!-- [3.0 end visible trailer] ============================================= --> + +</body> +</html> |