texFont Library Release 4 Documentation

glTexFont Library Documentation

By Nate Miller

Release 6

June 26, 1999

Inroduction

The glTexFont library is a set of functions that allow C/C++ programmers the ability to add text to their OpenGL applications. glTexFont is not meant to be a complex library, its main goal is simplicity. Keeping the library simpe gives the average user the chance to use it without a great amount of work.

Installing

Installing glTexFont is pretty simple. First extract gltexfontlib.zip to a temporary directory. Once you have done this copy glTexFont.h to your compilers "include" diretory. Then copy glTexFont.lib into your compilers "lib", or library directory. Once this is done you are ready to use glTexFont in your application.

Usage

Once you have glTexFont installed you are ready to use it. To use glTexFont in your projects the first thing you must do is link to the glTexFont library, glTexFont.lib. Once you have done this make sure that you #include <glTexFont.h>. Now you are ready to load the font. The other libraries which you should link too if you are creating a simple GLUT application are msvcrt.lib opengl32.lib, glu32.lib and glTexFont.lib.

Loading A Font

There are two different calls that load a font. The first call is fontLoad. The parameter to this function si the name of the font Targa file. After calling this function the font map that you specified will be loaded and you will be ready to draw text to the screen. If fontLoad is successfull it will return a value of 1, if not it will return one of the error codes listed below.

The second font loading call is fontLoadEx. This is an ADVANCED call and should not be used unless you have a good idea about what you are doing. This function takes the same parameters as fontLoad with the addition of a row and column parameter. The row parameter stands for the number of characters that will be in the image file per row and the col parameter stands for the number of characters that will be in the image file per column. If row and col were multiplied together they MUST equal 256 because the ASCII character set goes from 0 to 255.

Make sure that you call fontLoad AFTER OpenGL has been initialized and setup. If you call it before you wont see the correct font and all that will be displayed will be colored boxes where the font should show up. This is because glTexFont uploads the font map to texture memory when you load it and it also uses OpenGL to manage the texture id creation.

Errors

If there is an error when loading a font fontLoad and fontLoadEx will both return an error value which can be used to determine the souce of the problem. There are five different error codes that the font loading functions will return. Here are the error codes that are returned on failure:

FONT_FILE_NOT_FOUND -- Font image was not found.
FONT_BAD_IMAGE_TYPE -- The font image was a color mapped image or is compressed. Image must be uncompressed and not have a colormap.
FONT_BAD_DIMENSION -- Image dimension was not a power of 2.
FONT_BAD_BITS -- Image bit depth was not 8, 24 or 32.
FONT_BAD_DATA -- Image data could not be loaded.

Drawing A Simple String

glTexFont was designed to be as easy to use as printf, if you would like to output a float value its as easy as fontDrawString (0,0,"Some number %f", myNum); If you know how to use printf you will be perfectly comfortable with glTexFont. When you call any string drawing functions with glTexFont the string will be drawn into the current viewport. Below are some examples of simple strings:

fontDrawString (0, 0, "This is line has a \ttab in it");
fontDrawString (0, 0, "A line with a carrage return\nNew line!");
fontDrawString (0, 0, "This is a float number: %f", myFloat);

Setting The Font Size

To set the size of the font it takes one simple call to fontSize (int size) and the size of the text for the next font operation will be the number passed to fontSize. The default font size is 12.

Drawing A Shadow

If you would like to draw shadowed text make a call to fontShadow () before you draw your string and the next string that is drawn will be drawn with a shadow. Default font shadow is gray.

Font Gradient Coloring

If you would like to have gradient text, text which is shaded from the top to the bottom make a call too fontGradient. This will enable the gradient coloring. A call to fontGradientColor will set the ending color for the gradient. The color of the text will be the color specified with fontColor* on the top and the color specified with fontGradientColor* on the bottom.

Using Italics

Using italics is fairly simple. To start the italics you would use the \\i+ token, the i+ tells the library to start the italics. To stop italics the \\i- token would be used. As with the rest of the library the italics only last for one call to fontDrawString, after one call italics are turned off. Here are a few simple examples:

