Transformation Order

This isn't a bug, but it's an area that's open to some degree of interpretation.

When you compose two affine transforms A and B, you're asking for a new transform C that has the same effect as applying A and B in sequence. The API achieves this by multiplying their matrices together, which works because matrix multiplication is associative, and the order of this multiplication matters because matrix multiplication isn't commutative. But either order can be valid depending on how you apply the resulting transform. For example, if you're going to post-multiply (transform matrix on the right), then

V * C = V * A * B (for any vector V).

But if you pre-multiply (transform matrix on the left) when applying the transform, you'll have to reverse the order:

C * V = B * A * V

(You get around the dimension mismatch by transposing — swapping rows for columns.) You might choose one or the other order depending on whether you're transforming a point/vector/image/sprite/path or the coordinate system that contains it. Sometimes graphics APIs dictate the order.

Our graphics "pipeline" (such as it is) pre-multiplies when applying transforms, which is why our APIs for composing transforms use this multiplication order.