[cairo] API Shakeup: Abbreviation hunt: cairo_init_clip and cairo_concat_matrix

[Carl Worth]

As I've mentioned before, I dislike the use of abbreviations in the
public API. Abbreviations make it harder to remember how to spell
things, especially when both forms are pronounced similarly, (eg. SRC
and SOURCE).

This API Shakeup is a great time to rid ourselves of a few
abbreviations that have managed to sneak in to the API.

I propose the following name changes:

	cairo_init_clip -> cairo_reset_clip

	cairo_concat_matrix -> cairo_multiply_matrix

With that, the only abbreviations I see in the API are the DEST
operators and the relative path construction functions:
rel_move_to/line_to/curve_to. Maybe I'll just live with those.

I'm not 100% satisfied with "cairo_multiply_matrix" since the name is
so similar to the existing "cairo_matrix_multiply". The type
signatures of the two functions should make their purpose quite clear:

	/* Multiply the given matrix into the current transformation
	   matrix.
	 */
	void
	cairo_concat_matrix (cairo_t *cr,
        	             cairo_matrix_t *matrix);

	/* Perform matrix multiplication: result = a * b
	 */
	cairo_status_t
	cairo_matrix_multiply (cairo_matrix_t *result,
			       const cairo_matrix_t *a,
			       const cairo_matrix_t *b);

But I'm still open for better suggestions for a name to replace
cairo_concat_matrix.

One idea is cairo_append_matrix, but that might be a bit confusing
since the actual calculation may involve pre-multiplying the matrix
rather than post-multiplying. (The difference depends on whether one
prefers to work in terms of row or column vectors. I want the cairo
implementation itself to have a solid convention here, but I've been
trying to avoid forcing that on the user).

Interestingly enough, cairo_append_transform doesn't strike me as
having the same problem, since no matter the math, it is clear that
the operation here is to provide an additional transformation. I have
been tempted to rename cairo_matrix_t to cairo_transform_t, (to focus
on the behavior, not its mathematical implementation). Owen convinced
me once before that it wasn't worth changing, but now that we're
already changing almost everything else...

-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/20050223/5fa54796/attachment.pgp