ALLEGTTF
Anti-aliased text output and font loading routines for Allegro
Version 2.0
By Doug Eleveld
D.J.Eleveld@anest.azg.nl
deleveld@dds.nl
TTF font loading code from the Freetype Project.
(see /source/freetype/licence.txt)

#include <std.disclaimer.h>
"I do not accept responsibility for any effects, adverse or otherwise, that this code may have on you, your computer, your sanity, your dog, and anything else that you can think of. Use it at your own risk."

What is ALLEGTTF
ALLEGTTF is a collection of functions to produce anti-aliased text output and TTF (True Type Font) loader, a GRX font loader and a bitmap font loader for use with Allegro. Antialiased text means that fonts have 'soft' edges and blend into their backgrounds smoothly. Antialiased fonts are useful because the look a lot better than non-antialiased fonts, expecially at low resolutions.

One day I saw some code that Domenic Cooney had put on his web page to draw antialiased text. He used transparant pixels to draw the antialiasing and I really liked what I saw. I took his code and made some optimizations and re-wrote a lot of it. Now it's a quite a bit faster in most graphic modes, especially when drawing a filled background (i.e. Allegro's text_mode >= 0). It's quite a bit bigger too because there are now more than a few pretty well optimized routnes, which are called depending on the graphic mode colour depth and the text_mode.

I also found the Freetype Project on the net which is simple ansi C code for loading True Type Font files into memory. I simply added some routines to get Freetype and Allegro working well together. I DID NOT write any of the files in the /source/freetype directory. These files came from the Freetype Project.

ALLEGTTF draws text in 8 bit graphic modes with 6 different antialiasing levels. This is also true when Allegro's text_mode is >=0 in any graphic mode. When in a 15,16,24 or 32 bit graphic mode and with text_mode is <0, then the text is drawn with 255 levels of antialiasing.

ALLEGTTF is not very useful without Allegro since it relies on many of Allegro's procedures. The latest version of Allegro can always be found on ftp://x2ftp.oulu.fi, in /pub/msdos/programmer/djgpp2/, and on the Allegro homepage, http://www.talula.demon.co.uk/allegro/.

The latest version of ALLEGTTF is always available at: http://huizen.dds.nl/~deleveld/index.htm It might or might not also be available at ftp://x2ftp.oulu.fi, in /pub/msdos/programmer/djgpp2/

Copyright
ALLEGTTF consists of two parts. One in the code that I wrote for fast text antialiasing (partially taken from Allegro source) and the other part is the Freetype Project which is used for loading TTF fonts. Both sets of code have different restrictions. Any use of ALLEGTTF must meet both requirements.

For information on the restrictions on the Freetype project code, see the file /source/freetype.licence.txt. Basically it says that you cannot pretend that you wrote this software yourself and must give links to the Freetype Project homepage. See the file /source/freetype/licence.txt for the complete formal restrictions.

The source code that I wrote for ALLEGTTF is swap-ware. You may use, modify, redistribute, and generally hack it about in any way you like, but if you do you must send me something in exchange. This could be a complimentary copy of a game, an addition or improvement to ALLEGTTF, a bug report, some money (this is particularly encouraged if you use ALLEGTTF in a commercial product), or just a copy of your autoexec.bat if you don't have anything better. If you redistribute parts of ALLEGTTF or make a game using it, it would be nice if you mentioned me somewhere in the credits, but if you just want to pinch a few routines that is OK too. I'll trust you not to rip me off.

Since this whole library was inspired by the work of Domenic Cooney, I guess that the above copyright also applies to him. So if you send me anything, send it to Domenic also.

Of course you must also read Allegro's copyright too, I guess.

Download
You can download ALLEGTTF 2.0 for DOS/Windows or ALLEGTTF 2.0 for Linux. These are versions for the Allegro WIPs later than 3.9.36.
Older WIPS can use ALLEGTTF 1.9.
If you are using Allegro 3.12, then you can use ALLEGTTF 1.6.

Using ALLEGTTF
You have to make your own antialiased fonts this is possible in two ways.

1) Use the TTF2PCX program in the examples directory.

