Re: [ft] I need help understanding the use of face_index in FT_New_Face.

[Werner LEMBERG]

> I'm writing a font cache based on freetype. I'm creating an OpenGL
> text rendering library and need to textures of the glyphs. This is the
> first time that I have ever had the need to delve into fonts and
> unfortunately, the freetype documentation seems to make the assumption
> that those using the library have a deep understanding of fonts.

Please point to places in the documentation which are unclear so that
we can improve it.  Or you might provide patches after you've
understood the issue :-)

> I'm developing the cache on Windows, but it needs to be cross
> platform.  Since I cannot find a good example of different faces
> within a font, and the fact that most Windows TrueType fonts have
> only one face, I was just going to ignore the face_index parameter
> and leave it at zero.

A standard TrueType (TTF) or OpenType (OTF) font has *always* a single
face.  However, a TrueType (TTC) or OpenType (OTC) collection font has
more.  Take for example the standard Windows math font, `cambria.ttc',
which has two faces: Index 0 is for normal typesetting (`Cambria
Regular'), and index 1 is for mathematical formulae (`Cambria Math
Regular').  So in case you want to handle TTCs and OTCs, you *must*
support multiple faces.

> Then while trudging through the freetype source, I noticed a comment
> that when loading a Macintosh suitcase, the face_index corresponds
> to regular, bold, italic, etc., variants within the suitcase. :/

Yes, this is something not used on Windows normally.

> My question is how to I document this? I don't fully understand why
> a font would have multiple faces.

Usually, it makes fonts smaller, since the fonts can share common
TrueType tables.  In the Cambria example, the glyph shapes for most
characters are exactly the same, but some of them are different, and
the glyph metrics differ partially.

In case of Macintosh suitcases, however, it's rather to reduce the
number of files of a given font family.  Actually, it's quite clever:
Why having four files for normal, bold, italic, and bold italic, if it
is possible to have a single one?  There are rich families which have
much more shapes, and they can all be put into a single file.  Even
here it is possible to avoid duplication of some TrueType font tables,
so a single suitcase file is smaller than having multiple font files.


    Werner