Postscript Operators 'u'




uappend userpath uappend - LEVEL 2

interprets a user path definition and appends the result to the current path in the graphics state.
If userpath is an ordinary user path (in other words, an array or packed array whose length is at least 5),
uappend is equivalent to:

systemdict begin % Ensure standard operator meanings
cvx exec % Interpret userpath
end

If userpath is an encoded user path, uappend interprets it and performs the encoded operations. It does not matter whether the userpath object is literal or executable.

Note that uappend uses the standard definitions of all operator names mentioned in the user path, unaffected by any name redefinition that may have occurred.

A ucache appearing in userpath may or may not have an effect, depending on the environment in which uappend is executed. If the current path is initially empty and no path construction operators are executed after uappend, a subsequent painting operator may access the user path cache. Otherwise, it definitely will not. This is particularly useful in the case of clip and viewclip.

uappend performs a temporary adjustment to the current transformation matrix as part of its execution. This adjustment consists of rounding the tx and ty components of the CTM to the nearest integer values.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: upath, ucache

Troubleshooting index Back to Postscript index


ucache - ucache - LEVEL 2

notifies the PostScript interpreter that the enclosing user path is to be retained in the cache if it is not already there. If present, this operator must appear as the first element of a user path definition (before the mandatory

setbbox).

The ucache operator has no effect of its own when executed; if executed outside a user path definition, it does nothing. It is useful only with a user path painting operator, such as ufill or ustroke, that takes the user path as an operand. If the user path is not already in the cache, the painting operator performs the path construction operations specified in the user path and places the results (referred to as the reduced path) in the cache. If the user path is already present in the cache, the painting operator does not interpret the user path, but rather obtains the reduced path from the cache.

ERRORS: (none)

SEE ALSO: uappend, upath

Troubleshooting index Back to Postscript index


ucachestatus - ucachestatus mark bsize bmax rsize rmax blimit LEVEL 2

reports the current consumption and limit for two user path cache resources: bytes of reduced path storage (bsize and bmax) and total number of cached reduced paths (rsize and rmax).
It also reports the limit on the number of bytes occupied by a single reduced path (blimit)-reduced paths that are larger than this are not cached. All ucachestatus results except blimit are for information only. A PostScript language program can change blimit (see setucacheparams).

The number of values pushed on the operand stack is variable. Future versions of the PostScript interpreter may push additional values between mark and bsize. The purpose of the mark is to delimit the values returned by ucachestatus. This enables a program to determine how many values were returned (by counttomark) and to discard any unused ones (by cleartomark).

The bsize, bmax, and blimit parameters reported by ucachestatus are the same as the CurUPathCache and MaxUPathCache system parameters and MaxUPathItem user parameter reported by currentsystemparams and currentuserparams, respectively.

ERRORS: stackoverflow

SEE ALSO: setucacheparams, setsystemparams,

setuserparams

Troubleshooting index Back to Postscript index


ueofill userpath ueofill - LEVEL 2

is similar to ufill, but does eofill instead of fill.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: eofill, ufill

Troubleshooting index Back to Postscript index


ufill userpath ufill - LEVEL 2

interprets a user path definition and fills the resulting path as if by fill. The entire operation is effectively enclosed by gsave and grestore, so ufill has no lasting effect on the graphics state.
ufill is equivalent to:

gsave newpath uappend fill grestore

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: fill, uappend, ueofill

Troubleshooting index Back to Postscript index


undef dict key undef - LEVEL 2

removes key and its associated value from the dictionary dict. dict does not need to be on the dictionary stack.
No error occurs if key is not present in dict.

If the value of dict is in local VM, the effect of undef can be undone by a subsequent restore.
That is, if key was present in dict at the time of the matching save, restore will reinstate key and its former value.
But if dict is in global VM, the effect of undef is permanent.

ERRORS: invalidaccess, stackunderflow,

typecheck

SEE ALSO: def, put,

undefinefont

Troubleshooting index Back to Postscript index


undefined (error)

A name used as a dictionary key in some context cannot be found. This occurs if a name is looked up explicitly in a specified dictionary ( get) or in the current dictionary stack ( load) and is not found. It also occurs if an executable name is encountered by the interpreter and is not found in any dictionary on the dictionary stack.

A few PostScript operators are disabled in certain contexts-for example, it is illegal to execute image, or operators that specify colors or set color-related parameters in the graphics state, after a setcachedevice or setcachedevice2 in a BuildChar or BuildGlyph procedure. Attempting to execute such disabled operators results in an undefined error.

