Table of Contents

• 1. setmatrix
  • 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. Restoring Saved State
    • 1.6.2. Setting Absolute Transformation
    • 1.6.3. Device Setup
  • 1.7. Common Pitfalls
  • 1.8. Error Conditions
  • 1.9. Implementation Notes
  • 1.10. Matrix Format
  • 1.11. Why setmatrix Is Rarely Needed
  • 1.12. Comparison with Other Operators
  • 1.13. Performance Considerations
  • 1.14. See Also

1. setmatrix

Replaces the current transformation matrix with a specified matrix.

1.1. Syntax

matrix setmatrix → -

1.2. Stack Effects

Table 1. Before

Level	Object
0	matrix (6-element array)

Table 2. After

Level	Object
(empty)	No results

1.3. Description

setmatrix replaces the current transformation matrix (CTM) in the graphics state with the value of matrix.

This establishes an arbitrary transformation from user space to device space without reference to the former CTM. The matrix operand must be a 6-element array of numbers representing a transformation matrix.

Except in device setup procedures, use of setmatrix should be very rare. PostScript programs should ordinarily modify the CTM using translate, scale, rotate, and concat rather than replace it.

1.4. PostScript Level

Level 1 and later

1.5. Examples

Setting a specific matrix

[2 0 0 2 100 100] setmatrix
% CTM is now exactly [2 0 0 2 100 100]

Restoring saved matrix

matrix currentmatrix
/savedCTM exch def

% ... transformations ...

savedCTM setmatrix  % Restore CTM

Resetting to default

matrix defaultmatrix setmatrix
% Equivalent to: initmatrix

1.6. Common Use Cases

1.6.1. Restoring Saved State

% Save CTM
matrix currentmatrix /originalCTM exch def

% Complex nested transformations
gsave
  100 100 translate
  2 2 scale
  % ... more transformations ...
grestore

% Restore exact original CTM
originalCTM setmatrix

1.6.2. Setting Absolute Transformation

% Set specific transformation regardless of current state
[1.5 0 0 1.5 200 300] setmatrix
% CTM is now exactly this matrix

1.6.3. Device Setup

% In device initialization (rare)
/myDeviceMatrix [72 0 0 -72 0 792] def
myDeviceMatrix setmatrix

1.7. Common Pitfalls

Breaks Encapsulation - setmatrix can break assumptions about coordinate system.

% Dangerous in nested procedures
/proc1 {
  100 100 translate
  proc2  % Assumes translation is in effect
} def

/proc2 {
  matrix defaultmatrix setmatrix  % Destroys proc1's transformation!
} def

Use concat Instead - Usually you want to modify, not replace, the CTM.

% Wrong - replaces CTM:
[2 0 0 2 0 0] setmatrix

% Right - modifies CTM:
[2 0 0 2 0 0] concat
% Or better:
2 2 scale

Not Saved by gsave - Well, actually it is, but that’s the point:

gsave
  [1 0 0 1 0 0] setmatrix
  % Transformation in effect
grestore
% Transformation undone - setmatrix changes are saved/restored

Prefer Transform Operators - Use transformation operators instead of setmatrix:

% Instead of:
[2 0 0 2 100 200] setmatrix

% Use:
100 200 translate
2 2 scale

Valid Use Case - Restoring a saved matrix is the primary valid use:

matrix currentmatrix  % Save
/saved exch def
% ... operations ...
saved setmatrix       % Restore

1.8. Error Conditions

Error	Condition
[rangecheck]	Array does not have exactly 6 elements, or matrix values exceed implementation limits
[stackunderflow]	No operand on stack
[typecheck]	Operand is not an array, or array elements are not all numbers

1.9. Implementation Notes

• The CTM is stored internally in device space

• Very large or very small matrix values may cause precision issues

• Degenerate matrices (determinant = 0) create non-invertible transformations

• The matrix operand is not modified

• Unlike concat, setmatrix completely replaces the CTM

1.10. Matrix Format

The matrix [a b c d tx ty] transforms coordinates:

x' = a×x + c×y + tx
y' = b×x + d×y + ty

Where:

• a, d: scaling factors

• b, c: rotation/shear components

• tx, ty: translation components

1.11. Why setmatrix Is Rarely Needed

In well-structured PostScript programs:

1. Initialization: Device setup uses initmatrix

2. Modifications: Use translate, scale, rotate, concat

3. State Management: Use gsave/grestore

4. Restoration: Use grestore or saved matrix with setmatrix

1.12. Comparison with Other Operators

% setmatrix - replaces CTM
[2 0 0 2 100 100] setmatrix
% CTM = [2 0 0 2 100 100]

% concat - multiplies with CTM
matrix currentmatrix  % Assume [1 0 0 1 0 0]
[2 0 0 2 100 100] concat
% CTM = [2 0 0 2 100 100] × [1 0 0 1 0 0]
%     = [2 0 0 2 100 100]

% In this case same result, but concat respects existing CTM

1.13. Performance Considerations

• Very fast operation

• No matrix computation required

• Just replaces 6 values in graphics state

• No different in performance from concat

1.14. See Also

• currentmatrix - Get current CTM

• defaultmatrix - Get device default matrix

• initmatrix - Reset CTM to default

• concat - Concatenate matrix with CTM

• translate - Move origin

• scale - Change unit size

• rotate - Rotate axes

• gsave - Save graphics state

• grestore - Restore graphics state