[cairo] cairo reset

[Carl Worth]

On Fri, 22 Sep 2006 02:09:02 -0700 (PDT), Kevin Brooks wrote:
> I want to know if there is something like
> "cairo_reset(cairo_t*)" function to "reset" cairo
> context or it must be destroyed and created to start
> over again.

What state are you looking to reset exactly?

Currently, within the cairo_t there are a few different things that
you might mean when saying "reset":

The path:		Can be reset with:

			cairo_new_path (cr);

The target surface:	Can be cleared to 0 in all channels with:

			cairo_set_operator (cr,	CAIRO_OPERATOR_CLEAR);
			cairo_paint (cr);

The graphics state:     This includes the current transformation matrix,
			line stroking parameters, source pattern,
			etc. Basically any state that can be set in
			the cairo_t context aside from the path and
			the contents of the everything but the path.

			There is not currently a call to reset the
			graphics state to its defaults, but one can
			reset it to any state which was previously
			saved with cairo_save(). So, for example:

			cairo_save (cr); /* Save graphics state */
			... /* draw stuff */ ...
			cairo_restore (cr); /* Restore saved state */

The error status:	Initially the status has the non-error value
			of CAIRO_STATUS_SUCCESS. Once an error is set
			in the cairo_t context there is no way to
			reset that error, and the only thing that can
			be done with the context is to cairo_destroy
			it.

So there are two places where I mentioned above that there is no
available "reset". The first is the graphics state. We could add a way
to set the graphics state to all-default values if someone found that
very interesting. But I'm not sure that the default state is really
all that interesting---it has some fairly arbitrary things in it,
(such as an opaque black source pattern). One part of the default
graphics state that is often interesting is an identity
transformation matrix, and that can be set at any time with
cairo_identity_matrix().

The other state that cannot be reset is the error status. The
rationale for not making this recoverable is that we don't have any
guarantee that we can restore the context to any particular state
after an error occurs. Without a huge audit and a lot of pain to make
every cairo operation atomic, the only conceivable state to restore to
would be the default state. And if we had an operation that did
recover-error-and-return-context-to-default-state then I would argue
that that wouldn't achieve anything that cairo_destroy;cairo_create
does not also achieve, but that it could lead to confusion as people
might not expect all of the state to be reset when recovering from
errors.

If people can share real-world examples of where the above strategies
have lead to pain, I would love to hear about them so that we can
reconsider and fix things as needed.

Thanks,

-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/20060922/951027cf/attachment-0001.pgp