[cairo] The semantics of a surface matrix

[Carl Worth]

Two users have recently asked me about how a surface matrix, (ie. one
set with cairo_surface_set_matrix), is supposed to work, so I thought it
would be important to compose a reply for the list.

One user was confused because the visible result he got was the inverse
of what he expected. I find it confusing sometimes myself, but the
behavior is intended to be consistent[*] with PostScript semantics.

The "current matrix" that is usually manipulated within cairo, (eg. with
cairo_translate/scale/rotate) maps from user space to device space.

A "surface matrix" maps from user space to surface space. This is the
direction that "feels" backwards, since if you want a surface pattern to
appear at half-size you would construct its matrix with:

	cairo_matrix_scale (matrix, 2.0, 2.0);

If you want to think about coordinates being transformed from surface
space to user space to device space, then you need to think about the
inverse of the surface matrix for the first mapping.

-Carl

[*] The cairo behavior is consistent with PostScript in that it maps
from user space to surface space rather than the other
direction. However, cairo's notion of surface space does differ from
PostScript's image space in that cairo puts the surface space origin at
the upper-left rather than the lower-left.