== 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)
----