Canvas Transformations: Moving the Paper, Not the Pen

WHY IT EXISTS Graphics systems need an efficient way to position, orient, and scale objects. Instead of recalculating the absolute coordinates of every vertex of a shape each time it moves, a stateful transformation matrix is applied to everything drawn. This offloads complex calculations to the GPU and simplifies the drawing code.

THE MENTAL MODEL Don't think of moving your drawing on the canvas. Instead, think of moving the canvas's coordinate system—the virtual graph paper—underneath a fixed pen. When you call canvas.translate(50, 0), you aren't moving a shape. You are shifting the entire coordinate system's origin 50 pixels to the right. The next thing you draw at (0, 0) will now appear at (50, 0) on the screen. rotate spins the paper, and scale stretches or shrinks it.

HOW IT WORKS Every Canvas maintains a transformation matrix, which starts as the identity matrix (no transformation). Methods like translate, rotate, and scale multiply the current matrix by a new one, accumulating their effects. Because matrix multiplication is not commutative, the order of operations matters: translating then rotating is different from rotating then translating. To manage this state, the Canvas uses a stack. canvas.save() pushes the current transform (and clip region) onto the stack. canvas.restore() pops the last-saved state off the stack, undoing any transformations made since the last save().

WHEN TO USE IT Use Canvas transformations for complex drawings inside a CustomPaint widget. It's ideal for patterns or repeated elements around a point, like the tick marks on a clock, spokes on a wheel, or petals on a flower. It simplifies drawing groups of objects that need to be moved, rotated, or scaled together.

WHEN NOT TO USE IT Do not use Canvas transformations for general UI layout. Flutter's widget system is designed for that. If you just need to rotate or scale a standard widget, use the Transform widget. Using a CustomPaint for simple layout tasks is inefficient and fights the framework's declarative nature.

ONE CANONICAL EXAMPLE To draw a clock face, you would loop 12 times. Inside the loop, you would first call canvas.save(). Then, you'd rotate the canvas by the appropriate angle (e.g., 30 degrees for each hour). Next, you'd draw a simple vertical line at the top of the canvas. Finally, you'd call canvas.restore(). This returns the canvas to its original, un-rotated state for the next iteration. This avoids any complex trigonometric calculations to find the start and end points of each tick mark.