[cairo] API: cairo_set_current_point()

[Carl Worth]

On Wed, 2008-09-03 at 10:18 +0100, Chris Wilson wrote:
> Hi all,
>  I'd like to propose this new bit of API to move the current point
> without generating a new sub-path: cairo_set_current_point(). My
> motivation is from implementing PostScript operators (and type1 fonts,
> in particular, depend heavily on this operation). However, it is exactly
> the same operation required by Inkscape for its path optimisation,
> see http://lists.cairographics.org/archives/cairo/2008-April/013651.html
> and the most recent reminder.

Hi Chris,

I like this. It's clear from the Type1 documentation why you need it,
and as you remind us, it solves one of inkscape's problems, (which we've
been quite bad about getting around to it seems!).

If I'm understanding this correctly, we'll now have cairo_move_to
basically as a convenience function calling cairo_new_sub_path and
cairo_set_current_point, right? Would it be helpful to document it that
way?

Implement it that way?

> In terms of how I think it works...
> cairo_set_current_point() updates the current point, setting the
> has_current_point flag so future relative operations do not fail. The
> current use of has_current_point is restricted to the relative
> operations as the origin of their deltas and a (new last_point,
> has_last_point) is introduced to track what is currently referred to as
> current_point. That is a line_to() after set_current_point(), performs a
> move_to() (and similar effects for curve_to() and arc()) and
> close_path() does nothing if has_current_point, but not has_last_point
> is set. And paths are only equal if the last_point and not current_point
> are the same.

This description is a bit confusing...

> They say a patch speaks a thousand words...

I'll take your word that the patch matches your description, but...

We're left with very similar state variables "current_point" and
"last_point" in the code. Those definitely need some guidance, (at the
declaration at least), in a code comment stating how they are
distinguished. Basically, one should be able to review the code, see the
rules for these two variables, and verify that the rules are honored by
the implementation.

Right now that's just not possible, (one would have to infer the rules
from the code itself).

Can you fix that up?

Thanks,

-Carl