[cairo] cairo reset

[Behdad Esfahbod]

On Fri, 2006-09-22 at 13:14 -0400, Carl Worth wrote:
> 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.


This is awesome material for documentation btw.

behdad

> 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
-- 
behdad
http://behdad.org/

"Commandment Three says Do Not Kill, Amendment Two says Blood Will Spill"
        -- Dan Bern, "New American Language"