currentgstate

1.1. Syntax

gstate currentgstate → gstate

1.2. Stack Effects

Table 1. Before
Level	Object
0	`gstate` (graphics state object)

Table 2. After
Level	Object
0	`gstate` (updated with current state)

1.3. Description

currentgstate replaces the value of the gstate object by a copy of the current graphics state and pushes gstate back on the operand stack.

This is a copying operation that updates an existing gstate object rather than creating a new one. This is more efficient than creating a new gstate with gstate when you already have a gstate object to reuse.

The gstate object must have been previously created by gstate. After the operation, the gstate contains a snapshot of:

Current transformation matrix (CTM)
Color space and color values
Line parameters (width, cap, join, dash, miter limit)
Current font
Clipping path
All other graphics state parameters

The current path is not saved in the gstate object.

1.4. PostScript Level

Level 2 and later

1.5. Examples

Updating existing gstate

% Create gstate once
gstate /MyState exch def

% Later, capture current state
MyState currentgstate pop

% Can be used multiple times
modifyState
MyState currentgstate pop  % Update again

Efficient state monitoring

% Create gstate for snapshots
gstate /snapshot exch def

% Take multiple snapshots
initialSetup
snapshot currentgstate pop

moreChanges
snapshot currentgstate pop

finalChanges
snapshot currentgstate pop

State comparison

% Save initial state
gstate /before exch def

% Make changes
2 2 scale
1 0 0 setrgbcolor

% Capture modified state
gstate /after exch def

% Can now switch between them
before setgstate  % Original state
after setgstate   % Modified state

Reusing gstate objects

% Create gstate once
gstate /StateBuffer exch def

% Efficient state capture loop
items {
  /item exch def

  % Capture state before processing
  StateBuffer currentgstate pop

  % Process item (may modify state)
  item process

  % Restore state for next iteration
  StateBuffer setgstate
} forall

1.6. Common Use Cases

1.6.1. State Snapshots in Loops

% Create snapshot buffer
gstate /snapshot exch def

% Take snapshots efficiently
1 1 100 {
  % Capture current state
  snapshot currentgstate pop

  % Modify and draw
  dup scale
  drawShape

  % Restore
  snapshot setgstate
} for

1.6.2. Preserving State Templates

% Create template states
gstate /HeaderState exch def
gstate /BodyState exch def

% Configure header
/Helvetica-Bold findfont 18 scalefont setfont
0 setgray
HeaderState currentgstate pop

% Configure body
/Times-Roman findfont 12 scalefont setfont
0.3 setgray
BodyState currentgstate pop

% Use templates
HeaderState setgstate
drawHeader

BodyState setgstate
drawBody

1.6.3. State Diff Detection

% Capture state before operation
gstate /beforeState exch def

% Perform operation
complexOperation

% Check if state changed
gstate /afterState exch def
beforeState setgstate  % Restore if needed

1.7. Common Pitfalls

Global VM Restrictions - If gstate is in global VM, currentgstate fails if current state contains local VM objects.

true setglobal
gstate /globalState exch def
false setglobal

/LocalFont /Helvetica findfont def
globalState currentgstate pop  % Error: invalidaccess

Must Use Existing gstate - currentgstate requires a pre-existing gstate object.

% Wrong: trying to use a dict
10 dict currentgstate  % Error: typecheck

% Right: use gstate object
gstate currentgstate pop

Current Path Not Saved - The current path is never included in gstate.

newpath 0 0 moveto 100 100 lineto
gstate dup currentgstate setgstate
% Path is lost

Reuse gstate Objects - More efficient than creating new ones repeatedly.

1.8. Error Conditions

Error Condition

Error	Condition
[`invalidaccess`]	gstate in global VM but current state contains local VM objects
[`stackunderflow`]	No operand on stack
[`typecheck`]	Operand not a gstate object

[invalidaccess]

gstate in global VM but current state contains local VM objects

[stackunderflow]

No operand on stack

[typecheck]

Operand not a gstate object

1.9. Implementation Notes

Updates existing gstate object (doesn’t create new one)
More efficient than gstate when reusing objects
Returns same gstate object (for convenience)
Captures complete graphics state except current path
Fast operation suitable for frequent use
Ideal for state snapshots in loops

Operator Purpose

Operator	Purpose
`gstate`	Creates new gstate object with current state (allocates VM)
`currentgstate`	Updates existing gstate with current state (no allocation)
`setgstate`	Replaces current state from gstate object
`gsave`	Saves current state on graphics state stack
`grestore`	Restores state from graphics state stack

gstate

Creates new gstate object with current state (allocates VM)

currentgstate

Updates existing gstate with current state (no allocation)

setgstate

Replaces current state from gstate object

gsave

Saves current state on graphics state stack

grestore

Restores state from graphics state stack