diff options
Diffstat (limited to 'doc/Lib.htm')
| -rw-r--r-- | doc/Lib.htm | 1023 |
1 files changed, 0 insertions, 1023 deletions
diff --git a/doc/Lib.htm b/doc/Lib.htm deleted file mode 100644 index 10ce8ec4c..000000000 --- a/doc/Lib.htm +++ /dev/null @@ -1,1023 +0,0 @@ -<!doctype html> -<html lang="en"> -<head> - <meta http-equiv="content-type" content="text/html; charset=utf-8"> - <meta name="viewport" content="user-scalable=yes, initial-scale=1, width=device-width"> - <link href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:200,200i,300,300i,400,400i,600,600i,700,700i,900,900i" rel="stylesheet"> - <link rel="shortcut icon" href="images/favicon.svg"> - <title>The Ghostscript Library</title> - <link href="default.css" rel="stylesheet" type="text/css"> -</head> - -<body> - <header><div class="title"><a href="index.html"><h1 aria-label="title">Ghostscript documentation</h1><h2 aria-label="version"></h2></a></div><a href="Search.htm" aria-label="Search" id="searchSite"><div class="search"></div></a></header> - <main> - <article> - <div class="outer"> - - <div class="inner"> -<!--START EDITING HERE--> - -<h1>The Ghostscript Library</h1> - -<h2><a name="toc"></a>Table of contents</h2> -<ul class="toc"> - <li><a href="#GS_library">The Ghostscript library</a> - <li><a href="#PS_operator_API">PostScript operator API</a> - <li> - <ul> - <li><a href="#Patterns">Patterns</a> - <li><a href="#Lower_level_API">Lower-level API</a> - </ul> - </li> - <li><a href="#Visual_trace">Visual Trace instructions</a> - <li><a href="#Full_example">A full example</a> -</ul> - -<!-- [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 <code>gs_XXX</code>, for instance <code>gs_moveto</code> and -<code>gs_fill</code>. Nearly all of these procedures take graphics -state objects as their first arguments, such as - -<blockquote><code> -int gs_moveto(gs_state *, double, double); -</code></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 -<code>gserrors.h</code>. - -<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 <code>.h</code> -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 (<code>pathforall</code>, -<code>image</code>, <code>colorimage</code>, -<code>imagemask</code>) is partly inverted: the client calls a procedure -to set up an enumerator object, and then calls another procedure for each -iteration. The <code>...show</code> operators, -<code>charpath</code>, and <code>stringwidth</code> also use an -inverted control structure. - -<blockquote><table> -<tr> - <th align="left">Section<br>(operators)</th> - - <th align="left">Headers</th> - - <th align="left">Omissions</th> - </tr> -<tr> - <td>Graphics state – device-independent</td> - - <td><code>gscolor.h</code>(<code>gsstate.h</code>)<br><code>gscolor1.h</code><br><code>gscolor2.h</code><br><code>gscspace.h</code><br><code>gshsb.h</code><br><code>gsline.h</code>(<code>gsstate.h</code>)<br><code>gsstate.h</code></td> - - <td> </td> - </tr> -<tr> - <td>Graphics state – device-dependent</td> - - <td><code>gscolor.h</code>(<code>gsstate.h</code>)<br><code>gscolor1.h</code><br><code>gscolor2.h</code><br><code>gsht.h</code>(<code>gsht1.h</code>,<code>gsstate.h</code>)<br><code>gsht1.h</code><br><code>gsline.h</code>(<code>gsstate.h</code>)</td> - - <td> </td> - </tr> -<tr> - <td>Coordinate system and matrix</td> - - <td><code>gscoord.h</code><br><code>gsmatrix.h</code></td> - - <td><code>*matrix</code>, <code>*identmatrix</code>, <code>*concatmatrix</code>, <code>*invertmatrix</code></td> - </tr> -<tr> - <td>Path construction</td> - - <td><code>gspath.h</code><br><code>gspath2.h</code></td> - - <td><code>*arct</code>, <code>*pathforall</code>, <code>ustrokepath</code>, <code>uappend</code>, <code>upath</code>, <code>ucache</code></td> - </tr> -<tr> - <td>Painting</td> - - <td><code>gsimage.h</code><br><code>gspaint.h</code><br><code>gspath2.h</code></td> - - <td><code>*image</code>, <code>*colorimage</code>, <code>*imagemask</code>, <code>ufill</code>, <code>ueofill</code>, <code>ustroke</code></td> - </tr> -<tr> - <td>Form and pattern</td> - - <td><code>gscolor2.h</code></td> - - <td><code>execform</code></td> - </tr> -<tr> - <td>Device setup and output</td> - - <td><code>gsdevice.h</code></td> - - <td><code>*showpage</code>, <code>*set</code>/<code>currentpagedevice</code></td> - </tr> -<tr> - <td>Character and font</td> - - <td><code>gschar.h</code><br><code>gsfont.h</code></td> - - <td>*(all the <code>show</code> operators), <code>definefont</code>, <code>undefinefont</code>, <code>findfont</code>, <code>*scalefont</code>, <code>*makefont</code>, <code>selectfont</code>, <code>[Global]FontDirectory</code>, <code>Standard</code>/<code>ISOLatin1Encoding</code>, <code>findencoding</code></td> - </tr> -</table></blockquote> - -<p> -The following procedures from the list above operate differently from their -PostScript operator counterparts, as explained here: - -<dl> -<dt><code>gs_makepattern(gscolor2.h)</code> -<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 -<code>gs_makepattern</code>. -</dl> - -<dl> -<dt><code>gs_setpattern(gscolor2.h)</code> -<dt><code>gs_setcolor(gscolor2.h)</code> -<dt><code>gs_currentcolor(gscolor2.h)</code> -<dd>Use <code>gs_client_color</code> rather than a set of color -parameter values. See below for more details on -<code>gs_setpattern</code>. -</dl> - -<dl> -<dt><code>gs_currentdash_length/pattern/offset(gsline.h)</code> -<dd>Splits up <code>currentdash</code> into three separate procedures. -</dl> - -<dl> -<dt><code>gs_screen_init/currentpoint/next/install(gsht.h)</code> -<dd>Provide an "enumeration style" interface to <code>setscreen</code>. -(<code>gs_setscreen</code> is also implemented.) -</dl> - -<dl> -<dt><code>gs_rotate/scale/translate(gscoord.h)</code> -<dt><code>gs_[i][d]transform(gscoord.h)</code> -<dd>These always operate on the graphics state CTM. The corresponding -operations on free-standing matrices are in <code>gsmatrix.h</code> and -have different names. -</dl> - -<dl> -<dt><code>gs_path_enum_alloc/init/next/cleanup(gspath.h)</code> -<dd>Provide an "enumeration style" implementation of -<code>pathforall</code>. -</dl> - -<dl> -<dt><code>gs_image_enum_alloc(gsimage.h)</code> -<dt><code>gs_image_init/next/cleanup(gsimage.h)</code> -<dd>Provide an "enumeration style" interface to the equivalent of -<code>image</code>, <code>imagemask</code>, and -<code>colorimage</code>. In the <code>gs_image_t</code>, -<code>ColorSpace</code> provides an explicit color space, rather than -using the current color space in the graphics state; -<code>ImageMask</code> distinguishes <code>imagemask</code> from -<code>[color]image</code>. -</dl> - -<dl> -<dt><code>gs_get/putdeviceparams(gsdevice.h)</code> -<dd>Take a <code>gs_param_list</code> for specifying or receiving the -parameter values. See <code>gsparam.h</code> for more details. -</dl> - -<dl> -<dt><code>gs_show_enum_alloc/release(gschar.h)</code> -<dt><code>gs_xxxshow_[n_]init(gschar.h)</code> -<dt><code>gs_show_next(gschar.h)</code> -<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> -<tr> - <th align="left">Section<br>(operators)</th> - - <th align="left">Headers</th> - - <th align="left">Operators</th> - </tr> -<tr> - <td>Interpreter parameter</td> - - <td><code>gsfont.h</code></td> - - <td><code>cachestatus</code>, <code>setcachelimit</code>, <code>*set/currentcacheparams</code></td> - </tr> -<tr> - <td>Display PostScript</td> - - <td><code>gsstate.h</code></td> - - <td><code>set/currenthalftonephase</code></td> - </tr> -</table></blockquote> - -<p> -In order to obtain the full PostScript Level 2 functionality listed above, -<code>FEATURE_DEVS</code> must be set in the makefile to include at least the following: - -<blockquote><code> -FEATURE_DEVS=patcore.dev cmykcore.dev psl2core.dev dps2core.dev ciecore.dev path1core.dev hsbcore.dev -</code></blockquote> - -<p> -The <code>*lib.mak</code> makefiles mentioned below do not always -include all of these features. - -<p> -Files named <code>gs*.c</code> implement the higher level of the -graphics library. As might be expected, all procedures, variables, and -structures available at this level begin with "<code>gs_</code>". -Structures that appear in these interfaces, but whose definitions may be -hidden from clients, also have names beginning with "<code>gs_</code>", -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> -<code>gs_makepattern</code> defines a pattern color. Its arguments are as follows: - -<blockquote><table> -<tr> - <td><code>gs_client_color *</code></td> - - <td>The resulting <code>Pattern</code> 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.</td> - </tr> -<tr> - <td><code>const gs_client_pattern *</code></td> - - <td>The analogue of the original <code>Pattern</code> dictionary, described in detail just below.</td> - </tr> -<tr> - <td><code>const gs_matrix *</code></td> - - <td>Corresponds to the matrix argument of the <code>makepattern</code> operator.</td> - </tr> -<tr> - <td><code>gs_state *</code></td> - - <td>The current graphics state.</td> - </tr> -<tr> - <td><code>gs_memory_t *</code></td> - - <td>The allocator to use for allocating the saved data for the - <code>Pattern</code> color. If this is - <code>NULL</code>, <code>gs_makepattern</code> uses the - same allocator that allocated the graphics state. Library - clients should probably always use <code>NULL</code>.</td> -</tr> -</table></blockquote> - -<p> -The <code>gs_client_pattern</code> structure defined in -<code>gscolor2.h</code> corresponds to the <code>Pattern</code> -dictionary that is the argument to the PostScript language -<code>makepattern</code> operator. This structure has one extra member, -<code>void *client_data</code>, which is a place for clients to -store a pointer to additional data for the <code>PaintProc</code>; this -provides the same functionality as putting additional keys in the -<code>Pattern</code> dictionary at the PostScript language level. The -<code>PaintProc</code> is an ordinary C procedure that takes as -parameters a <code>gs_client_color *</code>, which is the -<code>Pattern</code> color that is being used for painting, and a -<code>gs_state *</code>, which is the same graphics state that -would be presented to the <code>PaintProc</code> in PostScript. -Currently the <code>gs_client_color *</code> is always the current -color in the graphics state, but the <code>PaintProc</code> should not -rely on this. The <code>PaintProc</code> can retrieve the -<code>gs_client_pattern *</code> from the -<code>gs_client_color *</code> with the -<code>gs_getpattern</code> procedure, also defined in -<code>gscolor2.h</code>, and from there, it can retrieve the -<code>client_data</code> pointer. - -<p> -The normal way to set a <code>Pattern</code> color is to call -<code>gs_setpattern</code> with the graphics state and with the -<code>gs_client_color</code> returned by <code>gs_makepattern</code>. -After that, one can use <code>gs_setcolor</code> to set further -<code>Pattern</code> colors (colored, or uncolored with the same -underlying color space); the rules are the same as those in PostScript. -Note that for <code>gs_setpattern</code>, the -<code>paint.values</code> in the <code>gs_client_color</code> must be -filled in for uncolored patterns; this corresponds to the additional -arguments for the PostScript <code>setpattern</code> operator in the -uncolored case. - -<p> -There is a special procedure <code>gs_makebitmappattern</code> for creating bitmap-based -patterns. Its API is documented in <code>gscolor2.h</code>; its implementation, in -<code>gspcolor.c</code>, may be useful as an example of a pattern using a particularly -simple <code>PaintProc.</code> - -<h3><a name="Lower_level_API"></a>Lower-level API</h3> - -<p> -Files named <code>gx*.c</code> implement the lower level of the graphics -library. The interfaces at the <code>gx</code> level are less stable, -and expose more of the implementation detail, than those at the -<code>gs</code> level: in particular, the <code>gx</code> interfaces -generally use device coordinates in an internal fixed-point representation, -as opposed to the <code>gs</code> interfaces that use floating point -user coordinates. Named entities at this level begin with -<code>gx_</code>. - -<p> -Files named <code>gz*.c</code> and <code>gz*.h</code> are internal to -the Ghostscript implementation, and are not designed to be called by -clients. - -<hr> - -<h2><a name="Visual_trace"></a>Visual Trace instructions</h2> - -<p> -Visual Trace instructions may be inserted in code to provide debug output in -a graphical form. Graphics Library doesn't provide a rasterisation of the -output, because it is platform dependent. Instead this, client application -shpuld set <code>vd_trace0</code> external variable to Graphics Library, -passing a set of callbacks which provide the rasterization. - -<p> -Visual Trace instructions are defined in <code>vdtrace.h</code>. -Debug output must be opened with <code>vd_get_dc</code> instruction, -which obtains a drawing context for the debug output, and must be closed -with <code>vd_release_dc</code> instruction. After opening the output, -scale, origin and shift to be set for mapping the debugee coordinate space -to window coordinate space. Than painting instructions to be used. -Painting may be either immediate or indirect. - -<p> -Indirect painting uses <code>vd_beg_path</code> before -line output and <code>vd_end_path</code> after line output, -to store a path into a temporary storage. After this -<code>vd_stroke</code> may be used for stroking the path, -or <code>vd_fill</code> may be used for filling the region inside the path. - -<p> -Immediate painting happens when path construction instructions are -involved without <code>vd_beg_path</code> and <code>vd_end_path</code>. -In this case lines and curves are being drawed immediately, when a path construction -instruction is executed. - -<p> -The following table explains the semantics of Visual Trace instructions. -<p> - -<table> - <tr> - <th colspan="3">Visual Trace instructions</th> - </tr> -<tr> - <th align="left">Instruction</th> - - <th align="left">Function</th> - - <th align="left">Parameters</th> - </tr> -<tr> - <td><code>vd_get_dc</code></td> - - <td>Obtain drawing context</td> - - <td><code>-T</code> option flag value, for which the subsequent output is enabled.</td> - </tr> -<tr> - <td><code>vd_release_dc</code></td> - - <td>Release drawing context</td> - - <td> </td> -</tr> -<tr> - <td><code>vd_enabled</code></td> - - <td>Is trace currently enabled ?</td> - - <td></td> - </tr> -<tr> - <td><code>vd_get_size_unscaled_x</code></td> - - <td>Get the horizontal size of the output window in pixels.</td> - - <td></td> - </tr> - <tr><td><code>vd_get_size_unscaled_y</code></td> - - <td>Get the vertical size of the output window in pixels.</td> - - <td></td></tr> -<tr> - <td><code>vd_get_size_caled_x</code></td> - - <td>Get the horizontal size of the output window in debuggee coordinate units.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_get_size_caled_y</code></td> - - <td>Get the vertical size of the output window in debuggee coordinate units.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_get_scale_x</code></td> - - <td>Get the horizontal scale.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_get_scale_y</code></td> - - <td>Get the vertical scale.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_get_origin_x</code></td> - - <td>Get the horizontal position of the draft origin in debuggee coordinate space.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_get_origin_y</code></td> - - <td>Get the vertical position of the draft origin in debuggee coordinate space.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_set_scale(s)</code></td> - - <td>Set isotripic scale.</td> - - <td>Debugee space to window space mapping scale, same for both dimentions.</td> - </tr> -<tr> - <td><code>vd_set_scaleXY(sx,sy)</code></td> - - <td>Set anisotripic scale.</td> - - <td>Debugee space to window space mapping scale, one for each dimention.</td> - </tr> -<tr> - <td><code>vd_set_origin(x,y)</code></td> - - <td>Set the draft origin.</td> - - <td>Origin of the draft in debugee space.</td> - </tr> -<tr> - <td><code>vd_set_shift(x,y)</code></td> - - <td>Set the draft position.</td> - - <td>Position of the draft origin in window space (in pixels).</td> - </tr> -<tr><td><code>vd_set_central_shift</code></td> - - <td>Set the draft position to window center.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_erase(c)</code></td> - - <td>Fill entire window.</td> - - <td>Color to fill.</td> - </tr> -<tr> - <td><code>vd_beg_path</code></td> - - <td>Begin path construction.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_end_path</code></td> - - <td>End path construction.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_moveto(x,y)</code></td> - - <td>Path construction : Set the draft current point.</td> - - <td>Debugee coordinates.</td> - </tr> -<tr> - <td><code>vd_lineto(x,y)</code></td> - - <td>Path construction : Line from current point to specified point.</td> - - <td>Debugee coordinates.</td> - </tr> -<tr> - <td><code>vd_lineto_mupti(p,n)</code></td> - - <td>Path construction : Poliline from current point to specified points.</td> - - <td>Array of points and its size, debugee coordinates.</td> - </tr> -<tr> - <td><code>vd_curveto(x0,y0,x1,y1,x2,y2)</code></td> - - <td>Path construction : Curve (3rd-order Bezier) from current - point to specified point, with specified poles.</td> - - <td>2 poles and the curve ending point, debuggee coordinates.</td> - </tr> -<tr> - <td><code>vd_closepath</code></td> - - <td>Path construction : Close the path (is necessary for filling an area).</td> - - <td></td> - </tr> -<tr> - <td><code>vd_bar(x0,y0,x1,y1,w,c)</code></td> - - <td>Bar from point to point.</td> - - <td>2 points (debugee coordinates), width (in pixels) and color.</td> - </tr> -<tr> - <td><code>vd_square(x0,y0,w,c)</code></td> - - <td>Square with specified center and size.</td> - - <td>The center (debugee coordinates), size (in pixels) and color.</td> - </tr> -<tr> - <td><code>vd_rect(x0,y0,x1,y1,w,c)</code></td> - - <td>Canonic rectangle with specified coordinites.</td> - - <td>Coordinates of boundaries (debugee coordinates), line width (in pixels) and color.</td> - </tr> -<tr> - <td><code>vd_quad(x0,y0,x1,y1,x2,y2,x3,y3,w,c)</code></td> - - <td>Quadrangle with specified coordinites.</td> - - <td>Coordinates of vertices (debugee coordinates), line width (in pixels) and color.</td> - </tr> -<tr> - <td><code>vd_curve(x0,y0,x1,y1,x2,y2,x3,y3,c,w)</code></td> - - <td>Curve with width.</td> - - <td>4 curve poles (debugee coordinates), color, and width (in pixels).</td> - </tr> -<tr> - <td><code>vd_circle(x,y,r,c)</code></td> - - <td>Circle.</td> - - <td>Center (debugee coordinates), radius (in pixels) and color.</td> - </tr> -<tr> - <td><code>vd_round(x,y,r,c)</code></td> - - <td>Filled circle.</td> - - <td>Center (debugee coordinates), radius (in pixels) and color.</td> - </tr> -<tr> - <td><code>vd_stroke</code></td> - - <td>Stroke a path constructed with vd_beg_path, vd_moveto, vd_lineto, - vd_curveto, vd_closepath, vd_end_path.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_fill</code></td> - - <td>Fill a path constructed with vd_beg_path, vd_moveto, vd_lineto, - vd_curveto, vd_closepath, vd_end_path.</td> - - <td></td> - </tr> -<tr> - <td><code>vd_setcolor(c)</code></td> - - <td>Set a color.</td> - - <td>Color (an integer consisting of red, green, blue bytes).</td> - </tr> -<tr> - <td><code>vd_setlinewidth(w)</code></td> - - <td>Set line width.</td> - - <td>Width (in pixels).</td> - </tr> -<tr> - <td><code>vd_text(x,y,s,c)</code></td> - - <td>Paint a text.</td> - - <td>Origin point (debugee coordinates), a string, and a color.</td> - </tr> -<tr> - <td><code>vd_wait</code></td> - - <td>Delay execution until a resuming command is entered through user interface.</td> - - <td></td> - </tr> -</table> - - -<p> -Graphics Library doesn't provide a rasterization of the debug output. -Instead it calls callbacks, which are specified by a client, and which may -have a platform dependent implementation. The implementation must not -use Graphics Library to exclude recursive calls to it from Visual Trace -instructions. The callbacks and auxiliary data are collected in -the structure <code>vd_trace_interface</code>, explained in the table below. -</p> - -<table> -<tr> - <th colspan="3">vd_trace_interface structure</th> - </tr> -<tr> - <th align="left">Field</th> - - <th align="left">Purpose</th> - - <th align="left">Parameters</th> - </tr> -<tr> - <td><code>host</code></td> - - <td>A pointer to the rasterizer control block - to be provided by client application. - The type of the fild is client dependent.</td> - - <td></td> - </tr> -<tr> - <td><code>scale_x, scale_y</code></td> - - <td>Scale of debugee coordinate to window coordinate mapping - internal work data, don't change.</td> - - <td></td> - </tr> -<tr> - <td><code>orig_x, orig_y</code></td> - - <td>Draft origin in debugee coordinates - internal work data, don't change.</td> - - <td></td> - </tr> -<tr> - <td><code>shift_x, shift_y</code></td> - - <td>Draft shift in window coordinates - internal work data, don't change.</td> - - <td></td> - </tr> -<tr> - <td><code>get_size_x(I)</code></td> - - <td>Get window width in pixels.</td> - - <td></td> - </tr> -<tr> - <td><code>get_size_y(I)</code></td> - - <td>Get window height in pixels.</td> - - <td></td> - </tr> -<tr> - <td><code>get_dc(I,I1)</code></td> - - <td>Obtain drawing context.</td> - - <td>Pointer to interface block, and pointer to copy of the pointer. - Implementation must set *I1 if it succeeds to get a drawing context.</td> - </tr> -<tr> - <td><code>release_dc(I,I1)</code></td> - - <td>Release drawing context.</td> - - <td>Pointer to interface block, and pointer to copy of the pointer. - Implementation must reset *I1 if it succeeds to release the drawing context.</td> - </tr> -<tr> - <td><code>erase(I,c)</code></td> - - <td>Erase entire window.</td> - - <td>Background color.</td> - </tr> -<tr> - <td><code>beg_path(I)</code></td> - - <td>Begin path construction.</td> - - <td></td> - </tr> -<tr> - <td><code>end_path(I)</code></td> - - <td>End path construction.</td> - - <td></td> - </tr> -<tr> - <td><code>moveto(I,x,y)</code></td> - - <td>Set current point.</td> - - <td>A point in window coordinates.</td> - </tr> -<tr> - <td><code>lineto(I,x,y)</code></td> - - <td>Line from current point to specified point.</td> - - <td>A point in window coordinates.</td> - </tr> -<tr> - <td><code>curveto(I,x0,y0,x1,y1,x2,y2)</code></td> - - <td>Curve from current point with specified poles to specified point.</td> - - <td>3 points in window coordinates.</td> - </tr> -<tr> - <td><code>closepath(I)</code></td> - - <td>Close the path.</td> - - <td></td> - </tr> -<tr> - <td><code>circle(I,x,y,r)</code></td> - - <td>Circle.</td> - - <td>Center and radius, window coordinates.</td> - </tr> -<tr> - <td><code>round(I,x,y,r)</code></td> - - <td>Filled circle.</td> - - <td>Center and radius, window coordinates.</td> - </tr> -<tr> - <td><code>fill(I)</code></td> - - <td>Fill the path.</td> - - <td></td> - </tr> -<tr> - <td><code>stroke(I)</code></td> - - <td>Stroke the path.</td> - - <td></td> - </tr> -<tr> - <td><code>setcolor(I,c)</code></td> - - <td>Set color.</td> - - <td>An integer, consisting of red, green, blue bytes.</td> - </tr> -<tr> - <td><code>setlinewidth(I,w)</code></td> - - <td>Set line width.</td> - - <td>Line width in pixels.</td> - </tr> -<tr> - <td><code>text(I,x,y,s)</code></td> - - <td>Draw a text.</td> - - <td>Coodrinates in pixels, and a string.</td> - </tr> -<tr> - <td><code>wait(I)</code></td> - - <td>Delay execution untill resume command is inputted from user.</td> - - <td></td> - </tr> -</table> - -<p> -<hr> - -<h2><a name="Full_example"></a>A full example</h2> - -<p> -The file <code>gslib.c</code> in the Ghostscript fileset is a complete -example program that initializes the library and produces output using it; -files named <code>*lib.mak</code> (such as <code>ugcclib.mak</code> -and <code>bclib.mak</code>) are makefiles using <code>gslib.c</code> -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 <code>gx.h</code> 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 <code>gx.h</code>. - -<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. <code>pgs</code> 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 © 2000-2022 Artifex Software, Inc. 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 that -license. Refer to licensing information at <a href="https://www.artifex.com">https://www.artifex.com</a> -or contact Artifex Software, Inc., 1305 Grant Avenue - Suite 200, -Novato, CA 94945, U.S.A., +1(415)492-9861, for further information. - -<p> -<small>Ghostscript version 9.56.0, 29 March 2022 - -<!-- [3.0 end visible trailer] ============================================= --> - - - -<!--FINISH EDITING HERE--> - </div><!-- close inner --> - </div><!-- close outer --> - </article> - </main> - <script src="site.js"></script> -</body> -</html> |