[Copyright status: this file is in the public domain.]

X supports clients querying a font's info; this allows a client to
position characters without needing to do constant server round-trips
to determine how large characters, or strings, are.

liblx represents this using two types.  There is LX_FONTINFO, which
represents a font's information as returned by requests such as
QueryFont, and LX_CHARINFO, which is used for two purposes: it
represents a single character's metrics, but it also represents the
metrics for a whole string in requests such as QueryTextExtents8.  (The
name could be better; it is mostly by analogy to Xlib's analogous
facilities, which use types called XFontStruct and XCharStruct.)

There are four functions for working directly with LX_FONTINFO and
LX_CHARINFO; there is also a utility function for computing the metrics
of a string based on a font.

LX_FONTINFO has a member lx_priv.  This points to data private to
liblx, data which makes some of the aforementioned functions easier to
implement.  Library code that uses LX_FONTINFOs may use the public
struct members or may use the private info; if application code changes
any of the public members, it must call lx_fontinfo_recache for the
library to udpate its cached info.  If an application is creating an
LX_FONTINFO without using liblx, the appropriate thing to do with
lx_priv is to set it to nil; lx_fontinfo_recache will then allocate
private data as appropriate and compute anything relevant.  However, it
is important to note that charinfos being nil indicates a lack of
per-character information; an LX_FONTINFO for a font which has
per-character metrics which are all identical to min-bounds and
max-bounds should have ncharinfo zero, but non-nil charinfos.

lx_fontinfo_recache may be relatively expensive; it should be called
sparingly, preferably only when necessary.

LX_FONTINFOs passed to the callback by lx_ListFontsWithInfo do not have
per-character info.  The individual routines' documentation state how
this affects their behaviour.

lx_fontinfo_recache
-------------------

void lx_fontinfo_recache(LX_FONTINFO *fi)

As outlined above, this recomputes liblx-private info used to
accelerate some calls, such as lx_fontinfo_charinfo.  Affected calls
mention in their documentation that they depend on the private info.

Does nothing if the LX_FONTINFO has no per-character info.

lx_fontinfo_free
----------------

void lx_fontinfo_free(LX_FONTINFO *fi)

This frees the LX_FONTINFO and everything it points to, assuming it was
allocated by liblx.

Operates normally if the lX_FONTINFO has no per-character info.

lx_fontinfo_free_priv
---------------------

void lx_fontinfo_free_priv(LX_FONTINFO *fi)

This frees just the library-private data for fi.  This is, for example,
suitable for use before freeing an LX_FONTINFO created directly by the
application.  It leaves the lx_priv pointer nil; if the LX_FONTINFO
isn't to be freed after all, another lx_fontinfo_recache call will
recompute the library-private data.

Does nothing if the LX_FONTINFO has no per-character info.

lx_fontinfo_charinfo
--------------------

const LX_CHARINFO *lx_fontinfo_charinfo(const LX_FONTINFO *fi, unsigned int cx)

This returns a pointer to an LX_CHARINFO describing the glyph
corresponding to character code cx in fi.  This is provided to free
applications from knowing the (relatively complex) rules for locating
the relevant LX_CHARINFO.  Note that the returned LX_CHARINFO pointer
is consted; it must not be written through, since under some
circumstances it may be shared among multiple character indices.

The behaviour of this call is undefined if cx is out of the range
0..65535.  For any in-range character index for which no info is
available, it will return nil.

This call depends on having an up-to-date lx_priv.

Always returns nil if the LX_FONTINFO has no per-character info.

lx_text_extents_8
-----------------

LX_CHARINFO lx_text_extents_8(const LX_FONTINFO *fi, const unsigned char *str, int len)

This is much the same as lx_QueryTextExtents8, but uses a client-side
LX_FONTINFO instead of a server roundtrip.

fi is of course the font info.

str is the string; len is its length.  As a convenience, if len is -1,
strlen(str) is used as the length.

This call depends on having an up-to-date lx_priv.

The LX_CHARINFO describing the string is returned.  The attr value is
zero.

For a zero-length string, the returned values are all zero, even though
for some of them (eg, ascent) this is not conceptually ideal.

Always returns an all-zero LX_CHARINFO if the LX_FONTINFO has no
per-character info.