[cairo] cairo_matrix_t

[Carl Worth]

On Mon, 06 Sep 2004 11:42:37 -0400, Owen Taylor wrote:
> 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);
[...]
> 
> What I did for Pango was almost exactly opposite from this,
> using the PangoMatrix conventions, the above code would=20
> look like:
> 
>   cairo_pattern_set_matrix (pattern,=20
>                             cairo_current_matrix (cr));

It's fairly hard to argue against a change that reduces 4 lines of code
to 1 -- especially for an API that is intended to be easy to use by
design.

One general problem with C APIs is that with a function like:

	foo_t *bar_get_foo (bar_t *bar);

It's not obvious whether the caller or the callee is responsible for the
memory allocation pointed to by the return value. I want to make this
very obvious in cairo. Preferably, there will be global convention
across all cairo functions of this type. Less appealing would be a
naming convention to distinguish the few exceptions.

So, if we're going to do this, first I want to audit all similar
functions in cairo to see if we can't get them acting the same way. (See
the new thread today regarding cairo_current_xxx).

There's another potential problem with returning pointers to objects
owned by cairo. If cairo returns a pointer to the live CTM, then the
user can inadvertently scramble cairo state when a copy really was
necessary. That's no big deal as its just a user bug (which we can't
eliminate). Worse though, is the possibility of a user relying on
modifying cairo state through direct manipulation of the returned
object. This could lead to behavior that works today and breaks
tomorrow. For example, we may have internal caches that must be informed
if the CTM ever changes. Direct manipulation of the CTM through a
returned object could break that.

I guess we could address that issue by having cairo return pointers to
copied objects. That would still allow cairo to maintain the memory, but
prevent the user from effecting state changes.

>    (After some debate, we settled on not duplicating returns in=20
>    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'll pick up the thread safety and the extension issues at later points
in this thread.

-Carl