[cairo] [cairo-commit] export meta-surface

[Carl Worth]

[Off-topic: Why does our cairo-commit mail include the changed files
as the subject instead of the one-line description of the change?
That's insane and I should be fixing it now instead of just
complaining. Anyway...]

On Fri, Jul 03, 2009 at 10:34:50AM -0700, Chris Wilson wrote:
> New commits:
> commit 6003ab77e1ebefadb97338de0e7da4a76d973b1a
> Author: Chris Wilson <chris at chris-wilson.co.uk>
> Date:   Fri Jul 3 18:26:50 2009 +0100
> 
>     Export meta-surface
>     
>     The meta-surface is a vital tool to record a trace of drawing commands
>     in-memory. As such it is used throughout cairo.
>     
>     The value of such a surface is immediately obvious and should be
>     applicable for many applications. The first such case is by
>     cairo-test-trace which wants to record the entire graph of drawing commands
>     that affect a surface in the event of a failure.

Thanks for doing this. It's been desired for a very long time, of
course.

> +/**
> + * cairo_meta_surface_create:
> + * @content: the content of the meta surface
> + * @width_pixels: width of the surface, in pixels
> + * @height_pixels: height of the surface, in pixels
> + *
> + * Creates a meta-surface which can be used to record all drawing operations
> + * at the highest level (that is, the level of paint, mask, stroke, fill
> + * and show_text_glyphs). The meta surface can then be "replayed" against
> + * any target surface with:
> + *
> + * <informalexample><programlisting>
> + *	cairo_meta_surface_replay (meta, target);
> + * </programlisting></informalexample>
> + *
> + * after which the results in target will be identical to the results
> + * that would have been obtained if the original operations applied to
> + * the meta surface had instead been applied to the target surface.
> + *
> + * The recording phase of the meta surface is careful to snapshot all
> + * necessary objects (paths, patterns, etc.), in order to achieve
> + * accurate replay.
> + *
> + * Since 1.10
> + **/

I think we need to say a little more here about what width and height
mean. Do they establish an initial clip extent? If so, is that
clipping enforced or just possible? (That is, does cairo guarantee
that rendering outside these bounds will not appear, or does it simply
say that rendering outside these bounds is undefined?)

That issue of width and height was really the only thing that kept me
from exporting meta surfaces almost from the beginning.

> +/**
> + * cairo_meta_surface_ink_extents:
> + * @surface: a #cairo_meta_surface_t
> + * @x0: the x-coordinate of the top-left of the ink bounding box
> + * @y0: the y-coordinate of the top-left of the ink bounding box
> + * @width: the width of the ink bounding box
> + * @height: the height of the ink bounding box
> + *
> + * Measures the extents of the operations stored within the meta-surface.
> + * This is useful to compute the required size of an image surface (or
> + * equivalent) into which to replay the full sequence of drawing operaitions.

[Looks like the misspelling of operaitions has been fixed
since---sorry for my late review---so I won't mention it here.]

I don't really have a problem with it, but I did want to point out
that "ink" is a new term for our API. I don't really have anything
else to propose for it, (and our documentation of
cairo_user_scaled_font_text_to_glyphs_func_t does already mention "ink
extents" so there is precedence for this.

So the code looks fine to me. Thanks again!

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.cairographics.org/archives/cairo/attachments/20090812/cd007153/attachment-0001.pgp