Introduction

Getting Started

Programming Guides

API Reference

Additional Resources

Define_Font

Functions

void Define_Font (const char *name, const char *options, int data_length, const char *data)
 Describes a specific set of simple geometry to be used as the actual shapes when drawing text characters. More...
 
void Define_Font_By_Reference (const char *name, const char *options, int data_length, const char *data)
 Similar to Define_Font(), but avoids creating an internal copy of the font within HOOPS memory. More...
 
void UnDefine_Font (const char *name)
 Removes all settings established by a previous call to Define_Font(). More...
 

Detailed Description

Function Documentation

void Define_Font ( const char *  name,
const char *  options,
int  data_length,
const char *  data 
)

Describes a specific set of simple geometry to be used as the actual shapes when drawing text characters.

Parameters
name- The name to be associated with this font definition. Passed by reference always.
options- A string describing general characteristics of the font. Passed by reference always.
data_length- Number of bytes in data.
data- Information about extents of character shapes and how to draw them. Passed by reference always.

DETAILS

Define_Font() allows you to specify specific shapes for drawing individual text characters. The data consists of a header section with general information about the font, followed (usually) by descriptions of the individual characters. The options may alter the exact data format. The general form of the data is to represent the characters as drawings within a grid from -127 to 127 in both the X and Y directions. For convenience, many fonts define a much smaller cell size within this range. The current built-in fonts, for instance, are defined in a "standard" box. The box is 0 to 50 vertically, and 0 to (an average of) 30 horizontally, with descenders extending as much as -15 and ascenders as high as 55.

Define_Font_By_Reference() will not make an internal copy of the character data. Instead, it will remember where your data is located.

The following options are recognized:

encoding = choice Specifies the mapping between character codes and their shapes. The same choices can be specified here as for the "encoding" field of Insert_Text_With_Encoding() . Note that a font can be used to draw text only if its encoding is compatible with the encoding specified when the text was inserted. The default is "ISO Latin One" if not specified.

[no] lookup [= callback name] Defines a routine called by the system when it needs data about a specific character in the font. The default, "no lookup", indicates the system should search the data it was given for the necessary information. When a lookup is specified, it is called to provide the address of the data for the specified character. In this case, the system ignores any character specific information (if any) following the header information. The format of the lookup functions is

    void lookup (
        const char *font,
        const char *data,
        unsigned short character,
        unsigned char const **address
    )

The lookup function should fill in "address" with the address of the first byte of the data for the requested character in the specified font. The first byte for the character is that of the "value" field (see character data description below). The data is passed to the lookup routine to do as it pleases. Since the system ignores anything after the header, it is a convenient place to store extra information for the routine. The data_length argument should include any such extra data, which will be copied and later returned. (The By_Reference() version does not copy, instead it passes the original address of the data).

The header portion of the data consists of the following required data (each specified as a single byte):

revision: An indication of the overall format of the data. The only value allowed is 3.

height: The nominal height of the font. This is usually the size of capital letters.

width: A nominal character width for the font.

spacing: The amount of space that should be placed between characters.

The per-character data consists of a short header with sizing information, followed by a list of drawing codes and coordinates. The header format (with each value specified as a byte unless otherwise noted) is as follows:

value: The index associated with this character. If the font encoding is "ISO Latin One", the value is specified as a single byte. Otherwise, (for all currently recognized encodings) the value is given as two bytes, with the high byte first.

width: The width of this character.

x offset / y offset: The position of the left edge and baseline of the character. Usually specified as 0,0 but might be otherwise if the font is being converted from another format, or if the character cell is too large to be based at the origin.

descender: The lowest point on the character.

ascender: The highest point on the character.

The drawing codes consist of a one byte code, possibly followed by other data. The codes currently recognized are as follows:

<0      Polyline-The actual number specifies the number of X,Y 
        coordinate pairs, will be drawn as connected line segments. A one point 
        polyline tries to draw a single dot.
0 Termination– This ends the definition of this character.

 -1 Start fill–Instead of drawing lines that follow, the lines will be stored as the outline of a region to be filled as a polygonal area.

 -2 Restart fill–The current outline will be closed and filled, and a new one will be started.

 -3 End fill–The outline will be closed and filled, and normal line drawing mode will resume. A -3 is added at the end of a character, if needed.

 -4 Ellipse–Two X,Y coordinate pairs are specified. These define the extents of the rectangle surrounding the ellipse. If fill mode is on, the ellipse is drawn filled, and the current outline (if any) remains unchanged.

 -5 3 Point arc–Three X,Y pairs are specified, indicating the start, intermediate, and end points of the arc.

 -13 Restart path–The current path (loop) is to stop and a new one will be started.

EXAMPLES

The definition of part of a (crude) font might have data similar to the following example (assuming options of "encoding=ISO Latin One, no lookup"):

        general header
                3 50 30 20
        left parenthesis
                40
                header
                        10 0 0 -10 55 
                drawing
                        -5 10 -10 0 22 10 55    arc from bottom to top 
                        0
        number 8
                56
                header
                        30 0 0 0 50
                drawing
                        -4 0  0 30 30  bottom circle
                        -4 3 30 27 50  ellipse(slightly flattened)
                        0
        capital A
                65
                header
                        30 0 0 0 50
                drawing
3 0 0 15 50 30 0 up & down slants 2 6 20 24 20 cross stroke 0

NOTES

RESTRICTIONS

See also
Show_Font, Set_Text_Font, Define_Callback_Name, Insert_Text_With_Encoding
void Define_Font_By_Reference ( const char *  name,
const char *  options,
int  data_length,
const char *  data 
)

Similar to Define_Font(), but avoids creating an internal copy of the font within HOOPS memory.

Parameters
name- The name to be associated with this font definition. Passed by reference always.
options- A string describing general characteristics of the font. Passed by reference always.
data_length- Number of bytes in data.
data- Information about extents of character shapes and how to of bytes draw them. Passed by reference always.

DETAILS

No additional details. See Define_Font()

void UnDefine_Font ( const char *  name)

Removes all settings established by a previous call to Define_Font().

Parameters
name- The name to be associated with this font definition. Passed by reference always.

DETAILS

No additional details. See Define_Font()