Table of Contents

• 1. gstate
  • 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. Preserving Graphics State
    • 1.6.2. Multiple State Snapshots
    • 1.6.3. State Templates
  • 1.7. Common Pitfalls
  • 1.8. Error Conditions
  • 1.9. Implementation Notes
  • 1.10. Graphics State Components
  • 1.11. See Also

1. gstate

Creates a graphics state object.

1.1. Syntax

– gstate → gstate

1.2. Stack Effects

Table 1. Before

Level	Object
(empty)	–

Table 2. After

Level	Object
0	gstate (graphics state object)

1.3. Description

gstate creates a new gstate (graphics state) object and pushes it on the operand stack. Its initial value is a copy of the current graphics state, including all graphics parameters such as:

• Current transformation matrix (CTM)

• Color space and color

• Line width, cap, join, and dash pattern

• Miter limit

• Current font

• Clipping path

• And all other graphics state parameters

This operator consumes VM; it is the only graphics state operator that does. The gstate is allocated in either local or global VM according to the current VM allocation mode.

The gstate object can later be used with setgstate to restore the graphics state to the captured values, or with currentgstate to update the saved state.

1.4. PostScript Level

Level 2 and later

1.5. Examples

Creating and using gstate

gstate                  % Create gstate object
/MyState exch def       % Save it

% Modify graphics state
2 2 scale
0.5 setgray
3 setlinewidth

% Restore previous state
MyState setgstate

Saving multiple states

% Save initial state
gstate /InitialState exch def

% Make some changes
1 0 0 setrgbcolor
/Helvetica findfont 12 scalefont setfont

% Save modified state
gstate /ModifiedState exch def

% Switch between states
InitialState setgstate   % Back to initial
ModifiedState setgstate  % To modified

State management in procedures

/DrawWithState {
  % Create state snapshot
  gstate

  % Draw with custom settings
  0.5 setlinewidth
  1 0 0 setrgbcolor
  drawShape

  % Restore state
  setgstate
} def

1.6. Common Use Cases

1.6.1. Preserving Graphics State

% Save entire state for later
gstate /SavedState exch def

% Do complex operations
modifyManyParameters
drawComplexGraphic

% Restore everything at once
SavedState setgstate

1.6.2. Multiple State Snapshots

/StateLibrary 10 dict def

% Save different states
gstate StateLibrary /NormalState 3 -1 roll put
1 0 0 setrgbcolor
gstate StateLibrary /RedState 3 -1 roll put
0 1 0 setrgbcolor
gstate StateLibrary /GreenState 3 -1 roll put

% Use saved states
StateLibrary /RedState get setgstate
StateLibrary /NormalState get setgstate

1.6.3. State Templates

% Create template states
/HeaderState {
  /Helvetica-Bold findfont 18 scalefont setfont
  0 setgray
  2 setlinewidth
  gstate
} def

/BodyState {
  /Times-Roman findfont 10 scalefont setfont
  0 setgray
  0.5 setlinewidth
  gstate
} def

1.7. Common Pitfalls

VM Consumption - gstate allocates memory; excessive use can exhaust VM.

% Bad: Creating gstate in loop
1 1 1000 {
  gstate /temp exch def  % VM grows!
} for

Global VM Restrictions - Creating gstate in global VM when graphics state contains local VM objects causes error.

true setglobal
/LocalFont /Helvetica findfont def  % Local VM
gstate  % Error: invalidaccess

Not a Substitute for gsave - Use gsave/grestore for simple state save/restore.

% Inefficient
gstate /temp exch def
drawShape
temp setgstate

% Better
gsave
drawShape
grestore

Use for Templates - gstate is ideal for creating reusable state configurations.

1.8. Error Conditions

Error	Condition
[invalidaccess]	gstate in global VM but current state contains local VM objects
[stackoverflow]	No room on operand stack
[VMerror]	Insufficient VM to allocate gstate object

1.9. Implementation Notes

• Only graphics state operator that consumes VM

• Allocated in local or global VM based on current allocation mode

• Contains complete copy of graphics state

• Can be used repeatedly with setgstate

• More expensive than gsave but more flexible

• Best used for state templates, not simple save/restore

1.10. Graphics State Components

The gstate object captures all of the following:

• Transformation matrix (CTM)

• Color space and color values

• Line parameters (width, cap, join, dash, miter limit)

• Current font

• Current path (not saved - always empty)

• Clipping path

• Flatness tolerance

• Stroke adjustment

• Halftone, transfer function, black generation

• Rendering intent (Level 3)

1.11. See Also

• setgstate - Replace graphics state from gstate

• currentgstate - Update gstate with current state

• gsave - Save graphics state on stack

• grestore - Restore graphics state from stack

• grestoreall - Restore all saved states