Table of Contents

• 1. setgstate
  • 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. Reusable State Configurations
    • 1.6.2. Clipping Path Restoration
    • 1.6.3. Batch Processing
  • 1.7. Common Pitfalls
  • 1.8. Error Conditions
  • 1.9. Implementation Notes
  • 1.10. Graphics State Replacement
  • 1.11. See Also

1. setgstate

Replaces current graphics state from a gstate object.

1.1. Syntax

gstate setgstate → –

1.2. Stack Effects

Table 1. Before

Level	Object
0	gstate (graphics state object)

Table 2. After

Level	Object
(empty)	Graphics state replaced

1.3. Description

setgstate replaces the current graphics state by the value of the gstate object. This is a copying operation, so subsequent modifications to the value of gstate will not affect the current graphics state or vice versa.

This is a wholesale replacement of all components of the graphics state. In particular:

• The current clipping path is replaced by the value in gstate, not intersected with it

• The current path is not affected (it remains unchanged)

• All other graphics parameters are replaced completely

The gstate object itself remains unchanged and can be reused to restore the same state multiple times.

1.4. PostScript Level

Level 2 and later

1.5. Examples

Basic state restoration

% Save current state
gstate /SavedState exch def

% Make changes
2 setlinewidth
1 0 0 setrgbcolor
45 rotate

% Restore original state
SavedState setgstate
% All changes undone

Template-based drawing

% Create state templates
/HeaderStyle {
  /Helvetica-Bold findfont 18 scalefont setfont
  0 setgray
  gstate
} def

/BodyStyle {
  /Times-Roman findfont 12 scalefont setfont
  0.3 setgray
  gstate
} def

% Use templates
/header HeaderStyle def
/body BodyStyle def

header setgstate
100 700 moveto (Title) show

body setgstate
100 650 moveto (Content) show

Multiple state switching

% Save initial state
gstate /InitState exch def

% Create and save modified state
0.5 setgray
3 setlinewidth
gstate /ThickGray exch def

% Create another state
1 0 0 setrgbcolor
0.5 setlinewidth
gstate /ThinRed exch def

% Switch between states
ThickGray setgstate
drawOutline stroke

ThinRed setgstate
drawDetails stroke

InitState setgstate
% Back to original

State preservation during complex operations

/ComplexDrawing {
  % Save state
  gstate /temp exch def

  % Perform many modifications
  matrix currentmatrix
  userMatrix concat
  customColorSpace setcolorspace
  customHalftone sethalftone

  % Do drawing
  drawComplexShape

  % Restore everything at once
  temp setgstate
} def

1.6. Common Use Cases

1.6.1. Reusable State Configurations

% Define standard states
/StandardStates <<
  /Header {
    /Helvetica-Bold findfont 14 scalefont setfont
    0 setgray
    1 setlinewidth
    gstate
  } def
  /Body {
    /Times-Roman findfont 10 scalefont setfont
    0 setgray
    0.5 setlinewidth
    gstate
  } def
  /Caption {
    /Helvetica findfont 8 scalefont setfont
    0.4 setgray
    0.25 setlinewidth
    gstate
  } def
>> def

% Use throughout document
StandardStates /Header get setgstate

1.6.2. Clipping Path Restoration

% Save state with clip
gstate /BeforeClip exch def

% Establish restrictive clip
newpath
0 0 100 100 rectclip

% Draw clipped content
drawContent

% Restore clip (and everything else)
BeforeClip setgstate
% Clip is now unrestricted again

1.6.3. Batch Processing

% Process items with consistent state
gstate /ProcessState exch def

items {
  ProcessState setgstate  % Reset to known state
  processItem
} forall

1.7. Common Pitfalls

Clipping Path Replaced - setgstate replaces the clipping path, not intersects.

% Save state
gstate /saved exch def

% Establish clip
newpath 0 0 100 100 rectclip

% Restore state - clip is GONE, not combined
saved setgstate

Current Path Unchanged - The current path is NOT saved in gstate.

newpath 0 0 moveto 100 100 lineto
gstate /temp exch def

newpath  % Clear path
temp setgstate
% Path is still empty, not restored

Not for Simple Save/Restore - Use gsave/grestore for temporary changes.

% Inefficient
gstate /temp exch def
modifyState
temp setgstate

% Better
gsave
modifyState
grestore

Reusable Templates - Create gstate objects once, reuse many times.

1.8. Error Conditions

Error	Condition
[stackunderflow]	No operand on stack
[typecheck]	Operand not a gstate object

1.9. Implementation Notes

• Copying operation - gstate object unchanged

• Replaces all graphics state components

• Clipping path is replaced, not intersected

• Current path is not affected

• Very fast operation

• gstate can be reused indefinitely

• More efficient than multiple parameter sets

1.10. Graphics State Replacement

setgstate replaces:

• ✓ Transformation matrix (CTM)

• ✓ Color space and color

• ✓ Line width, cap, join, dash, miter limit

• ✓ Current font

• ✓ Clipping path (replaced, not intersected)

• ✓ Flatness, stroke adjustment

• ✓ Halftone, transfer, black generation

• ✗ Current path (never saved/restored)

1.11. See Also

• gstate - Create graphics state object

• currentgstate - Update gstate with current state

• gsave - Save state on graphics state stack

• grestore - Restore state from stack

• grestoreall - Restore all saved states