[cairo] Proposal: cairo_save_state/cairo_restore_state

[Carl Worth]

On Tue, 18 Jan 2005 10:16:01 -0500, Carl Worth wrote:
> 
> Yes. That's a bug in naming. I think replacing cairo_copy with
> cairo_current_gstate and cairo_set_gstate should clear this up.

It's interesting to go back sometimes and see how old some ideas are.

Apparently, very close to a year ago I had an idea to eliminate
cairo_copy and replace it with (what we would call today)
cairo_get_gstate and cairo_set_gstate.

What happened back then was that we did eliminate cairo_copy. And the
primary reason for doing so is still valid:

    Copying a cairo_t is not a well-defined or generally useful
    concept. A cairo_t contains several things that don't make sense
    to copy generally:

	the target surface
	a stack of graphics "states"
	a path[1]

But what we never did is implement something to provide the missing
useful functional. Namely, there's no easy way to copy all graphics
state settings, (line_width, source pattern, font parameters, etc.),
in a single operation.

Even knowing about that API gap, I've avoided implementing anything
since I've never been fully satisfied with the API I suggested above.
But suddenly, a recent bug report[2] provided the answer. Robert
Staudinger provided the excellent insight that the desired operations
are variants of cairo_save/restore and should be named as such.

So now I'm excited to go ahead and implement this.

The advantage of this approach is that it allows users to manipulate
graphics states as individual objects in a more general way than the
stack-based nature of cairo_save/restore allows (since sometimes the
stack just isn't a good fit for what the user wants to do).

Here's the API that I think is needed:

	cairo_state_t *
	cairo_save_state (cairo_t *cr);

	void
	cairo_restore_state (cairo_t *cr, cairo_state_t *state);

along with the necessary:

	void
	cairo_state_reference (cairo_state_t *state);

	void
	cairo_state_destroy (cairo_state_t *state);

Note that I've gone away from "gstate" in favor of "state". This is
because "state" is a much cleaner and more cairo-style-consistent
abbreviation for "graphics state". Additionally, there is no name
conflict with any other "state", (the only candidate would be cairo_t
for which the only name used by the documentation is "context" not
"state").

Additionally, I've followed Robert's style of naming the new functions
in a way that makes clear the relation to cairo_save/restore.

These functions should be _really_ easy to implement. I'll come up
with a patch soon if nobody beats me to it.

As usual, I'm interested in any comments or feedback that anyone might
have.

-Carl

[1] It is useful to copy a path, and we do have
cairo_copy_path/cairo_append_path to allow that.

[2] https://bugs.freedesktop.org/show_bug.cgi?id=5686
-------------- 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/20060124/52a67289/attachment-0001.pgp