[cairo] A diagram for criticism/comments

[Donn]

> > a fairly abstract high level) that all the real "drawing" happens on the
> > *mask* and only 'Action' (Behdad's term) commands commit the "ink" to the
> > Surface.
> I wouldn't describe it that way.
I see (well, I try to) your pov, and here comes the "but": I want to aim for 
something that will give people a stepping stone, not a technically correct 
snapshot of the bits and bytes.
 It makes sense for a human to think of drawing *someplace*. The pen in one's 
hand must touch the paper. In my diagram it's easier to aim for visual 
metaphors -- anything else and I'll end up with a flowchart!
 So, I've not seen any strong argument against the "draws on the mask layer" 
idea and I'll stick to that until the wheels come off!
 
I'm going with the "context is the tool, mask is the paper, source is the ink, 
surface is the result" metaphor.

> Now, cairo_mask is probably the least commonly used drawing
> operation. But that's only because there are 4 variants of it that are
> more convenient, (cairo_stroke, cairo_fill, cairo_show_text/glyphs,
> and cairo_paint).
> These variants each provide a convenient mechanism 
> for constructing a desired mask, (from the path for stroke/fill, from
> a font for show_text/glyphs, and the trivial, infinitely large mask
> for paint).
> So those are the 5 drawing operations.
I will describe them as "Actions" that commit to the surface. I think that 
works nicely and is not technically wrong. 

> And I don't think anything else should be described as
> "drawing". 
I hear you, and worry that I'll be polluting the 'idea namespace' if I don't 
obey... It's just that the metaphor of 'drawing' is a strong one and when you 
think about it, as you string together line_to, arc, blah you are thinking of 
the shape you want to draw. 
 The programmer is drawing with code and thinking in outlines and coordinates. 
The eventual fill() or mask() is almost an afterthought, a kind of ritual. Am 
I wrong?

> There are things that construct a path, and there are 
> things that set transformations and options, but I wouldn't call any
> of those "drawing". 
I would, they are part of the drawing/coding flow. "Move here, make it 
just-so, rotate it a little, now a line from here to here... nice.. now a 
letter and then a little smaller ..."
Followed-by, "Right, that's done, let's see it - I'll fill_preserve() and 
stroke() this puppy and then run it!"
 
Since the two are so close, it gets tough to think around them, but without a 
clear distinction things get confusing. Source / Mask / Clip / Surface -- and 
one has to focus on where one is working at the time.

> In particular, none of these things "draw on a 
> mask".
Yes, they technically don't leave a mark. That's also why I want to describe 
Transforms as happening to the Context, and since the Context is "holding" 
the Mask (where your paths are) that's how the two combine.

> Instead an operation like cairo_fill might construct a mask 
> implicitly from the current path as part of doing its drawing, but it
> also might not need to construct a mask at all, (see what happens with
> cairo_fill in the PDF backend for example---it simply emits the path).
I see, so the meta-surface of the PDF pattern-source is simply spitting a 
given path out. Quite nice. 
 I'll give it some thought. Off the bat, it still fits with the Preparation 
(make paths--visible, and transform--invisible) then Action (commit source 
through the mask to surface) metaphor.

> Personally, I'm glad to help straighten out concepts as best I can. I
> think I'd be quite useless at laying things out---so I'm glad to have
> you doing the work that's actually hard.
Says the guy up to his eyeballs in bits and pointers and malloc! :)

> I think it's a lot better, well done!
Thanks.

> I'd like to see a more obvious 
> connection from the appearance of the source and the final result on
> the destination. For example, the source should be drawn with the same
> perspective as the mask and destination---it's effectively another
> layer.
Yes, from your recent email I am going that way. I will lay all three out - it 
really makes it clear.

> Also, to avoid confusion, it might be good if the result ended up in
> the upper-left corner of the destination, since that's where the origin 
> is in cairo, (as opposed to systems like PostScript where the origin
> is at the lower-left). 
I never thought about that. I was thinking visually (I'm a designer) and with 
the concept of Transforms the position of the final commit is irrelevant. 
It's also hard to fit all that stuff on the page. I don't want to exceed 1024 
by 768 (and I'm pushing 800 down) -- to make it easier to view the image. 
I'll have another look - I can certainly indicate 0,0 with something like a 
ruler on the page.

Good stuff, I eagerly await responses.
\d