Fontrast Manual

Fontrast
Copyright 2006 C Bayliss

Contents


Introduction

Fontrast is a tool designed to create high quality textures from Windows TrueType fonts. These textures can be incorporated into your own Direct3D or OpenGL applications, to produce beautifully rendered, smooth-looking text.

For each generated font, Fontrast produces one or more texture pages (in BMP, JPG, TGA, PNG or RAW format), along with a "coordinates file" which lists the positions and dimensions of each character within the texture pages.

Requirements

Using Fontrast

Click the image below to jump to the relevant part of the manual:

Screenshot

Font

This is where you select the typeface and size of the font you wish to create.

Font section
Select font Choose the Windows font you wish to render, from those currently installed on your system. You can also assign bold and/or italic attributes here. If you choose a point size, the Height (pixels) value will be adjusted to the closest approximation to the chosen point size.
Height (pixels) Choose the height of the font, in pixels. This overrides any point-size choice made in the font selection dialog.
Average width: default Uses the default character width for the specified height. Use this option if you want your font to have the same proportions as it does under Windows.
Average width: user-defined Allows you to specify the average character width (in pixels). Using this option you can create fonts with varying proportions (eg. Wider or narrower than the default). Note that this is the average width, so you may need to experiment with the value a little to obtain the desired result.

Character set

Here you define your character set - the group of letters, numbers and symbols which will appear in your font texture.

Character set section
A-Z Include uppercase letters A-Z in the font.
a-z Include lowercase letters a-z in the font.
0-9 Include digits 0-9 in the font.
Symbols Include common symbols in the font.
Null char Include the null character (ASCII code zero) in the font.
From file If you require accented characters or unusual symbols not covered by the presets, simply create a text file (either ASCII or Unicode) containing the characters you need, check the "From file" box and supply the location of your text file. Note that duplicates are automatically removed, so if you have a large amount of text which needs to be rendered, you can just supply all your source text and Fontrast will create a font containing all the relevant characters.

Note: When running on Windows 98 or Me, Fontrast supports only ASCII input files. On Windows 2000, XP or later, both ASCII and Unicode are fully supported.

Colour

Colour section
Font Defines the colour of your font.
Background Defines the background colour of your font textures. Ignored if Flood colour is selected.
Border Defines the border colour. If the checkbox is checked, a visible border will be drawn using this colour, around each character on your texture page(s). This is mainly used if you need to do some manual post-processing on the texture page, and need to see where the character boundaries lie.

Output options

Output options section
Page size Defines the size of each texture page, in pixels horizontally and vertically. For maximum compatibility with rendering hardware, choose a square texture with power-of-2 dimensions (eg. 256x256, 512x512). Multiple texture pages will be created if the entire font is unable to fit on a single page.
Border Defines the width (horizontally and vertically) of the border around each character. Generally a 1-pixel border is recommended. Selecting zero may cause rendering problems where adjacent characters are too close together.
Supersample Defines the level of super-sampling applied to the texture.
  • None - No supersampling, each pixel is either on or off. This may be appropriate for certain typefaces or very small fonts.
  • 2x2 - Each output pixel is sampled 4 times, (slight anti-aliasing)
  • 4x4 - Each output pixel is sampled 16 times (moderate anti-aliasing)
  • 8x8 - Each output pixel is samples 64 times (high level of anti-aliasing)
Flood colour When using the alpha channel to define the shape of your font, best results are obtained by setting the colour channel to a single colour (the Font colour). This prevents any unwanted halos or fringes around the text. Always use an alpha-capable texture format with this option (TGA or PNG).
Snap alpha When supersampling is enabled (2x2 or greater), this option forces the transparency values in the alpha channel to be 0 or 1 (ie. No semi-transparency). Any pixel which contains the background colour will be fully transparent, all others will be fully opaque. Generally this option should be unchecked, but may be useful in some situations.
Antialias towards... This option allows you to choose which colour a super-sampled font should be anti-aliased towards. In most cases this will be the background colour. Note that this option has no effect if Flood colour is checked.
Minimum cell width Defines the minimum allowable width (in pixels) of any character in the font. Usually this can be left at zero. Any characters narrower than this width are padded out horizontally. This option could be used to create a monospaced font from a proportional one.
Page format & options This is where you select the format of your font textures. Currently supported are BMP, JPEG, PNG, RAW and TGA. Note that only PNG and TGA support alpha channels. The Options button allows you to select format-specific options, such as bit-depth and compression levels where applicable.
Coords format Here you select the format of your coordinate files. Each format stores the same information; only the representation changes. Currently supported are ASCII, Unicode and Binary. These formats are described in detail in the File formats section below.
Output path Defines the location in which the font textures and coordinate files will be stored.
Base filename This is the base filename of your output files. The texture and coordinate files are prefixed by this name. Since this is a prefix rather than a full filename, you should not include any filename extension here. For example, specifying a base filename of "MyFont" might create textures named "MyFont000.tga" through "MyFont003.tga", and a coordinates file named "MyFont.txt"

Export / Import buttons

