[cairo] API Shakeup: cairo_current_matrix

[Carl Worth]

On Wed, 02 Mar 2005 07:23:44 -0500, Carl Worth wrote:
> So, I now propose supporting the column-vector order within the
> structure. My complaint about separating x0/y0 is dealt with by
> judicious use of white space:
> 
> 	typedef struct _cairo_matrix {
> 	    double xx; double xy; double x0;
> 	    double yx; double yy; double y0;
> 	} cairo_matrix_t;

In spite of being an arbitrary ordering convention, I continue to be
dissatisfied by the options for ordering the members of
cairo_matrix_t.

As I argued above, it seems natural to me to use column-vector
notation in the documentation. However, I now believe the order of the
matrix elements above will not work well.

I recently had the opportunity to convert an SVG file to cairo code in
C, (the fringing.svg test). I came to the following 6-value matrix
definition in the SVG file:

transform="matrix(0.647919,-0.761710,0.761710,0.647919,-208.7977,462.0608)

and had to stop and check before cutting-and-pasting to create a call
to cairo_matrix_set_affine. What I found is that the current
row-vector/row-major oriented interface of cairo_matrix_set_affine
matches SVG's ordering exactly so a straight cut-and-paste pleasantly
did the right thing. The column-vector/row-major proposal for
cairo_matrix_t above would break this consistency.

So then I thought it would be worth checking other major graphics
systems. Owen did the legwork and found that the following systems all
appear to use row-vector matrix forms in their documentation:

	Quartz
	System.Drawing
	PostScript

while these other systems appear to prefer column-vector matrix forms:

	OpenGL
	SVG
	Java2D.

So far, it's a dead heat.

Interestingly though, Owen also examined the 6-value constructor
functions that require the matrix values to be serialized. He
discovered that the systems that use row vectors all serialize the
matrix in row-major order, while the systems that use column vectors
all serialize the matrix in column-major order.

So, there really is a "universally" accepted order for these six
elements, namely:

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

It's not hard to convince me that we shouldn't be the only system with
some other order here. So the new implementation will have this order.

The only remaining question is whether the cairo documentation for
cairo should prefer the row-vector or column-vector forms. Given the
standard order now decided, the formatting of C code seems to give me
a slight nudge toward the row-vector order, (in spite of my natural
preference for column vectors as stated at the beginning of this
message). The nudge comes from the fact that it's natural to present
the 6 values in a way that looks like a row-vector-based matrix:

cairo_matrix_t matrix matrix = {
    xx; yx;
    xy; yy;
    x0; y0;
} cairo_matrix_t;

But, whatever we decide for documentation, I'm just happy to know what
the code interface has to look like now so we can press forward.

-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/20050402/7a250a10/attachment.pgp