[cairo] Cairo documentation for stroke_extents is misleading about top left bottom right and distances.

[Andrea Canciani]

On Thu, Jan 6, 2011 at 11:58 AM,  <bootch at nc.rr.com> wrote:
> Cairo documentation for stroke_extents is misleading about top left bottom right and distances. The pycairo documentation for stroke_extents() says:
>
> x1: left of the resulting extents
> y1: top of the resulting extents
> x2: right ...
> y2: bottom...
>
> Using the word left and right implies that x1 is less than x2.  However, that assertion is not true.

I would expect the python bindings to be a thin wrapper around the C API,
which should guarantee x1<=x2.

Could you please provide a testcase in which the above property doesn't hold?
If possible, it would be nice to have it under MIT or some other
permissive licence,
because that is the preferred licence for cairo testsuite.

>
> Better if the documentation (in several places) says:
>
> x1: x of the first point
> ...
> where x1, y1 and x2, y2 are two points that define some diagonal of the bounding box.
>
> In other words, x2 minus x1 is not a proper formula for the width (a distance) of the stroke extents, since it can be negative.
>
> Some models, such as gdk.Rectangle, don't properly allow a negative distance.  A common use of extents is to get a gdk.Rectangle for use in invalidate().  To compute a gdk.Rectangle from stroke extents requires (Python):
>
> x1, y1 = context.user_to_device(x1, y1)
> x2, y2 = context.user_to_device(x2, y2)

Please remember that even if x1<=x2 before context.user_to_device(),
the same property might not hold anymore after the transformation you're
applying.

> width = abs(x2 - x1)
> height = abs(y2 - y1)
> x = min(x1, x2)
> y = min(y1, y2)
> # expand float rect to outside integral pixel
> self.value = gdk.Rectangle(int(x), int(y), int(math.ceil(width)), int(math.ceil(height)))
>
> A neive Cairo user (myself) might just use: width = x2 - x1
>
> Thanks.
> --
> cairo mailing list
> cairo at cairographics.org
> http://lists.cairographics.org/mailman/listinfo/cairo
>