An X GC, which stands for `graphics context', is a server-side object
collecting state used by various graphics requests, such as foreground
colour and font.  The X requests to create, change, and destroy GCs are
fully supported by liblx (a GC, like other server-side objects such as
windows and pixmaps, is represented as an LX_XID in the API).

There are, however, two important things to mention, which are why GC
documentation is in its own file.

One is LX_GCFUNCTION values.  Unlike most of liblx's values, there is
some structure to LX_GCFUNCTION values.  They are chosen such that bit
operations on function values work, with __src and __dst available to
represent the source and destination respectively, *provided* that,
once done with the bit operations, you AND with __mask and then OR in
__base.  LX_GCFUNCTION_norm() is a convenience macro for this, as in

	LX_GCFUNCTION_norm(LX_GCFUNCTION__src & ~LX_GCFUNCTION_dst)

(which evaluates to the same value as LX_GCFUNCTION_AndReverse,
AndReverse being the canonical X name for the src&~dst operation).

The other is shadow GCs.  It is convenient, in many applications, to
keep a client-side copy of the info in a GC, so that (for example) when
switching from drawing one thing to drawing another thing, there is no
need to change the foreground colour in the GC unless the two colours'
pixel values aactually differ.  liblx contains code to facilitate this.

There is a type, LX_SGC, which represents a GC plus a client-side
shadow.  There are calls on SGCs analogous to CreateGC, ChangeGC,
CopyGC, and FreeGC requests, plus a call which convertsd an SGC into an
LX_XID for the underlying GC needed for requests such as CopyArea which
need a GC.

It is important to note that even *creation* of the underlying GC is
done lazily.  For example, when creating an SGC, the drawable must be
valid at the time the create operation is pushed to the server, which
is later than lx_CreateSGC_* time.  Similarly, when making a GC setting
that uses a server-side resource, such as using a bitmap as a
clip-mask, the resource must be valid at push time, not at set time.

Unfortunately, LX_SGC is assignment-compatible with LX_XID, so you will
not get compile-time warnings if you mistakenly pass an LX_SGC directly
to a graphics request that requires a GC.  You will get a run-time X
error instead.

lx_CreateSGC_va, lx_CreateSGC_attr
---------------  -----------------

LX_SGC lx_CreateSGC_va(LX_CONN *conn, LX_XID d, ...)
LX_SGC lx_CreateSGC_attr(LX_CONN *conn, LX_XID d, unsigned int mask, const LX_GC_ATTRIBUTES *attr)

These are just like lx_CreateGC_va and lx_createGC_attr except that
they return an LX_SGC instead of an LX_XID representing a GC.

lx_ChangeSGC_va, lx_ChangeSGC_attr
---------------  -----------------

LX_XID lx_ChangeSGC_va(LX_CONN *conn, LX_SGC sgc, ...);
LX_XID lx_ChangeSGC_attr(LX_CONN *conn, LX_SGC sgc, unsigned int mask, const LX_GC_ATTRIBUTES *attr)

These are just like lx_ChangeGC_va and lx_ChangeGC_attr except for two
things: (1) they operate on an LX_SGC instead of an LX_XID
representing a GC, and (2) they support one additional facility.

When changing an SGC, it is often useful to immediately push the
changes, if any, because the next thing the application wants to do is
a graphics request.  Rather than forcing applications to make a
separate lx_SGC_GC call each time, lx_ChangeSGC_* support an auto-push
facility.  If in lx_ChangeSGC_va you terminate the arglist with
LX_GCV_PUSH instead of LX_GCV_END, or if in lx_ChangeSGC_attr you set
the LX_GCM_PUSH bit in the mask, the changes will be pushed immediately
and the underlying GC's LX_XID will be returned.  If you don't enable
auto-push, while the returned value will be a valid LX_XID from a C
perspective, is meaningless from an X perspective.

lx_CopySGCtoGC, lx_CopySGCtoSGC
--------------  ---------------

extern void lx_CopySGCtoGC(LX_CONN *conn, LX_SGC fsgc, LX_XID tgc, unsigned int mask)
extern void lx_CopySGCtoSGC(LX_CONN *conn, LX_SGC fsgc, LX_SGC tsgc, unsigned int mask)

These copy from fsgc to tgc (...toGC) or tsgc (...toSGC), under control
of the mask, like a CopyGC request except the source is an SGC.

There is no lx_CopyGCtoSGC because there is no request which can read
back a GC's components.

There is no lx_CopyGCtoGC; that's just a plain CopyGC request.

lx_FreeSGC
----------

extern void lx_FreeSGC(LX_CONN *conn, LX_SGC sgc)

Analogous to lx_FreeGC, this frees an SGC.

lx_SGC_GC
---------

LX_XID lx_SGC_GC(LX_CONN *conn, LX_SGC sgc)

This returns the underlying GC's LX_XID for an SGC.  It also pushes any
changes made to the server.  If the underlying GC has not yet been
created, the creation is pushed.  If nothing needs pushing, this is a
cheap call which does not generate any protocol requests, just
returning the GC's LX_XID.