[cairo] add solid/gradient pattern info getters

[Behdad Esfahbod]

Few points:

-    CAIRO_STATUS_INVALID_DSC_COMMENT
+    CAIRO_STATUS_INVALID_DSC_COMMENT,
+    CAIRO_STATUS_INVALID_INDEX

You need to update this:

cairo.c:#define CAIRO_STATUS_LAST_STATUS CAIRO_STATUS_INVALID_DSC_COMMENT

and cairo_status_to_string()

On Wed, 2006-09-13 at 19:18 -0400, Vladimir Vukicevic wrote:
> The attached patch adds 4 new API methods:
> 
>  cairo_status_t
> cairo_solid_pattern_get_color (cairo_pattern_t *pattern,
> 			       double *r, double *g, double *b, double *a);

I prefer "rgba" instead of color here.

+ * @r, @g, @b, @a: a double to return a color value in. must not be NULL.

I don't think gtk-doc accepts this syntax.  Please document them
separately, and use full names as arguments like set_source_rgba does.

+    assert(r && g && b && a);

I also don't quite like this line.  User may only be interested in the
rgb values, or only in alpha...

Also, the controversial part of this API (and all the others involving
color) is, make sure we don't return clamped values.  Just return
whatever user set.


> 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().


> 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, or for
> doing some kind of bulk dump of the color stop data (e.g. something
> like get_color_stops (int *num_values, double *values) that will
> return the # of doubles needed in num_values if values is null, and
> will fill values with 'offset r g b a' chunks).

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.  For the pattern case, I agree that the API you
propose may be easier to deal with.  On the other hand, with your API,
all language bindings have too loop over it to create a list out of
it...  (it can be wrapped as a Python generator though.)


> Let me know if this looks ok to commit.
> 
>     - Vlad

-- 
behdad
http://behdad.org/

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