Postscript Operators 'i','j', and 'k'




identmatrix matrix identmatrix matrix

replaces the value of matrix with the value of the identity matrix

[1.0 0.0 0.0 1.0 0.0 0.0]

and pushes this modified matrix back on the operand stack. The identity matrix transforms any coordinate to itself.

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: matrix, currentmatrix,

defaultmatrix, initmatrix

Troubleshooting index Postscript Index

idiv int1 int2 idiv quotient
divides int1 by int2 and returns the integer part of the quotient, with any fractional part discarded. Both operands of idiv must be integers and the result is an integer.

EXAMPLE:
3 2 idiv -> 1
4 2 idiv -> 2
-5 2 idiv -> -2

ERRORS: stackunderflow, typecheck,

undefinedresult

SEE ALSO: div, add,

mul, sub, mod,

cvi

Troubleshooting index Back to Postscript index


idtransform dx` dy` idtransform dx dy
dx` dy` matrix idtransform dx dy

With no matrix operand, idtransform (inverse delta transform) transforms the device space distance vector (dx`, dy`) by the inverse of CTM to produce the corresponding distance vector (dx, dy) in user space.

If the matrix operand is supplied, idtransform transforms the distance vector by the inverse of matrix rather than by the inverse of CTM.

A delta transformation is similar to a normal transformation, but the translation components (tx and ty) of the transformation matrix are not used, making the distance vectors be positionless in both user space and device space.
idtransform is the inverse of dtransform. It is useful for determining how distances map from device space to user space.

ERRORS: rangecheck, stackunderflow,

typecheck, undefinedresult

SEE ALSO: dtransform, transform,

itransform

Troubleshooting index Back to Postscript index


if bool proc if -

removes both operands from the stack, then executes proc if bool is true. The if operator pushes no results of its own on the operand stack, but the proc may do so.

EXAMPLE:

3 4 lt /{

(3 is less than 4)} if -> (3 is less than 4)

ERRORS: stackunderflow, typecheck

SEE ALSO: ifelse

Troubleshooting index Back to Postscript index


ifelse bool proc1 proc2 ifelse -

removes all three operands from the stack, then executes proc1 if bool is true or proc2 if bool is false. The ifelse operator pushes no results of its own on the operand stack, but the procedure it executes may do so.

EXAMPLE:

4 3 lt /{

(TruePart)} /{

(FalsePart)} ifelse -> (FalsePart) % Since 4 is not less than 3


ERRORS: stackunderflow, typecheck

SEE ALSO: if

Troubleshooting index Back to Postscript index


image width height bits/sample matrix datasrc image
dict image -

paints a sampled image onto the current page. The description here only summarizes the image operator.

The sampled image is a rectangular array of width x height sample values, each of which consists of bits/sample bits of data (1, 2, 4, 8, or 12). The data is received as a sequence of characters-in other words, 8-bit integers in the range 0 to 255. If bits/sample is less than 8, sample values are packed left to right within a character

In the first form of image, the parameters are specified as separate operands. This is the only form Level 1 implementations support. image renders a monochrome image according to the DeviceGray color space, regardless of the current color space.

In the second form, the parameters are contained as key-value pairs in an image dictionary, which is specified as the single operand of image. This form is a Level 2 feature. image renders either a monochrome or color image according to the current color space parameter in the graphics state. The number of component values per source sample and the interpretations of those values depend on the current color space.

The image is considered to exist in its own coordinate system. The rectangular boundary of the image has its lower-left corner at (0, 0) and its upper-right corner at (width, height). The matrix operand specifies a transformation from user space to the image coordinate system.

In Level 1, datasrc must be a procedure. In Level 2, datasrc may be any data source ,-a procedure, string, or readable file object (including a filtered file).

If datasrc is a procedure, image executes datasrc repeatedly to obtain the actual image data. datasrc must return (on the operand stack) a string containing any number of additional characters of sample data.

If datasrc returns a string of length zero, image will terminate execution prematurely. The sample values are assumed to be received in a fixed order: (0, 0) through (width-1, 0), then (0, 1) through (width-1, 1), and so on.

Execution of this operator is not permitted in certain circumstances.

ERRORS: limitcheck, invalidaccess,

ioerror, rangecheck,

stackunderflow, typecheck,

undefinedresult, undefined

SEE ALSO: imagemask, colorimage

Troubleshooting index Back to Postscript index


imagemask width height polarity matrix datasrc imagemask -
dict imagemask -

