1. ufill

Interprets a user path definition and fills the resulting path.

1.1. Syntax 

userpath ufill → -

1.2. Stack Effects

Table 1. Before
Level Object

0

userpath (array, packed array, or string)
Table 2. After
Level Object

(empty)

No results

1.3. Description

ufill 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

The userpath operand can be:

  • An ordinary array or packed array (length ≥ 5) containing path construction operators

  • An encoded user path string for efficient representation

User paths must begin with setbbox (optionally preceded by ucache) to define the bounding box.

1.4. PostScript Level

Level 2 and later

1.5. Examples

Simple user path fill
[
  50 50 250 250 setbbox
  100 100 moveto
  200 100 lineto
  200 200 lineto
  100 200 lineto
  closepath
] ufill
User path with caching
[
  ucache
  50 50 250 250 setbbox
  150 150 moveto
  250 150 lineto
  250 250 lineto
  150 250 lineto
  closepath
] ufill
Circle with user path
[
  100 100 300 300 setbbox
  200 200 50 0 360 arc
  closepath
] ufill

1.6. Common Use Cases

1.6.1. Efficient Repeated Fills 

% Define reusable user path
/squarePath [
  ucache  % Enable caching
  0 0 100 100 setbbox
  10 10 moveto
  90 10 lineto
  90 90 lineto
  10 90 lineto
  closepath
] def

% Use multiple times efficiently
0.3 setgray
squarePath ufill

100 100 translate
0.6 setgray
squarePath ufill

1.6.2. Complex Shape Definition 

/starPath [
  ucache
  50 50 250 250 setbbox
  150 230 moveto
  170 170 lineto
  230 150 lineto
  170 130 lineto
  150 70 lineto
  130 130 lineto
  70 150 lineto
  130 170 lineto
  closepath
] def

starPath ufill

1.6.3. Parameterized User Paths 

/makeRectPath {
  % x y width height makeRectPath => userpath
  /h exch def
  /w exch def
  /y exch def
  /x exch def

  [
    ucache
    x y x w add y h add setbbox
    x y moveto
    w 0 rlineto
    0 h rlineto
    w neg 0 rlineto
    closepath
  ]
} def

100 100 80 60 makeRectPath ufill

1.7. Common Pitfalls

Must Include setbbox - User paths must begin with setbbox (optionally preceded by ucache). 
% Wrong - no setbbox
[
  100 100 moveto
  200 200 lineto
] ufill  % Error: rangecheck

% Correct
[
  50 50 250 250 setbbox
  100 100 moveto
  200 200 lineto
] ufill
Graphics State Not Modified - ufill automatically saves and restores the graphics state. 
0.5 setgray
[
  0 0 100 100 setbbox
  10 10 moveto
  90 90 lineto
] ufill
% Gray is still 0.5, path is empty
Use ucache for Repeated Paths - Include ucache as the first element for paths that will be reused: 
/myPath [
  ucache  % Cache this path
  0 0 100 100 setbbox
  % ... path construction ...
] def

% Efficient reuse
myPath ufill
myPath ufill  % Uses cached version

1.8. Error Conditions

Error Condition

[invalidaccess]

User path array is not executable or has insufficient access

[limitcheck]

Path becomes too complex for implementation

[rangecheck]

User path is malformed (missing setbbox, coordinates out of bounds)

[stackunderflow]

No operand on stack

[typecheck]

Operand is not a valid user path

1.9. Implementation Notes

  • User paths provide more efficient path construction than traditional operators

  • Cached user paths (with ucache) are stored for reuse

  • The bounding box enables optimization of path rendering

  • Coordinates are validated against the bounding box

  • User paths can be encoded as strings for maximum efficiency

1.10. User Path Format

A user path must be an array (or packed array) containing:

  1. Optionally, ucache as the first element

  2. setbbox with four coordinates (required)

  3. Path construction operators: moveto, lineto, curveto, arc, arcn, arct, closepath, etc.

[
  ucache              % Optional
  llx lly urx ury setbbox  % Required
  % Path operators...
  x y moveto
  x2 y2 lineto
  closepath
]

1.11. Comparison with Traditional Fill

Traditional fill approach
gsave
newpath
100 100 moveto
200 100 lineto
200 200 lineto
100 200 lineto
closepath
fill
grestore
User path approach (ufill)
[
  50 50 250 250 setbbox
  100 100 moveto
  200 100 lineto
  200 200 lineto
  100 200 lineto
  closepath
] ufill

Benefits of user paths:

  • More compact representation

  • Can be cached for efficiency

  • Automatic graphics state management

  • Potential for optimization by interpreter

1.12. Best Practices

1.12.1. Always Include Accurate Bounding Box 

% Calculate tight bounding box
/llx 100 def
/lly 100 def
/urx 200 def
/ury 200 def

[
  llx lly urx ury setbbox
  % Use same coordinates in path
  llx lly moveto
  urx lly lineto
  urx ury lineto
  llx ury lineto
  closepath
] ufill

1.12.2. Use ucache for Frequently Used Paths 

/buttonPath [
  ucache  % Cache for reuse
  0 0 120 40 setbbox
  5 5 moveto
  115 5 lineto
  115 35 lineto
  5 35 lineto
  closepath
] def

% Efficient reuse throughout document
10 {
  buttonPath ufill
  0 50 translate
} repeat

1.12.3. Combine with Other User Path Operators 

/myPath [
  ucache
  0 0 100 100 setbbox
  50 50 40 0 360 arc
  closepath
] def

% Fill
0.8 setgray
myPath ufill

% Stroke same path
0 setgray
1 setlinewidth
myPath ustroke

1.13. Performance Considerations

  • User paths are generally faster than traditional path construction

  • Cached user paths (ucache) provide significant performance benefits for reuse

  • Encoded user paths (strings) are most efficient but harder to construct

  • Accurate bounding boxes enable better optimization

  • Very complex user paths may still exceed limits

1.14. See Also

  • fill - Traditional fill operator

  • ueofill - Even-odd fill user path

  • ustroke - Stroke user path

  • setbbox - Set bounding box

  • ucache - Enable user path caching

  • uappend - Append user path to current path

  • gsave - Save graphics state

  • grestore - Restore graphics state

Back to top

Copyright © 2025 Ribose. PostScript is a trademark of Adobe. Distributed under the MIT License.