[cairo] add solid/gradient pattern info getters

[Vladimir Vukicevic]

On 9/13/06, Behdad Esfahbod <behdad at behdad.org> wrote:
> 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()

Fixed.

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

Done.

> + * @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...

Sure, I'll add a bunch of ifs :)

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

I'm not sure what you mean here -- or rather, I am, but we only keep
that data around for solid patterns.  For gradient endpoint patterns,
the data structures are all pixman ones, which keep everything as
16-bit colors.

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

Ugh, now that I think about it some more, my API actually makes it
hard to get the color stops out and store them anywhere.. since you'd
have to loop once to figure out how many there are, then allocate
enough space, and then pull them out.  (Is this what you're referring
to?)

Just read Carl's email; how does:

cairo_status_t cairo_pattern_get_color_stops (cairo_pattern_t *, int
*num_stops, double *color_stop_data);

sound?  If stop_data is NULL, then the number of color stops is
returned in num_stops.  Otherwise, num_stops must be the # of color
stops, and color_stop_data must be a pointer to 5*num_stops doubles,
which will contain "offset, r, g, b, a".

This would translate well into get_dash() as well, e.g.:

cairo_get_dash (cairo_t *cr, int *num_dashes, double *dashes, double *offset)

(Though I don't know whether double* offset should go before
num_dashes or after...)

     - Vlad