[cairo] Latest diagram - svgz file 51K

[Baz]

On Dec 15, 2007 12:48 PM, Donn <donn.ingle at gmail.com> wrote:
> I don't think the Cairo wiki allows images and I want to air the diagrams, so
> I have attached the SVG file (it's tarred), so you can open it with Inkscape
> and zoom around.
>  I specify the fonts to use within the diagram.
>
> As always comments/bug-reports are welcome.

I've got a bunch of comments here, but please don't take this as
damning criticism, I think having a diagram like this is a good thing,
and its great that you're working on this. However, I think this
diagram would confuse its target audience of new users.

Specific problems:
- "worlds". better than "bubbles" but still this should be "graphics
states" (gstate in cairo's internals, or the postscript drawing
model). New users won't find 'worlds' anywhere else in the cairo docs.

- "Path Setup" - I think this still reads a bit too 'miscellaneous',
and in teaching material you want the classifications to be clear -
I'll talk further about his below. You have set_line* duplicated here
BTW. New users do make the mistake that set_line_width is a property
of the path and so think it will affect clip(); it would be best to be
clear that it is a stroke property.

- "Draw the path first...then start drawing" - you use 'draw' here to
mean 'draw without ink' and then later in the same sentence use it to
mean 'draw with ink'. Consider a different wording here.eg 'Create the
clipping path first...then create the drawing path', for example.

- "your path accrues on the mask layer". Not really. You don't know
what its going to mask - if anything - until the user calls fill(),
stroke(), etc. It might be better to say that fill/stroke create a
mask from the path, and that show_* creates a mask from the glyphs.
This also applies to the "These commands merge source and mask" box -
I don't think a new user is going to grok from this that the mask here
is taken from the path (for stroke and fill) and they'll go looking
for a set_mask function, by analogy with set_source.

- I don't think save(), restore() belong in the box with
transform/rotate/scale. They also save and restore the font, the clip
path, the stroke properties, etc. This box makes it look like they
don't affect those properties.

And lesser style issues:
- "as long as you know what's going on" - true of anything? I don't
think its necessary to say this.

- "Destination Surface", "Destination surface", etc. It would be
better to use case consistently throughout the diagram. In some
language bindings, surfaces are objects, but there's never a
distinction made that this is a destination surface - so I'd go with
lower case D, upper case S. There's more confused capitals with
context/Context/ctx, Source, Mask (mask isn't a property of the state,
source is), and so on.

- Overall the diagram has too many arrows pointing at things for
apparently different reasons; it seems your intent is that the path
setup affects the path (indicated by an arrow), but other arrows
merely point at interesting bits of the diagram. There's no indication
that the path doesn't affect paint(), mask(), show_glyphs(), but does
affect fill() and stroke(). Consider differentiating the arrow style
based on its meaning; an arrow for 'affects', a ball-and-line for an
annotation, etc.

- The use of colour is a bit confusing too - the diagram says dark
yellow is used for the context,  but the operations in the gray boxes
are on the context too, and mostly the dark yellow seems to be used
for descriptive text. Some annotations are beige, some are grey, and
some are yellow; I don't see the scheme here?

Ok enough criticism, here's my suggestions for how part of the diagram
could be arranged to reduce confusion...

Start with a box describing the graphics state - things affected by
save(), restore(). Inside that group the functions based on their
effect; eg

{GRAPHICS STATE:
 {source: set_source*(), set_operator()}
 {transform: transform(), scale(), ...}
 {clipping path: clip()}
 {stroke properties: set_line*(), set_dash()}
 {fill properties: set_fill_rule()}
 {text properties: set_font*()}}

Next, add a box describing the path creation operations:

{PATHS: move_to(), line_to(), ... }

Next, add the box for the drawing operations:
{DRAWING:
 {stroke(), stroke_preserve()}
 {fill(), fill_preserve()}
 {mask()}
 {paint()}
 {show_text(), show_glyphs()}

Now add arrows to indicate cause and effect:
from PATHS to clip(), stroke(), fill()
from stroke properties to stroke()
from fill properties to fill()
from text properties to show_text()
from transform to an annotation saying 'change coordinate transform
used in subsequent path steps' and an arrow from there to PATH.

In my head the DRAWING box is in the middle with the GRAPHICS STATE
box to the left and the PATH box above. Obviously this only covers
part of the information on your diagram but it should get across the
idea of what save/restore affect, what inks the surface, and what
parts of the graphics state affect what drawing operations.

I started down the road of drawing this in cairopad, to explain what
I'm getting at - I think your inkscape graphics are nicer than I'll
manage, but I thought it might be cool to have something like this in
a show-me-the-code form for presentations and the like, especially
when it comes to showing off different operators. Unfortunately
cairopad doesn't work on my mac at home so I'll return to doing that
in windows next week :(

>
> Looks like a long weekend down here in RSA, maybe out there in the world too.
> Enjoy it and drive safely all.
>
> Regards,
> \d

Cheers,
Baz

>
> _______________________________________________
> cairo mailing list
> cairo at cairographics.org
> http://lists.cairographics.org/mailman/listinfo/cairo
>