123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881 |
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <head>
- <title>Ghostscript and the PostScript language</title>
- <!-- $Id: Language.htm,v 1.34.2.4 2002/02/01 05:31:25 raph Exp $ -->
- <!-- Originally: language.txt -->
- <link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
- </head>
- <body>
- <!-- [1.0 begin visible header] ============================================ -->
- <!-- [1.1 begin headline] ================================================== -->
- <h1>Ghostscript and the PostScript language</h1>
- <!-- [1.1 end headline] ==================================================== -->
- <!-- [1.2 begin table of contents] ========================================= -->
- <h2>Table of contents</h2>
- <blockquote><ul>
- <li><a href="#Capabilities">Ghostscript's capabilities in relation to PostScript</a>
- <li><a href="#Implementation_limits">Implementation limits</a>
- <ul>
- <li><a href="#Architectural_limits">Architectural limits</a>
- <li><a href="#Typical_memory_limits">Typical memory limits in LanguageLevel 1</a>
- <li><a href="#VM_consumption">Other differences in VM consumption</a>
- </ul>
- <li><a href="#Additional_operators">Additional operators in Ghostscript</a>
- <ul>
- <li><a href="#Graphics_and_text">Graphics and text operators</a>
- <ul>
- <li><a href="#Transparency">Transparency</a>
- <ul>
- <li><a href="#Transparency_graphics_state_operators">Graphics state operators</a>
- <li><a href="#Transparency_rendering_stack_operators">Rendering stack operators</a>
- <li><a href="#Transparency_ImageType">New ImageType</a>
- </ul>
- <li><a href="#Graphics_state">Other graphics state operators</a>
- <li><a href="#Path">Path operators</a>
- <li><a href="#Painting">Painting operators</a>
- <li><a href="#Character">Character operators</a>
- </ul>
- <li><a href="#Other">Other operators</a>
- <ul>
- <li><a href="#Mathematical">Mathematical operators</a>
- <li><a href="#Dictionary">Dictionary operators</a>
- <li><a href="#String">String and name operators</a>
- <li><a href="#Relational">Relational operators</a>
- <li><a href="#File">File operators</a>
- <li><a href="#Virtual_memory">Virtual memory operators</a>
- <li><a href="#Miscellaneous">Miscellaneous operators</a>
- <li><a href="#Device">Device operators</a>
- </ul>
- </ul>
- <li><a href="#Filters">Filters</a>
- <ul>
- <li><a href="#Standard_filters">Standard filters</a>
- <li><a href="#Non_standard_filters">Non-standard filters</a>
- <li><a href="#Unstable_filters">Unstable filters</a>
- </ul>
- <li><a href="#Device_parameters">Device parameters</a>
- <li><a href="#User_parameters">User parameters</a>
- <li><a href="#Miscellaneous_additions">Miscellaneous additions</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>.
- <!-- [1.3 end hint] ======================================================== -->
- <hr>
- <!-- [1.0 end visible header] ============================================== -->
- <!-- [2.0 begin contents] ================================================== -->
- <h2><a name="Capabilities"></a>Ghostscript's capabilities in relation to PostScript</h2>
- <p>
- The Ghostscript interpreter, except as noted below, is intended to execute
- properly any source program written in the (LanguageLevel 3)
- <b>PostScript</b> language as defined in the <cite>PostScript
- Language Reference, Third Edition</cite> (ISBN 0-201-37922-8) published by
- Addison-Wesley in mid-1999. However, the interpreter is configurable in
- ways that can restrict it to various subsets of this language.
- Specifically, the base interpreter accepts the Level 1 subset of the
- PostScript language, as defined in the first edition of the <cite>PostScript
- Language Reference Manual</cite> (ISBN 0-201-10174-2) Addison-Wesley 1985,
- plus the file system, version 25.0 language, and miscellaneous additions
- listed in sections A.1.6, A.1.7, and A.1.8 of the Second Edition
- respectively, including allowing a string operand for the
- "<b><tt>status</tt></b>" operator. The base interpreter may be configured
- (see the <a href="Make.htm">documentation on building Ghostscript</a> for
- how to configure it) by adding any combination of the following:
- <ul>
- <li>The ability to process PostScript Type 1 fonts. This facility is
- normally included in the interpreter.
- <li>The CMYK color extensions listed in section A.1.4 of the Second Edition
- (including <b><tt>colorimage</tt></b>). These facilities are available
- only if the <b><tt>color</tt></b>, <b><tt>dps</tt></b>, or
- <b><tt>level2</tt></b> feature was selected when Ghostscript was built.
- <li>The Display PostScript extensions listed in section A.1.3 of the Second
- Edition, but excluding the operators listed in section A.1.2. These
- facilities are available only if the <b><tt>dps</tt></b> feature or the
- <b><tt>level2</tt></b> feature was selected when Ghostscript was built.
- <li>The composite font extensions listed in section A.1.5 of the Second
- Edition, and the ability to handle Type 0 fonts. These facilities are
- available only if the <b><tt>compfont</tt></b> feature or the
- <b><tt>level2</tt></b> feature was selected when Ghostscript was built.
- <li>The ability to load TrueType fonts and to handle PostScript Type 42
- (encapsulated TrueType) fonts. These facilities are available only if the
- <b><tt>ttfont</tt></b> feature was selected when Ghostscript was built.
- <li>The PostScript Level 2 "filter" facilities except the
- <b><tt>DCTEncode</tt></b> and <b><tt>DCTDecode</tt></b> filters. These
- facilities are available only if the <b><tt>filter</tt></b>,
- <b><tt>dps</tt></b>, or <b><tt>level2</tt></b> feature was selected when
- Ghostscript was built.
- <li>The PostScript Level 2 <b><tt>DCTEncode</tt></b> and
- <b><tt>DCTDecode</tt></b> filters. These facilities are available only if
- the <b><tt>dct</tt></b> or <b><tt>level2</tt></b> feature was selected when
- Ghostscript was built.
- <li>All the other PostScript Level 2 operators and facilities listed in
- section A.1.1 of the Second Edition and not listed in any of the other
- A.1.n sections. These facilities are available only if the
- <b><tt>level2</tt></b> feature was selected when Ghostscript was built.
- <li>All PostScript LanguageLevel 3 operators and facilities listed in the
- Third Edition, except as noted below. These facilities are available only
- if the <b><tt>psl3</tt></b> feature was selected when Ghostscript was built.
- <li>The ability to recognize DOS EPSF files and process only the PostScript
- part, ignoring bitmap previews or other information. This facility is
- available only if the <b><tt>epsf</tt></b> feature was selected when
- Ghostscript was built.
- </ul>
- <p>
- Ghostscript currently does not implement the following PostScript
- LanguageLevel 3 facilities:
- <ul>
- <li>Native <b><tt>Separation</tt></b> and <b><tt>DeviceN</tt></b> color
- spaces -- the alternate space is always used.
- <li>Settable <b><tt>ProcessColorModel</tt></b> for page devices, except for
- a very few special devices.
- <li><b><tt>IODevice</tt></b>s other than <b><tt>%stdin</tt></b>,
- <b><tt>%stdout</tt></b>, <b><tt>%stderr</tt></b>, <b><tt>%lineedit</tt></b>,
- <b><tt>%statementedit</tt></b>, <b><tt>%os%</tt></b>, and (if configured)
- <b><tt>%pipe%</tt></b>.
- </ul>
- <p>
- Ghostscript can also interpret files in the Portable Document Format (PDF)
- 1.3 format defined in the <a
- href="http://partners.adobe.com/asn/developer/PDFS/TN/PLRM.pdf"><em>Portable
- Document Format Reference Manual</em> Version 1.3</a> of March 11, 1999,
- distributed by <a href="http://www.adobe.com/">Adobe Systems
- Incorporated</a>, except as noted below. This facility is available only if
- the <b><tt>pdf</tt></b> feature was selected when Ghostscript was built.
- <p>
- Ghostscript currently does not implement the following PDF 1.3 facilities:
- <ul>
- <li>Native <b><tt>Separation</tt></b> and <b><tt>DeviceN</tt></b> color
- spaces, as noted above for PostScript.
- <li>Native <b><tt>ICCBased</tt></b> color spaces -- these too always use the
- alternate space.
- </ul>
- <p>
- Ghostscript also includes a number of
- <a href="#Additional_operators">additional operators</a> defined below that
- are not in the PostScript language defined by Adobe.
- <hr>
- <h2><a name="Implementation_limits"></a>Implementation limits</h2>
- <p>
- The implementation limits show here correspond to those in Tables B.1 and
- B.2 of the Second and Third Editions, which describe the quantities fully.
- Where Ghostscript's limits are different from those of Adobe's
- implementations (as shown in the Third Edition), Adobe's limits are also
- shown.
- <h3><a name="Architectural_limits"></a>Architectural limits</h3>
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr><th colspan=7 bgcolor="#CCCC00"><hr><font size="+1">Architectural limits (corresponds to Adobe table B.1)</font><hr>
- <tr valign=bottom>
- <th align=left>Quantity
- <td>
- <th align=left>Limit
- <td>
- <th align=left>Type
- <td>
- <th align=left>Adobe
- <tr> <td colspan=7><hr>
- <tr valign=top> <td>integer
- <td>
- <td>32-bit
- <td>
- <td>twos complement integer
- <td>
- <td>
- <tr valign=top> <td>real
- <td>
- <td>single-precision
- <td>
- <td>IEEE float
- <td>
- <td>
- <tr valign=top> <td>array
- <td>
- <td>65535
- <td>
- <td>elements
- <td>
- <td>
- <tr valign=top> <td>dictionary
- <td>
- <td>65534
- <td>
- <td>elements
- <td>
- <td>65535
- <tr valign=top> <td>string
- <td>
- <td>65535
- <td>
- <td>characters
- <td>
- <td>
- <tr valign=top> <td>name
- <td>
- <td>16383
- <td>
- <td>characters
- <td>
- <td>127
- <tr valign=top> <td>filename
- <td>
- <td>128*
- <td>
- <td>characters
- <td>
- <td>
- <tr valign=top> <td><b><tt>save</tt></b> level
- <td>
- <td>none
- <td>
- <td>(capacity of memory)
- <td>
- <td>15
- <tr valign=top> <td><b><tt>gsave</tt></b> level
- <td>
- <td>none
- <td>
- <td>(capacity of memory)
- <td>
- <td>13
- </table></blockquote>
- <p>
- * The limit on the length of a file name is 128 characters if the name
- starts with a %...% IODevice designation, or 124 characters if it does not.
- <h3><a name="Typical_memory_limits"></a>Typical memory limits in LanguageLevel 1</h3>
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr><th colspan=7 bgcolor="#CCCC00"><hr><font size="+1">Memory limits (corresponds to Adobe table B.2)</font><hr>
- <tr valign=bottom>
- <th align=left>Quantity
- <td>
- <th align=left>Limit
- <td>
- <th align=left>Type
- <td>
- <th align=left>Adobe
- <tr> <td colspan=7><hr>
- <tr valign=top> <td><b><tt>userdict</tt></b>
- <td>
- <td>200
- <td>
- <td>
- <td>
- <td>
- <tr valign=top> <td><b><tt>FontDirectory</tt></b>
- <td>
- <td>100
- <td>
- <td>
- <td>
- <td>
- <tr valign=top> <td>operand stack
- <td>
- <td>800
- <td>
- <td>
- <td>
- <td>500
- <tr valign=top> <td>dictionary stack
- <td>
- <td>20
- <td>
- <td>
- <tr valign=top> <td>execution stack
- <td>
- <td>250
- <td>
- <td>
- <tr valign=top> <td>interpreter level
- <td>
- <td>none
- <td>
- <td>(capacity of memory)
- <td>
- <td>10
- <tr valign=top> <td>path
- <td>
- <td>none
- <td>
- <td>(capacity of memory)
- <td>
- <td>1500
- <tr valign=top> <td>dash
- <td>
- <td>11
- <td>
- <td>
- <tr valign=top> <td>VM
- <td>
- <td>none
- <td>
- <td>(capacity of memory)
- <td>
- <td>240000
- <tr valign=top> <td>file
- <td>
- <td>none
- <td>
- <td>(determined by operating system)
- <td>
- <td>6
- <tr valign=top> <td>image
- <td>
- <td>65535
- <td>
- <td>values (samples × components)<br>for1-, 2-, 4-, or 8-bit samples
- <td>
- <td>3300
- <tr valign=top> <td>
- <td>
- <td>32767
- <td>
- <td>values for 12-bit samples
- <td>
- <td>3300
- </table></blockquote>
- <h3><a name="VM_consumption"></a>Other differences in VM consumption</h3>
- <p>
- Packed array elements occupy either 2 bytes or 8 bytes. The average
- element size is probably about 5 bytes. Names occupy 12 bytes plus the
- space for the string.
- <hr>
- <h2><a name="Additional_operators"></a>Additional operators in Ghostscript</h2>
- <h3><a name="Graphics_and_text"></a>Graphics and text operators</h3>
- <h4><a name="Transparency"></a>Transparency</h4>
- <p>
- Ghostscript provides a set of operators for implementing the transparency
- and compositing facilities of PDF 1.4. These are defined only if the
- <b><tt>transpar</tt></b> option was selected when Ghostscript was built. We
- do not attempt to explain the underlying graphics model here: for details,
- see <a
- href="http://partners.adobe.com/asn/developer/technotes.html#acrobat-pdf"
- class="offsite">Adobe
- Technical Note</a> #5407, "<a
- href="http://partners.adobe.com/asn/developer/acrosdk/DOCS/PDF_Transparency.pdf"
- class="offsite">Transparency
- in PDF</a>". Note, however, that
- Ghostscript's model generalizes that of PDF 1.4 in that Ghostscript
- maintains separate alpha and mask values for opacity and shape, rather than
- a single value with a Boolean that says whether it represents opacity or
- shape. EVERYTHING IN THIS SECTION IS SUBJECT TO CHANGE.
- <h5><a name="Transparency_graphics_state_operators"></a>Graphics state
- operators</h5>
- <dl>
- <dt><b><tt><modename> .setblendmode -</tt></b>
- <dd>Sets the blending mode in the graphics state. If the mode name is not
- recognized, causes a <b><tt>rangecheck</tt></b> error. The initial value of
- the blending mode is <b><tt>/Compatible</tt></b>.
- </dl>
- <dl>
- <dt><b><tt>- .currentblendmode <modename></tt></b>
- <dd>Returns the current blending mode.
- </dl>
- <dl>
- <dt><b><tt><0..1> .setopacityalpha -</tt></b>
- <dd>Sets the opacity alpha value in the graphics state.
- The initial opacity alpha value is 1.
- </dl>
- <dl>
- <dt><b><tt>- .currentopacityalpha <0..1></tt></b>
- <dd>Returns the current opacity alpha value.
- </dl>
- <dl>
- <dt><b><tt><0..1> .setshapealpha -</tt></b>
- <dd>Sets the shape alpha value in the graphics state.
- The initial shape alpha value is 1.
- </dl>
- <dl>
- <dt><b><tt>- .currentshapealpha <0..1></tt></b>
- <dd>Returns the current shape alpha value.
- </dl>
- <dl>
- <dt><b><tt><bool> .settextknockout -</tt></b>
- <dd>Sets the text knockout flag in the graphics state.
- The initial value of the text knockout flag is <b><tt>true</tt></b>.
- </dl>
- <dl>
- <dt><b><tt>- .currenttextknockout <bool></tt></b>
- <dd>Returns the current text knockout flag.
- </dl>
- <h5><a name="Transparency_rendering_stack_operators"></a>Rendering stack
- operators</h5>
- <p>
- The interpreter state is extended to include a (per-context) rendering stack
- for handling transparency groups and masks (generically, "layers"). Groups
- accumulate a full value for each pixel (paint plus transparency); masks
- accumulate only a coverage value. Layers must be properly nested, i.e., the
- 'end' or 'discard' operator must match the corresponding 'begin' operator.
- <p>
- Beginning and ending layers must nest properly with respect to
- <b><tt>save</tt></b> and <b><tt>restore</tt></b>: <b><tt>save</tt></b> and
- <b><tt>restore</tt></b> do not save and restore the layer stack. Currently,
- layers are not required to nest with respect to <b><tt>gsave</tt></b> and
- <b><tt>grestore</tt></b>, except that the device that is current in the
- graphics state when ending a layer must be the same as the device that was
- current when beginning the layer. THIS AREA IS SUBJECT TO CHANGE.
- <dl>
- <dt><b><tt><paramdict> <llx> <lly> <urx> <ury>
- .begintransparencygroup -</tt></b>
- <dd>Begins a new transparency group. The <b><tt>ll/ur</tt></b> coordinates
- are the bounding box of the group in the current user coordinate system.
- <b><tt>paramdict</tt></b> has the following keys:
- <dl>
- <dt><b><tt>/Isolated</tt></b>
- <dd>(optional) Boolean; default value = <b><tt>false</tt></b>.
- <dt><b><tt>/Knockout</tt></b>
- <dd>(optional) Boolean; default value = <b><tt>false</tt></b>.
- </dl>
- </dl>
- <dl>
- <dt><b><tt>- .discardtransparencygroup -</tt></b>
- <dd>Ends and discards the current transparency group.
- </dl>
- <dl>
- <dt><b><tt>- .endtransparencygroup -</tt></b>
- <dd>Ends the current transparency group, compositing the group being ended
- onto the group that now becomes current.
- </dl>
- <dl>
- <dt><b><tt><paramdict> <llx> <lly> <urx> <ury>
- .begintransparencymask -</tt></b>
- <dd>Begins a new transparency mask. The <b><tt>ll/ur</tt></b> coordinates
- are the bounding box of the mask in the current user coordinate system.
- <b><tt>paramdict</tt></b> has the following keys:
- <dl>
- <dt><b><tt>/Subtype</tt></b>
- <dd>(required) Name, either <b><tt>/Alpha</tt></b> or
- <b><tt>/Luminosity</tt></b>.
- <dt><b><tt>/Background</tt></b>
- <dd>(optional) Array of number.
- <dt><b><tt>/TransferFunction</tt></b>
- <dd>(optional) Function object (produced by applying
- <b><tt>.buildfunction</tt></b> to a Function dictionary).
- </dl>
- </dl>
- <dl>
- <dt><b><tt>- .discardtransparencymask -</tt></b>
- <dd>Ends and discards the current transparency mask.
- </dl>
- <dl>
- <dt><b><tt><masknum> .endtransparencymask -</tt></b>
- <dd>Ends the current transparency mask, installing it as the current opacity
- (<b><tt>masknum</tt></b> = 0) or shape (<b><tt>masknum</tt></b> = 1) mask in
- the graphics state.
- </dl>
- <dl>
- <dt><b><tt><masknum> .inittransparencymask -</tt></b>
- <dd>Resets the current opacity (<b><tt>masknum</tt></b> = 0) or shape
- (<b><tt>masknum</tt></b> = 1) mask to an infinite mask with alpha = 1
- everywhere.
- </dl>
- <h5><a name="Transparency_ImageType"></a>New ImageType</h5>
- <p>
- The transparency extension defines a new ImageType 103, similar to ImageType
- 3 with the following differences:
- <ul>
- <li>The required <b><tt>MaskDict</tt></b> is replaced by two optional
- dictionaries, <b><tt>OpacityMaskDict</tt></b> and
- <b><tt>ShapeMaskDict</tt></b>. If present, these dictionaries must have a
- <b><tt>BitsPerComponent</tt></b> entry, whose value may be greater than 1.
- Note that in contrast to ImageType 3, where any non-zero chunky mask value
- is equivalent to 1, ImageType 103 simply takes the low-order bits of chunky
- mask values.
- <li>A <b><tt>Matte</tt></b> entry may be present in one or both mask
- dictionaries, indicating premultiplication of the data values. If both
- <b><tt>MaskDict</tt></b>s have a <b><tt>Matte</tt></b> entry and the values
- of the two <b><tt>Matte</tt></b> entries are different, a
- <b><tt>rangecheck</tt></b> error occurs.
- <li><b><tt>InterleaveType</tt></b> appears in the <b><tt>MaskDict</tt></b>s,
- not the <b><tt>DataDict</tt></b>, because each mask has its own
- <b><tt>InterleaveType</tt></b>. <b><tt>InterleaveType</tt></b> 2
- (interlaced scan lines) is not supported.
- </ul>
- <h4><a name="Graphics_state"></a>Other graphics state operators</h4>
- <dl>
- <dt><b><tt><bool> .setaccuratecurves -</tt></b>
- <dd>Sets a graphics state flag that determines whether curves and arcs,
- when flattened, always start and end with a line that is a segment of the
- tangent; this also causes butt and square caps to be properly perpendicular
- to the tangent. <b><tt>initgraphics</tt></b> sets this flag to false, to
- match other PostScript implementations.
- </dl>
- <dl>
- <dt><b><tt>- .currentaccuratecurves <bool></tt></b>
- <dd>Returns the current value of the accurate curves flag.
- </dl>
- <dl>
- <dt><b><tt><int> .setcurvejoin -</tt></b>
- <dd>Sets a graphics state parameter that determines how to treat the joins
- between the line segments produced when a curve is flattened. The parameter
- value may be either -1 or a value acceptable to <b><tt>setlinejoin</tt></b>.
- If the parameter value is -1, the join used for flattened curve line
- segments is given by the current line join parameter in the graphics state
- (except that if the line join value is "none", a bevel join is used), which
- matches the Adobe Red Book, but not the Adobe implementations; if the curve
- join parameter value is a line join value, that type of join is used for
- flattened curve line segments, regardless of the value of the graphics state
- line join parameter. The initial (and default) value of the curve join
- parameter is 2, causing bevel joins to be used: this matches the Adobe
- implementations. <b><tt>initgraphics</tt></b> sets the parameter to its
- default value.
- </dl>
- <dl>
- <dt><b><tt>- .currentcurvejoin <int></tt></b>
- <dd>Returns the current value of the curve join parameter.
- </dl>
- <dl>
- <dt><b><tt><bool> .setdashadapt -</tt></b>
- <dd>Sets a graphics state flag that determines whether dash patterns do
- (true) or do not (false) automatically scale themselves so that each line
- segment consists of an integral number of pattern repetitions.
- <b><tt>initgraphics</tt></b> sets this flag to false.
- </dl>
- <dl>
- <dt><b><tt>- .currentdashadapt <bool></tt></b>
- <dd>Returns the current value of the dash adaptation flag.
- </dl>
- <dl>
- <dt><b><tt><matrix> .setdefaultmatrix -</tt></b>
- <dd>Sets the default matrix that is returned by
- <b><tt>defaultmatrix</tt></b> and installed by <b><tt>initmatrix</tt></b>.
- Ordinary programs should not use this operator.
- </dl>
- <dl>
- <dt><b><tt><num> <bool> .setdotlength -</tt></b>
- <dd>Sets a graphics state parameter that determines the handling of
- zero-length lines (dots). If the dot length is zero, dots are painted as
- circles if round line caps are in effect, otherwise they are not painted at
- all. If the dot length is non-zero, dots are treated exactly like lines of
- the given length: the length is specified in user coordinates (like line
- width) if <b><tt>bool</tt></b> is false, or in default user coordinates of
- points (units of 1/72in; see the <a href="Devices.htm#Measurements">notes
- on measurements</a> in the documentation on devices) if
- <b><tt>bool</tt></b> is true. Dots occurring as part of dash patterns will
- be oriented correctly; isolated dots will be oriented as though they were
- part of a vertical line. <b><tt>initgraphics</tt></b> sets the dot length
- to zero.
- </dl>
- <dl>
- <dt><b><tt>- .currentdotlength <num> <bool></tt></b>
- <dd>Returns the current dot length and dot length mode.
- </dl>
- <dl>
- <dt><b><tt><dx> <dy> .setfilladjust2 -</tt></b>
- <dd>Sets graphics state parameters that cause all filled and stroked
- regions to be "fattened" by the given amount relative to an algorithm that
- only paints pixels whose centers fall within the region to be painted.
- <b><tt>dx</tt></b> and <b><tt>dy</tt></b> are numbers between 0 and 0.5,
- measured in device space. The only two values that are likely to be useful
- are 0, which gives a pure center-of-pixel rule, and 0.5, which gives
- Adobe's any-part-of-pixel rule. (0.5 is treated slightly specially in
- order to create half-open pixels per Adobe's specification.)
- </dl>
- <dl>
- <dt><b><tt>- .currentfilladjust2 <dx> <dy></tt></b>
- <dd>Returns the current fill adjustment values.
- </dl>
- <dl>
- <dt><b><tt><bool> .setlimitclamp -</tt></b>
- <dd>Sets a graphics state flag that determines whether attempts to set the
- current point outside the internally representable range should clamp the
- value to the largest representable value (true) or give a
- <b><tt>limitcheck</tt></b> error (false). <b><tt>initgraphics</tt></b> sets
- this flag to false, to match other PostScript implementations.
- </dl>
- <dl>
- <dt><b><tt>- .currentlimitclamp <bool></tt></b>
- <dd>Returns the current value of the limit clamp flag.
- </dl>
- <dl>
- <dt><b><tt><int> .setoverprintmode -</tt></b>
- <dd>Sets the overprint mode in the graphics state. Legal values are 0 or 1.
- Per the PDF 1.3 specification, if the overprint mode is 1, then when the
- current color space is <b><tt>DeviceCMYK</tt></b>, color components whose
- value is 0 do not write into the target, rather than writing a 0 value.
- THIS BEHAVIOR IS NOT IMPLEMENTED YET. The initial value of the overprint
- mode is 0.
- </dl>
- <dl>
- <dt><b><tt>- .currentoverprintmode <int></tt></b>
- <dd>Returns the current overprint mode.
- </dl>
- <h4><a name="Path"></a>Path operators</h4>
- <dl>
- <dt><b><tt>- .dashpath -</tt></b>
- <dd>If there is no current dash pattern, does nothing. Otherwise, does the
- equivalent of <b><tt>flattenpath</tt></b> and then chops up the path as
- determined by the dash pattern.
- </dl>
- <dl>
- <dt><b><tt><x> <y> <width> <height> .rectappend -</tt></b>
- <dt><b><tt><numarray> .rectappend -</tt></b>
- <dt><b><tt><numstring> .rectappend -</tt></b>
- <dd>Appends a rectangle or rectangles to the current path, in the same
- manner as <b><tt>rectfill</tt></b>, <b><tt>rectclip</tt></b>, etc. Defined
- only if the <b><tt>dps</tt></b> or <b><tt>level2</tt></b> option was
- selected when Ghostscript was built.
- </dl>
- <h4><a name="Painting"></a>Painting operators</h4>
- <p>
- Ghostscript supports an experimental extension of the PostScript imaging
- model to include <b><tt>RasterOp</tt></b> and some related facilities.
- This extension is available only if the <b><tt>rasterop</tt></b> option was
- selected when building Ghostscript.
- <p>
- With the <b><tt>RasterOp</tt></b> extension, imaging operations compute a
- function <b>D = f(D,S,T)</b> in RGB space, where <b>f</b> is an
- arbitrary 3-input Boolean function, <b>D</b> is the destination (frame
- buffer or print buffer), <b>S</b> is the source (described below), and
- <b>T</b> is the texture (the current PostScript color, which may be a
- pattern). The source and texture depend on the PostScript imaging
- operation:
- <ul>
- <li>For <b><tt>fill</tt></b> and <b><tt>stroke</tt></b>, the source is
- solid black, covering the region to be painted; the texture is the current
- PostScript color.
- <li>For <b><tt>show</tt></b> and <b><tt>imagemask</tt></b>, the source is
- solid black, covering the pixels to be painted; the texture is the current
- PostScript color.
- <li>For <b><tt>image</tt></b> and <b><tt>colorimage</tt></b>, the source is
- the image data; the texture depends on an optional Boolean parameter,
- <b><tt>CombineWithColor</tt></b>, in the image dictionary. If
- <b><tt>CombineWithColor</tt></b> is false (the default), the texture is
- solid black. If <b><tt>CombineWithColor</tt></b> is true, the texture is
- the current color. For the non-dictionary form of the image operator,
- <b><tt>CombineWithColor</tt></b> is considered to be false.
- </ul>
- <p>
- The <b><tt>rasterop</tt></b> option adds the following operators:
- <dl>
- <dt><b><tt><int8> .setrasterop -</tt></b>
- <dd>Sets the <b><tt>RasterOp</tt></b> function in the graphics state. The
- default function is 252, Source | Texture.
- </dl>
- <dl>
- <dt><b><tt>- .currentrasterop <int8></tt></b>
- <dd>Returns the current <b><tt>RasterOp</tt></b> function.
- </dl>
- <dl>
- <dt><b><tt><bool> .setsourcetransparent -</tt></b>
- <dd>Sets source transparency in the graphics state. When source
- transparency is true, white source pixels prevent storing into the
- destination, regardless of what the <b><tt>RasterOp</tt></b> function
- returns. The default source transparency is false.
- </dl>
- <dl>
- <dt><b><tt>- .currentsourcetransparent <bool> -</tt></b>
- <dd>Returns the current source transparency.
- </dl>
- <dl>
- <dt><b><tt><bool> .settexturetransparent -</tt></b>
- <dd>Sets texture transparency in the graphics state. When texture
- transparency is true, white texture pixels prevent storing into the
- destination, regardless of what the <b><tt>RasterOp</tt></b> function
- returns. The default texture transparency is false.
- </dl>
- <dl>
- <dt><b><tt>- .currenttexturetransparent <bool> -</tt></b>
- <dd>Returns the current texture transparency.
- </dl>
- <p>
- For more information on RasterOp and transparency, please consult chapter 5
- of the "PCL 5 Color Technical Reference Manual",
- <a href="http://www.hp.com/cposupport/printers/support_doc/bpl01354.html">Hewlett-Packard
- Manual Part No. 5961-0635</a>.
- <h4><a name="Character"></a>Character operators</h4>
- <dl>
- <dt><b><tt><string> <bool> .charboxpath -</tt></b>
- <dd>For each character <b>C</b> in the rendering of <string>, let the
- bounding box of <b>C</b> <b><em>in device space</em></b> be the four
- <b><em>user-space</em></b> points p1x/y, p2x/y, p3x/y, and p4x/y. For each
- character in order, <b><tt>.charboxpath</tt></b> appends the following to
- the current path:
- <ul><li>If <b><tt><bool></tt></b> is true, the equivalent of:
- <blockquote>
- p1x p1y <b><tt>moveto</tt></b><br>
- p2x p2y <b><tt>lineto</tt></b><br>
- p3x p3y <b><tt>lineto</tt></b><br>
- p4x p4y <b><tt>lineto</tt></b><br>
- <b><tt>closepath</tt></b>
- </blockquote>
- </ul>
- <p>
- This creates a path whose <b><tt>pathbbox</tt></b> is the
- <b><tt>bbox</tt></b> of the string.
- <ul><li>If <b><tt><bool></tt></b> is false, the equivalent of:
- <blockquote>
- p1x p1y <b><tt>moveto</tt></b><br>
- p3x p3y <b><tt>lineto</tt></b>
- </blockquote>
- </ul>
- <p>
- If the CTM is well-behaved (consists only of reflection, scaling, and
- rotation by multiples of 90 degrees), this too creates a (simpler) path
- whose <b><tt>pathbbox</tt></b> is the <b><tt>bbox</tt></b> of the string.
- </dl>
- <dl>
- <dt><b><tt><font> <charname|charcode> <charname> <charstring> .type1execchar -</tt></b>
- <dd>Does all the work for rendering a Type 1 outline. This operator, like
- <b><tt>setcharwidth</tt></b> and <b><tt>setcachedevice</tt></b>, is valid
- only in the context of a show operator -- that is, it must only be called
- from within a <b><tt>BuildChar</tt></b> or <b><tt>BuildGlyph</tt></b>
- procedure.
- </dl>
- <dl>
- <dt><b><tt><font> <charcode> %Type1BuildChar -</tt></b>
- <dd>This is not a new operator: rather, it is a name known specially to the
- interpreter. Whenever the interpreter needs to render a character (during
- a ...<b><tt>show</tt></b>, <b><tt>stringwidth</tt></b>, or
- <b><tt>charpath</tt></b>), it looks up the name <b><tt>BuildChar</tt></b>
- in the font dictionary to find a procedure to run. If it does not find
- this name, and if the <b><tt>FontType</tt></b> is 1, the interpreter
- instead uses the value (looked up on the dictionary stack in the usual way)
- of the name <b><tt>%Type1BuildChar</tt></b>.
- <p>
- The standard definition of <b><tt>%Type1BuildChar</tt></b> is in the
- initialization file <b><tt>gs_type1.ps</tt></b>. Users should not need to
- redefine <b><tt>%Type1BuildChar</tt></b>, except perhaps for tracing or
- debugging.
- </dl>
- <dl>
- <dt><b><tt><font> <charname> %Type1BuildGlyph -</tt></b>
- <dd>Provides the Type 1 implementation of <b><tt>BuildGlyph</tt></b>.
- </dl>
- <h3><a name="Other"></a>Other operators</h3>
- <h4><a name="Mathematical"></a>Mathematical operators</h4>
- <dl>
- <dt><b><tt><number> arccos <number></tt></b>
- <dd>Computes the arc cosine of a number between -1 and 1.
- </dl>
- <dl>
- <dt><b><tt><number> arcsin <number></tt></b>
- <dd>Computes the arc sine of a number between -1 and 1.
- </dl>
- <h4><a name="Dictionary"></a>Dictionary operators</h4>
- <dl>
- <dt><b><tt>mark <key1> <value1> <key2> <value2> ... .dicttomark <dict></tt></b>
- <dd>Creates and returns a dictionary with the given keys and values. This
- is the same as the PostScript Level 2 <b><tt>>></tt></b> operator,
- but is available even in Level 1 configurations.
- </dl>
- <dl>
- <dt><b><tt><dict> <key> <value> .forceput - </tt></b>
- <dd>Equivalent to <b><tt>put</tt></b>, but works even if
- <b><tt>dict</tt></b> is not writable, and (if <b><tt>dict</tt></b> is
- <b><tt>systemdict</tt></b> or the current save level is 0) even if
- <b><tt>dict</tt></b> is in global VM and <b><tt>key</tt></b> and/or
- <b><tt>value</tt></b> is in local VM. <strong>This operator should be used
- only initialization code, and only in executeonly procedures: it must not be
- accessible after initialization.</strong>
- </dl>
- <dl>
- <dt><b><tt><dict> <key> .forceundef - </tt></b>
- <dd>Equivalent to <b><tt>undef</tt></b>, but works even if
- <b><tt>dict</tt></b> is not writable. <strong>This operator should be used
- only initialization code, and only in executeonly procedures: it must not be
- accessible after initialization.</strong>
- </dl>
- <dl>
- <dt><b><tt><dict> <key> .knownget <value> true</tt></b>
- <dt><b><tt><dict> <key> .knownget false</tt></b>
- <dd>Combines <b><tt>known</tt></b> and <b><tt>get</tt></b> in the
- obvious way.
- </dl>
- <dl>
- <dt><b><tt><dict> <integer> .setmaxlength -</tt></b>
- <dd>Sets the capacity (<b><tt>maxlength</tt></b>) of a dictionary.
- Causes a <b><tt>dictfull</tt></b> error if the dictionary has more
- occupied entries than the requested capacity.
- </dl>
- <h4><a name="String"></a>String and name operators</h4>
- <dl>
- <dt><b><tt><integer> .bytestring <bytestring></tt></b>
- <dd>Allocates and returns a bytestring, a special data type that can be
- larger than the maximum size of a string (64K-1 bytes) and can be used in
- place of a string with a very few operators.
- </dl>
- <dl>
- <dt><b><tt><name> .namestring <string></tt></b>
- <dd>Returns the (read-only) string for a name.
- </dl>
- <dl>
- <dt><b><tt><obj> <pattern> .stringmatch <bool></tt></b>
- <dd>Matches <b><tt>obj</tt></b> against a pattern in which '*' matches 0 or
- more characters and '?' matches any single character. If
- <b><tt>obj</tt></b> is a string or a name, matches its characters against
- the pattern; if <b><tt>obj</tt></b> is of any other type, the result is
- <b><tt>true</tt></b> if the pattern is the single character "*" and
- <b><tt>false</tt></b> otherwise.
- </dl>
- <dl>
- <dt><b><tt><state> <fromString> <toString> .type1encrypt <newState> <toSubstring></tt></b>
- <dd>Encrypts <b><tt>fromString</tt></b> according to the algorithm for
- Adobe Type 1 fonts, writing the result into <b><tt>toString</tt></b>.
- <b><tt>toString</tt></b> must be at least as long as
- <b><tt>fromString</tt></b>, or a rangecheck error occurs.
- <b><tt>state</tt></b> is the initial state of the encryption algorithm (a
- 16-bit non-negative integer); <b><tt>newState</tt></b> is the new state of
- the algorithm.
- </dl>
- <dl>
- <dt><b><tt><state> <fromString> <toString> .type1decrypt <newState> <toSubstring></tt></b>
- <dd>Decrypts <b><tt>fromString</tt></b> according to the algorithm for
- Adobe Type 1 fonts, writing the result into <b><tt>toString</tt></b>.
- Other specifications are as for <b><tt>type1encrypt</tt></b>.
- </dl>
- <h4><a name="Relational"></a>Relational operators</h4>
- <dl>
- <dt><b><tt><number|string> <number|string> max <number|string></tt></b>
- <dd>Returns the larger of two numbers or strings.
- </dl>
- <dl>
- <dt><b><tt><number|string> <number|string> min <number|string></tt></b>
- <dd>Returns the smaller of two numbers or strings.
- </dl>
- <h4><a name="File"></a>File operators</h4>
- <dl>
- <dt><b><tt><file> .filename <string> true</tt></b>
- <dt><b><tt><file> .filename false</tt></b>
- <dd>If the file was opened by the <b><tt>file</tt></b> or
- <b><tt>.tempfile</tt></b> operator, returns the file name and
- <b><tt>true</tt></b>; if the file is a filter, returns
- <b><tt>false</tt></b>.
- </dl>
- <dl>
- <dt><b><tt><file> .fileposition <integer> true</tt></b>
- <dd>Returns the position of <b><tt>file</tt></b>. Unlike the standard
- <b><tt>fileposition</tt></b> operator, which causes an error if the file is
- not positionable, <b><tt>.fileposition</tt></b> works on all files,
- including filters: for non-positionable files, it returns the total number
- of bytes read or written since the file was opened.
- </dl>
- <dl>
- <dt><b><tt><string> findlibfile <foundstring> <file> true</tt></b>
- <dt><b><tt><string> findlibfile <string> false</tt></b>
- <dd>Opens the file of the given name for reading, searching through
- directories <a href="Use.htm#Finding_files">as described in the usage
- documentation</a>. If the search fails, <b><tt>findlibfile</tt></b> simply
- pushes false on the stack and returns, rather than causing an error.
- </dl>
- <dl>
- <dt><b><tt><file> <string> .peekstring <substring> <filled_bool></tt></b>
- <dd>Reads bytes from a file like <b><tt>readstring</tt></b>, but also leaves
- the bytes in the file buffer so they will be read again by a subsequent read
- operation. Currently gives a <b><tt>rangecheck</tt></b> error if
- <b><tt>string</tt></b> is larger than the file's buffer.
- </dl>
- <a name=Tempfile></a>
- <dl>
- <dt><b><tt><prefix_string|null> <access_string> .tempfile
- <string> <file></tt></b>
- <dd>Creates and opens a temporary file
- like the <b><tt>file</tt></b> operator, also returning the file name. There
- are three cases for the <b><tt><prefix_string|null></tt></b> operand:
- <ul>
- <p>
- <li><b><tt>null</tt></b>: create the file in the same directory and with the
- same name conventions as other temporary files created by the Ghostscript
- implementation on this platform. E.g., the temporary file might be named
- <b><tt>/tmp/gs_a1234</tt></b>.
- <p>
- <li>A string that is not the beginning of an absolute file name (e.g., does
- not begin with <b><tt>.</tt></b> or <b><tt>/</tt></b> on Unix-like
- platforms): create the file in the standard temporary directory, but use the
- <b><tt><prefix_string></tt></b> as the first part of the file name.
- E.g., if <b><tt><prefix_string></tt></b> is <b><tt>xx</tt></b>, the
- temporary file might be named <b><tt>/tmp/xxa1234</tt></b>.
- <p>
- <li>A string that is the beginning of an absolute file name: use the
- <b><tt><prefix_string></tt></b> as the first part of the file name.
- E.g., if <b><tt><prefix_string></tt></b> is
- <b><tt>/my/tmpdir/zz</tt></b>, the temporary file might be named
- <b><tt>/my/tmpdir/zza1234</tt></b>.
- <p>
- When running in <b><tt>SAFER</tt></b> mode, the absolute path must
- be one of the strings on the list given by the <b><tt>PermitFileWriting</tt></b>
- userparameter. Temporary files created with <b><tt>.tempfile</tt></b> can
- be deleted when in SAFER mode, and can be renamed to one of the paths
- that is on <b>both</b> the PermitFileControl and PermitFileWriting
- paths.
- </ul>
- <p>
- It is intended that in some future version of Ghostscript, files opened with
- <b><tt>.tempfile</tt></b> will be closed and deleted automatically when
- Ghostscript exits; however, this is not currently the case.
- </dl>
- <dl>
- <dt><b><tt><file> <integer> .unread -</tt></b>
- <dd>Pushes back the last-read character onto the front of the file. If the
- file is open only for writing, or if the integer argument is not the same
- as the last character read from the file, causes an <b><tt>ioerror</tt></b>
- error. May also cause an <b><tt>ioerror</tt></b> if the last operation on
- the file was not a reading operation. This operator is now deprecated:
- use <b><tt>.peekstring</tt></b> in new code.
- </dl>
-
- <p>
- Ghostscript also supports the following <b><tt>IODevice</tt></b> in
- addition to a subset of those defined in the Adobe documentation:
- <b><tt>%pipe%command</tt></b>, which opens a pipe on the given command.
- This is supported only on operating systems that provide
- <b><tt>popen</tt></b> (primarily Unix systems, and not all of those).
- <h4><a name="Virtual_memory"></a>Virtual memory operators</h4>
- <dl>
- <dt><b><tt><save> .forgetsave -</tt></b>
- <dd>Cancels the effect of a save, making it as though the save never
- happened.
- </dl>
- <h4><a name="Miscellaneous"></a>Miscellaneous operators</h4>
- <dl>
- <dt><b><tt><obj1> <obj2> ... <objn> <n> .execn ...</tt></b>
- <dd>This executes <b><tt>obj1</tt></b> through <b><tt>objn</tt></b> in that
- order, essentially equivalent to
- <blockquote><pre>
- <obj1> <obj2> ... <objn> <n> array astore {exec} forall
- </pre></blockquote>
- <p>
- except that it doesn't actually create the array.
- </dl>
- <dl>
- <dt><b><tt><string> getenv <string> true</tt></b>
- <dt><b><tt><string> getenv false</tt></b>
- <dd>Looks up a name in the shell environment. If the name is found,
- returns the corresponding value and true; if the name is not found, returns
- false.
- </dl>
- <dl>
- <dt><b><tt><name> <array> .makeoperator <operator></tt></b>
- <dd>Constructs and returns a new operator that is actually the given
- procedure in disguise. The name is only used for printing. The operator
- has the executable attribute.
- <p>
- Operators defined in this way do one other thing besides running the
- procedure: if an error occurs during the execution of the procedure, and
- there has been no net reduction in operand or dictionary stack depth, the
- operand or dictionary stack pointer respectively is reset to its position
- at the beginning of the procedure.
- </dl>
- <dl>
- <dt><b><tt><string> <boolean> .setdebug -</tt></b>
- <dd>If the Ghostscript interpreter was built with the <b><tt>DEBUG</tt></b>
- flag set, sets or resets any subset of the debugging flags normally
- controlled by <b><tt>-Z</tt></b> in the command line. Has no effect
- otherwise.
- </dl>
- <dl>
- <dt><b><tt>- .oserrno <errno></tt></b>
- <dd>Returns the error code for the most recent operating system error.
- </dl>
- <dl>
- <dt><b><tt>- .oserrorstring <string></tt></b>
- <dd>Returns the error string for the most recent operating system error.
- </dl>
- <a name="Runandhide"></a>
- <dl>
- <dt><b><tt><array> <procedure> .runandhide ... <array></tt></b>
- <dd>Runs the <i><tt><procedure></tt></i> after removing the
- <i><tt><array></tt></i> from the stack. As long as <i><tt><array></tt></i>
- is not contained in any readable dictionaries or elsewhere on stacks, it
- will not be accessible to <i><tt><procedure></tt></i>.
- <p>
- This operator is intended to allow hiding a <i><tt><save></tt></i> object
- during execution of procedures or files that run in <b>SAFER</b> mode.
- If a <b><tt>save</tt></b> is performed prior to entering <b>SAFER</b> mode
- with <b><tt>.setsafe</tt></b>, using the save object as the operand to
- <b><tt>restore</tt></b> will return to <b>NOSAFER</b> mode. In order to
- prevent the procedures running in <b>SAFER</b> mode from being able to
- return to <b>NOSAFER</b> mode, this operator should be used.
- Upon return from the file or procedure <b><tt>restore</tt></b> can be used
- to return to <b>NOSAFER</b> mode.
- <p>
- <b>Note:</b> The array operand hidden during the execution of the file or
- procedure will be placed at the top of the operand stack which may be on
- top of objects that the file or procedure leaves on top of the stack.
- Thus removing objects below the array may be needed to prevent an
- <b><tt>invalidrestore</tt></b> error.
- <p>
- For example, in order for a script or job server to execute a file
- <tt>somefile.ps</tt> with the <b>SAFER</b> mode restrictions in place, returning
- to unrestricted <b>NOSAFER</b> mode when the procedure exits is as follows:
- <pre>
- Start Ghostscript with <b>-dNOSAFER</b>
- ... % perform any device set up w/o restrictions
- [ save ] % create a save object before SAFER
- (somefile.ps) (r) file cvx % open the file to process
- .setsafe % enter SAFER mode
- .runandhide % run the file hiding the save object
- count 1 roll % place array below anything left over
- count 1 sub { pop } repeat % pop left over stuff
- cleardictstack % prevent invalidrestore from dicts
- 0 get restore % go back to NOSAFER mode
- </pre>
- Another refinement on the above would be to execute <b><tt>.runandhide</tt></b>
- using <b><tt>stopped</tt></b> in order to report errors but continue processing.
- </dl>
- <dl>
- <dt><b><tt>- .setsafe -</tt></b>
- <dd>If Ghostscript is started with <b><tt>-dNOSAFER</tt></b> or
- <b><tt>-dDELAYSAFER</tt></b>, this operator can be used to enter <b>SAFER</b>
- mode (see <a href="Use.htm#Safer"><b>-dSAFER</b></a>)
- <p>
- <b>Note: </b>If <b><tt>-dPARANOIDSAFER</tt></b> was specified on the command
- line, <b><tt>.setsafe</tt></b> also sets the <b><tt>PermitFileReading</tt></b>
- parameter to an empty array.
- <p>
- Since <b>SAFER</b> mode is implemented with userparameters and device parameters,
- it is possible to use <b><tt>save</tt></b> and <b><tt>restore</tt></b> before
- and after <b><tt>.setsafe</tt></b> to return to <b>NOSAFER</b> mode, but care
- should be taken to ensure that the <i><tt>save</tt></i> object is not
- accessible to any procedures or file run in <b>SAFER</b> mode (see
- <a href="#Runandhide"><b>.runandhide</b></a> above).
- </dl>
- <dl>
- <dt><b><tt>- .locksafe -</tt></b>
- <dd>
- This operator sets the current device's <b><tt>.LockSafetyParams</tt></b>
- and the <b><tt>LockFilePermissions</tt></b> user parameter true as well as
- adding the paths on LIBPATH and FONTPATH and the paths given by the
- system params /GenericResourceDir and /FontResourceDir to the current
- PermitFileReading list of paths.
- <p>
- If Ghostscript is started with <b><tt>-dNOSAFER</tt></b> or
- <b><tt>-dDELAYSAFER</tt></b>, this operator can be used to enter <b>SAFER</b>
- mode with the current set of <b><tt>PermitFile...</tt></b> user parameters
- in effect. Since <b><tt>.setsafe</tt></b> sets the <b><tt>PermitFileWriting</tt></b>
- and <b><tt>PermitFileControl</tt></b> user parameters to empty arrays, a script
- or job server that needs to enable certain paths for file Writing and/or Control
- can use this operator to perform the locking needed to enter <b>SAFER</b> mode.
- <p>
- See also <a href="#LockSafetyParams">.LockSafetyParams</a> and
- <a href="#User_parameters">User Parameters</a>.
- <p>
- </dl>
- <h4><a name="Device"></a>Device operators</h4>
- <dl>
- <dt><b><tt><device> copydevice <device></tt></b>
- <dd>Copies a device. The copy is writable and installable. The copy is
- created in the current VM (local or global), usually local VM for executing
- ordinary PostScript files.
- </dl>
- <dl>
- <dt><b><tt><devicename> finddevice <device></tt></b>
- <dd>Creates a default instance of a device specified by name. The instance
- is created in global VM. If <b><tt>finddevice</tt></b> is called more than
- once with the same device name, it creates the default instance the first
- time, and returns the same instance thereafter.
- </dl>
- <dl>
- <dt><b><tt><devicename> findprotodevice <device></tt></b>
- <dd>Finds the prototype of a device specified by name. A prototype can be
- used with <b><tt>.getdeviceparams</tt></b> or other parameter-reading
- operators, but it is read-only and cannot be set with
- <b><tt>setdevice</tt></b>: it must be copied first.
- </dl>
- <dl>
- <dt><b><tt><device> <x> <y> <width> <max_height> <alpha?> <std_depth|null> <string> .getbitsrect <height> <substring></tt></b>
- <dd>Reads a rectangle of rendered bits back from a device. This is only
- guaranteed to be implemented for image devices (see below).
- <b><tt>alpha?</tt></b> is 0 for no alpha, -1 for alpha first, 1 for alpha
- last. <b><tt>std_depth</tt></b> is null for native pixels, number of bits
- per component for a standard color space.
- </dl>
- <dl>
- <dt><b><tt><index> .getdevice <device></tt></b>
- <dd>Returns a device from the set of devices known to the system. The
- first device, which is the default, is numbered 0. If the
- <b><tt>index</tt></b> is out of range, causes a <b><tt>rangecheck</tt></b>
- error. This device is actually a prototype, not a directly usable device,
- and is marked read-only; it cannot have its parameters changed or be
- installed as the current device.
- </dl>
- <dl>
- <dt><b><tt><matrix> <width> <height> <palette> makeimagedevice <device></tt></b>
- <dd>Makes a new device that accumulates an image in memory. <b><tt>
- matrix</tt></b> is the initial transformation matrix: it must be orthogonal
- (that is, [a 0 0 b x y] or
- [0 a b 0 x y]). <b><tt>palette</tt></b> is a
- string of 2^<small><sup><b>N</b></sup></small> or
- 3 × 2^<small><sup><b>N</b></sup></small> elements,
- specifying how the 2^<small><sup><b>N</b></sup></small> possible pixel
- values will be interpreted. Each element is interpreted as a gray value,
- or as RGB values, multiplied by 255. For example, if you want a monochrome
- image for which 0=white and 1=black, the palette should be
- <b><tt><ff 00></tt></b>; if you want a 3-bit deep image with
- just the primary colors and their complements (ignoring the fact that 3-bit
- images are not supported), the palette might be <b><tt><000000 0000ff
- 00ff00 00ffff ff0000 ff00ff ffff00 ffffff></tt></b>. At present, the
- palette must contain exactly 2, 4, 16, or 256 entries, and must contain an
- entry for black and an entry for white; if it contains any entries that
- aren't black, white, or gray, it must contain at least the six primary
- colors (red, green, blue, and their complements cyan, magenta, and yellow);
- aside from this, its contents are arbitrary.
- <p>
- Alternatively, palette can be 16, 24, 32, or null (equivalent to 24).
- These are interpreted as:
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr valign=bottom>
- <th valign=bottom align=left>Palette
- <td>
- <th valign=bottom align=left>Bits allocated per color
- <tr> <td colspan=3><hr>
- <tr valign=top> <td>16
- <td>
- <td>5 red, 6 green, 5 blue
- <tr valign=top> <td>24
- <td>
- <td>8 red, 8 green, 8 blue
- <tr valign=top> <td>32
- <td>
- <td>8C, 8M, 8Y, 8K
- </table></blockquote>
- <p>
- Note that one can also make an image device (with the same palette as an
- existing image device) by copying a device using the
- <b><tt>copydevice</tt></b> operator.
- </dl>
- <dl>
- <dt><b><tt><matrix> <width> <height> <palette> <word?> makewordimagedevice <device></tt></b>
- <dd>Makes an image device as described above. <b><tt>word?</tt></b> is a
- Boolean value indicating whether the data should be stored in a
- word-oriented format internally. No ordinary PostScript programs should
- use this operator.
- </dl>
- <dl>
- <dt><b><tt><device> <index> <string> copyscanlines <substring></tt></b>
- <dd>Copies one or more scan lines from an image device into a string,
- starting at a given scan line in the image. The data is in the same format
- as for the <b><tt>image</tt></b> operator. It is an error if the device is
- not an image device or if the string is too small to hold at least one
- complete scan line. Always copies an integral number of scan lines.
- </dl>
- <dl>
- <dt><b><tt><device> setdevice -</tt></b>
- <dd>Sets the current device to the specified device. Also resets the
- transformation and clipping path to the initial values for the device.
- Signals an <b><tt>invalidaccess</tt></b> error if the device is a
- prototype or if <a href="Language.htm#LockSafetyParams">.LockSafetyParams</a>
- is true for the current device.
- </dl>
- <dl>
- <dt><b><tt>- currentdevice <device></tt></b>
- <dd>Gets the current device from the graphics state.
- </dl>
- <dl>
- <dt><b><tt><device> getdeviceprops <mark> <name1> <value1> ... <namen> <valuen></tt></b>
- <dd>Gets the properties of a device. See the section on
- <a href="#Device_parameters">device parameters</a> below for details.
- </dl>
- <dl>
- <dt><b><tt><mark> <name1> <value1> ... <namen> <valuen> <device> putdeviceprops <device></tt></b>
- <dd>Sets properties of a device. May cause <b><tt>undefined</tt></b>,
- <b><tt>invalidaccess</tt></b>, <b><tt>typecheck</tt></b>, <b><tt>rangecheck</tt></b>, or
- <b><tt>limitcheck</tt></b> errors.
- </dl>
- <dl>
- <dt><b><tt>- flushpage -</tt></b>
- <dd>On displays, flushes any buffered output, so that it is guaranteed to
- show up on the screen; on printers, has no effect.
- </dl>
- <hr>
- <h2><a name="Filters"></a>Filters</h2>
- <h3><a name="Standard_filters"></a>Standard filters</h3>
- <p>
- In its usual configuration, Ghostscript supports all the standard PostScript
- LanguageLevel 3 filters, both encoding and decoding, except that it does not
- currently support:
- <ul>
- <li>the <b><tt>EarlyChange</tt></b> key in the <b><tt>LZWEncode</tt></b>
- filter.
- </ul>
- <p>
- Ghostscript also supports additional keys in the optional dictionary
- operands for some filters. For the <b><tt>LZWDecode</tt></b> filter:
- <dl>
- <dt><b><tt>InitialCodeLength <integer></tt></b> (default 8)
- <dd>An integer between 2 and 11 specifying the initial number of data bits
- per code. Note that the actual initial code length is 1 greater than this,
- to allow for the reset and end-of-data code values.
- </dl>
- <dl>
- <dt><b><tt>FirstBitLowOrder <boolean></tt></b> (default false)
- <dd>If true, codes appear with their low-order bit first.
- </dl>
- <dl>
- <dt><b><tt>BlockData <boolean></tt></b> (default false)
- <dd>If true, the data is broken into blocks in the manner specified for the
- GIF file format.
- </dl>
- <p>
- For the <b><tt>CCITTFaxEncode</tt></b> and <b><tt>CCITTFaxDecode</tt></b>
- filters:
- <dl>
- <dt><b><tt>DecodedByteAlign <integer></tt></b> (default 1)
- <dd>An integer <b>N</b> with the value 1, 2, 4, 8, or 16, specifying that
- decoded data scan lines are always a multiple of <b>N</b> bytes. The
- encoding filter skips data in each scan line from Columns to the next
- multiple of <b>N</b> bytes; the decoding filter pads each scan line to a
- multiple of <b>N</b> bytes.
- </dl>
- <h3><a name="Non_standard_filters"></a>Non-standard filters</h3>
- <p>
- In addition to the standard PostScript LanguageLevel 3 filters, Ghostscript
- supports the following non-standard filters. Many of these filters are used
- internally to implement standard filters or facilities; they are almost
- certain to remain, in their present form or a backward-compatible one, in
- future Ghostscript releases.
- <dl>
- <dt><b><tt><target> /BCPEncode filter <file></tt></b>
- <dt><b><tt><source> /BCPDecode filter <file></tt></b>
- <dd>Create filters that implement the Adobe Binary Communications Protocol.
- See Adobe documentation for details.
- </dl>
- <dl>
- <dt><b><tt><target> <seed_integer> /eexecEncode filter <file></tt></b>
- <dd>Creates a filter for encrypting data into the encrypted format described
- in the Adobe Type 1 Font Format documentation. The
- <b><tt>seed_integer</tt></b> must be 55665 for the <b><tt>eexec</tt></b>
- section of a font, or 4330 for a <b><tt>CharString</tt></b>. Note that for
- the <b><tt>eexec</tt></b> section of a font, this filter produces binary
- output and does not include the initial 4 (or <b><tt>lenIV</tt></b>) garbage
- bytes.
- </dl>
- <dl>
- <dt><b><tt><source> <seed_integer> /eexecDecode filter <file></tt></b>
- <dt><b><tt><source> <dict> /eexecDecode filter <file></tt></b>
- <dd>Creates a filter for decrypting data encrypted as described in the Adobe
- Type 1 Font Format documentation. The <b><tt>seed_integer</tt></b> must be
- 55665 or 4330 as described just above. Recognized dictionary keys are:
- <blockquote>
- <b><tt>seed <16-bit integer></tt></b> (required)<br>
- <b><tt>lenIV <non-negative integer></tt></b> (default=4)
- </blockquote>
- </dl>
- <dl>
- <dt><b><tt><target> /MD5Encode filter <file></tt></b>
- <dd>Creates a filter that produces the 16-byte MD5 digest of the input.
- Note that no output is produced until the filter is closed.
- </dl>
- <dl>
- <dt><b><tt><source> <hex_boolean> /PFBDecode filter <file></tt></b>
- <dd>Creates a filter that decodes data in <b><tt>.PFB</tt></b> format, the
- usual semi-binary representation for Type 1 font files on IBM PC and
- compatible systems. If <b><tt>hex_boolean</tt></b> is true, binary packets
- are converted to hex; if false, binary packets are not converted.
- </dl>
- <dl>
- <dt><b><tt><target> <dict> /PixelDifferenceEncode filter <file></tt></b>
- <dt><b><tt><source> <dict> /PixelDifferenceDecode filter <file></tt></b>
- <dd>Implements the Predictor=2 pixel-differencing option of the LZW
- filters. Recognized keys are:
- <blockquote>
- <b><tt>Colors <integer></tt></b> (1 to 4, default=1)<br>
- <b><tt>BitsPerComponent <integer></tt></b> (1, 2, 4, or 8, default=8)<br>
- <b><tt>Columns <integer></tt></b> (>= 0, required)
- </blockquote>
- <p>
- See the Adobe <a
- href="http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf"><em>Portable
- Document Format Reference Manual</em></a> for details.
- </dl>
- <dl>
- <dt><b><tt><target> <dict> /PNGPredictorEncode filter <file></tt></b>
- <dt><b><tt><source> <dict> /PNGPredictorDecode filter <file></tt></b>
- <dd>Implements the "filter" algorithms of the
- <a href="http://www.libpng.org/pub/png/">Portable Network Graphics (PNG)
- graphics format</a>. Recognized keys are:
- <blockquote><table cellpadding=0 cellspacing=0>
- <tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Keys recognized in PNG filter algorithms</font><hr>
- <tr valign=bottom>
- <th align=left>Key
- <td>
- <th align=left>Range
- <td>
- <th align=left>Default
- <tr> <td colspan=5><hr>
- <tr valign=top> <td><b><tt>Colors <integer></tt></b>
- <td>
- <td>1 to 16
- <td>
- <td>16
- <tr valign=top> <td><b><tt>BitsPerComponent <integer></tt></b>
- <td>
- <td>1, 2, 4, 8, or 16
- <td>
- <td>8
- <tr valign=top> <td><b><tt>Columns <integer></tt></b>
- <td>
- <td>>= 0
- <td>
- <td>1
- <tr valign=top> <td><b><tt>Predictor <integer></tt></b>
- <td>
- <td>10 to 15
- <td>
- <td>15
- </table></blockquote>
- <p>
- The <b><tt>Predictor</tt></b> is the PNG algorithm number + 10 for the
- <b><tt>Encoding</tt></b> filter; the <b><tt>Decoding</tt></b> filter
- ignores <b><tt>Predictor</tt></b>. 15 means the encoder attempts to
- optimize the choice of algorithm. For more details see the PNG
- specification
- <blockquote>
- <a href="http://www.w3.org/TR/WD-png-960128.html">http://www.w3.org/TR/WD-png-960128.html</a>
- </blockquote>
- </dl>
- <dl>
- <dt><b><tt><target> /TBCPEncode filter <file></tt></b>
- <dt><b><tt><source> /TBCPDecode filter <file></tt></b>
- <dd>Create filters that implement the Adobe Tagged Binary Communications
- Protocol. See Adobe documentation for details.
- </dl>
- <dl>
- <dt><b><tt><target> /zlibEncode filter <file></tt></b>
- <dt><b><tt><source> /zlibDecode filter <file></tt></b>
- <dd>Creates filters that use the data compression method variously known as
- 'zlib' (the name of a popular library that implements it), 'Deflate' (as in
- <a href="http://www.ietf.org/rfc/rfc1951.txt">RFC 1951</a>, which is a
- detailed specification for the method), 'gzip' (the name of a popular
- compression application that uses it), or 'Flate' (Adobe's name). Note that
- the PostScript <b><tt>Flate</tt></b> filters are actually a combination of
- this filter with an optional predictor filter.
- </dl>
- <h3><a name="Unstable_filters"></a>Unstable filters</h3>
- <p>
- Some versions of Ghostscript may also support other non-standard filters for
- experimental purposes. The current version includes the following such
- filters, which are not documented further. No code should assume that these
- filters will exist in compatible form, or at all, in future versions.
- <dl>
- <dt><b><tt><target/source> <string> ByteTranslateEncode/Decode filter <file></tt></b>
- <dd><b><tt>string</tt></b> must be a string of exactly 256 bytes. Creates a
- filter that converts each input byte <em>b</em> to
- <b><tt>string</tt></b>[<em>b</em>]. Note that the <b><tt>Encode</tt></b>
- and <b><tt>Decode</tt></b> filters operate identically: the client must
- provide a <b><tt>string</tt></b> for the <b><tt>Decode</tt></b> filter that
- is the inverse mapping of the <b><tt>string</tt></b> for the
- <b><tt>Encode</tt></b> filter.
- </dl>
- <dl>
- <dt><b><tt><target/source> <dict> BoundedHuffmanEncode/Decode filter <file></tt></b>
- <dd>These filters encode and decode data using Huffman codes. Since these
- filters aren't used anywhere, we don't document them further, except to note
- the recognized dictionary keys, which must be set identically for encoding
- and decoding:
- <blockquote>
- <b><tt>FirstBitLowOrder <bool></tt></b> (default=false)<br>
- <b><tt>MaxCodeLength <int></tt></b> (default=16)<br>
- <b><tt>EndOfData <bool></tt></b> (default=true)<br>
- <b><tt>EncodeZeroRuns <int></tt></b> (default=256)<br>
- <b><tt>Tables <int_array></tt></b>
- </blockquote>
- </dl>
- <dl>
- <dt><b><tt><target/source> <dict> BWBlockSortEncode/Decode filter <file></tt></b>
- <dd>This filter implements the Burroughs-Wheeler block sorting compression
- method, which we've heard is also used in the popular <b><tt>bzip2</tt></b>
- compression application. See <a
- href="http://sources.redhat.com/bzip2/">http://sources.redhat.com/bzip2/</a>
- for more information. The only recognized dictionary key is:
- <blockquote>
- <b><tt>BlockSize <integer></tt></b> (default=16384)
- </blockquote>
- </dl>
- <dl>
- <dt><b><tt><target/source> MoveToFrontEncode/Decode filter <file></tt></b>
- <dd>The <b><tt>Encode</tt></b> filter starts by initializing an internal
- 256-byte array <b><tt>a</tt></b> to the values 0 .. 255. This array will
- always hold a permutation of these values. Then for each input byte
- <em>b</em>, the filter outputs the index <em>i</em> such that
- <b><tt>a</tt></b>[<em>i</em>] = <em>b</em>, and moves that element to the
- front (element 0) of <b><tt>a</tt></b>, moving elements 0 .. <em>i-1</em> to
- positions 1 .. <em>i</em>. The <b><tt>Decode</tt></b> filter inverts this
- process.
- </dl>
- <hr>
- <h2><a name="Device_parameters"></a>Device parameters</h2>
- Ghostscript supports the concept of device parameters for all devices, not
- just page devices. (For non-page devices, these are accessible through
- <b><tt>getdeviceprops</tt></b> and <b><tt>putdeviceprops</tt></b>, as
- indicated above.) Here are the currently defined parameters for all
- devices:
- <dl>
- <a name="LockSafetyParams"></a>
- <dt><b><tt>.LockSafetyParams <boolean></tt></b>
- <dd>This parameter allows for improved system security by preventing
- PostScript programs from being able to change potentially dangerous
- device paramters such as OutputFile. This parameter cannot be set false
- if it is already true.
- <p>
- If this parameter is true for the current device, attempt to set a new
- device that has <b><tt>.LockSafetyParams</tt></b> false will signal an
- <tt><b> invalidaccess</b></tt> error.
- </dl>
- <dl>
- <dt><b><tt>BitsPerPixel <integer> (usually read-only)</tt></b>
- <dd>Number of bits per pixel.
- </dl>
- <dl>
- <dt><b><tt>.HWMargins [<four floats>]</tt></b>
- <dd>Size of non-imageable regions around the edges of the page, in points
- (units of 1/72in; see the <a href="Devices.htm#Measurements">notes on
- measurements</a> in the documentation on devices).
- </dl>
- <dl>
- <dt><b><tt>HWSize [<integer> <integer>]</tt></b>
- <dd>X and Y size in pixels.
- </dl>
- <dl>
- <dt><b><tt>Name <string> (read-only)</tt></b>
- <dd>The device name. Currently the same as <b><tt>OutputDevice</tt></b>.
- </dl>
- <dl>
- <dt><b><tt>Colors, GrayValues, RedValues, GreenValues, BlueValues, ColorValues (usually read-only)</tt></b>
- <dd>As for the <b><tt>deviceinfo</tt></b> operator of Display PostScript.
- <b><tt>Red</tt></b>, <b><tt>Green</tt></b>, <b><tt>Blue</tt></b>, and
- <b><tt>ColorValues</tt></b> are only defined if
- <b><tt>Colors</tt></b> > 1.
- </dl>
- <dl>
- <dt><b><tt>TextAlphaBits, GraphicsAlphaBits (usually read-only)</tt></b>
- <dd>The number of bits of anti-aliasing information for text or graphics
- respectively. Legal values are 1 (no anti-aliasing, the default for most
- devices), 2, or 4.
- </dl>
- <p>
- In addition, the following are defined per Adobe's documentation for the
- <b><tt>setpagedevice</tt></b> operator:
- <blockquote>
- <b><tt>Duplex</tt></b> (if supported)<br>
- <b><tt>HWResolution</tt></b><br>
- <b><tt>ImagingBBox</tt></b><br>
- <b><tt>Margins</tt></b><br>
- <b><tt>NumCopies</tt></b> (for printers only)<br>
- <b><tt>Orientation</tt></b> (if supported)<br>
- <b><tt>OutputDevice</tt></b><br>
- <b><tt>PageOffset</tt></b> (write-only)<br>
- <b><tt>PageSize</tt></b><br>
- <b><tt>ProcessColorModel</tt></b> (usually read-only)<br>
- </blockquote>
- <p>
- Some devices may only allow certain values for <b><tt>HWResolution</tt></b>
- and <b><tt>PageSize</tt></b>. The null device ignores attempts to set
- <b><tt>PageSize</tt></b>; its size is always <b><tt>[0 0]</tt></b>.
- <p>
- For printers these are also defined:
- <dl>
- <dt><b><tt>BufferSpace <integer></tt></b>
- <dd>Buffer space for band lists, if the bitmap is too big to fit in memory.
- </dl>
- <dl>
- <dt><b><tt>MaxBitmap <integer></tt></b>
- <dd>Maximum space for a full bitmap in memory.
- </dl>
- <dl>
- <dt><b><tt>OutputFile <string></tt></b>
- <dd>An empty string means "send to printer directly", otherwise specifies
- the file name for output; <b><tt>%d</tt></b> is replaced by the page number;
- on Unix systems <b><tt>%pipe%</tt></b><em>command</em> writes to a pipe.
- (<b><tt>|</tt></b><em>command</em> also writes to a pipe, but is now
- deprecated.)
- <p>
- Attempts to set this parameter if <tt><b>.LockSafetyParams</b></tt> is true
- will signal an <tt><b>invalidaccess</b></tt> error.
- </dl>
- <dl>
- <dt><b><tt>OpenOutputFile <boolean></tt></b>
- <dd>If true, open the device's output file when the device is opened,
- rather than waiting until the first page is ready to print.
- </dl>
- <dl>
- <dt><b><tt>PageCount <integer> (read-only)</tt></b>
- <dd>Counts the number of pages printed on the device.
- </dl>
- <p>
- The following parameters are for use only by very specialized applications
- that separate band construction from band rasterization. Improper use may
- cause unpredictable errors. In particular, if you only want to allocate
- more memory for banding, to increase band size and improve performance, use
- the <b><tt>BufferSpace</tt></b> parameter, not
- <b><tt>BandBufferSpace</tt></b>.
- <dl>
- <dt><b><tt>BandHeight <integer></tt></b>
- <dd>The height of bands when banding. 0 means use the largest band height
- that will fit within the BandBufferSpace (or BufferSpace, if
- BandBufferSpace is not specified).
- </dl>
- <dl>
- <dt><b><tt>BandWidth <integer></tt></b>
- <dd>The width of bands in the rasterizing pass, in pixels. 0 means use the
- actual page width.
- </dl>
- <dl>
- <dt><b><tt>BandBufferSpace <integer></tt></b>
- <dd>The size of the band buffer in the rasterizing pass, in bytes. 0 means
- use the same buffer size as for the interpretation pass.
- </dl>
- <p>
- Ghostscript supports the following parameter for
- <b><tt>setpagedevice</tt></b> and <b><tt>currentpagedevice</tt></b> that is
- not a device parameter per se:
- <dl>
- <dt><b><tt>ViewerPreProcess <procedure></tt></b>
- <dd>Specifies a procedure to be applied to the page device dictionary
- before any other processing is done. The procedure may not alter the
- dictionary, but it may return a modified copy. This "hook" is provided for
- use by viewing programs such as GSview.
- </dl>
- <hr>
- <h2><a name="User_parameters"></a>User parameters</h2>
- Ghostscript supports the following non-standard user parameters:
- <dl>
- <dt><b><tt>ProcessDSCComment <procedure|null></tt></b>
- <dd>If not null, this procedure is called whenever the scanner detects a DSC
- comment (comment beginning with <b><tt>%%</tt></b> or <b><tt>%!</tt></b>).
- There are two operands, the file and the comment (minus any terminating
- EOL), which the procedure must consume.
- </dl>
- <dl>
- <dt><b><tt>ProcessComment <procedure|null></tt></b>
- <dd>If not null, this procedure is called whenever the scanner detects a
- comment (or, if <b><tt>ProcessDSCComment</tt></b> is also not null, a
- comment other than a DSC comment). The operands are the same as for
- <b><tt>ProcessDSCComment</tt></b>.
- </dl>
- <dl>
- <dt><b><tt>LockFilePermissions <boolean></tt></b>
- <dd>If <tt>true</tt>, this parameter and the three <tt>PermitFile...</tt>
- parameters cannot be changed. Attempts to change any of the values
- when LockFilePermissions is <tt>true</tt> will signal <b><tt>invalidaccess</tt></b>.
- Also, when this value is <tt>true</tt>, the <b><tt>file</tt></b> operator
- will give <b><tt>invalidaccess</tt></b> when attempting to open files
- (processes) using the <b><tt>%pipe</tt></b> device.
- <p>
- Also when <b><tt>LockFilePermissions</tt></b> is <tt>true</tt>, strings
- cannot reference the parent directory (platform specific). For example
- <b><tt>(../../xyz)</tt></b> is illegal on unix, Windows
- and Macintosh, and <b><tt>([.#.#.XYZ])</tt></b> is illegal on VMS.
- <p>
- This parameter is set <tt>true</tt> by the <b><tt>.setsafe</tt></b> and
- <b><tt>.locksafe</tt></b> operators.
- </dl>
- <dl>
- <dt><b><tt>PermitFileReading <array of strings></tt></b>
- <dt><b><tt>PermitFileWriting <array of strings></tt></b>
- <dt><b><tt>PermitFileControl <array of strings></tt></b>
- <dd>These parameters specify paths where file reading, writing and the
- 'control' operations are permitted, respectively. File control
- operations are <b><tt>deletefile</tt></b> and <b><tt>renamefile</tt></b>.
- For <b><tt>renamefile</tt></b>, the filename for the current filename
- must match one of the paths on the PermitFileControl list, and the
- new filename must be on <b>both</b> the PermitFileControl and the
- PermitFileWriting lists of paths.
- <p>
- The strings can contain wildcard characters as for the <b><tt>filenameforall</tt></b>
- operator and unless specifying a single file, will end with a <b>*</b>
- for directories (folders) to allow access to all files and sub-directories
- in that directory.
- <p>
- <b>Note:</b> The strings are used for stringmatch operations similar
- to <b><tt>filenameforall</tt></b>, thus on MS Windows platforms, use the '/'
- character to separate directories and filenames or use '\\\\' to
- have the string contain '\\' which will match a single '\' in the
- target filename (use of '/' is strongly recommended).
- <p>
- The <a href=Use.htm#Safer><b>SAFER</b></a> mode and the
- <b><tt>.setsafe</tt></b> operator set all three lists to empty arrays,
- thus the only files that can be read are the <b><tt>%stdin</tt></b> device and
- on LIBPATH or FONTPATH or the Resource paths specified by the /FontResourceDir
- or /GenericResourceDir system params. Files cannot be opened for writing
- anywhere and cannot be deleted or renamed except for files created with the
- <a href=#Tempfile><b>.tempfile</b></a> operator).
- </dl>
- <hr>
- <h2><a name="Miscellaneous_additions"></a>Miscellaneous additions</h2>
- <b><tt>run</tt></b> can take either a string or a file as its argument. In
- the latter case, it just runs the file, closing it at the end, and trapping
- errors just as for the string case.
- <!-- [2.0 end contents] ==================================================== -->
- <!-- [3.0 begin visible trailer] =========================================== -->
- <hr>
- <p>
- <small>Copyright © 1996, 2000 Aladdin Enterprises. 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>
|