This is a FreeType/2 users' mini-FAQ

Table of Contents:

Q1:  Where can I find the latest FreeType/2 release?
Q2:  Now that I have FreeType/2 installed, how do I actually add TrueType
     fonts to OS/2?
Q3:  When will you add font-smoothing to the DLL? I really want that!
Q4:  Why does IBM's TrueType engine do such a poor job?
Q5:  But there are still differences with the glyphs produced by Windows or
     the Mac, right?
Q6:  I've got TrueType Times New Roman installed but the system still seems
     to be using the original ATM (Type 1) font. Why this odd behaviour?
Q7:  I noticed it takes a second or two before the Font Palette object opens
     for the first time. Why?
Q8:  I noticed the characters sometimes have odd spacing. When will you fix
     it?
Q9:  Could you explain the open fonts limit?
Q10: Can you recommend some fonts to use?
Q11: What's a 'broken glyph'?
Q12: Why do some fonts appear twice, once starting with an '@'?
Q13: I've got a Chinese (Japanese, Korean) font but the characters aren't
     there! Why?
Q14: I tried to use a DBCS font but I got an exception in UCONV.DLL. What's
     wrong?
Q15: My system won't boot after I installed FreeType/2 and the uninstall
     script won't work when I boot to command line. What now?
Q16: I'm upgrading from previous version and I don't want to uninstall and
     reinstall. Is there any other way?
Q17: What's this stuff about Times New Roman being aliased to Tms Rmn?
     Please explain this.
Q18: What's all this about "Unicode encoding"?
Q19: Why would I care if a font uses Unicode?
Q20: What does "report Unicode fonts as MBCS compatible" mean?
Q21: What is DBCS font association?
Q22: What OS2.INI entries correspond to the various configuration settings?
Q23: Why are WPS folders/container controls taking a long time to refresh?
Q24: Are OpenType fonts supported?


Questions & Answers:

Q1: Where can I find the latest FreeType/2 release?

A1: Until the FreeType/2 homepage (http://www.freetype.org/ft_os2/index.html)
can be updated, please look for the latest release on the Hobbes archive:
http://hobbes.nmsu.edu/h-search.php?key=ft2v&pushbutton=Search


Q2: Now that I have FreeType/2 installed, how do I actually add TrueType
fonts to OS/2?

A2: I thought everyone knew that... It's simple, really. Open the Font
Palette object (in System Setup folder) then click 'Edit font' and 'Add'.
Now type the directory path where your TrueType fonts reside, such as
'C:\WINDOWS\FONTS' if you have Win95 and click 'Add'. You'll be presented a
list of all fonts that OS/2 found in specified directory. Simply select all
fonts you wish to install click 'Add' for the last time. If you wish to
remove fonts, just use the 'Delete' button in the 'Edit Font' dialog.
TIP: If you wish to add font to OS/2 but don't want to actually copy the
file, just type the directory name where the font files already are instead
of 'X:\PSFONTS' in the 'Add New Fonts' dialog.


Q3: When will you add font-smoothing to the DLL? I really want that!

A3: Short answer: We can't.
Long answer: The FreeType library already supports font-smoothing (or
antialiasing or grayscaling). The problem is that OS/2's font engine, in
its current incarnation, doesn't know anything about anti-aliased text and
is only able to manage monochrome bitmaps. Font smoothing support would
require some changes of PM/GPI/GRE components, which certainly is out of
our scope, and isn't planned by IBM (to our knowledge) in the foreseeable
future, if ever.

If you really need font smoothing in your application, you can still use
the FreeType library itself. Be warned that it is a rather low-level engine
and that you'll need to add a various number of text features on top of
this code to get the equivalent of PM's font API.  (Note: a number of
programs do this, including the Mozilla applications as well as the latest
port of the QT4 library.)

Version 2 of FreeType is now available, and may ease the pain for developers
somewhat.

There was also a somewhat experimental program called the "Innotek Font
Engine" released a couple of years back, which actually does modify and 
override key parts of PM/GPI/GRE and thus can (in theory) allow font 
smoothing in arbitrary applications, although it isn't perfectly stable.  
Do a search online if you're interested.


Q4: Why does IBM's TrueType engine do such a poor job?

A4: It'd be easy to throw one or two stones at IBM's engineers if this was
the result of lazy coding or bad software engineering. However, the problem
is more complex, and PSP programmers deserve little, if any, blame.

