Documentation
[SDK Documentation] [CGapiBitmapFont]

 

GapiDraw Classes CGapiSurface CGapiRGBASurface CGapiDraw CGapiDisplay CGapiMaskSurface CGapiBitmapFont CGapiCursor CGapiApplication CGapiInput CGapiVFS CGapiTimer CGapiGradient

CGapiBitmapFont

Overview

CGapiBitmapFont is a bitmapped font class for drawing text to surfaces.

Rectangles

All RECT structures are defined so that the right and bottom members are exclusive: right minus left equals the width of the rectangle, not one less than the width. This is to enable full compability with the DirectDraw coordinate system.

This document has been updated for use with GapiDraw 4.0 or later.
Last updated on October 5, 2008.

 

CGapiBitmapFont::CreateFont

This method initializes the font.

HRESULT CreateFont(
const TCHAR* pString, COLORREF dwColorKey,
DWORD dwFlags, GDFONTFX* pGDFontFx);
Parameters
pString
Pointer to a string containing the ASCII values of your font in the order that they appear. If set to NULL, GapiDraw will use the default string: TEXT(" !\"#$%&'()*+,-./0123456789:;<=>?@ ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~_"). Please note that the string shown here uses "\" escape codes. If pString contains more characters than the bitmap font, only those defined in the bitmap font will be used. If the bitmap font contains more characters than pString, only those defined in pString will be used.
dwColorKey
The color used to represent transparent pixels in your font surface.
dwFlags
The following table shows the possible flags.
Type Description

GDCREATEFONT_TRACKING

Uses the tracking value in pGDFontFx->lTracking to specify the default spacing between characters.

GDCREATEFONT_SIMPLEBITMAP

Use a simple bitmap format to create the font (see notes below)

pGDFontFx
Pointer to a GDFONTFX structure.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDBITMAP
GDERR_NOTINITIALIZED
GDERR_OUTOFMEMORY
GDERR_SURFACELOST

Remarks

GapiDraw supports two font formats: an advanced format with kerning tables and a simple format with no fixed kerning. No matter what format you choose from, the steps involved to create a font are always:

  1. Create a CGapiBitmapFont object.
  2. Call CGapiBitmapFont::CreateSurface and supply a valid font bitmap.
  3. Call CGapiBitmapFont::CreateFont to calculate the font offsets and widths.
  4. Draw some text with the font using CGapiSurface::DrawText.

THE ADVANCED FONT FORMAT

The advanced font format supports individual character kerning and can be useful to create extremely good looking bitmapped fonts. The advanced font format is illustrated in the picture below:


The first letters from one of the advanced bitmap fonts shipped with GapiDraw.

Each character will always be drawn as it is presented in the bitmap. The white kerning lines above each character adjusts the distance between the character and the surrounding characters in a sentence. If the white kerning line is one pixel short to the left of the character, the character will always be closer to the character to the left. You can use this to create individual character kerning such as those used by the TrueType fonts. Italic fonts are also possible to create using this font format.

The easiest way to create new fonts using the advanced font format is to use the FontMaker application which is delivered with each GapiDraw installation.

THE SIMPLE FONT FORMAT

The simple font format comprises plain bitmap letters arranged in the standard ASCII format. Create a new image in Photoshop and just type in the letters as in one of the sample fonts. Make sure that the quotation marks: " do not have a space between them since this will cause GapiDraw to treat them as two characters. The number of pixels before the first letter in the font bitmap defines the width of the <space> character (" "). An example of a simple font bitmap is seen below:


The first letters from one of the simple bitmap fonts shipped with GapiDraw.

CREATING NEW FONTS

To create a new bitmap font, the easiest way is to either create a font using the simple font format, or to use the supplied FontMaker by MetalShard, inc. No matter what method you choose, the time involved to create a new fonts is usually just a matter of minutes.

Some caveats to watch out for:

  1. If you use the advanced font format, please make sure that there is at least one masked pixel after the last width indicator. For example:


    The above will work
     

    The above will not work
     
  2. Make sure that the first quotation marks: " do not contain a space between them if you use the simple font format. If you use the advanced font format, make sure that none of the dots in the quotation mark begins outside the white kerning line.
  3. Make sure that there are no "free hanging" pixel elements that do not have a corresponding kerning lines above them. Characters can however extend outside the kerning lines.
  4. Make sure that you have switched off ClearType or other font antialiasing if you use the FontMaker program, otherwise all your characters will have a purple edge. An alternative is to modify the FontMaker source code to draw on a gray background and then use GetPixel/SetPixel to create the purple mask.

CGapiBitmapFont::SetKerning

This method adjusts font kerning for a bitmapped font.

HRESULT SetKerning(TCHAR tcPreviousChar, TCHAR tcCharToAdjust, LONG lOffset);
Parameters
tcPreviousChar
The preceding character of the char to be adjusted.
tcCharToAdjust
The character to be adjusted.
lOffset
If tcCharToAdjust is preceded by tcPreviousChar in a sentence, move it by lOffset to the left or right.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_OUTOFMEMORY

Remarks

In some cases it is not enough only being able to specify a fixed kerning for each character. For certain character combinations such as "FJ", "AV", and "LT" you might want to adjust the position of the characters individually. If you for example would like the "V" to move closer to the "A" if the string "AV" is being written, you simply call:
SetKerning(TEXT("A"), TEXT("V"), -1);

CGapiBitmapFont::GetStringWidth

This method returns the required width in pixels to draw a text string using the current font.

HRESULT GetStringWidth(const TCHAR* pString, DWORD* pWidth);
Parameters
pString
The string to use for calculation.
pWidth
Returns the width in pixels required to draw the string.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED

CGapiBitmapFont::GetCharWidth

This method returns the width in pixels for a specific character using the current font.

HRESULT GetCharWidth(TCHAR tcChar, DWORD* pWidth);
Parameters
tcChar
The character used to request width.
pWidth
Returns the width in pixels required to draw the character.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED

CGapiBitmapFont::GetSpacing

This method returns the space in pixels between two characters using the current font.

HRESULT GetSpacing(TCHAR tcChar1, TCHAR tcChar2, DWORD* pSpacing);
Parameters
tcChar1
The first character.
tcChar2
The second character.
pSpacing
Returns the space in pixels between tcChar1 and tcChar2.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED