Graphics Environment: 6.2 Graphics State: Working with GStates

GrCreateState(), GrDestroyState(), GrSaveState(), GrRestoreState()

As has been mentioned, most graphics routines require that a GState handle be provided as an argument. Beginning programmers are often unclear on just where to get the GState to use.

Many drawing routines are called by MSG_VIS_DRAW . This message provides a GState, and all routines in the handlers for this message should use the provided GState. Creating a new GState under these circumstances is unnecessary and wasteful. However, sometimes you will need to create a GState. GrCreateState() creates a GState with the default characteristics. You must specify the window with which the GState will be associated.

Commands which change drawing attributes or the current position change the GState.

GrDestroyState() is used to get rid of a GState, freeing the memory to be used by other things. If GStates are created but not destroyed, eventually they will take too much memory. Normally, for each call to GrCreateState() there is a corresponding GrDestroyState() . MSG_VIS_DRAW handlers don't need to destroy the passed GState. Graphics states are cached so that GrCreateState() and GrDestroyState() don't normally need to call MemAlloc() or MemFree() . When GStates are freed, their space is added to the cache. When the memory manager needs to find space on the heap, it flushes the cache.

A geode is most likely to call GrCreateState() when about to draw a piece of geode-defined UI. Other than that, you'll probably be using GStates provided to you by the system. You might want to create a GState if you wanted to calculate something (perhaps the length, in inches, of a text string) when you had no appropriate GState.

GrSaveState() provides a sort of "push" operation that works with GStates. When you call certain functions, like GrSetAreaColor() , new values will wipe out the values of the old GState. But if you've previously called GrSaveState() , then any time you call GrRestoreState() on your saved state, it will come back and displace the current state. Your application can save a GState to save a commonly used clipping region, which could then be restored by restoring the state instead of repeating all the operations needed to duplicate the region. GrSaveTransform() and GrRestoreTransform() are optimizations of GrSaveState() and GrRestoreState() , but they only preserve the GState's transformation.

GEOS SDK TechDocs|

6.1 GState Contents | Next:

7 Working With Bitmaps