Trouble is that the TrueType specification, which can be found both on
Microsoft and Apple sites, has severe lacks, as well as particularly fuzzy
definitions. Part of the TT spec is the TrueType bytecode specification.
This bytecode is used to write glyph programs that are used to explicitely
hint each glyph to have it rendered perfectly on the screen (and on
printers). It is made of approximately 200 opcodes, which relate to moving
points on a pixel grid, measuring distances in any kind of direction,
keeping widths and heights consistent across a single font, etc..

Some of these opcodes are simply un-documented, or lack precise and
important details related to their exact implementation. As a consequence,
when FreeType started, it's first bytecode interpreter exhibited results
which were very similar to OS/2's one (i.e. bad baseline, incoherent
widths, "swashs" and bad serifs, etc..). There are several commercial
engines which provide the same kind of "erroneous" output, like the one in
the BeOS for instance.

It took FreeType developers _many_ months and experimentation to discover
the real meaning of some opcodes, and incorporate it into the library. This
"spelunker" work has been painful and slow, which is why few commercial
companies, if any, dared to do it, but it finally pays off ! Moreover, the
FreeType library is released under a BSD-like free license. This means that
_anyone_ is now able to take the work that has been done to rewrite or fix
his own TrueType interpreter. (Of course, another good idea is to use
FreeType as your core TrueType engine, to be able to benefit to ongoing
fixes and "undocumented features" discoveries, etc...)

Incidentally, IBM did make some major improvements to their own TrueType
driver in later FixPaks.  But FreeType/2 still looks better. :p


Q5: But there are still differences with the glyphs produced by Windows or
the Mac, right?

A5: Right. Another feature of the TrueType specification is to use fixed
float pixel coordinates. When measuring distances along diagonals, some
rounding errors usually occur. Also, some TrueType opcodes have a more or
less "chaotic" behaviour, where a ridiculous difference in inputs can
produce vastly different results. These factors mean that the only way to
match bit-to-bit the glyphs produced by Windows or the Macintosh is to
implement the _exact_ same computation routines, and reproduce all their
rounding errors ! As FreeType is a clean-room implementation, this will
never be possible. Note that the bitmaps match in 95% of cases, at least, 
and that there are already differences between the Win 3.1 and Win95 
TrueType renderers (i.e. look at the "m" of Arial at size 8 for example).

The FreeType team tries very hard to "catch" differences, but there is a
point where this just isn't possible... However, we're very satisfied with
its current quality, and we hope you'll be too :-)


Q6: I've got TrueType Times New Roman installed but the system still seems
to be using the original ATM (Type 1) font. Why this odd behaviour?

A6: It seems in case of a name clash OS/2 is using the font that was
installed later. Try removing and reinstalling the TrueType font.
Alternately remove the ATM (Type 1) font (not recommended).
Experiments also suggest that different apps behave differently. Some apps
will for example show both fonts but will use only one of them anyway. It
really depends.


Q7: I noticed it takes a second or two before the Font Palette object opens
for the first time. Why?

A7: Because FreeType/2 postpones as much work on the fonts as possible
until it's really needed. This means the first opening of a font is a bit
slower. But it also means no resources are unnecessarily wasted. And it's
not really that bad :-) This behaviour is also noticeable when e.g. opening
a document for the first time. Note that subsequent openings are OK because
OS/2 caches as much information as possible.


Q8: I noticed the characters sometimes have odd spacing. When will you fix
it?

A8: I won't. It's not really a bug, it's a feature. If they weren't spaced
'oddly', the result might look better, but only at the cost of
Windows-style 'WYSIWYG', i.e. what you see on screen will almost certainly
look totally different on any other device. Anyway, the spacing is
controlled by OS/2 and not by the Font Driver itself, so if you still don't
like it, IBM is the right one to ask :-)

This problem is particularly visible in Netscape. Most probably this
happens because Netscape tries to use fractional pointsizes, but most
TrueType fonts don't allow that. This means that Netscape sometimes
positions characters as if they were e.g. 8.6 points while their actual
size is only 8 points.  (There is an optional sort-of-workaround for this 
that you can enable in the configuration GUI.)


Q9: Could you explain the open fonts limit?

