[cairo] add solid/gradient pattern info getters

[Carl Worth]

On Wed, 13 Sep 2006 19:37:28 -0400, Behdad Esfahbod wrote:
>
> I prefer "rgba" instead of color here.

Agreed.

> > cairo_status_t
> > cairo_gradient_pattern_get_color_stop (cairo_pattern_t *pattern,
> > 				       int index, double *offset,
> > 				       double *r, double *g, double *b, double *a);
> > cairo_status_t
> > cairo_linear_gradient_pattern_get_endpoints (cairo_pattern_t *pattern,
> > 					     double *x0, double *y0,
> > 					     double *x1, double *y1);
> >
> > cairo_status_t
> > cairo_linear_gradient_pattern_get_endpoints (cairo_pattern_t *pattern,
> > 					     double *x0, double *y0, double *r0,
> > 					     double *x1, double *y1, double *r1);
>
> These all should be renamed to cairo_pattern_get_...  We have
> cairo_pattern_create_linear(), not cairo_linear_pattern_create().

Yes, it should certainly be:

	cairo_pattern_get_color_stop

to parallel cairo_pattern_add_color_stop. But we do need to
distinguish the linear and radial function names. But I wouldn't put
the name gradient in there. I would propose:

	cairo_linear_pattern_get_endpoints
	cairo_radial_pattern_get_endpoints

I'm not sure I love "endpoints". It lays a one-word-or-two trap for
the user. What instead though? ... get_geometry maybe?

> > They all return CAIRO_STATUS_PATTERN_TYPE_MISMATCH on error.  The only
> > oddball here is get_color_stop, where the expected usage is to start
> > index at 0 and keep incrementing it until the function returns
> > CAIRO_STATUS_INVALID_INDEX (a new error code).  This seemed simpler
> > than having an explicit getter for the number of color stops,

You could add cairo_pattern_get_num_color_stops and still provide the
above approach. I can imagine cases where not being able to ask for
the number in advance of iterating over them would be quite painful.

But, this is a tricky things to do. I've basically never added
cairo_get_dash only because it was too annoying to try to think of a
good way to expose a variable-sized getter function.

> We already have cairo_svg_get_versions() that uses the other convention.
> For svg that may make sense since the return value is constant and
> should not be freed.

Yeah, that's a pretty big difference I think. Enough to not justify
following it for consistency's sake along.

-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/20060913/2d11f412/attachment.pgp