2) Use the TTF2PCX program which is available from the Allegro homepage. Be sure to use the maximim allowed antialiasing levels. (0-254, I think)

Since ALLEGTTF is only useful with Allegro, I will assume that you know something about compiling, linking, object files, library files etc.

The best way to use ALLEGTTF is to use libalttf.a as a library and use it during your linking process. You can the load TTF fonts, and draw them to the screen and BITMAP structures.

If you want maximum speed, make sure that you make an RGB table with Allegro so that ALLEGTTF and use fast table lookup in 8 bit modes instead of having to search the palette to find the proper antialiasing colours. The Allegro docs show how to do this, or you can look at the ALLEGTTF examples which do this also.

Initialization functions
`void antialias_init(PALETTE pal)`
This function should be called before using any of the functions in the ALLEGTTF library, however you could skip it and have the first call to the text drawing function initialise itself. Pass it the palette to use when in 8 bit colour depth, otherwise NULL. Passing a NULL when using 8 bit color mode will make the palette be calculated only when it's needed. It is only needed in 8 bit video modes when plotting text with an empty background. In 15,16,24,or 32 bit modes I suggest passing NULL.

`void antialias_palette(PALETTE pal)`
Pass it the palette to use when in 8 bit colour depth. Passing a NULL will free any internal colormaps and the colormaps will only be recalculated only when it's needed. It is only needed in 8 bit video modes when plotting text with an empty background.

`void antialias_exit(void)`
This function cleans up after the antialiased functions, releasing any internal memory that was used. You don't really have to call this function because it will be done automatically at program exit.

Text output functions
For Allegro versions higher that 3.0 + WIP, the user can create a FONT using ALLEGTTF and then call the normal Allegro textout functions and the text will be properly drawn antialised. There is no need for specialized text drawing functions. However you can call the antialiased text output functions directly. They are:

`void aatextout(BITMAP *bmp, const FONT *font, const char *string, int x, int y, int colour)`
`void aatextout_center(BITMAP *bmp, const FONT *font, const char *string, int x, int y, int colour)`
`void aatextout_right(BITMAP *bmp, const FONT *font, const char *string, int x, int y, int colour)`
`void aatextprintf(BITMAP *bmp, const FONT *f, int x, int y, int color, const char *format, ...)`
`void aatextprintf_center(BITMAP *bmp, const FONT *f, int x, int y, int color, const char *format, ...)`
`void aatextprintf_right(BITMAP *bmp, const FONT *f, int x, int y, int color, const char *format, ...)`
The function `aatextout` plots antialiased text on the screen just like Allegro's `textout` function. It is a little slower than the Allegro version, so it should only be used with smoothed fonts. To check out how much slower the antialiased text output is on your machine, run the profile program in the examples directory. Normally the antialiased text drawing is 2 to 8 times slower that Allegro's normal textout. You can use the profile program in the eaxmples directory to find out exactly how fast the text drawing is you computer.

Bitmap font loading functions
`FONT* load_font (const char* filename)`
This function loads an Allegro FONT structure from a file and return a pointer to it. Note that the color conversion mode must be set to COLORCONV_NONE. Don't forget to call the Allegro procedure destroy_font(FONT*) in order to release the memory associated with the font. The code for this function comes almost completely from Allegro's grabber utility. It is also in a seperate object file in the libalttf.a library so unless you use this function, it won't be included in your final executable.

True Type font loading functions
`FONT* load_ttf_font (const char* filename, const int points, const int smooth)`
This function loads a True Type font (*.TTF) as an Allegro FONT struct. The points variable tells how large the loaded font should be. The smooth tells what kind of font smoothing should be used when loading. See the Font Smoothing Defines section for details.

`FONT* load_ttf_font_ex (const char* filename, const int points_w, const int points_h, const int smooth)`
This function loads a True Type font (*.TTF) as an Allegro FONT struct. The points_w and points_h tell how wide and how tall the font should be loaded. This allows you to load very tall or very wide fonts. Loading Unicode values can be helpful for loading fonts that contain mostly graphic characters. The smooth tells what kind of font smoothing should be used when loading. See the Font Smoothing Defines section for details.

