Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

Rt2dFont
[Rt2d]


Functions
const RwChar *  Rt2dFontSetPath (const RwChar *path)
RwBool  Rt2dFontSetReadCallBack (Rt2dFontCallBackRead fpCallBack)
Rt2dFontCallBackRead  Rt2dFontGetReadCallBack (void)
RwReal  Rt2dFontGetHeight (Rt2dFont *font)
RwReal  Rt2dFontGetStringWidth (Rt2dFont *font, const RwChar *string, RwReal height)
Rt2dFont *  Rt2dFontFlow (Rt2dFont *font, RwChar *string, RwReal height, Rt2dBBox *bbox, Rt2dJustificationType format, Rt2dBrush *brush)
RwBool  Rt2dFontDestroy (Rt2dFont *font)
Rt2dFont *  Rt2dFontRead (const RwChar *name)
Rt2dFont *  Rt2dFontShow (Rt2dFont *font, const RwChar *string, RwReal height, RwV2d *anchor, Rt2dBrush *brush)
Rt2dFont *  Rt2dFontSetIntergapSpacing (Rt2dFont *font, RwReal gap)
RwBool  Rt2dFontCacheFlush (void)
Rt2dFont *  Rt2dFontGetFont (RwChar *fontName)
RwBool  Rt2dFontIsUnicode (Rt2dFont *font)

Detailed Description

Font functions

Rt2d Font Format

The Rt2d Toolkit supports three font formats, one outline and two bitmap fonts. Each font description is contained in a text file with .met extension.

The text file must be in UTF-8 format. This is to provide support for Unicode characters.

Metric 1
Metric 1 is a bitmap font and requires a bitmap image. An optional mask can be specified after the image file. The bitmap and mask filenames must not contain any spaces.
Metrics 1 uses the .met file to provide the characters available and their dimension. The position values are the pixel co-ordinates in the image.

The format of a metric 1 file is as follows,

       METRICS1
       <font bitmap> [<font mask bitmap>]
       <base line>
       <character code> <left pos> <top pos> <right pos> <bot pos>
       <character code> <left pos> <top pos> <right pos> <bot pos>
Metric 2
Metric 2 is also a bitmap requiring a bitmap image. An optional mask can be specified after the image file. The bitmap and mask filenames must not contain any spaces.
The metric 2 .met file only list the characters available in the bitmap. Each character's dimension are encoded in the image font.

Each character in the image is surrounded by a boundary. This marks the dimension of the character's bitmap. The start of a character's bitmap is denoted by a marker pixel at the top left of each boundary. It is therefore important that the color values of the marker pixel and the boundary are not used elsewhere. Otherwise the character will use an incorrect area of the bitmap for the character.

The same marker pixel must also be present at the bottom left corner for the first character's bitmap. This is used to determine the height of the font set. Otherwise the font will not be loaded correctly.

The area used for displaying the character is inset by two pixels from the four boundaries. This is to prevent the boundary pixels from appearing when displaying the character.

Metric 2 also support multiple bitmaps for the font. The font can spread over more than one bitmap. This can be used to break up a large image into smaller sections. Or it can be used to support font that have a large number of characters, such as Kanji.

Up to four image bitmaps can be specified.

The format of a metric 2 file is as follows,

       METRICS2
       <font bitmap> [<font mask bitmap>]
       <base line>
       <characters>
       [<font bitmap>] [<font mask bitmap>]
       [<base line>]
       [<characters>]
Metric 3
Metric 3 is an outline font similar to Adobe Type 1 fonts. Each character uses a series of 2d vector commands to describe the geometric shape of the character.
Each font character begins with the character string. The geometric description begins with the begin keyword and ends with end keyword. There is no limit to number of 2d commands for the font. A final moveto command is used to set the width of the character.

The format of a metric 3 file is as follows,

       METRICS3
       <font name>
       '<character>'
       begin
       moveto <x> <y>
       lineto <x> <y>
       curveto <x0> <y0> <x1> <y1> <x2> <y2>
       closepath
       moveto <x> <y>
       end

Rt2d Font Unicode Support

The Rt2d Toolkit provides support for Unicode characters.

A font is considered to be Unicode if it contains characters outside the ASCII character set. Otherwise it is considered to be a plain ASCII font.

Unicode code characters in a font are encoded using the UTF-8 format in the font metrics file. This is so it remains compatible with a plain ASCII character set, which can be encoded in a single byte UTF-8 format.

