[cairo] cairo_get_clip_as_rectangles

[Carl Worth]

On Wed, 28 Jun 2006 17:06:57 +1200, Robert O'Callahan wrote:
>
> Attached is a patch for my next attempt at getting the clip as a
> rectangle list.

Thanks! This looks really interesting.

It would have been nice to have a 1.2 release of cairo with this so
that we could build mozilla against a released system-cairo, but this
is too late---oh well.

> This is simple to implement and IMHO ends up looking very elegant.

I'm glad you like it. Thanks for being patient with the process as we
came up with this together. I'm quite happy with the result.

>                                     I'm not sure how to deal with this;
> I'd like to test with different expectations for different backends.

Yes, that would be helpful. We should probably just pass the surface
type value into the test's draw function. This would be a much more
elegant way for doing UNTESTED results on a few specific tests for
specific backends, (we've got an ugly hack in cairo-test.c for that
right now).

> +        /* convert each device-space rectangle to its bounding box in user space */
> +        if (!_cairo_gstate_backend_to_user_rectangle_bbox (gstate, &rectangle_array[i])) {
> +            /* the result was not tight */
> +            *is_tight = FALSE;
> +        }

This needs to check is_tight before dereferencing it. We already allow
NULL pointers for "optional" return values in other similar APIs. And
this one should be optional, (useful for when the caller only wants
the clip area bounds for example).

> + *            If the output *is_tight is set to true, then the union is exactly
> + * the clip area. (If *is_tight is false, the union may or may not be exactly
> + * the clip area.)

The wording here is a bit awkward as it might suggest that the user
needs to set is_tight to TRUE or FALSE before calling the function,
(perhaps as a hint for what they want). Maybe something like:

	The @is_tight parameter is used as a return value to indicate
	whether the returned rectangles are a tight bound on the clip
	region or not. A tight bound does not include any pixels not
	in the clip region. It is valid to pass a NULL pointer if the
	caller is not interested in the tightness.

> + *                 The function returns the number of rectangles placed
> + * in rectangle_array, which may range from zero to max_rectangles inclusive.

Oh, there's one thing missing from the API and implementation. We
should have a way to indicate how many rectangles _would_ be used if
max_rectangles is insufficient. And actually, that would end up with a
rather awkward calling convention, (having to call
get_clip_as_rectangles twice with a malloc in between).

One idea might be to just copy the interface of cairo_copy_path which
does the allocation for the user. Then we would have to add a separate
cairo_get_clip_extents function for when just the overall bounding box
is desired.

*Sigh* I guess that means we go another round on this. I hope you're
 not getting to sick of me on this one!

-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/20060629/2a7aa24c/attachment.pgp