TkGS Specification - Internals: Graphics Contexts

Introduction

From a user's point of view, Graphics Contexts (GCs) are defined as TkGS_GCs, which are opaque tokens. Internally, drawables are defined by the TkGS_GC_ structure (notice the trailing underscore). This structure is a "subclass" (using OOP terminology) of the more generic TkGS_Obj structure.

Structures


TkGS_GC_
Description
This structure is a "subclass" of the TkGS_Obj generic structure. Thus, its first member, header, contains a TkGS_Obj in order for a TkGS_Drawable_ to be used by generic object code.
It first stores the device-independent drawing parameters in the form of a TkGS_GCValues structure, values. The field valueMask is in turn used to synchronize the device-independent state held by values and the device-specific state (for example, selected Objects -- Pens, Brushes... -- in Win32 GDI). This allows for lazy evaluation of parameter modifications. For example, changing the foreground color several times won't issue any potentially expensive device-dependent calls, the drawing state will only be synchronized when the drawing is performed, and only relevant state will be synchronized (for example, a drawing operation that doesn't make use of the background color won't require up-to-date information).
Status
Internal use only. Not much likely to change.
Structure
typedef struct TkGS_GC_ {
    TkGS_Obj      header;	/* Must be first */
    TkGS_GCValues values;	/* Device-independent GC values */
    unsigned long valueMask;	/* Mask of altered values since the last
				 * call to one of the GC values accessors
				 * (eg. TkGS_SetGCValues) */
} TkGS_GC_;

Accessors


TkGSGC_GCValues
TkGSGC_GCValueMask
Description
Gives read/write access to the values and valueMask field of the TkGS_GC_ structure.
Status
Internal use only. Unlikely to change.
Declaration
#define TkGSGC_GCValues(objPtr) \
    (((TkGS_GC_*)objPtr)->values)
#define TkGSGC_GCValueMask(objPtr) \
    (((TkGS_GC_*)objPtr)->valueMask)
Arguments
The object to access.

Functions


TkGSNewGC
Description
Allocate a new TkGS_GC_.
Status
Internal use only. Unlikely to change.
Declaration
TkGS_Drawable_ * TkGSNewGC();
Arguments
None.
Returned value
A pointer to a newly allocated TkGS_GC_.
Side effects
A new object is allocated.

TkGS_GetGCBaseType
Description
Return a pointer to the Gc object base type. This is intended to be used by device drivers for creating new device-specific GC types.
Status
Complete.
Declaration
TkGS_BaseType* TkGS_GetGCBaseType();
Arguments
None.
Returned value
A pointer to the GC base type.
Side effects
None.

TODO