diff options
Diffstat (limited to 'doc/Language.htm')
| -rw-r--r-- | doc/Language.htm | 2293 |
1 files changed, 0 insertions, 2293 deletions
diff --git a/doc/Language.htm b/doc/Language.htm deleted file mode 100644 index 5f7f1077..00000000 --- a/doc/Language.htm +++ /dev/null @@ -1,2293 +0,0 @@ -<!doctype html> -<html lang="en"> -<head> - <meta http-equiv="content-type" content="text/html; charset=utf-8"> - <meta name="viewport" content="user-scalable=yes, initial-scale=1, width=device-width"> - <link href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:200,200i,300,300i,400,400i,600,600i,700,700i,900,900i" rel="stylesheet"> - <link rel="shortcut icon" href="images/favicon.svg"> - <title>Ghostscript and the PostScript Language</title> - <link href="default.css" rel="stylesheet" type="text/css"> -</head> - -<body> - <header><div class="title"><a href="index.html"><h1 aria-label="title">Ghostscript documentation</h1><h2 aria-label="version"></h2></a></div><a href="Search.htm" aria-label="Search" id="searchSite"><div class="search"></div></a></header> - <main> - <article> - <div class="outer"> - - <div class="inner"> -<!--START EDITING HERE--> - -<h1>Ghostscript and the PostScript Language</h1> - -<h2><a name="toc"></a>Table of contents</h2> -<ul class="toc"> - - <li><a href="#Capabilities">Ghostscript's capabilities in relation to PostScript</a></li> - <li><a href="#Implementation_limits">Implementation limits</a></li> - <li> - <ul> - <li><a href="#Architectural_limits">Architectural limits</a></li> - <li><a href="#Typical_memory_limits">Typical memory limits in LanguageLevel 1</a></li> - <li><a href="#VM_consumption">Other differences in VM consumption</a></li> - </ul> - </li> - <li><a href="#Additional_operators">Additional operators in Ghostscript</a></li> - <li> - <ul> - <li><a href="#Graphics_and_text">Graphics and text operators</a></li> - <li> - <ul> - <li><a href="#Transparency">Transparency</a></li> - <li> - <ul> - <li><a href="#Transparency_graphics_state_operators">Graphics state operators</a></li> - <li><a href="#Transparency_rendering_stack_operators">Rendering stack operators</a></li> - <li><a href="#Transparency_ImageType">New ImageType</a></li> - </ul> - </li> - <li><a href="#Graphics_state">Other graphics state operators</a></li> - <li><a href="#Character">Character operators</a></li> - </ul> - </li> - - <li><a href="#Other">Other operators</a></li> - <li> - <ul> - <li><a href="#Mathematical">Mathematical operators</a></li> - <li><a href="#Dictionary">Dictionary operators</a></li> - <li><a href="#Relational">Relational operators</a></li> - <li><a href="#File">File operators</a></li> - <li><a href="#Miscellaneous">Miscellaneous operators</a></li> - <li><a href="#Device">Device operators</a></li> - </ul> - </li> - </ul> - </li> - <li><a href="#Filters">Filters</a></li> - <li> - <ul> - <li><a href="#Standard_filters">Standard filters</a></li> - <li><a href="#Non_standard_filters">Non-standard filters</a></li> - <li><a href="#Unstable_filters">Unstable filters</a></li> - </ul> - </li> - <li><a href="#Device_parameters">Device parameters</a></li> - <li><a href="#Banding_parameters">Banding parameters</a></li> - <li><a href="#User_parameters">User parameters</a></li> - <li><a href="#Miscellaneous_additions">Miscellaneous additions</a></li> - <li> - <ul> - <li><a href="#Extended_semantics_of_run">Extended semantics of 'run'</a></li> - <li><a href="#DecodingResources">Decoding resources</a></li> - <li><a href="#CIDDecodingResources">CIDDecoding resources</a></li> - <li><a href="#GlyphNames2Unicode">GlyphNames2Unicode</a></li> - <li><a href="#MultipleResourceDirectories">Multiple Resource directories</a></li> - </ul> - </li> - <li><a href="#PDF_scripting">Scripting the PDF interpreter</a></li> - <li> - <ul> - <li><a href="#PS_functions">PostScript functions</a></li> - <li><a href="#PDF_PS_operators">PostScript operators</a></li> - </ul> - </li> -</ul> - -<!-- [1.2 end table of contents] =========================================== --> - -<!-- [1.3 begin hint] ====================================================== --> - -<p>For other information, see the <a href="Readme.htm">Ghostscript -overview</a>.</p> - -<!-- [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 -"<code>status</code>" 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:</p> - -<ul> -<li>The ability to process PostScript Type 1 fonts. This facility is -normally included in the interpreter.</li> - -<li>The CMYK color extensions listed in section A.1.4 of the Second Edition -(including <code>colorimage</code>). These facilities are available -only if the <code>color</code>, <code>dps</code>, or -<code>level2</code> feature was selected when Ghostscript was built.</li> - -<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 <code>dps</code> feature or the -<code>level2</code> feature was selected when Ghostscript was built.</li> - -<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 <code>compfont</code> feature or the -<code>level2</code> feature was selected when Ghostscript was built.</li> - -<li>The ability to load TrueType fonts and to handle PostScript Type 42 -(encapsulated TrueType) fonts. These facilities are available only if the -<code>ttfont</code> feature was selected when Ghostscript was built.</li> - -<li>The PostScript Level 2 "filter" facilities except the -<code>DCTEncode</code> and <code>DCTDecode</code> filters. These -facilities are available only if the <code>filter</code>, -<code>dps</code>, or <code>level2</code> feature was selected when -Ghostscript was built.</li> - -<li>The PostScript Level 2 <code>DCTEncode</code> and -<code>DCTDecode</code> filters. These facilities are available only if -the <code>dct</code> or <code>level2</code> feature was selected when -Ghostscript was built.</li> - -<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 -<code>level2</code> feature was selected when Ghostscript was built.</li> - -<li>All PostScript LanguageLevel 3 operators and facilities listed in the -Third Edition, except as noted below. These facilities are available only -if the <code>psl3</code> feature was selected when Ghostscript was built.</li> - -<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 <code>epsf</code> feature was selected when -Ghostscript was built.</li> -</ul> - -<p> -Ghostscript currently does not implement the following PostScript -LanguageLevel 3 facilities:</p> - -<ul> -<li>Settable <code>ProcessColorModel</code> for page devices, except for -a very few special devices.</li> - -<li><code>IODevice</code>s other than <code>%stdin</code>, -<code>%stdout</code>, <code>%stderr</code>, <code>%lineedit</code>, -<code>%statementedit</code>, <code>%os%</code>, and (if configured) -<code>%pipe%</code> and <code>%disk0%</code> through <code>%disk0%</code>.</li> -</ul> - -<p> -Ghostscript can also interpret files in the Portable Document Format (PDF) -1.7 format defined in the -<a href="http://www.adobe.com/devnet/pdf/pdf_reference.html"><em>PDF -Reference</em> Version 1.7</a>, -distributed by <a href="http://www.adobe.com/">Adobe Systems -Incorporated</a>, except as noted below. This facility can be -disabled by deselecting the <code>pdf</code> feature -when Ghostscript is built.</p> - -<p> -Ghostscript currently implements the majority of non-interactive -features defined in the PDF reference.</p> - -<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.</p> - -<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.</p> - -<h3><a name="Architectural_limits"></a>Architectural limits</h3> - -<blockquote><table> -<tr><th colspan="4">Architectural limits (corresponds to Adobe table B.1)</th></tr> -<tr valign="bottom"> - <th align="left">Quantity</th> - - <th align="left">Limit</th> - - <th align="left">Type</th> - - <th align="left">Adobe</th></tr> -<tr valign="top"> <td>integer</td> - - <td>32-bit</td> - - <td>twos complement integer</td> - - <td> </td></tr> -<tr valign="top"> <td>real</td> - - <td>single-precision</td> - - <td>IEEE float</td> - - <td> </td></tr> -<tr valign="top"> <td>array</td> - - <td>16777216</td> - - <td>elements</td> - - <td>65535</td></tr> -<tr valign="top"> <td>dictionary</td> - - <td>16777215</td> - - <td>elements</td> - - <td>65535</td></tr> -<tr valign="top"> <td>string</td> - - <td>16777216</td> - - <td>characters</td> - - <td>65535</td></tr> -<tr valign="top"> <td>name</td> - - <td>16383</td> - - <td>characters</td> - - <td>127</td></tr> -<tr valign="top"> <td>filename</td> - - <td>128*</td> - - <td>characters</td> - - <td> </td></tr> -<tr valign="top"> <td><code>save</code> level</td> - - <td>none</td> - - <td>(capacity of memory)</td> - - <td>15</td></tr> -<tr valign="top"> <td><code>gsave</code> level</td> - - <td>none</td> - - <td>(capacity of memory)</td> - - <td>13</td></tr> -</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.</p> - -<h3><a name="Typical_memory_limits"></a>Typical memory limits in LanguageLevel 1</h3> - -<blockquote><table> - -<tr><th colspan="4">Memory limits (corresponds to Adobe table B.2)</th></tr> -<tr valign="bottom"> - <th align="left">Quantity</th> - - <th align="left">Limit</th> - - <th align="left">Type</th> - - <th align="left">Adobe</th></tr> -<tr valign="top"> <td><code>userdict</code></td> - - <td>200</td> - - <td> </td> - - <td> </td></tr> -<tr valign="top"> <td><code>FontDirectory</code></td> - - <td>100</td> - <td> </td> - - <td> </td> - </tr> -<tr valign="top"> <td>operand stack</td> - - <td>800</td> - - <td> </td> - - <td>500</td></tr> -<tr valign="top"> <td>dictionary stack</td> - - <td>20</td> - <td> </td> - - <td> </td> - </tr> -<tr valign="top"> <td>execution stack</td> - - <td>250</td> - - <td> </td><td> </td></tr> -<tr valign="top"> <td>interpreter level</td> - - <td>none</td> - - <td>(capacity of memory)</td> - - <td>10</td></tr> -<tr valign="top"> <td>path</td> - - <td>none</td> - - <td>(capacity of memory)</td> - - <td>1500</td></tr> -<tr valign="top"> <td>dash</td> - - <td>11</td> - <td> </td> - - - <td> </td></tr> -<tr valign="top"> <td>VM</td> - - <td>none</td> - - <td>(capacity of memory)</td> - - <td>240000</td></tr> -<tr valign="top"> <td>file</td> - - <td>none</td> - - <td>(determined by operating system)</td> - - <td>6</td></tr> -<tr valign="top"> <td>image</td> - - <td>65535</td> - - <td>values (samples × components)<br>for 1-, 2-, 4-, or 8-bit samples</td> - - <td>3300</td></tr> -<tr valign="top"> <td> </td> - - <td>32767</td> - - <td>values for 12-bit samples</td> - - <td>3300</td></tr> -</table></blockquote> - -<h3><a name="VM_consumption"></a>Other differences in VM consumption</h3> - -<p> -In 32-bit builds packed array elements occupy either 2 bytes or 12 bytes. -The average element size is probably about 7 bytes. Names occupy 16 bytes plus the -space for the string.</p> -<p> -In 64-bit builds packed array elements occupy either 2 bytes or 16 bytes. -The average element size is probably about 9 bytes. -Names occupy 24 bytes plus the space for the string.</p> -<p> -The garbage collector doesn't reclaim portions of arrays obtained with -<tt>getinterval</tt>, rather it collects entire arrays.</p> -<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><u><a name="Transparency"></a>Transparency</u></h4> -<p><b><u>NOTE:</u></b> The following paragraphs describe non-standard operators -for accessing the PDF 1.4 and later transparent imaging model through Postscript. -If used incorrectly, they can have unexpected side effects and result in undefined -behavior. As a result, these operators are disabled when <a href="Use.htm#Safer"><b>SAFER</b></a> -is in force (as it is by default from version 9.50 onwards). To utilise these operators -you will either have to disable <code>SAFER</code> (<code>-dNOSAFER</code>) or use -the command line parameter <code>-dALLOWPSTRANSPARENCY</code>. The latter will make -the custom operators available, but leave the file access controls active. -<p> -Ghostscript provides a set of operators for implementing the transparency -and compositing facilities of PDF 1.4. These are defined only if the -<code>transpar</code> 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>". Previously (in 9.52 and earlier), Ghostscript's model -maintained separate alpha and mask values for opacity and shape. This -model has been changed (as of 9.53) and instead Ghostscript maintains separate -float values for stroke and fill alpha values with a boolean that indicates -if these should be interpreted as shape or alpha values to be more in line with the -PDF specification. -</p> -<p> -What follows is a subset of all the custom operators related to transparency, but -covers the most useful, most common requirements. -</p> - -<h5><a name="Transparency_graphics_state_operators"></a>Graphics state -operators</h5> - -<p>Pushing the compositor device must be done before any other marking -operations are made on the current page, and must be done per page. -Popping the compositor should be done after the last marking operation -of the page, and before the call to <code>showpage</code>. Any marking -operations made after the compositor is popped will bypass the transparent -imaging model, and may produce unexpected output. - -<dl> -<dt><code><depth> .pushpdf14devicefilter -</code></dt> -<dd>Installs the transparency compositor device into the graphics state. At -present the <code>depth</code> parameter should always be zero (<b>Subject -To Change.</b>) -</dl> -<dl> -<dt><code>- .popdf14devicefilter -</code></dt> -<dd>Removes (or, more accuracately, disables) the transparency compositor in -graphics state. -</dl> - - -<dl> -<dt><code><modename> .setblendmode -</code></dt> -<dd>Sets the blending mode in the graphics state. If the mode name is not -recognized, causes a <code>rangecheck</code> error. The initial value of -the blending mode is <code>/Compatible</code>.</dd> -</dl> - -<dl> -<dt><code>- .currentblendmode <modename></code></dt> -<dd>Returns the graphics state blend mode on the stack. -</dl> - -<dl> -<dt><code>[Deprecated as of 9.53] <0..1> .setopacityalpha -</code></dt> -<dd>Sets the opacity alpha value in the graphics state. -The initial opacity alpha value is 1. Note, it is strongly -suggested that this method not be used as it currently may -give inconsistent results when mixed with methods that -set stroke and fill alpha values. </dd> -</dl> - -<dl> -<dt><code>[Deprecated as of 9.53] - .currentopacityalpha <0..1></code></dt> -<dd>Returns the graphics state opacity alpha on the stack. Note, it is strongly -suggested that this method not be used as it currently may -give inconsistent results when mixed with methods that -set stroke and fill alpha values.</dd> -</dl> - -<dl> -<dt><code>[Deprecated as of 9.53] <0..1> .setshapealpha -</code></dt> -<dd>Sets the shape alpha value in the graphics state. -The initial shape alpha value is 1. Note, it is strongly -suggested that this method not be used as it currently may -give inconsistent results when mixed with methods that -set stroke and fill alpha values.</dd> -</dl> - -<dl> -<dt><code>[Deprecated as of 9.53] - .currentshapealpha <0..1></code></dt> -<dd>Returns the graphics state shape alpha on the stack. Note, it is strongly -suggested that this method not be used as it currently may -give inconsistent results when mixed with methods that -set stroke and fill alpha values.</dd> -</dl> - -<dl> -<dt><code><0..1> .setstrokeconstantalpha -</code></dt> -<dd>Sets the stroke alpha value in the graphics state. -The initial stroke alpha value is 1.</dd> -</dl> - -<dl> -<dt><code> - .currentstrokeconstantalpha <0..1></code></dt> -<dd>Returns the graphics state stroke alpha value on the stack.</dd> -</dl> - -<dl> -<dt><code><0..1> .setfillconstantalpha -</code></dt> -<dd>Sets the fill alpha value in the graphics state. -The initial fill alpha value is 1.</dd> -</dl> - -<dl> -<dt><code> - .currentfillconstantalpha <0..1></code></dt> -<dd>Returns the graphics state fill alpha value on the stack.</dd> -</dl> - -<dl> -<dt><code><bool> .setalphaisshape -</code></dt> -<dd>If true, the values set by setstrokeconstantalpha and setfillconstantalpha are interpreted as shape values. -The initial value of the AIS flag is <code>false</code>.</dd> -</dl> - -<dl> -<dt><code> - .currentalphaisshape <0..1></code></dt> -<dd>Returns the graphics state alpha is shape (AIS) on the stack.</dd> -</dl> - -<dl> -<dt><code><bool> .settextknockout -</code></dt> -<dd>Sets the text knockout flag in the graphics state. -The initial value of the text knockout flag is <code>true</code>.</dd> -</dl> - -<dl> -<dt><code>- .currenttextknockout <bool></code></dt> -<dd>Returns the graphics state text knockout on the stack..</dd> -</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> - -<p> -Beginning and ending groups must nest properly with respect to -<code>save</code> and <code>restore</code>: <code>save</code> and -<code>restore</code> do not save and restore the layer stack. Currently, -layers are not required to nest with respect to <code>gsave</code> and -<code>grestore</code>, 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.</p> - -<dl> -<dt><code><paramdict> <llx> <lly> <urx> <ury> -.begintransparencygroup -</code></dt> -<dd>Begins a new transparency group. The <code>ll/ur</code> coordinates -are the bounding box of the group in the current user coordinate system. -<code>paramdict</code> has the following keys:</dd> - -<dt><code>/Isolated</code></dt> -<dd>(optional) Boolean; default value = <code>false</code>.</dd> -<dt><code>/Knockout</code></dt> -<dd>(optional) Boolean; default value = <code>false</code>.</dd> - -</dl> - -<dl> -<dt><code>- .endtransparencygroup -</code></dt> -<dd>Ends the current transparency group, compositing the group being ended -onto the group that now becomes current.</dd> -</dl> - -<dl> -<dt><code><cs_set?> <paramdict> <llx> <lly> <urx> <ury> -.begintransparencymaskgroup -</code></dt> -<dd>Begins a new transparency mask, which is represented as a group. -The <code>ll/ur</code> coordinates -are the bounding box of the mask in the current user coordinate system. -<code>paramdict</code> has the following keys:</dd> - -<dt><code>/Subtype</code></dt> -<dd>(required) Name, either <code>/Alpha</code> or -<code>/Luminosity</code>.</dd> -<dt><code>/Background</code></dt> -<dd>(optional) Array of number.</dd> -<dt><code>/TransferFunction</code></dt> -<dd>(optional) Function object (produced by applying -<code>.buildfunction</code> to a Function dictionary). -<p> -The <code>cs_set</code> parameter is a boolean indicating whether the color -space for the mask group is the current color space in the graphics state, or -whether mask group color space should be inherited from the previous group -in the transparency group stack. In general, for the most consistent results, -it is recommended that this be set to <code>true</code>, and the intended -color space set in the graphics state prior to the <code>.begintransparencymaskgroup</code> -call.</p> -</dd> -</dl> - -<dl> -<dt><code><mask#> .endtransparencymask -</code></dt> -<dd>Ends the current transparency mask group, compositing the mask group being ended -and setting it as the current soft mask in the graphics state. -<p> -The <code>mask#</code> parameter indicates whether the mask should be treated as -as opacity mask (<code>0</code>) or shape (<code>1</code>). -</dd> -</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:</p> - -<ul> - -<li>The required <code>MaskDict</code> is replaced by two optional -dictionaries, <code>OpacityMaskDict</code> and -<code>ShapeMaskDict</code>. If present, these dictionaries must have a -<code>BitsPerComponent</code> 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> - -<li>A <code>Matte</code> entry may be present in one or both mask -dictionaries, indicating premultiplication of the data values. If both -<code>MaskDict</code>s have a <code>Matte</code> entry and the values -of the two <code>Matte</code> entries are different, a -<code>rangecheck</code> error occurs.</li> - -<li><code>InterleaveType</code> appears in the <code>MaskDict</code>s, -not the <code>DataDict</code>, because each mask has its own -<code>InterleaveType</code>. <code>InterleaveType</code> 2 -(interlaced scan lines) is not supported.</li> - -</ul> - -<h4><a name="Graphics_state"></a>Other graphics state operators</h4> - - <dl> -<dt><code><int> .setoverprintmode -</code></dt> -<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 <code>DeviceCMYK</code>, 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.</dd> -</dl> - -<dl> -<dt><code>- .currentoverprintmode <int></code></dt> -<dd>Returns the current overprint mode.</dd> -</dl> - -<h4><a name="Character"></a>Character operators</h4> - -<dl> -<dt><code><font> <charcode> %Type1BuildChar -</code></dt> -<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 ...<code>show</code>, <code>stringwidth</code>, or -<code>charpath</code>), it looks up the name <code>BuildChar</code> -in the font dictionary to find a procedure to run. If it does not find -this name, and if the <code>FontType</code> is 1, the interpreter -instead uses the value (looked up on the dictionary stack in the usual way) -of the name <code>%Type1BuildChar</code>. - -<p> -The standard definition of <code>%Type1BuildChar</code> is in the -initialization file <code>gs_type1.ps</code>. Users should not need to -redefine <code>%Type1BuildChar</code>, except perhaps for tracing or -debugging.</p> -</dd> -</dl> - -<dl> -<dt><code><font> <charname> %Type1BuildGlyph -</code></dt> -<dd>Provides the Type 1 implementation of <code>BuildGlyph</code>.</dd> -</dl> - -<h3><a name="Other"></a>Other operators</h3> - -<h4><a name="Mathematical"></a>Mathematical operators</h4> - -<dl> -<dt><code><number> arccos <number></code></dt> -<dd>Computes the arc cosine of a number between -1 and 1.</dd> -</dl> - -<dl> -<dt><code><number> arcsin <number></code></dt> -<dd>Computes the arc sine of a number between -1 and 1.</dd> -</dl> - -<h4><a name="Dictionary"></a>Dictionary operators</h4> - -<dl> -<dt><code>mark <key1> <value1> <key2> <value2> ... .dicttomark <dict></code></dt> -<dd>Creates and returns a dictionary with the given keys and values. This -is the same as the PostScript Level 2 <code>>></code> operator, -but is available even in Level 1 configurations.</dd> -</dl> - -<dl> -<dt><code><dict> <key> .knownget <value> true</code></dt> -<dt><code><dict> <key> .knownget false</code></dt> -<dd>Combines <code>known</code> and <code>get</code> in the -obvious way.</dd> -</dl> - - -<h4><a name="Relational"></a>Relational operators</h4> - -<dl> -<dt><code><number|string> <number|string> max <number|string></code></dt> -<dd>Returns the larger of two numbers or strings.</dd> -</dl> - -<dl> -<dt><code><number|string> <number|string> min <number|string></code></dt> -<dd>Returns the smaller of two numbers or strings.</dd> -</dl> - -<h4><a name="File"></a>File operators</h4> - -<dl> -<dt><code><file> .fileposition <integer> true</code></dt> -<dd>Returns the position of <code>file</code>. Unlike the standard -<code>fileposition</code> operator, which causes an error if the file is -not positionable, <code>.fileposition</code> 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.</dd> -</dl> - -<dl> -<dt><code><string> findlibfile <foundstring> <file> true</code></dt> -<dt><code><string> findlibfile <string> false</code></dt> -<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, <code>findlibfile</code> simply -pushes false on the stack and returns, rather than causing an error.</dd> -</dl> - -<a name="Tempfile"></a> -<dl> -<dt><code><prefix_string|null> <access_string> .tempfile -<string> <file></code></dt> -<dd>Creates and opens a temporary file -like the <code>file</code> operator, also returning the file name. There -are three cases for the <code><prefix_string|null></code> operand: - -<ul> -<li><code>null</code>: 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 -<code>/tmp/gs_a1234</code>.</li> -<li>A string that contains only alphanumeric characters, underline, -and dash: create the file in the standard temporary directory, but use -the -<code><prefix_string></code> as the first part of the file name. -E.g., if <code><prefix_string></code> is <code>xx</code>, the -temporary file might be named <code>/tmp/xxa1234</code>.</li> -<li>A string that is the beginning of an absolute file name: use the -<code><prefix_string></code> as the first part of the file name. -E.g., if <code><prefix_string></code> is -<code>/my/tmpdir/zz</code>, the temporary file might be named -<code>/my/tmpdir/zza1234</code>. -<p> - -When running in <code>SAFER</code> mode, the absolute path must -be one of the strings on the permit file writing list -(see <a href="Use.htm#Safer"><b>-dSAFER</b></a>) .</p></li> -</ul> -</dd> -</dl> - -<p> -Ghostscript also supports the following <code>IODevice</code> in -addition to a subset of those defined in the Adobe documentation:</p> -<ul> - <li> - <code>%pipe%command</code>, which opens a pipe on the given command. - This is supported only on operating systems that provide - <code>popen</code> (primarily Unix systems, and not all of those).</li> - <li> - <code>%disk#%</code>, which emulates the %disk0 - through %disk9 devices on some Adobe PostScript printers. This pseudo - device provides a flat filenaming system with a user definable location - for the files (/Root). These devices will only be present if the - diskn.dev feature is specified during the build. - - <p>This feature is intended to allow compatibility with font downloaders - that expect to store fonts on the %disk device of the printer.</p> - <p> - Use of the %disk#% devices requires that the location of files be given - by the user setting the /Root device parameter. The syntax for setting - the /Root parameter is:<pre> - mark /Root (directory_specification) (%disk#) .putdevparams - </pre> - For example, to store the files of the %disk0 device on the directory - /tmp/disk0, use:<pre> - mark /Root (/tmp/disk0/) (%disk0) .putdevparams - </pre></p> - <p>The files will be stored in the specified directory with arbitrary names. - A mapping file is used to store the association between the file - names given for the file operations on the %diskn# device and the file - that resides in the /Root directory.</p> - </li> -</ul> - -<h4><a name="Miscellaneous"></a>Miscellaneous operators</h4> - -<dl> -<dt><code><array> bind <array></code></dt> -<dd>Depending on the command line parameters <code>bind</code> is redefined as:</dd> -</dl> - -<blockquote><table> -<tr valign="bottom"> - <th valign="bottom" align="left">Flag</th> - - <th valign="bottom" align="left">Definition</th></tr> -<tr valign="top"> <td>DELAYBIND</td> - - <td>returns the argument, stores the argument for later use by <code>.bindnow</code></td></tr> -</table></blockquote> - - -<dl> -<dt><code><array> .bind <array></code></dt> -<dd>Performs standard <code>bind</code> operation as defined in PLRM regardless of -the DELAYBIND flag.</dd> -</dl> - -<a name="bindnow"></a> -<dl> -<dt><code>- .bindnow -</code></dt> -<dd>Applies <code>bind</code> operator to all saved procedures after binding has been -deferred through -dDELAYBIND. Note that idiom recognition has no effect for the deferred -binding because the value returned from <code>bind</code> is discarded. -<p> -Since v. 8.12 <code>.bindnow</code> undefines itself and restores standard definition of -<code>bind</code> operator. In earlier versions after calling <code>.bindnow</code>, -the postscript <code>bind</code> operator needs to be rebound to the internal implementation -<code>.bind</code>, as in this fragment from the ps2ascii script: -<blockquote><pre><tt>DELAYBIND { - .bindnow - /bind /.bind load def -} if -</tt></pre></blockquote> -This is necessary for correct behavior with later code that uses the <code>bind</code> operator.</p> -</dd> -</dl> - -<dl> -<dt><code><string> getenv <string> true</code></dt> -<dt><code><string> getenv false</code></dt> -<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.</dd> -</dl> - -<dl> -<dt><code><string> <boolean> .setdebug -</code></dt> -<dd>Sets or clears any subset of the debugging flags included in -<code><string></code> based on the value of -<code><boolean></code>. These correspond to the debug -flags set by <code>-Z</code> on the command line and enable -debug and tracing output from various internal modules. - -<p>Note that most tracing output is only produced if the Ghostscript -interpreter was built with the <code>DEBUG</code> preprocessor -symbol defined.</p> - -<p>The <code>zsetdebug()</code> C function, which implements this -operator, is a useful breakpoint for debuggers. -Inserting '<code>() true .setdebug</code>' in the interpreted code will -trigger a breakpoint at that location without side effects. The -current flag state is available in C as the <code>gs_debug[]</code> -array, indexed by character value. The <code>zsetdebug</code> function will -be entered, and <code>gs_debug[]</code> updated, whether or not Ghostscript -is built with the <code>DEBUG</code> preprocessor symbol defined, so this -is useful even with release builds.</p> -</dd> -</dl> - -<dl> -<dt><code>- .setsafe -</code></dt> -<dd>If Ghostscript is started with <code>-dNOSAFER</code> or -<code>-dDELAYSAFER</code>, this operator can be used to enter <b>SAFER</b> -mode (see <a href="Use.htm#Safer"><b>-dSAFER</b></a>) -<p> -<strong>The following is deprecated, see <a href="Use.htm#Safer"><b>-dSAFER</b></a></strong> -<p> -Since <b>SAFER</b> mode is implemented with userparameters and device parameters, -it is possible to use <code>save</code> and <code>restore</code> before -and after <code>.setsafe</code> to return to <b>NOSAFER</b> mode, but note -that such a save object is accessible to any procedures or file run in <b>SAFER</b> mode. -A malicious file with an unbalanced restore could potentially restore back to a point where -SAFER was not in operation.</p> -<p> -<b>Note: This uses setpagedevice to change .LockSafetyParams, so the page -will be erased as a side effect of this operator</b></p> -</dd> -</dl> - -<dl> -<dt><code>- .locksafe -</code></dt> -<dd> -<p> -<strong>The following is deprecated, see <a href="Use.htm#Safer"><b>-dSAFER</b></a></strong> -<p> -This operator sets the current device's <code>.LockSafetyParams</code> -and the <code>LockFilePermissions</code> userparameter 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 <code>-dNOSAFER</code> or -<code>-dDELAYSAFER</code>, this operator can be used to enter <b>SAFER</b> -mode with the current set of <code>PermitFile...</code> user parameters -in effect. Since <code>.setsafe</code> sets the <code>PermitFile...</code> -user parameters to empty arrays, a script or job server that needs to -enable certain paths for file Reading, Writing and/or Control can use this -operator to perform the locking needed to enter <b>SAFER</b> mode.</p> -<p> -For example, to enable reading everywhere, but disallow writing and file -control (deleting and renaming files), the following can be used:</p> -<pre> - { << /PermitFileReading [ (*) ] - /PermitFileWriting [ ] - /PermitFileControl [ ] - >> setuserparams - .locksafe - } stopped pop -</pre> -<p>In the above example, use of stopped will allow the use of this sequence on -older versions of Ghostscript where <code>.locksafe</code> was not an operator.</p> -<p> -<b>Note: This uses setpagedevice to change .LockSafetyParams, so the page -will be erased as a side effect of this operator</b></p> -<p> -See also <a href="#LockSafetyParams">.LockSafetyParams</a> and -<a href="#User_parameters">User Parameters</a>.</p> -</dd> -</dl> - -<dl> -<dt><a name=".addcontrolpath"></a> -<code><name> <string> .addcontrolpath</code></dt> -<dd> -Adds a single path to the file access control lists. -<p>The <name> parameter can be one of: -<ul> -<li> -<p><code>/PermitFileReading</code> -</li> -<li> -<p><code>/PermitFileWriting</code> -</li> -<li> -<p><code>/PermitFileControl</code> -</li> -</ul> -<p>Whilst the string parameter is the path to be added to the requested list. -<p><strong>NOTE: Any attempt to call this operator after <a href="#activatepathcontrol">.activatepathcontrol</a> -has been called will result in a <code>Fatal</code> error, and the interpreter -will immediately exit.</strong> -</dd> -</dl> - -<dl> -<dt><a name=".activatepathcontrol"></a> -<code>.activatepathcontrol</code></dt> -<dd> -Activates file access controls. Once activated, these access controls remain -in place until the interpreter shuts down. -</dd> -</dl> - -<dl> -<dt><a name=".currentpathcontrolstate"></a> -<code>.currentpathcontrolstate</code></dt> -<dd> -Returns <code>true</code> on the operand stack if file access control has been -activated, <code>false</code> if not. -</dd> -</dl> - -<dl> -<dt><a name=".genordered"></a> -<code><dict> .genordered <dict></code> (default: /OutputType /Type3).</dt> -<dt><code><dict> .genordered <string></code> (/OutputType /ThreshString).</dt> -<dt><code><dict> .genordered <array></code> (/OutputType /TOSArray).</dt> -<dd>This operator creates an ordered dither screening pattern with the parameters from the dictionary, returning (by default) a PostScript HalftoneType 3 (threshold array based) dictionary suitable for use with <code>sethalftone</code> or as a component Halftone of a <code>HalftoneType 5</code> Halftone dictionary. The /OutputType parameter can also select other than Halftone Type 3 as the return paramter, -<code><dict></code> has the following keys (all are optional):</dd> -<dt><code>/Frequency</code></dt> -<dd>Integer; default value = 75</dd> -<dt><code>/Angle</code></dt> -<dd>Integer; default value = 0</dd> -<dt><code>/HResolution</code></dt> -<dd>Real or Integer; default value is device X resolution.</dd> -<dt><code>/VResolution</code></dt> -<dd>Real or Integer; default value is device Y resolution.</dd> -<dt><code>/DotShape</code></dt> -<dd>Integer; default value = 0 (CIRCLE). Other shapes available are:</dd> -<dd> 1=REDBOOK, 2=INVERTED, 3=RHOMBOID, 4=LINE_X, 5=LINE_Y, 6=DIAMOND1, 7=DIAMOND2, 8=ROUNDSPOT,</dd> -<dt><code>/SuperCellSize</code></dt> -<dd>Integer; default value = 1 -- actual cell size determined by Frequency, Angle, H/V Resolution.</dd> -<dd>A larger value will allow more levels to be attained.</dd> -<dt><code>/Levels</code></dt> -<dd>Integer; default value = 1 -- actual number of gray levels is determined by Frequency and H/V Resolution.</dd> -<dd>SuperCellSize may need to be specified large enough to achieve the requested number of gray levels.</dd> -<dt><code>/OutputType</code></dt> -<dd>Name; default value = /Type3 (HalftoneType 3 dictionary). Other shapes available are:</dd> -<dt><code>/ThreshString</code></dt> -<dd> -First two bytes are width (high byte first), next two bytes are height, followed by the -threshold array bytes (same as /Thresholds of the Type3 dictionary). -</dd> -<dt><code>/TOSArray</code></dt> -<dd> -First element is the width, next is the height, followed by pairs X, then Y, of the turn-on-sequence of the threshold array. This information can be used to construct a threshold array with a transfer function "pickled into" the threshold array, which is useful if the turn-on-sequence has more than 256 pairs. Refer to toolbin/halftone/thresh_remap for more information.</dt> -</dd> -</dl> - -<dl> -<dt><a name=".shellarguments"></a> -<code>.shellarguments</code></dt> -<dd> -<p>This operator is used to access the ARGUMENTS command line option. -<p>Relies on Ghostscript being called with the "--" command -line option - see <a href="Use.htm#Input_control">Input Control</a> -<p>See examples in lib for more information. -</dd> -</dl> - - -<h4><a name="Device"></a>Device operators</h4> - -<dl> -<dt><code><device> copydevice <device></code></dt> -<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.</dd> -</dl> - -<dl> -<dt><code><devicename> finddevice <device></code></dt> -<dd>Creates a default instance of a device specified by name. The instance -is created in global VM. If <code>finddevice</code> is called more than -once with the same device name, it creates the default instance the first -time, and returns the same instance thereafter.</dd> -</dl> - -<dl> -<dt><code><devicename> findprotodevice <device></code></dt> -<dd>Finds the prototype of a device specified by name. A prototype can be -used with <code>getdeviceprops</code> or other parameter-reading -operators, but it is read-only and cannot be set with -<code>setdevice</code>: it must be copied first.</dd> -</dl> - -<dl> -<dt><code><matrix> <width> <height> <palette> makeimagedevice <device></code></dt> -<dd>Makes a new device that accumulates an image in memory. <code> -matrix</code> is the initial transformation matrix: it must be orthogonal -(that is, [a 0 0 b x y] or -[0 a b 0 x y]). <code>palette</code> 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 -<code><ff 00></code>; 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 <code><000000 0000ff -00ff00 00ffff ff0000 ff00ff ffff00 ffffff></code>. 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:</p> - -<blockquote><table> -<tr valign="bottom"> - <th valign="bottom" align="left">Palette</th> - - <th valign="bottom" align="left">Bits allocated per color</th></tr> -<tr valign="top"> <td>16</td> - - <td>5 red, 6 green, 5 blue</td></tr> -<tr valign="top"> <td>24</td> - - <td>8 red, 8 green, 8 blue</td></tr> -<tr valign="top"> <td>32</td> - - <td>8C, 8M, 8Y, 8K</td></tr> -</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 -<code>copydevice</code> operator.</p> -</dd> -</dl> - -<dl> -<dt><code><device> <index> <string> copyscanlines <substring></code></dt> -<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 <code>image</code> 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.</dd> -</dl> - -<dl> -<dt><code><device> setdevice -</code></dt> -<dd> -<p> -Sets the current device to the specified device. Also resets the -transformation and clipping path to the initial values for the device. -Signals an <code>invalidaccess</code> error if the device is a -prototype or if <a href="Language.htm#LockSafetyParams">.LockSafetyParams</a> -is true for the current device.</p> -<p> -Some device properties may need to be set with <tt>putdeviceprops</tt> before -<code>setdevice</code> is called. For example, the pdfwrite device will try -to open its output file, causing an <tt>undefinedfilename</tt> error if -<code>OutputFile</code> hasn't been set to a valid filename. Another -method in such cases is to use the level 2 operator instead: - - <code><< /OutputDevice /pdfwrite /OutputFile -(MyPDF.pdf) >> setpagedevice</code>.</p></dd> - -</dl> - -<dl> -<dt><code>- currentdevice <device></code></dt> -<dd>Gets the current device from the graphics state.</dd> -</dl> - -<dl> -<dt><code><device> getdeviceprops <mark> <name1> <value1> ... <namen> <valuen></code></dt> -<dd>Gets the properties of a device. See the section on -<a href="#Device_parameters">device parameters</a> below for details.</dd> -</dl> - -<dl> -<dt><code><mark> <name1> <value1> ... <namen> <valuen> <device> putdeviceprops <device></code></dt> -<dd>Sets properties of a device. May cause <code>undefined</code>, -<code>invalidaccess</code>, <code>typecheck</code>, <code>rangecheck</code>, or -<code>limitcheck</code> errors.</dd> -</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:</p> - -<ul> - -<li>the <code>EarlyChange</code> key in the <code>LZWEncode</code> -filter.</li> - -</ul> - -<p> -Ghostscript also supports additional keys in the optional dictionary -operands for some filters. For the <code>LZWDecode</code> filter:</p> - -<dl> -<dt><code>InitialCodeLength <integer></code> (default 8)</dt> -<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.</dd> -</dl> - -<dl> -<dt><code>FirstBitLowOrder <boolean></code> (default false)</dt> -<dd>If true, codes appear with their low-order bit first.</dd> -</dl> - -<dl> -<dt><code>BlockData <boolean></code> (default false)</dt> -<dd>If true, the data is broken into blocks in the manner specified for the -GIF file format.</dd> -</dl> - -<p> -For the <code>CCITTFaxEncode</code> and <code>CCITTFaxDecode</code> -filters:</p> - -<dl> -<dt><code>DecodedByteAlign <integer></code> (default 1)</dt> -<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.</dd> -</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.</p> - -<dl> -<dt><code><target> /BCPEncode filter <file></code></dt> -<dt><code><source> /BCPDecode filter <file></code></dt> -<dd>Create filters that implement the Adobe Binary Communications Protocol. -See Adobe documentation for details.</dd> -</dl> - -<dl> -<dt><code><target> <seed_integer> /eexecEncode filter <file></code></dt> -<dd>Creates a filter for encrypting data into the encrypted format described -in the Adobe Type 1 Font Format documentation. The -<code>seed_integer</code> must be 55665 for the <code>eexec</code> -section of a font, or 4330 for a <code>CharString</code>. Note that for -the <code>eexec</code> section of a font, this filter produces binary -output and does not include the initial 4 (or <code>lenIV</code>) garbage -bytes.</dd> -</dl> - -<dl> -<dt><code><source> <seed_integer> /eexecDecode filter <file></code></dt> -<dt><code><source> <dict> /eexecDecode filter <file></code></dt> -<dd>Creates a filter for decrypting data encrypted as described in the Adobe -Type 1 Font Format documentation. The <code>seed_integer</code> must be -55665 or 4330 as described just above. PDF interpreters don't skip space characters -after operator <code>eexec</code>. Use <code>keep_spaces = true</code> for -decoding embedded PDF fonts. Recognized dictionary keys are: - -<blockquote> -<code>seed <16-bit integer></code> (required)<br> -<code>lenIV <non-negative integer></code> (default=4)<br> -<code>eexec <bool></code> (default=<code>false</code>)<br> -<code>keep_spaces <bool></code> (default=<code>false</code>) -</blockquote> -</dd> -</dl> - -<dl> -<dt><code><target> /MD5Encode filter <file></code></dt> -<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.</dd> -</dl> - -<dl> -<dt><code><source> <hex_boolean> /PFBDecode filter <file></code></dt> -<dd>Creates a filter that decodes data in <code>.PFB</code> format, the -usual semi-binary representation for Type 1 font files on IBM PC and -compatible systems. If <code>hex_boolean</code> is true, binary packets -are converted to hex; if false, binary packets are not converted.</dd> -</dl> - -<dl> -<dt><code><target> <dict> /PixelDifferenceEncode filter <file></code></dt> -<dt><code><source> <dict> /PixelDifferenceDecode filter <file></code></dt> -<dd>Implements the Predictor=2 pixel-differencing option of the LZW -filters. Recognized keys are: - -<blockquote> -<code>Colors <integer></code> (1 to 4, default=1)<br> -<code>BitsPerComponent <integer></code> (1, 2, 4, or 8, default=8)<br> -<code>Columns <integer></code> (>= 0, required) -</blockquote> - -<p> -See the Adobe <a href="http://partners.adobe.com/public/developer/pdf/index_reference.html"><em>PDF Reference Manual</em></a> for details.</p> -</dd> -</dl> - -<dl> -<dt><code><target> <dict> /PNGPredictorEncode filter <file></code></dt> -<dt><code><source> <dict> /PNGPredictorDecode filter <file></code></dt> -<dd><p>Implements the "filter" algorithms of the -<a href="http://www.libpng.org/pub/png/">Portable Network Graphics (PNG) -graphics format</a>. Recognized keys are:</p> - -<blockquote><table> -<tr><th colspan="3">Keys recognized in PNG filter algorithms</th></tr> -<tr valign="bottom"> - <th align="left">Key</th> - - <th align="left">Range</th> - - <th align="left">Default</th></tr> -<tr valign="top"> <td><code>Colors <integer></code></td> - - <td>1 to 16</td> - - <td>16</td></tr> -<tr valign="top"> <td><code>BitsPerComponent <integer></code></td> - - <td>1, 2, 4, 8, or 16</td> - - <td>8</td></tr> -<tr valign="top"> <td><code>Columns <integer></code></td> - - <td>>= 0</td> - - <td>1</td></tr> -<tr valign="top"> <td><code>Predictor <integer></code></td> - - <td>10 to 15</td> - - <td>15</td></tr> -</table></blockquote> - -<p> -The <code>Predictor</code> is the PNG algorithm number + 10 for the -<code>Encoding</code> filter; the <code>Decoding</code> filter -ignores <code>Predictor</code>. 15 means the encoder attempts to -optimize the choice of algorithm. For more details see the PNG -specification</p> - -<blockquote> -<a href="http://www.w3.org/TR/WD-png-960128.html">http://www.w3.org/TR/WD-png-960128.html</a> -</blockquote> -</dd> -</dl> - -<dl> -<dt><code><target> /TBCPEncode filter <file></code></dt> -<dt><code><source> /TBCPDecode filter <file></code></dt> -<dd>Create filters that implement the Adobe Tagged Binary Communications -Protocol. See Adobe documentation for details.</dd> -</dl> - -<dl> -<dt><code><target> /zlibEncode filter <file></code></dt> -<dt><code><source> /zlibDecode filter <file></code></dt> -<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 <code>Flate</code> filters are actually a combination of -this filter with an optional predictor filter.</dd> -</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.</p> - -<dl> -<dt><code><target/source> <string> ByteTranslateEncode/Decode filter <file></code></dt> -<dd><code>string</code> must be a string of exactly 256 bytes. Creates a -filter that converts each input byte <em>b</em> to -<code>string</code>[<em>b</em>]. Note that the <code>Encode</code> -and <code>Decode</code> filters operate identically: the client must -provide a <code>string</code> for the <code>Decode</code> filter that -is the inverse mapping of the <code>string</code> for the -<code>Encode</code> filter.</dd> -</dl> - -<dl> -<dt><code><target/source> <dict> BoundedHuffmanEncode/Decode filter <file></code></dt> -<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> -<code>FirstBitLowOrder <bool></code> (default=false)<br> -<code>MaxCodeLength <int></code> (default=16)<br> -<code>EndOfData <bool></code> (default=true)<br> -<code>EncodeZeroRuns <int></code> (default=256)<br> -<code>Tables <int_array></code> -</blockquote> -</dd> -</dl> - -<dl> -<dt><code><target/source> <dict> BWBlockSortEncode/Decode filter <file></code></dt> -<dd>This filter implements the Burroughs-Wheeler block sorting compression -method, which we've heard is also used in the popular <code>bzip2</code> -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> -<code>BlockSize <integer></code> (default=16384) -</blockquote> -</dd> -</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 -<code>getdeviceprops</code> and <code>putdeviceprops</code>, as -indicated above.) Here are the currently defined parameters for all -devices: - -<dl> -<dt><a name="LockSafetyParams"></a> -<code>.LockSafetyParams <boolean></code></dt> -<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 <code>.LockSafetyParams</code> false will signal an -<code> invalidaccess</code> error.</p> -</dd> -</dl> - -<dl> -<dt><code>BitsPerPixel <integer> (usually read-only)</code></dt> -<dd>Number of bits per pixel.</dd> -</dl> - -<dl> -<dt><code>.HWMargins [<four floats>]</code></dt> -<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).</dd> -</dl> - -<dl> -<dt><code>HWSize [<integer> <integer>]</code></dt> -<dd>X and Y size in pixels.</dd> -</dl> - -<dl> -<dt><code>%MediaSource <integer></code></dt> -<dd>The input tray key as determined by setpagedevice. PostScript -language programs don't set this parameter directly; they can -<em>request</em> a particular tray through the MediaPosition -setpagedevice parameter, but the setpagedevice logic need not -necessarily honor the request. Devices which support switchable trays -should implement %MediaSource in their put_params device procedure, -but (unlike most other such parameters) need not implement -corresponding reading logic in get_params.</dd> -</dl> - -<dl> -<dt><code>%MediaDestination <integer></code></dt> -<dd>The output tray key as determined by setpagedevice. Handling by -devices should be parallel to %MediaSource.</dd> -</dl> - -<dl> -<dt><code>.IgnoreNumCopies <boolean></code></dt> -<dd>Some page description languages support a NumCopies parameter. -This parameter instructs the device to ignore this, producing only -one copy of the document on output. Note that some devices ignore -NumCopies regardless because of limitation of the output format -or the implementation.</dd> -</dl> - -<dl> -<dt><code>Name <string> (read-only)</code></dt> -<dd>The device name. Currently the same as <code>OutputDevice</code>.</dd> -</dl> - -<dl> -<dt><code>Colors, GrayValues, RedValues, GreenValues, BlueValues, ColorValues (usually read-only)</code></dt> -<dd>As for the <code>deviceinfo</code> operator of Display PostScript. -<code>Red</code>, <code>Green</code>, <code>Blue</code>, and -<code>ColorValues</code> are only defined if -<code>Colors</code> > 1.</dd> -</dl> - -<dl> -<dt><code>TextAlphaBits, GraphicsAlphaBits (usually read-only)</code></dt> -<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. -<p>Because this feature relies upon rendering the input it is incompatible, and will generate -an error on attempted use, with any of the vector output devices.</p> -</dd> -</dl> - -<p> -Ghostscript also supports the following read-only parameter that is not a -true device parameter:</p> - -<dl> -<dt><code>.EmbedFontObjects <integer></code></dt> -<dd>If non-zero, indicates that the device may embed font objects (as -opposed to bitmaps for individual characters) in the output. The purpose of -this parameter is to disable third-party font renderers for such devices. -(This is zero for almost all devices.)</dd> -</dl> - -<p> -In addition, the following are defined per Adobe's documentation for the -<code>setpagedevice</code> operator:</p> - -<blockquote> -<code>Duplex</code> (if supported)<br> -<code>HWResolution</code><br> -<code>ImagingBBox</code><br> -<code>Margins</code><br> -<code>LeadingEdge</code><br> -<code>MediaPosition</code><br> -<code>NumCopies</code> (for printers only)<br> -<code>Orientation</code> (if supported)<br> -<code>OutputDevice</code><br> -<code>PageOffset</code> (write-only)<br> -<code>PageSize</code><br> -<code>ProcessColorModel</code> (usually read-only)<br> -</blockquote> - -<p> -Some devices may only allow certain values for <code>HWResolution</code> -and <code>PageSize</code>. The null device ignores attempts to set -<code>PageSize</code>; its size is always <code>[0 0]</code>.</p> - -<p> -It should be noted that calling <tt>setpagedevice</tt> with one of the above keys may reset the effects of any <code>pdfmark</code> commands up to that point. In particular this is true of HWResolution, a behavior that differs from Adobe Distiller.</p> - -<a name="Banding_parameters"></a> -<p><b> -For raster printers and image format (jpeg*, tiff*, png* ...) devices these -page device parameters are also defined:</b></p> -<dl> -<dt><code>MaxBitmap <integer></code></dt> -<dd>Maximum space for a full page raster image (bitmap) in memory. -<p>This value includes the space for padding raster lines and for an array of -pointers for each raster line, thus the <code>MaxBitmap</code> value to allow -a given PageSize of a specific number of bits per pixel to be rendered in a -full page buffer may be somewhat larger than the bitmap size alone.</p> -</dd> -</dl> - -<dl> -<dt><code>BandListStorage <file|memory></code></dt> -<dd>The default is determined by the make file macro <code>BAND_LIST_STORAGE</code>. -Since <code>memory</code> is always included, specifying <code>-sBandListStorage=memory</code> -when the default is <code>file</code> will use memory based storage for the -band list of the page. This is primarily intended for testing, but if the disk I/O is -slow, band list storage in memory may be faster. -</dd> -</dl> - -<dl> -<dt><code>BufferSpace <integer></code></dt> -<dd>Size of the buffer space for band lists, if the full page raster image -(bitmap) is larger than <code>MaxBitmap</code> (see above.) - -<p>The buffer space is used to collect display list (clist) commands for the -bands and then to consolidate those commands when writing the clist to the -selected BAND_LIST_STORAGE device (memory or file) set when Ghostscript is compiled.</p> -<p>If <code>MaxBitmap</code> (above) forces banding mode, and if <code>BufferSpace</code> -is large enough, the display list (clist) will consist of a single band.</p> -<p>The <code>BufferSpace</code> will determine the size of the 'consolidation' -buffer (above) even if the <code>MaxBitmap</code> value is low enough to force -banding/clist mode.</p> -</dd> -</dl> - -<dl> -<dt><code>BGPrint <boolean></code></dt> -<dd>With many printer devices, when the display list (clist) banding mode is being used, -the page rendering and output can be performed in a background thread. -The default value, <code>false</code>, causes the rendering and printing to be -done in the same thread as the parser. When <code>-dBGPrint=true</code>, the -page output will be overlapped with parsing and writing the clist for the next page. -<p>If the device does not support background printing, rendering and printing will -be performed as if <code>-dBGPrint=false</code>.</p> -<p>Note that the background printing thread will allocate a band buffer (size determined -by the <code>BufferSpace</code> or <code>BandBufferSpace</code> values) in addition to -the band buffer in the 'main' parsing thread.</p> -<p>If <code>NumRenderingThreads</code> is > 0, then the background printing thread -will use the specified number of rendering threads as children of the background printing -thread. The background printing thread will perform any processing of the raster data -delivered by the rendering threads. Note that BGPrint is disabled for vector devices such as pdfwrite -and NumRenderingThreads has no effect on these devices eitehr.</p> -</dd> -</dl> - -<dl> -<dt><code>GrayDetection <boolean></code></dt> -<dd>When <code>true</code>, and when the display list (clist) banding mode is being used, -during writing of the clist, the color processing logic collects information about the -colors used <b>before</b> the device color profile is applied. This allows special devices -that examine <code>dev->icc_struct->pageneutralcolor</code> with the information that all -colors on the page are near <i>neutral</i>, i.e. monochrome, and converting the rendered -raster to gray may be used to reduce the use of color toners/inks. -<p> -Since the determination of whether or not the page uses colors is determined before the -conversion to device colors, this information is independent of the device output profile. -The determination has a small delta (<tt>DEV_NEUTRAL</tt> and <tt>AB_NEUTRAL</tt> in -<tt>base/gscms.h</tt>) to allow colors close to neutral to be detected as neutral. -Changing this value requires rebuilding.</p> -<p> -Among the devices distributed with the source, currently only the <code>pnmcmyk</code> -device supports this parameter and will produce either a <code>P7 PAM</code> CMYK output -or a <code>P5 PGM</code> Gray output depending on the use of color on the page.</p> -<p> -Also, the 'pageneutralcolor' status can be interrogated as a device parameter of the -same name. Using PostScript there are several methods:</p> -<pre> - currentpagedevice /pageneutralcolor get - - mark currentdevice getdeviceprops .dicttomark /pageneutralcolor get - - /pageneutralcolor /GetDeviceParam .special_op { exch pop }{ //false } ifelse -</pre> -<p> -Note that the <tt>pageneutralcolor</tt> state is reset to <tt>false</tt> after the -page is output, so this parameter is only valid immediately <b>before</b> <tt>showpage</tt> -is executed, although the <tt>setpagedevice EndPage</tt> procedure can be used to check -the state just prior to the actual output of the page that resets <tt>pagenuetralcolor</tt>. -For example:</p> -<pre> - << /EndPage { - exch pop 2 ne dup { - currentpagedevice /pageneutralcolor get (pageneutralcolor: ) print = flush - } if - } - >> setpagedevice -</pre> -<b>Notes:</b> -<p> -Since <code>-dGrayDetection=true</code> requires extra checking during -writing of the clist, this option should <b>only</b> be used for devices that -support the optimization of pages to monochrome, otherwise performance may be degraded -for no benefit.</p> -<p> -Since GrayDetection=true is only effective when in clist (banding) mode, it is recommended -to also force banding. For example: <b><tt>-dGrayDetection=true -dMaxBitmap=0</tt></b></p> -</dd> -</dl> - -<dl> -<dt><code>NumRenderingThreads <integer></code></dt> -<dd>When the display list (clist) banding mode is being used, bands can be rendered -in separate threads. The default value, 0, causes the rendering of bands to be -done in the same thread as the parser and device driver. <code>NumRenderingThreads</code> -of 1 or higher results in bands rendering in the specified number of 'background' -threads. -<p>The number of threads should generally be set to the number of available -processor cores for best throughput.</p> -<p>Note that each thread will allocate a band buffer (size determined by the -<code>BufferSpace</code> or <code>BandBufferSpace</code> values) in addition to -the band buffer in the 'main' thread.</p> -<p>Additoinally note that ths parameter has no effect with devices which do not generally -render to a bitmap output, such as the vector devices (eg pdfwrite) and has no effect -when rendering, but not using a clist. See <a href="Use.htm#Improving_performance">Improving_performance</a> -</p> -</dd> -</dl> - -<dl> -<dt><code>OutputFile <string></code></dt> -<dd>An empty string means "send to printer directly", otherwise specifies -the file name for output; <code>%d</code> is replaced by the page number -for page-oriented output devices; -on Unix systems <code>%pipe%</code><em>command</em> writes to a pipe. -(<code>|</code><em>command</em> also writes to a pipe, but is now -deprecated). Also see the <code>-o</code> parameter. -<p> -Attempts to set this parameter if <code>.LockSafetyParams</code> is true -will signal an <code>invalidaccess</code> error.</p> -</dd> -</dl> - -<dl> -<dt><code>OpenOutputFile <boolean></code></dt> -<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.</dd> -</dl> - -<dl> -<dt><code>PageCount <integer> (read-only)</code></dt> -<dd>Counts the number of pages printed on the device.</dd> -</dl> - -<p> -The following parameters are for use only by very specialized applications -that separate band construction from band rasterization. <b>Improper use may -cause unpredictable errors.</b> In particular, if you only want to allocate -more memory for banding, to increase band size and improve performance, use -the <code>BufferSpace</code> parameter, not <code>BandBufferSpace</code>.</p> - -<dl> -<dt><code>BandHeight <integer></code></dt> -<dd>The height of bands when banding. 0 means use the largest band height -that will fit within the <code>BandBufferSpace</code> (or <code>BufferSpace</code>, -if <code>BandBufferSpace</code> is not specified). If <code>BandHeight</code> -is larger than the number of lines that will fit in the buffer, opening the device will fail. -If the value is -1, the BandHeight will automatically be set to the page height -(1 band for the entire page). This is primarily for developers debugging clist issues. -</dd> -</dl> - -<dl> -<dt><code>BandWidth <integer></code></dt> -<dd>The width of bands in the rasterizing pass, in pixels. 0 means use the -actual page width. A BandWidth value smaller than the width of the page -will be ignored, and the actual page width will be used instead.</dd> -</dl> - -<dl> -<dt><code>BandBufferSpace <integer></code></dt> -<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.</dd> -</dl> - -<p> -Ghostscript supports the following parameter for -<code>setpagedevice</code> and <code>currentpagedevice</code> that is -not a device parameter per se:</p> - -<dl> -<dt><code>ViewerPreProcess <procedure></code></dt> -<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.</dd> -</dl> - -<hr> - -<h2><a name="User_parameters"></a>User parameters</h2> - -Ghostscript supports the following non-standard user parameters: - -<dl> -<dt><code>ProcessDSCComment <procedure|null></code></dt> -<dd>If not null, this procedure is called whenever the scanner detects a DSC -comment (comment beginning with <code>%%</code> or <code>%!</code>). -There are two operands, the file and the comment (minus any terminating -EOL), which the procedure must consume.</dd> -</dl> - -<dl> -<dt><code>ProcessComment <procedure|null></code></dt> -<dd>If not null, this procedure is called whenever the scanner detects a -comment (or, if <code>ProcessDSCComment</code> is also not null, a -comment other than a DSC comment). The operands are the same as for -<code>ProcessDSCComment</code>.</dd> -</dl> - -<dl> -<dt><code>LockFilePermissions <boolean></code></dt> -<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 <code>invalidaccess</code>. -Also, when this value is <tt>true</tt>, the <code>file</code> operator -will give <code>invalidaccess</code> when attempting to open files -(processes) using the <code>%pipe</code> device. -<p> -Also when <code>LockFilePermissions</code> is <tt>true</tt>, strings -cannot reference the parent directory (platform specific). For example -<code>(../../xyz)</code> is illegal on unix, Windows -and Macintosh, and <code>([.#.#.XYZ])</code> is illegal on VMS.</p> -<p> -This parameter is set <tt>true</tt> by the <code>.setsafe</code> and -<code>.locksafe</code> operators.</p> -</dd> -</dl> - -<dl> -<dt><code>PermitFileReading <array of strings></code></dt> -<dt><code>PermitFileWriting <array of strings></code></dt> -<dt><code>PermitFileControl <array of strings></code></dt> -<dd>These parameters specify paths where file reading, writing and the -'control' operations are permitted, respectively. File control -operations are <code>deletefile</code> and <code>renamefile</code>. -For <code>renamefile</code>, 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 <code>filenameforall</code> -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> -<p> -<b>Note:</b> The strings are used for stringmatch operations similar -to <code>filenameforall</code>, 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> -<p> -The <a href="Use.htm#Safer"><b>SAFER</b></a> mode and the -<code>.setsafe</code> operator set all three lists to empty arrays, -thus the only files that can be read are the <code>%stdin</code> 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).</p> -<p> -<b>Note: </b>Limiting file reading as above is <b>NOT</b> compatible with -SAFER mode in release versions before 7.11 and corresponds to the use of -<code>-dPARANOIDSAFER</code> in version 7.04 (up to and not including -version 7.10) and GPL versions 6.53 (up to and not including 6.60).</p> -</dd> -</dl> - -<dl> -<dt><code>AlignToPixels <integer></code></dt> -<dd>Control sub-pixel positioning of character glyphs (where -applicable). A value of 1 specifies alignment of text characters to -pixels boundaries. A value of 0 to subpixels where the division factor -is set by the device parameter <code>TextAlphaBits</code>. If the -latter is 1, the same rendering results regardless of the value of -<code>AlignToPixels</code>. The initial value defaults to 1, but this -may be overridden by the command line argument -<code>-dAlignToPixels</code>.</dd> -</dl> - - -<dl> -<dt><a name="GridFitTT"></a> -<code>GridFitTT <integer></code></dt> -<dd>Control the use of True Type grid fitting. -Ghostscript, by default, uses Freetype for rendering Truetype (and most other) glyphs -(but other scaler/renderer libraries can be used), thus has access to a complete Truetype -bytecode interpreter. -<p> -This parameter controls the hinting of Truetype glyphs.</p> -<ul> -<li> -A value of 0 disables grid fitting for all True Type fonts (not generally recommended). -</li> - -<li> -A value of 1 enables the grid fitting using the native Truetype hinting bytecode -program(s). Fonts or glyphs with faulty bytecode program(s) will be rendered unhinted. -</li> - -<li> -A value 2 is scaler/renderer dependent (generally, if no alternative hinting engine is available -this will be equivalent to 1). With the Freetype (our default) this enables Freetype's built-in -autohinter. -</li> - -<li> -With Freetype, a value of 3 is effectively equivalent to 1. -</li> -</ul> -<p> -This parameter defaults to 1, but this -may be overridden on the command line with -<code>-dGridFitTT=n</code>.</p> -</dd> -</dl> - -<hr> - -<h2><a name="Miscellaneous_additions"></a>Miscellaneous additions</h2> - -<h3><a name="Extended_semantics_of_run"></a>Extended semantics of 'run'</h3> - -<p> -The operator <code>run</code> 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.</p> - -<h3><a name="DecodingResources"></a>Decoding resources</h3> - -<p> -<code>Decoding</code> is a Ghostscript-specific resource category. It contains -various resources for emulating PostScript fonts with other font technologies. -Instances of the <tt>Decoding</tt> category are tables which map PostScript glyph -names to character codes used with TrueType, Intellifont, Microtype and other font formats.</p> - -<p> -Currently Ghostscript is capable of PostScript font emulation in 2 ways :</p> -<ul> -<li> -1. Through <a href="./Use.htm#FAPI_run">FAPI</a> plugins, and -</li> -<li> -2. With TrueType font files, using the native font renderer, by -specifying TrueType font names or files in <a href="../Resource/Init/Fontmap.GS">Resource/Init/Fontmap.GS</a>. -</li> -</ul> -<p> -<code>Decoding</code> resources are not currently used by the native font renderer.</p> - -<p> -An instance of the <code>Decoding</code> resource category is -a dictionary. The dictionary keys are PostScript glyph names and the -values are either character codes, or arrays of character codes. -Arrays are used when a single name may be mapped to various character codes - -in this case Ghostscript tries all alternatives until a success. -The name of the resource instance should -reflect the character set for which it maps. For example, -<code>/Unicode</code> <code>/Decoding</code> resource maps to -Unicode UTF-16.</p> - -<p> -The rules for using <code>Decoding</code> resources in particular -cases are specified in the configuration file -<a href="../Resource/Init/xlatmap">Resource/Init/xlatmap</a>. See the file itself for more -information.</p> - -<p> -The file format for <code>Decoding</code> resource files is -generic PostScript. -Users may want to define custom <code>Decoding</code> resources. -The <code>ParseDecoding</code> procset defined in -<a href="../Resource/Init/gs_ciddc.ps">Resource/Init/gs_ciddc.ps</a> allows representation -of the table in a comfortable form.</p> - - -<h3><a name="CIDDecodingResources"></a>CIDDecoding resources</h3> - -<p> -<code>CIDDecoding</code> resources are similar to <code>Decoding</code> -resources, except they map Character Identifiers (CIDs) rather than glyph names. -Another difference is that the native Ghostscript font renderer uses -<code>CIDDecoding</code> resources while emulate CID fonts with TrueType or OpenType fonts.</p> - -<p> -An instance of the <code>CIDDecoding</code> resource category is -a dictionary of arrays. Keys in the dictionary are integers, -which correspond to high order byte of a CID. -Values are 256-element arrays, and their indices correspond to the low order byte of a CID. -Each elemet of an array is either null, or character code (integer), or an array -of character codes (integers). The zero code represents mapping to the default character.</p> - -<p> -The dictionary includes the additional key <code>CIDCount</code>. -Its value is the maximal CID defined, plus one.</p> - -<p> -The Ghostscript library is capable of generating some <code>CIDDecoding</code> -instances automatically, using the appropriate <code>CMap</code> (character map) -resources. This covers most of practical cases if the neccessary <code>CMap</code> -resources are provided. See the table <code>.CMapChooser</code> in -<a href="../Resource/Init/gs_ciddc.ps">Resource/Init/gs_ciddc.ps</a> -for the names of automatically gerenated resources and associated <code>CMap</code>s. -They allow to mapping CNS1, GB1, Japan1, Japan2 and Korea1 CID sets to TrueType -character sets known as Unicode (exactly UTF-16), Big5, -GB1213, ShiftJIS, Johab and Wansung.</p> - -<p> -The file format for <code>CIDDecoding</code> resource file is -generic PostScript. -Users may want to define custom resources to <code>CIDDecoding</code> -resource category.</p> - -<h3><a name="GlyphNames2Unicode"></a>GlyphNames2Unicode</h3> -<p> -<code>GlyphNames2Unicode</code> is an undocumented dictionary which Adobe -PostScript printer driver uses to communicate with Adobe Distiller. -In this dictionary the keys are glyph names, the values are Unicode UTF-16 codes for them. -The dictionaly is stored in the <code>FontInfo</code> dictionary under -the key <code>GlyphNames2Unicode</code>. Ghostscript recognises it and uses -to generate <code>ToUnicode</code> CMaps with pdfwrite.</p> - -<h3><a name="MultipleResourceDirectories"></a>Multiple Resource directories</h3> - -<p> -Since 8.10 release Ghostscript maintains multiple resource directories.</p> - -<p> -Ghostscript does not distinguish <code>lib</code> and -<code>Resource</code> directories. -There is no file name conflicts because <code>lib</code> does not -contain subdirectories, but <code>Resource</code> -always store files in subdirectories.</p> - -<p> -The search method with multiple resource directories -appears not fully conforming to PLRM. We cannot unconditionally call -<code>ResourceFileName</code> while executing <code>findresource</code> -or <code>resourcestatus</code>, <code>resourceforall</code>, because -per PLRM it always returns a single path. Therefore Ghostscript -implements an extended search method in <code>findresource</code>, -<code>resourcestatus</code> and <code>resourceforall</code>, which -first calls <code>ResourceFileName</code> and checks whether the -returned path points to an existing file. If yes, the file is used, -othervise Ghostscript searches all directories specified in -<code>LIB_PATH</code>. With a single resource directory -it appears conforming to PLRM and equivalent to Adobe implementations.</p> - -<p> -<code>ResourceFileName</code> may be used for obtaining a path -where a resource file to be installed. In this case -Ghostscript to be invoked with <code>-sGenericResourceDir=path</code>, -specifying an absolute path. The default value for -<code>GenericResourceDir</code> is a relative path. Therefore -a default invocation with a PostScript installer -will install resource files into <code>/gs/Resource</code>.</p> - -<h2><a name="PDF_scripting"></a>Scripting the PDF interpreter</h2> - -<h3><a name="PS_functions"></a>PostScript functions</h3> - -<p>We have not previously documented the internals of the Ghostscript PDF interpreter, but we have, on -occasion, provided solutions that rely upon scripting the interpreter from PostScript. This was -possible because the interpreter was written in PostScript.</p> - -<p>From release 9.55.0 Ghostscript comes supplied with two PDF interpreters, the original written in PostScript -and a brand-new interpreter written in C. While the new interpreter can be run as part of the GhostPDL family -it has also been integrated into Ghostscript, and can be run from the PostScript environment in a similar fashion -to the old interpreter. We plan to deprecate, and eventually remove, the old interpreter and carry on with the new one.</p> - -<p>Because we have supplied solutions in the past based on the old interpreter, we have had to implement -the same capabilities in the integration of the new interpreter. Since this has meant discovering which internal -portions were being used, working out how those function, and duplicating them anew, it seemed a good time to -document these officially, so that in future the functionality would be available to all.</p> - -<p>The following functions existed in the original PDF interpreter and have been replicated for the new -interpreter. It should be possible to use these for the forseeable future.</p> -<dl> -<dt><code><file> runpdf - </code></dt> -<dd> Called from the modified PostScript run operator (which copies stdin to a temp - file if required). Checks for PDF collections, processes all requested pages.</dd> - -<dt><code><file> runpdfbegin -</code></dt> -<dd> This must be called before performing any further operations. Its exact action depends on which -interpreter is being used, but it essentially sets up the environment to process the file as a PDF</dd> -<dt><code><int> pdfgetpage <pagedict> | <null></code></dt> -<dd> int is a number from 1 to N indicating the desired page number from - the PDF file. Returns the a dictionary containing various informational key/value pairs. - If this fails, returns a null object.</dd> - <dt><code> - pdfshowpage_init -</code></dt> -<dd> In the PostScript PDF interpreter this simply adds 1 to the /DSCPageCount value in a dictionary. -It has no effect in the new PDF interpreter but is maintained for backwards compatibility.</dd> - -<dt><code><pagedict> pdfshowpage_setpage <pagedict></code></dt> -<dd> Takes a dictionary as returned from pdfgetpage, extracts various - parameters from it, and sets the media size for the page, taking into - account the boxes, and requested Box, Rotate value and PDFFitPage.</dd> - <dt><code><pagedict> pdfshowpage_finish -</code></dt> -<dd> Takes a dictionary as returned from pdfgetpage, renders the page content - executes showpage to transfer the rendered content to the device.</dd> - <dt><code>- runpdfend -</code></dt> -<dd> Terminates the PDF processing, executes restore and various cleanup activities.</dd> -<dt><code><file> pdfopen <dict></code></dt> -<dd> Open a PDF file and read the header, trailer - and cross-reference.</dd> - <dt><code><dict> pdfclose -</code></dt> -<dd> Terminates processing the original PDF file object. The dictionary parameter - should be the one returned from pdfopen</dd> - <dt><code><pagedict> pdfshowpage -</code></dt> -<dd> Takes a dictionary returned from pdfgetpage and calls the pdfshowpage_init - pdfshowpage_setpage, pdfshowpage_finish trio to start the page, set up the - media and render the page.</dd> - <dt><code><int> <int> dopdfpages -</code></dt> -<dd> The integers are the first and last pages to be run from the file. Runs a loop from - the fist integer to the last. NOTE! If the current dictionary contains a PDFPageList - array then we 'get' the entry from the array corresponding to the current loop - index, and use that to determine whether we should draw the page. Otherwise we - simply draw the page. Uses pdfshowpage to actually render the page.</dd> - <dt><code>- runpdfpagerange <int> <int></code></dt> -<dd> Processes the PostScript /FirstPage, /LastPage and /PageList parameters. These are used together to build an internal array - of page numbers to run, which is used by dopdfpages to actually process the pages if PageList is present, - and a FirstPage and LastPage value. Despite the name this function does not actually 'run' any pages at all. - -<p>Normal operation simply calls runpdf with an opened-for-read PostScript file object. The table below shows the normal -calling sequence</p> - -<blockquote><table> -<tr valign="bottom"> - <th align="left">Function</th> - - <th align="left">Calls</th> - - <th align="left">Calls</th> - - <th align="left">Calls</th></tr> -<tr valign="top"> - <td>runpdf</td> - - <td>runpdfbegin</td> - - <td>pdfopen</td> - - <td> </td></tr> -<tr valign="top"> - - <td> </td> - <td>process_trailer_attrs</td> - - <td> </td> - <td> </td> -</tr> -<tr valign="top"> - - <td> </td> - <td>runpdfpagerange</td> - - - <td> </td> - <td> </td></tr> -<tr valign="top"> - - <td> </td> - <td>dopdfpages</td> - - <td>pdfgetpage</td> - <td> </td></tr> -<tr valign="top"> - <td> </td> - <td> </td> - <td>pdfshowpage</td> - - <td>pdfshowpage_init</td></tr> -<tr valign="top"> - - <td> </td> - <td> </td> - <td> </td> - <td>pdfshowpage_setpage</td></tr> -<tr valign="top"> - - <td> </td> - <td> </td> - <td> </td> - <td>pdfshowpage_finish</td></tr> -<tr valign="top"> - - <td> </td> - <td>runpdfend</td> - - <td>pdfclose</td> - <td> </td></tr> -</table></blockquote> - -<p>It is important to get the number of spots and the presence of transparency correct when -rendering. Failure to do so will lead to odd output, and potentially crahses. This can be important in situations -such as N-up ordering.</p> -<p>As an example, if we have 2 A4 pages and want to render them side-by-side on A3 media, we might set up -the media size to A3, draw the first page contents, translate the origin, draw the second page contents -and then render the final content. If the first PDF page did not contain transparency, but the second did, it -would be necessary to set /PageHasTransparency before drawing the first PDF page.</p> - -<h3><a name="PDF_PS_operators"></a>PostScript operators interfacing to the PDF interpreter</h3> -<p>The PostScript functions documented above must somehow interface with the actual PDF interpreter, and this is done -using a small number of custom PostScript operators. These operators do not exist in standard PostScript; they -are specific to the Ghostscript implementation. These operators are documented here for the benefit of any -developers wishing to use them directly.</p> -</dd> - -<dt><code>dict .PDFInit <PDFContext></code></dt> -<dd> Initialises an instance of the PDF interpreter. dict is an optional dictionary that contains any interpreter-level -switches, such as PDFDEBUG, this is used to set the initial state of the PDF interpreter. -The return value is a PDFcontext object which is an opaque object to be used with the other PDF operators.</dd> -<dt><code>filename PDFcontext .PDFFile -</code></dt> -<dd> Opens a named file and associates it with the instance of the PDF interpreter. -Filename is a string containing a fully qualified path to the PDF file to open, this file must have been made accesible -by setting --permit-file-read. -</dd><dt><code>file PDFcontext .PDFStream -</code></dt> -<dd> Takes an already open (disk-based) file and associates it with the instance of the PDF interpreter. -</dd><dt><code>PDFcontext .PDFClose -</code></dt> -<dd> If the context contains an open PDF file which was opened via the .PDFfile operator, this closes the file. -Files associated with the context by the .PDFStream operator are unaffected. Regardless of the source it then shuts down the PDF interpreter and frees the associated memory. -</dd><dt><code>PDFcontext .PDFInfo dict</code></dt> -<dd> PDFcontext is a PDFcontext object returned from a previous call to .PDFInit. -The returned dictionary contains various key/value pairs with useful file level information: -<blockquote> - <code>/NumPages</code> int<br> - <code>/Creator</code> string<br> - <code>/Producer</code> string<br> - <code>/IsEncrypted</code> boolean<br> -</blockquote> -</dd><dt><code>PDFcontext .PDFMetadata -</code></dt> -<dd> PDFcontext is a PDFcontext object returned from a previous call to .PDFInit. -For the benefit of high level devices, this is a replacement for 'process_trailer_attrs' which is a seriously misnamed function now. -This function needs to write any required output intents, load and send Outlines to the device, copy the Author, Creator, Title, Subject -and Keywords from the Info dict to the output device, copy Optional Content Properties (OCProperties) to the output device. -If an AcroForm is present send all its fields and link widget annotations to fields, and finally copy the PageLabels. If we add support for anything else, it will be here too.. -</dd><dt><code>PDFcontext int .PDFPageInfo -</code></dt> -<dd> The integer argument is the page number to retrieve information for. -Returns a dictionary with the following key/value pairs: -<blockquote> - <code>/UsesTransparency</code> true|false<br> - <code>/SpotColours</code> array of names, may be empty|<br> - <code>/MediaBox</code> [llx lly urx ury]<br> - <code>/HasAnnots</code> true|false<br> - <code>/FontsUsed</code> array of names, may be empty.<br> -</blockquote> -May also contain (if they are present in the Page dictionary) -<blockquote> - <code>/ArtBox</code> [llx lly urx ury]<br> - <code>/CropBox</code> [llx lly urx ury]<br> - <code>/BleedBox</code> [llx lly urx ury]<br> - <code>/TrimBox</code> [llx lly urx ury]<br> - <code>/UserUnit</code> int<br> -</blockquote> -</dd> -<dt><code>PDFcontext int .PDFDrawPage -</code></dt> -<dd> PDFcontext is a PDFcontext object returned from a previous call to .PDFInit. -The integer argument is the page number to be processed. -Interprets the page content stream(s) of the specified page using the current graphics state. -</dd> - -<dt><code>PDFcontext int .PDFDrawAnnots -</code></dt> -<dd> PDFcontext is a PDFcontext object returned from a previous call to .PDFInit. -The integer argument is the page number to be processed. -Renders the Annotations (if any) of the specified page using the current graphics state -For correct results, the graphics state when this operator is run should be the same as when -PDFDrawPage is executed. - - -<p>Note: The PDFcontext object created by PDFInit must (clearly) have a PDF file associated -with it before you can usefully use it. Attempting to use a PDFcontext with -any of the processing operators (eg .PDFDrawPage) before using either .PDFStream of .PDFFile -to associate a file with the context will result in an error. -</p> -</dd> -</dl> -<!-- [2.0 end contents] ==================================================== --> - -<!-- [3.0 begin visible trailer] =========================================== --> -<hr> - -<p> -<small>Copyright © 2000-2022 Artifex Software, Inc. All rights reserved.</small> - -<p> -This software is provided AS-IS with no warranty, either express or -implied. - -This software is distributed under license and may not be copied, modified -or distributed except as expressly authorized under the terms of that -license. Refer to licensing information at <a href="https://www.artifex.com">https://www.artifex.com</a> -or contact Artifex Software, Inc., 1305 Grant Avenue - Suite 200, -Novato, CA 94945, U.S.A., +1(415)492-9861, for further information. - -<p> -<small>Ghostscript version 9.56.1, 4 April 2022 - -<!-- [3.0 end visible trailer] ============================================= --> - - - -<!--FINISH EDITING HERE--> - </div><!-- close inner --> - </div><!-- close outer --> - </article> - </main> - <script src="site.js"></script> -</body> -</html> |