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

[Mark Speir]

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.

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. 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. :/ Because of this, I made a couple of functions to enumerate the 
number of faces within a font and to allow the user to switch faces.

My question is how to I document this? I don't fully understand why a font 
would have multiple faces. It doesn't seem to have a place with Windows fonts, 
at least Roman based fonts, and I don't have a Mac and do not understand any 
language but English, so divining the purpose on my own has been futile. I have 
two functions in my code that may or may not do something and may or may not be 
needed, but I don't know why and I cannot create a piece of sample code to 
document these functions, or for that matter, explain why they might be needed.

Can someone explain this to me?

Thanks,
Mark Speir