is similar to the image operator. However, it treats the source image as a mask of 1-bit samples that are used to control where to apply paint with the current color and where not to apply any paint.

In the first form of imagemask, the parameters are specified as separate operands. This is the only form Level 1 implementations support. In the second form, the parameters are contained as key-value pairs in an image dictionary. The second form is a Level 2 feature. The semantics of imagemask do not depend on which way the operands are specified.

imagemask uses the width, height, matrix, and datasrc operands in precisely the same way image uses them. The polarity operand is a boolean that determines the polarity of the mask. It controls the sense of the mask only; it has no effect on the color of the pixels that are painted. If polarity is false, portions of the image corresponding to source sample values of 0 are painted, while those corresponding to sample values of 1 are left unchanged. If polarity is true, sample values of 1 are painted and sample values of 0 are left unchanged.

In the second form of imagemask, the polarity is specified by means of the Decode entry in the image dictionary. Decode values of [0 1] and [1 0] correspond to polarity values of false and true, respectively.

In Level 1, datasrc must be a procedure. In Level 2, datasrc may
be any data source ,-a procedure, string, or readable file object (including a filtered file).

imagemask is most useful for painting characters represented as bitmaps. Such bitmaps represent masks through which a color is to be transferred; the bitmaps themselves do not have a color.

EXAMPLE:
54 112 translate % Locate lower-left corner of square
120 120 scale % Scale 1 unit to 120 points
0 0 moveto 0 1 lineto % Fill square with gray background
1 1 lineto 1 0 lineto closepath
.9 setgray fill
0 setgray % Paint mask black
24 23 % Dimensions of source mask
true % Paint the 1 bits
[24 0 0 -23 0 23] % Map unit square to mask

/{

<003B00 002700 002480 0E4940 114920 14B220 3CB650 75FE88 17FF8C 175F14
1C07E2 3803C4 703182 F8EDFC B2BBC2 BB6F84 31BFC2 18EA3C 0E3E00 07FC00
03F800 1E1800 1FF800>} % Mask data
imagemask

ERRORS: stackunderflow, typecheck,

undefinedresult, limitcheck,

invalidaccess, ioerror

SEE ALSO: image, colorimage

Troubleshooting index Back to Postscript index


index anyn ... any0 n index anyn ... any0 anyn

removes the non-negative integer n from the operand stack, counts down to the nth element from the top of the stack, and pushes a copy of that element on the stack.

EXAMPLE:

(a)(b)(c)(d) 0 index -> (a)(b)(c)(d)(d)
(a)(b)(c)(d) 3 index -> (a)(b)(c)(d)(a)

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: copy, dup,

roll

Troubleshooting index Back to Postscript index


ineofill x y ineofill bool
userpath ineofill bool LEVEL 2

is similar to infill, but its "insideness" test is based on eofill instead of fill.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: eofill, infill

Troubleshooting index Back to Postscript index


infill x y infill bool
userpath infill bool LEVEL 2

The first form returns true if the device pixel containing the point (x, y) in user space would be painted by a fill of the current path in the graphics state. Otherwise, it returns false.

In the second form, the device pixels that would be painted by filling userpath become an "aperture." This form of the operator returns true if any of the pixels in the aperture would be painted by a fill of the current path in the graphics state. Otherwise, it returns false.

Both forms of this operator ignore the current clipping path and current view clip; that is, they detect a "hit" anywhere within the current path, even if filling that path would not mark the current page due to clipping. They do not place any marks on the current page nor do they disturb the current path. The following program fragment takes the current clipping path into account:

gsave clippath x y infill grestore
x y infill and

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: fill, ineofill

Troubleshooting index Back to Postscript index


initclip - initclip -

replaces the current clip path parameter in the graphics state by the default clip path for the current output device. This path usually corresponds to the boundary of the maximum imageable area for the current output device. For a pageoriented output device, its dimensions are those established by the setpagedevice operator. For a display device, the clipping region established by initclip is not well defined. Display PostScript applications should not make the assumption that the clipping region corresponds to the window boundary (see viewclippath).

There are few situations in which a PostScript language program should execute initclip explicitly. A page description that executes initclip usually produces incorrect results if it is embedded within another, composite page.

ERRORS: (none)

SEE ALSO: clip, eoclip,

clippath, initgraphics

Troubleshooting index Back to Postscript index


initgraphics - initgraphics -

% different in the NeXT implementation