A9: Sure. If you install 50 fonts in OS/2, the system opens them all at
startup and keeps them open until shutdown. While many users may want to
have large number of fonts installed (like me), very few of them probably
use all the fonts all the time. This of course wastes lots of memory and
swap space. Just for your information, normal fonts take up 30-50 K of
memory with FreeType/2, but for example Times New Roman MT 30 takes over
500K!

FreeType/2 overcomes this problem by only actually keeping in memory the
last n most recently used fonts. The actual number is settable via entry in
OS2.INI and there's an simple REXX script to do that. Good default might be
10-15 fonts, depending what you want to do with them.

Note that this process is totally transparent to the system. You won't have
to do anything, FreeType/2 will take care of everything. The only things
you will notice is dramatically reduced memory consumption and when working
with large numbers of fonts there may be slight delay when reopening a
font.


Q10: Can you recommend some fonts to use?

A10: Yes! I recommend to use Micro$oft's (oh no!) Core Fonts - Times New
Roman, Arial and Courier New, plus other MS fonts. There are several
reasons: the fonts have very good quality, stick to the TrueType spec prety
well, support many countries and are widely available. Moreover they're
free.  Do a search on Hobbes for "core fonts"; they may also still be 
available from MS's Web site.
Note: If you want to copy the fonts from a Win95 machine, they're in
\WINDOWS\FONTS. Watch out, the directory is hidden!


Q11: What's a 'broken glyph'?

A11: Some fonts contain buggy or 'broken' glyphs that cannot be reliably
loaded and rendered. Those glyphs are usually very rarely used so you might
never notice. There was a problem with the first Beta of FreeType/2 that if
there was a single broken glyph in a font, the
whole font didn't work.


Q12: Why do some fonts appear twice, once starting with an '@'?

A12: It's because they contain DBCS character support. If you don't have any
need/ability to write DBCS (East Asian) text, you can safely ignore these 
font names. Basically, the DBCS characters in them are rotated 90 degrees
counterclockwise. It allows you to write vertical text (e.g. Chinese) with
a normal word processor. You write the text horizontally but if you turn
the resulting page 90 degrees clockwise, you've got vertical text.
It's not working perfectly yet.


Q13: I've got a Chinese (Japanese, Korean) font but the characters aren't
there! Why?

A13: Most probably the font and your system settings don't mix. One
possible cause is that your country setting is different than that of the
font and the font contains no information about what language it's meant
for. In that case, FreeType/2 has to guess from your country setting. This
means it might try to treat e.g. Japanese font as a Korean one which means
you won't be able to access the Japanese characters in it. It's all a bit
more complicated but it's a result of how national language support is done
in OS/2.


Q14: I tried to use a DBCS font but I got an exception in UCONV.DLL. What's
wrong?

A14: UCONV.DLL is used for character code translation. A likely cause is
that you are missing the required translation table in \LANGUAGE\CODEPAGE
directory on your boot drive. Look for file named 'IBM<CP>', where <CP> is
the codepage you use, e.g. IBM950 for Taiwan or IBM949 for Korea.


Q15: My system won't boot after I installed FreeType/2 and the uninstall
script won't work when I boot to command line. What now?

A15: But you've archived the key files, haven't you? If not, one way out of
this mess is booting to command line and renaming or deleting FREETYPE.DLL
from \OS2\DLL. Your system should boot then.


Q16: I'm upgrading from previous version and I don't want to uninstall and
reinstall. Is there any other way?

A16: Yes! There's a little utility called REPMOD.EXE which allows you to
replace files that are in use. In case you don't already have it, it's
included in the FreeType/2 package. You should simply run UPDATE.CMD. The
new version will be used on next reboot.


Q17: What's this stuff about Times New Roman being aliased to Tms Rmn?
Please explain this.

A17: OS/2 contains a bitmap font called Tms Rmn which is often used in dialog
windows and elsewhere. The bitmap font contains only several pointsizes (8,
10, 12, 14, 18, 24). If you request a missing pointsize, OS/2's graphics
engine (GRE) substitutes it from the (outline) ATM font Times New Roman
which can also be referred to as Roman/Tms Rmn. Now FreeType/2 mimics this
functionality and can fully replace the ATM version. I recommend to
uninstall the ATM font since if both fonts are installed, some apps use the
ATM one, others TrueType one, without any apparent logic. If you uninstall
(via Font Palette) the ATM version, you will always get high-quality
TrueType Times New Roman.


