[cairo] cairo_draw_with_xlib API

[Robert O'Callahan]

On Fri, 2006-02-24 at 12:32 -0800, Carl Worth wrote:
> 2) Check for mismatch, call _cairo_error, return a "zero" value, but
>    give no direct notification to the user that an error occurred (see
>    cairo_image_surface_get_width).
> 
> I like option (2) for the current patch, which would mean removing the
> XXX comment and adding a call to _cairo_error.

OK

> > +/**
> > + * cairo_clip_rect_t:
> > + * 
> > + * A data structure for holding clip rectangles.
> > + */
> > +typedef struct _cairo_clip_rect {
> > +  double x, y, width, height;
> > +} cairo_clip_rect_t;
> 
> There's not really anything clip-specific about this structure, right?
> And I don't like the "rect" abbreviation. If we were to export this
> structure, I would expect it to be named cairo_rectangle_t. (That
> would certainly be more awkard to implement given the name clash with
> the current internal cairo_rectangle_t, but we could just first name
> that cairo_rectangle_fixed_t.)

OK. I tried to avoid making the patch too invasive until I received some
positive feedback :-)

> > +cairo_public cairo_bool_t
> > +cairo_has_clip (cairo_t *cr);
> 
> Hmm... there's always a clip. Initially it can be thought of as either
> an infinitely large rectangle, (which is rather hard to represent), or
> else it's a single rectangle no larger than the surface. We can always
> return the single rectangle for the case when cairo_clip has never
> been called, so do you actually need this function?

It's useful to distinguish "drawing will be clipped to the surface
extents" from other kinds of clipping: in that case, when I pass an xlib
surface through for direct drawing, I don't have to ask my native
drawing code to clip. But I can do this with a general or even
xlib-specific API to get the surface extents, so should I just add
cairo_xlib_surface_get_width/height to my xlibs getters patch instead?

> I think I would prefer to see an API that is more consistent with how
> we get at the current path. Something I've always imagined is:
> 
> 	cairo_public cairo_path_t *
> 	cairo_copy_clip (cairo_t *cr);
> 
> 	cairo_public cairo_path_t *
> 	cairo_copy_clip_flat (cairo_t *cr);
> 
> We certainly don't need to implement that now. But it might be natural
> to do so down the road if we end up always storing the clip path
> (which I suspect we might). So I think we should at least keep that
> API in mind while designing the rectangular version.

OK.

> Which perhaps suggests something like:
> 
> 	typedef struct _cairo_rectangle {
> 	    double x, y, width, height;
> 	} cairo_rectangle_t;
> 
> 	typedef struct _cairo_rectangles {
> 	    cairo_rectangle_t *rectangles;
> 	    int num_rectangles;
> 	} cairo_rectangles_t;
> 
> 	cairo_public cairo_rectangles_t *
> 	cairo_copy_clip_rectangles (cairo_t *cr);
> 
> If the copying must be avoided we could instead (or also) do:
> 
> 	cairo_public cairo_status_t
> 	cairo_get_clip_rectangles (cairo_t *cr,
> 				   cairo_rectangles_t *rectangles);
> 
> Where if rectangles->num_rectangles is insufficient then an error
> status would be returned, rectangles->rectangles would be set to NULL,
> and rectangles->num_rectangles would be set to the number needed.
> 
> Maybe clip_as_rectangles would actually be better then clip_rectangles
> in both of those function names.

I don't know how to implement this when a clip path has been specified
that yields a mask surface, without storing the clip path. In fact, even
if we have a clip path, it may be impossible to express as a union of
rectangles. We could treat that situation as failure due to the number
of rectangles required exceeding max_rectangles, but we couldn't then
return the required number of rectangles in num_rectangles. Thoughts?

Rob