== Font Features ==

Graphite fonts have user features. These are values that can be set to control
all kinds of rendering effects from choosing particular glyph styles for a group
of languages to how bad sequences should be displayed to almost anything.

A font (strictly speaking a face) has a set of features. Each feature has an
identifier which is a 32-bit number which can take the form of a tag
(4 characters) or if the top byte is 0 a number. Also each feature can take one
of a set of values. Each feature has a UI name from the name table. In addition
each value also has a UI name associated with it. This allows an application to
list all the features in a font and to show their names and values in a user
interface to allow user selection.

Feature values are held in a FeatureVal which is a compressed map of feature id
to value. The map is indexed via a FeatureRef which may be quered from a face
given an id. It is also possible to iterate over all the FeatureRefs in a face.

A face has a default featureVal corresponding to each language the face supports
along with a default for other languages. A face may be asked for a copy of one
of these default featureVals and then it may be modified to account for the
specific feature settings for a run.

[source, c]
----
include::../tests/examples/features.c[]
----

<1> The easiest way to turn a char[4] into a string is to append a nul, hence we
    make a char[5].

<2> Query the face for the default featureVal of the given lang or 0 for the
    default. The lang is a uint32 which has been converted from the string and
    is 0 padded (as opposed to space padded).

<3> Iterate over all the features in a font querying for the featureRef.

<4> Get the label in US English, for the feature name.

<5> Get the id for the feature name so that applications can refer to it.
    The id may be numeric or a string tag.

<6> Iterate over all the possible values for this feature and find the one the
    is equal to the value for the feature in the default featureVal. Then print
    out its details.

A sample run of.

----
./features ../fonts/Padauk.ttf ksw
----

Gives this output.

----
Khamti style dots (kdot)
	False (0)
Filled dots (fdot)
	False (0)
Lower dot shifts left (lldt)
	True (1)
Tear drop style washwe (wtri)
	True (1)
Long U with Yayit, long UU with Hato (ulon)
	False (0)
U and UU always full height (utal)
	False (0)
Insert dotted circles for errors (dotc)
	True (1)
Slanted hato (hsln)
	Sgaw style slanted leg with horizontal foot (1)
Disable great nnya (nnya)
	False (0)
Variant tta (vtta)
	False (0)
----
