Table of Contents

• 1. clippath
  • 1.1. Syntax
  • 1.2. Stack Effects
  • 1.3. Description
  • 1.4. PostScript Level
  • 1.5. Examples
  • 1.6. Common Use Cases
    • 1.6.1. Determining Available Drawing Area
    • 1.6.2. Clearing the Clipped Area
    • 1.6.3. Drawing Clip Region Border
    • 1.6.4. Inverting the Clip Region
  • 1.7. Common Pitfalls
  • 1.8. Error Conditions
  • 1.9. Implementation Notes
  • 1.10. Interaction with Graphics State
  • 1.11. Best Practices
    • 1.11.1. Save/Restore Around Use
    • 1.11.2. Use for Page Setup
    • 1.11.3. Combine with pathbbox
  • 1.12. Advanced Techniques
    • 1.12.1. Centering Content in Clip Region
    • 1.12.2. Tiling Within Clip Region
    • 1.12.3. Creating Margin Guides
  • 1.13. Performance Considerations
  • 1.14. Common Patterns
  • 1.15. See Also

1. clippath

Sets the current path to the current clipping path.

1.1. Syntax

- clippath → -

1.2. Stack Effects

Table 1. Before

Level	Object
(empty)	No operands required

Table 2. After

Level	Object
(empty)	No results (current path is set)

1.3. Description

clippath sets the current path to one that describes the current clipping path. This operator is useful for determining the exact extent of the imaging area on the current output device.

If the current clipping path is the result of application of the clip or eoclip operator, the path set by clippath is generally suitable only for filling or clipping. It is not suitable for stroking because it may contain interior segments or disconnected subpaths produced by the clipping process.

The path returned by clippath describes the clipping region as it exists in user space coordinates, transformed through the current transformation matrix (CTM).

1.4. PostScript Level

Level 1 and later

1.5. Examples

Getting the current clip bounds

clippath
pathbbox  % Returns llx lly urx ury
% Now know the bounding box of clip region

Erasing within the clip region

clippath
1 setgray
fill      % Erase (fill with white) the clip area

Stroking the clip boundary

gsave
  clippath
  2 setlinewidth
  0 setgray
  stroke  % Draw border around clip region
grestore

1.6. Common Use Cases

1.6.1. Determining Available Drawing Area

/getClipBounds {
  % Returns: llx lly urx ury
  clippath
  pathbbox
} def

getClipBounds
% Stack: llx lly urx ury

1.6.2. Clearing the Clipped Area

/clearClip {
  % Fill clip region with white
  gsave
    clippath
    1 setgray
    fill
  grestore
} def

clearClip

1.6.3. Drawing Clip Region Border

/showClipBorder {
  % Draw visible border of clip
  gsave
    clippath
    0 setgray
    1 setlinewidth
    stroke
  grestore
} def

showClipBorder

1.6.4. Inverting the Clip Region

/invertClip {
  % Fill everything outside clip
  gsave
    % Get clip bounds
    clippath pathbbox
    /ury exch def
    /urx exch def
    /lly exch def
    /llx exch def

    % Create inverse path
    newpath
    % Large outer rectangle
    llx 1000 sub lly 1000 sub moveto
    urx 1000 add lly 1000 sub lineto
    urx 1000 add ury 1000 add lineto
    llx 1000 sub ury 1000 add lineto
    closepath

    % Subtract clip region
    clippath

    % Fill with even-odd
    eofill
  grestore
} def

1.7. Common Pitfalls

Result May Not Be Suitable for Stroking - If the clip was created with clip or eoclip, the path may have interior segments.

% After complex clip operation
clip
newpath

clippath
stroke  % May show unexpected interior lines

% Better for filling or getting bounds
clippath
fill    % Suitable use

Path Is in User Space - The clip path is transformed to current user space coordinates.

% After scaling
2 2 scale

clippath  % Returns coordinates in scaled space
pathbbox  % Bounds reflect current CTM

Replaces Current Path - clippath replaces any existing current path.

newpath
100 100 moveto
200 200 lineto