`FONT* load_ttf_font_ex2 (const char* filename, const int points_w, const int points_h, const int begin, const int end, const int smooth)`
This function loads a True Type font (*.TTF) as an Allegro FONT struct. The points_w and points_h tell how wide and how tall the font should be loaded. This allows you to load very tall or very wide fonts. The begin and end variables determine which characters are put into the font. This function might or might not also support the Unicode character sets, but as I know almost nothing about Unicode, so I couldn't tell you. If you want a normal Allegro font, use 32 and 128 for these values. The smooth tells what kind of font smoothing should be used when loading. See the Font Smoothing Defines section for details.

`FONT* load_ttf_font_mem (const char* filename, const int points, const int smooth)`
`FONT* load_ttf_font_ex_mem (const char* filename, const int points_w, const int points_h, const int smooth)`
`FONT* load_ttf_font_ex2_mem (const char* filename, const int points_w, const int points_h, const int begin, const int end, const int smooth)`
These functions are just like the above functions except they convert the TTF font to the Allegro format via a system call to TTF2PCX.EXE. This saves you from having the Freetype code in memory, so your executables are about 50K smaller. The disadvantage is that it does require TTF2PCX.EXE to be in the path.

Font smoothing defines
These defines are used but the TTF loading functions to determine what kind of font smoothing will be done on the loaded TTF font.

ALLEGTTF_NOSMOOTH
Loads the font with no font smoothing
ALLEGTTF_TTFSMOOTH
Loads the font with font smoothing done by the TTF font loading code. This can look a little wierd for small font sizes.
ALLEGTTF_REALSMOOTH
Loads the font with real font smoothing done by the ALLEGTTF library. This looks OK at small font sizes, but can take a long time to load for large fonts.

Bugs
The aatextout and the aatextout_center functions will not handle properly individual characters larger that 128x128 pixels, as this is the size of the internal scratchpad for aliasing the characters. It would be easy to change the source to accept larger characters at the expense of a little more memory and (possibly) slower output. If you are drawing characters as big as that you probably don't have to antialias them since they should be smooth enough already.

I know almost nothing about unicode so I can't really promise that unicode characters will be handled properly.

Future Work
Do you have any suggestions about what to add to ALLEGTTF? Just e-mail me.

In Conclusion
Why is ALLEGTTF free? Why are the sources freely available? Because I want ALLEGTTF to be the best anti-aliased text library that there is. When you release your source code and give away your program for free people will use your program and look at your source code. When they find bugs and mistakes they'll tell you and sometimes even fix the bugs themselves. They couldn't do that without your source. The end result is that everybodys software gets better and better.

Thanks
I would like to thank a number of people for making ALLEGTTF possible:

- D. J. Delorie and all the people connected with DJGPP for making such a powerful tool available for DOS users. It runs in 32 bit protected mode, has got tons of virtual memory and mind boggling optimization. It's amazingly powerful and yet free.
- Robert Hohne and everyone connected with the extremely useful RHIDE, an IDE for DJGPP that has the look and feel of the Borland C++ 3.1 IDE. One of the best IDE's I have ever used, and yet free.
- Shawn Hargreaves and everyone connected with Allegro, the amazing graphics, sound and hardware programming library for DJGPP. Fast, complete, easy to use, and yet free.
- The Freetype Project for producing freely available True Type font loading code.
- Domenic Cooney for producing the original code and the great idea of producing the antialiasing by plotting pixels of different transparancies.
- Tom Burgess for letting me freely use his pentium timer macros for the text output profiler.
- Dan Bogdanov for helping port ALLEGTTF for Linux and Windows.
- Eric Botcazou for patching 1.9 to work with the Allegro WIPs.
- Everyone who sent in bug reports and especially those who also submitted code fixes.
- Everyone at comp.os.msdos.djgpp for being patient and helpful. It's too bad that the other newsgroups aren't useful and as friendly as this one.

Doug Eleveld
Herepoortenmolendrift 14
9711 DG, Groningen
The Netherlands

D.J.Eleveld@anest.azg.nl
deleveld@dds.nl

Back to Doug's homepage