| 1 | Copyright (C) 1989 Aladdin Enterprises. All rights reserved. |
| 2 | Distributed by Free Software Foundation, Inc. |
| 3 | |
| 4 | This file is part of Ghostscript. |
| 5 | |
| 6 | Ghostscript is distributed in the hope that it will be useful, but |
| 7 | WITHOUT ANY WARRANTY. No author or distributor accepts responsibility |
| 8 | to anyone for the consequences of using it or for whether it serves any |
| 9 | particular purpose or works at all, unless he says so in writing. Refer |
| 10 | to the Ghostscript General Public License for full details. |
| 11 | |
| 12 | Everyone is granted permission to copy, modify and redistribute |
| 13 | Ghostscript, but only under the conditions described in the Ghostscript |
| 14 | General Public License. A copy of this license is supposed to have been |
| 15 | given to you along with Ghostscript so you can know your rights and |
| 16 | responsibilities. It should be in a file named COPYING. Among other |
| 17 | things, the copyright notice and this notice must be preserved on all |
| 18 | copies. |
| 19 | |
| 20 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
| 21 | |
| 22 | This file, lib.doc, describes the Ghostscript library, a collection of C |
| 23 | procedures that implement the primitive graphic operations of the |
| 24 | Ghostscript language. |
| 25 | |
| 26 | For an overview of Ghostscript and a list of the documentation files, see |
| 27 | README. |
| 28 | |
| 29 | ******** |
| 30 | ******** The Ghostscript library ******** |
| 31 | ******** |
| 32 | |
| 33 | Ghostscript is actually two programs: a language interpreter, and a |
| 34 | graphics library. The library provides, in the form of C procedures, all |
| 35 | the graphics functions of the language, i.e., approximately those |
| 36 | facilities listed in section 6.2 of the PostScript manual starting with |
| 37 | the graphics state operators. In addition, the library provides some |
| 38 | lower-level graphics facilities that offer higher performance in exchange |
| 39 | for less generality. |
| 40 | |
| 41 | To be specific, the highest level of the library implements all the |
| 42 | operators in the "graphics state", "coordinate system and matrix", "path |
| 43 | construction", "painting", "character and font", and "font cache" sections |
| 44 | of the PostScript manual, with the following deliberate exceptions: |
| 45 | settransfer, currenttransfer |
| 46 | definefont, findfont |
| 47 | FontDirectory, StandardEncoding |
| 48 | The following "device" operators are implemented: |
| 49 | showpage (synchronizes the display) |
| 50 | nulldevice |
| 51 | |
| 52 | There are slight differences in the operators that return multiple values, |
| 53 | since C's provisions for this are awkward. Also, the control structure |
| 54 | for the operators involving (an) auxiliary procedure(s) (setscreen, |
| 55 | pathforall, image, imagemask) is partly inverted: the client calls a |
| 56 | procedure to set up an enumerator object, and then calls another procedure |
| 57 | for each iteration. The ...show operators, charpath, and stringwidth |
| 58 | also use an inverted control structure. |
| 59 | |
| 60 | Files named gs*.c implement the higher level of the graphics library. |
| 61 | To use the facilities of gs?.c, a client program should include |
| 62 | gs?.h. As might be expected, all procedures, variables, and |
| 63 | structures available at this level begin with gs_. Structures that |
| 64 | appear in these interfaces, but whose definitions may be hidden from |
| 65 | clients, also have names beginning with gs_, i.e., the prefix |
| 66 | reflects at what level the abstraction is made available, not the |
| 67 | implementation. |
| 68 | |
| 69 | Files named gx*.c implement the lower level of the graphics library. |
| 70 | To use the facilities of gx?.c, a client program should include |
| 71 | gx?.h. The interfaces at the gx level are less stable, and expose |
| 72 | more of the implementation detail, than those at the gs level: in |
| 73 | particular, the gx interfaces generally use device coordinates in an |
| 74 | internal fixed-point representation, as opposed to the gs interfaces |
| 75 | that use floating point user coordinates. Named entities at this |
| 76 | level begin with gx_. |
| 77 | |
| 78 | Files named gz*.c and gz*.h are internal to the Ghostscript |
| 79 | implementation, and not designed to be called by clients. |