clippath  % Previous path is lost

Use for Bounds Checking - clippath with pathbbox gives exact drawable area:

clippath
pathbbox
/height exch 3 index sub def
/width exch 3 index sub def
pop pop  % Remove llx lly
% width and height now available

1.8. Error Conditions

None. clippath cannot generate errors.

1.9. Implementation Notes

• The path set by clippath may be complex if multiple clip operations were performed

• The path accurately represents the intersection of all previous clip operations

• The path is always closed and suitable for filling

• Device-default clip paths are typically rectangular

• The path is transformed to user space via the inverse CTM

1.10. Interaction with Graphics State

clippath is affected by:

• Current clipping path - This is what gets returned

• Current transformation matrix (CTM) - Path is returned in user space

clippath affects:

• Current path - Replaced with the clip path

• Nothing else in graphics state

1.11. Best Practices

1.11.1. Save/Restore Around Use

gsave
  clippath
  % Use clip path
  % ...
grestore
% Original path restored

1.11.2. Use for Page Setup

% At document start, get page bounds
clippath
pathbbox
/pageHeight exch 3 index sub def
/pageWidth exch 3 index sub def
/pageBottom exch def
/pageLeft exch def

% Use throughout document
% ...

1.11.3. Combine with pathbbox

/getDrawingArea {
  % Returns: width height
  clippath
  pathbbox
  % Stack: llx lly urx ury
  exch 3 index sub  % height
  3 1 roll
  exch sub          % width
  exch
} def

getDrawingArea
% Stack: width height

1.12. Advanced Techniques

1.12.1. Centering Content in Clip Region

/centerInClip {
  % contentWidth contentHeight centerInClip -> x y
  /ch exch def
  /cw exch def

  clippath pathbbox
  /ury exch def
  /urx exch def
  /lly exch def
  /llx exch def

  % Calculate center position
  llx urx add 2 div cw 2 div sub
  lly ury add 2 div ch 2 div sub
} def

% Usage:
100 50 centerInClip  % Center 100x50 content
% Stack: x y

1.12.2. Tiling Within Clip Region

/tileInClip {
  % tileWidth tileHeight proc tileInClip
  /proc exch def
  /th exch def
  /tw exch def

  clippath pathbbox
  /ury exch def
  /urx exch def
  /lly exch def
  /llx exch def

  lly th ury {
    /y exch def
    llx tw urx {
      /x exch def
      gsave
        x y translate
        proc exec
      grestore
    } for
  } for
} def

1.12.3. Creating Margin Guides

/drawMargins {
  % margin drawMargins - draws margin guides
  /m exch def

  clippath pathbbox
  /ury exch def
  /urx exch def
  /lly exch def
  /llx exch def

  gsave
    [3 3] 0 setdash
    0.5 setgray
    0.5 setlinewidth

    newpath
    llx m add lly m add moveto
    urx m sub lly m add lineto
    urx m sub ury m sub lineto
    llx m add ury m sub lineto
    closepath
    stroke
  grestore
} def

20 drawMargins  % 20-point margins

1.13. Performance Considerations

• clippath is a fast operation

• The complexity of the returned path depends on clipping history

• Very complex clipping paths may result in large path structures

• Using pathbbox after clippath is efficient for bounds checking

• No rendering is performed by clippath itself

1.14. Common Patterns

Get clip dimensions

clippath pathbbox
3 index sub /height exch def
2 index sub /width exch def
pop pop

Fill clip with color

0.9 setgray
clippath fill

Test if point in clip

/inClip {
  % x y inClip -> bool
  gsave
    clippath
    infill  % or ineofill depending on clip
  grestore
} def

1.15. See Also

• clip - Set clipping path (non-zero winding)

• eoclip - Set clipping path (even-odd rule)

• initclip - Reset to device default

• rectclip - Clip to rectangles (Level 2)

• pathbbox - Get path bounding box

• infill - Test if point inside path

• gsave - Save graphics state

• grestore - Restore graphics state

• newpath - Clear current path