fontDrawString (0, 0, "\\i+All Italics!");
fontDrawString (0, 0, "\\i+This is italic, \\i-this is not and \\i+this is italic");

Using Bold

Using bold is fairly simple. To start the bold you would use the \\b+ token, thebi+ tells the library to start the bold. To stop bold the \\b- token would be used. As with the rest of the library the bold only lasts for one call to fontDrawString, after one call bold is turned off. Here are a few simple examples:

fontDrawString (0, 0, "\\b+All Bold!");
fontDrawString (0, 0, "\\b+This is bold, \\b-this is not and \\b+this is bold");

Coloring The Text

There are many different calls to set the current color of the font, the shadow or the gradient. Here they are listed in no particular order:

void fontColor (float r, float g, float b);
void fontColorA (float r, float g, float b, float a);
void fontColorp (float *clr);
void fontColorAp (float *clr);
void fontShadowColor (float r, float g, float b);
void fontShadowColorA (float r, float g, float b, float a);
void fontShadowColorp (float *clr);
void fontShadowColorAp (float *clr);
void fontGradientColor (float r, float g, float b);
void fontGradientColorA (float r, float g, float b, float a);
void fontGradientColorp (float *clr);
void fontGradientColorAp (float *clr);

So what do all these functions do?
fontColor* sets the color for the current string.
fontShadowColor* sets the color for the string shadow
fontGradientColor* sets the color for the gradient, this is the bottom color of the gradient, the top is the color specified with fontColor*

A note on the naming convention for these calls. If a functions name contains an ‘A’ at the end or near it that means that the call will set the color with an Alpha value. If there is no ‘A’ the color is assumed to be a regular RGB. If there is a ‘p’ at the end of the function name that means that the function expects an array of numbers to be passed to it rather than 3 or 4 numbers. All values that are passed to the functions are assumed to be float's in the range from 0.0 to 1.0.

Color Tokens

Color tokens are useful for giving each character in your string an individual color. Color tokens are used in the call fontDrawString as part of the string that will be drawn. There are two color tokens supported: \\c and \\a. If a \\c is encountered this is the syntax that should follow: \\c(r g b). What this does is sets all characters that follow the token to the RGB color that is defined by r, g, and b. If a \\a is encountered this is the syntax that should follow: \\a(r g b a). What this does is sets all characters that follow the token to the RGBA color that is defined by r, g, b and a. Again all of these numbers are integers. The range of these integers is from 0 to 255. A color token will color all characters that follow it until it either encounters another color token or the end of the string.

Font Regions

Font regions are useful when you would like to have a long string of text confined to a small area. To use a region you would call fontRegion. The first two parameters describe the upper left hand corner in window coordinates and the second two are the width and the height of the region. Here is some example code that would setup a text region:

fontRegion (10, 100, 12 * 12, 12 * 6);
fontDrawString (-1,-1, "Here is a simple text region! \\c(255 0 0)How nice!");

This region would be from the position (10, 120) with a width of 12 * 12 (12 characters at default font size) and a height of 12 * 6 (6 characters a default font size). The bottom of the text region would be described by (10, 100 – (12 * 6)). After the region is established the string is drawn into the region. As you can see fontDrawString is passed two negative numbers. Why? If a text region is established the position paramaters to fontDrawString are ignored, I did this for simplicity. The region only is present for one call to fontDrawString.

Closing Notes

PLEASE make sure that you look at the glTexFont example that I provide on my web page. This example can explain things better than I can because it is using the actual library. If you still have problems understanding how to use the library drop me a line and I will help you.

When the font size, color, shadow or region is set these are only set for one call to fontDrawString. Once a string has been drawn all values go back to their defaults.

If you would like to contribute code to the glTexFont distribution PLEASE email it to me with a description of what it does and I will merge it with the next release and give you credit for your work.

The glTexFont page is located at http://nate.scuzzy.net/gltexfont