geFontIndexed

geFont

Description: Bitmapped font support interface

Source file: …\genesis3d\OpenSource\Source\Font\font.h

Contents:

Functions: CreateRef, Destroy, AddCharacters, DestroyBitmapBuffer, AddBitmapBuffer, DrawText, DrawTextToBitmap, GetStringPixelWidth, GetBuffer, GetCharMap, EnableAntialiasing, IsAntialiased

Types: geFont

Constants: view

Overview: view

Additions in Genesis3D v1.6: None

Overview:

This implementation supports any TrueType fonts provided by Windows

To use this API:

1. Call geFont_CreateFont().
2. (Optionally) geFont_AddCharacters().
3. Otherwise, IF you intend to use geFont_DrawText(), call geFont_AddBitmapBuffer().
4. Between geEngine_BeginFrame() and geEngine_EndFrame(), and after geEngine_RenderWorld(),
call geFont_DrawText(). You may call geFont_DrawTextToBitmap() anytime, though.
5. When finished, geFont_Destroy().

Constants:

These are bit flags for geFont_DrawText().

Currently only _WORDWRAP is implemented, and without it, the function will still wrap, just not on word boundaries.

Note that these will fail for non ascii fonts.

#define GE_FONT_WORDWRAP 0x00000002 // wrap on word boundaries

// The following codes are not implemented, and their use will cause an assert.

#define GE_FONT_WRAP 0x00000001 // wrap to fit inside the drawing rect

// GE_FONT_JUST_RETURN_FIT causes return of number of characters that fit in drawing rectangle, WITHOUT drawing anything.

#define GE_FONT_JUST_RETURN_FIT 0x00000004

#define GE_FONT_JUSTIFY_RIGHT        0x00000008

#define GE_FONT_JUSTIFY_CENTER     0x00000010

Types:

typedef struct geFont geFont;

"This is an opaque structure header, an instance of a font"

NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only.

Functions:

GENESISAPI geFont* GENESISCC geFont_Create(const geEngine* Engine, const char * fontNameString, const int fontSize, const int fontWeight , const geBoolean antialiased) ;

PURPOSE: Creates a font, and returns a pointer to it.

Pass in the string name of the TrueType font (case sensitive), and the height in pixels.

ARGUMENTS:

fontNameString - char pointer to a string containing the case sensitive name of the font.

fontSize - the pixel height of the requested font.

RETURNS: On success, pointer to the newly created font. On failure, BasetypesIndexed.htm - NULL NULL.

NOTE: the new font set has NO actual characters in it at first. You must add characters

to it with the _AddCharacters() function before you can use the font.

NOTE: all fonts start out with a grayscale palette, with the range 0 to 128.

GENESISAPI void GENESISCC geFont_CreateRef(geFont* font);

GENESISAPI void GENESISCC geFont_Destroy(geFont** font);

PURPOSE: Destroys a font.

ARGUMENTS:

font - pointer to the font to be destroyed.

RETURNS: nothing.

GENESISAPI geBoolean GENESISCC geFont_AddCharacters(geFont* font, unsigned char leastIndex, unsigned char mostIndex);

PURPOSE: Adds a set of characters to the font defined by the ascii range passed in (leastIndex and mostIndex, inclusive).

ARGUMENTS:

font - pointer to the font to add characters to.

e - pointer to a valid geEngine. (this is apparently no longer required)

leastIndex and mostIndex - the ASCII range of characters to add.

cellBuffer - an allocated hunk of ram to temproarily store the character image (this is apparently no longer required)

bufferSize - length of the above buffer (this is apparently no longer required)

RETURNS: GE_TRUE if succesfull, otherwise, GE_FALSE on failure

NOTES: This is the function that actually uses the Win32 GetGlyphOutline() function to draw the character onto a geBitmap, which can be blitted to the screen.

GENESISAPI void GENESISCC geFont_DestroyBitmapBuffer(geFont* font );

PURPOSE: Destroys any valid "scratch-pad" buffer attached to the geFont.

ARGUMENTS: font - pointer to the geFont.

NOTES: You'll rarely need to call this function; it's called by geFont_Destroy() anyway.

Calling this function with a geFont that has no initialized buffer doesn't hurt anything.

GENESISAPI geBoolean GENESISCC geFont_AddBitmapBuffer(geFont* font, const uint32 width, const uint32 height);

PURPOSE: Adds a geBitmap to the geFont, to be used as a temporary "scratch-pad". This is required for using geFont_DrawText() when no characters have been added.

ARGUMENTS:

font - pointer to the geFont to add a buffer to.

width and height - the size of the buffer to create. Make sure this size is >= the biggest rectagle of text you'll want to write to the screen using this geFont

and DrawText().

RETURNS: GE_TRUE if succesfull, otherwise, GE_FALSE on failure