Q18: What's all this about "Unicode encoding"?

A18: One of the things which a font driver like FreeType/2 has to do is 
maintain an index or lookup table for each character in a font.  This index
(called a glyphlist) has to conform to one of several formats which OS/2 
understands.  Unicode is one such glyphlist, but there are others (mostly
corresponding to various standard codepages).  Most TrueType fonts support 
multiple encodings, and hence any of a number of glyphlists could be used.  

FreeType/2 uses some complex heuristics to choose the optimal glyphlist to 
use for a particular font.  However, it has an option (which you can set via 
ftconfig.exe) to ALWAYS use the Unicode glyphlist if the font supports it.  
This option defaults to enabled.

When this option is NOT enabled, Unicode will only be enabled for fonts which
contain at least 3,072 glyphs AND are not dedicated Chinese, Japanese, or
Korean fonts (which have their own special glyphlists).  Other Unicode-
compatible fonts will be assigned the Universal Glyph List (OS2UGL) instead, 
which supports about 1,100 characters.  (The OS2UGL is documented at 
<http://www.borgendale.com/glyphs.htm>, for those who are curious.)


Q19: Why would I care if a font uses Unicode?

A19: In an ideal world, you shouldn't... and in most cases you probably won't.
But there are some advantages and disadvantages which may affect you.
 - If a font uses the Unicode glyphlist, it CANNOT be used for DBCS "font
   association" (see Q21).  
 - Use of Unicode may involve a slight performance hit.  (I have received at
   least one report that it can cause a noticeable delay in populating WPS
   folders if the WPS font is a TrueType Unicode font; however, disabling
   the MBCS compatibility option (Q20) apparently eliminated this.)
 - ONLY fonts which use Unicode may be used to render Unicode-encoded text 
   (at least in applications which use native OS/2 functions).
 - If a font doesn't use Unicode, then FreeType/2 will use the best alternate
   encoding it can find that the font supports.  However, any characters in the
   font that are not supported by that particular encoding will not be 
   displayable under OS/2.  This may be a problem for fonts which contain 
   characters not defined in the Universal Glyph List, but with fewer than 
   3,072 glyphs in total (and which are not dedicated Chinese, Japanese, or 
   Korean fonts).


Q20: What does "report Unicode fonts as MBCS compatible" mean?

A20: The font metrics maintained by the OS/2 graphics interface (GPI) include
a flag which indicates whether the font is compatible with DBCS/MBCS codepages.
Unfortunately, it seems that OS/2 is a bit simple-minded in that it evidently
includes Unicode under the DBCS category.  If a Unicode font does not have this
flag set, many non-basic ASCII characters (mostly graphics characters) will
simply not display under any codepage.

If this option is enabled, then all Unicode fonts will have the MBCS flag set.
This mimics the behaviour of IBM's TRUETYPE.DLL, as well as FreeType/2 versions
prior to 1.20.  If this option is disabled, then Unicode fonts will only have 
the MBCS flag set if they contain at least 3,072 glyphs.  

So what's the point of disabling this option?  Well, if you use the DBCS font
association feature (see Q21), normally missing glyphs cannot be substituted 
into a Unicode font.  Disabling this option makes it work (for some reason).
This is probably only of interest to users of DBCS versions of OS/2 who may
want this enhanced substitution support.

NOTE: I have received some reports that disabling this option can also provide
a major boost to text rendering performance when Unicode fonts are used.

This setting is not applicable to non-Unicode fonts.  It defaults to enabled.


Q21: What is DBCS font association?

A21: It's a fairly obscure feature supported by OS/2 Presentation Manager.  It's
mostly used in DBCS versions of OS/2, although it happens to work under SBCS
systems as well.  Basically, if you have an entry in OS2.INI as follows:
  PM_SystemFonts->PM_AssociateFont = "Some Font Name;10"
where "Some Font Name" is a CJK (Chinese, Japanese, or Korean) font, then the 
"font association" feature will be enabled.  This has the following effect
(after rebooting): when using the appropriate codepage, and as long as "Some 
Font Name" isn't a Unicode font, then you can display text under Presentation 
Manager in that particular (Chinese, Japanese, or Korean) language WITHOUT 
having to specifically set the display font to one that supports that language.
When Presentation Manager encounters a CJK character which isn't supported by
the current display font, it will automatically load the equivalent glyph from
the "Some Font Name" font and substitute it into the displayed text.

This has a couple of limitations.  First, as mentioned under Q20, normally this
does not work when the font used for displaying the text is a Unicode font -- 
unless you disable the MBCS flag using the option described above (which has 
other side effects).  Second, you cannot use a Unicode font as the actual
substitution font either.

This second limitation poses a problem if you have FreeType/2 configured to
make ALL TrueType fonts Unicode if they support it (see Q18), especially since
that is the default behaviour.  Therefore, I've provided an additional setting:
"Use DBCS instead of Unicode for association font" (in ftconfig.exe).  When 
this setting is enabled (as it is by default), FreeType/2 will: detect the
currently-configured association font if there is one; determine which language
it is being used for; and force it to use the appropriate DBCS glyphlist for
that language INSTEAD of Unicode (regardless of the "Always use Unicode" 
setting).

Note: this option does technically make it possible for you to use a 
"pan-Unicode" font like "Times New Roman MT 30" or "Arial Unicode MS" as the 
association font.  Doing this is NOT RECOMMENDED: because Unicode encoding will
be disabled for that font, you will lose the ability to display any characters
in that font which the substituted DBCS glyphlist does not support.  (For 
instance, if you use "Arial Unicode MS" for Japanese font association, then 
you will not be able to use that font to display any characters that don't 
happen to exist in the Japanese character set.)  For this reason, you should
always use an association font which is specifically designed for the language
(Chinese, Japanese, or Korean) that you want to use.


Q22: What OS2.INI entries correspond to the various configuration settings?

A22: If you really want to know, they are listed below.  All of them go under 
the "FreeType/2" application in OS2.INI, and all of them are ASCII numbers:
  OpenFaces               - Number of fonts in the "open font" cache
  DPI                     - The interface resolution in dpi (72/96/120)
  Use_Netscape_Fix        - Activate the Netscape positioning workaround? (1/0)
  Use_Facename_Alias      - Enable the "TmsRmn" font alias feature? (1/0)
  Use_Fake_Bold           - Enable the simulated bold face feature? (1/0)
  Use_Unicode_Encoding    - Always use Unicode where possible? (1/0)
  Set_Unicode_MBCS        - Always set the MBCS flag for Unicode fonts? (1/0)
  Force_DBCS_Association  - Disable Unicode for the DBCS assoc. font? (1/0)
  Force_DBCS_Combined     - Disable Unicode for combined fonts? (1/0)


Q23: Why are WPS folders/container controls taking a long time to refresh?

A23: If you're using a TrueType font for WPS folders in detail view, or 
(possibly) other types of container controls as well, you may find that
OS/2 takes much longer to draw the contents than before.  I've had reports
that this may occur when the font is using the Unicode glyphlist AND is 
reported as MBCS capable.  

I don't really recommend using outline fonts for folder or dialog text, as
bitmap fonts are almost always both faster and crisper-looking, no matter what
font driver you use.  If you really want to do this, however, you may find
that turning off the option "Always report Unicode fonts as MBCS compatible"
provides a speed improvement.  Disabling the option to always use Unicode 
should also work.  Just remember that disabling these options has certain
implications (as discussed up above).



Q24: Are OpenType fonts supported?

A24: It depends. ;)

What you have to understand is that OpenType isn't really a font format by 
itself.  What's called an "OpenType font" is really just a standardized wrapper
around a TrueType or PostScript font (with some extra features called "layout
tables" which aren't relevant to us here).  

So basically, there are two types of OpenType font: OpenType/TT and OpenType/PS
(depending on whether the actual font contained inside is a TrueType or 
PostScript font).  

The Freetype v1 library (and thus FreeType/2, which is based on it) 
theoretically supports OpenType/TT fonts: it should simply see them as TrueType 
fonts.  

OpenType/PS fonts, on the other hand, are not supported at all.  This is 
because the FreeType v1 library is simply not designed to be able to handle
PostScript font data.

I hope to some day write a new version of FreeType/2 which is based on the 
FreeType v2 library; this would allow proper OpenType font support for both
types.  I've started preliminary work on it, but I can't give any time-frame 
for release, unfortunately.