The configuration of Fontrast can be saved and restored at any point. It can be useful to save a copy of the Fontrast configuration when you create a font, as this makes it very easy to tweak a font at a later date without having to remember what settings you used originally.

Export settings Save the current configuration of Fontrast to a location of your choice.
Import settings Load a previously saved Fontrast configuration file. The current settings will be lost.

About button

Displays information about Fontrast. This is also where you enter your license code.


Start button

Creates a coordinates file and one or more texture pages, based on the current settings. The creation process may be almost instantaneous or take a few seconds to complete, depending on your PC specification and the level of super-sampling in use.

Tutorial: Creating a font

This brief tutorial will guide you through the steps required to create a font texture and coordinate file.

Step 1: Select a typeface and size

In the Font section of the dialog, Click the Select font... button, and the standard font selector dialog will appear. Choose the desired typeface and style (bold, italic, etc) and click OK. The font size is unimportant at this stage.

Normally when using fonts with Windows, the size of a font is specified in "points". In this case however, we're more interested in pixel sizes. Enter a suitable size (in pixels) in the Height (pixels) box.

Step 2: Build a character set

You now need to define a set of characters which should appear in the generated font.

For a real-world application, you may need extra symbols or accented characters in order to support multiple languages. See Character set for more details.

Step 3: Choose some colours

Define the foreground and background colour of your texture pages by clicking the Font and Background buttons in the Colour section of the dialog.

Step 4: Set texture page dimensions and border width

In the Output options section, enter the required dimensions of your texture page(s) in Page Size. For maximum compatibility with 3D acceleration hardware, you should create square textures with power-of-2 dimensions. If the character set contains more characters than will fit on a single texture page, Fontrast will generate as many pages as required.

The Border width defines how many blank pixels will be placed horizontally and vertically between adjacent characters on the texture page. Usually 1x1 is ideal.

Step 5: Supersampling options

Supersampling controls the quality of anti-aliasing applied to the font. Higher levels of supersampling result in smoother-looking fonts.

When you need to create textures with an alpha channel, it is often useful to flood the colour channels with the foreground colour and store the font information purely in the alpha channel. This helps to avoid "halo" artifacts around the font when rendering. In this example however, we'll leave Flood colour turned off, so that we can view the resulting texture more easily in a regular image viewer, rather than having to resort to a more sophisticated editor which can display alpha channels.

Step 6: Set up the output files

Normally the choice of image format is dictated by the application which will eventually need to load the images, but in this case it's less important. For good quality and small file size, choose PNG. Click the Options button and select:

As with image format, the target application usually dictates the coordinates format, but in this example, select ASCII (TXT), as this will allow you to view the file in a text editor and see what's going on.

Step 7: Go!

Summary

