[cairo] add solid/gradient pattern info getters

[Vladimir Vukicevic]

On 9/14/06, Vladimir Vukicevic <vladimirv at gmail.com> wrote:
> On 9/14/06, Behdad Esfahbod <behdad at behdad.org> wrote:
> > + *
> > + * cairo_pattern_get_color_stops() is used to retrieve the color stops
> > + * associated with a gradient pattern.  Passing NULL for @stop_data
> > will
> > + * return the number of color stops in the pattern in @num_stops.
> > + * The caller should allocate 5*@num_stops doubles to hold the data,
> > + * and call the function again with @num_stops set to the returned
> > + * value and @stop_data set to the newly allocated array.
> > + *
> > + * The array contents will be filled in with the stop offset, red,
> > + * green, blue, alpha values in sequence, per stop.
> > + *
> > + * Return value: CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_INVALID_COUNT
> > + * if @stop_data is not NULL and @num_stops does not equal the actual
> > + * number of color stops in the gradient. If the pattern is not a
> > + * gradient pattern, CAIRO_STATUS_PATTERN_TYPE_MISMATCH is returned.
> > + * CAIRO_NULL_POINTER is returned if @num_stops is NULL.
> > + *
> >
> > Four paragraphs to document a getter is enough evidence that it's not
> > good API :-).  First, the 5*@num thing is scary. If you are not going to
> > allocate the buffer (which is good), then I don't see the point of
> > returning @num and the data in the same call.  At the cost of one more
> > call, we can get back to your original proposal plus a getter for the
> > number of entries.
> >
> >   cairo_pattern_get_color_stop_rgba (*pattern, *offset, *r, *g, *b, *a,
> > index);
> >   cairo_pattern_get_num_color_stops (*pattern, *num);
>
> Eh.. I'd still prefer the API I suggested, but I don't care enough
> about it to argue for it :)  So, sure, though I'll probably do
> get_color_stop_count and get_color_stop_rgba.
>
> > Not sure about get_dash().
>
> I'd have get_dash follow the same -- get_dash_count() and get_dash()

Now that I think about it for more than a second, they won't be the
same; get_dash really wants to fill in a buffer.  I guess I could do
get_dash (cairo_t *cr, int index, double *dval) for consistency, but
I'd rather not have two different kinds of getter APIs.  I guess
that's ok, because getting any of this stuff should be fairly
uncommon.

    - Vlad