1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<title>Information for Ghostscript developers</title> 5<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 6<!-- $Id: Develop.htm,v 1.47.2.3 2002/02/01 05:31:24 raph Exp $ --> 7</head> 8 9<body> 10<!-- [1.0 begin visible header] ============================================ --> 11 12<!-- [1.1 begin headline] ================================================== --> 13 14<h1>Information for Ghostscript developers</h1> 15 16<!-- [1.1 end headline] ==================================================== --> 17 18<!-- [1.2 begin table of contents] ========================================= --> 19 20<h2>Table of contents</h2> 21 22<blockquote><ul> 23<li><a href="#Introduction">Introduction</a> 24<li><a href="#Architecture">Architecture</a> 25<ul> 26<li><a href="#Design_goals">Design goals</a> 27<li><a href="#Design_principles">Design principles</a> 28<li><a href="#Large_scale_structure">Large-scale structure</a> 29<li><a href="#Object_oriented_constructs">Object-oriented constructs</a> 30</ul> 31<li><a href="#File_roadmap">File roadmap</a> 32<ul> 33<li><a href="#Substrate">Substrate</a> 34<li><a href="#Graphics_library">Graphics library</a> 35<ul> 36<li><a href="#Library_support">Support</a>, 37 <a href="#Paths">Paths</a>, 38 <a href="#Text">Text</a>, 39 <a href="#Images">Images</a>, 40 <a href="#Paint">Paint</a>, 41 <a href="#Clipping">Clipping</a>, 42 <a href="#Other_graphics">Other graphics</a>, 43 <a href="#Driver_support">Driver support</a> 44</ul> 45<li><a href="#Device_drivers">Device drivers</a> 46<ul> 47<li><a href="#Internal_devices">Internal devices</a>, 48 <a href="#PS_and_PDF_writers">PostScript and PDF writers</a>, 49 <a href="#High_level_devices">Other high-level devices</a>, 50 <a href="#Other_maintained_drivers">Other maintained drivers</a>, 51 <a href="#Contributed_drivers">Contributed drivers</a> 52</ul> 53<li><a href="#PostScript_interpreter">PostScript interpreter</a> 54<ul> 55<li><a href="#Main_program">Main program</a>, 56 <a href="#Data_structures">Data structures</a>, 57 <a href="#Interpreter_loop">Interpreter loop</a>, 58 <a href="#Scanning_parsing">Scanning/parsing</a>, 59 <a href="#Standard_operators">Standard operators</a>, 60 <a href="#Non_standard_operators">Non-standard operators</a>, 61 <a href="#Interpreter_support">Interpreter support</a>, 62 <a href="#PostScript_code">PostScript code</a> 63</ul> 64<li><a href="#PDF_interpreter">PDF interpreter</a> 65<li><a href="#Build_process">Build process</a> 66<ul> 67<li><a href="#Makefile_structure">Makefile structure</a>, 68 <a href="#dev_files">.dev files</a>, 69 <a href="#Generators">Generators</a>, 70 <a href="#Build_support">Support</a> 71</ul> 72<li><a href="#Utilities">Utilities</a> 73<ul> 74<li><a href="#Utilities_in_PostScript">Utilities in PostScript</a> 75<li><a href="#Utility_scripts">Utility scripts</a> 76</ul> 77</ul> 78<li><a href="#Memory_management">Memory management</a> 79<ul> 80<li><a href="#Memory_manager_architecture">Memory manager architecture</a> 81<ul> 82<li><a href="#Objects_vs_strings">Objects vs strings</a>, 83 <a href="#Structure_descriptors">Structure descriptors</a>, 84 <a href="#Garbage_collection">Garbage collection</a>, 85 <a href="#Movability">Movability</a>, 86 <a href="#Parent_hierarchy">Parent hierarchy</a>, 87 <a href="#Allocator_API">Allocator API</a> 88</ul> 89<li><a href="#Freeing_storage">Freeing storage</a> 90<ul> 91<li><a href="#Explicit_freeing">Explicit freeing</a>, 92 <a href="#Reference_counting">Reference counting</a>, 93 <a href="#Real_garbage_collection">(Real) garbage collection</a> 94</ul> 95<li><a href="#Special_implementations">Special implementations</a> 96<ul> 97<li><a href="#malloc">malloc</a>, 98 <a href="#Locking">Locking</a>, 99 <a href="#Retrying">Retrying</a> 100</ul> 101<li><a href="#Standard_implementation">Standard implementation</a> 102<li><a href="#PostScript_interpreter_extensions">PostScript interpreter extensions</a> 103<ul> 104<li><a href="#Refs">Refs (PostScript "objects")</a>, 105 <a href="#save_forgetsave_restore">save/.forgetsave/restore</a>, 106 <a href="#Stable_allocators">Stable allocators</a>, 107 <a href="#Interpreter_GC">Garbage collection</a> 108</ul> 109</ul> 110<li><a href="#Portability">Portability</a> 111<ul> 112<li><a href="#Structural">Structural</a> 113<ul> 114<li><a href="#CPU_and_compiler">CPU and compiler</a>, 115 <a href="#Library_headers">Library headers</a>, 116 <a href="#Cross_platform_APIs">Cross-platform APIs</a>, 117 <a href="#Makefiles">Makefiles</a> 118</ul> 119<li><a href="#Coding">Coding</a> 120<ul> 121<li><a href="#Explicit_dependencies">Explicit dependencies</a>, 122 <a href="#Implicit_dependencies">Implicit dependencies</a> 123</ul> 124<li><a href="#Platform_specific_code">Platform-specific code</a> 125</ul> 126<li><a href="#Adding_features_and_options">Adding features and options</a> 127<li><a href="#Troubleshooting">Troubleshooting</a> 128</ul></blockquote> 129 130<!-- [1.2 end table of contents] =========================================== --> 131 132<!-- [1.3 begin hint] ====================================================== --> 133 134<p>For other information, see the <a href="Readme.htm">Ghostscript 135overview</a> and the documentation related to <a 136href="Maintain.htm">maintaining Ghostscript</a>. 137 138<!-- [1.3 end hint] ======================================================== --> 139 140<hr> 141 142<!-- [1.0 end visible header] ============================================== --> 143 144<!-- [2.0 begin contents] ================================================== --> 145 146<h2><a name="Introduction"></a>Introduction</h2> 147 148<p> 149This document provides a wealth of information about Ghostscript's 150internals, primarily for developers actively working on Ghostscript. It is 151primarily <strong>descriptive</strong>, documenting the way things are; the 152companion <a href="C-style.htm">C style guide</a> is primarily 153<strong>prescriptive</strong>, documenting what developers should do when 154writing new code. 155 156<p> 157THIS FILE IS A WORK IN PROGRESS. MANY SECTIONS ARE PLACE-HOLDERS. 158 159<h2><a name="Architecture"></a>Architecture</h2> 160 161<h3><a name="Design_goals"></a>Design goals</h3> 162 163<p> 164Ghostscript has the following high-level design goals (not listed in order 165of importance): 166 167<ul> 168<li>Functionality 169<ul> 170<li>Ability to interpret the current PostScript and PDF languages, as 171defined (and occasionally, in the case of conflict, as implemented) by 172Adobe. 173<li>Ability to convert PostScript to and from PDF, comparable to 174Adobe products. 175<li>Ability to produce output for a wide range of resolutions (from 176TV-resolution displays to imagesetters) and color models (black and white, 177multilevel gray, bilevel or multi-level RGB and CMYK, 6- or 8-color 178inkjet printers, spot color). 179</ul> 180<li>Performance 181<ul> 182<li>Ability to render PostScript and PDF with commercial-quality performance 183(memory usage, speed, and output quality) on all platforms. 184<li>Specifically, ability to render PostScript effectively in embedded 185environments with constrained RAM, including the ability to put the code and 186supporting data in ROM. 187</ul> 188<li>Licensing 189<ul> 190<li>Licensing that supports both the Open Source / Free software communities 191and a commercial licensing business. 192<li>Freedom from licensing restrictions or fees imposed by third parties. 193</ul> 194<li>Other 195<ul> 196<li>Easy source portability to any platform (CPU, operating system, and 197development tools) that has an ANSI or K&R C compiler. 198<li>Support for writing new interpreters and new drivers with no change to 199any existing code; specifically, ability to support PCL 5e, PCL 5c, and PCL 200XL interpreters, and the ever-changing roster of inkjet printers. 201</ul> 202</ul> 203 204<p> 205These goals often conflict: part of Ghostscript's claim to quality is that 206the conflicts have been resolved well. 207 208<h3><a name="Design_principles"></a>Design principles</h3> 209 210<p> 211Part of what has kept Ghostscript healthy through many years of major code 212revisions and functional expansion is consistent and conscientious adherence 213to a set of design principles. We hope the following list captures the most 214important ones. 215 216<h4>Non-preemption</h4> 217 218<p> 219Ghostscript is designed to be used as a component. As such, it must share 220its environment with other components. Therefore, it must not require 221ownership of, or make decisions about, inherently shared resources. 222Specifically, it must not assume that it can "own" either the locus of 223control or the management of the address space. 224 225<p> 226Not owning control means that whenever Ghostscript passes control to its 227caller, it must do so in a way that doesn't constrain what the caller can do 228next. The caller must be able to call any other piece of software, wait for 229an external event, execute another task, etc., without having to worry about 230Ghostscript being in an unknown state. While this is easy to arrange in a 231multi-threaded environment (by running Ghostscript in a separate thread), 232multi-threading APIs are not well standardized at this time (December 2000), 233and may not be implemented efficiently, or at all, on some platforms. 234Therefore, Ghostscript must choose between only two options for interacting 235with its caller: to <em>return</em>, preserving its own state in data 236structures, or to <em>call back</em> through a caller-supplied procedure. 237Calling back constrains the client program unacceptably: the callback 238procedure only has the options of either returning, or aborting Ghostscript. 239In particular, if it wants (for whatever reason) to multi-task Ghostscript 240with another program, it cannot do so in general, especially if the other 241program also uses callback rather than suspension. Therefore, Ghostscript 242tries extremely hard to return, rather than calling back, for all caller 243interaction. In particular: 244 245<ul> 246 247<li>For callers that want to pass input to Ghostscript piece by piece, 248Ghostscript returns with an <b><tt>e_NeedInput</tt></b> code rather than 249using a callback. This allows the caller complete flexibility in its 250control structure for managing the source of input. (It might, for example, 251be generating the input dynamically.) 252 253<li>In the future, the same arrangement should be used for input from 254<b><tt>stdin</tt></b> and output to <b><tt>stdout</tt></b> and 255<b><tt>stderr</tt></b>. 256 257<li>Likewise, scheduling of Ghostscript's own threads (contexts), currently 258done with a callback, should be done with suspension. The Display 259Ghostscript project (GNU DGS) is working on this. 260 261</ul> 262 263<p> 264The one area where suspension is not feasible with Ghostscript's current 265architecture is device output. Device drivers are called from deep within 266the graphics library. (If Ghostscript were being redesigned from scratch, 267we might try to do this with suspension as well, or at least optional 268suspension.) 269 270<p> 271Not owning management of the address space means that even though 272Ghostscript supports garbage collection for its own data, it must not do any 273of the things that garbage collection schemes for C often require: it must 274not replace 'malloc' and 'free', must not require its clients to use its own 275allocator, must not rely on manipulating the read/write status of memory 276pages, must not require special compiler or run-time support (e.g., APIs for 277scanning the C stack), must not depend on the availability of 278multi-threading, and must not take possession of one of a limited number of 279timer interrupts. However, in order not to constrain its own code unduly, 280it must also not require using special macros or calls to enter or leave 281procedures or assign pointers, and must not constrain the variety of C data 282structures any more than absolutely necessary. It achieves all of these 283goals, at the expense of some complexity, some performance cost (mostly for 284garbage collection), and some extra manual work required for each structure 285type allocated by its allocator. The details appear in the <a 286href="#Memory_management">Memory management</a> section below. 287 288<h4>Multi-instantiability</h4> 289 290<p> 291From many years of experience with the benefits of object-oriented design, 292we have learned that when the word "the" appears in a software design -- 293"the" process scheduler, "the" memory manager, "the" output device, "the" 294interpreter, "the" stack -- it often flags an area in which the software 295will have difficulty adapting to future needs. For this reason, Ghostscript 296attempts to make every internal structure capable of existing in multiple 297instances. For example, Ghostscript's memory manager is not a one-of-a-kind 298entity with global state and procedures: it is (or rather they are, since 299Ghostscript has multiple memory managers, some of which have multiple 300instances) objects with their own state and (virtual) procedures. 301Ghostscript's PostScript interpreter has no writable non-local data 302(necessary, but not sufficient, to allow multiple instances), and in the 303future will be extended to be completely reentrant and instantiable. The 304device driver API is designed to make this easy for drivers as well. The 305graphics library is currently not completely reentrant or instantiable: we 306hope this will occur in the future. 307 308<h4>Late configuration binding</h4> 309 310<p> 311Ghostscript is designed to make configuration choices as late as possible, 312subject to simplicity and performance considerations. The major binding 313times for such choices are compilation, linking, startup, and dynamic. 314 315<ul> 316 317<li>Compilation binds only CPU and compiler characteristics (including data 318type size, presence of floating point hardware, and data alignment), and 319whether the code will be used for production, debugging, or profiling. 320 321<li>Linking binds the choice of what features and device drivers will be 322included in the executable. (Work is underway to make the choice of drivers 323dynamic.) 324 325<li>Startup binds essentially nothing. Almost every option and parameter 326that can appear on the command line can also be changed dynamically. 327 328<li>The selection of output device, all parameters associated with the 329device, the selection of debugging printout and self-checking (in debugging 330configurations), the macro-allocation of memory, and almost all other 331operational parameters are dynamic. 332 333</ul> 334 335<p> 336In addition, a number of major implementation decisions are made dynamically 337depending on the availability of resources. For example, Ghostscript 338chooses between banded and non-banded rendering depending on memory 339availability. 340 341<h3><a name="Large_scale_structure"></a>Large-scale structure</h3> 342 343<p> 344At the largest design scale, Ghostscript consists of 4 layers. Layer N 345is allowed to use the facilities of all layers M <= N. 346 347<ol> 348 349<li>The bottom layer is called the <a href="#Substrate">substrate</a>. It 350includes facilities like memory management, streams, fixed-point arithmetic, 351and low-level interfaces to the operating system. The substrate is written 352in C, with a little C++ and/or assembler code for some platforms. 353 354<li>The layer above the substrate is the graphics layer. It consists of two 355separate sub-parts. The graphics layer is written in C. 356 357<ul> 358 359<li>The <a href="#Graphics_library">graphics library</a> manages graphics 360state information for, and decomposes and renders 2-D images described 361using, a graphics model that is approximately the union of those of 362PostScript, PDF, and PCL 5e/5c/XL. 363 364<li>The <a href="#Device_drivers">device drivers</a> are called by the 365graphics library to produce actual output. The graphics library, and all 366higher layers, call device driver procedures only through virtual functions. 367 368</ul> 369 370<li>The principal clients of the graphics layer are language interpreters. 371Ghostscript as distributed includes the <a 372href="#PostScript_interpreter">PostScript interpreter</a>; there are also 373interpreters for PCL 5e, PCL 5c, and PCL XL, which are not currently freely 374redistributable and are not included in the standard Ghostscript package. 375The PostScript interpreter is written partly in C and partly in PostScript. 376 377<li>The <a href="#PDF_interpreter">PDF interpreter</a> is actually a client 378of the PostScript interpreter: it is written entirely in PostScript. 379 380</ol> 381 382<p> 383The most important interface in Ghostscript is the API between the graphics 384library and the device drivers: new printers (and, to a lesser extent, 385window systems, displays, plotters, film recorders, and graphics file 386formats) come on the scene frequently, and it must be possible to produce 387output for them with a minimum of effort and distruption. This API is the 388only one that is extensively documented (see <a 389href="Drivers.htm">Drivers.htm</a>) and kept stringently backward-compatible 390through successive releases. 391 392<h3><a name="Object_oriented_constructs"></a>Object-oriented constructs</h3> 393 394<p> 395Ghostscript makes heavy use of object-oriented constructs, including 396analogues of classes, instances, subclassing, and class-associated 397procedures. Since Ghostscript is written in C, not C++, implementing these 398constructs requires following coding conventions. The <a 399href="C-style.htm#Objects">"Objects"</a> section of the C style guide 400explains these. 401 402<p> 403The memory manager API provides run-time type information about each class, 404but this information does not include anything about subclassing. See under 405<a href="#Structure_descriptors">Structure descriptors</a> below. 406 407<hr> 408 409<h2><a name="File_roadmap"></a>File roadmap</h2> 410 411<p> 412This section of the document provides a roadmap to all of the Ghostscript 413source files. 414 415<h3><a name="Substrate"></a>Substrate</h3> 416 417<h4>Memory manager</h4> 418 419<p> 420See <a href="#Memory_management">below</a>. 421 422<h4>Streams</h4> 423 424<dl> 425 426<dt> 427Framework, file and string streams: 428<dd> 429<a href="../src/gsdsrc.c">src/gsdsrc.c</a>, 430<a href="../src/gsdsrc.h">src/gsdsrc.h</a>, 431<a href="../src/scommon.h">src/scommon.h</a>, 432<a href="../src/sfxboth.c">src/sfxboth.c</a>, 433<a href="../src/sfxfd.c">src/sfxfd.c</a>, 434<a href="../src/sfxstdio.c">src/sfxstdio.c</a>, 435<a href="../src/stream.h">src/stream.h</a>, 436<a href="../src/stream.c">src/stream.c</a>, 437<a href="../src/strimpl.h">src/strimpl.h</a>. 438 439<dt> 440Standard filters: 441<dd> 442 443<dl> 444 445<dt> 446CCITTFax: 447<dd> 448<a href="../src/scf.h">src/scf.h</a>, 449<a href="../src/scfd.c">src/scfd.c</a>, 450<a href="../src/scfdgen.c">src/scfdgen.c</a>, 451<a href="../src/scfdtab.c">src/scfdtab.c</a>, 452<a href="../src/scfe.c">src/scfe.c</a>, 453<a href="../src/scfetab.c">src/scfetab.c</a>, 454<a href="../src/scfparam.c">src/scfparam.c</a>, 455<a href="../src/scfx.h">src/scfx.h</a>. 456 457<dt> 458DCT (JPEG): 459<dd> 460<a href="../src/gsjconf.h">src/gsjconf.h</a>, 461<a href="../src/gsjmorec.h">src/gsjmorec.h</a>, 462<a href="../src/sdcparam.c">src/sdcparam.c</a>, 463<a href="../src/sdcparam.h">src/sdcparam.h</a>, 464<a href="../src/sdct.h">src/sdct.h</a>, 465<a href="../src/sdctc.c">src/sdctc.c</a>, 466<a href="../src/sdctd.c">src/sdctd.c</a>, 467<a href="../src/sdcte.c">src/sdcte.c</a>, 468<a href="../src/sddparam.c">src/sddparam.c</a>, 469<a href="../src/sdeparam.c">src/sdeparam.c</a>, 470<a href="../src/sjpeg.h">src/sjpeg.h</a>, 471<a href="../src/sjpegc.c">src/sjpegc.c</a>, 472<a href="../src/sjpegd.c">src/sjpegd.c</a>, 473<a href="../src/sjpege.c">src/sjpege.c</a>. 474 475<dt> 476Other compression/decompression: 477<dd> 478<a href="../src/slzwc.c">src/slzwc.c</a>, 479<a href="../src/slzwce.c">src/slzwce.c</a>, 480<a href="../src/slzwd.c">src/slzwd.c</a>, 481<a href="../src/slzwx.h">src/slzwx.h</a>, 482<a href="../src/srld.c">src/srld.c</a>, 483<a href="../src/srle.c">src/srle.c</a>, 484<a href="../src/srlx.h">src/srlx.h</a>. 485 486<dt> 487Other: 488<dd> 489<a href="../src/sa85d.c">src/sa85d.c</a>, 490<a href="../src/sa85d.h">src/sa85d.h</a>, 491<a href="../src/sa85x.h">src/sa85x.h</a>, 492<a href="../src/sfilter1.c">src/sfilter1.c</a>, 493<a href="../src/sfilter2.c">src/sfilter2.c</a>, 494<a href="../src/sstring.c">src/sstring.c</a>, 495<a href="../src/sstring.h">src/sstring.h</a>. 496 497</dl> 498 499<dt> 500Non-standard filters used to implement standard filters: 501<dd> 502<a href="../src/seexec.c">src/seexec.c</a>, 503<a href="../src/sfilter.h">src/sfilter.h</a>, 504<a href="../src/shc.c">src/shc.c</a>, 505<a href="../src/shc.h">src/shc.h</a>, 506<a href="../src/shcgen.c">src/shcgen.c</a>, 507<a href="../src/shcgen.h">src/shcgen.h</a>, 508<a href="../src/spdiff.c">src/spdiff.c</a>, 509<a href="../src/spdiffx.h">src/spdiffx.h</a>, 510<a href="../src/spngp.c">src/spngp.c</a>, 511<a href="../src/spngpx.h">src/spngpx.h</a>, 512<a href="../src/szlibc.c">src/szlibc.c</a>, 513<a href="../src/szlibd.c">src/szlibd.c</a>, 514<a href="../src/szlibe.c">src/szlibe.c</a>, 515<a href="../src/szlibx.h">src/szlibx.h</a>, 516<a href="../src/szlibxx.h">src/szlibxx.h</a>. 517 518<dt> 519Non-standard filters: 520<dd> 521<a href="../src/sbcp.c">src/sbcp.c</a>, 522<a href="../src/sbcp.h">src/sbcp.h</a>, 523<a href="../src/sbhc.c">src/sbhc.c</a>, 524<a href="../src/sbhc.h">src/sbhc.h</a>, 525<a href="../src/sbtx.h">src/sbtx.h</a>, 526<a href="../src/sbwbs.c">src/sbwbs.c</a>, 527<a href="../src/sbwbs.h">src/sbwbs.h</a>, 528<a href="../src/smd5.c">src/smd5.c</a>, 529<a href="../src/smd5.h">src/smd5.h</a>, 530<a href="../src/sarc4.c">src/sarc4.c</a>, 531<a href="../src/sarc4.h">src/sarc4.h</a>, 532<a href="../src/smtf.c">src/smtf.c</a>, 533<a href="../src/smtf.h">src/smtf.h</a>. 534 535<dt> 536Internal filters: 537<dd> 538a<a href="../src/siinterp.c">src/siinterp.c</a>, 539<a href="../src/siinterp.h">src/siinterp.h</a>, 540<a href="../src/siscale.c">src/siscale.c</a>, 541<a href="../src/siscale.h">src/siscale.h</a>, 542<a href="../src/sisparam.h">src/sisparam.h</a>. 543 544<dt> 545Higher-level stream support: 546<dd> 547<a href="../src/spprint.c">src/spprint.c</a>, 548<a href="../src/spprint.h">src/spprint.h</a>, 549<a href="../src/spsdf.c">src/spsdf.c</a>, 550<a href="../src/spsdf.h">src/spsdf.h</a>, 551<a href="../src/srdline.h">src/srdline.h</a>. 552 553</dl> 554 555<h4>Platform-specific code</h4> 556 557See <a href="#Cross_platform_APIs">below</a>. 558 559<h4>Miscellaneous</h4> 560 561<dl> 562 563<dt> 564Library top level: 565<dd> 566<a href="../src/gsinit.c">src/gsinit.c</a>, 567<a href="../src/gslib.h">src/gslib.h</a>. 568 569<dt> 570Configuration-related: 571<dd> 572<a href="../src/gconf.c">src/gconf.c</a>, 573<a href="../src/gconf.h">src/gconf.h</a>, 574<a href="../src/gscdef.c">src/gscdef.c</a>, 575<a href="../src/gscdefs.h">src/gscdefs.h</a>. 576 577<dt> 578Arithmetic: 579<dd> 580<a href="../src/gsfemu.c">src/gsfemu.c</a>, 581<a href="../src/gxarith.h">src/gxarith.h</a>, 582<a href="../src/gxdda.h">src/gxdda.h</a>, 583<a href="../src/gxfarith.h">src/gxfarith.h</a>, 584<a href="../src/gxfixed.h">src/gxfixed.h</a>, 585<a href="../src/gxfrac.h">src/gxfrac.h</a>. 586 587<dt> 588Operating system interface: 589<dd> 590<a href="../src/gserror.h">src/gserror.h</a>, 591<a href="../src/gsexit.h">src/gsexit.h</a>, 592<a href="../src/gxstdio.h">src/gxstdio.h</a>, 593<a href="../src/gxsync.c">src/gxsync.c</a>, 594<a href="../src/gxsync.h">src/gxsync.h</a>. 595 596<dt> 597Other: 598<dd> 599<a href="../src/gsargs.c">src/gsargs.c</a>, 600<a href="../src/gsargs.h">src/gsargs.h</a>, 601<a href="../src/gserrors.h">src/gserrors.h</a>, 602<a href="../src/gsnotify.c">src/gsnotify.c</a>, 603<a href="../src/gsnotify.h">src/gsnotify.h</a>, 604<a href="../src/gsrect.h">src/gsrect.h</a>, 605<a href="../src/gstypes.h">src/gstypes.h</a>, 606<a href="../src/gsuid.h">src/gsuid.h</a>, 607<a href="../src/gsutil.h">src/gsutil.h</a>, 608<a href="../src/gsutil.c">src/gsutil.c</a>, 609<a href="../src/gx.h">src/gx.h</a>, 610<a href="../src/md5.c">src/md5.c</a>, 611<a href="../src/md5.h">src/md5.h</a>. 612 613</dl> 614 615<h3><a name="Graphics_library"></a>Graphics library</h3> 616 617<h4><a name="Library_support"></a>Support</h4> 618 619<dl> 620 621<dt> 622Bitmap processing: 623<dd> 624<a href="../src/gsbitcom.c">src/gsbitcom.c</a>, 625<a href="../src/gsbitmap.h">src/gsbitmap.h</a>, 626<a href="../src/gsbitops.c">src/gsbitops.c</a>, 627<a href="../src/gsbitops.h">src/gsbitops.h</a>, 628<a href="../src/gsbittab.c">src/gsbittab.c</a>, 629<a href="../src/gsbittab.h">src/gsbittab.h</a>, 630<a href="../src/gsflip.c">src/gsflip.c</a>, 631<a href="../src/gsflip.h">src/gsflip.h</a>, 632<a href="../src/gxbitmap.h">src/gxbitmap.h</a>, 633<a href="../src/gxbitops.h">src/gxbitops.h</a>, 634<a href="../src/gxsample.c">src/gxsample.c</a>, 635<a href="../src/gxsample.h">src/gxsample.h</a>. 636 637<dt> 638Functions: 639<dd> 640<a href="../src/gsfunc.c">src/gsfunc.c</a>, 641<a href="../src/gsfunc.h">src/gsfunc.h</a>, 642<a href="../src/gsfunc0.c">src/gsfunc0.c</a>, 643<a href="../src/gsfunc0.h">src/gsfunc0.h</a>, 644<a href="../src/gsfunc3.c">src/gsfunc3.c</a>, 645<a href="../src/gsfunc3.h">src/gsfunc3.h</a>, 646<a href="../src/gsfunc4.c">src/gsfunc4.c</a>, 647<a href="../src/gsfunc4.h">src/gsfunc4.h</a>, 648<a href="../src/gsfuncv.c">src/gsfuncv.c</a>, 649<a href="../src/gsfuncv.h">src/gsfuncv.h</a>, 650<a href="../src/gxfunc.h">src/gxfunc.h</a>. 651 652<dt> 653Parameter lists: 654<dd> 655<a href="../src/gscparam.c">src/gscparam.c</a>, 656<a href="../src/gsparam.c">src/gsparam.c</a>, 657<a href="../src/gsparam.h">src/gsparam.h</a>, 658<a href="../src/gsparam2.c">src/gsparam2.c</a> (not used), 659<a href="../src/gsparams.c">src/gsparams.c</a>, 660<a href="../src/gsparams.h">src/gsparams.h</a>, 661<a href="../src/gsparamx.c">src/gsparamx.c</a>, 662<a href="../src/gsparamx.h">src/gsparamx.h</a>. 663 664<dt> 665I/O-related: 666<dd> 667<a href="../src/gdevpipe.c">src/gdevpipe.c</a>, 668<a href="../src/gsfname.c">src/gsfname.c</a>, 669<a href="../src/gsfname.h">src/gsfname.h</a>, 670<a href="../src/gsio.h">src/gsio.h</a>, 671<a href="../src/gsiodev.c">src/gsiodev.c</a>, 672<a href="../src/gsiodevs.c">src/gsiodevs.c</a>, 673<a href="../src/gxiodev.h">src/gxiodev.h</a>. 674 675</dl> 676 677<h4><a name="Paths"></a>Paths</h4> 678 679<dl> 680 681<dt> 682Coordinate transformation: 683<dd> 684<a href="../src/gscoord.c">src/gscoord.c</a>, 685<a href="../src/gscoord.h">src/gscoord.h</a>, 686<a href="../src/gsmatrix.c">src/gsmatrix.c</a>, 687<a href="../src/gsmatrix.h">src/gsmatrix.h</a>, 688<a href="../src/gxcoord.h">src/gxcoord.h</a>, 689<a href="../src/gxmatrix.h">src/gxmatrix.h</a>. 690 691<dt> 692Path building: 693<dd> 694<a href="../src/gsdps1.c">src/gsdps1.c</a>, 695<a href="../src/gspath.c">src/gspath.c</a>, 696<a href="../src/gspath.h">src/gspath.h</a>, 697<a href="../src/gspath1.c">src/gspath1.c</a>, 698<a href="../src/gspath2.h">src/gspath2.h</a>, 699<a href="../src/gxpath.c">src/gxpath.c</a>, 700<a href="../src/gxpath.h">src/gxpath.h</a>, 701<a href="../src/gxpath2.c">src/gxpath2.c</a>, 702<a href="../src/gxpcopy.c">src/gxpcopy.c</a>, 703<a href="../src/gxpdash.c">src/gxpdash.c</a>, 704<a href="../src/gxpflat.c">src/gxpflat.c</a>, 705<a href="../src/gzpath.h">src/gzpath.h</a>. 706 707<dt> 708Path rendering: 709<dd> 710<a href="../src/gdevddrw.c">src/gdevddrw.c</a>, 711<a href="../src/gsdps1.c">src/gsdps1.c</a>, 712<a href="../src/gspaint.c">src/gspaint.c</a>, 713<a href="../src/gspaint.h">src/gspaint.h</a>, 714<a href="../src/gspenum.h">src/gspenum.h</a>, 715<a href="../src/gxfill.c">src/gxfill.c</a>, 716<a href="../src/gxpaint.c">src/gxpaint.c</a>, 717<a href="../src/gxpaint.h">src/gxpaint.h</a>, 718<a href="../src/gxstroke.c">src/gxstroke.c</a>. 719 720<dt> 721Clipping: 722<dd> 723See under <a href="#Clipping">Clipping</a> below. 724 725</dl> 726 727<h4><a name="Text"></a>Text</h4> 728 729<dl> 730 731<dt> 732Fonts, generic: 733<dd> 734<a href="../src/gsfont.c">src/gsfont.c</a>, 735<a href="../src/gsfont.h">src/gsfont.h</a>, 736<a href="../src/gxfont.h">src/gxfont.h</a>. 737 738<dt> 739Fonts, specific FontTypes: 740<dd> 741<a href="../src/gsfcid.c">src/gsfcid.c</a>, 742<a href="../src/gsfcmap.c">src/gsfcmap.c</a>, 743<a href="../src/gsfcmap.h">src/gsfcmap.h</a>, 744<a href="../src/gsfont0.c">src/gsfont0.c</a>, 745<a href="../src/gxcid.h">src/gxcid.h</a>, 746<a href="../src/gxfcid.h">src/gxfcid.h</a>, 747<a href="../src/gxfcmap.h">src/gxfcmap.h</a>, 748<a href="../src/gxfont0.h">src/gxfont0.h</a>, 749<a href="../src/gxfont1.h">src/gxfont1.h</a>, 750<a href="../src/gxfont42.h">src/gxfont42.h</a>, 751<a href="../src/gxftype.h">src/gxftype.h</a>, 752<a href="../src/gxttf.h">src/gxttf.h</a>. 753 754<dt> 755Character rendering + font cache, generic: 756<dd> 757<a href="../src/gsccode.h">src/gsccode.h</a>, 758<a href="../src/gschar.c">src/gschar.c</a>, 759<a href="../src/gschar.h">src/gschar.h</a>, 760<a href="../src/gscpm.h">src/gscpm.h</a>, 761<a href="../src/gstext.c">src/gstext.c</a>, 762<a href="../src/gstext.h">src/gstext.h</a>, 763<a href="../src/gxbcache.c">src/gxbcache.c</a>, 764<a href="../src/gxbcache.h">src/gxbcache.h</a>, 765<a href="../src/gxccache.c">src/gxccache.c</a>, 766<a href="../src/gxccman.c">src/gxccman.c</a>, 767<a href="../src/gxchar.c">src/gxchar.c</a>, 768<a href="../src/gxchar.h">src/gxchar.h</a>, 769<a href="../src/gxfcache.h">src/gxfcache.h</a>, 770<a href="../src/gxtext.h">src/gxtext.h</a>. 771 772<dt> 773Character rendering, specific FontTypes: 774<dd> 775<a href="../src/gschar0.c">src/gschar0.c</a>, 776<a href="../src/gscrypt1.c">src/gscrypt1.c</a>, 777<a href="../src/gscrypt1.h">src/gscrypt1.h</a>, 778<a href="../src/gstype1.c">src/gstype1.c</a>, 779<a href="../src/gstype1.h">src/gstype1.h</a>, 780<a href="../src/gstype2.c">src/gstype2.c</a>, 781<a href="../src/gstype42.c">src/gstype42.c</a>, 782<a href="../src/gxchrout.c">src/gxchrout.c</a>, 783<a href="../src/gxchrout.h">src/gxchrout.h</a>, 784<a href="../src/gxhint1.c">src/gxhint1.c</a>, 785<a href="../src/gxhint2.c">src/gxhint2.c</a>, 786<a href="../src/gxhint3.c">src/gxhint3.c</a>, 787<a href="../src/gxop1.h">src/gxop1.h</a>, 788<a href="../src/gxtype1.c">src/gxtype1.c</a>, 789<a href="../src/gxtype1.h">src/gxtype1.h</a>. 790 791</dl> 792 793<h4><a name="Images"></a>Images</h4> 794 795<dl> 796 797<dt> 798Buffered API (mostly for PostScript interpreter): 799<dd> 800<a href="../src/gsimage.c">src/gsimage.c</a>, 801<a href="../src/gsimage.h">src/gsimage.h</a>. 802 803<dt> 804Generic support: 805<dd> 806<a href="../src/gsiparam.h">src/gsiparam.h</a>, 807<a href="../src/gxiclass.h">src/gxiclass.h</a>, 808<a href="../src/gximage.c">src/gximage.c</a>, 809<a href="../src/gximage.h">src/gximage.h</a>, 810<a href="../src/gxiparam.h">src/gxiparam.h</a>. 811 812<dt> 813Type 1 and 4 images: 814<dd> 815 816<dl> 817 818<dt> 819Setup: 820<dd> 821<a href="../src/gsiparm4.h">src/gsiparm4.h</a>, 822<a href="../src/gximage1.c">src/gximage1.c</a>, 823<a href="../src/gximage4.c">src/gximage4.c</a>. 824 825<dt> 826Rendering: 827<dd> 828<a href="../src/gxi12bit.c">src/gxi12bit.c</a>, 829<a href="../src/gxicolor.c">src/gxicolor.c</a>, 830<a href="../src/gxidata.c">src/gxidata.c</a>, 831<a href="../src/gxifast.c">src/gxifast.c</a>, 832<a href="../src/gximono.c">src/gximono.c</a>, 833<a href="../src/gxino12b.c">src/gxino12b.c</a>, 834<a href="../src/gxipixel.c">src/gxipixel.c</a>, 835<a href="../src/gxiscale.c">src/gxiscale.c</a>. 836 837</dl> 838 839<dt> 840Type 2 images (Display PostScript): 841<dd> 842<a href="../src/gsiparm2.h">src/gsiparm2.h</a>, 843<a href="../src/gximage2.c">src/gximage2.c</a>. 844 845<dt> 846Type 3 images: 847<dd> 848<a href="../src/gsipar3x.h">src/gsipar3x.h</a>, 849<a href="../src/gsiparm3.h">src/gsiparm3.h</a>, 850<a href="../src/gximag3x.c">src/gximag3x.c</a>, 851<a href="../src/gximag3x.h">src/gximag3x.h</a>, 852<a href="../src/gximage3.c">src/gximage3.c</a>, 853<a href="../src/gximage3.h">src/gximage3.h</a>. 854 855<dt> 856Other: 857<dd> 858<a href="../src/gsimpath.c">src/gsimpath.c</a>. 859 860</dl> 861 862<h4><a name="Paint"></a>Paint</h4> 863 864<p> 865Ghostscript uses 4 internal representations of color. We list them here in 866the order in which they occur in the rendering pipeline. 867 868<ol> 869 870<li>Clients of the graphics library normally specify colors using the 871<em>client color</em> structure (<b><tt>gs_client_color</tt></b>, defined in 872<a href="../src/gsccolor.h">src/gsccolor.h</a>), consisting of one or more 873numeric values and/or a pointer to a Pattern instance. This corresponds 874directly to the values that would be passed to the PostScript 875<b><tt>setcolor</tt></b> operator: one or more (floating-point) numeric 876components and/or a Pattern. Client colors are interpreted relative to a 877color space (<b><tt>gs_color_space</tt></b>, defined in <a 878href="../src/gscspace.h">src/gscspace.h</a> and <a 879href="../src/gxcspace.h">src/gxcspace.h</a>, with specific color spaces 880defined in other files). Client colors do not explicitly reference the 881color space in which they are are interpreted: <b><tt>setcolor</tt></b> uses 882the color space in the graphics state, while images and shadings explicitly 883specify the color space to be used. 884 885<li>For ordinary non-Pattern colors, the first step in color rendering 886reduces a client color to a <em>concrete</em> color -- a set of values in a 887color space that corresponds to the device's color model (except for 888possible conversions between DeviceGray, DeviceRGB, and DeviceCMYK), 889together with an identification of the associated color space. (The 890confusion here between color spaces and color models will have to be cleaned 891up when we implement native Separation/DeviceN colors.) Concrete colors are 892like the numeric values in a client color, except that they are represented 893by arrays of <b><tt>frac</tt></b> values (defined in <a 894href="../src/gxfrac.h">src/gxfrac.h</a>) rather than floats. The procedure 895for this step is the virtual <b><tt>concretize_color</tt></b> and 896<b><tt>concrete_space</tt></b> procedures in the (original) color space. 897This step reduces Indexed colors, CIEBased colors, and Separation and 898DeviceN colors that use the alternate space. 899 900<li>The final step requires mapping a concrete color to the device's color 901model, done by procedures in <a href="../src/gxcmap.c">src/gxcmap.c</a>. 902These procedures combine the following three conceptual sub-steps: 903 904<ul> 905 906<li>A possible mapping between Device color spaces, possibly involving black 907generation and undercolor removal. The non-trivial cases are implemented in 908<a href="../src/gxdcconv.c">src/gxdcconv.c</a>. 909 910<li>Application of the transfer function(s) (done in-line). 911 912<li>Halftoning if necessary: see below. 913 914</ul> 915 916The result is called (inappropriately) a <em>device color</em> 917(<b><tt>gx_device_color</tt></b>, defined in <a 918href="../src/gsdcolor.h">src/gsdcolor.h</a> and <a 919href="../src/gxdcolor.h">src/gxdcolor.h</a>). For ordinary non-Pattern 920colors, a device color is either a pure color, or a halftone. The device 921and color model associated with a device color are implicit. The procedure 922for this step is the virtual <b><tt>remap_concrete_color</tt></b> procedure 923in the color space. 924 925<li>The pure colors that underlie a device color are opaque <em>pixel 926values</em> defined by the device (misnamed <b><tt>gx_color_index</tt></b>, 927defined in <a href="../src/gscindex.h">src/gscindex.h</a>). The device with 928which they are associated is implicit. Although the format and 929interpretation of a pixel value are known only to the device, the device's 930color model and color representation capabilities are public, defined by a 931<b><tt>gx_color_info</tt></b> structure stored in the device (defined in <a 932href="../src/gxdevcli.h">src/gxdevcli.h</a>). Virtual procedures of the 933device driver map between pixel values and RGB or CMYK. (This area is 934untidy and will need to be cleaned up when we implement native 935Separation/DeviceN colors.) 936 937</ol> 938 939<p> 940Steps 2 and 3 are normally combined into a single step for efficiency, as 941the <b><tt>remap_color</tt></b> virtual procedure in a color space. 942 943<p> 944Using a device color to actually paint pixels requires a further step called 945<em>color loading</em>, implemented by the <b><tt>load</tt></b> virtual 946procedure in the device color. This does nothing for pure colors, but loads 947the caches for halftones and Patterns. 948 949<p> 950All of the above steps -- concretizing, mapping to a device color, and color 951loading -- are done as late as possible, normally not until the color is 952actually needed for painting. 953 954<p> 955All painting operations (fill, stroke, imagemask/show) eventually call a 956virtual procedure in the device color, either <b><tt>fill_rectangle</tt></b> 957or <b><tt>fill_mask</tt></b> to actually paint pixels. For rectangle fills, 958pure colors call the device's <b><tt>fill_rectangle</tt></b> procedure; 959halftones and tiled Patterns call the device's 960<b><tt>tile_rectangle</tt></b>; shaded Patterns, and painting operations 961that involve a RasterOp, do something more complicated. 962 963<dl> 964 965<dt> 966Color specification: 967<dd> 968<a href="../src/gsccolor.h">src/gsccolor.h</a>, 969<a href="../src/gscolor.c">src/gscolor.c</a>, 970<a href="../src/gscolor.h">src/gscolor.h</a>, 971<a href="../src/gscolor1.c">src/gscolor1.c</a>, 972<a href="../src/gscolor1.h">src/gscolor1.h</a>, 973<a href="../src/gscolor2.c">src/gscolor2.c</a>, 974<a href="../src/gscolor2.h">src/gscolor2.h</a>, 975<a href="../src/gscolor3.c">src/gscolor3.c</a>, 976<a href="../src/gscolor3.h">src/gscolor3.h</a>, 977<a href="../src/gshsb.c">src/gshsb.c</a>, 978<a href="../src/gshsb.h">src/gshsb.h</a>, 979<a href="../src/gxcolor2.h">src/gxcolor2.h</a>, 980<a href="../src/gxcvalue.h">src/gxcvalue.h</a>. 981 982<dt> 983Color spaces: 984<dd> 985<a href="../src/gscdevn.c">src/gscdevn.c</a>, 986<a href="../src/gscdevn.h">src/gscdevn.h</a>, 987<a href="../src/gscie.c">src/gscie.c</a>, 988<a href="../src/gscie.h">src/gscie.h</a>, 989<a href="../src/gscpixel.c">src/gscpixel.c</a>, 990<a href="../src/gscpixel.h">src/gscpixel.h</a>, 991<a href="../src/gscscie.c">src/gscscie.c</a>, 992<a href="../src/gscsepnm.h">src/gscsepnm.h</a>, 993<a href="../src/gscsepr.c">src/gscsepr.c</a>, 994<a href="../src/gscsepr.h">src/gscsepr.h</a>, 995<a href="../src/gscspace.c">src/gscspace.c</a>, 996<a href="../src/gscspace.h">src/gscspace.h</a>, 997<a href="../src/gscssub.c">src/gscssub.c</a>, 998<a href="../src/gscssub.h">src/gscssub.h</a>, 999<a href="../src/gxcdevn.h">src/gxcdevn.h</a>, 1000<a href="../src/gxcie.h">src/gxcie.h</a>, 1001<a href="../src/gxcspace.h">src/gxcspace.h</a>. 1002 1003<dt> 1004Color mapping: 1005<dd> 1006<a href="../src/gsciemap.c">src/gsciemap.c</a>, 1007<a href="../src/gscindex.h">src/gscindex.h</a>, 1008<a href="../src/gscrd.c">src/gscrd.c</a>, 1009<a href="../src/gscrd.h">src/gscrd.h</a>, 1010<a href="../src/gscrdp.c">src/gscrdp.c</a>, 1011<a href="../src/gscrdp.h">src/gscrdp.h</a>, 1012<a href="../src/gscsel.h">src/gscsel.h</a>, 1013<a href="../src/gsdcolor.h">src/gsdcolor.h</a>, 1014<a href="../src/gxcindex.h">src/gxcindex.h</a>, 1015<a href="../src/gxcmap.c">src/gxcmap.c</a>, 1016<a href="../src/gxcmap.h">src/gxcmap.h</a>, 1017<a href="../src/gxctable.c">src/gxctable.c</a>, 1018<a href="../src/gxctable.h">src/gxctable.h</a>, 1019<a href="../src/gxdcconv.c">src/gxdcconv.c</a>, 1020<a href="../src/gxdcconv.h">src/gxdcconv.h</a>, 1021<a href="../src/gxdcolor.c">src/gxdcolor.c</a>, 1022<a href="../src/gxdcolor.h">src/gxdcolor.h</a>, 1023<a href="../src/gxdither.c">src/gxdither.c</a>, 1024<a href="../src/gxdither.h">src/gxdither.h</a>, 1025<a href="../src/gxfmap.h">src/gxfmap.h</a>, 1026<a href="../src/gxlum.h">src/gxlum.h</a>, 1027<a href="../src/gxtmap.h">src/gxtmap.h</a>. 1028 1029<p> 1030ICC profiles are in some ways a special case of color mapping, but are 1031not standard in PostScript. 1032 1033<dt> 1034Color mapping: 1035<dd> 1036<a href="../src/gsicc.c">src/gsicc.c</a>, 1037<a href="../src/gsicc.h">src/gsicc.h</a>, 1038 1039</dl> 1040 1041<p> 1042Ghostscript represents halftones internally by "whitening orders" -- 1043essentially, arrays of arrays of bit coordinates within a halftone cell, 1044specifying which bits are inverted to get from halftone level K to level 1045K+1. The code does support all of the PostScript halftone types, but they 1046are all ultimately reduced to whitening orders. 1047 1048<p> 1049Threshold arrays, the more conventional representation of halftones, can be 1050mapped to whitening orders straightforwardly; however, whitening orders can 1051represent non-monotonic halftones (halftones where the bits turned on for 1052level K+1 don't necessarily include all the bits turned on for level K), 1053while threshold arrays cannot. On the other hand, threshold arrays allow 1054rapid conversion of images (using a threshold comparison for each pixel) 1055with no additional space, while whitening orders do not: they require 1056storing the rendered halftone cell for each possible level as a bitmap. 1057 1058<p> 1059Ghostscript uses two distinct types of rendered halftones -- that is, the 1060bitmap(s) that represent a particular level. 1061 1062<ul> 1063 1064<li>Binary halftones. The rendered halftone is a single bit plane; each bit 1065selects one of two pure colors. These are fast but limited: they are used 1066for monochrome output devices, or for color devices in those cases where 1067only two distinct colors are involved in a halftone (e.g., a pure cyan shade 1068on a CMYK device). The device color for a binary halftone stores a pointer 1069to the halftone bitmap, and the two pure colors. 1070 1071<li>Multi-plane halftones. Internally, each plane is rendered individually. 1072Since there isn't enough room to store all 2^N pure colors, multi-plane 1073halftones only store the scaled values for the individual components; the 1074halftone renderer maps these to the pure colors on the fly, then combines 1075the planes to assemble an N-bit index into the list of colors for each 1076pixel, and stores the color into the fully rendered halftone. 1077 1078</ul> 1079 1080<p> 1081The halftone level for rendering a color is computed in <a 1082href="../src/gxdither.c">src/gxdither.c</a>; the actual halftone mask or 1083tile is computed either in <a href="../src/gxcht.c">src/gxcht.c</a> (for 1084multi-plane halftones), or in <a href="../src/gxht.c">src/gxht.c</a> and <a 1085href="../src/gxhtbit.c">src/gxhtbit.c</a> (for binary halftones). 1086 1087<dl> 1088 1089<dt> 1090Halftoning: 1091<dd> 1092<a href="../src/gsht.c">src/gsht.c</a>, 1093<a href="../src/gsht.h">src/gsht.h</a>, 1094<a href="../src/gsht1.c">src/gsht1.c</a>, 1095<a href="../src/gsht1.h">src/gsht1.h</a>, 1096<a href="../src/gshtscr.c">src/gshtscr.c</a>, 1097<a href="../src/gshtx.c">src/gshtx.c</a>, 1098<a href="../src/gshtx.h">src/gshtx.h</a>, 1099<a href="../src/gxcht.c">src/gxcht.c</a>, 1100<a href="../src/gxdht.h">src/gxdht.h</a>, 1101<a href="../src/gxdhtres.h">src/gxdhtres.h</a>, 1102<a href="../src/gxht.c">src/gxht.c</a>, 1103<a href="../src/gxht.h">src/gxht.h</a>, 1104<a href="../src/gxhtbit.c">src/gxhtbit.c</a>, 1105<a href="../src/gxhttile.h">src/gxhttile.h</a>, 1106<a href="../src/gxhttype.h">src/gxhttype.h</a>, 1107<a href="../src/gzht.h">src/gzht.h</a>. 1108 1109</dl> 1110 1111<p> 1112Pattern colors (tiled patterns and shadings) each use a slightly different 1113approach from solid colors. 1114 1115<p> 1116The device color for a tiled (PatternType 1) pattern contains a pointer to a 1117pattern instance, plus (for uncolored patterns) the device color to be 1118masked. The pattern instance includes a procedure that actually paints the 1119pattern if the pattern is not in the cache. For the PostScript interpreter, 1120this procedure returns an <b><tt>e_RemapColor</tt></b> exception code: this 1121eventually causes the interpreter to run the pattern's PaintProc, loading 1122the rendering into the cache, and then re-execute the original drawing 1123operator. 1124 1125<dl> 1126 1127<dt> 1128Patterns: 1129<dd> 1130<a href="../src/gspcolor.c">src/gspcolor.c</a>, 1131<a href="../src/gspcolor.h">src/gspcolor.h</a>, 1132<a href="../src/gsptype1.c">src/gsptype1.c</a>, 1133<a href="../src/gsptype1.h">src/gsptype1.h</a>, 1134<a href="../src/gxp1fill.c">src/gxp1fill.c</a>, 1135<a href="../src/gxp1impl.h">src/gxp1impl.h</a>, 1136<a href="../src/gxpcache.h">src/gxpcache.h</a>, 1137<a href="../src/gxpcmap.c">src/gxpcmap.c</a>, 1138<a href="../src/gxpcolor.h">src/gxpcolor.h</a>. 1139 1140</dl> 1141 1142<p> 1143The device color for a shading (PatternType 2) pattern also contains a 1144pointer to a pattern instance. Shadings are not cached: painting with a 1145shading runs the shading algorithm every time. 1146 1147<dl> 1148 1149<dt> 1150Shading: 1151<dd> 1152<a href="../src/gsptype2.c">src/gsptype2.c</a>, 1153<a href="../src/gsptype2.h">src/gsptype2.h</a>, 1154<a href="../src/gsshade.c">src/gsshade.c</a>, 1155<a href="../src/gsshade.h">src/gsshade.h</a>, 1156<a href="../src/gxshade.c">src/gxshade.c</a>, 1157<a href="../src/gxshade.h">src/gxshade.h</a>, 1158<a href="../src/gxshade1.c">src/gxshade1.c</a>, 1159<a href="../src/gxshade4.c">src/gxshade4.c</a>, 1160<a href="../src/gxshade4.h">src/gxshade4.h</a>, 1161<a href="../src/gxshade6.c">src/gxshade6.c</a>. 1162 1163</dl> 1164 1165<p> 1166In addition to the PostScript graphics model, Ghostscript supports RasterOp, 1167a weak form of alpha channel, and eventually the full PDF 1.4 transparency 1168model. The implemention of these facilities is quite slipshod and 1169scattered: only RasterOp is really implemented fully. There is a general 1170compositing architecture, but it is hardly used at all, and in particular is 1171not used for RasterOp. ****** TO BE COMPLETED ****** 1172 1173<dl> 1174 1175<dt> 1176Compositing architecture: 1177<dd> 1178<a href="../src/gscompt.h">src/gscompt.h</a>, 1179<a href="../src/gxcomp.h">src/gxcomp.h</a>. 1180 1181<dt> 1182RasterOp: 1183<dd> 1184<a href="../src/gdevdrop.c">src/gdevdrop.c</a>, 1185<a href="../src/gdevrops.c">src/gdevrops.c</a>, 1186<a href="../src/gsnorop.c">src/gsnorop.c</a>, 1187<a href="../src/gsrop.c">src/gsrop.c</a>, 1188<a href="../src/gsrop.h">src/gsrop.h</a>, 1189<a href="../src/gsropc.c">src/gsropc.c</a>, 1190<a href="../src/gsropc.h">src/gsropc.h</a>, 1191<a href="../src/gsropt.h">src/gsropt.h</a>, 1192<a href="../src/gsroptab.c">src/gsroptab.c</a>, 1193<a href="../src/gxdevrop.h">src/gxdevrop.h</a>, 1194<a href="../src/gxropc.h">src/gxropc.h</a>. 1195 1196<dt> 1197Alpha channel and compositing: 1198<dd> 1199<a href="../src/gsalpha.c">src/gsalpha.c</a>, 1200<a href="../src/gsalpha.h">src/gsalpha.h</a>, 1201<a href="../src/gsalphac.c">src/gsalphac.c</a>, 1202<a href="../src/gsalphac.h">src/gsalphac.h</a>, 1203<a href="../src/gsdpnext.h">src/gsdpnext.h</a>, 1204<a href="../src/gxalpha.h">src/gxalpha.h</a>. 1205 1206<dt> 1207Advanced transparency: 1208<dd> 1209<a href="../src/gstparam.h">src/gstparam.h</a>, 1210<a href="../src/gstrans.c">src/gstrans.c</a>, 1211<a href="../src/gstrans.h">src/gstrans.h</a>, 1212<a href="../src/gxblend.c">src/gxblend.c</a>, 1213<a href="../src/gxblend.h">src/gxblend.h</a>, 1214<a href="../src/gdevp14.c">src/gdevp14.c</a>. 1215<a href="../src/gdevp14.h">src/gdevp14.h</a>. 1216<a href="../src/gdevpnga.c">src/gdevpnga.c</a>. 1217 1218</dl> 1219 1220<h4><a name="Clipping"></a>Clipping</h4> 1221 1222<p> 1223The Ghostscript graphics library implements clipping by inserting a clipping 1224device in the device pipeline. The clipping device modifies all drawing 1225operations to confine them to the clipping region. 1226 1227<p> 1228The library supports three different kinds of clipping: 1229 1230<dl> 1231 1232<dt> 1233Region/path clipping 1234<dd> 1235This corresponds to the PostScript concept of a clipping path. The clipping 1236region is specified either by a list of rectangles (subject to the 1237constraints documented in <a href="../src/gxcpath.h">src/gxcpath.h</a>), or 1238by a path that is converted to such a list of rectangles. 1239 1240<dt> 1241Stationary mask clipping 1242<dd> 1243This corresponds to the mask operand of a PostScript ImageType 3 image. The 1244clipping region is specified by a bitmap and an (X,Y) offset in the 1245coordinate space. 1246 1247<dt> 1248Tiled mask clipping 1249<dd> 1250This corresponds to the region painted by a PostScript Pattern, for the case 1251where the Pattern does not completely cover its bounding box but the 1252combined transformation matrix has no skew or non-orthogonal rotation (i.e., 1253XStep and YStep map respectively to (X,0) and (0,Y) or vice versa). The 1254clipping region is specified by a bitmap and an (X,Y) offset in the 1255coordinate space, and is replicated indefinitely in both X and Y. 1256 1257</dl> 1258 1259<p> 1260Note that simply scan-converting a clipping path in the usual way does not 1261produce a succession of rectangles that can simply be stored as the list for 1262region-based clipping: in general, the rectangles do not satisfy the 1263constraint for rectangle lists specified in <a 1264href="../src/gxcpath.h">src/gxcpath.h</a>, since they may overlap in X, Y, 1265or both. A non-trivial "clipping list accumulator" device is needed to 1266produce a rectangle list that does satisfy the constraint. 1267 1268<dl> 1269 1270<dt> 1271Clipping support: 1272<dd> 1273<a href="../src/gxclip.c">src/gxclip.c</a>, 1274<a href="../src/gxclip.h">src/gxclip.h</a>. 1275 1276<dt> 1277Region/path clipping: 1278<dd> 1279<a href="../src/gxcpath.c">src/gxcpath.c</a>, 1280<a href="../src/gxcpath.h">src/gxcpath.h</a>, 1281<a href="../src/gzcpath.h">src/gzcpath.h</a>. 1282 1283<dt> 1284Clipping list accumulator: 1285<dd> 1286<a href="../src/gxacpath.c">src/gxacpath.c</a>, 1287<a href="../src/gzacpath.h">src/gzacpath.h</a>. 1288 1289<dt> 1290Mask clipping support: 1291<dd> 1292<a href="../src/gxmclip.c">src/gxmclip.c</a>, 1293<a href="../src/gxmclip.h">src/gxmclip.h</a>. 1294 1295<dt> 1296Stationary mask clipping: 1297<dd> 1298<a href="../src/gxclipm.c">src/gxclipm.c</a>, 1299<a href="../src/gxclipm.h">src/gxclipm.h</a>. 1300 1301<dt> 1302Tiled mask clipping: 1303<dd> 1304<a href="../src/gxclip2.c">src/gxclip2.c</a>, 1305<a href="../src/gxclip2.h">src/gxclip2.h</a>. 1306 1307</dl> 1308 1309<h4><a name="Other_graphics"></a>Other graphics</h4> 1310 1311<dl> 1312 1313<dt> 1314Miscellaneous graphics state: 1315<dd> 1316<a href="../src/gsclipsr.c">src/gsclipsr.c</a>, 1317<a href="../src/gsclipsr.h">src/gsclipsr.h</a>, 1318<a href="../src/gsdps.c">src/gsdps.c</a>, 1319<a href="../src/gsdps.h">src/gsdps.h</a>, 1320<a href="../src/gsdps1.c">src/gsdps1.c</a>, 1321<a href="../src/gsistate.c">src/gsistate.c</a>, 1322<a href="../src/gsline.c">src/gsline.c</a>, 1323<a href="../src/gsline.h">src/gsline.h</a>, 1324<a href="../src/gslparam.h">src/gslparam.h</a>, 1325<a href="../src/gsstate.c">src/gsstate.c</a>, 1326<a href="../src/gsstate.h">src/gsstate.h</a>, 1327<a href="../src/gstrap.c">src/gstrap.c</a>, 1328<a href="../src/gstrap.h">src/gstrap.h</a>, 1329<a href="../src/gxclipsr.h">src/gxclipsr.h</a>, 1330<a href="../src/gxistate.h">src/gxistate.h</a>, 1331<a href="../src/gxline.h">src/gxline.h</a>, 1332<a href="../src/gxstate.h">src/gxstate.h</a>, 1333<a href="../src/gzline.h">src/gzline.h</a>, 1334<a href="../src/gzstate.h">src/gzstate.h</a>. 1335 1336</dl> 1337 1338<h4><a name="Driver_support"></a>Driver support</h4> 1339 1340<dl> 1341 1342<dt> 1343Generic driver support: 1344<dd> 1345<a href="../src/gdevdcrd.c">src/gdevdcrd.c</a>, 1346<a href="../src/gdevdcrd.h">src/gdevdcrd.h</a>, 1347<a href="../src/gdevemap.c">src/gdevemap.c</a>, 1348<a href="../src/gsdevice.c">src/gsdevice.c</a>, 1349<a href="../src/gsdevice.h">src/gsdevice.h</a>, 1350<a href="../src/gsdparam.c">src/gsdparam.c</a>, 1351<a href="../src/gsxfont.h">src/gsxfont.h</a>, 1352<a href="../src/gxdevbuf.h">src/gxdevbuf.h</a>, 1353<a href="../src/gxdevcli.h">src/gxdevcli.h</a>, 1354<a href="../src/gxdevice.h">src/gxdevice.h</a>, 1355<a href="../src/gxrplane.h">src/gxrplane.h</a>, 1356<a href="../src/gxxfont.h">src/gxxfont.h</a>. 1357 1358<dt> 1359Accessing rendered bits: 1360<dd> 1361<a href="../src/gdevdbit.c">src/gdevdbit.c</a>, 1362<a href="../src/gdevdgbr.c">src/gdevdgbr.c</a>, 1363<a href="../src/gxbitfmt.h">src/gxbitfmt.h</a>, 1364<a href="../src/gxgetbit.h">src/gxgetbit.h</a>. 1365 1366<dt> 1367"Printer" driver support: 1368<dd> 1369<a href="../src/gdevmeds.c">src/gdevmeds.c</a>, 1370<a href="../src/gdevmeds.h">src/gdevmeds.h</a>, 1371<a href="../src/gdevppla.c">src/gdevppla.c</a>, 1372<a href="../src/gdevppla.h">src/gdevppla.h</a>, 1373<a href="../src/gdevprn.c">src/gdevprn.c</a>, 1374<a href="../src/gdevprn.h">src/gdevprn.h</a>, 1375<a href="../src/gdevprna.c">src/gdevprna.c</a>, 1376<a href="../src/gdevprna.h">src/gdevprna.h</a>, 1377<a href="../src/gxband.h">src/gxband.h</a>, 1378<a href="../src/gxpageq.c">src/gxpageq.c</a>, 1379<a href="../src/gxpageq.h">src/gxpageq.h</a>. 1380 1381<dt> 1382High-level device support: 1383<dd> 1384<a href="../src/gdevvec.c">src/gdevvec.c</a>, 1385<a href="../src/gdevvec.h">src/gdevvec.h</a>. 1386 1387<dt> 1388Banding: 1389<dd> 1390<a href="../src/gxclbits.c">src/gxclbits.c</a>, 1391<a href="../src/gxcldev.h">src/gxcldev.h</a>, 1392<a href="../src/gxclfile.c">src/gxclfile.c</a>, 1393<a href="../src/gxclimag.c">src/gxclimag.c</a>, 1394<a href="../src/gxclio.h">src/gxclio.h</a>, 1395<a href="../src/gxclist.c">src/gxclist.c</a>, 1396<a href="../src/gxclist.h">src/gxclist.h</a>, 1397<a href="../src/gxcllzw.c">src/gxcllzw.c</a>, 1398<a href="../src/gxclmem.c">src/gxclmem.c</a>, 1399<a href="../src/gxclmem.h">src/gxclmem.h</a>, 1400<a href="../src/gxclpage.c">src/gxclpage.c</a>, 1401<a href="../src/gxclpage.h">src/gxclpage.h</a>, 1402<a href="../src/gxclpath.c">src/gxclpath.c</a>, 1403<a href="../src/gxclpath.h">src/gxclpath.h</a>, 1404<a href="../src/gxclrast.c">src/gxclrast.c</a>, 1405<a href="../src/gxclread.c">src/gxclread.c</a>, 1406<a href="../src/gxclrect.c">src/gxclrect.c</a>, 1407<a href="../src/gxclutil.c">src/gxclutil.c</a>, 1408<a href="../src/gxclzlib.c">src/gxclzlib.c</a>. 1409 1410</dl> 1411 1412<h3><a name="Device_drivers"></a>Device drivers</h3> 1413 1414<p> 1415See <a href="Drivers.htm">doc/Drivers.htm</a> for extensive documentation on 1416the interface between the core code and drivers. 1417 1418<p> 1419The driver API includes high-level (path / image / text), mid-level 1420(polygon), and low-level (rectangle / raster) operations. Most devices 1421implement only the low-level operations, and let generic code break down the 1422high-level operations. However, some devices produce high-level output, and 1423therefore must implement the high-level operations. 1424 1425<h4><a name="Internal_devices"></a>Internal devices</h4> 1426 1427<p> 1428There are a number of "devices" that serve internal purposes. Some of these 1429are meant to be real rendering targets; others are intended for use in 1430device pipelines. The rendering targets are: 1431 1432<dl> 1433 1434<dt> 1435Memory devices, depth-independent: 1436<dd> 1437<a href="../src/gdevmem.c">src/gdevmem.c</a>, 1438<a href="../src/gdevmem.h">src/gdevmem.h</a>, 1439<a href="../src/gdevmpla.c">src/gdevmpla.c</a>, 1440<a href="../src/gdevmpla.h">src/gdevmpla.h</a>, 1441<a href="../src/gdevmrop.h">src/gdevmrop.h</a>, 1442<a href="../src/gsdevmem.c">src/gsdevmem.c</a>, 1443<a href="../src/gxdevmem.h">src/gxdevmem.h</a>. 1444 1445<dt> 1446Memory devices, specific depths: 1447<dd> 1448<a href="../src/gdevm1.c">src/gdevm1.c</a>, 1449<a href="../src/gdevm2.c">src/gdevm2.c</a>, 1450<a href="../src/gdevm4.c">src/gdevm4.c</a>, 1451<a href="../src/gdevm8.c">src/gdevm8.c</a>, 1452<a href="../src/gdevm16.c">src/gdevm16.c</a>, 1453<a href="../src/gdevm24.c">src/gdevm24.c</a>, 1454<a href="../src/gdevm32.c">src/gdevm32.c</a>, 1455<a href="../src/gdevmr1.c">src/gdevmr1.c</a>, 1456<a href="../src/gdevmr2n.c">src/gdevmr2n.c</a>, 1457<a href="../src/gdevmr8n.c">src/gdevmr8n.c</a>. 1458 1459<dt> 1460Alpha-related devices: 1461<dd> 1462<a href="../src/gdevabuf.c">src/gdevabuf.c</a>, 1463<a href="../src/gdevalph.c">src/gdevalph.c</a>. 1464 1465<dt> 1466Other devices: 1467<dd> 1468<a href="../src/gdevdflt.c">src/gdevdflt.c</a>, 1469<a href="../src/gdevhit.c">src/gdevhit.c</a>, 1470<a href="../src/gdevht.c">src/gdevht.c</a>, 1471<a href="../src/gdevht.h">src/gdevht.h</a>, 1472<a href="../src/gdevmrun.c">src/gdevmrun.c</a>, 1473<a href="../src/gdevmrun.h">src/gdevmrun.h</a>, 1474<a href="../src/gdevplnx.c">src/gdevplnx.c</a>, 1475<a href="../src/gdevplnx.h">src/gdevplnx.h</a>, 1476 1477</dl> 1478 1479<p> 1480The forwarding devices meant for use in pipelines are: 1481 1482<dl> 1483 1484<dt> 1485The bounding box device: 1486<dd> 1487<a href="../src/gdevbbox.h">src/gdevbbox.h</a>, 1488<a href="../src/gdevbbox.c">src/gdevbbox.c</a>. 1489 1490<dt> 1491Clipping devices: 1492<dd> 1493See under <a href="#Clipping">Clipping</a> above. 1494 1495<dt> 1496Device filter stack: 1497<dd> 1498<a href="../src/gsdfilt.c">src/gsdfilt.c</a>, 1499<a href="../src/gsdfilt.h">src/gsdfilt.h</a>, 1500 1501<dt> 1502Other devices: 1503<dd> 1504<a href="../src/gdevcmap.c">src/gdevcmap.c</a>, 1505<a href="../src/gdevcmap.h">src/gdevcmap.h</a>, 1506<a href="../src/gdevnfwd.c">src/gdevnfwd.c</a>. 1507 1508</dl> 1509 1510<h4><a name="PS_and_PDF_writers"></a>PostScript and PDF writers</h4> 1511 1512<p> 1513Because PostScript and PDF have the same graphics model, lexical syntax, and 1514stack-based execution model, the drivers that produce PostScript and PDF 1515output share a significant amount of support code. In the future, the 1516PostScript output driver should be replaced with a slightly modified version 1517of the PDF driver, since the latter is far more sophisticated (in 1518particular, it has extensive facilities for image compression and for 1519handling text and fonts). 1520 1521<dl> 1522 1523<dt> 1524Shared support: 1525<dd> 1526 1527<dl> 1528Writing fonts: 1529<dd> 1530<a href="../src/gdevpsf.h">src/gdevpsf.h</a>, 1531<a href="../src/gdevpsf1.c">src/gdevpsf1.c</a>, 1532<a href="../src/gdevpsf2.c">src/gdevpsf2.c</a>, 1533<a href="../src/gdevpsfm.c">src/gdevpsfm.c</a>, 1534<a href="../src/gdevpsft.c">src/gdevpsft.c</a>, 1535<a href="../src/gdevpsfu.c">src/gdevpsfu.c</a>, 1536<a href="../src/gdevpsfx.c">src/gdevpsfx.c</a>. 1537 1538<dt> 1539Other: 1540<dd> 1541<a href="../src/gdevpsdf.h">src/gdevpsdf.h</a>, 1542<a href="../src/gdevpsdi.c">src/gdevpsdi.c</a>, 1543<a href="../src/gdevpsdp.c">src/gdevpsdp.c</a>, 1544<a href="../src/gdevpsds.c">src/gdevpsds.c</a>, 1545<a href="../src/gdevpsds.h">src/gdevpsds.h</a>, 1546<a href="../src/gdevpsdu.c">src/gdevpsdu.c</a>. 1547 1548</dl> 1549 1550<dt> 1551PostScript output driver ([e]pswrite): 1552<dd> 1553<a href="../src/gdevps.c">src/gdevps.c</a>, 1554<a href="../src/gdevpsu.c">src/gdevpsu.c</a>, 1555<a href="../src/gdevpsu.h">src/gdevpsu.h</a>. 1556 1557<dt> 1558PDF output driver (pdfwrite): 1559<dd> 1560<dl> 1561 1562<dt> 1563Substrate: 1564<dd> 1565<a href="../src/gdevpdfo.c">src/gdevpdfo.c</a>, 1566<a href="../src/gdevpdfo.h">src/gdevpdfo.h</a>, 1567<a href="../src/gdevpdfr.c">src/gdevpdfr.c</a>, 1568<a href="../src/gdevpdfu.c">src/gdevpdfu.c</a>. 1569 1570<dt> 1571Text and fonts: 1572<dd> 1573<a href="../src/gdevpdfe.c">src/gdevpdfe.c</a>, 1574<a href="../src/gdevpdff.c">src/gdevpdff.c</a>, 1575<a href="../src/gdevpdff.h">src/gdevpdff.h</a>, 1576<a href="../src/gdevpdfs.c">src/gdevpdfs.c</a>, 1577<a href="../src/gdevpdft.c">src/gdevpdft.c</a>, 1578<a href="../src/gdevpdfw.c">src/gdevpdfw.c</a>. 1579 1580<dt> 1581Graphics: 1582<dd> 1583<a href="../src/gdevpdfc.c">src/gdevpdfc.c</a>, 1584<a href="../src/gdevpdfd.c">src/gdevpdfd.c</a>, 1585<a href="../src/gdevpdfg.c">src/gdevpdfg.c</a>, 1586<a href="../src/gdevpdfg.h">src/gdevpdfg.h</a>, 1587<a href="../src/gdevpdfv.c">src/gdevpdfv.c</a>. 1588 1589<dt> 1590Images: 1591<dd> 1592<a href="../src/gdevpdfb.c">src/gdevpdfb.c</a>, 1593<a href="../src/gdevpdfi.c">src/gdevpdfi.c</a>, 1594<a href="../src/gdevpdfj.c">src/gdevpdfj.c</a>. 1595 1596<dt> 1597Other: 1598<dd> 1599<a href="../src/gdevpdf.c">src/gdevpdf.c</a>, 1600<a href="../src/gdevpdfm.c">src/gdevpdfm.c</a>, 1601<a href="../src/gdevpdfp.c">src/gdevpdfp.c</a>, 1602<a href="../src/gdevpdfx.h">src/gdevpdfx.h</a>. 1603 1604</dl> 1605 1606</dl> 1607 1608<h4><a name="High_level_devices"></a>Other high-level devices</h4> 1609 1610<p> 1611Currently, the CGM driver is raster-only. If anyone cares seriously about 1612CGM in the future, this driver should be upgraded to a higher level. 1613 1614<dl> 1615 1616<dt> 1617PCL XL output device (pxlmono, pxlcolor): 1618<dd> 1619<a href="../src/gdevpx.c">src/gdevpx.c</a>, 1620<a href="../src/gdevpxat.h">src/gdevpxat.h</a>, 1621<a href="../src/gdevpxen.h">src/gdevpxen.h</a>, 1622<a href="../src/gdevpxop.h">src/gdevpxop.h</a>, 1623<a href="../src/gdevpxut.c">src/gdevpxut.c</a>, 1624<a href="../src/gdevpxut.h">src/gdevpxut.h</a>. 1625 1626<dt> 1627Other high-level devices: 1628<dd> 1629<a href="../src/gdevtrac.c">src/gdevtrac.c</a>. 1630 1631</dl> 1632 1633<h4><a name="Other_maintained_drivers"></a>Other maintained drivers</h4> 1634 1635<p> 1636The standard Ghostscript distribution includes a collection of drivers, 1637mostly written by Aladdin Enterprises, that are "maintained" in the same 1638sense as the Ghostscript core code. 1639 1640<dl> 1641 1642<dt> 1643Display drivers: 1644<dd> 1645<a href="../src/gdev8bcm.c">src/gdev8bcm.c</a>, 1646<a href="../src/gdev8bcm.h">src/gdev8bcm.h</a>, 1647<a href="../src/gdevegaa.asm">src/gdevegaa.asm</a>, 1648<a href="../src/gdevevga.c">src/gdevevga.c</a>, 1649<a href="../src/gdevl256.c">src/gdevl256.c</a>, 1650<a href="../src/gdevpccm.c">src/gdevpccm.c</a>, 1651<a href="../src/gdevpccm.h">src/gdevpccm.h</a>, 1652<a href="../src/gdevpcfb.c">src/gdevpcfb.c</a>, 1653<a href="../src/gdevpcfb.h">src/gdevpcfb.h</a>, 1654<a href="../src/gdevs3ga.c">src/gdevs3ga.c</a>, 1655<a href="../src/gdevsco.c">src/gdevsco.c</a>, 1656<a href="../src/gdevsvga.c">src/gdevsvga.c</a>, 1657<a href="../src/gdevsvga.h">src/gdevsvga.h</a>, 1658<a href="../src/gdevvglb.c">src/gdevvglb.c</a>. 1659 1660<dt> 1661Window system drivers: 1662<dd> 1663 1664<dl> 1665 1666<dt> 1667X Windows: 1668<dd> 1669<a href="../src/gdevx.c">src/gdevx.c</a>, 1670<a href="../src/gdevx.h">src/gdevx.h</a>, 1671<a href="../src/gdevxalt.c">src/gdevxalt.c</a>, 1672<a href="../src/gdevxcmp.c">src/gdevxcmp.c</a>, 1673<a href="../src/gdevxcmp.h">src/gdevxcmp.h</a>, 1674<a href="../src/gdevxini.c">src/gdevxini.c</a>, 1675<a href="../src/gdevxres.c">src/gdevxres.c</a>, 1676<a href="../src/gdevxxf.c">src/gdevxxf.c</a>. 1677 1678<dt> 1679Microsoft Windows: 1680<dd> 1681<a href="../src/gdevmswn.c">src/gdevmswn.c</a>, 1682<a href="../src/gdevmswn.h">src/gdevmswn.h</a>, 1683<a href="../src/gdevmsxf.c">src/gdevmsxf.c</a>, 1684<a href="../src/gdevwddb.c">src/gdevwddb.c</a>, 1685<a href="../src/gdevwdib.c">src/gdevwdib.c</a>. 1686 1687<dt> 1688OS/2 Presentation Manager: 1689<dd> 1690<a href="../src/gdevpm.c">src/gdevpm.c</a>, 1691<a href="../src/gdevpm.h">src/gdevpm.h</a>, 1692<a href="../src/gspmdrv.c">src/gspmdrv.c</a>, 1693<a href="../src/gspmdrv.h">src/gspmdrv.h</a>. 1694 1695</dl> 1696 1697<dt> 1698Raster file output drivers: 1699<dd> 1700 1701<dl> 1702 1703<dt> 1704Fax and TIFF: 1705<dd> 1706<a href="../src/gdevfax.c">src/gdevfax.c</a>, 1707<a href="../src/gdevfax.h">src/gdevfax.h</a>, 1708<a href="../src/gdevtfax.c">src/gdevtfax.c</a>, 1709<a href="../src/gdevtfax.h">src/gdevtfax.h</a>, 1710<a href="../src/gdevtifs.c">src/gdevtifs.c</a>, 1711<a href="../src/gdevtifs.h">src/gdevtifs.h</a>, 1712<a href="../src/gdevtfnx.c">src/gdevtfnx.c</a>. 1713 1714<dt> 1715(Low-level) CGM: 1716<dd> 1717<a href="../src/gdevcgm.c">src/gdevcgm.c</a>, 1718<a href="../src/gdevcgml.c">src/gdevcgml.c</a>, 1719<a href="../src/gdevcgml.h">src/gdevcgml.h</a>, 1720<a href="../src/gdevcgmx.h">src/gdevcgmx.h</a>. 1721 1722<dt> 1723Other raster file formats: 1724<dd> 1725<a href="../src/gdevbit.c">src/gdevbit.c</a>, 1726<a href="../src/gdevbmp.c">src/gdevbmp.c</a>, 1727<a href="../src/gdevbmp.h">src/gdevbmp.h</a>, 1728<a href="../src/gdevbmpa.c">src/gdevbmpa.c</a>, 1729<a href="../src/gdevbmpc.c">src/gdevbmpc.c</a>, 1730<a href="../src/gdevjpeg.c">src/gdevjpeg.c</a>, 1731<a href="../src/gdevmiff.c">src/gdevmiff.c</a>, 1732<a href="../src/gdevp2up.c">src/gdevp2up.c</a>, 1733<a href="../src/gdevpcx.c">src/gdevpcx.c</a>, 1734<a href="../src/gdevpbm.c">src/gdevpbm.c</a>, 1735<a href="../src/gdevpng.c">src/gdevpng.c</a>, 1736<a href="../src/gdevpsim.c">src/gdevpsim.c</a>. 1737 1738</dl> 1739 1740<dt> 1741Printer drivers: 1742<dd> 1743 1744<dl> 1745 1746<dt> 1747Operating system printer services: 1748<dd> 1749<a href="../src/gdevos2p.c">src/gdevos2p.c</a>, 1750<a href="../src/gdevwpr2.c">src/gdevwpr2.c</a>, 1751<a href="../src/gdevwprn.c">src/gdevwprn.c</a>. 1752 1753<dt> 1754H-P monochrome printers: 1755<dd> 1756<a href="../src/gdevdljm.c">src/gdevdljm.c</a>, 1757<a href="../src/gdevdljm.h">src/gdevdljm.h</a>, 1758<a href="../src/gdevdjet.c">src/gdevdjet.c</a>, 1759<a href="../src/gdevlj56.c">src/gdevlj56.c</a>. 1760 1761<dt> 1762Other printers: 1763<dd> 1764<a href="../src/gdevatx.c">src/gdevatx.c</a>. 1765 1766</dl> 1767 1768</dl> 1769 1770<h4><a name="Contributed_drivers"></a>Contributed drivers</h4> 1771 1772<p> 1773This list is likely to be incomplete and inaccurate: see <a 1774href="../src/contrib.mak">src/contrib.mak</a> for the real one. 1775 1776<dl> 1777 1778<dt> 1779Display and window system drivers: 1780<dd> 1781<a href="../src/gdev3b1.c">src/gdev3b1.c</a>, 1782<a href="../src/gdevherc.c">src/gdevherc.c</a>, 1783<a href="../src/gdevpe.c">src/gdevpe.c</a>, 1784<a href="../src/gdevsnfb.c">src/gdevsnfb.c</a>, 1785<a href="../src/gdevsun.c">src/gdevsun.c</a>. 1786 1787<dt> 1788Raster file output drivers: 1789<dd> 1790<a href="../src/gdevcfax.c">src/gdevcfax.c</a>, 1791<a href="../src/gdevcif.c">src/gdevcif.c</a>, 1792<a href="../src/gdevdfax.c">src/gdevdfax.c</a>, 1793<a href="../src/gdevifno.c">src/gdevifno.c</a>, 1794<a href="../src/gdevmgr.c">src/gdevmgr.c</a>, 1795<a href="../src/gdevmgr.h">src/gdevmgr.h</a>, 1796<a href="../src/gdevsgi.c">src/gdevsgi.c</a>, 1797<a href="../src/gdevsgi.h">src/gdevsgi.h</a>, 1798<a href="../src/gdevsunr.c">src/gdevsunr.c</a>. 1799 1800<dt> 1801Printer drivers: 1802<dd> 1803<a href="../lib/bj8.rpd">lib/bj8.rpd</a>, 1804<a href="../lib/cbjc600.ppd">lib/cbjc600.ppd</a>, 1805<a href="../lib/cbjc800.ppd">lib/cbjc800.ppd</a>, 1806<a href="../src/gdev3852.c">src/gdev3852.c</a>, 1807<a href="../src/gdev4081.c">src/gdev4081.c</a>, 1808<a href="../src/gdev4693.c">src/gdev4693.c</a>, 1809<a href="../src/gdev8510.c">src/gdev8510.c</a>, 1810<a href="../src/gdevadmp.c">src/gdevadmp.c</a>, 1811<a href="../src/gdevbj10.c">src/gdevbj10.c</a>, 1812<a href="../src/gdevbjc.h">src/gdevbjc.h</a>, 1813<a href="../src/gdevbjcl.c">src/gdevbjcl.c</a>, 1814<a href="../src/gdevbjcl.h">src/gdevbjcl.h</a>, 1815<a href="../src/gdevccr.c">src/gdevccr.c</a>, 1816<a href="../src/gdevcdj.c">src/gdevcdj.c</a>, 1817<a href="../src/gdevclj.c">src/gdevclj.c</a>, 1818<a href="../src/gdevcljc.c">src/gdevcljc.c</a>, 1819<a href="../src/gdevcp50.c">src/gdevcp50.c</a>, 1820<a href="../src/gdevcslw.c">src/gdevcslw.c</a>, 1821<a href="../src/gdevdjtc.c">src/gdevdjtc.c</a>, 1822<a href="../src/gdevdm24.c">src/gdevdm24.c</a>, 1823<a href="../src/gdevepsc.c">src/gdevepsc.c</a>, 1824<a href="../src/gdevepsn.c">src/gdevepsn.c</a>, 1825<a href="../src/gdevescp.c">src/gdevescp.c</a>, 1826<a href="../src/gdevhl7x.c">src/gdevhl7x.c</a>, 1827<a href="../src/gdevhpij.c">src/gdevhpij.c</a>, 1828<a href="../src/gdevhpij.h">src/gdevhpij.h</a>, 1829<a href="../src/gdevijs.c">src/gdevijs.c</a>, 1830<a href="../src/gdevimgn.c">src/gdevimgn.c</a>, 1831<a href="../src/gdevl31s.c">src/gdevl31s.c</a>, 1832<a href="../src/gdevlbp8.c">src/gdevlbp8.c</a>, 1833<a href="../src/gdevlp8k.c">src/gdevlp8k.c</a>, 1834<a href="../src/gdevlxm.c">src/gdevlxm.c</a>, 1835<a href="../src/gdevn533.c">src/gdevn533.c</a>, 1836<a href="../src/gdevo182.c">src/gdevo182.c</a>, 1837<a href="../src/gdevokii.c">src/gdevokii.c</a>, 1838<a href="../src/gdevpcl.c">src/gdevpcl.c</a>, 1839<a href="../src/gdevpcl.h">src/gdevpcl.h</a>, 1840<a href="../src/gdevphex.c">src/gdevphex.c</a>, 1841<a href="../src/gdevpjet.c">src/gdevpjet.c</a>, 1842<a href="../src/gdevsj48.c">src/gdevsj48.c</a>, 1843<a href="../src/gdevsppr.c">src/gdevsppr.c</a>, 1844<a href="../src/gdevstc.c">src/gdevstc.c</a>, 1845<a href="../src/gdevstc.h">src/gdevstc.h</a>, 1846<a href="../src/gdevstc1.c">src/gdevstc1.c</a>, 1847<a href="../src/gdevstc2.c">src/gdevstc2.c</a>, 1848<a href="../src/gdevstc3.c">src/gdevstc3.c</a>, 1849<a href="../src/gdevstc4.c">src/gdevstc4.c</a>, 1850<a href="../src/gdevtknk.c">src/gdevtknk.c</a>, 1851<a href="../src/gdevupd.c">src/gdevupd.c</a>. 1852 1853</dl> 1854 1855<h3><a name="PostScript_interpreter"></a>PostScript interpreter</h3> 1856 1857<p> 1858The PostScript interpreter is conceptually simple: in fact, an interpreter 1859that could execute "3 4 add =" and print "7" was running 3 weeks after the 1860first line of Ghostscript code was written. However, a number of 1861considerations make the code large and complex. 1862 1863<p> 1864The interpreter is designed to run in environments with very limited memory. 1865The main consequence of this is that it cannot allocate its stacks 1866(dictionary, execution, operand) as ordinary arrays, since the 1867user-specified stack size limit may be very large. Instead, it allocates 1868them as a linked list of blocks. See below for more details. 1869 1870<p> 1871The interpreter must never cause a C runtime error that it cannot trap. 1872Unfortunately, C implementations almost never provide the ability to trap 1873stack overflow. In order to put a fixed bound on the C stack size, the 1874interpreter never implements PostScript recursion by C recursion. This 1875means that any C code that logically needs to call the interpreter must 1876instead push a continuation (including all necessary state information) on 1877the PostScript execution stack, followed by the PostScript object to be 1878executed, and then <em>return</em> to the interpreter. Unfortunately, since 1879PostScript Level 2 introduces streams whose data source can be a PostScript 1880procedure, any code that reads or writes stream data must be prepared to 1881suspend itself, storing all necessary state in a continuation. There are 1882some places where this is extremely awkward, such as the scanner/parser. 1883 1884<p> 1885The use of continuations affects many places in the interpreter, and even 1886some places in the graphics library. For example, when processing an image, 1887one may need to call a PostScript procedure as part of mapping a CIE color 1888to a device color. Ghostscript uses a variety of dodges to handle this: for 1889example, in the case of CIE color mapping, all of the PostScript procedures 1890are pre-sampled and the results cached. The Adobe implementation limits 1891this kind of recursion to a fixed number of levels (5?): this would be 1892another acceptable approach, but at this point it would require far more 1893code restructuring than it would be worth. 1894 1895<p> 1896A significant amount of the PostScript language implementation is in fact 1897written in PostScript. Writing in PostScript leverages the C code for 1898multi-threading, garbage collection, error handling, continuations for 1899streams, etc., etc.; also, we have found PostScript in general more concise 1900and easier to debug than C, mostly because of memory management issues. So 1901given the choice, we tended to implement a feature in PostScript if it 1902worked primarily with PostScript data structures, wasn't heavily used 1903(example: font loading), or if it interacted with the stream or other 1904callback machinery (examples: ReusableFileDecode streams, resourceforall). 1905Often we would add non-standard PostScript operators for functions that had 1906to run faster or that did more C-like things, such as the media matching 1907algorithm for setpagedevice. 1908 1909</ul> 1910 1911<h4><a name="Main_program"></a>Main program</h4> 1912 1913<p> 1914The main program of the interpreter is normally invoked from the command 1915line, but it has an API as well. In fact, it has two APIs: one that 1916recognizes the existence of multiple "interpreter instances" (although it 1917currently provides a default instance, which almost all clients use), and a 1918completely different one designed for Windows DLLs. These should be unified 1919as soon as possible, since there are two steadily growing incompatible 1920bodies of client code. 1921 1922<dl> 1923 1924<dt> 1925Files: 1926<dd> 1927<a href="../src/gs.c">src/gs.c</a>, 1928<a href="../src/gserver.c">src/gserver.c</a>, 1929<a href="../src/iccinit0.c">src/iccinit0.c</a>, 1930<a href="../src/iinit.c">src/iinit.c</a>, 1931<a href="../src/iinit.h">src/iinit.h</a>, 1932<a href="../src/imain.c">src/imain.c</a>, 1933<a href="../src/imain.h">src/imain.h</a>, 1934<a href="../src/imainarg.c">src/imainarg.c</a>, 1935<a href="../src/imainarg.h">src/imainarg.h</a>, 1936<a href="../src/iminst.h">src/iminst.h</a>, 1937<a href="../src/main.h">src/main.h</a>. 1938 1939</dl> 1940 1941<h4><a name="Data_structures"></a>Data structures</h4> 1942 1943<p> 1944The main data structures visible to the PostScript programmers are arrays, 1945contexts, dictionaries, names, and stacks. 1946 1947<p> 1948Arrays have no unusual properties. See under <a href="#Refs">Refs</a> below 1949for more information about how array elements are stored. 1950 1951<p> 1952Contexts are used to hold the interpreter state even in configurations that 1953don't include the Display PostScript multiple context extension. Context 1954switching is implemented by a complex cooperation of C and PostScript code. 1955 1956<p> 1957Dictionaries have two special properties worth noting: 1958 1959<ul> 1960 1961<li>They use an optimized storage representation if all the keys are names, 1962which is almost always the case. 1963 1964<li>They interact with a caching scheme used to accelerate name lookup in 1965the interpreter. 1966 1967</ul> 1968 1969<p> 1970Names are allocated in blocks. The characters and hash chains are stored 1971separately from the lookup cache information, so that in the future, most of 1972the former can be compiled into the executable and shared or put in ROM. 1973(This is not actually done yet.) 1974 1975<p> 1976As mentioned above, each stack is allocated as a linked list of blocks. 1977However, for reasonable performance, operators must normally be able to 1978access their operands and produce their results using indexing rather than 1979an access procedure. This is implemented by ensuring that all the operands 1980of an operator are in the topmost block of the stack, using guard entries 1981that cause an internal error if the condition isn't met. See <a 1982href="../src/iostack.h">src/iostack.h</a> for more details. 1983 1984<dl> 1985 1986<dt> 1987General data structures: 1988<dd> 1989 1990<dl> 1991 1992<dt> 1993Contexts: 1994<dd> 1995<a href="../src/icontext.c">src/icontext.c</a>, 1996<a href="../src/icontext.h">src/icontext.h</a>, 1997<a href="../src/icstate.h">src/icstate.h</a>. 1998 1999<dt> 2000Dictionaries: 2001<dd> 2002<a href="../src/iddict.h">src/iddict.h</a>, 2003<a href="../src/idict.h">src/idict.h</a>, 2004<a href="../src/idict.c">src/idict.c</a>, 2005<a href="../src/idictdef.h">src/idictdef.h</a>. 2006 2007<dt> 2008Names: 2009<dd> 2010<a href="../src/iname.c">src/iname.c</a>, 2011<a href="../src/iname.h">src/iname.h</a>, 2012<a href="../src/inamedef.h">src/inamedef.h</a>, 2013<a href="../src/inameidx.h">src/inameidx.h</a>, 2014<a href="../src/inames.h">src/inames.h</a>, 2015<a href="../src/inamestr.h">src/inamestr.h</a>. 2016 2017<dt> 2018Stacks: 2019<dd> 2020<a href="../src/isdata.h">src/isdata.h</a>, 2021<a href="../src/istack.c">src/istack.c</a>, 2022<a href="../src/istack.h">src/istack.h</a>, 2023<a href="../src/istkparm.h">src/istkparm.h</a>. 2024 2025</dl> 2026 2027<dt> 2028Specific stacks: 2029<dd> 2030 2031<dl> 2032 2033<dt> 2034Dictionary stack: 2035<dd> 2036<a href="../src/dstack.h">src/dstack.h</a>, 2037<a href="../src/estack.h">src/estack.h</a>, 2038<a href="../src/iddstack.h">src/iddstack.h</a>, 2039<a href="../src/idsdata.h">src/idsdata.h</a>, 2040<a href="../src/idstack.c">src/idstack.c</a>, 2041<a href="../src/idstack.h">src/idstack.h</a>. 2042 2043<dt> 2044Execution stack: 2045<dd> 2046<a href="../src/iesdata.h">src/iesdata.h</a>, 2047<a href="../src/iestack.h">src/iestack.h</a>. 2048 2049<dt> 2050Operand stack: 2051<dd> 2052<a href="../src/iosdata.h">src/iosdata.h</a>, 2053<a href="../src/iostack.h">src/iostack.h</a>, 2054<a href="../src/ostack.h">src/ostack.h</a>. 2055 2056</dl> 2057 2058</dl> 2059 2060<h4><a name="Interpreter_loop"></a>Interpreter loop</h4> 2061 2062<dl> 2063 2064<dt> 2065Files: 2066<dd> 2067<a href="../src/interp.c">src/interp.c</a>, 2068<a href="../src/interp.h">src/interp.h</a>. 2069 2070</dl> 2071 2072<h4><a name="Scanning_parsing"></a>Scanning/parsing</h4> 2073 2074<p> 2075PostScript parsing consists essentially of token scanning, and is simple in 2076principle. The scanner is complex because it must be able to suspend its 2077operation at any time (i.e., between any two input characters) to allow an 2078interpreter callout, if its input is coming from a procedure-based stream 2079and the procedure must be called to provide more input data. 2080 2081<dl> 2082 2083<dt> 2084Main scanner: 2085<dd> 2086<a href="../src/iscan.c">src/iscan.c</a>, 2087<a href="../src/iscan.h">src/iscan.h</a>, 2088<a href="../src/iscannum.c">src/iscannum.c</a>, 2089<a href="../src/iscannum.h">src/iscannum.h</a>, 2090<a href="../src/scanchar.h">src/scanchar.h</a>, 2091<a href="../src/scantab.c">src/scantab.c</a>. 2092 2093<dt> 2094Binary tokens: 2095<dd> 2096<a href="../src/btoken.h">src/btoken.h</a>, 2097<a href="../src/ibnum.c">src/ibnum.c</a>, 2098<a href="../src/ibnum.h">src/ibnum.h</a>, 2099<a href="../src/inobtokn.c">src/inobtokn.c</a>, 2100<a href="../src/iscanbin.c">src/iscanbin.c</a>, 2101<a href="../src/iscanbin.h">src/iscanbin.h</a>. 2102 2103<dt> 2104DSC parsing: 2105<dd> 2106<a href="../src/dscparse.c">src/dscparse.c</a>, 2107<a href="../src/dscparse.h">src/dscparse.h</a>. 2108 2109</dl> 2110 2111<h4><a name="Standard_operators"></a>Standard operators</h4> 2112 2113<dl> 2114 2115<dt> 2116Non-output-related: 2117<dd> 2118 2119<dl> 2120 2121<dt> 2122Filters: 2123<dd> 2124<a href="../src/ifilter.h">src/ifilter.h</a>, 2125<a href="../src/ifilter2.h">src/ifilter2.h</a>, 2126<a href="../src/ifrpred.h">src/ifrpred.h</a>, 2127<a href="../src/ifwpred.h">src/ifwpred.h</a>, 2128<a href="../src/istream.h">src/istream.h</a>, 2129<a href="../src/zfbcp.c">src/zfbcp.c</a>, 2130<a href="../src/zfdctd.c">src/zfdctd.c</a>, 2131<a href="../src/zfdcte.c">src/zfdcte.c</a>, 2132<a href="../src/zfdecode.c">src/zfdecode.c</a>, 2133<a href="../src/zfilter.c">src/zfilter.c</a>, 2134<a href="../src/zfilter2.c">src/zfilter2.c</a>, 2135<a href="../src/zfilterx.c">src/zfilterx.c</a>, 2136<a href="../src/zfmd5.c">src/zfmd5.c</a>, 2137<a href="../src/zfarc4.c">src/zfarc4.c</a>, 2138<a href="../src/zfproc.c">src/zfproc.c</a>, 2139<a href="../src/zfrsd.c">src/zfrsd.c</a>, 2140<a href="../src/zfzlib.c">src/zfzlib.c</a>. 2141 2142<dt> 2143File and stream I/O: 2144<dd> 2145<a href="../src/files.h">src/files.h</a>, 2146<a href="../src/itoken.h">src/itoken.h</a>, 2147<a href="../src/zbseq.c">src/zbseq.c</a>, 2148<a href="../src/zdscpars.c">src/zdscpars.c</a>, 2149<a href="../src/zfile.c">src/zfile.c</a>, 2150<a href="../src/zfileio.c">src/zfileio.c</a>, 2151<a href="../src/ztoken.c">src/ztoken.c</a>. 2152 2153<dt> 2154Data structures: 2155<dd> 2156<a href="../src/zarray.c">src/zarray.c</a>, 2157<a href="../src/zdict.c">src/zdict.c</a>, 2158<a href="../src/zgeneric.c">src/zgeneric.c</a>, 2159<a href="../src/zpacked.c">src/zpacked.c</a>, 2160<a href="../src/zstring.c">src/zstring.c</a>. 2161 2162<dt> 2163Functions: 2164<dd> 2165<a href="../src/ifunc.h">src/ifunc.h</a>, 2166<a href="../src/zfunc.c">src/zfunc.c</a>, 2167<a href="../src/zfunc0.c">src/zfunc0.c</a>, 2168<a href="../src/zfunc3.c">src/zfunc3.c</a>, 2169<a href="../src/zfunc4.c">src/zfunc4.c</a>, 2170 2171<dt> 2172Other: 2173<dd> 2174<a href="../src/ivmem2.h">src/ivmem2.h</a>, 2175<a href="../src/zarith.c">src/zarith.c</a>, 2176<a href="../src/zcontext.c">src/zcontext.c</a>, 2177<a href="../src/zcontrol.c">src/zcontrol.c</a>, 2178<a href="../src/zmath.c">src/zmath.c</a>, 2179<a href="../src/zmatrix.c">src/zmatrix.c</a>, 2180<a href="../src/zmisc.c">src/zmisc.c</a>, 2181<a href="../src/zmisc1.c">src/zmisc1.c</a>, 2182<a href="../src/zmisc2.c">src/zmisc2.c</a>, 2183<a href="../src/zmisc3.c">src/zmisc3.c</a>, 2184<a href="../src/zrelbit.c">src/zrelbit.c</a>, 2185<a href="../src/zstack.c">src/zstack.c</a>, 2186<a href="../src/ztype.c">src/ztype.c</a>, 2187<a href="../src/zusparam.c">src/zusparam.c</a>, 2188<a href="../src/zvmem.c">src/zvmem.c</a>, 2189<a href="../src/zvmem2.c">src/zvmem2.c</a>. 2190 2191</dl> 2192 2193<dt> 2194Output-related: 2195<dd> 2196 2197<dl> 2198 2199<dt> 2200Device management: 2201<dd> 2202<a href="../src/zdevcal.c">src/zdevcal.c</a>, 2203<a href="../src/zdevice.c">src/zdevice.c</a>, 2204<a href="../src/zdevice2.c">src/zdevice2.c</a>, 2205<a href="../src/ziodev.c">src/ziodev.c</a>, 2206<a href="../src/ziodev2.c">src/ziodev2.c</a>, 2207<a href="../src/ziodevs.c">src/ziodevs.c</a>, 2208<a href="../src/ziodevsc.c">src/ziodevsc.c</a>, 2209<a href="../src/zmedia2.c">src/zmedia2.c</a>, 2210<a href="../src/zdfilter.c">src/zdfilter.c</a>. 2211 2212<dt> 2213Fonts and text: 2214<dd> 2215<a href="../src/bfont.h">src/bfont.h</a>, 2216<a href="../src/ccfont.h">src/ccfont.h</a>, 2217<a href="../src/iccfont.c">src/iccfont.c</a>, 2218<a href="../src/icfontab.c">src/icfontab.c</a>, 2219<a href="../src/ichar.h">src/ichar.h</a>, 2220<a href="../src/ichar1.h">src/ichar1.h</a>, 2221<a href="../src/icharout.h">src/icharout.h</a>, 2222<a href="../src/icid.h">src/icid.h</a>, 2223<a href="../src/ifcid.h">src/ifcid.h</a>, 2224<a href="../src/ifont.h">src/ifont.h</a>, 2225<a href="../src/ifont1.h">src/ifont1.h</a>, 2226<a href="../src/ifont2.h">src/ifont2.h</a>, 2227<a href="../src/ifont42.h">src/ifont42.h</a>, 2228<a href="../src/zbfont.c">src/zbfont.c</a>, 2229<a href="../src/zcfont.c">src/zcfont.c</a>, 2230<a href="../src/zchar.c">src/zchar.c</a>, 2231<a href="../src/zchar1.c">src/zchar1.c</a>, 2232<a href="../src/zchar2.c">src/zchar2.c</a>, 2233<a href="../src/zchar32.c">src/zchar32.c</a>, 2234<a href="../src/zchar42.c">src/zchar42.c</a>, 2235<a href="../src/zcharout.c">src/zcharout.c</a>, 2236<a href="../src/zcharx.c">src/zcharx.c</a>, 2237<a href="../src/zcid.c">src/zcid.c</a>, 2238<a href="../src/zfcid.c">src/zfcid.c</a>, 2239<a href="../src/zfcid0.c">src/zfcid0.c</a>, 2240<a href="../src/zfcid1.c">src/zfcid1.c</a>, 2241<a href="../src/zfcmap.c">src/zfcmap.c</a>, 2242<a href="../src/zfont.c">src/zfont.c</a>, 2243<a href="../src/zfont0.c">src/zfont0.c</a>, 2244<a href="../src/zfont1.c">src/zfont1.c</a>, 2245<a href="../src/zfont2.c">src/zfont2.c</a>, 2246<a href="../src/zfont32.c">src/zfont32.c</a>, 2247<a href="../src/zfont42.c">src/zfont42.c</a>. 2248 2249<dt> 2250Color, pattern, and halftone: 2251<dd> 2252<a href="../src/icie.h">src/icie.h</a>, 2253<a href="../src/icolor.h">src/icolor.h</a>, 2254<a href="../src/icremap.h">src/icremap.h</a>, 2255<a href="../src/icsmap.h">src/icsmap.h</a>, 2256<a href="../src/iht.h">src/iht.h</a>, 2257<a href="../src/ipcolor.h">src/ipcolor.h</a>, 2258<a href="../src/zcie.c">src/zcie.c</a>, 2259<a href="../src/zcolor.c">src/zcolor.c</a>, 2260<a href="../src/zcolor1.c">src/zcolor1.c</a>, 2261<a href="../src/zcolor2.c">src/zcolor2.c</a>, 2262<a href="../src/zcrd.c">src/zcrd.c</a>, 2263<a href="../src/zcsdevn.c">src/zcsdevn.c</a>, 2264<a href="../src/zcsindex.c">src/zcsindex.c</a>, 2265<a href="../src/zcspixel.c">src/zcspixel.c</a>, 2266<a href="../src/zcssepr.c">src/zcssepr.c</a>, 2267<a href="../src/zicc.c">src/zicc.c</a>, 2268<a href="../src/zhsb.c">src/zhsb.c</a>, 2269<a href="../src/zht.c">src/zht.c</a>, 2270<a href="../src/zht1.c">src/zht1.c</a>, 2271<a href="../src/zht2.c">src/zht2.c</a>, 2272<a href="../src/zpcolor.c">src/zpcolor.c</a>, 2273<a href="../src/zshade.c">src/zshade.c</a>, 2274<a href="../src/ztrans.c">src/ztrans.c</a>. 2275 2276<dt> 2277Images: 2278<dd> 2279<a href="../src/iimage.h">src/iimage.h</a>, 2280<a href="../src/iimage2.h">src/iimage2.h</a>, 2281<a href="../src/zimage.c">src/zimage.c</a>, 2282<a href="../src/zimage2.c">src/zimage2.c</a>, 2283<a href="../src/zimage3.c">src/zimage3.c</a>. 2284 2285<dt> 2286Other graphics: 2287<dd> 2288<a href="../src/igstate.h">src/igstate.h</a>, 2289<a href="../src/zdpnext.c">src/zdpnext.c</a>, 2290<a href="../src/zdps.c">src/zdps.c</a>, 2291<a href="../src/zdps1.c">src/zdps1.c</a>, 2292<a href="../src/zgstate.c">src/zgstate.c</a>, 2293<a href="../src/zpaint.c">src/zpaint.c</a>, 2294<a href="../src/zpath.c">src/zpath.c</a>, 2295<a href="../src/zpath1.c">src/zpath1.c</a>, 2296<a href="../src/zrop.c">src/zrop.c</a>, 2297<a href="../src/ztrap.c">src/ztrap.c</a>, 2298<a href="../src/zupath.c">src/zupath.c</a>. 2299 2300</dl> 2301 2302<dt> 2303Operator support: 2304<dd> 2305<a href="../src/oparc.h">src/oparc.h</a>, 2306<a href="../src/opcheck.h">src/opcheck.h</a>, 2307<a href="../src/opdef.h">src/opdef.h</a>, 2308<a href="../src/oper.h">src/oper.h</a>, 2309<a href="../src/opextern.h">src/opextern.h</a>. 2310 2311</dl> 2312 2313<h4><a name="Non_standard_operators"></a>Non-standard operators</h4> 2314 2315<p> 2316The interpreter includes many non-standard operators. Most of these provide 2317some part of the function of a standard operator, so that the standard 2318operator itself can be implemented in PostScript: these are not of interest 2319to users, and their function is usually obvious from the way they are used. 2320However, some non-standard operators provide access to additional, 2321non-standard facilities that users might want to know about, such as 2322transparency, RasterOp, and in-memory rendering. These are documented at <a 2323href="Language.htm#Additional_operators">Language.htm#Additional_operators</a>. 2324 2325<p> 2326We don't document the complete set of non-standard operators here, because 2327the set changes frequently. However, all non-standard operators are 2328supposed to have names that begin with '.', so you can find them all by 2329executing the following (Unix) command: 2330 2331<blockquote><pre> 2332grep '{".[.]' src/[zi]*.c 2333</pre></blockquote> 2334 2335<p> 2336In addition to individual non-standard operators implemented in the same 2337files as standard ones, there are several independent optional packages of 2338non-standard operators. As with other non-standard operators, the names of 2339all the operators in these packages begin with '.'. We list those packages 2340here. 2341 2342<dl> 2343 2344<dt> 2345<a href="../src/zdosio.c">src/zdosio.c</a> 2346<dd> 2347Provides access to PC hardware I/O through MS-DOS system calls. Probably no 2348longer useful. 2349 2350<dt> 2351<a href="../src/zdouble.c">src/zdouble.c</a> 2352<dd> 2353Provides "double" floating point arithmetic, using 8-byte strings to hold 2354values. Developed under a contract; probably used only by the group that 2355funded the development. 2356 2357<dt> 2358<a href="../src/zsysvm.c">src/zsysvm.c</a> 2359<dd> 2360Provides operators for allocating objects in specific VM spaces, 2361disregarding the current VM mode. 2362 2363<dt> 2364<a href="../src/zccube.c">src/zccube.c</a> 2365<dd> 2366Provides an operator for building a color cube from an arbitrary tint 2367transform, so that tint transforms can be applied from inside the 2368graphics library without calling back to the PostScript interpreter. 2369 2370</dl> 2371 2372<h4><a name="Interpreter_support"></a>Interpreter support</h4> 2373 2374<p> 2375Memory management (refs, GC, save/restore) -- see <a 2376href="#PostScript_interpreter_extensions">below</a>. 2377 2378<dl> 2379 2380<dt> 2381Miscellaneous support: 2382<dd> 2383<a href="../src/errors.h">src/errors.h</a>, 2384<a href="../src/ghost.h">src/ghost.h</a>, 2385<a href="../src/iconf.c">src/iconf.c</a>, 2386<a href="../src/iconf.h">src/iconf.h</a>, 2387<a href="../src/idparam.c">src/idparam.c</a>, 2388<a href="../src/idparam.h">src/idparam.h</a>, 2389<a href="../src/ilevel.h">src/ilevel.h</a>, 2390<a href="../src/inouparm.c">src/inouparm.c</a>, 2391<a href="../src/iparam.c">src/iparam.c</a>, 2392<a href="../src/iparam.h">src/iparam.h</a>, 2393<a href="../src/iparray.h">src/iparray.h</a>, 2394<a href="../src/iutil.c">src/iutil.c</a>, 2395<a href="../src/iutil.h">src/iutil.h</a>, 2396<a href="../src/iutil2.c">src/iutil2.c</a>, 2397<a href="../src/iutil2.h">src/iutil2.h</a>, 2398<a href="../src/iutilasm.asm">src/iutilasm.asm</a>. 2399 2400</dl> 2401 2402<h4><a name="PostScript_code"></a>PostScript code</h4> 2403 2404<dl> 2405 2406<dt> 2407Initialization and language support: 2408<dd> 2409 2410<dl> 2411 2412<dt> 2413All configurations: 2414<dd> 2415<a href="../lib/gs_init.ps">lib/gs_init.ps</a>, 2416<a href="../lib/gs_statd.ps">lib/gs_statd.ps</a>. 2417 2418<dt> 2419Level 2: 2420<dd> 2421<a href="../lib/gs_btokn.ps">lib/gs_btokn.ps</a>, 2422<a href="../lib/gs_dps1.ps">lib/gs_dps1.ps</a>, 2423<a href="../lib/gs_dps2.ps">lib/gs_dps2.ps</a>, 2424<a href="../lib/gs_lev2.ps">lib/gs_lev2.ps</a>, 2425<a href="../lib/gs_res.ps">lib/gs_res.ps</a>, 2426<a href="../lib/gs_setpd.ps">lib/gs_setpd.ps</a>. 2427 2428<dt> 2429LanguageLevel 3: 2430<dd> 2431<a href="../lib/gs_frsd.ps">lib/gs_frsd.ps</a>, 2432<a href="../lib/gs_ll3.ps">lib/gs_ll3.ps</a>, 2433<a href="../lib/gs_trap.ps">lib/gs_trap.ps</a>. 2434 2435<dt> 2436Display PostScript: 2437<dd> 2438<a href="../lib/gs_dpnxt.ps">lib/gs_dpnxt.ps</a>, 2439<a href="../lib/gs_dps.ps">lib/gs_dps.ps</a>. 2440 2441<dt> 2442ICC color profiles: 2443<dd> 2444<a href="../lib/gs_icc.ps">lib/gs_icc.ps</a>. 2445 2446</dl> 2447 2448<dt> 2449Font loading and support: 2450<dd> 2451 2452<dl> 2453 2454<dt> 2455Font name mapping: 2456<dd> 2457<a href="../lib/Fontmap">lib/Fontmap</a>, 2458<a href="../lib/Fontmap.ATB">lib/Fontmap.ATB</a>, 2459<a href="../lib/Fontmap.ATM">lib/Fontmap.ATM</a>, 2460<a href="../lib/Fontmap.GS">lib/Fontmap.GS</a>, 2461<a href="../lib/Fontmap.OS2">lib/Fontmap.OS2</a>, 2462<a href="../lib/Fontmap.OSF">lib/Fontmap.OSF</a>, 2463<a href="../lib/Fontmap.SGI">lib/Fontmap.SGI</a>, 2464<a href="../lib/Fontmap.Sol">lib/Fontmap.Sol</a>, 2465<a href="../lib/Fontmap.Ult">lib/Fontmap.Ult</a>, 2466<a href="../lib/Fontmap.VMS">lib/Fontmap.VMS</a>. 2467 2468<dt> 2469Generic: 2470<dd> 2471<a href="../lib/gs_ccfnt.ps">lib/gs_ccfnt.ps</a>, 2472<a href="../lib/gs_fonts.ps">lib/gs_fonts.ps</a>. 2473 2474<dt> 2475Type 1 and CFF: 2476<dd> 2477<a href="../lib/gs_cff.ps">lib/gs_cff.ps</a>, 2478<a href="../lib/gs_diskf.ps">lib/gs_diskf.ps</a>, 2479<a href="../lib/gs_type1.ps">lib/gs_type1.ps</a>. 2480 2481<dt> 2482TrueType: 2483<dd> 2484<a href="../lib/gs_ttf.ps">lib/gs_ttf.ps</a>, 2485<a href="../lib/gs_typ42.ps">lib/gs_typ42.ps</a>. 2486 2487<dt> 2488CID-keyed: 2489<dd> 2490<a href="../lib/gs_cidcm.ps">lib/gs_cidcm.ps</a>, 2491<a href="../lib/gs_cidfn.ps">lib/gs_cidfn.ps</a>, 2492<a href="../lib/gs_cmap.ps">lib/gs_cmap.ps</a>. 2493 2494<dt> 2495Other: 2496<dd> 2497<a href="../lib/gs_kanji.ps">lib/gs_kanji.ps</a>, 2498<a href="../lib/gs_pfile.ps">lib/gs_pfile.ps</a>, 2499<a href="../lib/gs_typ32.ps">lib/gs_typ32.ps</a>. 2500 2501</dl> 2502 2503<dt> 2504Encodings: 2505<dd> 2506 2507<dl> 2508 2509<dt> 2510Adobe-specified: 2511<dd> 2512<a href="../lib/gs_ce_e.ps">lib/gs_ce_e.ps</a>, 2513<a href="../lib/gs_dbt_e.ps">lib/gs_dbt_e.ps</a>, 2514<a href="../lib/gs_il1_e.ps">lib/gs_il1_e.ps</a>, 2515<a href="../lib/gs_mex_e.ps">lib/gs_mex_e.ps</a>, 2516<a href="../lib/gs_mro_e.ps">lib/gs_mro_e.ps</a>, 2517<a href="../lib/gs_pdf_e.ps">lib/gs_pdf_e.ps</a>, 2518<a href="../lib/gs_std_e.ps">lib/gs_std_e.ps</a>, 2519<a href="../lib/gs_sym_e.ps">lib/gs_sym_e.ps</a>, 2520<a href="../lib/gs_wan_e.ps">lib/gs_wan_e.ps</a>. 2521 2522<dt> 2523Additional: 2524<dd> 2525<a href="../lib/gs_il2_e.ps">lib/gs_il2_e.ps</a>, 2526<a href="../lib/gs_ksb_e.ps">lib/gs_ksb_e.ps</a>, 2527<a href="../lib/gs_wl1_e.ps">lib/gs_wl1_e.ps</a>, 2528<a href="../lib/gs_wl2_e.ps">lib/gs_wl2_e.ps</a>, 2529<a href="../lib/gs_wl5_e.ps">lib/gs_wl5_e.ps</a>. 2530 2531<dt> 2532Pseudo-encodings for internal use: 2533<dd> 2534<a href="../lib/gs_css_e.ps">lib/gs_css_e.ps</a>, 2535<a href="../lib/gs_lgo_e.ps">lib/gs_lgo_e.ps</a>, 2536<a href="../lib/gs_lgx_e.ps">lib/gs_lgx_e.ps</a>, 2537<a href="../lib/gs_mgl_e.ps">lib/gs_mgl_e.ps</a>. 2538 2539</dl> 2540 2541<dt> 2542Miscellaneous: 2543<dd> 2544 2545<dl> 2546 2547<dt> 2548Other support: 2549<dd> 2550<a href="../lib/gs_agl.ps">lib/gs_agl.ps</a>, 2551<a href="../lib/gs_dscp.ps">lib/gs_dscp.ps</a>, 2552<a href="../lib/gs_epsf.ps">lib/gs_epsf.ps</a>, 2553<a href="../lib/gs_pdfwr.ps">lib/gs_pdfwr.ps</a>, 2554<a href="../lib/gs_rdlin.ps">lib/gs_rdlin.ps</a>. 2555 2556<dt> 2557X Windows icon bitmaps: 2558<dd> 2559<a href="../lib/gs_l.xbm">lib/gs_l.xbm</a>, 2560<a href="../lib/gs_l.xpm">lib/gs_l.xpm</a>, 2561<a href="../lib/gs_l_m.xbm">lib/gs_l_m.xbm</a>, 2562<a href="../lib/gs_m.xbm">lib/gs_m.xbm</a>, 2563<a href="../lib/gs_m.xpm">lib/gs_m.xpm</a>, 2564<a href="../lib/gs_m_m.xbm">lib/gs_m_m.xbm</a>, 2565<a href="../lib/gs_s.xbm">lib/gs_s.xbm</a>, 2566<a href="../lib/gs_s.xpm">lib/gs_s.xpm</a>, 2567<a href="../lib/gs_s_m.xbm">lib/gs_s_m.xbm</a>, 2568<a href="../lib/gs_t.xbm">lib/gs_t.xbm</a>, 2569<a href="../lib/gs_t.xpm">lib/gs_t.xpm</a>, 2570<a href="../lib/gs_t_m.xbm">lib/gs_t_m.xbm</a>. 2571 2572<dt> 2573Not currently used: 2574<dd> 2575<a href="../lib/gs_cmdl.ps">lib/gs_cmdl.ps</a>, 2576<a href="../lib/gs_fform.ps">lib/gs_fform.ps</a>, 2577<a href="../lib/gs_l2img.ps">lib/gs_l2img.ps</a>. 2578 2579</dl> 2580 2581</dl> 2582 2583<h3><a name="PDF_interpreter"></a>PDF interpreter</h3> 2584 2585<p> 2586Ghostscript's PDF interpreter is written entirely in PostScript, because its 2587data structures are the same as PostScript's, and it is much more convenient 2588to manipulate PostScript-like data structures in PostScript than in C. 2589There is definitely a performance cost, but apparently not a substantial 2590one: we considered moving the main interpreter loop (read a token using 2591slightly different syntax than PostScript, push it on the stack if literal, 2592look it up in a special dictionary for execution if not) into C, but we did 2593some profiling and discovered that this wasn't accounting for enough of the 2594time to be worthwhile. 2595 2596<p> 2597Until recently, there was essentially no C code specifically for the purpose 2598of supporting PDF interpretation. The one major exception is the PDF 1.4 2599transparency features, which we (but not Adobe) have made available to 2600PostScript code. 2601 2602<p> 2603In addition to patching the <b><tt>run</tt></b> operator to detect PDF 2604files, the interpreter provides some procedures in <a 2605href="../lib/pdf_main.ps">lib/pdf_main.ps</a> that are meant to be called 2606from applications such as previewers. 2607 2608<dl> 2609 2610<dt> 2611Files: 2612<dd> 2613<a href="../lib/pdf_base.ps">lib/pdf_base.ps</a>, 2614<a href="../lib/pdf_draw.ps">lib/pdf_draw.ps</a>, 2615<a href="../lib/pdf_font.ps">lib/pdf_font.ps</a>, 2616<a href="../lib/pdf_main.ps">lib/pdf_main.ps</a>, 2617<a href="../lib/pdf_ops.ps">lib/pdf_ops.ps</a>, 2618<a href="../lib/pdf_sec.ps">lib/pdf_sec.ps</a>. 2619 2620</dl> 2621 2622<h3><a name="Build_process"></a>Build process</h3> 2623 2624<h4><a name="Makefile_structure"></a>Makefile structure</h4> 2625 2626<p> 2627Ghostscript's makefiles embody a number of design decisions and assumptions 2628that may not be obvious from a casual reading of the code. 2629 2630<ul> 2631 2632<li>All files are stored in subdirectories. The names of all subdirectories 2633used in the build process are defined in the top-level makefiles for the 2634various platforms: there are no "hard wired" directory names in any makefile 2635rule. Subdirectory names in the makefiles are relative to the directory 2636that is current at build time: normally this directory is the parent of the 2637various subdirectories, and holds only a <b><tt>makefile</tt></b>, which in 2638turn simply references the real top-level makefile in the source 2639subdirectory. 2640 2641<li>All compiler and linker switches are likewise defined by macros, again 2642preferably in the top-level platform makefile. 2643 2644<li>There is an absolute distinction between "source-like" subdirectories, 2645which are read-only during the build process, and "object-like" 2646subdirectories, all of whose contents are generated by the build process and 2647which can be emptied (<b><tt>rm *</tt></b>) at any time with no bad 2648effects. The source subdirectories are defined by macros named 2649<b><tt>xxxSRCDIR</tt></b>. 2650 2651<li>Object subdirectories may distinguish further between those that hold 2652the results of the build process that are needed at run time (i.e., that 2653should be included in a run-time distribution), defined by 2654<b><tt>BINDIR</tt></b>, and those that are not needed at run time, defined 2655by <b><tt>xxxGENDIR</tt></b> and <b><tt>xxxOBJDIR</tt></b>. (The 2656distinction between these is historical and probably no longer relevant.) 2657 2658<li>There may be multiple object subdirectories for different build 2659configurations. On Unix, the <b><tt>obj</tt></b> and <b><tt>bin</tt></b> 2660directories are used for normal production builds, the 2661<b><tt>debugobj</tt></b> directory for debugging builds, and the 2662<b><tt>pgobj</tt></b> directory for profiling builds; other platforms may 2663use different conventions. The Unix makefiles support targets named 2664<b><tt>debug</tt></b> and <b><tt>pg</tt></b> for debugging and profiling 2665builds respectively; other platforms generally do not. 2666 2667<li>Makefiles will be maintained by hand. This requires editing the 2668following makefile elements whenever the relevant source files changes: 2669 2670<ul> 2671 2672<li>Every header (.h) file must have a corresponding macro definition in a 2673makefile. If <b><tt>abc.h</tt></b> #includes <b><tt>def.h</tt></b> and 2674<b><tt>xyz.h</tt></b>, the definition must have the form 2675 2676<blockquote><pre> 2677xyz_h=$(xxxSRCD)xyz.h $(def_h) $(xyz_h) 2678</pre></blockquote> 2679 2680where <b><tt>xxxSRCD</tt></b> is the macro defining the relevant source 2681directory (including a trailing '/'). Note that the '.' in the file name 2682has been replaced by an underscore. Note also that the definition must 2683follow all definitions it references, since some <b><tt>make</tt></b> 2684programs expand macros in definitions at the time of definition rather than 2685at the time of use. 2686 2687<li>Every .c file must have a corresponding rule in a makefile. If 2688<b><tt>abc.c</tt></b> #includes <b><tt>def.h</tt></b> and 2689<b><tt>lmn.h</tt></b>, the rule must have approximately the form 2690 2691<blockquote><pre> 2692$(xxxOBJD)abc.$(OBJ) : $(xxxSRCD)abc.c $(def_h) $(lmn_h) 2693 $(xxCC) $(xxO_)abc.$(OBJ) $(C_) $(xxxSRCD)abc.c 2694</pre></blockquote> 2695 2696where <b><tt>xxxSRCD</tt></b> is as before; <b><tt>xxxOBJD</tt></b> is the 2697relevant object directory; <b><tt>xxCC</tt></b> defines the name of the C 2698compiler plus the relevant compilation switches; and <b><tt>xxO_</tt></b> 2699and <b><tt>C_</tt></b> are macros used to bridge syntactic differences 2700between different <b><tt>make</tt></b> programs. 2701 2702</ul> 2703 2704</ul> 2705 2706<p> 2707The requirement to keep makefiles up to date by hand has been controversial. 2708Two alternatives are generally proposed. 2709 2710<ul> 2711 2712<li>Programs like <b><tt>makedeps</tt></b>, which generate build rules 2713automatically from the #include lists in C files. We have found such 2714programs useless: they "wire in" specific, concrete directory names, not 2715only for our own code but even for the system header files; they have to be 2716run manually whenever code files are added, renamed, or deleted, or whenever 2717the list of #includes in any file changes; and they cannot deal with 2718different source files requiring different compilation switches. 2719 2720<li>MSVC-style "project" files. These are equally useless: they are not 2721portable across different vendors' tools -- in fact, there may not even be a 2722usable import/export facility to convert their data to or from text form -- 2723and they cannot combine configuration-independent data with 2724configuration-specific data. 2725 2726</ul> 2727 2728<p> 2729We have seriously considered writing our own build program in Tcl or Python 2730that would eliminate these problems, or perhaps porting the tools developed 2731by Digital's Vesta research project (if we can get access to them); however, 2732either of these approaches would create potential portability problems of 2733its own, not to mention difficulties in integrating with others' build 2734systems. 2735 2736<p> 2737In the meantime, to ease the pain for mortal users and developers on 2738Unix platforms, we have adopted the standard autoconf tool to 2739systematically generate an appropriate top-level makefile for the 2740target system. As currently implemented, its use makes no deep changes 2741to the Ghostscript build system, but rather generates a makefile, more 2742or less the same as would be achieved by starting from a 2743platform-specific toplevel makefile and hand-editing. The relevant 2744autoconf sources are in <a 2745href="../src/Makefile.in">src/Makefile.in</a>, and <a 2746href="../src/configure.ac">configure.ac</a>. These sources are used in 2747the release process to create a <a href="../configure">configure</a> 2748script in the toplevel directory of releases. Also, there is an <a 2749href="../autogen.sh">autogen.sh</a> script to automate the autoconf 2750process somewhat. The names and locations of these files were chosen 2751to be clear to those familiar with autoconf, even though they represent 2752a slight departure from Ghostscript tradition. 2753 2754<p> 2755For more information about makefiles: 2756 2757<ul> 2758 2759<li>For a detailed list of makefiles, and a discussion of makefile issues 2760related to portability, see the <a href="#Makefiles">Makefiles</a> section 2761below. 2762 2763<li>For more detailed information about editing configuration information in 2764makefiles, see <a 2765href="Make.htm#Makefile_overview">doc/Make.htm#Makefile_overview</a>. 2766 2767<li>For a complete example of adding a new driver to a makefile, see <a 2768href="Drivers.htm#Adding_drivers">doc/Drivers.htm#Adding_drivers</a>. 2769 2770<li>For a few more notes on makefile coding conventions, see <a 2771href="C-style.htm#Makefiles">doc/C-style.htm#Makefiles</a>. 2772 2773</ul> 2774 2775<h4><a name="dev_files"></a>.dev files</h4> 2776 2777<p> 2778On top of the general conventions just described, Ghostscript's makefiles 2779add a further layer of structure in order to support an open-ended set of 2780fine-grained, flexible configuration options. Selecting an option (usually 2781called a "module") for inclusion in the build may affect the build in many 2782ways: 2783 2784<ul> 2785 2786<li>Almost always, it requires linking in some compiled code files. 2787 2788<li>It may require running some additional initialization procedures at 2789startup. 2790 2791<li>It may require reading in some additional PostScript files at startup. 2792For example, a Level 2 PostScript build requires support for PostScript 2793resources and for setpagedevice, which are implemented in PostScript code. 2794 2795<li>It may require adding entries to a variety of internal tables that 2796catalogue such things as drivers, IODevices, Function types, etc. 2797 2798<li>It may require that other particular modules be included. For example, 2799the "PostScript Level 2" module requires the modules for various filters, 2800color spaces, etc. 2801 2802<li>It may require <em>removing</em> some other (default) module from the 2803build. For example, the core (Level 1) PostScript build has a "stub" for 2804binary tokens, which are a Level 2 feature but are referenced by the core 2805scanner: a Level 2 build must remove the stub. For more information about 2806this, look for the string <b><tt>-replace</tt></b> in the makefiles and in 2807<a href="../src/genconf.c">src/genconf.c</a>. 2808 2809</ul> 2810 2811<p> 2812Each module is defined in the makefiles by rules that create a file named 2813<b><em>xxx</em><tt>.dev</tt></b>. The dependencies of the rule include all 2814the files that make up the module (compiled code files, PostScript files, 2815etc.); the body of the rule creates the .dev file by writing the description 2816of the module into it. A program called <b><tt>genconf</tt></b>, described 2817in the next section, merges all the relevant .dev files together. For 2818examples of .dev rules, see any of the Ghostscript makefiles. 2819 2820<p> 2821Ultimately, a person must specify the root set of modules to include in a 2822build (which of course may require other modules, recursively). 2823Ghostscript's makefiles do this with a set of macros called 2824<b><tt>FEATURE_DEVS</tt></b> and <b><tt>DEVICE_DEVS</tt>n</b>, defined in 2825each top-level makefile, but nothing in the module machinery depends on 2826this. 2827 2828<h4><a name="Generators"></a>Generators</h4> 2829 2830<p> 2831Ghostscript's build procedure is somewhat unusual in that it compiles and 2832then executes some support programs during the build process. These 2833programs then generate data or source code that is used later on in the 2834build. 2835 2836<p> 2837The most important and complex of the generator programs is 2838<b><tt>genconf</tt></b>. <b><tt>genconf</tt></b> merges all the .dev files 2839that make up the build, and creates three or more output files used in later 2840stages: 2841 2842<ul> 2843 2844<li><b><tt>gconfig.h</tt></b>, consisting mainly of macro calls, one call 2845per "resource" making up the build, other than "resources" listed in the 2846other output files. 2847 2848<li><b><tt>gconfigf.h</tt></b>, produced only for PostScript builds with 2849compiled-in fonts, consisting of one macro call per font. 2850 2851<li>A linker control file whose name varies from one platform to another, 2852containing the list of compiled code files to be linked. 2853 2854<li>If necessary, another linker control file, also varying between 2855platforms, that contains other information for the linker such as the list 2856of system libraries to be searched. (On Unix platforms, the two linker 2857control functions are combined in a single file.) 2858 2859</ul> 2860 2861<dl> 2862 2863<dt> 2864Source generators: 2865<dd> 2866 2867<dl> 2868 2869<dt> 2870<a href="../src/ansi2knr.c">src/ansi2knr.c</a> 2871<dd> 2872Converts ANSI C source to traditional (also known as "K&R") C. Used if 2873and only if compiling with a pre-ANSI C compiler. 2874 2875<dt> 2876<a href="../src/genarch.c">src/genarch.c</a> 2877<dd> 2878Creates a header file containing a variety of information about the hardware 2879and compiler that isn't provided in any standard system header file. Always 2880used. 2881 2882<dt> 2883<a href="../src/genconf.c">src/genconf.c</a> (also generates non-source) 2884<dd> 2885Constructs header files and linker control files from the collection of 2886options and modules that make up the build. See above. Always used. 2887 2888<dt> 2889<a href="../src/genht.c">src/genht.c</a> 2890<dd> 2891Converts a PostScript halftone (in a particular constrained format) to a C 2892data structure that can be compiled into an executable. Only used if any 2893such halftones are included in the build. 2894 2895<dt> 2896<a href="../src/geninit.c">src/geninit.c</a> 2897<dd> 2898Converts PostScript initialization files to C data structures that can be 2899compiled into an executable. Only used when building a PostScript 2900interpreter, and only if <b><tt>COMPILE_INITS</tt></b> was set to 1 in the 2901makefile. 2902 2903</dl> 2904 2905<dt> 2906Other generators: 2907<dd> 2908 2909<dl> 2910 2911<dt> 2912<a href="../src/echogs.c">src/echogs.c</a> 2913<dd> 2914Implements a variety of shell-like functions to get around quirks, 2915limitations, and omissions in the shells on various platforms. Always used. 2916 2917<dt> 2918<a href="../src/genconf.c">src/genconf.c</a> (also generates source) 2919<dd> 2920See above. 2921 2922<dt> 2923<a href="../src/gendev.c">src/gendev.c</a> (not used) 2924<dd> 2925Was intended as a replacement for <b><tt>genconf</tt></b>, but was never 2926completed. 2927 2928</dl> 2929 2930</dl> 2931 2932<h4><a name="Build_support"></a>Support</h4> 2933 2934<p> 2935There are a number of programs, scripts, and configuration files that exist 2936only for the sake of the build process. 2937 2938<dl> 2939 2940<dt> 2941Files for PC environments: 2942<dd> 2943<a href="../src/bcc32.cfg">src/bcc32.cfg</a>, 2944<a href="../src/cp.bat">src/cp.bat</a>, 2945<a href="../src/cp.cmd">src/cp.cmd</a>, 2946<a href="../src/dw32c.def">src/dw32c.def</a>, 2947<a href="../src/dwmain.rc">src/dwmain.rc</a>, 2948<a href="../src/dwmain16.def">src/dwmain16.def</a>, 2949<a href="../src/dwmain32.def">src/dwmain32.def</a>, 2950<a href="../src/dwsetup.def">src/dwsetup.def</a>, 2951<a href="../src/dwsetup.rc">src/dwsetup.rc</a>, 2952<a href="../src/dwuninst.def">src/dwuninst.def</a>, 2953<a href="../src/dwuninst.rc">src/dwuninst.rc</a>, 2954<a href="../src/gs16spl.def">src/gs16spl.def</a>, 2955<a href="../src/gs16spl.rc">src/gs16spl.rc</a>, 2956<a href="../src/gsdll2.def">src/gsdll2.def</a>, 2957<a href="../src/gsdll2.rc">src/gsdll2.rc</a>, 2958<a href="../src/gsdll32.def">src/gsdll32.def</a>, 2959<a href="../src/gsdll32.rc">src/gsdll32.rc</a>, 2960<a href="../src/gsdll32w.lnk">src/gsdll32w.lnk</a>, 2961<a href="../src/gsgraph.icx">src/gsgraph.icx</a>, 2962<a href="../src/gsos2.def">src/gsos2.def</a>, 2963<a href="../src/gsos2.icx">src/gsos2.icx</a>, 2964<a href="../src/gsos2.rc">src/gsos2.rc</a>, 2965<a href="../src/gspmdrv.def">src/gspmdrv.def</a>, 2966<a href="../src/gspmdrv.icx">src/gspmdrv.icx</a>, 2967<a href="../src/gspmdrv.rc">src/gspmdrv.rc</a>, 2968<a href="../src/gstext.icx">src/gstext.icx</a>, 2969<a href="../src/gswin.rc">src/gswin.rc</a>, 2970<a href="../src/gswin32.rc">src/gswin32.rc</a>, 2971<a href="../src/gswin386.rc">src/gswin386.rc</a>, 2972<a href="../src/mv.bat">src/mv.bat</a>, 2973<a href="../src/mv.cmd">src/mv.cmd</a>, 2974<a href="../src/rm.bat">src/rm.bat</a>, 2975<a href="../src/rm.cmd">src/rm.cmd</a>, 2976<a href="../src/turboc.cfg">src/turboc.cfg</a>. 2977 2978<dt> 2979Files for OpenVMS: 2980<dd> 2981<a href="../src/append_l.com">src/append_l.com</a>, 2982<a href="../src/copy_one.com">src/copy_one.com</a>, 2983<a href="../src/rm_all.com">src/rm_all.com</a>, 2984<a href="../src/rm_one.com">src/rm_one.com</a>. 2985 2986<dt> 2987Other files: 2988<dd> 2989<a href="../src/bench.c">src/bench.c</a>, 2990<a href="../src/catmake">src/catmake</a>, 2991<a href="../src/ccgs">src/ccgs</a>, 2992<a href="../src/instcopy">src/instcopy</a>. 2993 2994</dl> 2995 2996<h3><a name="Utilities"></a>Utilities</h3> 2997 2998<p> 2999Ghostscript comes with many utilities for doing things like viewing bitmap 3000files and converting between file formats. Some of these are written in 3001PostScript, some as scripts, and some as scripts that invoke special 3002PostScript code. 3003 3004<h4><a name="Utilities_in_PostScript"></a>Utilities in PostScript</h4> 3005 3006<p> 3007These are all documented in <a href="Psfiles.htm">doc/Psfiles.htm</a>, q.v. 3008 3009<h4><a name="Utility_scripts"></a>Utility scripts</h4> 3010 3011<p> 3012Many of these scripts come in both Unix and MS-DOS (<b><tt>.bat</tt></b> 3013versions; some also have an OS/2 (<b><tt>.cmd</tt></b>) version. The choice 3014of which versions are provided is historical and irregular. These scripts 3015should all be documented somewhere, but currently, many of them have man 3016pages, a few have their own documentation in the doc directory, and some 3017aren't documented at all. 3018 3019<dl> 3020 3021<dt> 3022Script files without PC versions: 3023<dd> 3024<a href="../lib/afmdiff.awk">lib/afmdiff.awk</a>, 3025<a href="../lib/dvipdf">lib/dvipdf</a>, 3026<a href="../lib/fixmswrd.pl">lib/fixmswrd.pl</a>, 3027<a href="../lib/lprsetup.sh">lib/lprsetup.sh</a>, 3028<a href="../lib/pfbtopfa">lib/pfbtopfa</a>, 3029<a href="../lib/pj-gs.sh">lib/pj-gs.sh</a>, 3030<a href="../lib/pphs">lib/pphs</a>, 3031<a href="../lib/printafm">lib/printafm</a>, 3032<a href="../lib/pv.sh">lib/pv.sh</a>, 3033<a href="../lib/sysvlp.sh">lib/sysvlp.sh</a>, 3034<a href="../lib/unix-lpr.sh">lib/unix-lpr.sh</a>, 3035<a href="../lib/wftopfa">lib/wftopfa</a>. 3036 3037<dt> 3038Script files with PC versions: 3039<dd> 3040<a href="../lib/bdftops">lib/bdftops</a>, 3041<a href="../lib/bdftops.bat">lib/bdftops.bat</a>, 3042<a href="../lib/bdftops.cmd">lib/bdftops.cmd</a>, 3043<a href="../lib/eps2eps">lib/eps2eps</a>, 3044<a href="../lib/eps2eps.bat">lib/eps2eps.bat</a>, 3045<a href="../lib/eps2eps.cmd">lib/eps2eps.cmd</a>, 3046<a href="../lib/font2c">lib/font2c</a>, 3047<a href="../lib/font2c.bat">lib/font2c.bat</a>, 3048<a href="../lib/font2c.cmd">lib/font2c.cmd</a>, 3049<a href="../lib/gsbj">lib/gsbj</a>, 3050<a href="../lib/gsbj.bat">lib/gsbj.bat</a>, 3051<a href="../lib/gsdj">lib/gsdj</a>, 3052<a href="../lib/gsdj.bat">lib/gsdj.bat</a>, 3053<a href="../lib/gsdj500">lib/gsdj500</a>, 3054<a href="../lib/gsdj500.bat">lib/gsdj500.bat</a>, 3055<a href="../lib/gslj">lib/gslj</a>, 3056<a href="../lib/gslj.bat">lib/gslj.bat</a>, 3057<a href="../lib/gslp">lib/gslp</a>, 3058<a href="../lib/gslp.bat">lib/gslp.bat</a>, 3059<a href="../lib/gsnd">lib/gsnd</a>, 3060<a href="../lib/gsnd.bat">lib/gsnd.bat</a>, 3061<a href="../lib/pdf2dsc">lib/pdf2dsc</a>, 3062<a href="../lib/pdf2dsc.bat">lib/pdf2dsc.bat</a>, 3063<a href="../lib/pdf2ps">lib/pdf2ps</a>, 3064<a href="../lib/pdf2ps.bat">lib/pdf2ps.bat</a>, 3065<a href="../lib/pdf2ps.cmd">lib/pdf2ps.cmd</a>, 3066<a href="../lib/pdfopt">lib/pdfopt</a>, 3067<a href="../lib/pdfopt.bat">lib/pdfopt.bat</a>, 3068<a href="../lib/pf2afm">lib/pf2afm</a>, 3069<a href="../lib/pf2afm.bat">lib/pf2afm.bat</a>, 3070<a href="../lib/pf2afm.cmd">lib/pf2afm.cmd</a>, 3071<a href="../lib/ps2ascii">lib/ps2ascii</a>, 3072<a href="../lib/ps2ascii.bat">lib/ps2ascii.bat</a>, 3073<a href="../lib/ps2ascii.cmd">lib/ps2ascii.cmd</a>, 3074<a href="../lib/ps2epsi">lib/ps2epsi</a>, 3075<a href="../lib/ps2epsi.bat">lib/ps2epsi.bat</a>, 3076<a href="../lib/ps2epsi.cmd">lib/ps2epsi.cmd</a>, 3077<a href="../lib/ps2pdf">lib/ps2pdf</a>, 3078<a href="../lib/ps2pdf.bat">lib/ps2pdf.bat</a>, 3079<a href="../lib/ps2pdf.cmd">lib/ps2pdf.cmd</a>, 3080<a href="../lib/ps2pdf12">lib/ps2pdf12</a>, 3081<a href="../lib/ps2pdf12.bat">lib/ps2pdf12.bat</a>, 3082<a href="../lib/ps2pdf12.cmd">lib/ps2pdf12.cmd</a>, 3083<a href="../lib/ps2pdf13">lib/ps2pdf13</a>, 3084<a href="../lib/ps2pdf13.bat">lib/ps2pdf13.bat</a>, 3085<a href="../lib/ps2pdf13.cmd">lib/ps2pdf13.cmd</a>, 3086<a href="../lib/ps2pdf14">lib/ps2pdf14</a>, 3087<a href="../lib/ps2pdf14.bat">lib/ps2pdf14.bat</a>, 3088<a href="../lib/ps2pdf14.cmd">lib/ps2pdf14.cmd</a>, 3089<a href="../lib/ps2pdfwr">lib/ps2pdfwr</a>, 3090<a href="../lib/ps2pdfxx.bat">lib/ps2pdfxx.bat</a>, 3091<a href="../lib/ps2ps">lib/ps2ps</a>, 3092<a href="../lib/ps2ps.bat">lib/ps2ps.bat</a>, 3093<a href="../lib/ps2ps.cmd">lib/ps2ps.cmd</a>. 3094 3095<dt> 3096Script files with only PC versions: 3097<dd> 3098<a href="../lib/gsndt.bat">lib/gsndt.bat</a>, 3099<a href="../lib/gssetgs.bat">lib/gssetgs.bat</a>, 3100<a href="../lib/gst.bat">lib/gst.bat</a>, 3101<a href="../lib/gstt.bat">lib/gstt.bat</a>, 3102<a href="../lib/lp386.bat">lib/lp386.bat</a>, 3103<a href="../lib/lp386r2.bat">lib/lp386r2.bat</a>, 3104<a href="../lib/lpgs.bat">lib/lpgs.bat</a>, 3105<a href="../lib/lpr2.bat">lib/lpr2.bat</a>, 3106<a href="../lib/pftogsf.bat">lib/pftogsf.bat</a>, 3107<a href="../lib/wmakebat.bat">lib/wmakebat.bat</a>. 3108 3109</dl> 3110 3111<hr> 3112 3113<h2><a name="Memory_management"></a>Memory management</h2> 3114 3115<h3><a name="Memory_manager_architecture"></a>Memory manager architecture</h3> 3116 3117<p> 3118In many environments, the memory manager is a set of library facilities that 3119implicitly manage the entire address space in a homogenous manner. 3120Ghostscript's memory manager architecture has none of these properties: 3121 3122<ul> 3123 3124<li>Rather than a single library accessed as procedures, Ghostscript 3125includes multiple allocator types, each of which in turn may have multiple 3126instances (allocators). Allocators are 'objects' with a substantial set of 3127virtual functions. 3128 3129<li>Rather than managing the entire address space, each allocator manages a 3130storage pool, which it may or may not be able to expand or reduce by calling 3131on a 'parent' allocator. 3132 3133<li>Rather than a single genus of untyped storage blocks, Ghostscript's 3134allocators provide two genera -- type-tagged 'objects', and 'strings' -- 3135with substantially different properties. 3136 3137</ul> 3138 3139<h4><a name="Objects_vs_strings"></a>Objects vs strings</h4> 3140 3141<p> 3142As noted above, allocators provide two different storage genera. 3143 3144<p> 3145Objects: 3146 3147<ul> 3148<li>Are aligned in storage to satisfy the most stringent alignment 3149requirement imposed by the CPU or compiler; 3150<li>Can be referenced only by pointers to their start, not to any internal 3151location, unless special arrangements are made; 3152<li>May contain pointers to other objects, or to strings; 3153<li>Have an associated <em>structure descriptor</em> that specifies their 3154size (usually) and the location of any pointers contained within them. 3155</ul> 3156 3157<p> 3158Given a pointer to an object, the allocator that allocated it must be able 3159to return the object's size and the pointer to its structure descriptor. 3160(It is up to the client to know what allocator allocated an object.) 3161 3162<p> 3163Strings: 3164 3165<ul> 3166<li>Are not aligned in storage; 3167<li>Can be referenced by pointers (consisting of a starting address and a 3168length) to any substring, starting anywhere within the string; 3169<li>May not contain pointers; 3170<li>Do not have a structure descriptor. 3171</ul> 3172 3173<p> 3174The object/string distinction reflects a space/capability tradeoff. The 3175per-object space overhead of the standard type of allocator is typically 12 3176bytes; this is too much to impose on every string of a few bytes. On the 3177other hand, restricting object pointers to reference the start of the object 3178currently makes object garbage collection and compaction more 3179space-efficient. If we were to redesign the standard allocator, we would 3180probably opt for a different design in which strings were allocated within 3181container objects of a few hundred bytes, and pointers into the middle of 3182all objects were allowed. 3183 3184<h4><a name="Structure_descriptors"></a>Structure descriptors</h4> 3185 3186<p> 3187Every object allocated by a Ghostscript allocator has an associated 3188structure descriptor, which the caller provides when allocating the object. 3189The structure descriptor serves several purposes: 3190 3191<ul> 3192<li>Specifying the size of the object for allocation; 3193<li>Providing pointer-enumeration and pointer-relocation procedures for 3194the garbage collector; 3195<li>Providing an optional finalization procedure to be called when the 3196object is freed (either explicitly or automatically). 3197</ul> 3198 3199<p> 3200Structure descriptors are read-only, and are normally defined statically 3201using one of the large set of <b><tt>gs_private_st_</tt></b> or 3202<b><tt>gs_public_st_</tt></b> macros in <a 3203href="../src/gsstruct.h">src/gsstruct.h</a>. 3204 3205<p> 3206While the structure descriptor normally specifies the size of the object, 3207one can also allocate an array of bytes or objects, whose size is a multiple 3208of the size in the descriptor. For this reason, every object stores its 3209size as well as a reference to its descriptor. 3210 3211<p> 3212Because the standard Ghostscript garbage collector is conservative and can 3213move objects, every object allocated by a Ghostscript allocator must have an 3214accurate structure descriptor. If you define a new type of object 3215(structure) that will be allocated in storage managed by Ghostscript, you 3216<em>must</em> create an accurate descriptor for it, and use that descriptor 3217to allocate it. The process of creating accurate descriptors for all 3218structures was long and painful, and accounted for many hard-to-diagnose 3219bugs. 3220 3221<p> 3222By convention, the structure descriptor for structure type 3223<b><tt>xxx_t</tt></b> is named <b><tt>st_xxx</tt></b> (this is preferred), 3224or occasionally <b><tt>st_xxx_t</tt></b>. 3225 3226<p> 3227Note that a structure descriptor is only required for objects allocated by 3228the Ghostscript allocator. A structure type <b><tt>xxx_t</tt></b> does not 3229require a structure descriptor if instances of that type are used 3230<em>only</em> in the following ways: 3231 3232<ul> 3233 3234<li>Instances are allocated only on the C stack, e.g., as 3235<b><tt>xxx_t xxx1, xxx2;</tt></b>, or on the C heap, with 3236<b><tt>malloc</tt></b> or through the Ghostscript "wrapper" defined in <a 3237href="../src/gsmalloc.h">src/gsmalloc.h</a>. 3238 3239<li>Pointers to instances are not stored in places where the garbage 3240collector will try to trace the pointer. 3241 3242<li>Code never attempts to get the structure type or size of an instance 3243through the allocator API. 3244 3245</ul> 3246 3247<p> 3248In general, structures without descriptors are problem-prone, and are 3249deprecated; in new code, they should only be used if the structure is 3250confined to a single .c file and its instances are only allocated on the C 3251stack. 3252 3253<dl> 3254<dt> 3255Files: 3256<dd> 3257<a href="../src/gsstruct.h">src/gsstruct.h</a>, 3258<a href="../src/gsstype.h">src/gsstype.h</a>. 3259</dl> 3260 3261<h4><a name="Garbage_collection"></a>Garbage collection</h4> 3262 3263<p> 3264The allocator architecture is designed to support compacting garbage 3265collection. Every object must be able to enumerate all the pointers it 3266contains, both for tracing and for relocation. As noted just above, the 3267structure descriptor provides procedures that do this. 3268 3269<p> 3270Whether or not a particular allocator type actually provides a garbage 3271collector is up to the allocator: garbage collection is invoked through a 3272virtual procedure. In practice, however, there are only two useful garbage 3273collectors for Ghostscript's own allocator: 3274 3275<ul> 3276<li>The "real" garbage collector associated with the PostScript interpreter, 3277described <a href="#Interpreter_GC">below</a>; 3278<li>A "non" garbage collector that only merges adjacent free blocks. 3279</ul> 3280 3281<dl> 3282<dt> 3283Files: 3284<dd> 3285<a href="../src/gsgc.h">src/gsgc.h</a>, 3286<a href="../src/gsnogc.c">src/gsnogc.c</a>, 3287<a href="../src/gsnogc.h">src/gsnogc.h</a>. 3288</dl> 3289 3290<h4><a name="Movability"></a>Movability</h4> 3291 3292<p> 3293As just noted, objects are normally movable by the garbage collector. 3294However, some objects must be immovable, usually because some other piece of 3295software must retain pointers to them. The allocator API includes 3296procedures for allocating both movable (default) and immovable objects. 3297Note, however, that even immovable objects must be traceable (have a 3298structure descriptor), and may be freed, by the garbage collector. 3299 3300<h4><a name="Parent_hierarchy"></a>Parent hierarchy</h4> 3301 3302<p> 3303When an allocator needs to add memory to the pool that it manages, it 3304requests the memory from its <em>parent</em> allocator. Every allocator has 3305a pointer to its parent; multiple allocators may share a single parent. The 3306ultimate ancestor of all allocators that can expand their pool dynamically 3307is an allocator that calls <b><tt>malloc</tt></b>, described <a 3308href="#malloc">below</a>. However, especially in embedded environments, an 3309allocator may be limited to a fixed-size pool assigned to it when it is 3310created. 3311 3312<h4><a name="Allocator_API"></a>Allocator API</h4> 3313 3314In summary, the allocator API provides the following principal operations: 3315 3316<ul> 3317<li>Allocate and free movable (default) or immovable objects and strings. 3318<li>Return the structure type and size of an object. 3319<li>Resize (shrink or grow) movable objects and strings, preserving 3320the contents insofar as possible. 3321<li>Report the size of the managed pool, and how much of it is in use. 3322<li>Register and unregister root pointers for the garbage collector. 3323<li>Free the allocator itself. 3324<li>Consolidate adjacent free blocks to reduce fragmentation. 3325</ul> 3326 3327<p> 3328For details, see <a href="../src/gsmemory.h">src/gsmemory.h</a>. 3329 3330<p> 3331The allocator API also includes one special hook for the PostScript 3332interpreter: the concept of stable allocators. See the section on <a 3333href="#save_forgetsave_restore"><b><tt>save</tt></b> and 3334<b><tt>restore</tt></b></a> below for details. 3335 3336<dl> 3337<dt> 3338Files: 3339<dd> 3340<a href="../src/gsmemraw.h">src/gsmemraw.h</a>, 3341<a href="../src/gsmemory.c">src/gsmemory.c</a>, 3342<a href="../src/gsmemory.h">src/gsmemory.h</a>, 3343<a href="../src/gsstruct.h">src/gsstruct.h</a>, 3344<a href="../src/gsstype.h">src/gsstype.h</a>. 3345</dl> 3346 3347<h3><a name="Freeing_storage"></a>Freeing storage</h3> 3348 3349<p> 3350Ghostscript's memory management architecture provides three different ways 3351to free objects: explicitly, by reference counting, or by garbage 3352collection. They provide different safety / performance / convenience 3353tradeoffs; we believe that all three are necessary. 3354 3355<p> 3356Objects are always freed as a whole; strings may be freed piecemeal. 3357 3358<p> 3359An object may have an associated finalization procedure, defined in the 3360structure descriptor. This procedure is called just before the object is 3361freed, independent of which method is being used to free the object. A few 3362types of objects have a virtual finalization procedure as well: the 3363finalization procedure defined in the descriptor simply calls the one in the 3364object. 3365 3366<h4><a name="Explicit_freeing"></a>Explicit freeing</h4> 3367 3368<p> 3369Objects and strings may be freed explicitly, using the 3370<b><tt>gs_free_</tt></b> virtual procedures in the allocator API. It is up 3371to the client to ensure that all allocated objects are freed at most once, 3372and that there are no dangling pointers. 3373 3374<p> 3375Explicit freeing is the fastest method, but is the least convenient and 3376least safe. It is most appropriate when storage is freed in the same 3377procedure where it is allocated, or for storage that is known to be 3378referenced by only one pointer. 3379 3380<h4><a name="Reference_counting"></a>Reference counting</h4> 3381 3382<p> 3383Objects may be managed by reference counting. When an object is allocated, 3384its reference count may be set to 0 or 1. Subsequently, when the reference 3385count is decremented to 0, the object is freed. 3386 3387<p> 3388The reference counting machinery provides its own virtual finalization 3389procedure for all reference-counted objects. The machinery calls this 3390procedure when it is about to free the object (but not when the object is 3391freed in any other way, which is probably a design bug). This is in 3392addition to (and called before) any finalization procedure associated with 3393the object type. 3394 3395<p> 3396Reference counting is as fast as explicit freeing, but takes more space in 3397the object. It is most appropriate for relatively large objects which are 3398referenced only from a small set of pointers. Note that reference counting 3399cannot free objects that are involved in a pointer cycle (e.g., A -> B -> C 3400-> A). 3401 3402<dl> 3403<dt> 3404Files: 3405<dd> 3406<a href="../src/gsrefct.h">src/gsrefct.h</a>. 3407</dl> 3408 3409<h4><a name="Real_garbage_collection"></a>(Real) garbage collection</h4> 3410 3411<p> 3412Objects and strings may be freed automatically by a garbage collector. See 3413<a href="#Interpreter_GC">below</a>. 3414 3415<h3><a name="Special_implementations"></a>Special implementations</h3> 3416 3417<h4><a name="malloc"></a>malloc</h4> 3418 3419<p> 3420As mentioned <a href="#Parent_hierarchy">above</a>, the ultimate ancestor of 3421all allocators with an expandable pool is one that calls 3422<b><tt>malloc</tt></b>. 3423 3424<dl> 3425<dt> 3426Files: 3427<dd> 3428<a href="../src/gsmalloc.h">src/gsmalloc.h</a>, 3429<a href="../src/gsmalloc.c">src/gsmalloc.c</a>. 3430</dl> 3431 3432<h4><a name="Locking"></a>Locking</h4> 3433 3434<p> 3435In a multi-threaded environment, if an allocator must be callable from 3436multiple threads (for example, if it is used to allocate structures in one 3437thread that are passed to, and freed by, another thread), the allocator must 3438provide mutex protection. Ghostscript provides this capability in the form 3439of a <em>wrapper</em> allocator, that simply forwards all calls to a 3440<em>target</em> allocator under protection of a mutex. Using the wrapper 3441technique, any allocator can be made thread-safe. 3442 3443<dl> 3444<dt> 3445Files: 3446<dd> 3447<a href="../src/gsmemlok.h">src/gsmemlok.h</a>, 3448<a href="../src/gsmemlok.c">src/gsmemlok.c</a>. 3449</dl> 3450 3451<h4><a name="Retrying"></a>Retrying</h4> 3452 3453<p> 3454In an embedded environment, job failure due to memory exhaustion is very 3455undesirable. Ghostscript provides a wrapper allocator that, when an 3456allocation attempt fails, calls a client-provided procedure that can attempt 3457to free memory, then ask for the original allocation to be retried. For 3458example, such a procedure can wait for a queue to empty, or can free memory 3459occupied by caches. 3460 3461<dl> 3462<dt> 3463Files: 3464<dd> 3465<a href="../src/gsmemret.h">src/gsmemret.h</a>, 3466<a href="../src/gsmemret.c">src/gsmemret.c</a>. 3467</dl> 3468 3469<h3><a name="Standard_implementation"></a>Standard implementation</h3> 3470 3471<p> 3472The standard Ghostscript allocator gets storage from its parent (normally 3473the <b><tt>malloc</tt></b> allocator) in large blocks called 3474<em>chunks</em>, and then allocates objects up from the low end and strings 3475down from the high end. Large objects or strings are allocated in their own 3476chunk. 3477 3478<p> 3479The standard allocator maintains a set of free-block lists for small object 3480sizes, one list per size (rounded up to the word size), plus a free-block 3481list for large objects (but not for objects so large that they get their own 3482chunk: when such an object is freed, its chunk is returned to the parent). 3483The lists are not sorted; adjacent blocks are only merged if needed. 3484 3485<p> 3486While the standard allocator implements the generic allocator API, and is 3487usable with the library alone, it includes a special hook for the PostScript 3488interpreter to aid in the efficient allocation of PostScript composite 3489objects (arrays and dictionaries). See the section on <a 3490href="#Refs">Refs</a> below for details. 3491 3492<dl> 3493<dt> 3494Files: 3495<dd> 3496<a href="../src/gsalloc.c">src/gsalloc.c</a>, 3497<a href="../src/gsalloc.h">src/gsalloc.h</a>, 3498<a href="../src/gxalloc.h">src/gxalloc.h</a>, 3499<a href="../src/gxobj.h">src/gxobj.h</a>. 3500</dl> 3501 3502<h3><a name="PostScript_interpreter_extensions"></a>PostScript interpreter extensions</h3> 3503 3504<p> 3505The PostScript interpreter uses an allocator that extends the graphic 3506library's standard allocator to handle PostScript objects, 3507<b><tt>save</tt></b> and <b><tt>restore</tt></b>, and real garbage 3508collection. 3509 3510<h4><a name="Refs"></a>Refs (PostScript "objects")</h4> 3511 3512<p> 3513Ghostscript represents what the PLRM calls PostScript "objects" using a 3514structure called a <b><tt>ref</tt></b>, defined in <a 3515href="../src/iref.h">src/iref.h</a>; packed refs, used for the elements of 3516packed arrays, are defined in <a href="../src/ipacked.h">src/ipacked.h</a>. 3517See those files for detailed information. 3518 3519<dl> 3520<dt> 3521Files: 3522<dd> 3523<a href="../src/ipacked.h">src/ipacked.h</a>, 3524<a href="../src/iref.h">src/iref.h</a>. 3525</dl> 3526 3527<p> 3528The PLRM calls for two types of "virtual memory" (VM) space: global and 3529local. Ghostscript adds a third space, <em>system</em> VM, whose lifetime 3530is an entire session -- i.e., it is effectively "permanent". All three 3531spaces are subject to garbage collection. There is a separate allocator 3532instance for each VM space (actually, two instances each for global and 3533local spaces; see <a href="#save_forgetsave_restore">below</a>). In a 3534system with multiple contexts and multiple global or local VMs, each global 3535or local VM has its own allocator instance(s). 3536 3537<p> 3538Refs that represent PostScript composite objects, and therefore include 3539pointers to stored data, include a 2-bit VM space tag to indicate in which 3540VM the object data are stored. In addition to system, global, and local VM, 3541there is a tag for "foreign" VM, which means that the memory is not managed 3542by a Ghostscript allocator at all. Every store into a composite object must 3543check for <b><tt>invalidaccess</tt></b>: the VM space tag values are chosen 3544to help make this check efficient. See <a 3545href="../src/ivmspace.h">src/ivmspace.h</a>, <a 3546href="../src/iref.h">src/iref.h</a>, and <a 3547href="../src/store.h">src/store.h</a> for details. 3548 3549<dl> 3550<dt> 3551Files: 3552<dd> 3553<a href="../src/ivmspace.h">src/ivmspace.h</a>. 3554</dl> 3555 3556<p> 3557PostScript composite objects (arrays and dictionaries) are usually small. 3558Using a separate memory manager object for each composite object would waste 3559a lot of space for object headers. Therefore, the interpreter's memory 3560manager packs multiple composite objects (also called "ref-containing 3561objects") into a single memory manager object, similar to the way the memory 3562manager packs multiple objects into a chunk (see <a 3563href="#Standard_implementation">above</a>). See <a 3564href="../src/gxalloc.h">src/gxalloc.h</a> for details. This memory manager 3565object has a structure descriptor, like all other memory manager objects. 3566 3567<p> 3568Note that the <b><tt>value.pdict</tt></b>, <b><tt>value.refs</tt></b>, or 3569<b><tt>value.packed</tt></b> member of a ref must point to a PostScript 3570composite object, and therefore can point into the middle of a memory 3571manager object. This requires special handling by the garbage collector (<a 3572href="#Interpreter_GC">q.v.</a>). 3573 3574<dl> 3575<dt> 3576Files: 3577<dd> 3578<a href="../src/ialloc.c">src/ialloc.c</a>, 3579<a href="../src/ialloc.h">src/ialloc.h</a>, 3580<a href="../src/iastate.h">src/iastate.h</a>, 3581<a href="../src/iastruct.h">src/iastruct.h</a>, 3582<a href="../src/ilocate.c">src/ilocate.c</a>, 3583<a href="../src/imemory.h">src/imemory.h</a>, 3584<a href="../src/istruct.h">src/istruct.h</a>. 3585</dl> 3586 3587<h4><a name="save_forgetsave_restore"></a>save/.forgetsave/restore</h4> 3588 3589<p> 3590In addition to <b><tt>save</tt></b> and <b><tt>restore</tt></b>, Ghostscript 3591provides a <b><tt>.forgetsave</tt></b> operator that makes things as though 3592a given <b><tt>save</tt></b> had never happened. (In data base terminology, 3593<b><tt>save</tt></b> is "begin transaction", <b><tt>restore</tt></b> is 3594"abort transaction", and <b><tt>.forgetsave</tt></b> is "end/commit 3595transaction"). <b><tt>.forgetsave</tt></b> was implemented for a specific 3596commercial customer (who may no longer even be using it): it was a pain to 3597make work, but it's in the code now, and should be maintained. See the 3598extensive comments in <a href="../src/isave.c">src/isave.c</a> for more 3599information about how these operations work. 3600 3601<dl> 3602<dt> 3603Files: 3604<dd> 3605<a href="../src/idosave.h">src/idosave.h</a>, 3606<a href="../src/isave.c">src/isave.c</a>, 3607<a href="../src/isave.h">src/isave.h</a>, 3608<a href="../src/isstate.h">src/isstate.h</a>, 3609<a href="../src/store.h">src/store.h</a>. 3610</dl> 3611 3612<h4><a name="Stable_allocators"></a>Stable allocators</h4> 3613 3614<p> 3615Even though <b><tt>save</tt></b> and <b><tt>restore</tt></b> are concepts 3616from the PostScript interpreter, the generic allocator architecture and API 3617include a feature to support them, called <em>stable</em> allocators. Every 3618allocator has an associated stable allocator, which tags pointers with the 3619same VM space number but which is not subject to <b><tt>save</tt></b> and 3620<b><tt>restore</tt></b>. System VM is intrinsically stable (its associated 3621stable allocator is the same allocator), so there are only 5 allocators in 3622ordinary single-context usage: system VM, stable global VM, ordinary global 3623VM, stable local VM, ordinary local VM. 3624 3625<p> 3626The reason that we cannot simply allocate all stable objects in system VM is 3627that their refs must still be tagged with the correct VM space number, so 3628that the check against storing pointers from global VM to local VM can be 3629enforced properly. 3630 3631<p> 3632All PostScript objects are normally allocated with the non-stable 3633allocators. The stable allocators should be used with care, since using 3634them can easily create dangling pointers: if storage allocated with a stable 3635allocator contains any references to PostScript objects, the client is 3636responsible for ensuring that the references don't outlive the referenced 3637objects, normally by ensuring that any such referenced objects are allocated 3638at the outermost <b><tt>save</tt></b> level. (The original reason for 3639wanting stable allocators was the PostScript stacks, which are essentially 3640PostScript arrays but are not subject to <b><tt>save</tt></b> and 3641<b><tt>restore</tt></b>.) For more examples, search the sources for 3642references to <b><tt>gs_memory_stable</tt></b>. 3643 3644<h4><a name="Interpreter_GC"></a>Garbage collection</h4> 3645 3646<p> 3647The interpreter's garbage collector is a compacting, non-conservative, 3648mark-and-sweep collector. 3649 3650<ul> 3651<li>It compacts storage because that is the only way to avoid permanent 3652sandbars, which is essential in limited-memory environments. 3653<li>It is non-conservative because conservative collectors (which attempt 3654to determine whether arbitrary bit patterns are pointers) cannot compact. 3655<li>It uses mark-and-sweep, rather than a more modern copying approach, 3656because it cannot afford the extra memory required for copying. 3657</ul> 3658 3659<p> 3660Roots for tracing must be registered with the allocator. Most roots are 3661registered during initialization. 3662 3663<p> 3664"Mark-and-sweep" is a bit of a misnomer. The garbage collector actually has 36655 main phases: 3666 3667<ul> 3668<li>Sweep to clear marks; 3669<li>Trace and mark; 3670<li>Sweep to compute relocation; 3671<li>Sweep to relocate pointers; 3672<li>Sweep and compact. 3673</ul> 3674 3675<p> 3676There is some extra complexity to handle collecting local VM only. In this 3677case, all pointers in global VM are treated as roots, and global VM is not 3678compacted. 3679 3680<p> 3681As noted above, PostScript arrays and strings can have refs that point 3682within them (because of <b><tt>getinterval</tt></b>). Thus the garbage 3683collector must mark each element of an array, and even each byte of a 3684string, individually. Specifically, it marks objects, refs, and strings 3685using 3 different mechanisms: 3686 3687<ul> 3688 3689<li>Objects have a mark bit in their header: see 3690<a href="../src/gxobj.h">src/gxobj.h</a>, 3691 3692<li>Refs and packed refs have a reserved mark bit: see <a 3693href="../src/iref.h">src/iref.h</a> and <a 3694href="../src/ipacked.h">src/ipacked.h</a>. 3695 3696<li>Strings use a separate bit table, with one bit per string byte: see 3697<a href="../src/gxalloc.h">src/gxalloc.h</a>, 3698 3699</ul> 3700 3701<p> 3702Similarly, it records the relocation information for objects, refs, and 3703strings differently: 3704 3705<ul> 3706 3707<li>Objects record relocation in the object header. 3708 3709<li>Refs record relocation in unused fields of refs such as nulls that 3710don't use their <b><tt>value</tt></b> field. Every memory manager object 3711that stores ref-containing objects as described above has an extra, unused 3712ref at the end for this purpose. 3713 3714<li>Strings use a separate relocation table. 3715 3716</ul> 3717 3718<dl> 3719<dt> 3720Files: 3721<dd> 3722<a href="../src/igc.c">src/igc.c</a>, 3723<a href="../src/igc.h">src/igc.h</a>, 3724<a href="../src/igcref.c">src/igcref.c</a>, 3725<a href="../src/igcstr.c">src/igcstr.c</a>, 3726<a href="../src/igcstr.h">src/igcstr.h</a>, 3727<a href="../src/ireclaim.c">src/ireclaim.c</a>. 3728</dl> 3729 3730<hr> 3731 3732<h2><a name="Portability"></a>Portability</h2> 3733 3734<p> 3735One of Ghostscript's most important features is its great portability across 3736platforms (CPUs, operating systems, compilers, and build tools). The code 3737supports portability through two mechanisms: 3738 3739<ul> 3740 3741<li><a href="#Structural">Structural mechanisms</a> -- segregating 3742platform-dependent information into files in a particular way. 3743 3744<li><a href="#Coding">Coding standards</a> -- avoiding relying on byte 3745order, scalar size, and platform-specific compiler or library features. 3746 3747</ul> 3748 3749<h3><a name="Structural"></a>Structural</h3> 3750 3751<h4><a name="CPU_and_compiler"></a>CPU and compiler</h4> 3752 3753<p> 3754Ghostscript attempts to discover characteristics of the CPU and compiler 3755automatically during the build process, by compiling and then executing a 3756program called <b><tt>genarch</tt></b>. <b><tt>genarch</tt></b> generates a 3757file <b><tt>obj/arch.h</tt></b>, which almost all Ghostscript files then 3758include. This works well for things like word size, byte order, and 3759floating point representation, but it can't determine whether or not a 3760compiler supports a particular feature, because if a feature is absent, the 3761compilation may fail. 3762 3763<dl> 3764<dt> 3765Files: 3766<dd> 3767<a href="../src/genarch.c">src/genarch.c</a>, 3768<a href="../obj/arch.h">obj/arch.h</a>. 3769</dl> 3770 3771<h4><a name="Library_headers"></a>Library headers</h4> 3772 3773<p> 3774Despite the supposed standardization of ANSI C, platforms vary considerably 3775in where (and whether) they provide various standard library facilities. 3776Currently, Ghostscript's build process doesn't attempt to sort this out 3777automatically. Instead, for each library header file 3778<b><tt><</tt></b><em>xxx</em><b><tt>.h></tt></b> there is a 3779corresponding Ghostscript source file 3780<b><tt>src/</tt></b><em>xxx</em><b><tt>_.h</tt></b>, containing a set of 3781compile-time conditionals that attempt to select the correct platform header 3782file, or in some cases substitute Ghostscript's own code for a missing 3783facility. You may need to edit these files when moving to platforms with 3784unusually non-standard libraries. 3785 3786<dl> 3787<dt> 3788Files: 3789<dd> 3790<a href="../src/ctype_.h">src/ctype_.h</a>, 3791<a href="../src/dirent_.h">src/dirent_.h</a>, 3792<a href="../src/dos_.h">src/dos_.h</a>, 3793<a href="../src/errno_.h">src/errno_.h</a>, 3794<a href="../src/fcntl_.h">src/fcntl_.h</a>, 3795<a href="../src/jerror_.h">src/jerror_.h</a>, 3796<a href="../src/malloc_.h">src/malloc_.h</a>, 3797<a href="../src/math_.h">src/math_.h</a>, 3798<a href="../src/memory_.h">src/memory_.h</a>, 3799<a href="../src/pipe_.h">src/pipe_.h</a>, 3800<a href="../src/png_.h">src/png_.h</a>, 3801<a href="../src/stat_.h">src/stat_.h</a>, 3802<a href="../src/stdio_.h">src/stdio_.h</a>, 3803<a href="../src/string_.h">src/string_.h</a>, 3804<a href="../src/time_.h">src/time_.h</a>, 3805<a href="../src/unistd_.h">src/unistd_.h</a>, 3806<a href="../src/vmsmath.h">src/vmsmath.h</a>, 3807<a href="../src/windows_.h">src/windows_.h</a>, 3808<a href="../src/x_.h">src/x_.h</a>. 3809</dl> 3810 3811<p> 3812It has been suggested that the GNU <b><tt>configure</tt></b> scripts do the 3813above better, for Unix systems, than Ghostscript's current methods. While 3814this may be true, we have found <b><tt>configure</tt></b> scripts difficult 3815to write, understand, and maintain; and the <b><tt>autoconf</tt></b> tool 3816for generating <b><tt>configure</tt></b> scripts, which we found easy to 3817use, doesn't cover much of the ground that Ghostscript requires. 3818 3819<h4><a name="Cross_platform_APIs"></a>Cross-platform APIs</h4> 3820 3821<p> 3822For a few library facilities that are available on all platforms but are not 3823well standardized, or that may need to be changed for special environments, 3824Ghostscript defines its own APIs. It is an architectural property of 3825Ghostscript that the implementations of these APIs are the only .c files for 3826which the choice of platform (as opposed to choices of drivers or optional 3827features) determines whether they are compiled and linked into an 3828executable. 3829 3830<dl> 3831 3832<dt> 3833API: 3834<dd> 3835<a href="../src/gp.h">src/gp.h</a>, 3836<a href="../src/gpcheck.h">src/gpcheck.h</a>, 3837<a href="../src/gpgetenv.h">src/gpgetenv.h</a>, 3838<a href="../src/gpmisc.h">src/gpmisc.h</a>, 3839<a href="../src/gpsync.h">src/gpsync.h</a>. 3840 3841<dt> 3842Implementation files shared among multiple platforms: 3843<dd> 3844<a href="../src/gp_getnv.c">src/gp_getnv.c</a>, 3845<a href="../src/gp_mktmp.c">src/gp_mktmp.c</a>, 3846<a href="../src/gp_nsync.c">src/gp_nsync.c</a>, 3847<a href="../src/gp_psync.c">src/gp_psync.c</a>, 3848<a href="../src/gp_strdl.c">src/gp_strdl.c</a>, 3849<a href="../src/gpmisc.c">src/gpmisc.c</a>. 3850 3851<dt> 3852Platform-specific implementation files: 3853<dd> 3854<a href="../src/gp_dosfe.c">src/gp_dosfe.c</a>, 3855<a href="../src/gp_dosfs.c">src/gp_dosfs.c</a>, 3856<a href="../src/gp_dvx.c">src/gp_dvx.c</a>, 3857<a href="../src/gp_iwatc.c">src/gp_iwatc.c</a>, 3858<a href="../src/gp_msdos.c">src/gp_msdos.c</a>, 3859<a href="../src/gp_mshdl.c">src/gp_mshdl.c</a>, 3860<a href="../src/gp_msio.c">src/gp_msio.c</a>, 3861<a href="../src/gp_mslib.c">src/gp_mslib.c</a>, 3862<a href="../src/gp_mswin.c">src/gp_mswin.c</a>, 3863<a href="../src/gp_mswin.h">src/gp_mswin.h</a>, 3864<a href="../src/gp_ntfs.c">src/gp_ntfs.c</a>, 3865<a href="../src/gp_os2.c">src/gp_os2.c</a>, 3866<a href="../src/gp_os9.c">src/gp_os9.c</a>, 3867<a href="../src/gp_stdia.c">src/gp_stdia.c</a>, 3868<a href="../src/gp_stdin.c">src/gp_stdin.c</a>, 3869<a href="../src/gp_sysv.c">src/gp_sysv.c</a>, 3870<a href="../src/gp_unifn.c">src/gp_unifn.c</a>, 3871<a href="../src/gp_unifs.c">src/gp_unifs.c</a>, 3872<a href="../src/gp_unix.c">src/gp_unix.c</a>, 3873<a href="../src/gp_vms.c">src/gp_vms.c</a>, 3874<a href="../src/gp_wgetv.c">src/gp_wgetv.c</a>, 3875<a href="../src/gp_win32.c">src/gp_win32.c</a>, 3876<a href="../src/gp_wsync.c">src/gp_wsync.c</a>. 3877 3878</dl> 3879 3880<h4><a name="Makefiles"></a>Makefiles</h4> 3881 3882<p> 3883For information on the structure and conventions used within makefiles, see 3884the <a href="#Makefile_structure">Makefile structure</a> section above. 3885 3886<p> 3887Ghostscript's makefiles are structured very similarly to the cross-platform 3888library files. The great majority of the makefiles are portable across all 3889platforms and all versions of <b><tt>make</tt></b>. To achieve this, the 3890platform-independent makefiles must obey two constraints beyond those of the 3891POSIX <b><tt>make</tt></b> program: 3892 3893<ul> 3894 3895<li>No conditionals or <b><tt>include</tt></b>s are allowed. While most 3896<b><tt>make</tt></b> programs now provide some form of conditional execution 3897and some form of inclusion, there is no agreement on the syntax. 3898(Conditionals and includes are allowed in platform-dependent makefiles; in 3899fact, an inclusion facility is required.) 3900 3901<li>There must be a space on both sides of the : that separates the target 3902of a rule from its dependencies. This is required for compatibility with 3903the OpenVMS <b><tt>MMS</tt></b> and <b><tt>MMK</tt></b> programs. 3904 3905</ul> 3906 3907<p> 3908The top-level makefile for each platform (where "platform" includes the OS, 3909the compiler, and the flavor of <b><tt>make</tt></b>) contains all the build 3910options, plus <b><tt>include</tt></b>s for the generic makefiles and any 3911platform-dependent makefiles that are shared among multiple platforms. 3912 3913<p> 3914While most of the top-level makefiles build a PostScript and/or PDF 3915interpreter configuration, there are also a few makefiles that build a test 3916program that only uses the graphics library without any language 3917interpreter. Among other things, this can be helpful in verifying that no 3918accidental dependencies on the interpreter have crept into the library or 3919drivers. 3920 3921<p> 3922For families of similar platforms, the question arises whether to use 3923multiple top-level makefiles, or whether to use a single top-level makefile 3924that may require minor editing for some (or all) platforms. Ghostscript 3925currently uses the following top-level makefiles for building interpreter 3926configurations: 3927 3928<ul> 3929 3930<li>Unix (including Linux): 3931<ul> 3932<li><a href="../src/unix-gcc.mak">src/unix-gcc.mak</a>, 3933for Unix with gcc. 3934<li><a href="../src/unixansi.mak">src/unixansi.mak</a>, 3935for Unix with an ANSI C compiler other than gcc. 3936<li><a href="../src/unixtrad.mak">src/unixtrad.mak</a>, 3937for Unix with a "traditional" or "K&R" compiler. 3938</ul> 3939 3940<li>PC: 3941<ul> 3942<li><a href="../src/bcwin32.mak">src/bcwin32.mak</a>, 3943for MS Windows with Borland C++ Builder. 3944<li><a href="../src/msvc32.mak">src/msvc32.mak</a>, 3945for MS Windows with Microsoft Visual C (MSVC). 3946<li><a href="../src/os2.mak">src/os2.mak</a>, 3947for MS-DOS or OS/2 GCC/EMX environment. 3948<li><a href="../src/watc.mak">src/watc.mak</a>, 3949for extended MS-DOS with Watcom C. 3950<li><a href="../src/watcw32.mak">src/watcw32.mak</a>, 3951for MS Windows with Watcom C. 3952</ul> 3953 3954<li>Macintosh: 3955<ul> 3956<li><a href="../src/macos-mcp.mak">src/macos-mcp.mak</a>, 3957for Macintosh MCP. 3958</ul> 3959 3960 3961<li>Other: 3962<ul> 3963<li><a href="../src/all-arch.mak">src/all-arch.mak</a>, 3964for building on many Unix systems in a networked test environment. 3965<li><a href="../src/dvx-gcc.mak">src/dvx-gcc.mak</a>, 3966for DesqView/X with gcc. 3967<li><a href="../src/openvms.mak">src/openvms.mak</a>, 3968for OpenVMS with Digital's CC compiler and the MMS build program. 3969<li><a href="../src/openvms.mmk">src/openvms.mmk</a>, 3970for OpenVMS with Digital's CC compiler and the MMK build program. 3971</ul> 3972 3973</ul> 3974 3975<p> 3976The following top-level makefiles build the library test program: 3977 3978<ul> 3979<li><a href="../src/ugcclib.mak">src/ugcclib.mak</a>, 3980on Unix with gcc. 3981<li><a href="../src/msvclib.mak">src/msvclib.mak</a>, 3982on MS Windows with MSVC. 3983<li><a href="../src/watclib.mak">src/watclib.mak</a>, 3984on extended MS-DOS with Watcom C. 3985</ul> 3986 3987<p> 3988The MSVC makefiles may require editing to select between different versions 3989of MSVC, since different versions may have slightly incompatible command 3990line switches or customary installation path names. The Unix makefiles 3991often require editing to deal with differing library path names and/or 3992library names. For details, see <a href="Make.htm#Unix_build">the Unix 3993section</a> of the documentation for building Ghostscript. 3994 3995<dl> 3996 3997<dt> 3998Library test program: 3999<dd> 4000<a href="../src/gslib.c">src/gslib.c</a>. 4001 4002<dt> 4003Platform-independent makefiles: 4004<dd> 4005 4006<dl> 4007 4008<dt> 4009Graphics library and support: 4010<dd> 4011<a href="../src/contrib.mak">src/contrib.mak</a>, 4012<a href="../src/devs.mak">src/devs.mak</a>, 4013<a href="../src/gs.mak">src/gs.mak</a>, 4014<a href="../src/lib.mak">src/lib.mak</a>, 4015<a href="../src/version.mak">src/version.mak</a>. 4016 4017<dt> 4018PostScript interpreter and fonts: 4019<dd> 4020<a href="../src/cfonts.mak">src/cfonts.mak</a>, 4021<a href="../src/int.mak">src/int.mak</a>, 4022<a href="../src/wmin.mak">src/wmin.mak</a>. 4023 4024<dt> 4025Third-party libraries: 4026<dd> 4027<a href="../src/icclib.mak">src/icclib.mak</a>, 4028<a href="../src/ijs.mak">src/ijs.mak</a>, 4029<a href="../src/jpeg.mak">src/jpeg.mak</a>, 4030<a href="../src/libpng.mak">src/libpng.mak</a>, 4031<a href="../src/zlib.mak">src/zlib.mak</a>. 4032 4033</dl> 4034 4035<dt> 4036Shared platform-dependent makefiles: 4037<dd> 4038 4039<dl> 4040 4041<dt> 4042Unix: 4043<dd> 4044<a href="../src/unix-aux.mak">src/unix-aux.mak</a>, 4045<a href="../src/unix-dll.mak">src/unix-dll.mak</a>, 4046<a href="../src/unix-end.mak">src/unix-end.mak</a>, 4047<a href="../src/unixhead.mak">src/unixhead.mak</a>, 4048<a href="../src/unixinst.mak">src/unixinst.mak</a>, 4049<a href="../src/unixlink.mak">src/unixlink.mak</a>. 4050 4051<dt> 4052Microsoft Windows and MS-DOS: 4053<dd> 4054<a href="../src/msvccmd.mak">src/msvccmd.mak</a>, 4055<a href="../src/msvctail.mak">src/msvctail.mak</a>, 4056<a href="../src/pcwin.mak">src/pcwin.mak</a>, 4057<a href="../src/wccommon.mak">src/wccommon.mak</a>, 4058<a href="../src/wctail.mak">src/wctail.mak</a>, 4059<a href="../src/winint.mak">src/winint.mak</a>, 4060<a href="../src/winlib.mak">src/winlib.mak</a>, 4061<a href="../src/winplat.mak">src/winplat.mak</a>. 4062 4063<dt> 4064Other: 4065<dd> 4066<a href="../src/dvx-head.mak">src/dvx-head.mak</a>, 4067<a href="../src/dvx-tail.mak">src/dvx-tail.mak</a>. 4068 4069</dl> 4070 4071</dl> 4072 4073<h3><a name="Coding"></a>Coding</h3> 4074 4075<p> 4076Coding for portability requires avoiding both <em>explicit</em> 4077dependencies, such as platform-dependent <b><tt>#ifdef</tt></b>s, and 4078<em>implicit</em> dependencies, such as dependencies on byte order or the 4079size of the integral types. 4080 4081<h4><a name="Explicit_dependencies"></a>Explicit dependencies</h4> 4082 4083<p> 4084The platform-independent .c files never, ever, use <b><tt>#ifdef</tt></b> or 4085<b><tt>#if</tt></b> to select code for specific platforms. Instead, we 4086always try to characterize some abstract property that is being tested. For 4087example, rather than checking for macros that are defined on those specific 4088platforms that have 64-bit <b><tt>long</tt></b> values, we define a macro 4089<b><tt>ARCH_SIZEOF_LONG</tt></b> that can then be tested. Such macros are 4090always defined in a .h file, either automatically in <b><tt>arch.h</tt></b>, 4091or explicitly in a <em>xxx</em><b><tt>_.h</tt></b> file, as described in 4092earlier sections. 4093 4094<dl> 4095<dt> 4096Files: 4097<dd> 4098<a href="../src/std.h">src/std.h</a>, 4099<a href="../src/stdpre.h">src/stdpre.h</a>. 4100</dl> 4101 4102<h4><a name="Implicit_dependencies"></a>Implicit dependencies</h4> 4103 4104<p> 4105The most common source of byte ordering dependencies is casting between 4106types (T1 *) and (T2 *) where T1 and T2 are numeric types that aren't merely 4107signed/unsigned variants of each other. To avoid this, the only casts 4108allowed in the code are between numeric types, from a pointer type to a long 4109integral type, and between pointer types. 4110 4111<p> 4112Ghostscript's code assumes the following about the sizes of various types: 4113 4114<dl> 4115<dt>char<dd>8 bits 4116<dt>short<dd>16 bits 4117<dt>int<dd>32 or 64 bits 4118<dt>long<dd>32 or 64 bits 4119<dt>float<dd>32 bits (may work with 64 bits) 4120<dt>double<dd>64 bits (may work with 128 bits) 4121</dl> 4122 4123<p> 4124The code does not assume that the <b><tt>char</tt></b> type is signed (or 4125unsigned); except for places where the value is always a literal string, or 4126for interfacing to library procedures, the code uses <b><tt>byte</tt></b> (a 4127Ghostscript synonym for <b><tt>unsigned char</tt></b>) almost everywhere. 4128 4129<p> 4130Pointers are signed on some platforms and unsigned on others. In the few 4131places in the memory manager where it's necessary to reliably order-compare 4132(as opposed to equality-compare) pointers that aren't known to point to the 4133same allocated block of memory, the code uses the 4134<b><tt>PTR_</tt></b><em>relation</em> macros rather than direct comparisons. 4135 4136<p> 4137See the files listed above for other situations where a macro provides 4138platform-independence or a workaround for bugs in specific compilers or 4139libraries (of which there are a distressing number). 4140 4141<h4><a name="Platform_specific_code"></a>Platform-specific code</h4> 4142 4143<p> 4144There are some features that are inherently platform-specific: 4145 4146<ul> 4147 4148<li>Microsoft Windows requires a lot of special top-level code, and also has 4149an installer and uninstaller. 4150 4151<li>OS/2 requires a little special code. 4152 4153<li>MacOS also requires special top-level code (now distributed with the 4154standard Ghostscript package). 4155 4156<li>All platforms supporting DLLs (currently all three of the above) share 4157some special top-level code. 4158 4159</ul> 4160 4161<dl> 4162 4163<dt> 4164MS Windows files: 4165<dd> 4166<a href="../src/dpmain.c">src/dpmain.c</a>, 4167<a href="../src/dwdll.c">src/dwdll.c</a>, 4168<a href="../src/dwdll.h">src/dwdll.h</a>, 4169<a href="../src/dwimg.c">src/dwimg.c</a>, 4170<a href="../src/dwimg.h">src/dwimg.h</a>, 4171<a href="../src/dwinst.cpp">src/dwinst.cpp</a>, 4172<a href="../src/dwinst.h">src/dwinst.h</a>, 4173<a href="../src/dwmain.c">src/dwmain.c</a>, 4174<a href="../src/dwmain.h">src/dwmain.h</a>, 4175<a href="../src/dwmainc.c">src/dwmainc.c</a>, 4176<a href="../src/dwnodll.c">src/dwnodll.c</a>, 4177<a href="../src/dwreg.c">src/dwreg.c</a>, 4178<a href="../src/dwreg.h">src/dwreg.h</a>, 4179<a href="../src/dwsetup.cpp">src/dwsetup.cpp</a>, 4180<a href="../src/dwsetup.h">src/dwsetup.h</a>, 4181<a href="../src/dwtext.c">src/dwtext.c</a>, 4182<a href="../src/dwtext.h">src/dwtext.h</a>, 4183<a href="../src/dwuninst.cpp">src/dwuninst.cpp</a>, 4184<a href="../src/dwuninst.h">src/dwuninst.h</a>, 4185<a href="../src/gp_msdll.c">src/gp_msdll.c</a>, 4186<a href="../src/gp_mspol.c">src/gp_mspol.c</a>, 4187<a href="../src/gp_msprn.c">src/gp_msprn.c</a>, 4188<a href="../src/gs16spl.c">src/gs16spl.c</a>, 4189<a href="../src/gsdllwin.h">src/gsdllwin.h</a>. 4190 4191<dt> 4192OS/2 files: 4193<dd> 4194<a href="../src/gsdllos2.h">src/gsdllos2.h</a>. 4195 4196<dt> 4197Unix files: 4198<dd> 4199<a href="../src/dxmain.c">src/dxmain.c</a>. 4200<a href="../src/dxmainc.c">src/dxmainc.c</a>. 4201 4202<dt> 4203Macintosh files: 4204<dd> 4205<a href="../src/gdevmac.c">src/gdevmac.c</a>. 4206<a href="../src/gdevmac.h">src/gdevmac.h</a>. 4207<a href="../src/gdevmacpictop.h">src/gdevmacpictop.h</a>. 4208<a href="../src/gdevmacttf.h">src/gdevmacttf.h</a>. 4209<a href="../src/gdevmacxf.c">src/gdevmacxf.c</a>. 4210<a href="../src/gp_mac.c">src/gp_mac.c</a>. 4211<a href="../src/gp_mac.h">src/gp_mac.h</a>. 4212<a href="../src/gp_macio.c">src/gp_macio.c</a>. 4213<a href="../src/macgenmcpxml.sh">src/macgenmcpxml.sh</a>. 4214<a href="../src/macsysstat.h">src/macsysstat.h</a>. 4215<a href="../src/macsystypes.h">src/macsystypes.h</a>. 4216 4217<dt> 4218VMS files: 4219<dd> 4220<a href="../src/vms_x_fix.h">src/vms_x_fix.h</a>. 4221 4222<dt> 4223DLL files: 4224<dd> 4225<a href="../src/gsdll.c">src/gsdll.c</a>, 4226<a href="../src/gsdll.h">src/gsdll.h</a>, 4227<a href="../src/gdevdsp.c">src/gdevdsp.c</a>, 4228<a href="../src/gdevdsp.h">src/gdevdsp.h</a>, 4229<a href="../src/gdevdsp2.h">src/gdevdsp2.h</a>, 4230<a href="../src/iapi.c">src/iapi.c</a>, 4231<a href="../src/iapi.h">src/iapi.h</a>, 4232<a href="../src/idisp.c">src/idisp.c</a>, 4233<a href="../src/idisp.h">src/idisp.h</a>. 4234<p> 4235The new DLL interface (new as of 7.0) is especially useful with the 4236new display device, so it is included here. Both are due to Russell 4237Lang. 4238 4239</dl> 4240 4241 4242<hr> 4243 4244<h2><a name="Adding_features_and_options"></a>Adding features and options</h2> 4245 4246<p> 4247[Ray, please supply more information about what you want here] 4248 4249<h2><a name="Troubleshooting"></a>Troubleshooting</h2> 4250 4251<p> 4252The Ghostscript code has many tracing and debugging features that can be 4253enabled at run time using the <b><tt>-Z</tt></b> command line switch, if the 4254executable was compiled with <b><tt>DEBUG</tt></b> defined. One 4255particularly useful combination is <b><tt>-Z@\?</tt></b>, which fills free 4256memory blocks with a pattern and also turns on run-time memory consistency 4257checking. For more information, see <a 4258href="Use.htm#Debugging">doc/Use.htm#Debugging</a>; you can also search for 4259occurrences of <b><tt>if_debug</tt></b> or <b><tt>gs_debug_c</tt></b> in the 4260source code. Note that many of these features are in the graphics library 4261and do not require a PostScript interpreter. 4262 4263<p> 4264The code also contains many run-time procedures whose only purpose is to be 4265called from the debugger to print out various data structures, including all 4266the procedures in <a href="../src/idebug.c">src/idebug.c</a> (for the 4267PostScript interpreter) and the <b><tt>debug_dump_</tt></b> procedures in <a 4268href="../src/gsmisc.c">src/gsmisc.c</a>. 4269 4270<dl> 4271<dt> 4272Files: 4273<dd> 4274<a href="Use.htm#Debugging">doc/Use.htm#Debugging</a>, 4275<a href="../src/gdebug.h">src/gdebug.h</a>, 4276<a href="../src/gsmdebug.h">src/gsmdebug.h</a>, 4277<a href="../src/idebug.h">src/idebug.h</a>, 4278<a href="../src/idebug.c">src/idebug.c</a>. 4279</dl> 4280 4281<!-- [2.0 end contents] ==================================================== --> 4282 4283<!-- [3.0 begin visible trailer] =========================================== --> 4284<hr> 4285 4286<p> 4287<small>Copyright © 2001 artofcode LLC. 4288All rights reserved.</small> 4289 4290<p> 4291<small>This file is part of AFPL Ghostscript. See the <a 4292href="Public.htm">Aladdin Free Public License</a> (the "License") for full 4293details of the terms of using, copying, modifying, and redistributing 4294AFPL Ghostscript.</small> 4295 4296<p> 4297<small>Ghostscript version 7.04, 31 January 2002 4298 4299<!-- [3.0 end visible trailer] ============================================= --> 4300 4301</body> 4302</html> 4303