Rendering a Unicode string is done as normal using the standard API functions. Depending on the font being used, the string will be treated either as Unicode or plain ASCII. Strings using a Unicode font must be in double byte format. Strings using a plain ASCII font must be in single byte format.

Function Documentation

RwBool Rt2dFontCacheFlush (  void    ) 
 

Rt2dFontCacheFlush is used to flush the string cache. This forces the rendering of all the strings in the cache.

Strings using a simple single bitmap as a font are not rendered immediately but instead are store in a cache. This enables all the strings using the same font to be rendered together rather than separately to give an improvement in performance.

This means the drawing order for strings are not preserve and will appear in front of other 2d objects.

Normally the cache is flush automatically via RwCameraEndUpdate or when the cache is full.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Note:
This function is redundant and is no longer used.
Returns:
TRUE if successful or FALSE if there is an error
See also:
Rt2dFontFlow , Rt2dFontShow
RwBool Rt2dFontDestroy (  Rt2dFont *    font ) 
 

Rt2dFontDestroy is used to destroy the specified font. All fonts created by an application must be destroyed before the application closes down.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
font  Pointer to the font
Returns:
TRUE if successful or FALSE if there is an error
See also:
Rt2dFontRead , Rt2dOpen , Rt2dClose
Rt2dFont* Rt2dFontFlow (  Rt2dFont *    font,
RwChar *    string,
RwReal    height,
Rt2dBBox *    bbox,
Rt2dJustificationType    format,
Rt2dBrush *    brush
) 
 

Rt2dFontFlow is used to render the specified string in the given bounding-box and have the text wrap over several lines if necessary. The string is rendered using the specified font, at the specified height and with the given brush. The text is justified within the boundaries of the box according to the specified format.

Note that text is rendered until it reaches the end of the string or no more text can be accommodated inside the bounding-box, whichever comes first.

If the font contains just the ASCII character set, then the string is assumed to be in single byte format.

If the font contains characters outside the ASCII set, then it is assumed to be Unicode and the string must be in double byte format.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
font  Pointer to the font.
string  Pointer to a string containing the text to show.
height  A RwReal value equal to the height of the rendered text.
bbox  Pointer to the bounding-box.
format  Text justification.
brush  Pointer to the brush.
Returns:
a pointer to the font if successful or NULL if there is an error.
See also:
Rt2dFontShow , Rt2dFontRead
Rt2dFont* Rt2dFontGetFont (  RwChar *    fontName ) 
 

Rt2dFontGetFont is used to query if the font is in the font dictionary.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
fontName  Name of the font.
Returns:
A pointer to the Rt2dFont if the font is found, NULL otherwise.
See also:
Rt2dObjectStringGetFont , Rt2dObjectStringSetFont
RwReal Rt2dFontGetHeight (  Rt2dFont *    font ) 
 

Rt2dFontGetHeight is used to retrieve the 'natural' height of the specified font. For outline fonts this function always returns 1.0, but for bitmap fonts the returned value will depend on the current view settings and the CTM. Therefore, using the bitmap font height when rendering text ensures there is a one-to-one mapping to the display; hence the text's rendered size remains independent of current transformations.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
font  Pointer to the font.
Returns:
a RwReal value equal to the height of the font if successful or zero if there is an error.
See also:
Rt2dFontGetStringWidth , Rt2dFontSetIntergapSpacing
Rt2dFontCallBackRead Rt2dFontGetReadCallBack (  void    ) 
 

Rt2dFontGetReadCallBack is used to enquire which function is currently used for reading fonts.

Returns:
Returns a pointer to the user defined font reading function
See also:
Rt2dFontSetReadCallBack , Rt2dFontRead
RwReal Rt2dFontGetStringWidth (  Rt2dFont *    font,
const RwChar *    string,
RwReal    height
) 
 

Rt2dFontGetStringWidth is used to determine the width of the specified string if it were to be rendered at the given height using the given font.

If the font contains just the ASCII character set, then the string is assumed to be in single byte format.

If the font contains characters outside the ASCII set, then it is assumed to be Unicode and the string must be in double byte format.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
font  Pointer to the font.
string  Pointer to the string.
height  A RwReal value equal to the height.
Returns:
a RwReal value equal to the string's width if successful or zero if there is an error.
See also:
Rt2dFontGetHeight , Rt2dFontSetIntergapSpacing , Rt2dFontShow
RwBool Rt2dFontIsUnicode (  Rt2dFont *    font ) 
 

