lib.htm

GhostScript的源代码

	<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 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.

<h2><a name="Patterns"></a>Patterns</h2>

<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>&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 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&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 that
would be presented to the <b><tt>PaintProc</tt></b> in PostScript.
Currently the <b><tt>gs_client_color&nbsp;*</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&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 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>

<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 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>

<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 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 &lt;stdio.h&gt;
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(&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> 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, &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 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>

<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") for
full details of the terms of using, copying, modifying, and redistributing
Aladdin Ghostscript.

<p>
Ghostscript version 5.50, 16 September 1998

</font>

<!-- [3.0 end visible trailer] --------------------------------------------- -->

</body>
</html>