[cairo] Finding minimum distance to a stroke or fill

[Behdad Esfahbod]

On Wed, 1 Mar 2006, Carl Worth wrote:

> How about the following names instead:
>
> 	cairo_distance_to_stroke
>
> 	cairo_distance_to_fill
>
> And does the return point really belong in this interface? I think I'd
> prefer to just return the distance. That functionality matches the
> names well. Of course, if its actually the nearest point that is
> desired, that would require separate new functions, but I think I'd
> prefer to add that functionality under a separate name rather than
> using one name for both purposes here.
>
> Ashwin, in your original use case, do you need the point or is the
> distance alone sufficient for what you were doing?
>
> The other optimization suggested down-thread was returning a squared
> distance to avoid a bunch of calls to sqrt() that might not be
> necessary at all in common uses of this function.
>
> Internally to cairo I've used naming of "distance_squared" to make the
> distinction clear from any "distance" function. Should we actually
> provide all four functions:
>
> 	cairo_distance_squared_to_stroke
> 	cairo_distance_to_stroke
> 	cairo_distance_squared_to_fill
> 	cairo_distance_to_stroke
>
> That puts a rather long name on the commonly needed function, (which
> could be a minor performance trap), and it does put two extremely thin
> convenience functions in to cairo (which is something we don't usually
> do).

Having this functionality does make cairo_in_stroke and
cairo_in_fill look like thin wrappers too...  It looks like such
a heavy hammer.

> However, I don't think I'd like to just define
> cairo_distance_to_stroke/fill as returning squared distances since
> that buries some fairly essential (in certain cases) information about
> the return value in the documentation rather than the name, (which is
> something else we try to avoid in cairo).
>
> Thoughts and suggestions?

I suggest having cairo_distance_to_stroke/fill that do exactly
what they should (return the distance), and have a couple more
functions, returning distance_squared and the mapped point.
Those may be called cairo_map_to_stroke/fill.  Not that I'm
satisfied with the name.  The api for them may look like:

cairo_boolean_t cairo_map_to_stroke (cairo_t *cr,
				     double x, double y,
				     double *mx, double *my,
				     double *squared_distance);

Where the return value is what cairo_in_stroke would return.  I'm
assuming that these functionalities (in, distance, and
intersection point) are used together quite regularly, and will
be substantially faster to find together, rather than computing
them separately.

--behdad
http://behdad.org/

"Commandment Three says Do Not Kill, Amendment Two says Blood Will Spill"
	-- Dan Bern, "New American Language"