This standard PostScript operator has these additional effects in the NeXT implementation of the Display PostScript System:

S Sets the coverage parameter in the current window's graphics state to 1 (opaque)

S Turns off instance drawing

resets several values in the current graphics state to their default values:

current transformation matrix (default for current device)
current path (empty)
current point (undefined)
current clipping path (default for current device)
current color space (DeviceGray)
current color (black)
current line width (one user space unit)
current line cap style (butt end caps)
current line join style (miter joins)
current dash description (undashed, i.e., solid lines)
current miter limit (10)

The initgraphics operator does not change the other graphics state parameters. These include the current output device, font, stroke adjust, and all devicedependent parameters. This operator affects only the graphics state, not the contents of raster memory or the output device.

initgraphics is equivalent to the PostScript language sequence:

initmatrix newpath initclip
1 setlinewidth 0 setlinecap 0 setlinejoin
[ ] 0 setdash 0 setgray 10 setmiterlimit

There are few situations in which a PostScript language program should execute initgraphics explicitly. A page description that executes initgraphics usually produces incorrect results if it is embedded within another, composite page. A program requiring information about its initial graphics state should read and save that state at the beginning of the program rather than assume that the default state prevailed initially.

ERRORS: (none)

SEE ALSO: grestoreall, hideinstance, newinstance, setalpha, setinstance
Troubleshooting index Back to Postscript index


initmatrix - initmatrix -

sets the current transformation matrix (CTM) to the default matrix for the current output device. This matrix transforms the default user coordinate system to device space. For a page-oriented device, the default matrix is initially established
by the setpagedevice operator.

There are few situations in which a PostScript language program should execute initmatrix explicitly. A page description that executes initmatrix usually produces incorrect results if it is embedded within another, composite page.

ERRORS: (none)

SEE ALSO: defaultmatrix, currentmatrix,

setmatrix

Troubleshooting index Back to Postscript index


initviewclip - initviewclip - DPS
returns the context to its initial view clipping state, in which no view clipping path exists.

ERRORS: (none)

SEE ALSO: viewclip, viewclippath
Troubleshooting index Back to Postscript index


instroke x y instroke bool
userpath instroke bool LEVEL 2

The first form returns true if the device pixel containing the point (x, y) in user space would be painted by a stroke of the current path in the graphics state. Otherwise, it returns false. It does not place any marks on the current page nor does it disturb the current path.

In the second form of the operator, the device pixels that would be painted by filling userpath become an "aperture." instroke returns true if any of the pixels in the aperture would be painted by a stroke of the current path in the graphics state. Otherwise, it returns false.

As with infill, this operator ignores the current clipping path and current view clip; that is, it detects a "hit" on any pixel that lies beneath a stroke drawn along the current path, even if stroking that path would not mark the current page due to clipping.

The shape against which the point (x, y) or the aperture, userpath, is tested is computed according to the current, stroke-related parameters in the graphics state: line width, line cap, line join, miter limit, dash pattern, and stroke adjust. If the current line width is zero, the set of pixels considered to be part of the stroke is device dependent.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: infill, inustroke,

stroke

Troubleshooting index Back to Postscript index


internaldict int internaldict dict

pushes the internal dictionary object on the operand stack. The int operand must be the integer 1183615869. The internal dictionary is in local VM and is writable. It contains operators and other information whose purpose is internal to the PostScript interpreter. It should be referenced only in special circumstances, such as during construction of Type 1 font programs.
The contents of internaldict are undocumented and subject to change at any time.

This operator is not present in some PostScript interpreters.

ERRORS: invalidaccess, stackunderflow,

undefined

Troubleshooting index Back to Postscript index


interrupt (error)

processes an external request to interrupt execution of a PostScript language program. When the interpreter receives an interrupt request, it executes interrupt as if it were an error-in other words, it looks up the name interrupt in errordict. Execution of interrupt is sandwiched between execution of two objects being interpreted in normal sequence.

Unlike most other errors, occurrence of an interrupt does not cause the object being executed to be pushed on the operand stack nor does it disturb the operand stack in any way.

The precise nature of an external interrupt request depends on the environment in which the PostScript interpreter is running. For example, in some environments, receipt of a control-C character from a serial communication channel gives rise to the interrupt error. This enables a user to explicitly abort a PostScript computation. The default definition of interrupt executes a stop.
Troubleshooting index Back to Postscript index


inueofill x y userpath inueofill bool
userpath1 userpath2 inueofill bool LEVEL 2

