[cairo] Re: New API: cairo_surface_get_width/height

[Owen Taylor]

On Thu, 2006-06-08 at 22:37 -0700, Carl Worth wrote:
[...]
> I balked at the original proposal for cairo_has_clip as seen below:
> 
>  On Mon, 27 Feb 2006 10:17:01 +1300 Robert O'Callahan wrote:
>  >On Fri, 2006-02-24 at 12:32 -0800, Carl Worth wrote:
>  > >On Thu, 23 Feb 2006 16:39:14 +1300, Robert O'Callahan wrote:
>  > > > +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?
> 
> So, I'm already arguing there from the point-of-view of a surface
> having a "size". We can just as easily talk about the surface not
> having a size per se, but definitely having some limit on the
> coordinate values that will have an effect on it, (due to some "clip"
> on the underlying surface). Either way, Robert sees some benefit from
> being able to distinguish that from cairo_clip()-based clipping, so
> I'm looking for a way to advertise it.
> 
> So that's what I'm trying to do with cairo_surface_get_width/height.

We can list various things that Cairo knows that it might be interesting
to reveal if someone is drawing with native code:

 - The list list of backend space integer clip rectangles
 - Whether there is a clip mask in addition
 - The relationship between Cairo's coordinate space and the underlying
   backend space clip rectnagles.

The relevant point of these quantities to me is that they can't easily
be tracked externally.

I'm not so sure about the concept of "inherent clipping", as I might
call it ... whether drawing to the underlying object gets clipped 
correctly without having to do anything else.

It's certainly worth pointing out that in the motivating case here,
the information about inherent clipping is available without adding
anything to Cairo; given an XID, it's straightforward to say:

 - What's the GdkDrawable for this XID
 - Is that a pixmap?
 - What's the size of the pixmap?

In fact, since Robert is about to call GDK theme drawing functions,
he's already done the first step.

And when we turn around and look at the concept of "inherent clipping"
for the Win32 backend, things look very different.

 - The surface was created, not for a window or bitmap, but for a 
   DC (device context). So the clip region of the device context
   is a vastly more relevant concept than the "size of the surface"
 
 - If we call into the XP native theme drawing functions, we pass
   in a DC again, and they honor it.

The idea of asking "does cairo need any more clipping than the surface
had originally" may still be interesting, but I think the relationship
of that question to the width and height of a surface pretty weak.

In fact, what you'd probably really want in the Win32 case, is a
public way of doing:

  _cairo_surface_set_clip (gstate->target, &gstate->clip);

> What proposal would you make instead?

To me, I'd first ask if anything is needed at all. (See above.) If
it is, I'd keep it specific to what is actually needed here - having
some method of determining the extents of the Xlib drawable that
the surface is targeting. Most likely backend specific. 

> > I don't think the argument about pattern sources is very compelling,
> > because using a window as a repeating pattern source is pretty much
> > nonsensical, for X, for Windows, or for any system. 
> 
> Fine, we can ignore that argument.
> 
> > If the desire is simply to push the get size operations up the stack
> > to have them in a more logical place, then why not make the operation
> > optional and document that not all surfaces have a size?
> 
> Your size-less win32 windows still have limits due to the underlying
> clipping, right? And that's what GetClipBox reports?
> 
> I don't see how that notion wouldn't be captured in get_width/height.
> (Obviously, get_width/height isn't providing as detailed information
> as it could---we could actually return a rectangle or a list of
> rectangles for the "inherent clipping" on a surface, but I don't see
> much use in providing an abstraction that detailed.)
>
> > GetClipBox definitely doesn't return the size of the surface, it 
> > returns the box that it is interesting to draw on.
> 
> So that sounds like that would satisfy what Robert needs. Do you think
> we could get by with just changing the wording of the documentation
> (and perhaps tweaking the names) of my surface_get_width/height?

One of my big concerns here is that cairo_surface_get_width/height 
has a very natural interpretation for the user when dealing with:

 - An image surface
 - A PDF surface

And many other surfaces. I think the cases where there is a natural
meaning to the user have to the be the primary ones if you are going
to use those names. 

Regards,
					Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060609/228a5b48/attachment.pgp