Using the settings as described in steps 1 to 7 above, the directory you specified as the Output path should now contain two files: MyFont000.tga and MyFont.txt. (If you chose the binary coordinates format, you'll have MyFont.tab instead of MyFont.txt).

If you load MyFont.txt into a text editor and refer to the coordinate file formats information below, you should be able to see quite easily how the characters are arranged on the texture page(s).


File formats

Texture pages

Fontrast can create texture pages in the following formats:

Of these formats, PNG and TGA are the most useful, as they both support alpha channels and optional lossless compression.

With the exception of RAW, every format has an options dialog which allows you to choose bit-depth, compression levels and other format-specific flags. When creating a font with an alpha channel, be sure to select 32-bit mode.

Coordinate files

Whenever you create a font texture with Fontrast, a coordinate file is also produced. This file contains some common information about the font, and a list of coordinates for each character stored in the font, enabling other applications to find the location and size of each character on the texture page(s).

Fontrast supports 3 coordinate file formats. Each contains the same information, only the representation changes.

The first part of the coordinate file contains the following information about the font:

ID A fixed string "FONTRAST", used to identify the file
VersionNumber The file version number. The current version of Fontrast sets this to 1.
NumChars The number of characters stored in the font.
NumPages The number of texture pages used to store the font. This will be at least 1.
MinCode The lowest-numbered character code represented by the font
MaxCode The highest-numbered character code represented by the font. Note that NumChars is not necessarily the same as ((MaxCode - MinCode) + 1), as the characters within the range may not be contiguous.
CellHeight The value of Height (pixels) when the font was generated.

The second part of a coordinate file contains the location and dimensions of each character stored in the font:

Coordinates diagram
Code The Unicode representation of the character. If you're dealing only with ASCII characters, you can just treat this as an ASCII code.
PageNumber Zero-based index of the texture page containing this character. If your entire font fits on a single page, this value will always be zero.
PositionX
PositionY
The location of the top-left corner of the character within the texture page. (0,0) represents the top-left corner of the texture page.
Width
Height
The width and height of the character cell on the texture page
LeadingXOffset LeadingXOffset refers to the number of pixels by which the character should overlap the preceeding character (eg. In the word "My" using an italicised font, the tail of the letter "y" may extend leftwards a few pixels into the space occupied by the "M").
TrailingXOffset TrailingXOffset refers to the number of pixels between LeadingXOffset and the left edge of the next character to be rendered.

The pseudo-code below describes how to deal with X-coordinates when rendering using Fontrast-generated fonts.


   posX = (initial X coordinate)
   posY = (initial Y coordinate)
   for (each character to be rendered)
   {
      renderLetterAtCoordinates(posX - leadingXOffset, posY)
      posX = posX + trailingXOffset
   }
      

ASCII / Unicode format

Each line in the file ends with a carriage return. Where more than one value is stored on a single line, the values are separated by a single tab character.

Line 1 contains the ID ("FONTRAST"), used to identify the purpose of the file
Line 2 contains VersionNumber. Currently this is always "1".
Line 3 contains 5 integer values: NumChars, NumPages, MinCode, MaxCode and CellHeight
Line 4+ Each of the following lines corresponds to a single character in the font. These lines contain 8 integers each: Code, PageNum, X, Y, Width, Height, LeadingXOffset, TrailingXOffset
Example:
FONTRAST
1
6  1  32 52 48
32 0  0  0  0  0  0  10
48 0  1  0  22 48 0  21
49 0  24 0  20 48 0  20
50 0  45 0  21 48 0  21
51 0  67 0  21 48 0  21
52 0  89 0  23 48 0  21
      

The font described in the example above contains 6 characters on a single texture page, with character codes ranging between 32 and 52 inclusive and a cell height of 48 pixels.

Note that character 32 is a "space" - it doesn't occupy any area on the texture page, but is always included in the coordinates file so that your application knows how much space to leave between adjacent words when rendering text.


Binary format

Binary coordinate files are created as follows:

Byte offset Length (bytes) Description
0 8 ID "FONTRAST" - File identifier string
8 2 VersionNumber. Currently always 1.
10 2 NumChars
12 2 NumPages
14 2 MinCode
16 2 MaxCode
18 2 CellHeight
Beginning at byte offset 20, the following 16 byte block is then repeated (NumChars) times:
+0 2 Code
+2 2 PageNum
+4 2 PositionX
+6 2 PositionY
+8 2 Width
+10 2 Height
+12 2 LeadingXOffset
+14 2 TrailingXOffset

NB. All 2-byte values are stored unsigned in little endian (Intel) byte order.

Command-line parameters and batch processing

Fontrast can be run in a non-interactive mode, to generate textures and coordinates in configurations you have previously saved as .FRS files. To run Fontrast from the command-line, use fontrast-console.exe, found in the Fontrast installation folder (by default, c:\Program Files\Fontrast)

Command-line parameters
fontrast-console.exe <filename.frs> [options]
Where filename.frs is the full path to a previously saved .FRS configuration file
Options:
  -a         Auto-generate textures and coordinates, then exit. This option launches Fontrast in non-interactive mode.
  -o <path>  Override the output path stored in the .FRS configuration file
  -c <path>  Override the path to the character set file stored in the .FRS configuration file
Example usage
fontrast-console.exe "c:\some\folder\myfont.frs" -a -o "c:\output\folder\" -c "c:\charset\source\"

This example will generate textures and coordinates according to the configuration stored in the file c:\some\folder\myfont.frs. The output textures and coordinates file will be stored in the folder c:\output\folder\, regardless of the output path specified by the .FRS file.

Similarly, if the .FRS file specifies a character set file, for example d:\fontrast_projects\japanese.txt, the -c option overrides this path, so that Fontrast will look for the file c:\charset\source\japanese.txt.

The -o and -c options are provided to make it easier to integrate Fontrast into your asset generation process. You may find these options useful if you want to run Fontrast as a batch process on different PCs with varying directory structures, without having to modify the paths within the .FRS files for each PC.

Troubleshooting / FAQ

1. Why do some values on the main dialog highlight in yellow while I'm altering other settings?

Highlight example

2. When I display a super-sampled font, a faint halo is visible around some letters. How do I fix this?

3. Can I force the characters to be arranged in a regular grid pattern on the texture pages, instead of being variably spaced?

4. I need each character in the font to be stored on its own separate texture page. How can I do this?

5. When rendering my font, all I see are rectangular blocks. What's going on?

6. How do I support BMP/JPG/PNG/RAW/TGA format in my own programs?

For a more up-to-date list of questions and answers, please check the Fontrast website. If your question is not answered there, please let us know via the contact details on the website.

Legal notes and Credits

By using this software, you agree to the terms of the Licensing Agreement set out in the file license.txt, which can be found in the directory where this software is installed.

Please respect the copyright of TrueType font creators and publishers. Using a font texture created with Fontrast may have the same legal implications as using the original TrueType font in a document. You must possess a license for any commercial fonts you use, and abide by the licensing terms set out by the publisher.

Fontrast is Copyright 2003 C Bayliss, All Rights Reserved.
Website: http://www.hexforge.com/

Fontrast makes use of libpng and code written by the Independent JPEG Group.

Valid HTML 4.01! Valid CSS!

Last updated: 13th September 2003

Font Character set Colour Output options Export / Import About button Start button