SEE ALSO: known, where,

load, exec,

get

Troubleshooting index Back to Postscript index


undefinedfilename (error)

A file identified by a name string operand of file, run, deletefile, or renamefile cannot be found or cannot be opened.
The undefinedfilename error also occurs if the special file %statementedit or %lineedit is opened when the standard input file has reached end-of-file.
Troubleshooting index Back to Postscript index


undefinedresource (error) LEVEL 2

A named resource instance sought by findresource cannot be found; that is, no such instance exists either in VM or in external storage. This error arises only in the case of findresource with a defined resource category.
If the category itself is not defined, resource operators execute the undefined error.

SEE ALSO: findresource
Troubleshooting index Back to Postscript index


undefinedresult (error)

A numeric computation would produce a meaningless result or one that cannot be represented as a number. Possible causes include numeric overflow or underflow, division by zero, or inverse transformation of a non-invertible matrix. A large number of graphics and font operators can generate an undefinedresult error if the CTM is not invertible (scaled by zero, for instance).
Troubleshooting index Back to Postscript index


undefinefont key undefinefont - LEVEL 2

removes key and its associated value (a font dictionary) from the font directory, reversing the effect of a previous definefont. undefinefont is a special case of the undefineresource operator applied to the Font category.

ERRORS: stackunderflow, typecheck

SEE ALSO: definefont, undefineresource
Troubleshooting index Back to Postscript index


undefineresource key category undefineresource - LEVEL 2

removes the named resource instance identified by key from the specified category.
This undoes the effect of a previous defineresource. If no such resource instance exists in VM, undefineresource does nothing; no error occurs. However, the resource category must exist, or else an undefined error occurs.

Local and global resource definitions are maintained separately; the precise effect of undefineresource depends on the current VM allocation mode:
Depending on the resource category, undefineresource may have other side effects . However, it does not alter the resource instance in any way. If the instance is still accessible (say, stored directly in some dictionary or defined as a resource under another name), it can still be used in whatever ways are appropriate. The object becomes a candidate for garbage collection only if it is no longer accessible.

The effect of undefineresource is subject to normal VM semantics. In particular, removal of a local resource instance can be undone by a subsequent non-nested restore. In this case, the resource instance is not a candidate for garbage collection.

undefineresource removes the resource instance definition from VM only. If the resource instance also exists in external storage, it can still be found by findresource, resourcestatus, and resourceforall.

ERRORS: stackunderflow, typecheck , undefined

SEE ALSO: defineresource, findresource,

resourcestatus, resourceforall

Troubleshooting index Back to Postscript index


undefineuserobject index undefineuserobject - LEVEL 2

breaks the association between the non-negative integer index and an object established by some previous execution of defineuserobject. It does so simply by replacing the specified UserObjects array element by the null object. This is equivalent to:

userdict /UserObjects get
exch null put

undefineuserobject does not take any other actions such as shrinking the

UserObjects array.
If index is not a valid index for the existing UserObjects array, a rangecheck error occurs.

There is no need to execute undefineuserobject prior to executing a defineuserobject that reuses the same index.
The purpose of undefineuserobject is to eliminate references to objects that are no longer needed.
This may enable the garbage collector to reclaim such objects.

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: defineuserobject, UserObjects

Troubleshooting index Back to Postscript index


unmatchedmark (error)

A mark object is sought on the operand stack by the ],

>>, cleartomark,

counttomark, fork,

setcacheparams, or setucacheparams operator, but none is present.

Troubleshooting index Back to Postscript index


unregistered (error)

An operator object has been executed for which the interpreter has no built-in action. This represents an internal malfunction in the PostScript interpreter and should not occur.
Troubleshooting index Back to Postscript index


upath bool upath userpath LEVEL 2

creates a new user path object that is equivalent to the current path in the graphics state. upath creates a new executable array object of the appropriate length and fills it with the operands and operators needed to describe the current path. upath produces only an ordinary user path array, not an encoded user path. It does not disturb the current path in the graphics state.

The bool operand specifies whether the resulting user path is to include ucache as its first element.

Since the current path's coordinates are maintained in device space, upath transforms them to user space using the inverse of the CTM while constructing the user path. Applying uappend to the resulting user path will reproduce the same current path in the graphics state, but only if the same CTM is in effect at that time.

upath is equivalent to:

[
exch /{

/ucache cvx} if
pathbbox /setbbox cvx
/{

/moveto cvx} /{

/lineto cvx} /{

/curveto cvx} /{

/closepath cvx} pathforall
] cvx

