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