[cairo] Cairoglyphics ver 1.2

[Carl Worth]

On Fri, 14 Dec 2007 01:07:07 +0200, Donn wrote:
> Okay, bedtime is long overdue, herewith my latest diagram. I hope it has
> addressed much of the input I have received. Thanks for all the help.

Yes, very nice.

Someone else already pointed out that the clip should be different than
the mask, (I would imagine an inverted triangle for example).

Also, the mask and clip should be filled, not stroked, to more
accurately reflect how things work.

Meanwhile, having the destination surface in an "upright" orientation
is a nice improvement, and I think that the "context" arrow emanating
from the upper-left corner nicely suggests where the origin comes
from.

Things like the depiction of the source as a layer with content that's
obviously correlated to the final result is a great improvement. Well
done!

As for remaining comments from me, I'd replace "Context:Actions" with
"Context:Drawing" and I would remove clip() from that list. The
cairo_clip() call definitely does not draw anything, (but everything
else in that list does).

Also, the diagram is quite good in general about being language- and
environment-agnostic, which is excellent. The only obvious deviations
from that are phrases like "ctx.clip()" which look more like python
than C, (could be just "clip()" to avoid the problem); and "ctx =
window.cairo_create()" which is GTK+-specific, (similarly with
GDKDrawingArea).

Maybe the GTK+-specific stuff could just use a footnote pointing out
that this applies only to programs written for GTK+? Or maybe there's
a separate diagram for using cairo within GTK+ (could also talk about
things like gdk_cairo_set_source_pixbuf for example)? I don't know.

I still don't like "bubbles" and I think we can do better than
"visible/invisible". For one thing, I have seen new users surprised
that line_to doesn't immediately draw anything---and "visible" doesn't
disabuse the user of that notion. Maybe three groups in that box?
"Path creation", "Transformation", "Options" ? or something like that?

And for cairo_save/cairo_restore---it would be excellent to indicate
that they apply to "transformation" and "options" but not to the path
stuff. Perhaps a dashed rectangle around those two groups of calls
coming out to a box that says "The effect of these calls can be made
temporary by placing them inside a cairo_save/cairo_restore group." or
something like that?

Again though, this is really nice---please keep up the great work.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.cairographics.org/archives/cairo/attachments/20071214/b7661b0d/attachment.pgp