[cairo] _cairo_surface_create_pattern docs and suggestions

[Owen Taylor]

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.

Regards,
						Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050120/9a10656a/attachment.pgp