[cairo] _cairo_surface_create_pattern docs and suggestions

[Kristian Høgsberg]

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().

You mean "if left with the current behaviour"?

> 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.

or C) wrap the original pattern in a dummy surface, which is what I do 
in the PDF backend.
> 
>    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?

I've been wanting to do this rewrite for a while.  I think it should be 
possible to remove the create_pattern function for the surface from the 
vtable entirely and just keep the functionality internal to the surfaces 
that require it.

> 
>  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.

I think we shold go straight for number 3.  I'll try to find the work I 
did on this previously.

cheers,
Kristian