Sub-Pixel Font Positioning on UNIX mini-HOWTO

(Last mod: Jun 9 2004 jm) (text version)

This mini-HOWTO document describes how to get sub-pixel font positioning working on your UNIX system, using Linux as an example platform. Sub-pixel font positioning is also known as "sub-pixel rendering", "sub-pixel decimation", or by Microsoft's term for its implementation of the technique, "Microsoft(r) ClearType(tm)". (ObTM: "ClearType" is a trademark of Microsoft Corporation.)

Steve Gibson has provided a good description and demo of how sub-pixel rendering works, and the history way back to the Apple II days, at his site. Also, John Platt at research.microsoft.com provides some papers and a brief overview of ClearType(tm).

I won't go into the details here, since they're better covered in depth there. Suffice to say that, if you're using a laptop or other LCD screen, then sub-pixel rendering will greatly improve your screen's readability, especially at small font sizes.

A lot of people have strong (and mostly justified) feelings about anti-aliasing; it blurs the text, making it harder to read at small-to-medium point sizes. However, on a laptop screen, sub-pixel rendering is a different kettle of fish. Take a look at the Mozilla window to right, and see what you think. (Hint: it'll probably look horrible on a CRT screen, but great on an LCD or TFT.)

Thanks to work by Keith Packard, XFree86 4 now includes Xft and Render, two extensions to the X display protocol which allow use of sub-pixel rendering. IMO, he's done a fantastic job at getting these implemented and into XFree86 4, and thereby into the major Linux distros. Thanks Keith!

First of all, you'll need to use an X server with support for Xft, the X FreeType interface library. As far as I can tell, any version of XFree86 4 since XFree86 4.0.2 will have this included. This means that at least these Linux distributions have it available:

• Red Hat Linux 7.1 and later (warning: 7.x also includes XFree86 3.3.6, which you do not want)

• Mandrake 8.1 (warning: also includes XFree86 3.3.6)

• SuSE Linux 7.x

• (TODO: please send me more specific distros)

If you're brave, you could try out the binary installer from xfree86.org . This will require quite a lot of knowledge about X, so it's not recommended. You're better off using your distribution's packaged version.

Once you get XFree86 4 installed and running as before, check to make sure that XFree86 supports the Render extension for your graphics card:

        xdpyinfo | grep -c -i render

If you get a '1', you can go on. Otherwise, you'll have to wait until XFree86 supports Render on your graphics card -- sorry :( Newer versions of XFree86 contain Render drivers for more video cards, so if you're not using the latest, try upgrading that.

Red Hat 6.x or 7.x users need to have the Freetype library installed. This is installed by default, but if you've done a custom install, you'll need to install the RPM from your CD-ROMs or the FTP site. Check to see if it's there using this command:

        rpm -qa | grep freetype

You should see at least freetype and freetype-utils listed in the output.

You really want the Microsoft TrueType fonts. They are high-quality screen-display fonts, and work nicely. Most other free fonts are, to be honest, just not as good-looking.

Update: not any more! Bigelow and Holmes have donated a range of fonts called Luxi (included in XFree86 4.2.0), and Bitstream are now donating another called Vera. Great news! If you're going to be happy with these very nice fonts, skip this step entirely.

Debian users should just:

        apt-get install anti-aliasing-howto

Other folks: the easiest way to install 'em is by downloading Keith Packard's tarfile, like so:

        cd ~
        wget http://keithp.com/~keithp/truetype.tar.gz

(and wait... it's about 3 megs ;)

        cd /usr/X11R6/lib/X11/fonts
        tar xvfz ~/truetype.tar.gz

and hey presto, you've got a /usr/X11R6/lib/X11/fonts/truetype directory.

Debian users: the anti-aliasing-howto deb you just installed covers this. Take a look.

Red Hat 8 or 9 users: this now seems to be covered. All that's left is turning on sub-pixel positioning, and (on RH8) switching to a version of Mozilla that'll use it. Both GNOME and KDE will use it out of the box.

Mandrake or Red Hat 7.x users: MandrakeUser has a great guide to this, so rather than reprinting chunks, I'll link to it. Read the 'Font Anti-Aliasing' section.

SuSE users: the SuSE support database provides a very helpful page.

OpenBSD users: covered in the OpenBSD FAQ.

GNOME 2 and all recent versions of KDE do it out-of-the-box. If your GNOME 2 install isn't doing it, and you're using garnome, there's a good troubleshooting page on the gnomesupport.org Wiki.

If you want to get GTK+ and GNOME 1 to use anti-aliasing, you need to install a package called 'gdkxft'. Nowadays I haven't felt the need to do this, since Red Hat 8/9 now boast AA text pretty much everywhere by default.

If you installed the fonts from Keith Packard's site in the last step, you'll need to add a line like this to your /etc/X11/XftConfig or /usr/X11R6/lib/X11/XftConfig file, right at the top:

        dir "/usr/X11R6/lib/X11/fonts/truetype"

This is the key bit.

Note that recent versions of XFree86 use a totally different file, with the new and improved fontconfig system. If you have a file called /etc/fonts/fonts.conf, skip to the next section. Otherwise, carry on this one.

First, check Steve Gibson's site again, and take a look at the diagrams about halfway down the page demonstrating whole-pixel graphics, whole-pixel antialiasing, R-G-B LCD Sub-Pixel Rendering, and B-G-R LCD Sub-Pixel Rendering.

Now, edit your /etc/X11/XftConfig file, and add a line at the end. Most LCD screens will look better with R-G-B LCD Sub-Pixel Rendering. If yours does, add these lines:

        match edit antialias = true;
        match edit rgba = rgb;

Otherwise, for the B-G-R case, add:

        match edit antialias = true;
        match edit rgba = bgr;

Save and quit the editor. Now start up gfontsel and select the verdana font, in font size medium and charset iso-8859-1, and you should see lovely, super-smooth sub-pixel-rendered text in the Preview window.

If your system is using fontconfig, you're in luck -- this is much cleaner and easier. Kudos to KeithP, yet again, for a nice job on this stuff.

First, figure out (using the link above) if you want to use R-G-B or B-G-R subpixel rendering.

Next, create a file in your home directory, called ~/.fonts.conf, and cut and paste this XML text in:

     <?xml version="1.0"?>
     <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
     <fontconfig>
       <match target="font">
         <edit name="rgba" mode="assign"><const>rgb</const></edit>
       </match>
     </fontconfig>

Change rgb to bgr if you need to use B-G-R subpixel rendering.

For system-wide use, add that text to /etc/fonts/local.conf (thanks Paul Kelly for the tip).

The change takes effect immediately, but you may want to log out so that everything on the desktop is updated.

Most GTK+, GNOME and KDE applications should have picked it up. Just pick a TrueType or URW font you like (such as Luxi or Verdana, perhaps), and tell them to use that. Hey presto ;)

Mozilla, however, is the big problem at the moment. It currently takes a shortcut around GTK+ to draw text, due to inefficiencies in GTK+ or X. As a result, it doesn't gain anti-aliased text when you install 'gdkxft' or GNOME 2. (Bugs: bug 100570, bug 109423)

Thankfully, there's a patch and prebuilt binaries which fix this, up at http://fontconfig.org/mozilla/ .

Update: Jan 25 2002 jm: Slashdot reports Xft Support For Mozilla: keithp and Chris Blizzard have hacked a patch which "uses a new version of the Xft library available at http://keithp.com . That will be integrated into the XFree86 CVS tree after 4.2 stablizes; the existing Xft library will remain in place for backwards compatibility." With CB's support, this should make it into the Moz mainline. Good news.

Update: Apr 22 2003 jm: RH9 now includes an anti-aliased build of Mozilla by default. It's very, very nice.

David Chester has written a very nice set of modifications to Xft which improve the font display quality greatly, as far as I can see, by applying some new hinting algorithms.

Also Anders Kaseorg has come up with a patch which improves subpixel filtering in Xft 'especially for autohinted fonts'.

If you're not averse to some compilation, take a look.

If your TrueType fonts are not appearing, it may be because your UNIX does not automatically rebuild the font cache files. Here's how to do this:

cd /usr/X11R6/lib/X11/fonts/truetype
ttmkfdir -o fonts.scale
mkfontdir -e /usr/X11R6/lib/X11/fonts/encodings

(Note that /usr/X11R6/lib/X11/fonts/truetype is the directory where the TrueType fonts are kept. The XFree86 convention is /usr/X11R6/lib/X11/fonts/truetype, but Red Hat 7.2 also uses /usr/share/fonts/default/TrueType and Mandrake also uses /usr/X11R6/lib/X11/fonts/drakfont.)

If you're not using the most recent version of XFree86, it's definitely work upgrading; more and more hardware is gaining Render support with each release.

You can always test anti-aliasing with TrueType fonts using this command:

        xterm -fa 'Andale Mono'

Kevin Pfeiffer notes: 'I just upgraded to SuSE 8.2 with KDE 3.1.1 and wasn't very happy with the sub-pixel rendering -- too much color fringing for my taste. However boosting the gamma setting from 1.0 to 1.30 or so as help tremendously.'

If you're a tweaker, another thing to do is to run through the /etc/X11/XftConfig file. It seems that each directory listed in a dir statement will be searched for an XftCache file when Xft is first used; so currently, every application that uses anti-aliasing and/or sub-pixel positioning will apparently open about 6 files at startup. You don't need this slowdown.

To get around it, edit /etc/X11/XftConfig and look for lines like:

        dir "/usr/X11R6/lib/X11/fonts/truetype"

Check to see if the directory exists and contains files that end in either .pfa or .ttf -- if it doesn't contain any such files, delete the line from the XftConfig, you don't need it.

If you're a real tweaker, Jason Byrne reckons compiling X on your own machine will give you some good performance. It'll certainly improve your knowledge of its installation ;)

Xft also supports system-wide font aliasing -- which is very handy for getting recalcitrant or non-tweakable apps to use the font you want ;). For example, I have these lines at the end of my /etc/X11/XftConfig file, to alias a variety of common fonts to anti-aliased versions from the URW foundry:

        match any family == "Palatino" edit family += "URW Palladio L";
        match any family == "Bookman" edit family += "URW Bookman L";
        match any family == "Courier" edit family += "Nimbus Mono L";
        match any family == "Helvetica" edit family += "Nimbus Sans L";
        match any family == "New Century Schoolbook" edit family += "Century Schoolbook L";
        match any family == "Times" edit family += "Nimbus Roman No9 L";

That's all so far!

Changes and suggestions for this mini-HOWTO should be sent to me, Justin Mason, at <jm-subpixel-howto /at/ jmason /dot/ org>. In particular, distro-specific gotchas would be welcome!

For more interesting XFree86 (and general Linux) tips, Jason Byrne maintains a page here.