[cairo] API Shakeup: cairo_current_matrix

[Carl Worth]

On Tue, 15 Feb 2005 17:45:39 -0800, Bill Spitzak wrote:
> Note that some Postscript and OpenGL documentation trasposes the matrix, 
> describe the vectors as rows instead of columns, and transform by 
> post-multiply.

Yes, there are equivalent row-vector and column-vector representations
for all of this. Describing the operation with equations rather than a
matrix diagram was a lame attempt to let the user think in terms of
row-vectors or column-vectors according to any pre-existing mental
wiring.

Perhaps a better approach is just to adopt column-vector terminology
throughout the documentation.

> This is mathematically the same, however it appears the 
> above syntax is much more popular nowadays. (And to further confuse 
> things OpenGL does transformations completely opposite the way 
> PostScript does, by post-multiply in the above syntax. Translate 
> followed by rotate in OpenGL rotates about the real origin, not the 
> translated point. I find this very confusing and like the PostScript 
> method much better!)

Yes, the order-of-transformations convention is another one, with more
significant impact on usage. The OpenGL model can be understood in
terms of "transforming the object" while the PostScript model can be
understood in terms of "transforming the coordinate system".

I agree that we want to match PostScript in this regard.

> I suspect you have xy and yx swapped in either your description of the 
> structure or in your functions. If you meant to order them in the same 
> way PostScript does it  is xx,yx,xy,yy,x0,y0, ie. by column in the above 
> diagram.

The order I gave was intentional, though admittedly "a little funny"
as I mentioned before. The names are chosen to be easy to remember,
(xx, xy, and x0 contribute to the new X value, while yx, yy, and y0
contribute to the new Y value).

The order of the structure is a bit funny in that it can't be read
directly from the rows or columns of the matrix, as can be seen:

>   |X|   | xx xy x0 |   |x|
>   |Y| = | yx yy y0 | x |y|
>   |1|   |  0  0  1 |   |1|

> > 	typedef struct _cairo_matrix {
> > 	    double xx;
> > 	    double xy;
> > 	    double yx;
> > 	    double yy;
> > 	    double x0;
> > 	    double y0;
> > 	};

But I don't have any better proposal for ordering the members of the
structure. Assuming the column-vector convention, (as proposed above),
reading off the matrix rows would separate the translation values from
each other, (xx, xy, x0, yx, yy, y0), which seems most desirable.

Using the matrix column order (xx, yx, xy, yy, x0, y0) would put x0,y0
next to each other, but it's a bit awkward given the column-vector
matrix. Worse, this would make the structure order incompatible with
freetype and fontconfig which both provide a 2x2 matrix with an (xx,
xy, yx, yy) order).

Finally, the proposed order (xx, xy, yx, yy, x0, y0) is compatible
with the order used by pango, (whose designers faced a similar
situation). It can be understood as the natural order of a 2x2 matrix,
followed by the two translation values.

But the easiest thing for users to do is probably to just ignore the
order of the members and access them by name. This is where the
intuitive names are important, and as proposed, are compatible with
freetype, fontconfig, and pango.

-Carl

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050301/2d031574/attachment.pgp