[cairo] cairo_matrix_t

[Owen Taylor]

Code using cairo_matrix_t tends to look like:

  cairo_matrix_t *matrix = cairo_matrix_create ();
  cairo_current_matrix (cr, matrix);
  cairo_pattern_set_matrix (pattern, matrix);
  cairo_matrix_destroy (matrix);

Or like:

  cairo_matrix_t *matrix = cairo_matrix_create ();
  cairo_matrix_scale (matrix, w * 5., h * 5.);
  cairo_pattern_set_matrix (pattern, matrix);
  cairo_matrix_destroy (matrix);

This strikes me as being a mix of the worst elements of 
stack-allocated and heap allocated. It needs to be 
explicitly allocated, but then you have to pass an already
allocated matrix in to get a result.

What I did for Pango was almost exactly opposite from this,
using the PangoMatrix conventions, the above code would 
look like:

  cairo_pattern_set_matrix (pattern, 
                            cairo_current_matrix (cr));
and like:

 cairo_matrix_t matrix = CAIRO_MATRIX_INIT;
 cairo_marix_scale (&matrix, 0.5, 0.5);  
 cairo_pattern_set_matrix (pattern, &matrix);

So, the principles are:

 - the matrix structure is "public" so that it can be 
   stack allocated. (Doesn't allow for alternate representations,
   without an ABI change, but the need to change seems unlikely 
   to me.)

 - getters when possible, return 'const PangoMatrix *', 
   a pointer to storage owned by the object.
   Like cairo_current_pattern(). 

   (After some debate, we settled on not duplicating returns in 
   the GTK+ stack because it makes life *so* much easier for the
   programmer. It does mean that you can't add transparent thread
    safety)

I'm pretty happy with how this worked out for Pango, but if you
don't want to change the API, or you don't like the 
non-copying getters, a smaller change would be to just allow
for stack allocation of cairo_matrix_t.
   
Regards,
					Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20040906/41f6100c/attachment.pgp