[cairo] [cairo-announce] cairo snapshot 1.3.2 now available

[Carl Worth]

On Mon, 08 Jan 2007 10:52:31 +0800, Steve Chaplin wrote:
> > The copy_clip_rectangles/rectangle_list_destroy functions follow a
> > style similar to that of cairo_copy_path. Meanwhile, the dash and
> > pattern color stop functions introduce a new style in which there is a
> > single call to return the number of elements available (get_dash_count
> > and get_color_stop_count) and then a function to be called once to get
> > each element (get_dash and get_color_stop_rgba).
...
> Are you saying that the new dash and color_stop interfaces are similar
> and that the new clip "getter" is different? I can't see that.
...
> cairo_get_dash()
>   returns a list of dashes and an offset == [1.0, 2.0, 3.0, 4.0], offset
> cairo_copy_clip_rectangles()
>   returns a list of rectangles == [(x,y,w,h), (x,y,w,h), ...]
> cairo_copy_path()
>   returns a list of path elements == [(type, points), (type,
> points), ...]
> cairo_pattern_get_color_stop_rgba()
>   returns one item from a list   list[i] == (o,r,g,b,a)
>                            where list    == [(o,r,g,b,a),
...
> It looks like cairo_pattern_get_color_stop_rgba() is the odd one out -
> it returns an item from a list whereas the others return lists.
> Why not simply return the whole list?

Ah, so that's yet another difference.

Here's a summary that includes both the difference I was talking
about, as well as the one you were talking about:

cairo_copy_clip_rectangles

	Allocates an array for the user, and also allocated a
	containing object that contains a pointer to the array as well
	as the size. The returned object must be destroyed with
	cairo_rectangle_list_destroy.

cairo_get_dash

	Fills in an array that is provided by the user, (so no
	function is provided to destroy anything since cairo isn't
	allocating anything). But cairo does provide
	cairo_get_dash_count so that the user can allocate the array
	in the first place.

cairo_get_color_stop

	Fills in pointers to several values corresponding to a single
	color stop. This function must be called several times in
	order to obtain the complete set of color stops, (and cairo
	provides cairo_get_color_stop_count so the user can know how
	many times to call the function).

I don't think those differences are good, (even if I can even answer
_why_ some of them exist).

For example, the distinction between get_dash and get_color_stop is
that get_dash is filling in an array of native doubles, (and the same
array is used by set_dash). But with get_color_stop, you have the
flexibility to use it to fill in any custom structure you might have
that has color stop values in it, (that is without any additional
copying). You would still need a loop around that to get them all, but
you also need the same look to call cairo_pattern_add_color_stop. Is
that a good optimization or just an API gaffe?

It sounds like you were able to paper over the allocation difference
in your language binding, so it won't cause any user confusion
there. But I'd still like to have a better story for users of the C
interface, (like yourself, for example).

Also note that there is an outstanding naming inconsistency with
cairo_copy_clip_rectangles and friends, (rectangles
vs. rectangle_list).

So what I'd still like to see is a clear guideline that encompasses
all of these "getter" APIs, (and will serve as a useful precedent for
future additions).

I'm very glad to have binding authors involved in the discussion.

-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/20070117/913eb7c8/attachment.pgp