If charpath was used to construct any portion of the current path from a font whose outlines are protected, upath is not allowed. Its execution will produce an invalidaccess error (see

charpath).

ERRORS: invalidaccess, stackunderflow,

typecheck, VMerror

SEE ALSO: uappend, ucache,

pathforall

Troubleshooting index Back to Postscript index


userdict - userdict dict

pushes the dictionary object userdict on the operand stack. userdict is not an operator; it is a name in systemdict associated with the dictionary object.

ERRORS: stackoverflow

SEE ALSO: systemdict, globaldict,

errordict

Troubleshooting index Back to Postscript index


UserObjects - UserObjects array LEVEL 2

returns the current UserObjects array defined in userdict. UserObjects is not an operator; it is simply a name associated with an array in userdict. This array is created and managed by the operators defineuserobject,

undefineuserobject, and execuserobject. It defines a mapping from small integers (used as array indices) to arbitrary objects (the elements of the array).

The UserObjects entry in userdict is present only if defineuserobject has been executed at least once by the current execution context or a context that shares the same local VM. The length of the array depends on the index operands of all previous executions of defineuserobject.

Note that defineuserobject, undefineuserobject, and execuserobject operate on the value of UserObjects in userdict, without regard to the dictionaries currently on the dictionary stack. Defining UserObjects in some other dictionary on the dictionary stack changes the value returned by executing the name object UserObjects, but does not alter the behavior of the user object operators.

Although UserObjects is an ordinary array object, it should be manipulated only by the user object operators. Improper direct alteration of UserObjects can subsequently cause the user object operators to malfunction.

ERRORS: stackoverflow, undefined

SEE ALSO: defineuserobject, undefineuserobject,

execuserobject

Troubleshooting index Back to Postscript index


usertime - usertime int

returns the value of a clock that increments by 1 for every millisecond of execution by the PostScript interpreter. The value has no defined meaning in terms of calendar time or time of day; its only use is interval timing. The accuracy and stability of the clock depends on the environment in which the PostScript interpreter is running. As the time value becomes greater than the largest integer allowed in the implementation, it wraps to the smallest (most negative) integer.

In a Display PostScript system that supports multiple execution contexts, the value returned by usertime reports execution time on behalf of the current context only. A context that executes usertime can subsequently execute with reduced efficiency, because in order to perform user time accounting, the PostScript interpreter must perform an operating system call whenever it switches control to and from that context. Therefore, one should not execute usertime gratuitously.

ERRORS: stackoverflow

SEE ALSO: realtime
Troubleshooting index Postscript Index

ustroke userpath ustroke
- userpath matrix ustroke - LEVEL 2

interprets a user path definition and strokes the resulting path as if by

stroke. The entire operation is effectively enclosed by gsave and grestore, so ustroke has no lasting effect on the graphics state

In the first form (with no matrix operand), ustroke is equivalent to:

gsave newpath uappend stroke grestore

In the second form, ustroke concatenates matrix to the CTM after interpreting userpath, but before executing stroke. The matrix applies to the line width and the dash pattern, if any, but not to the path itself. This form of ustroke is equivalent to:

gsave
newpath
exch uappend % Interpret userpath
concat % Concat matrix to CTM
stroke
grestore

The main use of the second form of ustroke is to compensate for variations in line width and dash pattern that occur if the CTM has been scaled by different amounts in x and y. This is accomplished by defining matrix to be the inverse of the unequal scaling transformation.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: stroke, uappend

Troubleshooting index Back to Postscript index


ustrokepath userpath ustrokepath - LEVEL 2
userpath matrix ustrokepath

- replaces the current path with one enclosing the shape that would result if the ustroke operator were applied to the same operands. The path resulting from ustrokepath is suitable as the implicit operand to a subsequent fill,

clip, or pathbbox. In general, this path is not suitable for stroke, as it may contain interior segments or disconnected subpaths produced by ustrokepath's stroke to outline conversion process.

In the first form, ustrokepath is equivalent to:

newpath uappend strokepath


In the second form, ustrokepath is equivalent to:

newpath
exch uappend % Interpret userpath
matrix currentmatrix % Save CTM
exch concat % Concat matrix to CTM
strokepath % Compute outline of stroke
setmatrix % Restore original CTM


ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

SEE ALSO: ustroke, strokepath

Troubleshooting index Back to Postscript index




Original file name: PS.html