[cairo] semantics of cairo_copy()

[Carl Worth]

At Sat, 01 Jan 2005 16:42:48 -0500,
Jonathan Brandmeyer wrote:
> What are the semantics of cairo_copy()?  Specifically: What parts of the
> state are copied?

A cairo_t contains a stack of graphics state objects, (managed by
cairo_save and cairo_restore). The semantics of cairo_copy is that it
copies the contents of the graphics state from the top of the stack of
src to the top of the stack of dest.

The copy copies all of the graphics state, (which is really everything
that can be set in cairo, minus the stack).

> What preconditions must be met for src and dest before calling
> cairo_copy()?

Valid cairo_t objects, (results of cairo_copy).

> Can a cairo_t targeting a PNG file be copied to a cairo_t targeting
> X11?

That should "work", but the resulting cairo_t would then be targeting
the PNG file. I won't argue that this makes a lot of sense.

> Is it an error to perform a cairo_copy() to a cairo_t that has not
> been targeted from one that is?**

Copying to a non-targeted cairo_t should work just fine. I just tried
the following and it worked just fine:

	/* Given cr, targeting a PNG image */
	cairo_t *copy;
	copy = cairo_create ();
	cairo_copy (copy, cr);

> ** This one is an error right now: the code is "SIGSEGV" ;)  At worst,
> it should set the error flag.  Is it possible to make this work at all?

SIGSEGV is almost certainly a cairo bug. Can you show me the code
leading to this?

> What usage model is cairo_copy intended for?

The usage model is that some users want to do graphics state
management in ways that don't fit a stack model very well. For such
users, cairo_save/cairo_restore will be unsatisfactory. So, instead
the user can use separate cairo_t objects and copy the state around
between them with cairo_copy.

That was the idea anyway. In practice, the semantics of "copy just the
top object on the stack" are pretty confusing. The best replacement
I've had in mind is to create a new object, cairo_gstate_t and allow
the user to get/set this object. That should be less confusing, (but
it a bit annoying in that the new object won't have any functions
other than those needed for memory management).

You do raise a good question on whether the target surface should be
part of the graphics state or not. Owen raised a similar question
recently when he asked if setting a new target surface shouldn't reset
the CTM to the default, (since a new device should imply a new device
space).

One use for having the target surface on the stack, (and for
maintaining the CTM across the target surface change), is for
compositing objects to a temporary surface and then compositing the
result as a group to the destination. I've been wanting to add direct
support for this operation to cairo anyway with implicit scratch
surfaces, (which would not require any size information from the user
and could just grow as needed). I just need to work out the right
interface for compositing the group back onto the destination.

If we had implicit scratch surfaces it may make sense to split the
target surface apart from the primary graphics state. It might even
make sense to require the target surface at the time of cairo_create
and not let it be changed.

-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.freedesktop.org/archives/cairo/attachments/20050111/193d1b54/attachment.pgp