Table of Contents

• 1. gsave
  • 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. Temporary Modifications
    • 1.6.2. Coordinate System Isolation
    • 1.6.3. Multiple Graphics Elements
  • 1.7. Common Pitfalls
  • 1.8. Error Conditions
  • 1.9. Implementation Notes
  • 1.10. What Gets Saved
  • 1.11. See Also

1. gsave

Pushes a copy of the current graphics state onto the graphics state stack.

1.1. Syntax

– gsave → –

1.2. Stack Effects

Table 1. Before/After

Level	Object
(none)	Graphics state stack increased by one

1.3. Description

gsave pushes a copy of the current graphics state onto the graphics state stack. All elements of the graphics state are saved, including:

• Current transformation matrix (CTM)

• Current path

• Current point

• Clipping path

• Color and color space

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

• Font

• Output device identity

Raster memory contents are NOT saved.

The saved state can later be restored by grestore.

1.4. PostScript Level

Level 1 and later

1.5. Examples

Basic state save/restore

gsave
  2 setlinewidth
  0.5 setgray
  % Draw with these settings
  stroke
grestore
% Original settings restored

Nested saves

gsave
  72 72 translate
  gsave
    45 rotate
    % Draw rotated
  grestore
  % Rotation undone, translation still active
grestore
% Both undone

Isolating color changes

gsave
  1 0 0 setrgbcolor  % Red
  fill
grestore
% Original color restored

1.6. Common Use Cases

1.6.1. Temporary Modifications

/drawBox {
  gsave
    1 setlinewidth
    0 setgray
    0 0 moveto
    100 0 lineto
    100 100 lineto
    0 100 lineto
    closepath stroke
  grestore
} def

1.6.2. Coordinate System Isolation

gsave
  x y translate
  scale rotate
  % Draw in transformed space
grestore
% Original CTM restored

1.6.3. Multiple Graphics Elements

% Draw multiple independent elements
/elements [
  { drawCircle }
  { drawSquare }
  { drawTriangle }
] def

elements {
  gsave
    exec
  grestore
} forall

1.7. Common Pitfalls

Must Match with grestore - Every gsave must have matching grestore.

gsave
  % Changes
  % Missing grestore causes stack growth

Limited Stack Depth - Graphics state stack has implementation-dependent maximum depth.

% Too many nested gsaves
{ gsave } repeat  % Eventually: limitcheck

Use for All Temporary Changes - Always bracket temporary state changes with gsave/grestore.

1.8. Error Conditions

Error	Condition
[limitcheck]	Graphics state stack overflow

1.9. Implementation Notes

• Copies entire state (relatively expensive operation)

• Stack typically allows 15-30 levels

• Each saved state consumes memory

• Very common operation in PostScript programs

1.10. What Gets Saved

Complete list of saved parameters

• Current transformation matrix

• Current path and current point

• Clipping path

• Color space and color

• Font

• Line width, line cap, line join

• Miter limit

• Dash pattern

• Flatness

• Stroke adjustment (Level 2)

• Overprint (Level 2)

• Black generation and undercolor removal functions

• Transfer function

• Halftone screen

• Device

1.11. See Also

• grestore - Restore graphics state

• grestoreall - Restore all levels

• gstate - Create gstate object (Level 2)

• setgstate - Set from gstate (Level 2)

• VM operations: save, restore - Also save graphics state