Rt2dFontIsUnicode is used to query if the font is plain ASCII or Unicode. This affects the way strings are treated internally. Plain ASCII fonts treat strings as single bytes. Whereas Unicode fonts requires strings in double byte format.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
font  Pointer to the font.
Returns:
TRUE if the font is Unicode, FALSE otherwise.
See also:
Rt2dFontGetStringWidth , Rt2dFontFlow , Rt2dFontShow
Rt2dFont* Rt2dFontRead (  const RwChar *    name ) 
 

Rt2dFontRead is used to create a font by reading the information contained in the specified font metrics file (the file extension .met is assumed but it should not be included in the file name). The path specified using the function Rt2dFontSetPath is used to indicate the location of the file in the file system. Internally, the full pathname of the font file is obtained by concatenating the font search path with the supplied file name and appending the extension .met (note that the search path should including a trailing path separator).

The metrics file must be in UTF-8 format. This is to support Unicode characters.

A side effect of this function is that the image path is changed.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
name  Pointer to a string containing the name of the font file.
Returns:
a pointer to the font if successful or NULL if there is an error. (This function will also return NULL if the font's image format has not been registered using RwImageRegisterImageFormat.
See also:
Rt2dFontSetPath , Rt2dFontShow , Rt2dFontFlow , Rt2dFontDestroy , RwImageSetPath
Rt2dFont* Rt2dFontSetIntergapSpacing (  Rt2dFont *    font,
RwReal    gap
) 
 

Rt2dFontSetIntergapSpacing is used to define the horizontal spacing of characters when a string is rendered using the specified font. Essentially, an application can use this function to control the spread of rendered strings.

The default spacing is zero, that is, no spreading.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
font  A pointer to the font.
gap  A RwReal value equal to the intergap spacing.
Returns:
a pointer to the font if successful or NULL if there is an error.
See also:
Rt2dFontGetHeight , Rt2dFontGetStringWidth
const RwChar* Rt2dFontSetPath (  const RwChar *    path ) 
 

Rt2dFontSetPath is used to specify the current search path for reading fonts from the file system.

The search path can be considered to be either absolute or relative. In the latter case the search path is relative to the directory from which the application executable is running (the current directory).

When fonts are read the image path is changed.

Always include a trailing path separator in the directory name when setting the search path.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
path  Pointer to a string containing the current font search path.
Returns:
pointer to the font path if successful or NULL if there is an error.
See also:
Rt2dFontRead , RwImageSetPath
RwBool Rt2dFontSetReadCallBack (  Rt2dFontCallBackRead    fpCallBack ) 
 

Rt2dFontSetReadCallBack is used to override the function that will be used to read fonts.

The default font loading mechanism can be used to read any fonts that are accessible via the usual RenderWare file system.

The format of the callback function is:

   Rt2dFont * (*Rt2dFontCallBackRead) (const RwChar *name)
Parameters:
fpCallBack  A pointer to the font-reading function
Returns:
Returns TRUE
See also:
Rt2dFontGetReadCallBack , Rt2dFontRead
Rt2dFont* Rt2dFontShow (  Rt2dFont *    font,
const RwChar *    string,
RwReal    height,
RwV2d *    anchor,
Rt2dBrush *    brush
) 
 

Rt2dFontShow is used to render the specified string using the given font and brush. The height and anchor parameters specify the size and position of the string text when it is rendered; the anchor defines the position of lower-left corner of the string's bounding-box. The anchor is updated to return the position at the end of the string.

Note that heights and positions are defined in absolute coordinates and are subject to the current transformation matrix (CTM).

If the font contains just the ASCII character set, then the string is assumed to be in single byte format.

If the font contains characters outside the ASCII set, then it is assumed to be Unicode and the string must be in double byte format.

The include file rt2d.h and the library file rt2d.lib are required to use this function.

Parameters:
font  Pointer to the font.
string  Pointer to the string.
height  A RwReal value equal to the height of the rendered text.
anchor  A RwV2d value specifying the position for the rendered text. It also returns the position of the end of the string on screen.
brush  Pointer to the brush.
Returns:
a pointer to the font if successful or NULL if there is an error.
See also:
Rt2dFontRead , Rt2dFontFlow , Rt2dFontGetHeight , Rt2dFontGetStringWidth
Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:46:47 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)