[cairo] save/restore guidelines?

[Owen Taylor]

On Thu, 2008-08-14 at 16:40 -0300, Ian Britten wrote:
> Hi all,
> I'm sortof familiar with the save/restore idiom when drawing,
> from some previous work with PostScript.  I see that Cairo
> provides this mechanism, and was wondering if anyone had any
> guidelines about when (or when not) to use it?

The most basic place you want to use save/restore is to make
a function that draws something not affect the context. So
I can do:

 A) set some state on my cairo context
 B) call a function that draws something
 C) Draw something myself 

I shouldn't have to worry that B) messed up the state in A).

There are also some more esoteric uses. E.g., to take advantage 
of the fact that save/restore don't affect the current path. If you
tried to stroke an oval by:

 - scale non-uniformly in the x/y directions
 - create a circular path
 - stroke

Then your stroke would have non-uniform widths. So, instead you can:

 - save
 - set scale non-uniformly
 - create a circular path
 - restore
 - stroke

save/restore is essential when using cairo to draw things directly.
If you are wrapping cairo in a non-cairo API then it may not be 
so useful since the non-cairo API will already be doing the work
of tracking all the state.

- Owen