[cairo] A diagram for criticism/comments

[Carl Worth]

On Thu, 13 Dec 2007 09:16:41 +0200, Donn wrote:
> "is used [as] a surface *pattern* source" -- from my pov on the learning
> curve, a pattern *is* a bitmap.

No, not at all.

> This leaves me in some doubt : Am I to assume that *all* sources are pixmaps
> (I mean a generic term for 'arrays of rgba data') regardless of their origin?
> Or do vector sources remain as vectors ?

Absolutely not. Cairo has a "meta surface" internally which is used
for the PostScript, PDF, and SVG backends, for example, (and which we
plan to allow users to create explicitly at some point). The meta
surface records a sequence of operations (as vectors) and can replay
those to any other surface.

> PDF file (vectors) ---> Cairo source ---> cairo drawn commands ---> PDF file.
> When you open the output file, is it *all* vectors or a mix of the new ones
> you just drew on top of a bunch of 'rasterized' vectors from the original
> file?

PDF through cairo to PDF again preserves the vectors, (see a recent
post I made where I ran a file from PDF->SVG->PDF->SVG... through
cairo---it was vector all the way).

> I guess I am still really fuzzy on what a pattern is.

A pattern is simply a thing from which cairo can read "stuff". Some
patterns are backed by surfaces and as discussed above those surfaces
can have either vector or raster information. Other patterns have no
associated surface, but are simply backed by a description of what the
pattern looks like at any point, (the solid and gradient patterns, for
example).

As for a surface-backed pattern, the distinction between a pattern and
a surface is that the pattern can only be read from, while the surface
can be written to as well.

> Thanks to all for the other suggestions -- I have some work ahead of me.

As a random comment inserted here---I really like the idea of having a
"cairo at a glance" diagram. Here are some thoughts:

  * On nouns vs. verbs/actions: The term I use and would like to see
    in the diagram is "drawing operation". There are basically 5 of
    these: paint, stroke, fill, mask, and show_glyphs.

  * I don't think I like the terms "preparations" or "bubble". I think
    we can find more "cairo" ways of describing what you're trying to
    get at there.

  * Instead of the drawing operation being depicted at the side, I'd
    really like to see the drawing operation depicted as a mask that's
    floating above the destination, (which is what you're already
    depicting on the "bubble" side of your diagram). I imagine a layer
    at the top for the source, a layer in the middle for the mask, and
    then the destination surface at the bottom showing the final
    result. It would be awesome if you could successfully depict all 5
    "drawing operation" variants in the diagram.

  * It would be even extra-awesome if you could also depict the 3
    primary pattern types for the source as well, (solid, gradient,
    and surface). Though admittedly, that will start to get crowded.

    Here's an image I have used to try to capture a bunch of that:

	http://cworth.org/~cworth/papers/cairo_ddc2005/html/cairo-003.html

    It doesn't do the 3D thing you're doing, (but that's just because
    I'm not good at visualizing how to pull that off in a
    diagram). And it's totally missing all of the explanatory text.

  * Then there's trying to get clipping into the diagram, and I
    definitely have no idea how to do that. (There's even less hope of
    trying to depict all of the blending operators, but they should
    probably at least be mentioned somewhere in the diagram.)

  * For the stuff you called "preparations", there are probably two
    different concepts. One is "path creation", (line_to, move_to,
    etc.), and one is something like "state changes", (scale, rotate,
    etc.).

  * Your "bubble" concept seems to also mix two concepts. One is that
    of cairo_save/cairo_restore which allows for temporary state
    changes. The other is cairo_push_group/cairo_pop_group which
    allows for temporarily redirecting drawing operations to an
    intermediate destination surface. I have really no idea how to try
    to make a visual description of concepts like these.

There's no doubt that cairo's model has a lot of different pieces, and
trying to get as many of them as possible into a single diagram is
clearly very challenging. I really do appreciate your efforts on this
though.

A few other general comments, perhaps not directly related to the
diagram. Patterns are used in cairo not only for the source, but also
for the mask, (see the cairo_mask operation, for example). So in a
fundamental way, the only drawing operation cairo provides combines a
source pattern with a mask pattern and blends that (within the current
clip) according to the current operator onto the destination
surface. A user doesn't always "see" the source pattern, (and even
less often the mask pattern), because there are things to make it easy
to construct those implicitly. For example, the path plus cairo_fill
constructs an implicit mask pattern for you. But the concepts are
still there, and I think it's useful to understand them that way.

-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/20071213/ffc0d508/attachment.pgp