123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302 |
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <head>
- <title>Information for Ghostscript developers</title>
- <link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
- <!-- $Id: Develop.htm,v 1.47.2.3 2002/02/01 05:31:24 raph Exp $ -->
- </head>
- <body>
- <!-- [1.0 begin visible header] ============================================ -->
- <!-- [1.1 begin headline] ================================================== -->
- <h1>Information for Ghostscript developers</h1>
- <!-- [1.1 end headline] ==================================================== -->
- <!-- [1.2 begin table of contents] ========================================= -->
- <h2>Table of contents</h2>
- <blockquote><ul>
- <li><a href="#Introduction">Introduction</a>
- <li><a href="#Architecture">Architecture</a>
- <ul>
- <li><a href="#Design_goals">Design goals</a>
- <li><a href="#Design_principles">Design principles</a>
- <li><a href="#Large_scale_structure">Large-scale structure</a>
- <li><a href="#Object_oriented_constructs">Object-oriented constructs</a>
- </ul>
- <li><a href="#File_roadmap">File roadmap</a>
- <ul>
- <li><a href="#Substrate">Substrate</a>
- <li><a href="#Graphics_library">Graphics library</a>
- <ul>
- <li><a href="#Library_support">Support</a>,
- <a href="#Paths">Paths</a>,
- <a href="#Text">Text</a>,
- <a href="#Images">Images</a>,
- <a href="#Paint">Paint</a>,
- <a href="#Clipping">Clipping</a>,
- <a href="#Other_graphics">Other graphics</a>,
- <a href="#Driver_support">Driver support</a>
- </ul>
- <li><a href="#Device_drivers">Device drivers</a>
- <ul>
- <li><a href="#Internal_devices">Internal devices</a>,
- <a href="#PS_and_PDF_writers">PostScript and PDF writers</a>,
- <a href="#High_level_devices">Other high-level devices</a>,
- <a href="#Other_maintained_drivers">Other maintained drivers</a>,
- <a href="#Contributed_drivers">Contributed drivers</a>
- </ul>
- <li><a href="#PostScript_interpreter">PostScript interpreter</a>
- <ul>
- <li><a href="#Main_program">Main program</a>,
- <a href="#Data_structures">Data structures</a>,
- <a href="#Interpreter_loop">Interpreter loop</a>,
- <a href="#Scanning_parsing">Scanning/parsing</a>,
- <a href="#Standard_operators">Standard operators</a>,
- <a href="#Non_standard_operators">Non-standard operators</a>,
- <a href="#Interpreter_support">Interpreter support</a>,
- <a href="#PostScript_code">PostScript code</a>
- </ul>
- <li><a href="#PDF_interpreter">PDF interpreter</a>
- <li><a href="#Build_process">Build process</a>
- <ul>
- <li><a href="#Makefile_structure">Makefile structure</a>,
- <a href="#dev_files">.dev files</a>,
- <a href="#Generators">Generators</a>,
- <a href="#Build_support">Support</a>
- </ul>
- <li><a href="#Utilities">Utilities</a>
- <ul>
- <li><a href="#Utilities_in_PostScript">Utilities in PostScript</a>
- <li><a href="#Utility_scripts">Utility scripts</a>
- </ul>
- </ul>
- <li><a href="#Memory_management">Memory management</a>
- <ul>
- <li><a href="#Memory_manager_architecture">Memory manager architecture</a>
- <ul>
- <li><a href="#Objects_vs_strings">Objects vs strings</a>,
- <a href="#Structure_descriptors">Structure descriptors</a>,
- <a href="#Garbage_collection">Garbage collection</a>,
- <a href="#Movability">Movability</a>,
- <a href="#Parent_hierarchy">Parent hierarchy</a>,
- <a href="#Allocator_API">Allocator API</a>
- </ul>
- <li><a href="#Freeing_storage">Freeing storage</a>
- <ul>
- <li><a href="#Explicit_freeing">Explicit freeing</a>,
- <a href="#Reference_counting">Reference counting</a>,
- <a href="#Real_garbage_collection">(Real) garbage collection</a>
- </ul>
- <li><a href="#Special_implementations">Special implementations</a>
- <ul>
- <li><a href="#malloc">malloc</a>,
- <a href="#Locking">Locking</a>,
- <a href="#Retrying">Retrying</a>
- </ul>
- <li><a href="#Standard_implementation">Standard implementation</a>
- <li><a href="#PostScript_interpreter_extensions">PostScript interpreter extensions</a>
- <ul>
- <li><a href="#Refs">Refs (PostScript "objects")</a>,
- <a href="#save_forgetsave_restore">save/.forgetsave/restore</a>,
- <a href="#Stable_allocators">Stable allocators</a>,
- <a href="#Interpreter_GC">Garbage collection</a>
- </ul>
- </ul>
- <li><a href="#Portability">Portability</a>
- <ul>
- <li><a href="#Structural">Structural</a>
- <ul>
- <li><a href="#CPU_and_compiler">CPU and compiler</a>,
- <a href="#Library_headers">Library headers</a>,
- <a href="#Cross_platform_APIs">Cross-platform APIs</a>,
- <a href="#Makefiles">Makefiles</a>
- </ul>
- <li><a href="#Coding">Coding</a>
- <ul>
- <li><a href="#Explicit_dependencies">Explicit dependencies</a>,
- <a href="#Implicit_dependencies">Implicit dependencies</a>
- </ul>
- <li><a href="#Platform_specific_code">Platform-specific code</a>
- </ul>
- <li><a href="#Adding_features_and_options">Adding features and options</a>
- <li><a href="#Troubleshooting">Troubleshooting</a>
- </ul></blockquote>
- <!-- [1.2 end table of contents] =========================================== -->
- <!-- [1.3 begin hint] ====================================================== -->
- <p>For other information, see the <a href="Readme.htm">Ghostscript
- overview</a> and the documentation related to <a
- href="Maintain.htm">maintaining Ghostscript</a>.
- <!-- [1.3 end hint] ======================================================== -->
- <hr>
- <!-- [1.0 end visible header] ============================================== -->
- <!-- [2.0 begin contents] ================================================== -->
- <h2><a name="Introduction"></a>Introduction</h2>
- <p>
- This document provides a wealth of information about Ghostscript's
- internals, primarily for developers actively working on Ghostscript. It is
- primarily <strong>descriptive</strong>, documenting the way things are; the
- companion <a href="C-style.htm">C style guide</a> is primarily
- <strong>prescriptive</strong>, documenting what developers should do when
- writing new code.
- <p>
- THIS FILE IS A WORK IN PROGRESS. MANY SECTIONS ARE PLACE-HOLDERS.
- <h2><a name="Architecture"></a>Architecture</h2>
- <h3><a name="Design_goals"></a>Design goals</h3>
- <p>
- Ghostscript has the following high-level design goals (not listed in order
- of importance):
- <ul>
- <li>Functionality
- <ul>
- <li>Ability to interpret the current PostScript and PDF languages, as
- defined (and occasionally, in the case of conflict, as implemented) by
- Adobe.
- <li>Ability to convert PostScript to and from PDF, comparable to
- Adobe products.
- <li>Ability to produce output for a wide range of resolutions (from
- TV-resolution displays to imagesetters) and color models (black and white,
- multilevel gray, bilevel or multi-level RGB and CMYK, 6- or 8-color
- inkjet printers, spot color).
- </ul>
- <li>Performance
- <ul>
- <li>Ability to render PostScript and PDF with commercial-quality performance
- (memory usage, speed, and output quality) on all platforms.
- <li>Specifically, ability to render PostScript effectively in embedded
- environments with constrained RAM, including the ability to put the code and
- supporting data in ROM.
- </ul>
- <li>Licensing
- <ul>
- <li>Licensing that supports both the Open Source / Free software communities
- and a commercial licensing business.
- <li>Freedom from licensing restrictions or fees imposed by third parties.
- </ul>
- <li>Other
- <ul>
- <li>Easy source portability to any platform (CPU, operating system, and
- development tools) that has an ANSI or K&R C compiler.
- <li>Support for writing new interpreters and new drivers with no change to
- any existing code; specifically, ability to support PCL 5e, PCL 5c, and PCL
- XL interpreters, and the ever-changing roster of inkjet printers.
- </ul>
- </ul>
- <p>
- These goals often conflict: part of Ghostscript's claim to quality is that
- the conflicts have been resolved well.
- <h3><a name="Design_principles"></a>Design principles</h3>
- <p>
- Part of what has kept Ghostscript healthy through many years of major code
- revisions and functional expansion is consistent and conscientious adherence
- to a set of design principles. We hope the following list captures the most
- important ones.
- <h4>Non-preemption</h4>
- <p>
- Ghostscript is designed to be used as a component. As such, it must share
- its environment with other components. Therefore, it must not require
- ownership of, or make decisions about, inherently shared resources.
- Specifically, it must not assume that it can "own" either the locus of
- control or the management of the address space.
- <p>
- Not owning control means that whenever Ghostscript passes control to its
- caller, it must do so in a way that doesn't constrain what the caller can do
- next. The caller must be able to call any other piece of software, wait for
- an external event, execute another task, etc., without having to worry about
- Ghostscript being in an unknown state. While this is easy to arrange in a
- multi-threaded environment (by running Ghostscript in a separate thread),
- multi-threading APIs are not well standardized at this time (December 2000),
- and may not be implemented efficiently, or at all, on some platforms.
- Therefore, Ghostscript must choose between only two options for interacting
- with its caller: to <em>return</em>, preserving its own state in data
- structures, or to <em>call back</em> through a caller-supplied procedure.
- Calling back constrains the client program unacceptably: the callback
- procedure only has the options of either returning, or aborting Ghostscript.
- In particular, if it wants (for whatever reason) to multi-task Ghostscript
- with another program, it cannot do so in general, especially if the other
- program also uses callback rather than suspension. Therefore, Ghostscript
- tries extremely hard to return, rather than calling back, for all caller
- interaction. In particular:
- <ul>
- <li>For callers that want to pass input to Ghostscript piece by piece,
- Ghostscript returns with an <b><tt>e_NeedInput</tt></b> code rather than
- using a callback. This allows the caller complete flexibility in its
- control structure for managing the source of input. (It might, for example,
- be generating the input dynamically.)
- <li>In the future, the same arrangement should be used for input from
- <b><tt>stdin</tt></b> and output to <b><tt>stdout</tt></b> and
- <b><tt>stderr</tt></b>.
- <li>Likewise, scheduling of Ghostscript's own threads (contexts), currently
- done with a callback, should be done with suspension. The Display
- Ghostscript project (GNU DGS) is working on this.
- </ul>
- <p>
- The one area where suspension is not feasible with Ghostscript's current
- architecture is device output. Device drivers are called from deep within
- the graphics library. (If Ghostscript were being redesigned from scratch,
- we might try to do this with suspension as well, or at least optional
- suspension.)
- <p>
- Not owning management of the address space means that even though
- Ghostscript supports garbage collection for its own data, it must not do any
- of the things that garbage collection schemes for C often require: it must
- not replace 'malloc' and 'free', must not require its clients to use its own
- allocator, must not rely on manipulating the read/write status of memory
- pages, must not require special compiler or run-time support (e.g., APIs for
- scanning the C stack), must not depend on the availability of
- multi-threading, and must not take possession of one of a limited number of
- timer interrupts. However, in order not to constrain its own code unduly,
- it must also not require using special macros or calls to enter or leave
- procedures or assign pointers, and must not constrain the variety of C data
- structures any more than absolutely necessary. It achieves all of these
- goals, at the expense of some complexity, some performance cost (mostly for
- garbage collection), and some extra manual work required for each structure
- type allocated by its allocator. The details appear in the <a
- href="#Memory_management">Memory management</a> section below.
- <h4>Multi-instantiability</h4>
- <p>
- From many years of experience with the benefits of object-oriented design,
- we have learned that when the word "the" appears in a software design --
- "the" process scheduler, "the" memory manager, "the" output device, "the"
- interpreter, "the" stack -- it often flags an area in which the software
- will have difficulty adapting to future needs. For this reason, Ghostscript
- attempts to make every internal structure capable of existing in multiple
- instances. For example, Ghostscript's memory manager is not a one-of-a-kind
- entity with global state and procedures: it is (or rather they are, since
- Ghostscript has multiple memory managers, some of which have multiple
- instances) objects with their own state and (virtual) procedures.
- Ghostscript's PostScript interpreter has no writable non-local data
- (necessary, but not sufficient, to allow multiple instances), and in the
- future will be extended to be completely reentrant and instantiable. The
- device driver API is designed to make this easy for drivers as well. The
- graphics library is currently not completely reentrant or instantiable: we
- hope this will occur in the future.
- <h4>Late configuration binding</h4>
- <p>
- Ghostscript is designed to make configuration choices as late as possible,
- subject to simplicity and performance considerations. The major binding
- times for such choices are compilation, linking, startup, and dynamic.
- <ul>
- <li>Compilation binds only CPU and compiler characteristics (including data
- type size, presence of floating point hardware, and data alignment), and
- whether the code will be used for production, debugging, or profiling.
- <li>Linking binds the choice of what features and device drivers will be
- included in the executable. (Work is underway to make the choice of drivers
- dynamic.)
- <li>Startup binds essentially nothing. Almost every option and parameter
- that can appear on the command line can also be changed dynamically.
- <li>The selection of output device, all parameters associated with the
- device, the selection of debugging printout and self-checking (in debugging
- configurations), the macro-allocation of memory, and almost all other
- operational parameters are dynamic.
- </ul>
- <p>
- In addition, a number of major implementation decisions are made dynamically
- depending on the availability of resources. For example, Ghostscript
- chooses between banded and non-banded rendering depending on memory
- availability.
- <h3><a name="Large_scale_structure"></a>Large-scale structure</h3>
- <p>
- At the largest design scale, Ghostscript consists of 4 layers. Layer N
- is allowed to use the facilities of all layers M <= N.
- <ol>
- <li>The bottom layer is called the <a href="#Substrate">substrate</a>. It
- includes facilities like memory management, streams, fixed-point arithmetic,
- and low-level interfaces to the operating system. The substrate is written
- in C, with a little C++ and/or assembler code for some platforms.
- <li>The layer above the substrate is the graphics layer. It consists of two
- separate sub-parts. The graphics layer is written in C.
- <ul>
- <li>The <a href="#Graphics_library">graphics library</a> manages graphics
- state information for, and decomposes and renders 2-D images described
- using, a graphics model that is approximately the union of those of
- PostScript, PDF, and PCL 5e/5c/XL.
- <li>The <a href="#Device_drivers">device drivers</a> are called by the
- graphics library to produce actual output. The graphics library, and all
- higher layers, call device driver procedures only through virtual functions.
- </ul>
- <li>The principal clients of the graphics layer are language interpreters.
- Ghostscript as distributed includes the <a
- href="#PostScript_interpreter">PostScript interpreter</a>; there are also
- interpreters for PCL 5e, PCL 5c, and PCL XL, which are not currently freely
- redistributable and are not included in the standard Ghostscript package.
- The PostScript interpreter is written partly in C and partly in PostScript.
- <li>The <a href="#PDF_interpreter">PDF interpreter</a> is actually a client
- of the PostScript interpreter: it is written entirely in PostScript.
- </ol>
- <p>
- The most important interface in Ghostscript is the API between the graphics
- library and the device drivers: new printers (and, to a lesser extent,
- window systems, displays, plotters, film recorders, and graphics file
- formats) come on the scene frequently, and it must be possible to produce
- output for them with a minimum of effort and distruption. This API is the
- only one that is extensively documented (see <a
- href="Drivers.htm">Drivers.htm</a>) and kept stringently backward-compatible
- through successive releases.
- <h3><a name="Object_oriented_constructs"></a>Object-oriented constructs</h3>
- <p>
- Ghostscript makes heavy use of object-oriented constructs, including
- analogues of classes, instances, subclassing, and class-associated
- procedures. Since Ghostscript is written in C, not C++, implementing these
- constructs requires following coding conventions. The <a
- href="C-style.htm#Objects">"Objects"</a> section of the C style guide
- explains these.
- <p>
- The memory manager API provides run-time type information about each class,
- but this information does not include anything about subclassing. See under
- <a href="#Structure_descriptors">Structure descriptors</a> below.
- <hr>
- <h2><a name="File_roadmap"></a>File roadmap</h2>
- <p>
- This section of the document provides a roadmap to all of the Ghostscript
- source files.
- <h3><a name="Substrate"></a>Substrate</h3>
- <h4>Memory manager</h4>
- <p>
- See <a href="#Memory_management">below</a>.
- <h4>Streams</h4>
- <dl>
- <dt>
- Framework, file and string streams:
- <dd>
- <a href="../src/gsdsrc.c">src/gsdsrc.c</a>,
- <a href="../src/gsdsrc.h">src/gsdsrc.h</a>,
- <a href="../src/scommon.h">src/scommon.h</a>,
- <a href="../src/sfxboth.c">src/sfxboth.c</a>,
- <a href="../src/sfxfd.c">src/sfxfd.c</a>,
- <a href="../src/sfxstdio.c">src/sfxstdio.c</a>,
- <a href="../src/stream.h">src/stream.h</a>,
- <a href="../src/stream.c">src/stream.c</a>,
- <a href="../src/strimpl.h">src/strimpl.h</a>.
- <dt>
- Standard filters:
- <dd>
- <dl>
- <dt>
- CCITTFax:
- <dd>
- <a href="../src/scf.h">src/scf.h</a>,
- <a href="../src/scfd.c">src/scfd.c</a>,
- <a href="../src/scfdgen.c">src/scfdgen.c</a>,
- <a href="../src/scfdtab.c">src/scfdtab.c</a>,
- <a href="../src/scfe.c">src/scfe.c</a>,
- <a href="../src/scfetab.c">src/scfetab.c</a>,
- <a href="../src/scfparam.c">src/scfparam.c</a>,
- <a href="../src/scfx.h">src/scfx.h</a>.
- <dt>
- DCT (JPEG):
- <dd>
- <a href="../src/gsjconf.h">src/gsjconf.h</a>,
- <a href="../src/gsjmorec.h">src/gsjmorec.h</a>,
- <a href="../src/sdcparam.c">src/sdcparam.c</a>,
- <a href="../src/sdcparam.h">src/sdcparam.h</a>,
- <a href="../src/sdct.h">src/sdct.h</a>,
- <a href="../src/sdctc.c">src/sdctc.c</a>,
- <a href="../src/sdctd.c">src/sdctd.c</a>,
- <a href="../src/sdcte.c">src/sdcte.c</a>,
- <a href="../src/sddparam.c">src/sddparam.c</a>,
- <a href="../src/sdeparam.c">src/sdeparam.c</a>,
- <a href="../src/sjpeg.h">src/sjpeg.h</a>,
- <a href="../src/sjpegc.c">src/sjpegc.c</a>,
- <a href="../src/sjpegd.c">src/sjpegd.c</a>,
- <a href="../src/sjpege.c">src/sjpege.c</a>.
- <dt>
- Other compression/decompression:
- <dd>
- <a href="../src/slzwc.c">src/slzwc.c</a>,
- <a href="../src/slzwce.c">src/slzwce.c</a>,
- <a href="../src/slzwd.c">src/slzwd.c</a>,
- <a href="../src/slzwx.h">src/slzwx.h</a>,
- <a href="../src/srld.c">src/srld.c</a>,
- <a href="../src/srle.c">src/srle.c</a>,
- <a href="../src/srlx.h">src/srlx.h</a>.
- <dt>
- Other:
- <dd>
- <a href="../src/sa85d.c">src/sa85d.c</a>,
- <a href="../src/sa85d.h">src/sa85d.h</a>,
- <a href="../src/sa85x.h">src/sa85x.h</a>,
- <a href="../src/sfilter1.c">src/sfilter1.c</a>,
- <a href="../src/sfilter2.c">src/sfilter2.c</a>,
- <a href="../src/sstring.c">src/sstring.c</a>,
- <a href="../src/sstring.h">src/sstring.h</a>.
- </dl>
- <dt>
- Non-standard filters used to implement standard filters:
- <dd>
- <a href="../src/seexec.c">src/seexec.c</a>,
- <a href="../src/sfilter.h">src/sfilter.h</a>,
- <a href="../src/shc.c">src/shc.c</a>,
- <a href="../src/shc.h">src/shc.h</a>,
- <a href="../src/shcgen.c">src/shcgen.c</a>,
- <a href="../src/shcgen.h">src/shcgen.h</a>,
- <a href="../src/spdiff.c">src/spdiff.c</a>,
- <a href="../src/spdiffx.h">src/spdiffx.h</a>,
- <a href="../src/spngp.c">src/spngp.c</a>,
- <a href="../src/spngpx.h">src/spngpx.h</a>,
- <a href="../src/szlibc.c">src/szlibc.c</a>,
- <a href="../src/szlibd.c">src/szlibd.c</a>,
- <a href="../src/szlibe.c">src/szlibe.c</a>,
- <a href="../src/szlibx.h">src/szlibx.h</a>,
- <a href="../src/szlibxx.h">src/szlibxx.h</a>.
- <dt>
- Non-standard filters:
- <dd>
- <a href="../src/sbcp.c">src/sbcp.c</a>,
- <a href="../src/sbcp.h">src/sbcp.h</a>,
- <a href="../src/sbhc.c">src/sbhc.c</a>,
- <a href="../src/sbhc.h">src/sbhc.h</a>,
- <a href="../src/sbtx.h">src/sbtx.h</a>,
- <a href="../src/sbwbs.c">src/sbwbs.c</a>,
- <a href="../src/sbwbs.h">src/sbwbs.h</a>,
- <a href="../src/smd5.c">src/smd5.c</a>,
- <a href="../src/smd5.h">src/smd5.h</a>,
- <a href="../src/sarc4.c">src/sarc4.c</a>,
- <a href="../src/sarc4.h">src/sarc4.h</a>,
- <a href="../src/smtf.c">src/smtf.c</a>,
- <a href="../src/smtf.h">src/smtf.h</a>.
- <dt>
- Internal filters:
- <dd>
- a<a href="../src/siinterp.c">src/siinterp.c</a>,
- <a href="../src/siinterp.h">src/siinterp.h</a>,
- <a href="../src/siscale.c">src/siscale.c</a>,
- <a href="../src/siscale.h">src/siscale.h</a>,
- <a href="../src/sisparam.h">src/sisparam.h</a>.
- <dt>
- Higher-level stream support:
- <dd>
- <a href="../src/spprint.c">src/spprint.c</a>,
- <a href="../src/spprint.h">src/spprint.h</a>,
- <a href="../src/spsdf.c">src/spsdf.c</a>,
- <a href="../src/spsdf.h">src/spsdf.h</a>,
- <a href="../src/srdline.h">src/srdline.h</a>.
- </dl>
- <h4>Platform-specific code</h4>
- See <a href="#Cross_platform_APIs">below</a>.
- <h4>Miscellaneous</h4>
- <dl>
- <dt>
- Library top level:
- <dd>
- <a href="../src/gsinit.c">src/gsinit.c</a>,
- <a href="../src/gslib.h">src/gslib.h</a>.
- <dt>
- Configuration-related:
- <dd>
- <a href="../src/gconf.c">src/gconf.c</a>,
- <a href="../src/gconf.h">src/gconf.h</a>,
- <a href="../src/gscdef.c">src/gscdef.c</a>,
- <a href="../src/gscdefs.h">src/gscdefs.h</a>.
- <dt>
- Arithmetic:
- <dd>
- <a href="../src/gsfemu.c">src/gsfemu.c</a>,
- <a href="../src/gxarith.h">src/gxarith.h</a>,
- <a href="../src/gxdda.h">src/gxdda.h</a>,
- <a href="../src/gxfarith.h">src/gxfarith.h</a>,
- <a href="../src/gxfixed.h">src/gxfixed.h</a>,
- <a href="../src/gxfrac.h">src/gxfrac.h</a>.
- <dt>
- Operating system interface:
- <dd>
- <a href="../src/gserror.h">src/gserror.h</a>,
- <a href="../src/gsexit.h">src/gsexit.h</a>,
- <a href="../src/gxstdio.h">src/gxstdio.h</a>,
- <a href="../src/gxsync.c">src/gxsync.c</a>,
- <a href="../src/gxsync.h">src/gxsync.h</a>.
- <dt>
- Other:
- <dd>
- <a href="../src/gsargs.c">src/gsargs.c</a>,
- <a href="../src/gsargs.h">src/gsargs.h</a>,
- <a href="../src/gserrors.h">src/gserrors.h</a>,
- <a href="../src/gsnotify.c">src/gsnotify.c</a>,
- <a href="../src/gsnotify.h">src/gsnotify.h</a>,
- <a href="../src/gsrect.h">src/gsrect.h</a>,
- <a href="../src/gstypes.h">src/gstypes.h</a>,
- <a href="../src/gsuid.h">src/gsuid.h</a>,
- <a href="../src/gsutil.h">src/gsutil.h</a>,
- <a href="../src/gsutil.c">src/gsutil.c</a>,
- <a href="../src/gx.h">src/gx.h</a>,
- <a href="../src/md5.c">src/md5.c</a>,
- <a href="../src/md5.h">src/md5.h</a>.
- </dl>
- <h3><a name="Graphics_library"></a>Graphics library</h3>
- <h4><a name="Library_support"></a>Support</h4>
- <dl>
- <dt>
- Bitmap processing:
- <dd>
- <a href="../src/gsbitcom.c">src/gsbitcom.c</a>,
- <a href="../src/gsbitmap.h">src/gsbitmap.h</a>,
- <a href="../src/gsbitops.c">src/gsbitops.c</a>,
- <a href="../src/gsbitops.h">src/gsbitops.h</a>,
- <a href="../src/gsbittab.c">src/gsbittab.c</a>,
- <a href="../src/gsbittab.h">src/gsbittab.h</a>,
- <a href="../src/gsflip.c">src/gsflip.c</a>,
- <a href="../src/gsflip.h">src/gsflip.h</a>,
- <a href="../src/gxbitmap.h">src/gxbitmap.h</a>,
- <a href="../src/gxbitops.h">src/gxbitops.h</a>,
- <a href="../src/gxsample.c">src/gxsample.c</a>,
- <a href="../src/gxsample.h">src/gxsample.h</a>.
- <dt>
- Functions:
- <dd>
- <a href="../src/gsfunc.c">src/gsfunc.c</a>,
- <a href="../src/gsfunc.h">src/gsfunc.h</a>,
- <a href="../src/gsfunc0.c">src/gsfunc0.c</a>,
- <a href="../src/gsfunc0.h">src/gsfunc0.h</a>,
- <a href="../src/gsfunc3.c">src/gsfunc3.c</a>,
- <a href="../src/gsfunc3.h">src/gsfunc3.h</a>,
- <a href="../src/gsfunc4.c">src/gsfunc4.c</a>,
- <a href="../src/gsfunc4.h">src/gsfunc4.h</a>,
- <a href="../src/gsfuncv.c">src/gsfuncv.c</a>,
- <a href="../src/gsfuncv.h">src/gsfuncv.h</a>,
- <a href="../src/gxfunc.h">src/gxfunc.h</a>.
- <dt>
- Parameter lists:
- <dd>
- <a href="../src/gscparam.c">src/gscparam.c</a>,
- <a href="../src/gsparam.c">src/gsparam.c</a>,
- <a href="../src/gsparam.h">src/gsparam.h</a>,
- <a href="../src/gsparam2.c">src/gsparam2.c</a> (not used),
- <a href="../src/gsparams.c">src/gsparams.c</a>,
- <a href="../src/gsparams.h">src/gsparams.h</a>,
- <a href="../src/gsparamx.c">src/gsparamx.c</a>,
- <a href="../src/gsparamx.h">src/gsparamx.h</a>.
- <dt>
- I/O-related:
- <dd>
- <a href="../src/gdevpipe.c">src/gdevpipe.c</a>,
- <a href="../src/gsfname.c">src/gsfname.c</a>,
- <a href="../src/gsfname.h">src/gsfname.h</a>,
- <a href="../src/gsio.h">src/gsio.h</a>,
- <a href="../src/gsiodev.c">src/gsiodev.c</a>,
- <a href="../src/gsiodevs.c">src/gsiodevs.c</a>,
- <a href="../src/gxiodev.h">src/gxiodev.h</a>.
- </dl>
- <h4><a name="Paths"></a>Paths</h4>
- <dl>
- <dt>
- Coordinate transformation:
- <dd>
- <a href="../src/gscoord.c">src/gscoord.c</a>,
- <a href="../src/gscoord.h">src/gscoord.h</a>,
- <a href="../src/gsmatrix.c">src/gsmatrix.c</a>,
- <a href="../src/gsmatrix.h">src/gsmatrix.h</a>,
- <a href="../src/gxcoord.h">src/gxcoord.h</a>,
- <a href="../src/gxmatrix.h">src/gxmatrix.h</a>.
- <dt>
- Path building:
- <dd>
- <a href="../src/gsdps1.c">src/gsdps1.c</a>,
- <a href="../src/gspath.c">src/gspath.c</a>,
- <a href="../src/gspath.h">src/gspath.h</a>,
- <a href="../src/gspath1.c">src/gspath1.c</a>,
- <a href="../src/gspath2.h">src/gspath2.h</a>,
- <a href="../src/gxpath.c">src/gxpath.c</a>,
- <a href="../src/gxpath.h">src/gxpath.h</a>,
- <a href="../src/gxpath2.c">src/gxpath2.c</a>,
- <a href="../src/gxpcopy.c">src/gxpcopy.c</a>,
- <a href="../src/gxpdash.c">src/gxpdash.c</a>,
- <a href="../src/gxpflat.c">src/gxpflat.c</a>,
- <a href="../src/gzpath.h">src/gzpath.h</a>.
- <dt>
- Path rendering:
- <dd>
- <a href="../src/gdevddrw.c">src/gdevddrw.c</a>,
- <a href="../src/gsdps1.c">src/gsdps1.c</a>,
- <a href="../src/gspaint.c">src/gspaint.c</a>,
- <a href="../src/gspaint.h">src/gspaint.h</a>,
- <a href="../src/gspenum.h">src/gspenum.h</a>,
- <a href="../src/gxfill.c">src/gxfill.c</a>,
- <a href="../src/gxpaint.c">src/gxpaint.c</a>,
- <a href="../src/gxpaint.h">src/gxpaint.h</a>,
- <a href="../src/gxstroke.c">src/gxstroke.c</a>.
- <dt>
- Clipping:
- <dd>
- See under <a href="#Clipping">Clipping</a> below.
- </dl>
- <h4><a name="Text"></a>Text</h4>
- <dl>
- <dt>
- Fonts, generic:
- <dd>
- <a href="../src/gsfont.c">src/gsfont.c</a>,
- <a href="../src/gsfont.h">src/gsfont.h</a>,
- <a href="../src/gxfont.h">src/gxfont.h</a>.
- <dt>
- Fonts, specific FontTypes:
- <dd>
- <a href="../src/gsfcid.c">src/gsfcid.c</a>,
- <a href="../src/gsfcmap.c">src/gsfcmap.c</a>,
- <a href="../src/gsfcmap.h">src/gsfcmap.h</a>,
- <a href="../src/gsfont0.c">src/gsfont0.c</a>,
- <a href="../src/gxcid.h">src/gxcid.h</a>,
- <a href="../src/gxfcid.h">src/gxfcid.h</a>,
- <a href="../src/gxfcmap.h">src/gxfcmap.h</a>,
- <a href="../src/gxfont0.h">src/gxfont0.h</a>,
- <a href="../src/gxfont1.h">src/gxfont1.h</a>,
- <a href="../src/gxfont42.h">src/gxfont42.h</a>,
- <a href="../src/gxftype.h">src/gxftype.h</a>,
- <a href="../src/gxttf.h">src/gxttf.h</a>.
- <dt>
- Character rendering + font cache, generic:
- <dd>
- <a href="../src/gsccode.h">src/gsccode.h</a>,
- <a href="../src/gschar.c">src/gschar.c</a>,
- <a href="../src/gschar.h">src/gschar.h</a>,
- <a href="../src/gscpm.h">src/gscpm.h</a>,
- <a href="../src/gstext.c">src/gstext.c</a>,
- <a href="../src/gstext.h">src/gstext.h</a>,
- <a href="../src/gxbcache.c">src/gxbcache.c</a>,
- <a href="../src/gxbcache.h">src/gxbcache.h</a>,
- <a href="../src/gxccache.c">src/gxccache.c</a>,
- <a href="../src/gxccman.c">src/gxccman.c</a>,
- <a href="../src/gxchar.c">src/gxchar.c</a>,
- <a href="../src/gxchar.h">src/gxchar.h</a>,
- <a href="../src/gxfcache.h">src/gxfcache.h</a>,
- <a href="../src/gxtext.h">src/gxtext.h</a>.
- <dt>
- Character rendering, specific FontTypes:
- <dd>
- <a href="../src/gschar0.c">src/gschar0.c</a>,
- <a href="../src/gscrypt1.c">src/gscrypt1.c</a>,
- <a href="../src/gscrypt1.h">src/gscrypt1.h</a>,
- <a href="../src/gstype1.c">src/gstype1.c</a>,
- <a href="../src/gstype1.h">src/gstype1.h</a>,
- <a href="../src/gstype2.c">src/gstype2.c</a>,
- <a href="../src/gstype42.c">src/gstype42.c</a>,
- <a href="../src/gxchrout.c">src/gxchrout.c</a>,
- <a href="../src/gxchrout.h">src/gxchrout.h</a>,
- <a href="../src/gxhint1.c">src/gxhint1.c</a>,
- <a href="../src/gxhint2.c">src/gxhint2.c</a>,
- <a href="../src/gxhint3.c">src/gxhint3.c</a>,
- <a href="../src/gxop1.h">src/gxop1.h</a>,
- <a href="../src/gxtype1.c">src/gxtype1.c</a>,
- <a href="../src/gxtype1.h">src/gxtype1.h</a>.
- </dl>
- <h4><a name="Images"></a>Images</h4>
- <dl>
- <dt>
- Buffered API (mostly for PostScript interpreter):
- <dd>
- <a href="../src/gsimage.c">src/gsimage.c</a>,
- <a href="../src/gsimage.h">src/gsimage.h</a>.
- <dt>
- Generic support:
- <dd>
- <a href="../src/gsiparam.h">src/gsiparam.h</a>,
- <a href="../src/gxiclass.h">src/gxiclass.h</a>,
- <a href="../src/gximage.c">src/gximage.c</a>,
- <a href="../src/gximage.h">src/gximage.h</a>,
- <a href="../src/gxiparam.h">src/gxiparam.h</a>.
- <dt>
- Type 1 and 4 images:
- <dd>
- <dl>
- <dt>
- Setup:
- <dd>
- <a href="../src/gsiparm4.h">src/gsiparm4.h</a>,
- <a href="../src/gximage1.c">src/gximage1.c</a>,
- <a href="../src/gximage4.c">src/gximage4.c</a>.
- <dt>
- Rendering:
- <dd>
- <a href="../src/gxi12bit.c">src/gxi12bit.c</a>,
- <a href="../src/gxicolor.c">src/gxicolor.c</a>,
- <a href="../src/gxidata.c">src/gxidata.c</a>,
- <a href="../src/gxifast.c">src/gxifast.c</a>,
- <a href="../src/gximono.c">src/gximono.c</a>,
- <a href="../src/gxino12b.c">src/gxino12b.c</a>,
- <a href="../src/gxipixel.c">src/gxipixel.c</a>,
- <a href="../src/gxiscale.c">src/gxiscale.c</a>.
- </dl>
- <dt>
- Type 2 images (Display PostScript):
- <dd>
- <a href="../src/gsiparm2.h">src/gsiparm2.h</a>,
- <a href="../src/gximage2.c">src/gximage2.c</a>.
- <dt>
- Type 3 images:
- <dd>
- <a href="../src/gsipar3x.h">src/gsipar3x.h</a>,
- <a href="../src/gsiparm3.h">src/gsiparm3.h</a>,
- <a href="../src/gximag3x.c">src/gximag3x.c</a>,
- <a href="../src/gximag3x.h">src/gximag3x.h</a>,
- <a href="../src/gximage3.c">src/gximage3.c</a>,
- <a href="../src/gximage3.h">src/gximage3.h</a>.
- <dt>
- Other:
- <dd>
- <a href="../src/gsimpath.c">src/gsimpath.c</a>.
- </dl>
- <h4><a name="Paint"></a>Paint</h4>
- <p>
- Ghostscript uses 4 internal representations of color. We list them here in
- the order in which they occur in the rendering pipeline.
- <ol>
- <li>Clients of the graphics library normally specify colors using the
- <em>client color</em> structure (<b><tt>gs_client_color</tt></b>, defined in
- <a href="../src/gsccolor.h">src/gsccolor.h</a>), consisting of one or more
- numeric values and/or a pointer to a Pattern instance. This corresponds
- directly to the values that would be passed to the PostScript
- <b><tt>setcolor</tt></b> operator: one or more (floating-point) numeric
- components and/or a Pattern. Client colors are interpreted relative to a
- color space (<b><tt>gs_color_space</tt></b>, defined in <a
- href="../src/gscspace.h">src/gscspace.h</a> and <a
- href="../src/gxcspace.h">src/gxcspace.h</a>, with specific color spaces
- defined in other files). Client colors do not explicitly reference the
- color space in which they are are interpreted: <b><tt>setcolor</tt></b> uses
- the color space in the graphics state, while images and shadings explicitly
- specify the color space to be used.
- <li>For ordinary non-Pattern colors, the first step in color rendering
- reduces a client color to a <em>concrete</em> color -- a set of values in a
- color space that corresponds to the device's color model (except for
- possible conversions between DeviceGray, DeviceRGB, and DeviceCMYK),
- together with an identification of the associated color space. (The
- confusion here between color spaces and color models will have to be cleaned
- up when we implement native Separation/DeviceN colors.) Concrete colors are
- like the numeric values in a client color, except that they are represented
- by arrays of <b><tt>frac</tt></b> values (defined in <a
- href="../src/gxfrac.h">src/gxfrac.h</a>) rather than floats. The procedure
- for this step is the virtual <b><tt>concretize_color</tt></b> and
- <b><tt>concrete_space</tt></b> procedures in the (original) color space.
- This step reduces Indexed colors, CIEBased colors, and Separation and
- DeviceN colors that use the alternate space.
- <li>The final step requires mapping a concrete color to the device's color
- model, done by procedures in <a href="../src/gxcmap.c">src/gxcmap.c</a>.
- These procedures combine the following three conceptual sub-steps:
- <ul>
- <li>A possible mapping between Device color spaces, possibly involving black
- generation and undercolor removal. The non-trivial cases are implemented in
- <a href="../src/gxdcconv.c">src/gxdcconv.c</a>.
- <li>Application of the transfer function(s) (done in-line).
- <li>Halftoning if necessary: see below.
- </ul>
- The result is called (inappropriately) a <em>device color</em>
- (<b><tt>gx_device_color</tt></b>, defined in <a
- href="../src/gsdcolor.h">src/gsdcolor.h</a> and <a
- href="../src/gxdcolor.h">src/gxdcolor.h</a>). For ordinary non-Pattern
- colors, a device color is either a pure color, or a halftone. The device
- and color model associated with a device color are implicit. The procedure
- for this step is the virtual <b><tt>remap_concrete_color</tt></b> procedure
- in the color space.
- <li>The pure colors that underlie a device color are opaque <em>pixel
- values</em> defined by the device (misnamed <b><tt>gx_color_index</tt></b>,
- defined in <a href="../src/gscindex.h">src/gscindex.h</a>). The device with
- which they are associated is implicit. Although the format and
- interpretation of a pixel value are known only to the device, the device's
- color model and color representation capabilities are public, defined by a
- <b><tt>gx_color_info</tt></b> structure stored in the device (defined in <a
- href="../src/gxdevcli.h">src/gxdevcli.h</a>). Virtual procedures of the
- device driver map between pixel values and RGB or CMYK. (This area is
- untidy and will need to be cleaned up when we implement native
- Separation/DeviceN colors.)
- </ol>
- <p>
- Steps 2 and 3 are normally combined into a single step for efficiency, as
- the <b><tt>remap_color</tt></b> virtual procedure in a color space.
- <p>
- Using a device color to actually paint pixels requires a further step called
- <em>color loading</em>, implemented by the <b><tt>load</tt></b> virtual
- procedure in the device color. This does nothing for pure colors, but loads
- the caches for halftones and Patterns.
- <p>
- All of the above steps -- concretizing, mapping to a device color, and color
- loading -- are done as late as possible, normally not until the color is
- actually needed for painting.
- <p>
- All painting operations (fill, stroke, imagemask/show) eventually call a
- virtual procedure in the device color, either <b><tt>fill_rectangle</tt></b>
- or <b><tt>fill_mask</tt></b> to actually paint pixels. For rectangle fills,
- pure colors call the device's <b><tt>fill_rectangle</tt></b> procedure;
- halftones and tiled Patterns call the device's
- <b><tt>tile_rectangle</tt></b>; shaded Patterns, and painting operations
- that involve a RasterOp, do something more complicated.
- <dl>
- <dt>
- Color specification:
- <dd>
- <a href="../src/gsccolor.h">src/gsccolor.h</a>,
- <a href="../src/gscolor.c">src/gscolor.c</a>,
- <a href="../src/gscolor.h">src/gscolor.h</a>,
- <a href="../src/gscolor1.c">src/gscolor1.c</a>,
- <a href="../src/gscolor1.h">src/gscolor1.h</a>,
- <a href="../src/gscolor2.c">src/gscolor2.c</a>,
- <a href="../src/gscolor2.h">src/gscolor2.h</a>,
- <a href="../src/gscolor3.c">src/gscolor3.c</a>,
- <a href="../src/gscolor3.h">src/gscolor3.h</a>,
- <a href="../src/gshsb.c">src/gshsb.c</a>,
- <a href="../src/gshsb.h">src/gshsb.h</a>,
- <a href="../src/gxcolor2.h">src/gxcolor2.h</a>,
- <a href="../src/gxcvalue.h">src/gxcvalue.h</a>.
- <dt>
- Color spaces:
- <dd>
- <a href="../src/gscdevn.c">src/gscdevn.c</a>,
- <a href="../src/gscdevn.h">src/gscdevn.h</a>,
- <a href="../src/gscie.c">src/gscie.c</a>,
- <a href="../src/gscie.h">src/gscie.h</a>,
- <a href="../src/gscpixel.c">src/gscpixel.c</a>,
- <a href="../src/gscpixel.h">src/gscpixel.h</a>,
- <a href="../src/gscscie.c">src/gscscie.c</a>,
- <a href="../src/gscsepnm.h">src/gscsepnm.h</a>,
- <a href="../src/gscsepr.c">src/gscsepr.c</a>,
- <a href="../src/gscsepr.h">src/gscsepr.h</a>,
- <a href="../src/gscspace.c">src/gscspace.c</a>,
- <a href="../src/gscspace.h">src/gscspace.h</a>,
- <a href="../src/gscssub.c">src/gscssub.c</a>,
- <a href="../src/gscssub.h">src/gscssub.h</a>,
- <a href="../src/gxcdevn.h">src/gxcdevn.h</a>,
- <a href="../src/gxcie.h">src/gxcie.h</a>,
- <a href="../src/gxcspace.h">src/gxcspace.h</a>.
- <dt>
- Color mapping:
- <dd>
- <a href="../src/gsciemap.c">src/gsciemap.c</a>,
- <a href="../src/gscindex.h">src/gscindex.h</a>,
- <a href="../src/gscrd.c">src/gscrd.c</a>,
- <a href="../src/gscrd.h">src/gscrd.h</a>,
- <a href="../src/gscrdp.c">src/gscrdp.c</a>,
- <a href="../src/gscrdp.h">src/gscrdp.h</a>,
- <a href="../src/gscsel.h">src/gscsel.h</a>,
- <a href="../src/gsdcolor.h">src/gsdcolor.h</a>,
- <a href="../src/gxcindex.h">src/gxcindex.h</a>,
- <a href="../src/gxcmap.c">src/gxcmap.c</a>,
- <a href="../src/gxcmap.h">src/gxcmap.h</a>,
- <a href="../src/gxctable.c">src/gxctable.c</a>,
- <a href="../src/gxctable.h">src/gxctable.h</a>,
- <a href="../src/gxdcconv.c">src/gxdcconv.c</a>,
- <a href="../src/gxdcconv.h">src/gxdcconv.h</a>,
- <a href="../src/gxdcolor.c">src/gxdcolor.c</a>,
- <a href="../src/gxdcolor.h">src/gxdcolor.h</a>,
- <a href="../src/gxdither.c">src/gxdither.c</a>,
- <a href="../src/gxdither.h">src/gxdither.h</a>,
- <a href="../src/gxfmap.h">src/gxfmap.h</a>,
- <a href="../src/gxlum.h">src/gxlum.h</a>,
- <a href="../src/gxtmap.h">src/gxtmap.h</a>.
- <p>
- ICC profiles are in some ways a special case of color mapping, but are
- not standard in PostScript.
- <dt>
- Color mapping:
- <dd>
- <a href="../src/gsicc.c">src/gsicc.c</a>,
- <a href="../src/gsicc.h">src/gsicc.h</a>,
- </dl>
- <p>
- Ghostscript represents halftones internally by "whitening orders" --
- essentially, arrays of arrays of bit coordinates within a halftone cell,
- specifying which bits are inverted to get from halftone level K to level
- K+1. The code does support all of the PostScript halftone types, but they
- are all ultimately reduced to whitening orders.
- <p>
- Threshold arrays, the more conventional representation of halftones, can be
- mapped to whitening orders straightforwardly; however, whitening orders can
- represent non-monotonic halftones (halftones where the bits turned on for
- level K+1 don't necessarily include all the bits turned on for level K),
- while threshold arrays cannot. On the other hand, threshold arrays allow
- rapid conversion of images (using a threshold comparison for each pixel)
- with no additional space, while whitening orders do not: they require
- storing the rendered halftone cell for each possible level as a bitmap.
- <p>
- Ghostscript uses two distinct types of rendered halftones -- that is, the
- bitmap(s) that represent a particular level.
- <ul>
- <li>Binary halftones. The rendered halftone is a single bit plane; each bit
- selects one of two pure colors. These are fast but limited: they are used
- for monochrome output devices, or for color devices in those cases where
- only two distinct colors are involved in a halftone (e.g., a pure cyan shade
- on a CMYK device). The device color for a binary halftone stores a pointer
- to the halftone bitmap, and the two pure colors.
- <li>Multi-plane halftones. Internally, each plane is rendered individually.
- Since there isn't enough room to store all 2^N pure colors, multi-plane
- halftones only store the scaled values for the individual components; the
- halftone renderer maps these to the pure colors on the fly, then combines
- the planes to assemble an N-bit index into the list of colors for each
- pixel, and stores the color into the fully rendered halftone.
- </ul>
- <p>
- The halftone level for rendering a color is computed in <a
- href="../src/gxdither.c">src/gxdither.c</a>; the actual halftone mask or
- tile is computed either in <a href="../src/gxcht.c">src/gxcht.c</a> (for
- multi-plane halftones), or in <a href="../src/gxht.c">src/gxht.c</a> and <a
- href="../src/gxhtbit.c">src/gxhtbit.c</a> (for binary halftones).
- <dl>
- <dt>
- Halftoning:
- <dd>
- <a href="../src/gsht.c">src/gsht.c</a>,
- <a href="../src/gsht.h">src/gsht.h</a>,
- <a href="../src/gsht1.c">src/gsht1.c</a>,
- <a href="../src/gsht1.h">src/gsht1.h</a>,
- <a href="../src/gshtscr.c">src/gshtscr.c</a>,
- <a href="../src/gshtx.c">src/gshtx.c</a>,
- <a href="../src/gshtx.h">src/gshtx.h</a>,
- <a href="../src/gxcht.c">src/gxcht.c</a>,
- <a href="../src/gxdht.h">src/gxdht.h</a>,
- <a href="../src/gxdhtres.h">src/gxdhtres.h</a>,
- <a href="../src/gxht.c">src/gxht.c</a>,
- <a href="../src/gxht.h">src/gxht.h</a>,
- <a href="../src/gxhtbit.c">src/gxhtbit.c</a>,
- <a href="../src/gxhttile.h">src/gxhttile.h</a>,
- <a href="../src/gxhttype.h">src/gxhttype.h</a>,
- <a href="../src/gzht.h">src/gzht.h</a>.
- </dl>
- <p>
- Pattern colors (tiled patterns and shadings) each use a slightly different
- approach from solid colors.
- <p>
- The device color for a tiled (PatternType 1) pattern contains a pointer to a
- pattern instance, plus (for uncolored patterns) the device color to be
- masked. The pattern instance includes a procedure that actually paints the
- pattern if the pattern is not in the cache. For the PostScript interpreter,
- this procedure returns an <b><tt>e_RemapColor</tt></b> exception code: this
- eventually causes the interpreter to run the pattern's PaintProc, loading
- the rendering into the cache, and then re-execute the original drawing
- operator.
- <dl>
- <dt>
- Patterns:
- <dd>
- <a href="../src/gspcolor.c">src/gspcolor.c</a>,
- <a href="../src/gspcolor.h">src/gspcolor.h</a>,
- <a href="../src/gsptype1.c">src/gsptype1.c</a>,
- <a href="../src/gsptype1.h">src/gsptype1.h</a>,
- <a href="../src/gxp1fill.c">src/gxp1fill.c</a>,
- <a href="../src/gxp1impl.h">src/gxp1impl.h</a>,
- <a href="../src/gxpcache.h">src/gxpcache.h</a>,
- <a href="../src/gxpcmap.c">src/gxpcmap.c</a>,
- <a href="../src/gxpcolor.h">src/gxpcolor.h</a>.
- </dl>
- <p>
- The device color for a shading (PatternType 2) pattern also contains a
- pointer to a pattern instance. Shadings are not cached: painting with a
- shading runs the shading algorithm every time.
- <dl>
- <dt>
- Shading:
- <dd>
- <a href="../src/gsptype2.c">src/gsptype2.c</a>,
- <a href="../src/gsptype2.h">src/gsptype2.h</a>,
- <a href="../src/gsshade.c">src/gsshade.c</a>,
- <a href="../src/gsshade.h">src/gsshade.h</a>,
- <a href="../src/gxshade.c">src/gxshade.c</a>,
- <a href="../src/gxshade.h">src/gxshade.h</a>,
- <a href="../src/gxshade1.c">src/gxshade1.c</a>,
- <a href="../src/gxshade4.c">src/gxshade4.c</a>,
- <a href="../src/gxshade4.h">src/gxshade4.h</a>,
- <a href="../src/gxshade6.c">src/gxshade6.c</a>.
- </dl>
- <p>
- In addition to the PostScript graphics model, Ghostscript supports RasterOp,
- a weak form of alpha channel, and eventually the full PDF 1.4 transparency
- model. The implemention of these facilities is quite slipshod and
- scattered: only RasterOp is really implemented fully. There is a general
- compositing architecture, but it is hardly used at all, and in particular is
- not used for RasterOp. ****** TO BE COMPLETED ******
- <dl>
- <dt>
- Compositing architecture:
- <dd>
- <a href="../src/gscompt.h">src/gscompt.h</a>,
- <a href="../src/gxcomp.h">src/gxcomp.h</a>.
- <dt>
- RasterOp:
- <dd>
- <a href="../src/gdevdrop.c">src/gdevdrop.c</a>,
- <a href="../src/gdevrops.c">src/gdevrops.c</a>,
- <a href="../src/gsnorop.c">src/gsnorop.c</a>,
- <a href="../src/gsrop.c">src/gsrop.c</a>,
- <a href="../src/gsrop.h">src/gsrop.h</a>,
- <a href="../src/gsropc.c">src/gsropc.c</a>,
- <a href="../src/gsropc.h">src/gsropc.h</a>,
- <a href="../src/gsropt.h">src/gsropt.h</a>,
- <a href="../src/gsroptab.c">src/gsroptab.c</a>,
- <a href="../src/gxdevrop.h">src/gxdevrop.h</a>,
- <a href="../src/gxropc.h">src/gxropc.h</a>.
- <dt>
- Alpha channel and compositing:
- <dd>
- <a href="../src/gsalpha.c">src/gsalpha.c</a>,
- <a href="../src/gsalpha.h">src/gsalpha.h</a>,
- <a href="../src/gsalphac.c">src/gsalphac.c</a>,
- <a href="../src/gsalphac.h">src/gsalphac.h</a>,
- <a href="../src/gsdpnext.h">src/gsdpnext.h</a>,
- <a href="../src/gxalpha.h">src/gxalpha.h</a>.
- <dt>
- Advanced transparency:
- <dd>
- <a href="../src/gstparam.h">src/gstparam.h</a>,
- <a href="../src/gstrans.c">src/gstrans.c</a>,
- <a href="../src/gstrans.h">src/gstrans.h</a>,
- <a href="../src/gxblend.c">src/gxblend.c</a>,
- <a href="../src/gxblend.h">src/gxblend.h</a>,
- <a href="../src/gdevp14.c">src/gdevp14.c</a>.
- <a href="../src/gdevp14.h">src/gdevp14.h</a>.
- <a href="../src/gdevpnga.c">src/gdevpnga.c</a>.
- </dl>
- <h4><a name="Clipping"></a>Clipping</h4>
- <p>
- The Ghostscript graphics library implements clipping by inserting a clipping
- device in the device pipeline. The clipping device modifies all drawing
- operations to confine them to the clipping region.
- <p>
- The library supports three different kinds of clipping:
- <dl>
- <dt>
- Region/path clipping
- <dd>
- This corresponds to the PostScript concept of a clipping path. The clipping
- region is specified either by a list of rectangles (subject to the
- constraints documented in <a href="../src/gxcpath.h">src/gxcpath.h</a>), or
- by a path that is converted to such a list of rectangles.
- <dt>
- Stationary mask clipping
- <dd>
- This corresponds to the mask operand of a PostScript ImageType 3 image. The
- clipping region is specified by a bitmap and an (X,Y) offset in the
- coordinate space.
- <dt>
- Tiled mask clipping
- <dd>
- This corresponds to the region painted by a PostScript Pattern, for the case
- where the Pattern does not completely cover its bounding box but the
- combined transformation matrix has no skew or non-orthogonal rotation (i.e.,
- XStep and YStep map respectively to (X,0) and (0,Y) or vice versa). The
- clipping region is specified by a bitmap and an (X,Y) offset in the
- coordinate space, and is replicated indefinitely in both X and Y.
- </dl>
- <p>
- Note that simply scan-converting a clipping path in the usual way does not
- produce a succession of rectangles that can simply be stored as the list for
- region-based clipping: in general, the rectangles do not satisfy the
- constraint for rectangle lists specified in <a
- href="../src/gxcpath.h">src/gxcpath.h</a>, since they may overlap in X, Y,
- or both. A non-trivial "clipping list accumulator" device is needed to
- produce a rectangle list that does satisfy the constraint.
- <dl>
- <dt>
- Clipping support:
- <dd>
- <a href="../src/gxclip.c">src/gxclip.c</a>,
- <a href="../src/gxclip.h">src/gxclip.h</a>.
- <dt>
- Region/path clipping:
- <dd>
- <a href="../src/gxcpath.c">src/gxcpath.c</a>,
- <a href="../src/gxcpath.h">src/gxcpath.h</a>,
- <a href="../src/gzcpath.h">src/gzcpath.h</a>.
- <dt>
- Clipping list accumulator:
- <dd>
- <a href="../src/gxacpath.c">src/gxacpath.c</a>,
- <a href="../src/gzacpath.h">src/gzacpath.h</a>.
- <dt>
- Mask clipping support:
- <dd>
- <a href="../src/gxmclip.c">src/gxmclip.c</a>,
- <a href="../src/gxmclip.h">src/gxmclip.h</a>.
- <dt>
- Stationary mask clipping:
- <dd>
- <a href="../src/gxclipm.c">src/gxclipm.c</a>,
- <a href="../src/gxclipm.h">src/gxclipm.h</a>.
- <dt>
- Tiled mask clipping:
- <dd>
- <a href="../src/gxclip2.c">src/gxclip2.c</a>,
- <a href="../src/gxclip2.h">src/gxclip2.h</a>.
- </dl>
- <h4><a name="Other_graphics"></a>Other graphics</h4>
- <dl>
- <dt>
- Miscellaneous graphics state:
- <dd>
- <a href="../src/gsclipsr.c">src/gsclipsr.c</a>,
- <a href="../src/gsclipsr.h">src/gsclipsr.h</a>,
- <a href="../src/gsdps.c">src/gsdps.c</a>,
- <a href="../src/gsdps.h">src/gsdps.h</a>,
- <a href="../src/gsdps1.c">src/gsdps1.c</a>,
- <a href="../src/gsistate.c">src/gsistate.c</a>,
- <a href="../src/gsline.c">src/gsline.c</a>,
- <a href="../src/gsline.h">src/gsline.h</a>,
- <a href="../src/gslparam.h">src/gslparam.h</a>,
- <a href="../src/gsstate.c">src/gsstate.c</a>,
- <a href="../src/gsstate.h">src/gsstate.h</a>,
- <a href="../src/gstrap.c">src/gstrap.c</a>,
- <a href="../src/gstrap.h">src/gstrap.h</a>,
- <a href="../src/gxclipsr.h">src/gxclipsr.h</a>,
- <a href="../src/gxistate.h">src/gxistate.h</a>,
- <a href="../src/gxline.h">src/gxline.h</a>,
- <a href="../src/gxstate.h">src/gxstate.h</a>,
- <a href="../src/gzline.h">src/gzline.h</a>,
- <a href="../src/gzstate.h">src/gzstate.h</a>.
- </dl>
- <h4><a name="Driver_support"></a>Driver support</h4>
- <dl>
- <dt>
- Generic driver support:
- <dd>
- <a href="../src/gdevdcrd.c">src/gdevdcrd.c</a>,
- <a href="../src/gdevdcrd.h">src/gdevdcrd.h</a>,
- <a href="../src/gdevemap.c">src/gdevemap.c</a>,
- <a href="../src/gsdevice.c">src/gsdevice.c</a>,
- <a href="../src/gsdevice.h">src/gsdevice.h</a>,
- <a href="../src/gsdparam.c">src/gsdparam.c</a>,
- <a href="../src/gsxfont.h">src/gsxfont.h</a>,
- <a href="../src/gxdevbuf.h">src/gxdevbuf.h</a>,
- <a href="../src/gxdevcli.h">src/gxdevcli.h</a>,
- <a href="../src/gxdevice.h">src/gxdevice.h</a>,
- <a href="../src/gxrplane.h">src/gxrplane.h</a>,
- <a href="../src/gxxfont.h">src/gxxfont.h</a>.
- <dt>
- Accessing rendered bits:
- <dd>
- <a href="../src/gdevdbit.c">src/gdevdbit.c</a>,
- <a href="../src/gdevdgbr.c">src/gdevdgbr.c</a>,
- <a href="../src/gxbitfmt.h">src/gxbitfmt.h</a>,
- <a href="../src/gxgetbit.h">src/gxgetbit.h</a>.
- <dt>
- "Printer" driver support:
- <dd>
- <a href="../src/gdevmeds.c">src/gdevmeds.c</a>,
- <a href="../src/gdevmeds.h">src/gdevmeds.h</a>,
- <a href="../src/gdevppla.c">src/gdevppla.c</a>,
- <a href="../src/gdevppla.h">src/gdevppla.h</a>,
- <a href="../src/gdevprn.c">src/gdevprn.c</a>,
- <a href="../src/gdevprn.h">src/gdevprn.h</a>,
- <a href="../src/gdevprna.c">src/gdevprna.c</a>,
- <a href="../src/gdevprna.h">src/gdevprna.h</a>,
- <a href="../src/gxband.h">src/gxband.h</a>,
- <a href="../src/gxpageq.c">src/gxpageq.c</a>,
- <a href="../src/gxpageq.h">src/gxpageq.h</a>.
- <dt>
- High-level device support:
- <dd>
- <a href="../src/gdevvec.c">src/gdevvec.c</a>,
- <a href="../src/gdevvec.h">src/gdevvec.h</a>.
- <dt>
- Banding:
- <dd>
- <a href="../src/gxclbits.c">src/gxclbits.c</a>,
- <a href="../src/gxcldev.h">src/gxcldev.h</a>,
- <a href="../src/gxclfile.c">src/gxclfile.c</a>,
- <a href="../src/gxclimag.c">src/gxclimag.c</a>,
- <a href="../src/gxclio.h">src/gxclio.h</a>,
- <a href="../src/gxclist.c">src/gxclist.c</a>,
- <a href="../src/gxclist.h">src/gxclist.h</a>,
- <a href="../src/gxcllzw.c">src/gxcllzw.c</a>,
- <a href="../src/gxclmem.c">src/gxclmem.c</a>,
- <a href="../src/gxclmem.h">src/gxclmem.h</a>,
- <a href="../src/gxclpage.c">src/gxclpage.c</a>,
- <a href="../src/gxclpage.h">src/gxclpage.h</a>,
- <a href="../src/gxclpath.c">src/gxclpath.c</a>,
- <a href="../src/gxclpath.h">src/gxclpath.h</a>,
- <a href="../src/gxclrast.c">src/gxclrast.c</a>,
- <a href="../src/gxclread.c">src/gxclread.c</a>,
- <a href="../src/gxclrect.c">src/gxclrect.c</a>,
- <a href="../src/gxclutil.c">src/gxclutil.c</a>,
- <a href="../src/gxclzlib.c">src/gxclzlib.c</a>.
- </dl>
- <h3><a name="Device_drivers"></a>Device drivers</h3>
- <p>
- See <a href="Drivers.htm">doc/Drivers.htm</a> for extensive documentation on
- the interface between the core code and drivers.
- <p>
- The driver API includes high-level (path / image / text), mid-level
- (polygon), and low-level (rectangle / raster) operations. Most devices
- implement only the low-level operations, and let generic code break down the
- high-level operations. However, some devices produce high-level output, and
- therefore must implement the high-level operations.
- <h4><a name="Internal_devices"></a>Internal devices</h4>
- <p>
- There are a number of "devices" that serve internal purposes. Some of these
- are meant to be real rendering targets; others are intended for use in
- device pipelines. The rendering targets are:
- <dl>
- <dt>
- Memory devices, depth-independent:
- <dd>
- <a href="../src/gdevmem.c">src/gdevmem.c</a>,
- <a href="../src/gdevmem.h">src/gdevmem.h</a>,
- <a href="../src/gdevmpla.c">src/gdevmpla.c</a>,
- <a href="../src/gdevmpla.h">src/gdevmpla.h</a>,
- <a href="../src/gdevmrop.h">src/gdevmrop.h</a>,
- <a href="../src/gsdevmem.c">src/gsdevmem.c</a>,
- <a href="../src/gxdevmem.h">src/gxdevmem.h</a>.
- <dt>
- Memory devices, specific depths:
- <dd>
- <a href="../src/gdevm1.c">src/gdevm1.c</a>,
- <a href="../src/gdevm2.c">src/gdevm2.c</a>,
- <a href="../src/gdevm4.c">src/gdevm4.c</a>,
- <a href="../src/gdevm8.c">src/gdevm8.c</a>,
- <a href="../src/gdevm16.c">src/gdevm16.c</a>,
- <a href="../src/gdevm24.c">src/gdevm24.c</a>,
- <a href="../src/gdevm32.c">src/gdevm32.c</a>,
- <a href="../src/gdevmr1.c">src/gdevmr1.c</a>,
- <a href="../src/gdevmr2n.c">src/gdevmr2n.c</a>,
- <a href="../src/gdevmr8n.c">src/gdevmr8n.c</a>.
- <dt>
- Alpha-related devices:
- <dd>
- <a href="../src/gdevabuf.c">src/gdevabuf.c</a>,
- <a href="../src/gdevalph.c">src/gdevalph.c</a>.
- <dt>
- Other devices:
- <dd>
- <a href="../src/gdevdflt.c">src/gdevdflt.c</a>,
- <a href="../src/gdevhit.c">src/gdevhit.c</a>,
- <a href="../src/gdevht.c">src/gdevht.c</a>,
- <a href="../src/gdevht.h">src/gdevht.h</a>,
- <a href="../src/gdevmrun.c">src/gdevmrun.c</a>,
- <a href="../src/gdevmrun.h">src/gdevmrun.h</a>,
- <a href="../src/gdevplnx.c">src/gdevplnx.c</a>,
- <a href="../src/gdevplnx.h">src/gdevplnx.h</a>,
- </dl>
- <p>
- The forwarding devices meant for use in pipelines are:
- <dl>
- <dt>
- The bounding box device:
- <dd>
- <a href="../src/gdevbbox.h">src/gdevbbox.h</a>,
- <a href="../src/gdevbbox.c">src/gdevbbox.c</a>.
- <dt>
- Clipping devices:
- <dd>
- See under <a href="#Clipping">Clipping</a> above.
- <dt>
- Device filter stack:
- <dd>
- <a href="../src/gsdfilt.c">src/gsdfilt.c</a>,
- <a href="../src/gsdfilt.h">src/gsdfilt.h</a>,
- <dt>
- Other devices:
- <dd>
- <a href="../src/gdevcmap.c">src/gdevcmap.c</a>,
- <a href="../src/gdevcmap.h">src/gdevcmap.h</a>,
- <a href="../src/gdevnfwd.c">src/gdevnfwd.c</a>.
- </dl>
- <h4><a name="PS_and_PDF_writers"></a>PostScript and PDF writers</h4>
- <p>
- Because PostScript and PDF have the same graphics model, lexical syntax, and
- stack-based execution model, the drivers that produce PostScript and PDF
- output share a significant amount of support code. In the future, the
- PostScript output driver should be replaced with a slightly modified version
- of the PDF driver, since the latter is far more sophisticated (in
- particular, it has extensive facilities for image compression and for
- handling text and fonts).
- <dl>
- <dt>
- Shared support:
- <dd>
- <dl>
- Writing fonts:
- <dd>
- <a href="../src/gdevpsf.h">src/gdevpsf.h</a>,
- <a href="../src/gdevpsf1.c">src/gdevpsf1.c</a>,
- <a href="../src/gdevpsf2.c">src/gdevpsf2.c</a>,
- <a href="../src/gdevpsfm.c">src/gdevpsfm.c</a>,
- <a href="../src/gdevpsft.c">src/gdevpsft.c</a>,
- <a href="../src/gdevpsfu.c">src/gdevpsfu.c</a>,
- <a href="../src/gdevpsfx.c">src/gdevpsfx.c</a>.
- <dt>
- Other:
- <dd>
- <a href="../src/gdevpsdf.h">src/gdevpsdf.h</a>,
- <a href="../src/gdevpsdi.c">src/gdevpsdi.c</a>,
- <a href="../src/gdevpsdp.c">src/gdevpsdp.c</a>,
- <a href="../src/gdevpsds.c">src/gdevpsds.c</a>,
- <a href="../src/gdevpsds.h">src/gdevpsds.h</a>,
- <a href="../src/gdevpsdu.c">src/gdevpsdu.c</a>.
- </dl>
- <dt>
- PostScript output driver ([e]pswrite):
- <dd>
- <a href="../src/gdevps.c">src/gdevps.c</a>,
- <a href="../src/gdevpsu.c">src/gdevpsu.c</a>,
- <a href="../src/gdevpsu.h">src/gdevpsu.h</a>.
- <dt>
- PDF output driver (pdfwrite):
- <dd>
- <dl>
- <dt>
- Substrate:
- <dd>
- <a href="../src/gdevpdfo.c">src/gdevpdfo.c</a>,
- <a href="../src/gdevpdfo.h">src/gdevpdfo.h</a>,
- <a href="../src/gdevpdfr.c">src/gdevpdfr.c</a>,
- <a href="../src/gdevpdfu.c">src/gdevpdfu.c</a>.
- <dt>
- Text and fonts:
- <dd>
- <a href="../src/gdevpdfe.c">src/gdevpdfe.c</a>,
- <a href="../src/gdevpdff.c">src/gdevpdff.c</a>,
- <a href="../src/gdevpdff.h">src/gdevpdff.h</a>,
- <a href="../src/gdevpdfs.c">src/gdevpdfs.c</a>,
- <a href="../src/gdevpdft.c">src/gdevpdft.c</a>,
- <a href="../src/gdevpdfw.c">src/gdevpdfw.c</a>.
- <dt>
- Graphics:
- <dd>
- <a href="../src/gdevpdfc.c">src/gdevpdfc.c</a>,
- <a href="../src/gdevpdfd.c">src/gdevpdfd.c</a>,
- <a href="../src/gdevpdfg.c">src/gdevpdfg.c</a>,
- <a href="../src/gdevpdfg.h">src/gdevpdfg.h</a>,
- <a href="../src/gdevpdfv.c">src/gdevpdfv.c</a>.
- <dt>
- Images:
- <dd>
- <a href="../src/gdevpdfb.c">src/gdevpdfb.c</a>,
- <a href="../src/gdevpdfi.c">src/gdevpdfi.c</a>,
- <a href="../src/gdevpdfj.c">src/gdevpdfj.c</a>.
- <dt>
- Other:
- <dd>
- <a href="../src/gdevpdf.c">src/gdevpdf.c</a>,
- <a href="../src/gdevpdfm.c">src/gdevpdfm.c</a>,
- <a href="../src/gdevpdfp.c">src/gdevpdfp.c</a>,
- <a href="../src/gdevpdfx.h">src/gdevpdfx.h</a>.
- </dl>
- </dl>
- <h4><a name="High_level_devices"></a>Other high-level devices</h4>
- <p>
- Currently, the CGM driver is raster-only. If anyone cares seriously about
- CGM in the future, this driver should be upgraded to a higher level.
- <dl>
- <dt>
- PCL XL output device (pxlmono, pxlcolor):
- <dd>
- <a href="../src/gdevpx.c">src/gdevpx.c</a>,
- <a href="../src/gdevpxat.h">src/gdevpxat.h</a>,
- <a href="../src/gdevpxen.h">src/gdevpxen.h</a>,
- <a href="../src/gdevpxop.h">src/gdevpxop.h</a>,
- <a href="../src/gdevpxut.c">src/gdevpxut.c</a>,
- <a href="../src/gdevpxut.h">src/gdevpxut.h</a>.
- <dt>
- Other high-level devices:
- <dd>
- <a href="../src/gdevtrac.c">src/gdevtrac.c</a>.
- </dl>
- <h4><a name="Other_maintained_drivers"></a>Other maintained drivers</h4>
- <p>
- The standard Ghostscript distribution includes a collection of drivers,
- mostly written by Aladdin Enterprises, that are "maintained" in the same
- sense as the Ghostscript core code.
- <dl>
- <dt>
- Display drivers:
- <dd>
- <a href="../src/gdev8bcm.c">src/gdev8bcm.c</a>,
- <a href="../src/gdev8bcm.h">src/gdev8bcm.h</a>,
- <a href="../src/gdevegaa.asm">src/gdevegaa.asm</a>,
- <a href="../src/gdevevga.c">src/gdevevga.c</a>,
- <a href="../src/gdevl256.c">src/gdevl256.c</a>,
- <a href="../src/gdevpccm.c">src/gdevpccm.c</a>,
- <a href="../src/gdevpccm.h">src/gdevpccm.h</a>,
- <a href="../src/gdevpcfb.c">src/gdevpcfb.c</a>,
- <a href="../src/gdevpcfb.h">src/gdevpcfb.h</a>,
- <a href="../src/gdevs3ga.c">src/gdevs3ga.c</a>,
- <a href="../src/gdevsco.c">src/gdevsco.c</a>,
- <a href="../src/gdevsvga.c">src/gdevsvga.c</a>,
- <a href="../src/gdevsvga.h">src/gdevsvga.h</a>,
- <a href="../src/gdevvglb.c">src/gdevvglb.c</a>.
- <dt>
- Window system drivers:
- <dd>
- <dl>
- <dt>
- X Windows:
- <dd>
- <a href="../src/gdevx.c">src/gdevx.c</a>,
- <a href="../src/gdevx.h">src/gdevx.h</a>,
- <a href="../src/gdevxalt.c">src/gdevxalt.c</a>,
- <a href="../src/gdevxcmp.c">src/gdevxcmp.c</a>,
- <a href="../src/gdevxcmp.h">src/gdevxcmp.h</a>,
- <a href="../src/gdevxini.c">src/gdevxini.c</a>,
- <a href="../src/gdevxres.c">src/gdevxres.c</a>,
- <a href="../src/gdevxxf.c">src/gdevxxf.c</a>.
- <dt>
- Microsoft Windows:
- <dd>
- <a href="../src/gdevmswn.c">src/gdevmswn.c</a>,
- <a href="../src/gdevmswn.h">src/gdevmswn.h</a>,
- <a href="../src/gdevmsxf.c">src/gdevmsxf.c</a>,
- <a href="../src/gdevwddb.c">src/gdevwddb.c</a>,
- <a href="../src/gdevwdib.c">src/gdevwdib.c</a>.
- <dt>
- OS/2 Presentation Manager:
- <dd>
- <a href="../src/gdevpm.c">src/gdevpm.c</a>,
- <a href="../src/gdevpm.h">src/gdevpm.h</a>,
- <a href="../src/gspmdrv.c">src/gspmdrv.c</a>,
- <a href="../src/gspmdrv.h">src/gspmdrv.h</a>.
- </dl>
- <dt>
- Raster file output drivers:
- <dd>
- <dl>
- <dt>
- Fax and TIFF:
- <dd>
- <a href="../src/gdevfax.c">src/gdevfax.c</a>,
- <a href="../src/gdevfax.h">src/gdevfax.h</a>,
- <a href="../src/gdevtfax.c">src/gdevtfax.c</a>,
- <a href="../src/gdevtfax.h">src/gdevtfax.h</a>,
- <a href="../src/gdevtifs.c">src/gdevtifs.c</a>,
- <a href="../src/gdevtifs.h">src/gdevtifs.h</a>,
- <a href="../src/gdevtfnx.c">src/gdevtfnx.c</a>.
- <dt>
- (Low-level) CGM:
- <dd>
- <a href="../src/gdevcgm.c">src/gdevcgm.c</a>,
- <a href="../src/gdevcgml.c">src/gdevcgml.c</a>,
- <a href="../src/gdevcgml.h">src/gdevcgml.h</a>,
- <a href="../src/gdevcgmx.h">src/gdevcgmx.h</a>.
- <dt>
- Other raster file formats:
- <dd>
- <a href="../src/gdevbit.c">src/gdevbit.c</a>,
- <a href="../src/gdevbmp.c">src/gdevbmp.c</a>,
- <a href="../src/gdevbmp.h">src/gdevbmp.h</a>,
- <a href="../src/gdevbmpa.c">src/gdevbmpa.c</a>,
- <a href="../src/gdevbmpc.c">src/gdevbmpc.c</a>,
- <a href="../src/gdevjpeg.c">src/gdevjpeg.c</a>,
- <a href="../src/gdevmiff.c">src/gdevmiff.c</a>,
- <a href="../src/gdevp2up.c">src/gdevp2up.c</a>,
- <a href="../src/gdevpcx.c">src/gdevpcx.c</a>,
- <a href="../src/gdevpbm.c">src/gdevpbm.c</a>,
- <a href="../src/gdevpng.c">src/gdevpng.c</a>,
- <a href="../src/gdevpsim.c">src/gdevpsim.c</a>.
- </dl>
- <dt>
- Printer drivers:
- <dd>
- <dl>
- <dt>
- Operating system printer services:
- <dd>
- <a href="../src/gdevos2p.c">src/gdevos2p.c</a>,
- <a href="../src/gdevwpr2.c">src/gdevwpr2.c</a>,
- <a href="../src/gdevwprn.c">src/gdevwprn.c</a>.
- <dt>
- H-P monochrome printers:
- <dd>
- <a href="../src/gdevdljm.c">src/gdevdljm.c</a>,
- <a href="../src/gdevdljm.h">src/gdevdljm.h</a>,
- <a href="../src/gdevdjet.c">src/gdevdjet.c</a>,
- <a href="../src/gdevlj56.c">src/gdevlj56.c</a>.
- <dt>
- Other printers:
- <dd>
- <a href="../src/gdevatx.c">src/gdevatx.c</a>.
- </dl>
- </dl>
- <h4><a name="Contributed_drivers"></a>Contributed drivers</h4>
- <p>
- This list is likely to be incomplete and inaccurate: see <a
- href="../src/contrib.mak">src/contrib.mak</a> for the real one.
- <dl>
- <dt>
- Display and window system drivers:
- <dd>
- <a href="../src/gdev3b1.c">src/gdev3b1.c</a>,
- <a href="../src/gdevherc.c">src/gdevherc.c</a>,
- <a href="../src/gdevpe.c">src/gdevpe.c</a>,
- <a href="../src/gdevsnfb.c">src/gdevsnfb.c</a>,
- <a href="../src/gdevsun.c">src/gdevsun.c</a>.
- <dt>
- Raster file output drivers:
- <dd>
- <a href="../src/gdevcfax.c">src/gdevcfax.c</a>,
- <a href="../src/gdevcif.c">src/gdevcif.c</a>,
- <a href="../src/gdevdfax.c">src/gdevdfax.c</a>,
- <a href="../src/gdevifno.c">src/gdevifno.c</a>,
- <a href="../src/gdevmgr.c">src/gdevmgr.c</a>,
- <a href="../src/gdevmgr.h">src/gdevmgr.h</a>,
- <a href="../src/gdevsgi.c">src/gdevsgi.c</a>,
- <a href="../src/gdevsgi.h">src/gdevsgi.h</a>,
- <a href="../src/gdevsunr.c">src/gdevsunr.c</a>.
- <dt>
- Printer drivers:
- <dd>
- <a href="../lib/bj8.rpd">lib/bj8.rpd</a>,
- <a href="../lib/cbjc600.ppd">lib/cbjc600.ppd</a>,
- <a href="../lib/cbjc800.ppd">lib/cbjc800.ppd</a>,
- <a href="../src/gdev3852.c">src/gdev3852.c</a>,
- <a href="../src/gdev4081.c">src/gdev4081.c</a>,
- <a href="../src/gdev4693.c">src/gdev4693.c</a>,
- <a href="../src/gdev8510.c">src/gdev8510.c</a>,
- <a href="../src/gdevadmp.c">src/gdevadmp.c</a>,
- <a href="../src/gdevbj10.c">src/gdevbj10.c</a>,
- <a href="../src/gdevbjc.h">src/gdevbjc.h</a>,
- <a href="../src/gdevbjcl.c">src/gdevbjcl.c</a>,
- <a href="../src/gdevbjcl.h">src/gdevbjcl.h</a>,
- <a href="../src/gdevccr.c">src/gdevccr.c</a>,
- <a href="../src/gdevcdj.c">src/gdevcdj.c</a>,
- <a href="../src/gdevclj.c">src/gdevclj.c</a>,
- <a href="../src/gdevcljc.c">src/gdevcljc.c</a>,
- <a href="../src/gdevcp50.c">src/gdevcp50.c</a>,
- <a href="../src/gdevcslw.c">src/gdevcslw.c</a>,
- <a href="../src/gdevdjtc.c">src/gdevdjtc.c</a>,
- <a href="../src/gdevdm24.c">src/gdevdm24.c</a>,
- <a href="../src/gdevepsc.c">src/gdevepsc.c</a>,
- <a href="../src/gdevepsn.c">src/gdevepsn.c</a>,
- <a href="../src/gdevescp.c">src/gdevescp.c</a>,
- <a href="../src/gdevhl7x.c">src/gdevhl7x.c</a>,
- <a href="../src/gdevhpij.c">src/gdevhpij.c</a>,
- <a href="../src/gdevhpij.h">src/gdevhpij.h</a>,
- <a href="../src/gdevijs.c">src/gdevijs.c</a>,
- <a href="../src/gdevimgn.c">src/gdevimgn.c</a>,
- <a href="../src/gdevl31s.c">src/gdevl31s.c</a>,
- <a href="../src/gdevlbp8.c">src/gdevlbp8.c</a>,
- <a href="../src/gdevlp8k.c">src/gdevlp8k.c</a>,
- <a href="../src/gdevlxm.c">src/gdevlxm.c</a>,
- <a href="../src/gdevn533.c">src/gdevn533.c</a>,
- <a href="../src/gdevo182.c">src/gdevo182.c</a>,
- <a href="../src/gdevokii.c">src/gdevokii.c</a>,
- <a href="../src/gdevpcl.c">src/gdevpcl.c</a>,
- <a href="../src/gdevpcl.h">src/gdevpcl.h</a>,
- <a href="../src/gdevphex.c">src/gdevphex.c</a>,
- <a href="../src/gdevpjet.c">src/gdevpjet.c</a>,
- <a href="../src/gdevsj48.c">src/gdevsj48.c</a>,
- <a href="../src/gdevsppr.c">src/gdevsppr.c</a>,
- <a href="../src/gdevstc.c">src/gdevstc.c</a>,
- <a href="../src/gdevstc.h">src/gdevstc.h</a>,
- <a href="../src/gdevstc1.c">src/gdevstc1.c</a>,
- <a href="../src/gdevstc2.c">src/gdevstc2.c</a>,
- <a href="../src/gdevstc3.c">src/gdevstc3.c</a>,
- <a href="../src/gdevstc4.c">src/gdevstc4.c</a>,
- <a href="../src/gdevtknk.c">src/gdevtknk.c</a>,
- <a href="../src/gdevupd.c">src/gdevupd.c</a>.
- </dl>
- <h3><a name="PostScript_interpreter"></a>PostScript interpreter</h3>
- <p>
- The PostScript interpreter is conceptually simple: in fact, an interpreter
- that could execute "3 4 add =" and print "7" was running 3 weeks after the
- first line of Ghostscript code was written. However, a number of
- considerations make the code large and complex.
- <p>
- The interpreter is designed to run in environments with very limited memory.
- The main consequence of this is that it cannot allocate its stacks
- (dictionary, execution, operand) as ordinary arrays, since the
- user-specified stack size limit may be very large. Instead, it allocates
- them as a linked list of blocks. See below for more details.
- <p>
- The interpreter must never cause a C runtime error that it cannot trap.
- Unfortunately, C implementations almost never provide the ability to trap
- stack overflow. In order to put a fixed bound on the C stack size, the
- interpreter never implements PostScript recursion by C recursion. This
- means that any C code that logically needs to call the interpreter must
- instead push a continuation (including all necessary state information) on
- the PostScript execution stack, followed by the PostScript object to be
- executed, and then <em>return</em> to the interpreter. Unfortunately, since
- PostScript Level 2 introduces streams whose data source can be a PostScript
- procedure, any code that reads or writes stream data must be prepared to
- suspend itself, storing all necessary state in a continuation. There are
- some places where this is extremely awkward, such as the scanner/parser.
- <p>
- The use of continuations affects many places in the interpreter, and even
- some places in the graphics library. For example, when processing an image,
- one may need to call a PostScript procedure as part of mapping a CIE color
- to a device color. Ghostscript uses a variety of dodges to handle this: for
- example, in the case of CIE color mapping, all of the PostScript procedures
- are pre-sampled and the results cached. The Adobe implementation limits
- this kind of recursion to a fixed number of levels (5?): this would be
- another acceptable approach, but at this point it would require far more
- code restructuring than it would be worth.
- <p>
- A significant amount of the PostScript language implementation is in fact
- written in PostScript. Writing in PostScript leverages the C code for
- multi-threading, garbage collection, error handling, continuations for
- streams, etc., etc.; also, we have found PostScript in general more concise
- and easier to debug than C, mostly because of memory management issues. So
- given the choice, we tended to implement a feature in PostScript if it
- worked primarily with PostScript data structures, wasn't heavily used
- (example: font loading), or if it interacted with the stream or other
- callback machinery (examples: ReusableFileDecode streams, resourceforall).
- Often we would add non-standard PostScript operators for functions that had
- to run faster or that did more C-like things, such as the media matching
- algorithm for setpagedevice.
- </ul>
- <h4><a name="Main_program"></a>Main program</h4>
- <p>
- The main program of the interpreter is normally invoked from the command
- line, but it has an API as well. In fact, it has two APIs: one that
- recognizes the existence of multiple "interpreter instances" (although it
- currently provides a default instance, which almost all clients use), and a
- completely different one designed for Windows DLLs. These should be unified
- as soon as possible, since there are two steadily growing incompatible
- bodies of client code.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gs.c">src/gs.c</a>,
- <a href="../src/gserver.c">src/gserver.c</a>,
- <a href="../src/iccinit0.c">src/iccinit0.c</a>,
- <a href="../src/iinit.c">src/iinit.c</a>,
- <a href="../src/iinit.h">src/iinit.h</a>,
- <a href="../src/imain.c">src/imain.c</a>,
- <a href="../src/imain.h">src/imain.h</a>,
- <a href="../src/imainarg.c">src/imainarg.c</a>,
- <a href="../src/imainarg.h">src/imainarg.h</a>,
- <a href="../src/iminst.h">src/iminst.h</a>,
- <a href="../src/main.h">src/main.h</a>.
- </dl>
- <h4><a name="Data_structures"></a>Data structures</h4>
- <p>
- The main data structures visible to the PostScript programmers are arrays,
- contexts, dictionaries, names, and stacks.
- <p>
- Arrays have no unusual properties. See under <a href="#Refs">Refs</a> below
- for more information about how array elements are stored.
- <p>
- Contexts are used to hold the interpreter state even in configurations that
- don't include the Display PostScript multiple context extension. Context
- switching is implemented by a complex cooperation of C and PostScript code.
- <p>
- Dictionaries have two special properties worth noting:
- <ul>
- <li>They use an optimized storage representation if all the keys are names,
- which is almost always the case.
- <li>They interact with a caching scheme used to accelerate name lookup in
- the interpreter.
- </ul>
- <p>
- Names are allocated in blocks. The characters and hash chains are stored
- separately from the lookup cache information, so that in the future, most of
- the former can be compiled into the executable and shared or put in ROM.
- (This is not actually done yet.)
- <p>
- As mentioned above, each stack is allocated as a linked list of blocks.
- However, for reasonable performance, operators must normally be able to
- access their operands and produce their results using indexing rather than
- an access procedure. This is implemented by ensuring that all the operands
- of an operator are in the topmost block of the stack, using guard entries
- that cause an internal error if the condition isn't met. See <a
- href="../src/iostack.h">src/iostack.h</a> for more details.
- <dl>
- <dt>
- General data structures:
- <dd>
- <dl>
- <dt>
- Contexts:
- <dd>
- <a href="../src/icontext.c">src/icontext.c</a>,
- <a href="../src/icontext.h">src/icontext.h</a>,
- <a href="../src/icstate.h">src/icstate.h</a>.
- <dt>
- Dictionaries:
- <dd>
- <a href="../src/iddict.h">src/iddict.h</a>,
- <a href="../src/idict.h">src/idict.h</a>,
- <a href="../src/idict.c">src/idict.c</a>,
- <a href="../src/idictdef.h">src/idictdef.h</a>.
- <dt>
- Names:
- <dd>
- <a href="../src/iname.c">src/iname.c</a>,
- <a href="../src/iname.h">src/iname.h</a>,
- <a href="../src/inamedef.h">src/inamedef.h</a>,
- <a href="../src/inameidx.h">src/inameidx.h</a>,
- <a href="../src/inames.h">src/inames.h</a>,
- <a href="../src/inamestr.h">src/inamestr.h</a>.
- <dt>
- Stacks:
- <dd>
- <a href="../src/isdata.h">src/isdata.h</a>,
- <a href="../src/istack.c">src/istack.c</a>,
- <a href="../src/istack.h">src/istack.h</a>,
- <a href="../src/istkparm.h">src/istkparm.h</a>.
- </dl>
- <dt>
- Specific stacks:
- <dd>
- <dl>
- <dt>
- Dictionary stack:
- <dd>
- <a href="../src/dstack.h">src/dstack.h</a>,
- <a href="../src/estack.h">src/estack.h</a>,
- <a href="../src/iddstack.h">src/iddstack.h</a>,
- <a href="../src/idsdata.h">src/idsdata.h</a>,
- <a href="../src/idstack.c">src/idstack.c</a>,
- <a href="../src/idstack.h">src/idstack.h</a>.
- <dt>
- Execution stack:
- <dd>
- <a href="../src/iesdata.h">src/iesdata.h</a>,
- <a href="../src/iestack.h">src/iestack.h</a>.
- <dt>
- Operand stack:
- <dd>
- <a href="../src/iosdata.h">src/iosdata.h</a>,
- <a href="../src/iostack.h">src/iostack.h</a>,
- <a href="../src/ostack.h">src/ostack.h</a>.
- </dl>
- </dl>
- <h4><a name="Interpreter_loop"></a>Interpreter loop</h4>
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/interp.c">src/interp.c</a>,
- <a href="../src/interp.h">src/interp.h</a>.
- </dl>
- <h4><a name="Scanning_parsing"></a>Scanning/parsing</h4>
- <p>
- PostScript parsing consists essentially of token scanning, and is simple in
- principle. The scanner is complex because it must be able to suspend its
- operation at any time (i.e., between any two input characters) to allow an
- interpreter callout, if its input is coming from a procedure-based stream
- and the procedure must be called to provide more input data.
- <dl>
- <dt>
- Main scanner:
- <dd>
- <a href="../src/iscan.c">src/iscan.c</a>,
- <a href="../src/iscan.h">src/iscan.h</a>,
- <a href="../src/iscannum.c">src/iscannum.c</a>,
- <a href="../src/iscannum.h">src/iscannum.h</a>,
- <a href="../src/scanchar.h">src/scanchar.h</a>,
- <a href="../src/scantab.c">src/scantab.c</a>.
- <dt>
- Binary tokens:
- <dd>
- <a href="../src/btoken.h">src/btoken.h</a>,
- <a href="../src/ibnum.c">src/ibnum.c</a>,
- <a href="../src/ibnum.h">src/ibnum.h</a>,
- <a href="../src/inobtokn.c">src/inobtokn.c</a>,
- <a href="../src/iscanbin.c">src/iscanbin.c</a>,
- <a href="../src/iscanbin.h">src/iscanbin.h</a>.
- <dt>
- DSC parsing:
- <dd>
- <a href="../src/dscparse.c">src/dscparse.c</a>,
- <a href="../src/dscparse.h">src/dscparse.h</a>.
- </dl>
- <h4><a name="Standard_operators"></a>Standard operators</h4>
- <dl>
- <dt>
- Non-output-related:
- <dd>
- <dl>
- <dt>
- Filters:
- <dd>
- <a href="../src/ifilter.h">src/ifilter.h</a>,
- <a href="../src/ifilter2.h">src/ifilter2.h</a>,
- <a href="../src/ifrpred.h">src/ifrpred.h</a>,
- <a href="../src/ifwpred.h">src/ifwpred.h</a>,
- <a href="../src/istream.h">src/istream.h</a>,
- <a href="../src/zfbcp.c">src/zfbcp.c</a>,
- <a href="../src/zfdctd.c">src/zfdctd.c</a>,
- <a href="../src/zfdcte.c">src/zfdcte.c</a>,
- <a href="../src/zfdecode.c">src/zfdecode.c</a>,
- <a href="../src/zfilter.c">src/zfilter.c</a>,
- <a href="../src/zfilter2.c">src/zfilter2.c</a>,
- <a href="../src/zfilterx.c">src/zfilterx.c</a>,
- <a href="../src/zfmd5.c">src/zfmd5.c</a>,
- <a href="../src/zfarc4.c">src/zfarc4.c</a>,
- <a href="../src/zfproc.c">src/zfproc.c</a>,
- <a href="../src/zfrsd.c">src/zfrsd.c</a>,
- <a href="../src/zfzlib.c">src/zfzlib.c</a>.
- <dt>
- File and stream I/O:
- <dd>
- <a href="../src/files.h">src/files.h</a>,
- <a href="../src/itoken.h">src/itoken.h</a>,
- <a href="../src/zbseq.c">src/zbseq.c</a>,
- <a href="../src/zdscpars.c">src/zdscpars.c</a>,
- <a href="../src/zfile.c">src/zfile.c</a>,
- <a href="../src/zfileio.c">src/zfileio.c</a>,
- <a href="../src/ztoken.c">src/ztoken.c</a>.
- <dt>
- Data structures:
- <dd>
- <a href="../src/zarray.c">src/zarray.c</a>,
- <a href="../src/zdict.c">src/zdict.c</a>,
- <a href="../src/zgeneric.c">src/zgeneric.c</a>,
- <a href="../src/zpacked.c">src/zpacked.c</a>,
- <a href="../src/zstring.c">src/zstring.c</a>.
- <dt>
- Functions:
- <dd>
- <a href="../src/ifunc.h">src/ifunc.h</a>,
- <a href="../src/zfunc.c">src/zfunc.c</a>,
- <a href="../src/zfunc0.c">src/zfunc0.c</a>,
- <a href="../src/zfunc3.c">src/zfunc3.c</a>,
- <a href="../src/zfunc4.c">src/zfunc4.c</a>,
- <dt>
- Other:
- <dd>
- <a href="../src/ivmem2.h">src/ivmem2.h</a>,
- <a href="../src/zarith.c">src/zarith.c</a>,
- <a href="../src/zcontext.c">src/zcontext.c</a>,
- <a href="../src/zcontrol.c">src/zcontrol.c</a>,
- <a href="../src/zmath.c">src/zmath.c</a>,
- <a href="../src/zmatrix.c">src/zmatrix.c</a>,
- <a href="../src/zmisc.c">src/zmisc.c</a>,
- <a href="../src/zmisc1.c">src/zmisc1.c</a>,
- <a href="../src/zmisc2.c">src/zmisc2.c</a>,
- <a href="../src/zmisc3.c">src/zmisc3.c</a>,
- <a href="../src/zrelbit.c">src/zrelbit.c</a>,
- <a href="../src/zstack.c">src/zstack.c</a>,
- <a href="../src/ztype.c">src/ztype.c</a>,
- <a href="../src/zusparam.c">src/zusparam.c</a>,
- <a href="../src/zvmem.c">src/zvmem.c</a>,
- <a href="../src/zvmem2.c">src/zvmem2.c</a>.
- </dl>
- <dt>
- Output-related:
- <dd>
- <dl>
- <dt>
- Device management:
- <dd>
- <a href="../src/zdevcal.c">src/zdevcal.c</a>,
- <a href="../src/zdevice.c">src/zdevice.c</a>,
- <a href="../src/zdevice2.c">src/zdevice2.c</a>,
- <a href="../src/ziodev.c">src/ziodev.c</a>,
- <a href="../src/ziodev2.c">src/ziodev2.c</a>,
- <a href="../src/ziodevs.c">src/ziodevs.c</a>,
- <a href="../src/ziodevsc.c">src/ziodevsc.c</a>,
- <a href="../src/zmedia2.c">src/zmedia2.c</a>,
- <a href="../src/zdfilter.c">src/zdfilter.c</a>.
- <dt>
- Fonts and text:
- <dd>
- <a href="../src/bfont.h">src/bfont.h</a>,
- <a href="../src/ccfont.h">src/ccfont.h</a>,
- <a href="../src/iccfont.c">src/iccfont.c</a>,
- <a href="../src/icfontab.c">src/icfontab.c</a>,
- <a href="../src/ichar.h">src/ichar.h</a>,
- <a href="../src/ichar1.h">src/ichar1.h</a>,
- <a href="../src/icharout.h">src/icharout.h</a>,
- <a href="../src/icid.h">src/icid.h</a>,
- <a href="../src/ifcid.h">src/ifcid.h</a>,
- <a href="../src/ifont.h">src/ifont.h</a>,
- <a href="../src/ifont1.h">src/ifont1.h</a>,
- <a href="../src/ifont2.h">src/ifont2.h</a>,
- <a href="../src/ifont42.h">src/ifont42.h</a>,
- <a href="../src/zbfont.c">src/zbfont.c</a>,
- <a href="../src/zcfont.c">src/zcfont.c</a>,
- <a href="../src/zchar.c">src/zchar.c</a>,
- <a href="../src/zchar1.c">src/zchar1.c</a>,
- <a href="../src/zchar2.c">src/zchar2.c</a>,
- <a href="../src/zchar32.c">src/zchar32.c</a>,
- <a href="../src/zchar42.c">src/zchar42.c</a>,
- <a href="../src/zcharout.c">src/zcharout.c</a>,
- <a href="../src/zcharx.c">src/zcharx.c</a>,
- <a href="../src/zcid.c">src/zcid.c</a>,
- <a href="../src/zfcid.c">src/zfcid.c</a>,
- <a href="../src/zfcid0.c">src/zfcid0.c</a>,
- <a href="../src/zfcid1.c">src/zfcid1.c</a>,
- <a href="../src/zfcmap.c">src/zfcmap.c</a>,
- <a href="../src/zfont.c">src/zfont.c</a>,
- <a href="../src/zfont0.c">src/zfont0.c</a>,
- <a href="../src/zfont1.c">src/zfont1.c</a>,
- <a href="../src/zfont2.c">src/zfont2.c</a>,
- <a href="../src/zfont32.c">src/zfont32.c</a>,
- <a href="../src/zfont42.c">src/zfont42.c</a>.
- <dt>
- Color, pattern, and halftone:
- <dd>
- <a href="../src/icie.h">src/icie.h</a>,
- <a href="../src/icolor.h">src/icolor.h</a>,
- <a href="../src/icremap.h">src/icremap.h</a>,
- <a href="../src/icsmap.h">src/icsmap.h</a>,
- <a href="../src/iht.h">src/iht.h</a>,
- <a href="../src/ipcolor.h">src/ipcolor.h</a>,
- <a href="../src/zcie.c">src/zcie.c</a>,
- <a href="../src/zcolor.c">src/zcolor.c</a>,
- <a href="../src/zcolor1.c">src/zcolor1.c</a>,
- <a href="../src/zcolor2.c">src/zcolor2.c</a>,
- <a href="../src/zcrd.c">src/zcrd.c</a>,
- <a href="../src/zcsdevn.c">src/zcsdevn.c</a>,
- <a href="../src/zcsindex.c">src/zcsindex.c</a>,
- <a href="../src/zcspixel.c">src/zcspixel.c</a>,
- <a href="../src/zcssepr.c">src/zcssepr.c</a>,
- <a href="../src/zicc.c">src/zicc.c</a>,
- <a href="../src/zhsb.c">src/zhsb.c</a>,
- <a href="../src/zht.c">src/zht.c</a>,
- <a href="../src/zht1.c">src/zht1.c</a>,
- <a href="../src/zht2.c">src/zht2.c</a>,
- <a href="../src/zpcolor.c">src/zpcolor.c</a>,
- <a href="../src/zshade.c">src/zshade.c</a>,
- <a href="../src/ztrans.c">src/ztrans.c</a>.
- <dt>
- Images:
- <dd>
- <a href="../src/iimage.h">src/iimage.h</a>,
- <a href="../src/iimage2.h">src/iimage2.h</a>,
- <a href="../src/zimage.c">src/zimage.c</a>,
- <a href="../src/zimage2.c">src/zimage2.c</a>,
- <a href="../src/zimage3.c">src/zimage3.c</a>.
- <dt>
- Other graphics:
- <dd>
- <a href="../src/igstate.h">src/igstate.h</a>,
- <a href="../src/zdpnext.c">src/zdpnext.c</a>,
- <a href="../src/zdps.c">src/zdps.c</a>,
- <a href="../src/zdps1.c">src/zdps1.c</a>,
- <a href="../src/zgstate.c">src/zgstate.c</a>,
- <a href="../src/zpaint.c">src/zpaint.c</a>,
- <a href="../src/zpath.c">src/zpath.c</a>,
- <a href="../src/zpath1.c">src/zpath1.c</a>,
- <a href="../src/zrop.c">src/zrop.c</a>,
- <a href="../src/ztrap.c">src/ztrap.c</a>,
- <a href="../src/zupath.c">src/zupath.c</a>.
- </dl>
- <dt>
- Operator support:
- <dd>
- <a href="../src/oparc.h">src/oparc.h</a>,
- <a href="../src/opcheck.h">src/opcheck.h</a>,
- <a href="../src/opdef.h">src/opdef.h</a>,
- <a href="../src/oper.h">src/oper.h</a>,
- <a href="../src/opextern.h">src/opextern.h</a>.
- </dl>
- <h4><a name="Non_standard_operators"></a>Non-standard operators</h4>
- <p>
- The interpreter includes many non-standard operators. Most of these provide
- some part of the function of a standard operator, so that the standard
- operator itself can be implemented in PostScript: these are not of interest
- to users, and their function is usually obvious from the way they are used.
- However, some non-standard operators provide access to additional,
- non-standard facilities that users might want to know about, such as
- transparency, RasterOp, and in-memory rendering. These are documented at <a
- href="Language.htm#Additional_operators">Language.htm#Additional_operators</a>.
- <p>
- We don't document the complete set of non-standard operators here, because
- the set changes frequently. However, all non-standard operators are
- supposed to have names that begin with '.', so you can find them all by
- executing the following (Unix) command:
- <blockquote><pre>
- grep '{".[.]' src/[zi]*.c
- </pre></blockquote>
- <p>
- In addition to individual non-standard operators implemented in the same
- files as standard ones, there are several independent optional packages of
- non-standard operators. As with other non-standard operators, the names of
- all the operators in these packages begin with '.'. We list those packages
- here.
- <dl>
- <dt>
- <a href="../src/zdosio.c">src/zdosio.c</a>
- <dd>
- Provides access to PC hardware I/O through MS-DOS system calls. Probably no
- longer useful.
- <dt>
- <a href="../src/zdouble.c">src/zdouble.c</a>
- <dd>
- Provides "double" floating point arithmetic, using 8-byte strings to hold
- values. Developed under a contract; probably used only by the group that
- funded the development.
- <dt>
- <a href="../src/zsysvm.c">src/zsysvm.c</a>
- <dd>
- Provides operators for allocating objects in specific VM spaces,
- disregarding the current VM mode.
- <dt>
- <a href="../src/zccube.c">src/zccube.c</a>
- <dd>
- Provides an operator for building a color cube from an arbitrary tint
- transform, so that tint transforms can be applied from inside the
- graphics library without calling back to the PostScript interpreter.
- </dl>
- <h4><a name="Interpreter_support"></a>Interpreter support</h4>
- <p>
- Memory management (refs, GC, save/restore) -- see <a
- href="#PostScript_interpreter_extensions">below</a>.
- <dl>
- <dt>
- Miscellaneous support:
- <dd>
- <a href="../src/errors.h">src/errors.h</a>,
- <a href="../src/ghost.h">src/ghost.h</a>,
- <a href="../src/iconf.c">src/iconf.c</a>,
- <a href="../src/iconf.h">src/iconf.h</a>,
- <a href="../src/idparam.c">src/idparam.c</a>,
- <a href="../src/idparam.h">src/idparam.h</a>,
- <a href="../src/ilevel.h">src/ilevel.h</a>,
- <a href="../src/inouparm.c">src/inouparm.c</a>,
- <a href="../src/iparam.c">src/iparam.c</a>,
- <a href="../src/iparam.h">src/iparam.h</a>,
- <a href="../src/iparray.h">src/iparray.h</a>,
- <a href="../src/iutil.c">src/iutil.c</a>,
- <a href="../src/iutil.h">src/iutil.h</a>,
- <a href="../src/iutil2.c">src/iutil2.c</a>,
- <a href="../src/iutil2.h">src/iutil2.h</a>,
- <a href="../src/iutilasm.asm">src/iutilasm.asm</a>.
- </dl>
- <h4><a name="PostScript_code"></a>PostScript code</h4>
- <dl>
- <dt>
- Initialization and language support:
- <dd>
- <dl>
- <dt>
- All configurations:
- <dd>
- <a href="../lib/gs_init.ps">lib/gs_init.ps</a>,
- <a href="../lib/gs_statd.ps">lib/gs_statd.ps</a>.
- <dt>
- Level 2:
- <dd>
- <a href="../lib/gs_btokn.ps">lib/gs_btokn.ps</a>,
- <a href="../lib/gs_dps1.ps">lib/gs_dps1.ps</a>,
- <a href="../lib/gs_dps2.ps">lib/gs_dps2.ps</a>,
- <a href="../lib/gs_lev2.ps">lib/gs_lev2.ps</a>,
- <a href="../lib/gs_res.ps">lib/gs_res.ps</a>,
- <a href="../lib/gs_setpd.ps">lib/gs_setpd.ps</a>.
- <dt>
- LanguageLevel 3:
- <dd>
- <a href="../lib/gs_frsd.ps">lib/gs_frsd.ps</a>,
- <a href="../lib/gs_ll3.ps">lib/gs_ll3.ps</a>,
- <a href="../lib/gs_trap.ps">lib/gs_trap.ps</a>.
- <dt>
- Display PostScript:
- <dd>
- <a href="../lib/gs_dpnxt.ps">lib/gs_dpnxt.ps</a>,
- <a href="../lib/gs_dps.ps">lib/gs_dps.ps</a>.
- <dt>
- ICC color profiles:
- <dd>
- <a href="../lib/gs_icc.ps">lib/gs_icc.ps</a>.
- </dl>
- <dt>
- Font loading and support:
- <dd>
- <dl>
- <dt>
- Font name mapping:
- <dd>
- <a href="../lib/Fontmap">lib/Fontmap</a>,
- <a href="../lib/Fontmap.ATB">lib/Fontmap.ATB</a>,
- <a href="../lib/Fontmap.ATM">lib/Fontmap.ATM</a>,
- <a href="../lib/Fontmap.GS">lib/Fontmap.GS</a>,
- <a href="../lib/Fontmap.OS2">lib/Fontmap.OS2</a>,
- <a href="../lib/Fontmap.OSF">lib/Fontmap.OSF</a>,
- <a href="../lib/Fontmap.SGI">lib/Fontmap.SGI</a>,
- <a href="../lib/Fontmap.Sol">lib/Fontmap.Sol</a>,
- <a href="../lib/Fontmap.Ult">lib/Fontmap.Ult</a>,
- <a href="../lib/Fontmap.VMS">lib/Fontmap.VMS</a>.
- <dt>
- Generic:
- <dd>
- <a href="../lib/gs_ccfnt.ps">lib/gs_ccfnt.ps</a>,
- <a href="../lib/gs_fonts.ps">lib/gs_fonts.ps</a>.
- <dt>
- Type 1 and CFF:
- <dd>
- <a href="../lib/gs_cff.ps">lib/gs_cff.ps</a>,
- <a href="../lib/gs_diskf.ps">lib/gs_diskf.ps</a>,
- <a href="../lib/gs_type1.ps">lib/gs_type1.ps</a>.
- <dt>
- TrueType:
- <dd>
- <a href="../lib/gs_ttf.ps">lib/gs_ttf.ps</a>,
- <a href="../lib/gs_typ42.ps">lib/gs_typ42.ps</a>.
- <dt>
- CID-keyed:
- <dd>
- <a href="../lib/gs_cidcm.ps">lib/gs_cidcm.ps</a>,
- <a href="../lib/gs_cidfn.ps">lib/gs_cidfn.ps</a>,
- <a href="../lib/gs_cmap.ps">lib/gs_cmap.ps</a>.
- <dt>
- Other:
- <dd>
- <a href="../lib/gs_kanji.ps">lib/gs_kanji.ps</a>,
- <a href="../lib/gs_pfile.ps">lib/gs_pfile.ps</a>,
- <a href="../lib/gs_typ32.ps">lib/gs_typ32.ps</a>.
- </dl>
- <dt>
- Encodings:
- <dd>
- <dl>
- <dt>
- Adobe-specified:
- <dd>
- <a href="../lib/gs_ce_e.ps">lib/gs_ce_e.ps</a>,
- <a href="../lib/gs_dbt_e.ps">lib/gs_dbt_e.ps</a>,
- <a href="../lib/gs_il1_e.ps">lib/gs_il1_e.ps</a>,
- <a href="../lib/gs_mex_e.ps">lib/gs_mex_e.ps</a>,
- <a href="../lib/gs_mro_e.ps">lib/gs_mro_e.ps</a>,
- <a href="../lib/gs_pdf_e.ps">lib/gs_pdf_e.ps</a>,
- <a href="../lib/gs_std_e.ps">lib/gs_std_e.ps</a>,
- <a href="../lib/gs_sym_e.ps">lib/gs_sym_e.ps</a>,
- <a href="../lib/gs_wan_e.ps">lib/gs_wan_e.ps</a>.
- <dt>
- Additional:
- <dd>
- <a href="../lib/gs_il2_e.ps">lib/gs_il2_e.ps</a>,
- <a href="../lib/gs_ksb_e.ps">lib/gs_ksb_e.ps</a>,
- <a href="../lib/gs_wl1_e.ps">lib/gs_wl1_e.ps</a>,
- <a href="../lib/gs_wl2_e.ps">lib/gs_wl2_e.ps</a>,
- <a href="../lib/gs_wl5_e.ps">lib/gs_wl5_e.ps</a>.
- <dt>
- Pseudo-encodings for internal use:
- <dd>
- <a href="../lib/gs_css_e.ps">lib/gs_css_e.ps</a>,
- <a href="../lib/gs_lgo_e.ps">lib/gs_lgo_e.ps</a>,
- <a href="../lib/gs_lgx_e.ps">lib/gs_lgx_e.ps</a>,
- <a href="../lib/gs_mgl_e.ps">lib/gs_mgl_e.ps</a>.
- </dl>
- <dt>
- Miscellaneous:
- <dd>
- <dl>
- <dt>
- Other support:
- <dd>
- <a href="../lib/gs_agl.ps">lib/gs_agl.ps</a>,
- <a href="../lib/gs_dscp.ps">lib/gs_dscp.ps</a>,
- <a href="../lib/gs_epsf.ps">lib/gs_epsf.ps</a>,
- <a href="../lib/gs_pdfwr.ps">lib/gs_pdfwr.ps</a>,
- <a href="../lib/gs_rdlin.ps">lib/gs_rdlin.ps</a>.
- <dt>
- X Windows icon bitmaps:
- <dd>
- <a href="../lib/gs_l.xbm">lib/gs_l.xbm</a>,
- <a href="../lib/gs_l.xpm">lib/gs_l.xpm</a>,
- <a href="../lib/gs_l_m.xbm">lib/gs_l_m.xbm</a>,
- <a href="../lib/gs_m.xbm">lib/gs_m.xbm</a>,
- <a href="../lib/gs_m.xpm">lib/gs_m.xpm</a>,
- <a href="../lib/gs_m_m.xbm">lib/gs_m_m.xbm</a>,
- <a href="../lib/gs_s.xbm">lib/gs_s.xbm</a>,
- <a href="../lib/gs_s.xpm">lib/gs_s.xpm</a>,
- <a href="../lib/gs_s_m.xbm">lib/gs_s_m.xbm</a>,
- <a href="../lib/gs_t.xbm">lib/gs_t.xbm</a>,
- <a href="../lib/gs_t.xpm">lib/gs_t.xpm</a>,
- <a href="../lib/gs_t_m.xbm">lib/gs_t_m.xbm</a>.
- <dt>
- Not currently used:
- <dd>
- <a href="../lib/gs_cmdl.ps">lib/gs_cmdl.ps</a>,
- <a href="../lib/gs_fform.ps">lib/gs_fform.ps</a>,
- <a href="../lib/gs_l2img.ps">lib/gs_l2img.ps</a>.
- </dl>
- </dl>
- <h3><a name="PDF_interpreter"></a>PDF interpreter</h3>
- <p>
- Ghostscript's PDF interpreter is written entirely in PostScript, because its
- data structures are the same as PostScript's, and it is much more convenient
- to manipulate PostScript-like data structures in PostScript than in C.
- There is definitely a performance cost, but apparently not a substantial
- one: we considered moving the main interpreter loop (read a token using
- slightly different syntax than PostScript, push it on the stack if literal,
- look it up in a special dictionary for execution if not) into C, but we did
- some profiling and discovered that this wasn't accounting for enough of the
- time to be worthwhile.
- <p>
- Until recently, there was essentially no C code specifically for the purpose
- of supporting PDF interpretation. The one major exception is the PDF 1.4
- transparency features, which we (but not Adobe) have made available to
- PostScript code.
- <p>
- In addition to patching the <b><tt>run</tt></b> operator to detect PDF
- files, the interpreter provides some procedures in <a
- href="../lib/pdf_main.ps">lib/pdf_main.ps</a> that are meant to be called
- from applications such as previewers.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../lib/pdf_base.ps">lib/pdf_base.ps</a>,
- <a href="../lib/pdf_draw.ps">lib/pdf_draw.ps</a>,
- <a href="../lib/pdf_font.ps">lib/pdf_font.ps</a>,
- <a href="../lib/pdf_main.ps">lib/pdf_main.ps</a>,
- <a href="../lib/pdf_ops.ps">lib/pdf_ops.ps</a>,
- <a href="../lib/pdf_sec.ps">lib/pdf_sec.ps</a>.
- </dl>
- <h3><a name="Build_process"></a>Build process</h3>
- <h4><a name="Makefile_structure"></a>Makefile structure</h4>
- <p>
- Ghostscript's makefiles embody a number of design decisions and assumptions
- that may not be obvious from a casual reading of the code.
- <ul>
- <li>All files are stored in subdirectories. The names of all subdirectories
- used in the build process are defined in the top-level makefiles for the
- various platforms: there are no "hard wired" directory names in any makefile
- rule. Subdirectory names in the makefiles are relative to the directory
- that is current at build time: normally this directory is the parent of the
- various subdirectories, and holds only a <b><tt>makefile</tt></b>, which in
- turn simply references the real top-level makefile in the source
- subdirectory.
- <li>All compiler and linker switches are likewise defined by macros, again
- preferably in the top-level platform makefile.
- <li>There is an absolute distinction between "source-like" subdirectories,
- which are read-only during the build process, and "object-like"
- subdirectories, all of whose contents are generated by the build process and
- which can be emptied (<b><tt>rm *</tt></b>) at any time with no bad
- effects. The source subdirectories are defined by macros named
- <b><tt>xxxSRCDIR</tt></b>.
- <li>Object subdirectories may distinguish further between those that hold
- the results of the build process that are needed at run time (i.e., that
- should be included in a run-time distribution), defined by
- <b><tt>BINDIR</tt></b>, and those that are not needed at run time, defined
- by <b><tt>xxxGENDIR</tt></b> and <b><tt>xxxOBJDIR</tt></b>. (The
- distinction between these is historical and probably no longer relevant.)
- <li>There may be multiple object subdirectories for different build
- configurations. On Unix, the <b><tt>obj</tt></b> and <b><tt>bin</tt></b>
- directories are used for normal production builds, the
- <b><tt>debugobj</tt></b> directory for debugging builds, and the
- <b><tt>pgobj</tt></b> directory for profiling builds; other platforms may
- use different conventions. The Unix makefiles support targets named
- <b><tt>debug</tt></b> and <b><tt>pg</tt></b> for debugging and profiling
- builds respectively; other platforms generally do not.
- <li>Makefiles will be maintained by hand. This requires editing the
- following makefile elements whenever the relevant source files changes:
- <ul>
- <li>Every header (.h) file must have a corresponding macro definition in a
- makefile. If <b><tt>abc.h</tt></b> #includes <b><tt>def.h</tt></b> and
- <b><tt>xyz.h</tt></b>, the definition must have the form
- <blockquote><pre>
- xyz_h=$(xxxSRCD)xyz.h $(def_h) $(xyz_h)
- </pre></blockquote>
- where <b><tt>xxxSRCD</tt></b> is the macro defining the relevant source
- directory (including a trailing '/'). Note that the '.' in the file name
- has been replaced by an underscore. Note also that the definition must
- follow all definitions it references, since some <b><tt>make</tt></b>
- programs expand macros in definitions at the time of definition rather than
- at the time of use.
- <li>Every .c file must have a corresponding rule in a makefile. If
- <b><tt>abc.c</tt></b> #includes <b><tt>def.h</tt></b> and
- <b><tt>lmn.h</tt></b>, the rule must have approximately the form
- <blockquote><pre>
- $(xxxOBJD)abc.$(OBJ) : $(xxxSRCD)abc.c $(def_h) $(lmn_h)
- $(xxCC) $(xxO_)abc.$(OBJ) $(C_) $(xxxSRCD)abc.c
- </pre></blockquote>
- where <b><tt>xxxSRCD</tt></b> is as before; <b><tt>xxxOBJD</tt></b> is the
- relevant object directory; <b><tt>xxCC</tt></b> defines the name of the C
- compiler plus the relevant compilation switches; and <b><tt>xxO_</tt></b>
- and <b><tt>C_</tt></b> are macros used to bridge syntactic differences
- between different <b><tt>make</tt></b> programs.
- </ul>
- </ul>
- <p>
- The requirement to keep makefiles up to date by hand has been controversial.
- Two alternatives are generally proposed.
- <ul>
- <li>Programs like <b><tt>makedeps</tt></b>, which generate build rules
- automatically from the #include lists in C files. We have found such
- programs useless: they "wire in" specific, concrete directory names, not
- only for our own code but even for the system header files; they have to be
- run manually whenever code files are added, renamed, or deleted, or whenever
- the list of #includes in any file changes; and they cannot deal with
- different source files requiring different compilation switches.
- <li>MSVC-style "project" files. These are equally useless: they are not
- portable across different vendors' tools -- in fact, there may not even be a
- usable import/export facility to convert their data to or from text form --
- and they cannot combine configuration-independent data with
- configuration-specific data.
- </ul>
- <p>
- We have seriously considered writing our own build program in Tcl or Python
- that would eliminate these problems, or perhaps porting the tools developed
- by Digital's Vesta research project (if we can get access to them); however,
- either of these approaches would create potential portability problems of
- its own, not to mention difficulties in integrating with others' build
- systems.
- <p>
- In the meantime, to ease the pain for mortal users and developers on
- Unix platforms, we have adopted the standard autoconf tool to
- systematically generate an appropriate top-level makefile for the
- target system. As currently implemented, its use makes no deep changes
- to the Ghostscript build system, but rather generates a makefile, more
- or less the same as would be achieved by starting from a
- platform-specific toplevel makefile and hand-editing. The relevant
- autoconf sources are in <a
- href="../src/Makefile.in">src/Makefile.in</a>, and <a
- href="../src/configure.ac">configure.ac</a>. These sources are used in
- the release process to create a <a href="../configure">configure</a>
- script in the toplevel directory of releases. Also, there is an <a
- href="../autogen.sh">autogen.sh</a> script to automate the autoconf
- process somewhat. The names and locations of these files were chosen
- to be clear to those familiar with autoconf, even though they represent
- a slight departure from Ghostscript tradition.
- <p>
- For more information about makefiles:
- <ul>
- <li>For a detailed list of makefiles, and a discussion of makefile issues
- related to portability, see the <a href="#Makefiles">Makefiles</a> section
- below.
- <li>For more detailed information about editing configuration information in
- makefiles, see <a
- href="Make.htm#Makefile_overview">doc/Make.htm#Makefile_overview</a>.
- <li>For a complete example of adding a new driver to a makefile, see <a
- href="Drivers.htm#Adding_drivers">doc/Drivers.htm#Adding_drivers</a>.
- <li>For a few more notes on makefile coding conventions, see <a
- href="C-style.htm#Makefiles">doc/C-style.htm#Makefiles</a>.
- </ul>
- <h4><a name="dev_files"></a>.dev files</h4>
- <p>
- On top of the general conventions just described, Ghostscript's makefiles
- add a further layer of structure in order to support an open-ended set of
- fine-grained, flexible configuration options. Selecting an option (usually
- called a "module") for inclusion in the build may affect the build in many
- ways:
- <ul>
- <li>Almost always, it requires linking in some compiled code files.
- <li>It may require running some additional initialization procedures at
- startup.
- <li>It may require reading in some additional PostScript files at startup.
- For example, a Level 2 PostScript build requires support for PostScript
- resources and for setpagedevice, which are implemented in PostScript code.
- <li>It may require adding entries to a variety of internal tables that
- catalogue such things as drivers, IODevices, Function types, etc.
- <li>It may require that other particular modules be included. For example,
- the "PostScript Level 2" module requires the modules for various filters,
- color spaces, etc.
- <li>It may require <em>removing</em> some other (default) module from the
- build. For example, the core (Level 1) PostScript build has a "stub" for
- binary tokens, which are a Level 2 feature but are referenced by the core
- scanner: a Level 2 build must remove the stub. For more information about
- this, look for the string <b><tt>-replace</tt></b> in the makefiles and in
- <a href="../src/genconf.c">src/genconf.c</a>.
- </ul>
- <p>
- Each module is defined in the makefiles by rules that create a file named
- <b><em>xxx</em><tt>.dev</tt></b>. The dependencies of the rule include all
- the files that make up the module (compiled code files, PostScript files,
- etc.); the body of the rule creates the .dev file by writing the description
- of the module into it. A program called <b><tt>genconf</tt></b>, described
- in the next section, merges all the relevant .dev files together. For
- examples of .dev rules, see any of the Ghostscript makefiles.
- <p>
- Ultimately, a person must specify the root set of modules to include in a
- build (which of course may require other modules, recursively).
- Ghostscript's makefiles do this with a set of macros called
- <b><tt>FEATURE_DEVS</tt></b> and <b><tt>DEVICE_DEVS</tt>n</b>, defined in
- each top-level makefile, but nothing in the module machinery depends on
- this.
- <h4><a name="Generators"></a>Generators</h4>
- <p>
- Ghostscript's build procedure is somewhat unusual in that it compiles and
- then executes some support programs during the build process. These
- programs then generate data or source code that is used later on in the
- build.
- <p>
- The most important and complex of the generator programs is
- <b><tt>genconf</tt></b>. <b><tt>genconf</tt></b> merges all the .dev files
- that make up the build, and creates three or more output files used in later
- stages:
- <ul>
- <li><b><tt>gconfig.h</tt></b>, consisting mainly of macro calls, one call
- per "resource" making up the build, other than "resources" listed in the
- other output files.
- <li><b><tt>gconfigf.h</tt></b>, produced only for PostScript builds with
- compiled-in fonts, consisting of one macro call per font.
- <li>A linker control file whose name varies from one platform to another,
- containing the list of compiled code files to be linked.
- <li>If necessary, another linker control file, also varying between
- platforms, that contains other information for the linker such as the list
- of system libraries to be searched. (On Unix platforms, the two linker
- control functions are combined in a single file.)
- </ul>
- <dl>
- <dt>
- Source generators:
- <dd>
- <dl>
- <dt>
- <a href="../src/ansi2knr.c">src/ansi2knr.c</a>
- <dd>
- Converts ANSI C source to traditional (also known as "K&R") C. Used if
- and only if compiling with a pre-ANSI C compiler.
- <dt>
- <a href="../src/genarch.c">src/genarch.c</a>
- <dd>
- Creates a header file containing a variety of information about the hardware
- and compiler that isn't provided in any standard system header file. Always
- used.
- <dt>
- <a href="../src/genconf.c">src/genconf.c</a> (also generates non-source)
- <dd>
- Constructs header files and linker control files from the collection of
- options and modules that make up the build. See above. Always used.
- <dt>
- <a href="../src/genht.c">src/genht.c</a>
- <dd>
- Converts a PostScript halftone (in a particular constrained format) to a C
- data structure that can be compiled into an executable. Only used if any
- such halftones are included in the build.
- <dt>
- <a href="../src/geninit.c">src/geninit.c</a>
- <dd>
- Converts PostScript initialization files to C data structures that can be
- compiled into an executable. Only used when building a PostScript
- interpreter, and only if <b><tt>COMPILE_INITS</tt></b> was set to 1 in the
- makefile.
- </dl>
- <dt>
- Other generators:
- <dd>
- <dl>
- <dt>
- <a href="../src/echogs.c">src/echogs.c</a>
- <dd>
- Implements a variety of shell-like functions to get around quirks,
- limitations, and omissions in the shells on various platforms. Always used.
- <dt>
- <a href="../src/genconf.c">src/genconf.c</a> (also generates source)
- <dd>
- See above.
- <dt>
- <a href="../src/gendev.c">src/gendev.c</a> (not used)
- <dd>
- Was intended as a replacement for <b><tt>genconf</tt></b>, but was never
- completed.
- </dl>
- </dl>
- <h4><a name="Build_support"></a>Support</h4>
- <p>
- There are a number of programs, scripts, and configuration files that exist
- only for the sake of the build process.
- <dl>
- <dt>
- Files for PC environments:
- <dd>
- <a href="../src/bcc32.cfg">src/bcc32.cfg</a>,
- <a href="../src/cp.bat">src/cp.bat</a>,
- <a href="../src/cp.cmd">src/cp.cmd</a>,
- <a href="../src/dw32c.def">src/dw32c.def</a>,
- <a href="../src/dwmain.rc">src/dwmain.rc</a>,
- <a href="../src/dwmain16.def">src/dwmain16.def</a>,
- <a href="../src/dwmain32.def">src/dwmain32.def</a>,
- <a href="../src/dwsetup.def">src/dwsetup.def</a>,
- <a href="../src/dwsetup.rc">src/dwsetup.rc</a>,
- <a href="../src/dwuninst.def">src/dwuninst.def</a>,
- <a href="../src/dwuninst.rc">src/dwuninst.rc</a>,
- <a href="../src/gs16spl.def">src/gs16spl.def</a>,
- <a href="../src/gs16spl.rc">src/gs16spl.rc</a>,
- <a href="../src/gsdll2.def">src/gsdll2.def</a>,
- <a href="../src/gsdll2.rc">src/gsdll2.rc</a>,
- <a href="../src/gsdll32.def">src/gsdll32.def</a>,
- <a href="../src/gsdll32.rc">src/gsdll32.rc</a>,
- <a href="../src/gsdll32w.lnk">src/gsdll32w.lnk</a>,
- <a href="../src/gsgraph.icx">src/gsgraph.icx</a>,
- <a href="../src/gsos2.def">src/gsos2.def</a>,
- <a href="../src/gsos2.icx">src/gsos2.icx</a>,
- <a href="../src/gsos2.rc">src/gsos2.rc</a>,
- <a href="../src/gspmdrv.def">src/gspmdrv.def</a>,
- <a href="../src/gspmdrv.icx">src/gspmdrv.icx</a>,
- <a href="../src/gspmdrv.rc">src/gspmdrv.rc</a>,
- <a href="../src/gstext.icx">src/gstext.icx</a>,
- <a href="../src/gswin.rc">src/gswin.rc</a>,
- <a href="../src/gswin32.rc">src/gswin32.rc</a>,
- <a href="../src/gswin386.rc">src/gswin386.rc</a>,
- <a href="../src/mv.bat">src/mv.bat</a>,
- <a href="../src/mv.cmd">src/mv.cmd</a>,
- <a href="../src/rm.bat">src/rm.bat</a>,
- <a href="../src/rm.cmd">src/rm.cmd</a>,
- <a href="../src/turboc.cfg">src/turboc.cfg</a>.
- <dt>
- Files for OpenVMS:
- <dd>
- <a href="../src/append_l.com">src/append_l.com</a>,
- <a href="../src/copy_one.com">src/copy_one.com</a>,
- <a href="../src/rm_all.com">src/rm_all.com</a>,
- <a href="../src/rm_one.com">src/rm_one.com</a>.
- <dt>
- Other files:
- <dd>
- <a href="../src/bench.c">src/bench.c</a>,
- <a href="../src/catmake">src/catmake</a>,
- <a href="../src/ccgs">src/ccgs</a>,
- <a href="../src/instcopy">src/instcopy</a>.
- </dl>
- <h3><a name="Utilities"></a>Utilities</h3>
- <p>
- Ghostscript comes with many utilities for doing things like viewing bitmap
- files and converting between file formats. Some of these are written in
- PostScript, some as scripts, and some as scripts that invoke special
- PostScript code.
- <h4><a name="Utilities_in_PostScript"></a>Utilities in PostScript</h4>
- <p>
- These are all documented in <a href="Psfiles.htm">doc/Psfiles.htm</a>, q.v.
- <h4><a name="Utility_scripts"></a>Utility scripts</h4>
- <p>
- Many of these scripts come in both Unix and MS-DOS (<b><tt>.bat</tt></b>
- versions; some also have an OS/2 (<b><tt>.cmd</tt></b>) version. The choice
- of which versions are provided is historical and irregular. These scripts
- should all be documented somewhere, but currently, many of them have man
- pages, a few have their own documentation in the doc directory, and some
- aren't documented at all.
- <dl>
- <dt>
- Script files without PC versions:
- <dd>
- <a href="../lib/afmdiff.awk">lib/afmdiff.awk</a>,
- <a href="../lib/dvipdf">lib/dvipdf</a>,
- <a href="../lib/fixmswrd.pl">lib/fixmswrd.pl</a>,
- <a href="../lib/lprsetup.sh">lib/lprsetup.sh</a>,
- <a href="../lib/pfbtopfa">lib/pfbtopfa</a>,
- <a href="../lib/pj-gs.sh">lib/pj-gs.sh</a>,
- <a href="../lib/pphs">lib/pphs</a>,
- <a href="../lib/printafm">lib/printafm</a>,
- <a href="../lib/pv.sh">lib/pv.sh</a>,
- <a href="../lib/sysvlp.sh">lib/sysvlp.sh</a>,
- <a href="../lib/unix-lpr.sh">lib/unix-lpr.sh</a>,
- <a href="../lib/wftopfa">lib/wftopfa</a>.
- <dt>
- Script files with PC versions:
- <dd>
- <a href="../lib/bdftops">lib/bdftops</a>,
- <a href="../lib/bdftops.bat">lib/bdftops.bat</a>,
- <a href="../lib/bdftops.cmd">lib/bdftops.cmd</a>,
- <a href="../lib/eps2eps">lib/eps2eps</a>,
- <a href="../lib/eps2eps.bat">lib/eps2eps.bat</a>,
- <a href="../lib/eps2eps.cmd">lib/eps2eps.cmd</a>,
- <a href="../lib/font2c">lib/font2c</a>,
- <a href="../lib/font2c.bat">lib/font2c.bat</a>,
- <a href="../lib/font2c.cmd">lib/font2c.cmd</a>,
- <a href="../lib/gsbj">lib/gsbj</a>,
- <a href="../lib/gsbj.bat">lib/gsbj.bat</a>,
- <a href="../lib/gsdj">lib/gsdj</a>,
- <a href="../lib/gsdj.bat">lib/gsdj.bat</a>,
- <a href="../lib/gsdj500">lib/gsdj500</a>,
- <a href="../lib/gsdj500.bat">lib/gsdj500.bat</a>,
- <a href="../lib/gslj">lib/gslj</a>,
- <a href="../lib/gslj.bat">lib/gslj.bat</a>,
- <a href="../lib/gslp">lib/gslp</a>,
- <a href="../lib/gslp.bat">lib/gslp.bat</a>,
- <a href="../lib/gsnd">lib/gsnd</a>,
- <a href="../lib/gsnd.bat">lib/gsnd.bat</a>,
- <a href="../lib/pdf2dsc">lib/pdf2dsc</a>,
- <a href="../lib/pdf2dsc.bat">lib/pdf2dsc.bat</a>,
- <a href="../lib/pdf2ps">lib/pdf2ps</a>,
- <a href="../lib/pdf2ps.bat">lib/pdf2ps.bat</a>,
- <a href="../lib/pdf2ps.cmd">lib/pdf2ps.cmd</a>,
- <a href="../lib/pdfopt">lib/pdfopt</a>,
- <a href="../lib/pdfopt.bat">lib/pdfopt.bat</a>,
- <a href="../lib/pf2afm">lib/pf2afm</a>,
- <a href="../lib/pf2afm.bat">lib/pf2afm.bat</a>,
- <a href="../lib/pf2afm.cmd">lib/pf2afm.cmd</a>,
- <a href="../lib/ps2ascii">lib/ps2ascii</a>,
- <a href="../lib/ps2ascii.bat">lib/ps2ascii.bat</a>,
- <a href="../lib/ps2ascii.cmd">lib/ps2ascii.cmd</a>,
- <a href="../lib/ps2epsi">lib/ps2epsi</a>,
- <a href="../lib/ps2epsi.bat">lib/ps2epsi.bat</a>,
- <a href="../lib/ps2epsi.cmd">lib/ps2epsi.cmd</a>,
- <a href="../lib/ps2pdf">lib/ps2pdf</a>,
- <a href="../lib/ps2pdf.bat">lib/ps2pdf.bat</a>,
- <a href="../lib/ps2pdf.cmd">lib/ps2pdf.cmd</a>,
- <a href="../lib/ps2pdf12">lib/ps2pdf12</a>,
- <a href="../lib/ps2pdf12.bat">lib/ps2pdf12.bat</a>,
- <a href="../lib/ps2pdf12.cmd">lib/ps2pdf12.cmd</a>,
- <a href="../lib/ps2pdf13">lib/ps2pdf13</a>,
- <a href="../lib/ps2pdf13.bat">lib/ps2pdf13.bat</a>,
- <a href="../lib/ps2pdf13.cmd">lib/ps2pdf13.cmd</a>,
- <a href="../lib/ps2pdf14">lib/ps2pdf14</a>,
- <a href="../lib/ps2pdf14.bat">lib/ps2pdf14.bat</a>,
- <a href="../lib/ps2pdf14.cmd">lib/ps2pdf14.cmd</a>,
- <a href="../lib/ps2pdfwr">lib/ps2pdfwr</a>,
- <a href="../lib/ps2pdfxx.bat">lib/ps2pdfxx.bat</a>,
- <a href="../lib/ps2ps">lib/ps2ps</a>,
- <a href="../lib/ps2ps.bat">lib/ps2ps.bat</a>,
- <a href="../lib/ps2ps.cmd">lib/ps2ps.cmd</a>.
- <dt>
- Script files with only PC versions:
- <dd>
- <a href="../lib/gsndt.bat">lib/gsndt.bat</a>,
- <a href="../lib/gssetgs.bat">lib/gssetgs.bat</a>,
- <a href="../lib/gst.bat">lib/gst.bat</a>,
- <a href="../lib/gstt.bat">lib/gstt.bat</a>,
- <a href="../lib/lp386.bat">lib/lp386.bat</a>,
- <a href="../lib/lp386r2.bat">lib/lp386r2.bat</a>,
- <a href="../lib/lpgs.bat">lib/lpgs.bat</a>,
- <a href="../lib/lpr2.bat">lib/lpr2.bat</a>,
- <a href="../lib/pftogsf.bat">lib/pftogsf.bat</a>,
- <a href="../lib/wmakebat.bat">lib/wmakebat.bat</a>.
- </dl>
- <hr>
- <h2><a name="Memory_management"></a>Memory management</h2>
- <h3><a name="Memory_manager_architecture"></a>Memory manager architecture</h3>
- <p>
- In many environments, the memory manager is a set of library facilities that
- implicitly manage the entire address space in a homogenous manner.
- Ghostscript's memory manager architecture has none of these properties:
- <ul>
- <li>Rather than a single library accessed as procedures, Ghostscript
- includes multiple allocator types, each of which in turn may have multiple
- instances (allocators). Allocators are 'objects' with a substantial set of
- virtual functions.
- <li>Rather than managing the entire address space, each allocator manages a
- storage pool, which it may or may not be able to expand or reduce by calling
- on a 'parent' allocator.
- <li>Rather than a single genus of untyped storage blocks, Ghostscript's
- allocators provide two genera -- type-tagged 'objects', and 'strings' --
- with substantially different properties.
- </ul>
- <h4><a name="Objects_vs_strings"></a>Objects vs strings</h4>
- <p>
- As noted above, allocators provide two different storage genera.
- <p>
- Objects:
- <ul>
- <li>Are aligned in storage to satisfy the most stringent alignment
- requirement imposed by the CPU or compiler;
- <li>Can be referenced only by pointers to their start, not to any internal
- location, unless special arrangements are made;
- <li>May contain pointers to other objects, or to strings;
- <li>Have an associated <em>structure descriptor</em> that specifies their
- size (usually) and the location of any pointers contained within them.
- </ul>
- <p>
- Given a pointer to an object, the allocator that allocated it must be able
- to return the object's size and the pointer to its structure descriptor.
- (It is up to the client to know what allocator allocated an object.)
- <p>
- Strings:
- <ul>
- <li>Are not aligned in storage;
- <li>Can be referenced by pointers (consisting of a starting address and a
- length) to any substring, starting anywhere within the string;
- <li>May not contain pointers;
- <li>Do not have a structure descriptor.
- </ul>
- <p>
- The object/string distinction reflects a space/capability tradeoff. The
- per-object space overhead of the standard type of allocator is typically 12
- bytes; this is too much to impose on every string of a few bytes. On the
- other hand, restricting object pointers to reference the start of the object
- currently makes object garbage collection and compaction more
- space-efficient. If we were to redesign the standard allocator, we would
- probably opt for a different design in which strings were allocated within
- container objects of a few hundred bytes, and pointers into the middle of
- all objects were allowed.
- <h4><a name="Structure_descriptors"></a>Structure descriptors</h4>
- <p>
- Every object allocated by a Ghostscript allocator has an associated
- structure descriptor, which the caller provides when allocating the object.
- The structure descriptor serves several purposes:
- <ul>
- <li>Specifying the size of the object for allocation;
- <li>Providing pointer-enumeration and pointer-relocation procedures for
- the garbage collector;
- <li>Providing an optional finalization procedure to be called when the
- object is freed (either explicitly or automatically).
- </ul>
- <p>
- Structure descriptors are read-only, and are normally defined statically
- using one of the large set of <b><tt>gs_private_st_</tt></b> or
- <b><tt>gs_public_st_</tt></b> macros in <a
- href="../src/gsstruct.h">src/gsstruct.h</a>.
- <p>
- While the structure descriptor normally specifies the size of the object,
- one can also allocate an array of bytes or objects, whose size is a multiple
- of the size in the descriptor. For this reason, every object stores its
- size as well as a reference to its descriptor.
- <p>
- Because the standard Ghostscript garbage collector is conservative and can
- move objects, every object allocated by a Ghostscript allocator must have an
- accurate structure descriptor. If you define a new type of object
- (structure) that will be allocated in storage managed by Ghostscript, you
- <em>must</em> create an accurate descriptor for it, and use that descriptor
- to allocate it. The process of creating accurate descriptors for all
- structures was long and painful, and accounted for many hard-to-diagnose
- bugs.
- <p>
- By convention, the structure descriptor for structure type
- <b><tt>xxx_t</tt></b> is named <b><tt>st_xxx</tt></b> (this is preferred),
- or occasionally <b><tt>st_xxx_t</tt></b>.
- <p>
- Note that a structure descriptor is only required for objects allocated by
- the Ghostscript allocator. A structure type <b><tt>xxx_t</tt></b> does not
- require a structure descriptor if instances of that type are used
- <em>only</em> in the following ways:
- <ul>
- <li>Instances are allocated only on the C stack, e.g., as
- <b><tt>xxx_t xxx1, xxx2;</tt></b>, or on the C heap, with
- <b><tt>malloc</tt></b> or through the Ghostscript "wrapper" defined in <a
- href="../src/gsmalloc.h">src/gsmalloc.h</a>.
- <li>Pointers to instances are not stored in places where the garbage
- collector will try to trace the pointer.
- <li>Code never attempts to get the structure type or size of an instance
- through the allocator API.
- </ul>
- <p>
- In general, structures without descriptors are problem-prone, and are
- deprecated; in new code, they should only be used if the structure is
- confined to a single .c file and its instances are only allocated on the C
- stack.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsstruct.h">src/gsstruct.h</a>,
- <a href="../src/gsstype.h">src/gsstype.h</a>.
- </dl>
- <h4><a name="Garbage_collection"></a>Garbage collection</h4>
- <p>
- The allocator architecture is designed to support compacting garbage
- collection. Every object must be able to enumerate all the pointers it
- contains, both for tracing and for relocation. As noted just above, the
- structure descriptor provides procedures that do this.
- <p>
- Whether or not a particular allocator type actually provides a garbage
- collector is up to the allocator: garbage collection is invoked through a
- virtual procedure. In practice, however, there are only two useful garbage
- collectors for Ghostscript's own allocator:
- <ul>
- <li>The "real" garbage collector associated with the PostScript interpreter,
- described <a href="#Interpreter_GC">below</a>;
- <li>A "non" garbage collector that only merges adjacent free blocks.
- </ul>
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsgc.h">src/gsgc.h</a>,
- <a href="../src/gsnogc.c">src/gsnogc.c</a>,
- <a href="../src/gsnogc.h">src/gsnogc.h</a>.
- </dl>
- <h4><a name="Movability"></a>Movability</h4>
- <p>
- As just noted, objects are normally movable by the garbage collector.
- However, some objects must be immovable, usually because some other piece of
- software must retain pointers to them. The allocator API includes
- procedures for allocating both movable (default) and immovable objects.
- Note, however, that even immovable objects must be traceable (have a
- structure descriptor), and may be freed, by the garbage collector.
- <h4><a name="Parent_hierarchy"></a>Parent hierarchy</h4>
- <p>
- When an allocator needs to add memory to the pool that it manages, it
- requests the memory from its <em>parent</em> allocator. Every allocator has
- a pointer to its parent; multiple allocators may share a single parent. The
- ultimate ancestor of all allocators that can expand their pool dynamically
- is an allocator that calls <b><tt>malloc</tt></b>, described <a
- href="#malloc">below</a>. However, especially in embedded environments, an
- allocator may be limited to a fixed-size pool assigned to it when it is
- created.
- <h4><a name="Allocator_API"></a>Allocator API</h4>
- In summary, the allocator API provides the following principal operations:
- <ul>
- <li>Allocate and free movable (default) or immovable objects and strings.
- <li>Return the structure type and size of an object.
- <li>Resize (shrink or grow) movable objects and strings, preserving
- the contents insofar as possible.
- <li>Report the size of the managed pool, and how much of it is in use.
- <li>Register and unregister root pointers for the garbage collector.
- <li>Free the allocator itself.
- <li>Consolidate adjacent free blocks to reduce fragmentation.
- </ul>
- <p>
- For details, see <a href="../src/gsmemory.h">src/gsmemory.h</a>.
- <p>
- The allocator API also includes one special hook for the PostScript
- interpreter: the concept of stable allocators. See the section on <a
- href="#save_forgetsave_restore"><b><tt>save</tt></b> and
- <b><tt>restore</tt></b></a> below for details.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsmemraw.h">src/gsmemraw.h</a>,
- <a href="../src/gsmemory.c">src/gsmemory.c</a>,
- <a href="../src/gsmemory.h">src/gsmemory.h</a>,
- <a href="../src/gsstruct.h">src/gsstruct.h</a>,
- <a href="../src/gsstype.h">src/gsstype.h</a>.
- </dl>
- <h3><a name="Freeing_storage"></a>Freeing storage</h3>
- <p>
- Ghostscript's memory management architecture provides three different ways
- to free objects: explicitly, by reference counting, or by garbage
- collection. They provide different safety / performance / convenience
- tradeoffs; we believe that all three are necessary.
- <p>
- Objects are always freed as a whole; strings may be freed piecemeal.
- <p>
- An object may have an associated finalization procedure, defined in the
- structure descriptor. This procedure is called just before the object is
- freed, independent of which method is being used to free the object. A few
- types of objects have a virtual finalization procedure as well: the
- finalization procedure defined in the descriptor simply calls the one in the
- object.
- <h4><a name="Explicit_freeing"></a>Explicit freeing</h4>
- <p>
- Objects and strings may be freed explicitly, using the
- <b><tt>gs_free_</tt></b> virtual procedures in the allocator API. It is up
- to the client to ensure that all allocated objects are freed at most once,
- and that there are no dangling pointers.
- <p>
- Explicit freeing is the fastest method, but is the least convenient and
- least safe. It is most appropriate when storage is freed in the same
- procedure where it is allocated, or for storage that is known to be
- referenced by only one pointer.
- <h4><a name="Reference_counting"></a>Reference counting</h4>
- <p>
- Objects may be managed by reference counting. When an object is allocated,
- its reference count may be set to 0 or 1. Subsequently, when the reference
- count is decremented to 0, the object is freed.
- <p>
- The reference counting machinery provides its own virtual finalization
- procedure for all reference-counted objects. The machinery calls this
- procedure when it is about to free the object (but not when the object is
- freed in any other way, which is probably a design bug). This is in
- addition to (and called before) any finalization procedure associated with
- the object type.
- <p>
- Reference counting is as fast as explicit freeing, but takes more space in
- the object. It is most appropriate for relatively large objects which are
- referenced only from a small set of pointers. Note that reference counting
- cannot free objects that are involved in a pointer cycle (e.g., A -> B -> C
- -> A).
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsrefct.h">src/gsrefct.h</a>.
- </dl>
- <h4><a name="Real_garbage_collection"></a>(Real) garbage collection</h4>
- <p>
- Objects and strings may be freed automatically by a garbage collector. See
- <a href="#Interpreter_GC">below</a>.
- <h3><a name="Special_implementations"></a>Special implementations</h3>
- <h4><a name="malloc"></a>malloc</h4>
- <p>
- As mentioned <a href="#Parent_hierarchy">above</a>, the ultimate ancestor of
- all allocators with an expandable pool is one that calls
- <b><tt>malloc</tt></b>.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsmalloc.h">src/gsmalloc.h</a>,
- <a href="../src/gsmalloc.c">src/gsmalloc.c</a>.
- </dl>
- <h4><a name="Locking"></a>Locking</h4>
- <p>
- In a multi-threaded environment, if an allocator must be callable from
- multiple threads (for example, if it is used to allocate structures in one
- thread that are passed to, and freed by, another thread), the allocator must
- provide mutex protection. Ghostscript provides this capability in the form
- of a <em>wrapper</em> allocator, that simply forwards all calls to a
- <em>target</em> allocator under protection of a mutex. Using the wrapper
- technique, any allocator can be made thread-safe.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsmemlok.h">src/gsmemlok.h</a>,
- <a href="../src/gsmemlok.c">src/gsmemlok.c</a>.
- </dl>
- <h4><a name="Retrying"></a>Retrying</h4>
- <p>
- In an embedded environment, job failure due to memory exhaustion is very
- undesirable. Ghostscript provides a wrapper allocator that, when an
- allocation attempt fails, calls a client-provided procedure that can attempt
- to free memory, then ask for the original allocation to be retried. For
- example, such a procedure can wait for a queue to empty, or can free memory
- occupied by caches.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsmemret.h">src/gsmemret.h</a>,
- <a href="../src/gsmemret.c">src/gsmemret.c</a>.
- </dl>
- <h3><a name="Standard_implementation"></a>Standard implementation</h3>
- <p>
- The standard Ghostscript allocator gets storage from its parent (normally
- the <b><tt>malloc</tt></b> allocator) in large blocks called
- <em>chunks</em>, and then allocates objects up from the low end and strings
- down from the high end. Large objects or strings are allocated in their own
- chunk.
- <p>
- The standard allocator maintains a set of free-block lists for small object
- sizes, one list per size (rounded up to the word size), plus a free-block
- list for large objects (but not for objects so large that they get their own
- chunk: when such an object is freed, its chunk is returned to the parent).
- The lists are not sorted; adjacent blocks are only merged if needed.
- <p>
- While the standard allocator implements the generic allocator API, and is
- usable with the library alone, it includes a special hook for the PostScript
- interpreter to aid in the efficient allocation of PostScript composite
- objects (arrays and dictionaries). See the section on <a
- href="#Refs">Refs</a> below for details.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/gsalloc.c">src/gsalloc.c</a>,
- <a href="../src/gsalloc.h">src/gsalloc.h</a>,
- <a href="../src/gxalloc.h">src/gxalloc.h</a>,
- <a href="../src/gxobj.h">src/gxobj.h</a>.
- </dl>
- <h3><a name="PostScript_interpreter_extensions"></a>PostScript interpreter extensions</h3>
- <p>
- The PostScript interpreter uses an allocator that extends the graphic
- library's standard allocator to handle PostScript objects,
- <b><tt>save</tt></b> and <b><tt>restore</tt></b>, and real garbage
- collection.
- <h4><a name="Refs"></a>Refs (PostScript "objects")</h4>
- <p>
- Ghostscript represents what the PLRM calls PostScript "objects" using a
- structure called a <b><tt>ref</tt></b>, defined in <a
- href="../src/iref.h">src/iref.h</a>; packed refs, used for the elements of
- packed arrays, are defined in <a href="../src/ipacked.h">src/ipacked.h</a>.
- See those files for detailed information.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/ipacked.h">src/ipacked.h</a>,
- <a href="../src/iref.h">src/iref.h</a>.
- </dl>
- <p>
- The PLRM calls for two types of "virtual memory" (VM) space: global and
- local. Ghostscript adds a third space, <em>system</em> VM, whose lifetime
- is an entire session -- i.e., it is effectively "permanent". All three
- spaces are subject to garbage collection. There is a separate allocator
- instance for each VM space (actually, two instances each for global and
- local spaces; see <a href="#save_forgetsave_restore">below</a>). In a
- system with multiple contexts and multiple global or local VMs, each global
- or local VM has its own allocator instance(s).
- <p>
- Refs that represent PostScript composite objects, and therefore include
- pointers to stored data, include a 2-bit VM space tag to indicate in which
- VM the object data are stored. In addition to system, global, and local VM,
- there is a tag for "foreign" VM, which means that the memory is not managed
- by a Ghostscript allocator at all. Every store into a composite object must
- check for <b><tt>invalidaccess</tt></b>: the VM space tag values are chosen
- to help make this check efficient. See <a
- href="../src/ivmspace.h">src/ivmspace.h</a>, <a
- href="../src/iref.h">src/iref.h</a>, and <a
- href="../src/store.h">src/store.h</a> for details.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/ivmspace.h">src/ivmspace.h</a>.
- </dl>
- <p>
- PostScript composite objects (arrays and dictionaries) are usually small.
- Using a separate memory manager object for each composite object would waste
- a lot of space for object headers. Therefore, the interpreter's memory
- manager packs multiple composite objects (also called "ref-containing
- objects") into a single memory manager object, similar to the way the memory
- manager packs multiple objects into a chunk (see <a
- href="#Standard_implementation">above</a>). See <a
- href="../src/gxalloc.h">src/gxalloc.h</a> for details. This memory manager
- object has a structure descriptor, like all other memory manager objects.
- <p>
- Note that the <b><tt>value.pdict</tt></b>, <b><tt>value.refs</tt></b>, or
- <b><tt>value.packed</tt></b> member of a ref must point to a PostScript
- composite object, and therefore can point into the middle of a memory
- manager object. This requires special handling by the garbage collector (<a
- href="#Interpreter_GC">q.v.</a>).
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/ialloc.c">src/ialloc.c</a>,
- <a href="../src/ialloc.h">src/ialloc.h</a>,
- <a href="../src/iastate.h">src/iastate.h</a>,
- <a href="../src/iastruct.h">src/iastruct.h</a>,
- <a href="../src/ilocate.c">src/ilocate.c</a>,
- <a href="../src/imemory.h">src/imemory.h</a>,
- <a href="../src/istruct.h">src/istruct.h</a>.
- </dl>
- <h4><a name="save_forgetsave_restore"></a>save/.forgetsave/restore</h4>
- <p>
- In addition to <b><tt>save</tt></b> and <b><tt>restore</tt></b>, Ghostscript
- provides a <b><tt>.forgetsave</tt></b> operator that makes things as though
- a given <b><tt>save</tt></b> had never happened. (In data base terminology,
- <b><tt>save</tt></b> is "begin transaction", <b><tt>restore</tt></b> is
- "abort transaction", and <b><tt>.forgetsave</tt></b> is "end/commit
- transaction"). <b><tt>.forgetsave</tt></b> was implemented for a specific
- commercial customer (who may no longer even be using it): it was a pain to
- make work, but it's in the code now, and should be maintained. See the
- extensive comments in <a href="../src/isave.c">src/isave.c</a> for more
- information about how these operations work.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/idosave.h">src/idosave.h</a>,
- <a href="../src/isave.c">src/isave.c</a>,
- <a href="../src/isave.h">src/isave.h</a>,
- <a href="../src/isstate.h">src/isstate.h</a>,
- <a href="../src/store.h">src/store.h</a>.
- </dl>
- <h4><a name="Stable_allocators"></a>Stable allocators</h4>
- <p>
- Even though <b><tt>save</tt></b> and <b><tt>restore</tt></b> are concepts
- from the PostScript interpreter, the generic allocator architecture and API
- include a feature to support them, called <em>stable</em> allocators. Every
- allocator has an associated stable allocator, which tags pointers with the
- same VM space number but which is not subject to <b><tt>save</tt></b> and
- <b><tt>restore</tt></b>. System VM is intrinsically stable (its associated
- stable allocator is the same allocator), so there are only 5 allocators in
- ordinary single-context usage: system VM, stable global VM, ordinary global
- VM, stable local VM, ordinary local VM.
- <p>
- The reason that we cannot simply allocate all stable objects in system VM is
- that their refs must still be tagged with the correct VM space number, so
- that the check against storing pointers from global VM to local VM can be
- enforced properly.
- <p>
- All PostScript objects are normally allocated with the non-stable
- allocators. The stable allocators should be used with care, since using
- them can easily create dangling pointers: if storage allocated with a stable
- allocator contains any references to PostScript objects, the client is
- responsible for ensuring that the references don't outlive the referenced
- objects, normally by ensuring that any such referenced objects are allocated
- at the outermost <b><tt>save</tt></b> level. (The original reason for
- wanting stable allocators was the PostScript stacks, which are essentially
- PostScript arrays but are not subject to <b><tt>save</tt></b> and
- <b><tt>restore</tt></b>.) For more examples, search the sources for
- references to <b><tt>gs_memory_stable</tt></b>.
- <h4><a name="Interpreter_GC"></a>Garbage collection</h4>
- <p>
- The interpreter's garbage collector is a compacting, non-conservative,
- mark-and-sweep collector.
- <ul>
- <li>It compacts storage because that is the only way to avoid permanent
- sandbars, which is essential in limited-memory environments.
- <li>It is non-conservative because conservative collectors (which attempt
- to determine whether arbitrary bit patterns are pointers) cannot compact.
- <li>It uses mark-and-sweep, rather than a more modern copying approach,
- because it cannot afford the extra memory required for copying.
- </ul>
- <p>
- Roots for tracing must be registered with the allocator. Most roots are
- registered during initialization.
- <p>
- "Mark-and-sweep" is a bit of a misnomer. The garbage collector actually has
- 5 main phases:
- <ul>
- <li>Sweep to clear marks;
- <li>Trace and mark;
- <li>Sweep to compute relocation;
- <li>Sweep to relocate pointers;
- <li>Sweep and compact.
- </ul>
- <p>
- There is some extra complexity to handle collecting local VM only. In this
- case, all pointers in global VM are treated as roots, and global VM is not
- compacted.
- <p>
- As noted above, PostScript arrays and strings can have refs that point
- within them (because of <b><tt>getinterval</tt></b>). Thus the garbage
- collector must mark each element of an array, and even each byte of a
- string, individually. Specifically, it marks objects, refs, and strings
- using 3 different mechanisms:
- <ul>
- <li>Objects have a mark bit in their header: see
- <a href="../src/gxobj.h">src/gxobj.h</a>,
- <li>Refs and packed refs have a reserved mark bit: see <a
- href="../src/iref.h">src/iref.h</a> and <a
- href="../src/ipacked.h">src/ipacked.h</a>.
- <li>Strings use a separate bit table, with one bit per string byte: see
- <a href="../src/gxalloc.h">src/gxalloc.h</a>,
- </ul>
- <p>
- Similarly, it records the relocation information for objects, refs, and
- strings differently:
- <ul>
- <li>Objects record relocation in the object header.
- <li>Refs record relocation in unused fields of refs such as nulls that
- don't use their <b><tt>value</tt></b> field. Every memory manager object
- that stores ref-containing objects as described above has an extra, unused
- ref at the end for this purpose.
- <li>Strings use a separate relocation table.
- </ul>
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/igc.c">src/igc.c</a>,
- <a href="../src/igc.h">src/igc.h</a>,
- <a href="../src/igcref.c">src/igcref.c</a>,
- <a href="../src/igcstr.c">src/igcstr.c</a>,
- <a href="../src/igcstr.h">src/igcstr.h</a>,
- <a href="../src/ireclaim.c">src/ireclaim.c</a>.
- </dl>
- <hr>
- <h2><a name="Portability"></a>Portability</h2>
- <p>
- One of Ghostscript's most important features is its great portability across
- platforms (CPUs, operating systems, compilers, and build tools). The code
- supports portability through two mechanisms:
- <ul>
- <li><a href="#Structural">Structural mechanisms</a> -- segregating
- platform-dependent information into files in a particular way.
- <li><a href="#Coding">Coding standards</a> -- avoiding relying on byte
- order, scalar size, and platform-specific compiler or library features.
- </ul>
- <h3><a name="Structural"></a>Structural</h3>
- <h4><a name="CPU_and_compiler"></a>CPU and compiler</h4>
- <p>
- Ghostscript attempts to discover characteristics of the CPU and compiler
- automatically during the build process, by compiling and then executing a
- program called <b><tt>genarch</tt></b>. <b><tt>genarch</tt></b> generates a
- file <b><tt>obj/arch.h</tt></b>, which almost all Ghostscript files then
- include. This works well for things like word size, byte order, and
- floating point representation, but it can't determine whether or not a
- compiler supports a particular feature, because if a feature is absent, the
- compilation may fail.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/genarch.c">src/genarch.c</a>,
- <a href="../obj/arch.h">obj/arch.h</a>.
- </dl>
- <h4><a name="Library_headers"></a>Library headers</h4>
- <p>
- Despite the supposed standardization of ANSI C, platforms vary considerably
- in where (and whether) they provide various standard library facilities.
- Currently, Ghostscript's build process doesn't attempt to sort this out
- automatically. Instead, for each library header file
- <b><tt><</tt></b><em>xxx</em><b><tt>.h></tt></b> there is a
- corresponding Ghostscript source file
- <b><tt>src/</tt></b><em>xxx</em><b><tt>_.h</tt></b>, containing a set of
- compile-time conditionals that attempt to select the correct platform header
- file, or in some cases substitute Ghostscript's own code for a missing
- facility. You may need to edit these files when moving to platforms with
- unusually non-standard libraries.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/ctype_.h">src/ctype_.h</a>,
- <a href="../src/dirent_.h">src/dirent_.h</a>,
- <a href="../src/dos_.h">src/dos_.h</a>,
- <a href="../src/errno_.h">src/errno_.h</a>,
- <a href="../src/fcntl_.h">src/fcntl_.h</a>,
- <a href="../src/jerror_.h">src/jerror_.h</a>,
- <a href="../src/malloc_.h">src/malloc_.h</a>,
- <a href="../src/math_.h">src/math_.h</a>,
- <a href="../src/memory_.h">src/memory_.h</a>,
- <a href="../src/pipe_.h">src/pipe_.h</a>,
- <a href="../src/png_.h">src/png_.h</a>,
- <a href="../src/stat_.h">src/stat_.h</a>,
- <a href="../src/stdio_.h">src/stdio_.h</a>,
- <a href="../src/string_.h">src/string_.h</a>,
- <a href="../src/time_.h">src/time_.h</a>,
- <a href="../src/unistd_.h">src/unistd_.h</a>,
- <a href="../src/vmsmath.h">src/vmsmath.h</a>,
- <a href="../src/windows_.h">src/windows_.h</a>,
- <a href="../src/x_.h">src/x_.h</a>.
- </dl>
- <p>
- It has been suggested that the GNU <b><tt>configure</tt></b> scripts do the
- above better, for Unix systems, than Ghostscript's current methods. While
- this may be true, we have found <b><tt>configure</tt></b> scripts difficult
- to write, understand, and maintain; and the <b><tt>autoconf</tt></b> tool
- for generating <b><tt>configure</tt></b> scripts, which we found easy to
- use, doesn't cover much of the ground that Ghostscript requires.
- <h4><a name="Cross_platform_APIs"></a>Cross-platform APIs</h4>
- <p>
- For a few library facilities that are available on all platforms but are not
- well standardized, or that may need to be changed for special environments,
- Ghostscript defines its own APIs. It is an architectural property of
- Ghostscript that the implementations of these APIs are the only .c files for
- which the choice of platform (as opposed to choices of drivers or optional
- features) determines whether they are compiled and linked into an
- executable.
- <dl>
- <dt>
- API:
- <dd>
- <a href="../src/gp.h">src/gp.h</a>,
- <a href="../src/gpcheck.h">src/gpcheck.h</a>,
- <a href="../src/gpgetenv.h">src/gpgetenv.h</a>,
- <a href="../src/gpmisc.h">src/gpmisc.h</a>,
- <a href="../src/gpsync.h">src/gpsync.h</a>.
- <dt>
- Implementation files shared among multiple platforms:
- <dd>
- <a href="../src/gp_getnv.c">src/gp_getnv.c</a>,
- <a href="../src/gp_mktmp.c">src/gp_mktmp.c</a>,
- <a href="../src/gp_nsync.c">src/gp_nsync.c</a>,
- <a href="../src/gp_psync.c">src/gp_psync.c</a>,
- <a href="../src/gp_strdl.c">src/gp_strdl.c</a>,
- <a href="../src/gpmisc.c">src/gpmisc.c</a>.
- <dt>
- Platform-specific implementation files:
- <dd>
- <a href="../src/gp_dosfe.c">src/gp_dosfe.c</a>,
- <a href="../src/gp_dosfs.c">src/gp_dosfs.c</a>,
- <a href="../src/gp_dvx.c">src/gp_dvx.c</a>,
- <a href="../src/gp_iwatc.c">src/gp_iwatc.c</a>,
- <a href="../src/gp_msdos.c">src/gp_msdos.c</a>,
- <a href="../src/gp_mshdl.c">src/gp_mshdl.c</a>,
- <a href="../src/gp_msio.c">src/gp_msio.c</a>,
- <a href="../src/gp_mslib.c">src/gp_mslib.c</a>,
- <a href="../src/gp_mswin.c">src/gp_mswin.c</a>,
- <a href="../src/gp_mswin.h">src/gp_mswin.h</a>,
- <a href="../src/gp_ntfs.c">src/gp_ntfs.c</a>,
- <a href="../src/gp_os2.c">src/gp_os2.c</a>,
- <a href="../src/gp_os9.c">src/gp_os9.c</a>,
- <a href="../src/gp_stdia.c">src/gp_stdia.c</a>,
- <a href="../src/gp_stdin.c">src/gp_stdin.c</a>,
- <a href="../src/gp_sysv.c">src/gp_sysv.c</a>,
- <a href="../src/gp_unifn.c">src/gp_unifn.c</a>,
- <a href="../src/gp_unifs.c">src/gp_unifs.c</a>,
- <a href="../src/gp_unix.c">src/gp_unix.c</a>,
- <a href="../src/gp_vms.c">src/gp_vms.c</a>,
- <a href="../src/gp_wgetv.c">src/gp_wgetv.c</a>,
- <a href="../src/gp_win32.c">src/gp_win32.c</a>,
- <a href="../src/gp_wsync.c">src/gp_wsync.c</a>.
- </dl>
- <h4><a name="Makefiles"></a>Makefiles</h4>
- <p>
- For information on the structure and conventions used within makefiles, see
- the <a href="#Makefile_structure">Makefile structure</a> section above.
- <p>
- Ghostscript's makefiles are structured very similarly to the cross-platform
- library files. The great majority of the makefiles are portable across all
- platforms and all versions of <b><tt>make</tt></b>. To achieve this, the
- platform-independent makefiles must obey two constraints beyond those of the
- POSIX <b><tt>make</tt></b> program:
- <ul>
- <li>No conditionals or <b><tt>include</tt></b>s are allowed. While most
- <b><tt>make</tt></b> programs now provide some form of conditional execution
- and some form of inclusion, there is no agreement on the syntax.
- (Conditionals and includes are allowed in platform-dependent makefiles; in
- fact, an inclusion facility is required.)
- <li>There must be a space on both sides of the : that separates the target
- of a rule from its dependencies. This is required for compatibility with
- the OpenVMS <b><tt>MMS</tt></b> and <b><tt>MMK</tt></b> programs.
- </ul>
- <p>
- The top-level makefile for each platform (where "platform" includes the OS,
- the compiler, and the flavor of <b><tt>make</tt></b>) contains all the build
- options, plus <b><tt>include</tt></b>s for the generic makefiles and any
- platform-dependent makefiles that are shared among multiple platforms.
- <p>
- While most of the top-level makefiles build a PostScript and/or PDF
- interpreter configuration, there are also a few makefiles that build a test
- program that only uses the graphics library without any language
- interpreter. Among other things, this can be helpful in verifying that no
- accidental dependencies on the interpreter have crept into the library or
- drivers.
- <p>
- For families of similar platforms, the question arises whether to use
- multiple top-level makefiles, or whether to use a single top-level makefile
- that may require minor editing for some (or all) platforms. Ghostscript
- currently uses the following top-level makefiles for building interpreter
- configurations:
- <ul>
- <li>Unix (including Linux):
- <ul>
- <li><a href="../src/unix-gcc.mak">src/unix-gcc.mak</a>,
- for Unix with gcc.
- <li><a href="../src/unixansi.mak">src/unixansi.mak</a>,
- for Unix with an ANSI C compiler other than gcc.
- <li><a href="../src/unixtrad.mak">src/unixtrad.mak</a>,
- for Unix with a "traditional" or "K&R" compiler.
- </ul>
- <li>PC:
- <ul>
- <li><a href="../src/bcwin32.mak">src/bcwin32.mak</a>,
- for MS Windows with Borland C++ Builder.
- <li><a href="../src/msvc32.mak">src/msvc32.mak</a>,
- for MS Windows with Microsoft Visual C (MSVC).
- <li><a href="../src/os2.mak">src/os2.mak</a>,
- for MS-DOS or OS/2 GCC/EMX environment.
- <li><a href="../src/watc.mak">src/watc.mak</a>,
- for extended MS-DOS with Watcom C.
- <li><a href="../src/watcw32.mak">src/watcw32.mak</a>,
- for MS Windows with Watcom C.
- </ul>
- <li>Macintosh:
- <ul>
- <li><a href="../src/macos-mcp.mak">src/macos-mcp.mak</a>,
- for Macintosh MCP.
- </ul>
- <li>Other:
- <ul>
- <li><a href="../src/all-arch.mak">src/all-arch.mak</a>,
- for building on many Unix systems in a networked test environment.
- <li><a href="../src/dvx-gcc.mak">src/dvx-gcc.mak</a>,
- for DesqView/X with gcc.
- <li><a href="../src/openvms.mak">src/openvms.mak</a>,
- for OpenVMS with Digital's CC compiler and the MMS build program.
- <li><a href="../src/openvms.mmk">src/openvms.mmk</a>,
- for OpenVMS with Digital's CC compiler and the MMK build program.
- </ul>
- </ul>
- <p>
- The following top-level makefiles build the library test program:
- <ul>
- <li><a href="../src/ugcclib.mak">src/ugcclib.mak</a>,
- on Unix with gcc.
- <li><a href="../src/msvclib.mak">src/msvclib.mak</a>,
- on MS Windows with MSVC.
- <li><a href="../src/watclib.mak">src/watclib.mak</a>,
- on extended MS-DOS with Watcom C.
- </ul>
- <p>
- The MSVC makefiles may require editing to select between different versions
- of MSVC, since different versions may have slightly incompatible command
- line switches or customary installation path names. The Unix makefiles
- often require editing to deal with differing library path names and/or
- library names. For details, see <a href="Make.htm#Unix_build">the Unix
- section</a> of the documentation for building Ghostscript.
- <dl>
- <dt>
- Library test program:
- <dd>
- <a href="../src/gslib.c">src/gslib.c</a>.
- <dt>
- Platform-independent makefiles:
- <dd>
- <dl>
- <dt>
- Graphics library and support:
- <dd>
- <a href="../src/contrib.mak">src/contrib.mak</a>,
- <a href="../src/devs.mak">src/devs.mak</a>,
- <a href="../src/gs.mak">src/gs.mak</a>,
- <a href="../src/lib.mak">src/lib.mak</a>,
- <a href="../src/version.mak">src/version.mak</a>.
- <dt>
- PostScript interpreter and fonts:
- <dd>
- <a href="../src/cfonts.mak">src/cfonts.mak</a>,
- <a href="../src/int.mak">src/int.mak</a>,
- <a href="../src/wmin.mak">src/wmin.mak</a>.
- <dt>
- Third-party libraries:
- <dd>
- <a href="../src/icclib.mak">src/icclib.mak</a>,
- <a href="../src/ijs.mak">src/ijs.mak</a>,
- <a href="../src/jpeg.mak">src/jpeg.mak</a>,
- <a href="../src/libpng.mak">src/libpng.mak</a>,
- <a href="../src/zlib.mak">src/zlib.mak</a>.
- </dl>
- <dt>
- Shared platform-dependent makefiles:
- <dd>
- <dl>
- <dt>
- Unix:
- <dd>
- <a href="../src/unix-aux.mak">src/unix-aux.mak</a>,
- <a href="../src/unix-dll.mak">src/unix-dll.mak</a>,
- <a href="../src/unix-end.mak">src/unix-end.mak</a>,
- <a href="../src/unixhead.mak">src/unixhead.mak</a>,
- <a href="../src/unixinst.mak">src/unixinst.mak</a>,
- <a href="../src/unixlink.mak">src/unixlink.mak</a>.
- <dt>
- Microsoft Windows and MS-DOS:
- <dd>
- <a href="../src/msvccmd.mak">src/msvccmd.mak</a>,
- <a href="../src/msvctail.mak">src/msvctail.mak</a>,
- <a href="../src/pcwin.mak">src/pcwin.mak</a>,
- <a href="../src/wccommon.mak">src/wccommon.mak</a>,
- <a href="../src/wctail.mak">src/wctail.mak</a>,
- <a href="../src/winint.mak">src/winint.mak</a>,
- <a href="../src/winlib.mak">src/winlib.mak</a>,
- <a href="../src/winplat.mak">src/winplat.mak</a>.
- <dt>
- Other:
- <dd>
- <a href="../src/dvx-head.mak">src/dvx-head.mak</a>,
- <a href="../src/dvx-tail.mak">src/dvx-tail.mak</a>.
- </dl>
- </dl>
- <h3><a name="Coding"></a>Coding</h3>
- <p>
- Coding for portability requires avoiding both <em>explicit</em>
- dependencies, such as platform-dependent <b><tt>#ifdef</tt></b>s, and
- <em>implicit</em> dependencies, such as dependencies on byte order or the
- size of the integral types.
- <h4><a name="Explicit_dependencies"></a>Explicit dependencies</h4>
- <p>
- The platform-independent .c files never, ever, use <b><tt>#ifdef</tt></b> or
- <b><tt>#if</tt></b> to select code for specific platforms. Instead, we
- always try to characterize some abstract property that is being tested. For
- example, rather than checking for macros that are defined on those specific
- platforms that have 64-bit <b><tt>long</tt></b> values, we define a macro
- <b><tt>ARCH_SIZEOF_LONG</tt></b> that can then be tested. Such macros are
- always defined in a .h file, either automatically in <b><tt>arch.h</tt></b>,
- or explicitly in a <em>xxx</em><b><tt>_.h</tt></b> file, as described in
- earlier sections.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="../src/std.h">src/std.h</a>,
- <a href="../src/stdpre.h">src/stdpre.h</a>.
- </dl>
- <h4><a name="Implicit_dependencies"></a>Implicit dependencies</h4>
- <p>
- The most common source of byte ordering dependencies is casting between
- types (T1 *) and (T2 *) where T1 and T2 are numeric types that aren't merely
- signed/unsigned variants of each other. To avoid this, the only casts
- allowed in the code are between numeric types, from a pointer type to a long
- integral type, and between pointer types.
- <p>
- Ghostscript's code assumes the following about the sizes of various types:
- <dl>
- <dt>char<dd>8 bits
- <dt>short<dd>16 bits
- <dt>int<dd>32 or 64 bits
- <dt>long<dd>32 or 64 bits
- <dt>float<dd>32 bits (may work with 64 bits)
- <dt>double<dd>64 bits (may work with 128 bits)
- </dl>
- <p>
- The code does not assume that the <b><tt>char</tt></b> type is signed (or
- unsigned); except for places where the value is always a literal string, or
- for interfacing to library procedures, the code uses <b><tt>byte</tt></b> (a
- Ghostscript synonym for <b><tt>unsigned char</tt></b>) almost everywhere.
- <p>
- Pointers are signed on some platforms and unsigned on others. In the few
- places in the memory manager where it's necessary to reliably order-compare
- (as opposed to equality-compare) pointers that aren't known to point to the
- same allocated block of memory, the code uses the
- <b><tt>PTR_</tt></b><em>relation</em> macros rather than direct comparisons.
- <p>
- See the files listed above for other situations where a macro provides
- platform-independence or a workaround for bugs in specific compilers or
- libraries (of which there are a distressing number).
- <h4><a name="Platform_specific_code"></a>Platform-specific code</h4>
- <p>
- There are some features that are inherently platform-specific:
- <ul>
- <li>Microsoft Windows requires a lot of special top-level code, and also has
- an installer and uninstaller.
- <li>OS/2 requires a little special code.
- <li>MacOS also requires special top-level code (now distributed with the
- standard Ghostscript package).
- <li>All platforms supporting DLLs (currently all three of the above) share
- some special top-level code.
- </ul>
- <dl>
- <dt>
- MS Windows files:
- <dd>
- <a href="../src/dpmain.c">src/dpmain.c</a>,
- <a href="../src/dwdll.c">src/dwdll.c</a>,
- <a href="../src/dwdll.h">src/dwdll.h</a>,
- <a href="../src/dwimg.c">src/dwimg.c</a>,
- <a href="../src/dwimg.h">src/dwimg.h</a>,
- <a href="../src/dwinst.cpp">src/dwinst.cpp</a>,
- <a href="../src/dwinst.h">src/dwinst.h</a>,
- <a href="../src/dwmain.c">src/dwmain.c</a>,
- <a href="../src/dwmain.h">src/dwmain.h</a>,
- <a href="../src/dwmainc.c">src/dwmainc.c</a>,
- <a href="../src/dwnodll.c">src/dwnodll.c</a>,
- <a href="../src/dwreg.c">src/dwreg.c</a>,
- <a href="../src/dwreg.h">src/dwreg.h</a>,
- <a href="../src/dwsetup.cpp">src/dwsetup.cpp</a>,
- <a href="../src/dwsetup.h">src/dwsetup.h</a>,
- <a href="../src/dwtext.c">src/dwtext.c</a>,
- <a href="../src/dwtext.h">src/dwtext.h</a>,
- <a href="../src/dwuninst.cpp">src/dwuninst.cpp</a>,
- <a href="../src/dwuninst.h">src/dwuninst.h</a>,
- <a href="../src/gp_msdll.c">src/gp_msdll.c</a>,
- <a href="../src/gp_mspol.c">src/gp_mspol.c</a>,
- <a href="../src/gp_msprn.c">src/gp_msprn.c</a>,
- <a href="../src/gs16spl.c">src/gs16spl.c</a>,
- <a href="../src/gsdllwin.h">src/gsdllwin.h</a>.
- <dt>
- OS/2 files:
- <dd>
- <a href="../src/gsdllos2.h">src/gsdllos2.h</a>.
- <dt>
- Unix files:
- <dd>
- <a href="../src/dxmain.c">src/dxmain.c</a>.
- <a href="../src/dxmainc.c">src/dxmainc.c</a>.
- <dt>
- Macintosh files:
- <dd>
- <a href="../src/gdevmac.c">src/gdevmac.c</a>.
- <a href="../src/gdevmac.h">src/gdevmac.h</a>.
- <a href="../src/gdevmacpictop.h">src/gdevmacpictop.h</a>.
- <a href="../src/gdevmacttf.h">src/gdevmacttf.h</a>.
- <a href="../src/gdevmacxf.c">src/gdevmacxf.c</a>.
- <a href="../src/gp_mac.c">src/gp_mac.c</a>.
- <a href="../src/gp_mac.h">src/gp_mac.h</a>.
- <a href="../src/gp_macio.c">src/gp_macio.c</a>.
- <a href="../src/macgenmcpxml.sh">src/macgenmcpxml.sh</a>.
- <a href="../src/macsysstat.h">src/macsysstat.h</a>.
- <a href="../src/macsystypes.h">src/macsystypes.h</a>.
- <dt>
- VMS files:
- <dd>
- <a href="../src/vms_x_fix.h">src/vms_x_fix.h</a>.
- <dt>
- DLL files:
- <dd>
- <a href="../src/gsdll.c">src/gsdll.c</a>,
- <a href="../src/gsdll.h">src/gsdll.h</a>,
- <a href="../src/gdevdsp.c">src/gdevdsp.c</a>,
- <a href="../src/gdevdsp.h">src/gdevdsp.h</a>,
- <a href="../src/gdevdsp2.h">src/gdevdsp2.h</a>,
- <a href="../src/iapi.c">src/iapi.c</a>,
- <a href="../src/iapi.h">src/iapi.h</a>,
- <a href="../src/idisp.c">src/idisp.c</a>,
- <a href="../src/idisp.h">src/idisp.h</a>.
- <p>
- The new DLL interface (new as of 7.0) is especially useful with the
- new display device, so it is included here. Both are due to Russell
- Lang.
- </dl>
- <hr>
- <h2><a name="Adding_features_and_options"></a>Adding features and options</h2>
- <p>
- [Ray, please supply more information about what you want here]
- <h2><a name="Troubleshooting"></a>Troubleshooting</h2>
- <p>
- The Ghostscript code has many tracing and debugging features that can be
- enabled at run time using the <b><tt>-Z</tt></b> command line switch, if the
- executable was compiled with <b><tt>DEBUG</tt></b> defined. One
- particularly useful combination is <b><tt>-Z@\?</tt></b>, which fills free
- memory blocks with a pattern and also turns on run-time memory consistency
- checking. For more information, see <a
- href="Use.htm#Debugging">doc/Use.htm#Debugging</a>; you can also search for
- occurrences of <b><tt>if_debug</tt></b> or <b><tt>gs_debug_c</tt></b> in the
- source code. Note that many of these features are in the graphics library
- and do not require a PostScript interpreter.
- <p>
- The code also contains many run-time procedures whose only purpose is to be
- called from the debugger to print out various data structures, including all
- the procedures in <a href="../src/idebug.c">src/idebug.c</a> (for the
- PostScript interpreter) and the <b><tt>debug_dump_</tt></b> procedures in <a
- href="../src/gsmisc.c">src/gsmisc.c</a>.
- <dl>
- <dt>
- Files:
- <dd>
- <a href="Use.htm#Debugging">doc/Use.htm#Debugging</a>,
- <a href="../src/gdebug.h">src/gdebug.h</a>,
- <a href="../src/gsmdebug.h">src/gsmdebug.h</a>,
- <a href="../src/idebug.h">src/idebug.h</a>,
- <a href="../src/idebug.c">src/idebug.c</a>.
- </dl>
- <!-- [2.0 end contents] ==================================================== -->
- <!-- [3.0 begin visible trailer] =========================================== -->
- <hr>
- <p>
- <small>Copyright © 2001 artofcode LLC.
- All rights reserved.</small>
- <p>
- <small>This file is part of AFPL Ghostscript. See the <a
- href="Public.htm">Aladdin Free Public License</a> (the "License") for full
- details of the terms of using, copying, modifying, and redistributing
- AFPL Ghostscript.</small>
- <p>
- <small>Ghostscript version 7.04, 31 January 2002
- <!-- [3.0 end visible trailer] ============================================= -->
- </body>
- </html>
|