is similar to inufill, but its "insideness" test is based on ueofill instead of ufill.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: inufill, eofill

Troubleshooting index Back to Postscript index


inufill x y userpath inufill bool LEVEL 2
userpath1 userpath2 inufill bool

The first form returns true if the device pixel containing the point (x, y) in user space would be painted by a ufill of the specified userpath . Otherwise, it returns false.

In the second form, the device pixels that would be painted by filling userpath1 become an "aperture." inufill returns true if any of the pixels in the aperture would be painted by a ufill of userpath2. Otherwise, it returns false.

This operator does not place any marks on the current page nor does it disturb the current path in the graphics state. Except for the manner in which the path is specified, inufill behaves the same as infill.

By itself, this operator is seemingly a trivial composition of several other operators:

gsave
newpath uappend
infill
grestore

However, when used with a user path that specifies ucache, inufill can access the user path cache, potentially resulting in improved performance.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: inueofill, infill,

ufill

Troubleshooting index Back to Postscript index


inustroke x y userpath inustroke bool LEVEL 2
x y userpath matrix inustroke bool
userpath1 userpath2 inustroke bool
userpath1 userpath2 matrix inustroke bool

The first form returns true if the device pixel containing the point (x, y) in user space would be painted by a ustroke applied to the same operands. Otherwise it returns false.

In the second form, inustroke concatenates matrix to the CTM after interpreting the user paths, but before computing the stroke (see ustroke operator).

In the third and fourth forms, the device pixels that would be painted by filling userpath1 become an "aperture." inustroke returns true if any of the pixels in the aperture would be painted by a ustroke of userpath2. Otherwise it returns false.

This operator does not place any marks on the current page nor does it disturb the current path in the graphics state. Except for the manner in which the path is specified, inustroke behaves the same as instroke.

As with inufill, if userpath is already present in the user path cache, inustroke can take advantage of the cached information to optimize execution.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: stroke, ustroke,

instroke

Troubleshooting index Back to Postscript index


invalidaccess (error)

An access violation has occurred. Principal causes of invalidaccess are:
SEE ALSO: rcheck, wcheck, gcheck, readonly,

executeonly, noaccess

Troubleshooting index Back to Postscript index


invalidcontext (error) DPS

indicates that an invalid use of the context synchronization facilities has been detected.
Possible causes include:
The PostScript interpreter detects only the simplest types of deadlock.
It is possible to encounter deadlocks for which no invalidcontext error is generated.
Troubleshooting index Back to Postscript index


invalidexit (error)

An exit has been executed for which there is no dynamically enclosing looping context (for example, for, loop,

repeat, or pathforall) or it has attempted to leave the context of a run or stopped operator.

Troubleshooting index Back to Postscript index


invalidfileaccess (error)

The access string specification to the file operator is unacceptable or a file operation has been attempted (for example, deletefile) that is not permitted by the storage device.
Troubleshooting index Back to Postscript index


invalidfont (error)

Either the operand to findfont is not a valid font name or the operand to makefont or setfont is not a well-formed font dictionary. The invalidfont error may also be executed by other font operators upon discovering a font dictionary is malformed.
Troubleshooting index Back to Postscript index


invalidid (error) DPS

indicates that an invalid identifier has been presented to a window system specific operator. In each integration of the Display PostScript system with a window system, there is a collection of window system specific operators. The operands of such operators are usually integers that identify windows and other objects that exist outside the PostScript language. This error occurs when the operand does not identify a valid object. It is generated only by window system specific operators and not by any standard operator.
Troubleshooting index Back to Postscript index


invalidrestore (error)

An improper restore has been attempted. One or more of the operand, dictionary, or execution stacks contains composite objects whose values were created more recently than the save whose context is being restored. Since restore would destroy those values, but the stacks are unaffected by restore, the outcome would be undefined and cannot be allowed.

SEE ALSO: restore, save
Troubleshooting index Back to Postscript index


invertmatrix matrix1 matrix2 invertmatrix matrix2

replaces the value of matrix2 with the result of inverting matrix1 and pushes the modified matrix2 back on the operand stack. The result of inverting a matrix is that if matrix1 transforms a coordinate (x, y) to (x`, y`) then matrix2 transforms (x`, y`) to (x, y).

ERRORS rangecheck, stackunderflow,

typecheck , undefinedresult

SEE ALSO: itransform, idtransform

Troubleshooting index Back to Postscript index


ioerror (error)

