[cairo] _cairo_surface_create_pattern docs and suggestions

[David Reveman]

On Thu, 2005-01-20 at 14:02 -0500, Owen Taylor wrote:
> Just spent some time trying to figure out  how
> _cairo_surface_create_pattern works.
> 
> Here's the docs I would write given my current understanding
> 
>   _cairo_surface_create_pattern() prepares a pattern for use
>   with a particular destination surface by initializing the
>   pattern->source member with a backend-specific source surface.
>  
>   pattern->source will then be used as the source argument to
>   _cairo_surface_composite(), _cairo_surface_composite_trapezoids()
>   or _cairo_font_show_glyphs() with the destination argument
>   being that passed to _cairo_surface_create_pattern(). 
> 
>   Prior to the call pattern->source will be NULL; once drawing
>   with the pattern is finished, pattern->source will be 
>   released with cairo_surface_destroy().
> 
> Suggestions:
> 
> 1. If left with the current name, the function should be 
>    renamed to _cairo_surface_realize_pattern().
> 
> 2. Modifying the pattern passed in is ugly. Why not have
>    the function *return* the source pattern? And name it:
> 
>    _cairo_surface_create_pattern_source()
> 
> 3. More ambitiously, isn't the whole idea of a "source surface"
>    a bit forced? In order to recognize drawing with a
>    solid color, a backend either has to:
> 
>     A) Recognize the sequence "create a 1x1 solid image, fill
>        it with a r, use it as the source".
> 
>     B) Create a backend-specific "solid color" surface subtype.
> 
>    Wouldn't it be better to make the surface operations
>    (composite/composite_trapezoids/show_glyphs) take a pattern
>    for the source then have a _cairo_pattern_get_source_surface() 
>    that can be used for a fallback?
> 
>  4. Add my docs above (or a fixed version of them) somewhere.
> 
> I'd suggest we should do one or or the other of the first two
> even if the third makes sense in the longer term.

When I added the current pattern system to cairo, I thought of it as a
temporary solution and the plan was to move forward to something similar
to your suggestion number 3. At the time I wrote the pattern code, I
don't think we really knew how we wanted it to work. Today, I think we
have a much better idea. I sent a mail to the list some time ago with a
bunch of suggestions regarding to this [1]. It's basically like your
suggestion number 3. Unfortunately, I haven't had the time implement any
of this yet, but if no one beats me to it, I'll probably give it a go in
the second part of February.

[1]
http://lists.freedesktop.org/archives/cairo/2004-September/001898.html

-David