#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 and DJGPP. 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 (see the file liscence.txt for links) 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/
ALLETTF requires DJGPP and Allegro. The True Type font loading code comes from the Freetype Project.
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.
I think that the way Allegro for DJGPP is copyrighted is fantastic and so I'm going to copyright the source code that I wrote for ALLEGTTF in the same way.
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 DJGPP's and Allegro's copyright too, I guess.
Download
You can download
ALLEGTTF.
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 DJGPP and 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, FONT *font, char *string,
int x, int y, int colour)
void aatextout_center(BITMAP *bmp, FONT *font, char
*string, int x, int y, int colour)
It plots antialiased text on the screen just like Allegro's
textout function. It is a little slower than Allegro's textout
function, so this function 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. 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.
FONT* load_font2 (const char* filename, int* antialiased)
This function works just like load_font except that it
will change the antialiased variable to some non-zero number if the font
is an antialised font. If the variable antialiased < 0 when the
routine starts then the function will not try to automatically determine
if the font is antialiased or not which is a bit faster than loading a
font and trying to detect it automatically. This is done by looking
for aliased values on the S and s characters. It doesn't check every
pixel of character otherwise it takes too long to load for large non antialiased
fonts.
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 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.Eleveld@anest.azg.nl
deleveld@dds.nl