An exception other than end-of-file has occurred during execution of one of the file operators. The nature of the exception is environment dependent, but may include such events as parity or checksum errors, or broken network connections. Attempting to write to an input file or to a file that has been closed will also cause an ioerror. Occurrence of an ioerror does not cause the file to become closed unless it was already closed or the error occurs during closefile.
Troubleshooting index Back to Postscript index


ISOLatin1Encoding - ISOLatin1Encoding array LEVEL 2

pushes the ISO Latin-1 encoding vector on the operand stack. This is a 256-element literal array object, indexed by character codes whose values are the character names for those codes. ISOLatin1Encoding is not an operator; it is a name in systemdict associated with the array object.

Roman text fonts produced by Adobe usually use the StandardEncoding encoding vector. However, they contain all the characters needed to support the use of ISOLatin1Encoding.

ERRORS: stackoverflow

SEE ALSO: StandardEncoding, findencoding
Troubleshooting index Postscript Index
itransform x` y` itransform x y
x` y` matrix itransform x y

With no matrix operand, itransform (inverse transform) transforms the device space coordinate (x', y') by the inverse of CTM to produce the corresponding user space coordinate (x, y). If the matrix operand is supplied, itransform transforms (x', y') by the inverse of matrix rather than by the inverse of CTM.

ERRORS: rangecheck, stackunderflow,

typecheck , undefinedresult

SEE ALSO: transform, dtransform,

idtransform, invertmatrix

Troubleshooting index Back to Postscript index


join context join mark obj1 ... objn DPS

waits for the execution context identified by the integer context to finish executing its top-level procedure (the proc operand of fork). It then pushes a mark followed by the entire contents of that context's operand stack onto the current context's operand stack. Finally, it causes the other context to terminate.

The objects obj1 through objn are those left on the operand stack by the context that is terminating. Ordinarily, there should not be a mark among those objects, because its presence might cause confusion in the context that executes the join.

If context is not a valid context identifier, perhaps because the context has terminated prematurely due to executing quit or encountering an error, join executes an invalidcontext error. This also occurs if the context has already been joined or detached, if context identifies the current context, or if the context does not share the current context's
local and global VM.

It is illegal to execute join if there has been any previous save not yet matched by a restore. Attempting to do so will cause an invalidcontext error.

ERRORS: invalidcontext, stackunderflow,

stackoverflow, typecheck

SEE ALSO: fork, detach,

currentcontext

Troubleshooting index Back to Postscript index


known dict key known bool

returns the boolean value true if there is an entry in the dictionary dict whose key is key. Otherwise, it returns false. dict does not have to be on the dictionary stack.

EXAMPLE:

/mydict 5 dict def
mydict /total 0 put
mydict /total known -> true
mydict /badname known -> false

ERRORS: invalidaccess, stackunderflow,

typecheck

SEE ALSO: where, load,

get

Troubleshooting index Back to Postscript index


kshow proc string kshow -

paints the characters of string in a manner similar to show, but allowing program intervention between characters. If the character codes in string are c0, c1, ... cn, kshow proceeds as follows: First it shows c0 at the current point, updating the current point by c0's width. Then it pushes the character codes c0 and c1 on the operand stack (as integers) and executes proc. The proc may perform any actions it wishes; typically, it will modify the current point to affect the subsequent placement of c1. kshow continues by showing c1, pushing c1 and c2 on the stack, executing proc, and so on. It finishes by pushing cn-1 and cn on the stack, executing proc, and finally showing cn.

When proc is called for the first time, the graphics state (in particular, the CTM) is the same as it was at the time kshow was invoked, except that the current point has been updated by the width of c0. Execution of proc is permitted to have any side effects, including changes to the graphics state. Such changes persist from one call of proc to the next and may affect graphical output for the remainder of kshow's execution and afterward.

The name kshow is derived from "kern-show." To kern characters is to adjust the spacing between adjacent pairs of characters in order to achieve a visually pleasing result. The kshow operator enables user-defined kerning and other manipulations, because arbitrary computations can be performed between each pair of characters.

kshow can be applied only to base fonts. If the current font is composite, kshow issues an invalidfont error.

ERRORS: invalidaccess, invalidfont,

nocurrentpoint, stackunderflow,

typecheck

SEE ALSO: show, ashow,

awidthshow, widthshow,

xshow, xyshow,

yshow, cshow

Troubleshooting index Back to Postscript index




Original file name: PSL2ik