NOTES: You don't need to call this function IF you _AddCharacters() to this geFont.

You call this function for each geFont you need to use. geFont's don't share buffers.

if you call this function on a geFont that already has a valid buffer, the buffer is

destroyed, and replaced by the new one.

GENESISAPI geBoolean GENESISCC geFont_DrawText(geFont* font, const char * textString, const BasetypesIndexed.htm - GE_Rect GE_Rect* Rect, const GE_RGBA* Color, uint32 flags, const BasetypesIndexed.htm - GE_Rect GE_Rect* clipRect);

PURPOSE: This is the function you put between geEngine_BeginFrame() and _EndFrame(), the function that draws text to the screen.

ARGUMENTS:

font - pointer to the font to draw with. IF the font has NO characters in it (added by geFont_AddCharacters() ) then a different, more windows-intensive way is used to draw out the characters.

textString - pointer to the text string to output to the screen.

Rect - screen rectangle to place the text within.

Color - RGB color the text should be.

flags - a bitfield of GE_FONT_ values.

clipRect - pointer to a screen rectangle to clip the text to. MAY BE BasetypesIndexed.htm - NULL NULL, in which case the text is only clipped by the boundaries of the screen.

RETURNS: GE_TRUE if succesfull, otherwise, GE_FALSE on failure

NOTES: Assuming you've added characters to the font, characters which have NOT been added WILL cause an assert if you try to draw them.

Only GE_FONTSET_WORDWRAP (actually, GE_FONT_WORDWRAP) is meaningfull right now. Using any other flags will cause an assert.

As stated above, you can use an entirely different way of creating a string, by making a font with no characters in it. This jumps through Windows DIB hoops, and draws the text in a non-anti-aliased, but (hopefully) more unicode-tolerant way (DrawText() ).

GENESISAPI geBoolean GENESISCC geFont_DrawTextToBitmap(geFont* font, const char * textString, const BasetypesIndexed.htm - GE_Rect GE_Rect* Rect, const GE_RGBA* Color, uint32 flags, const GE_Rect* clipRect, geBitmap* targetBitmap);

PURPOSE: This is the function you put between geEngine_BeginFrame() and _EndFrame(), the function that draws text to the screen.

ARGUMENTS:

font - pointer to the font to draw with. IF the font has NO characters in it (added by geFont_AddCharacters() ) then a different, more windows-intensive way is used to draw out the characters.

textString - pointer to the text string to output to the screen.

Rect - screen rectangle to place the text within.

Color - RGB color the text should be.

flags - a bitfield of GE_FONT_ values.

clipRect - pointer to a screen rectangle to clip the text to. MAY BE BasetypesIndexed.htm - NULL NULL, in which case the text is only clipped by the boundaries of the screen.

targetBitmap - pointer to a target bitmap to draw the text into. MAY NOT BE BasetypesIndexed.htm - NULL NULL, and MUST BE BasetypesIndexed.htm - GE_PI GE_PIXELFORMAT_8BIT.

RETURNS: GE_TRUE if succesfull, otherwise, GE_FALSE on failure

NOTES: Assuming you've added characters to the font, characters which have NOT been added WILL cause an assert if you try to draw them.

Only GE_FONTSET_WORDWRAP (actually, GE_FONT_WORDWRAP) is meaningfull right now. Using any other flags will cause an assert.

The Color argument is will be used to modify the existing palette of the targetBitmap passed in. Therefore, you won't be able to _DrawTextToBitmap() a red piece of text, then a green piece, then a blue piece. You'll end up with three lines of blue text

GENESISAPI int32 GENESISCC geFont_GetStringPixelWidth (geFont* font, const char * textString);

PURPOSE: These two functions return the pixel width and height of the string passed in.

ARGUMENTS:

font - pointer to the font to draw with.

textString - pointer to the text string to output to the screen.

RETURNS: On success: a positive value in pixels. IF the text passed in contains characters which haven't been added to the font yet, BUT other characters HAVE been added, the function asserts. On failure: -1.

NOTES: These two functions assume no text wrapping!

GENESISAPI geBitmap* GENESISCC geFont_GetBuffer(geFont* font);

PURPOSE: This function returns a pointer to the drawing buffer contained by the font.

ARGUMENTS:

font - pointer to the font.

RETURNS: A valid pointer to a geBitmap, OR BasetypesIndexed.htm - NULL NULL, signifying that the buffer wasn't initialized.

GENESISAPI geBoolean GENESISCC geFont_GetCharMap(geFont* font, uint8 character, GE_Rect* Rect, geBitmap** targetBitmap, int32* fullWidth, int32* fullHeight, int32* offsetX, int32* offsetY);

GENESISAPI void GENESISCC geFont_EnableAntialiasing(geFont* font, const geBoolean anti);

GENESISAPI geBoolean GENESISCC geFont_IsAntialiased(geFont* font);