[cairo] API Shakeup: cairo_current_matrix

[Bill Spitzak]

Robert O'Callahan wrote:
> On Thu, 2005-06-16 at 12:48 -0700, Carl Worth wrote:
> 
>>We've already got all the const-correctness we need in the API to be
>>able to return a "const cairo_matrix_t *" from the two get_matrix
>>functions, (cairo_get_matrix and cairo_pattern_get_matrix).
>>
>>Here's a patch that implements this.
> 
> 
> I thought we discussed this before and you had decided not to do it. The
> problem with this API is that although the matrix is "const" to the
> user, it can still be changed by cairo and those changes will be visible
> to the user. Therefore specifying what exactly that matrix will be at
> any given time, either formally or informally, is quite hard. At a
> minimum you need to document which cairo API calls will change the
> matrix and guarantee that all others do not. (Although it will still be
> error-prone when users accidentally reuse a stale CTM pointer.)

It is probably best to document that *all* Cairo calls may change the 
matrix. It is only good until the next call to the same cairo_t. I'm 
pretty certain the users of Cairo will be smart enough to copy the 
matrix and not just store the pointer.

I much prefer the pointer design. I don't care how fast the processor 
can do it or how proper the design is, copying is slower than passing 
the pointer around by an amount that is not zero. A slower 
implementation is fine if it makes the API easier and cleaner to use, 
but this is not the case here.