Metagraphics .fnt Font File Specification

(The following information is excerpted from the Metagraphics FontWINDOW Reference Manual)

11.1 MetaWINDOW Font Files
This chapter provides detailed technical information on the MetaWINDOW™ font file data structures, plus descriptions on how MetaWINDOW internally operates with bitmap fonts. This information is principally of interest to MetaWINDOW application developers. If you are using FontWINDOW simply to edit or create new fonts, you may wish to skip this chapter or skim it for general interest.

11.2 Font File Formats
The following sections describe the MetaWINDOW font file data structure and its key elements.

The MetaWINDOW font file data structure has been designed such that new features and data elements may be added to font files when required. This font file structure provides an upward compatible path insuring that existing fonts work consistently with newer versions of MetaWINDOW based applications. (Fonts created with newer file formats and extensions are not guaranteed to be downward compatible with applications linked with older MetaWINDOW versions, however.) Two font file formats have been defined for use with MetaWINDOW. Font format 2.0 was used with MetaWINDOW Versions 2.0 through 3.3. Font format 2.1 was provided in MetaWINDOW Versions 3.4 and later. Fonts created with file format 2.0 can be used with applications linked to any MetaWINDOW library Version 2.0 or later. File format 2.1 contains a number of major new enhancements, but will only work with applications linked to MetaWINDOW Version 3.4 or later.

If you are using MetaWINDOW Version 3.3 or earlier, you must use font file format 2.0. If you are using MetaWINDOW Version 3.4 or later, you can use either font file format 2.0 or 2.1, but you should use font format 2.1 in order to take advantage of the enhanced functionality provided with this new file format. This chapter only discusses font format 2.1, which is a superset of the earlier font format 2.0.

11.3 Font File Data Structures
A MetaWINDOW font file is comprised of the following structures:

A font header data structure.
GrafMap and rowTable data strucutures.
A location table data array.
An offset/width table data array
A pixImage data array.
A kerning pairs data array (optional).

Font Header
The first element of any MetaWINDOW font file is the font header record. The font header describes the global parameters for the font file, and also contains the offsets from the start of the file to the other key data elements in the font. (When a font is loaded into memory these offsets are added to the font's base address to define the location of the other structures in the font.) A detailed description of the font header record is provided in Section 11.3.1, pg 53.

(click to view enlarged image)

GrafMap
A MetaWINDOW grafMap data structure (also sometimes referred to as bitmap data record) describes hardware information related to the font. The grafMap data record is defined with the following information:


 typedef struct _grafMap        /* "grafMap" Data Structure     */
 {
     short        devClass;     /* Device class                 */
     short        devType;      /* Device type                  */
     devProc far *devProcs;     /* Ptr to device procedure list */
     short        pixBytes;     /* Bytes per scan line          */
     word         pixWidth;     /* Pixels horizontal            */
     word         pixHeight;    /* Pixels vertical              */
     short        pixResX;      /* Pixels per inch horizontally */
     short        pixResY;      /* Pixels per inch vertically   */
     short        pixBits;      /* Color bits per pixel         */
     short        pixPlanes;    /* Color planes per pixel       */
     short        mapFlags;     /* grafMap flags                */
     rowMap  far *mapTable[32]; /* Pointers to rowTable(s)      */
     short        mapActive;    /* Active logical page          */
     short        mapPages;     /* Number of mapList entries    */
     short        mapList[4];   /* List of logical pages loaded */
     short   far *mapIO;        /* Pointer to I/O port list     */
     short        mapRsvd[4];   /* (reserved for internal use)  */
     long         mapSegment;   /* Map segment                  */
     long         mapHandle;    /* Map handle                   */
     short  (far *mapManager)();/* Pointer to paging manager    */
     short        mapResvd[36]; /* (reserved for internal use)  */
 }  grafMap;

RowTable
The grafMap data record also references a table of pointers to hold the addresses of each raster line of the font's pixel image data. This table is another element of the font file and is called the rowTable. The entries in the rowtable are filled in by MetaWINDOW when the font file is read into memory and initialized. The values that are actually contained in the file are not used and may be anything, as only the space they take up in the file is required.

Location Table
The location table is a table of 16-bit unsigned integer values which define the starting X pixel position for each character in the font's pixel image data record. The ending X pixel position is computed simply as one less than the starting pixel position for the next character. The location table contains n + 1 entries (the last character in the font also needs a terminating location value). If a character is missing (there is no pixel image data corresponding to the location table entry), the location table entry is set to the starting position for the next non missing character in sequence. Any given character n in the font will have an image width of (location table[n+1] - location table[n]) pixels.

Remember that the character's image width is not the same as the character width actually used for determining character spacing (see Offset/Width Table, following). The image width simply defines the width of the character's pixel image which may or may not include any inter-character spacing (MetaWINDOW can separately apply inter-character spacing without taking up any room in the font's pixel image buffer.)

Offset/Width Table
The offset/width table is a table containing pairs of values defining proportional width and positioning information for each character in the font. The first entry for a character specifies its proportional character width. When drawing proportional characters, the character width specifies the spacing from the current pen position to the next pen position for starting the next character.

The second value in each offset/width table entry is a signed image offset value. The image offset can be used to adjust the placement of the character pixel image either right or left relative to the starting pen position. With an offset value of zero (0), the left edge of the character's cell image is aligned on the starting pen position. A plus or minus offset value shifts the left edge of the character's cell image either to the right or left of the pen position, respectively.

The offset/width entries are also used to identify missing characters. If a particular character is undefined, the offset/width values for its entry are set to all bits ON (0xFFFF). When attempting to display a character with an offset/width table entry of undefined, MetaWINDOW reverts to using the font's missing character (as defined in the font header record) in its place.

PixImage
The pixImage is the actual pixel data of all the characters in the font. The format of the pixImage is a standard MetaWINDOW local memory bitmap which, once initialized, may be drawn into and read from just like a graphics screen. The pixImage data can be thought of as a very short and very wide graphics screen containing a single text line of images for each character in the font stored horizontally one next to the other.

As with any screen image memory, horizontal lines of pixels or rasters are stored in contiguous memory. This means that pixImage starts with the top horizontal row of the first character in the font (upper left), and is followed by the next character's top horizontal row, etc. The second horizontal raster line for the first character starts following the end of the top horizontal row for the last character in the font (see Figure 14).

File Structure Organization
Except for the font header and pixImage data buffers, the other various font structures may appear in the font file in any order. The offset values in the font header record defines the starting location for each of these structures in the font. The font header record must always be the first structure in the font, and the pixImage data buffer must always be the last.

11.3.1 Font Header Fields
The following section describes the contents and use of the various font header record fields:

The Font Header Data Structure
The following is a C type definition for the font header.


 typedef struct _ofswid	   /* Offset/Width Table Entry               */
 {
     unsigned char  wid;       /* character width                    */
     signed   char  ofs;       /* character offset                   */
 } ofswid;


 typedef struct  _fontRcd  /* MetaWINDOW FONT HEADER RECORD          */
 {
     Byte   fontVer;           /* Font format version number(=2)     */
     Byte   fontRev;           /* Font style revision designation    */
     Byte   fontNameLen;       /* Font baseName length (0-15)        */
     char   fontBaseName[16];  /* Font Base Name                     */
     char   fontSuffix1[10];   /* Font suffix 1                      */
     char   fontSuffix2[10];   /* Font suffix 2                      */
     char   fontSuffix3[10];   /* Font suffix 3                      */
     char   fontFacing;        /* Synthesized font facing flags      */
     char   fontSign[8];       /* 'METAFONT' signature               */
     Byte   fontWeight;        /* Font weight                        */
     Byte   fontCoding;        /* Character set encoding             */
     long   fontSize;          /* Buffer size needed to hold font    */
     word   fontMax;           /* Maximum character code             */
     word   fontMin;           /* Minimum character code             */
     short  fontPtSize;        /* Point Size                         */
     short  fontfamily;        /* Font family                        */
     short  fontStyle;         /* Device style                       */
     short  fontFlags;         /* Font flags                         */
     long   fontColor[2];      /* Font Character & bkground colors   */
     Byte   minChar;           /* Minimum ASCII character code       */
     Byte   maxChar;           /* Maximum ASCII character code       */
     short  chWidth;           /* Fixed space character width        */
     short  chHeight;          /* Character height                   */
     short  chKern;            /* Fixed space character offset       */
     short  ascent;            /* Ascent                             */
     short  descent;           /* Descent                            */
     short  lnSpace;           /* Line spacing                       */
     word   chBad;             /* Char to show for undefined codes   */
     short  chCenter[2];       /* Icon or Marker center (X,Y)        */
     short  chAngle;           /* Italicize slant angle              */
     short  chUnder;           /* recommended txUnder setting        */
     short  chScore;           /* recommended txScore setting        */
     long   locTbl;            /* offset to locTable                 */
     long   ofwdTbl;           /* offset to ofwdTable                */
     long   kernTbl;           /* offset to kernTable                */
     long   sizeTbl;           /* offset to size/rotation tbl(strk)  */
     long   grafMapTbl;        /* offset to grafMap data record      */
     long   rowTbl;            /* offset to grafMap rowTable(s)      */
     long   fontTbl;           /* offset to font bitImage/nodes tbl  */
     long   fontNotice;        /* offset to trademk/cpyright notice  */
     long   fontSupplier;      /* offset to name of font supplier    */
     long   fontAuthor;        /* offset to name of font author      */
     long   fontInfo;          /* offset to miscellaneous font info  */
     long   fontDate;          /* offset to font creation date       */
     fixed  fontSpacing;       /* spacing between baselines          */
     fixed  fontLowHgt;        /* baseline to top of lowercase 'x'   */
     fixed  fontCapHgt;        /* baseline to top of capital 'H'     */
     fixed  fontAscent;        /* baseline to top of lowercase 'd'   */
     fixed  fontDescent;       /* baseline to bottom of lowercase 'p'*/
     fixed  fontMaxWid;        /* maximum character width            */
     fixed  fontAvgWid;        /* average character width            */
     fixed  fontEmWid;         /* Em space width                     */
     short  fontRsvd;          /* (reserved for future use)          */
     long   offwidTbl[16];     /* offset to facing off/wid tables    */
  /* short  fontData[]; */     /* font data/image tables (variable)  */
}  fontRcd;

fontVer
fontVer is the MetaWINDOW font file format version number. The font version designation is divided into two parts, the minor revision and the major revision as follows:

bit: 7654 3210 ---- xxxx Major Revision xxxx ---- Minor Revision

The font format version number described in this document is Version 2.1 which would be indicated in fontVer as 12 hex (0x12).

fontRev
fontRev is the revision designation set by the font designer for this particular font. The revision should be updated to reflect font revisions and edits.

fontNameLen
fontNameLen is the length (0-15) of the fontBaseName string which follows.

fontBaseName
fontBaseName is an ASCII string for the basic family name of the font. The fontBaseName may have a maximum size of 15 characters and should be terminated by a null character.

fontSuffix1
fontSuffix1 is an ASCII string which may indicate the weight of the font such as light, dark, demi, or bold. fontSuffix1 may have a maximum size of 9 characters and should be null terminated.

fontSuffix2
fontSuffix2 is an ASCII string which may indicate the posture of the font such as italic or oblique. fontSuffix2 may have a maximum size of 9 characters and should be null terminated.

fontSuffix3
fontSuffix3 is an ASCII string which indicates the character spacing or tightness of the font such as condensed, extended, or addset. fontSuffix3 may have a maximum size of 9 characters and should be null terminated.

fontFacing
fontFacing> defines what types of synthesized font facings may be created by MetaWINDOW. In certain cases separate fonts may be created to more accurately represent different font faces rather than to use MetaWINDOW's built-in synthesized font facing features. For these cases, particular synthesized faces may be disabled and not performed by MetaWINDOW.

The fontFacing field is defined as follows:

bit: 7654 3210 Enable(0)/disable(1) Font Facing ---- ---x synthesized Bold face ---- --x- synthesized Italic face ---- -x-- synthesized Condensed face ---- x--- synthesized Extended face ---x ---- synthesized Underline --x- ---- synthesized Strikeout

For example, if a separate font has been created to more closely represent TimesRoman-Italic, the fontFacing flags for the font may be set to 0E hex to allow only synthesized bold, underline and strikeout facings with italic, condensed and extended synthesis disabled.

fontSign
fontSign is the Metagraphics signature for a MetaWINDOW font. This field is set equal to the eight ASCII characters METAFONT and may be tested to verify the identity of a Metagraphics font. The METAFONT signature is also used to identify byte order sequence for fonts ported from other systems.

fontSize
fontSize is the size of the memory font buffer (in bytes) needed to hold this font. fontSize may be larger than the fonts file size if the font is compressed.

fontMin
fontMin is the minimum character code value defined in this font. fontMin may have a value between 0 and 65535.

fontMax
fontMax is the maximum character code value defined in this font. fontMax may have a value between fontMin and 65535.

fontWeight
fontWeight indicates the general font blackness in a range of values from 0 (light) to 255 (max-black). Eight weight ranges are predefined for designating a font's weight (the mid value is the nominal designation for each range):

Weight Range Nominal Weight 0-31 16 Light 32-63 48 Book 64-95 80 Medium (default) 96-127 112 Demi-bold 128-159 144 Bold 160-191 176 Extra-bold 192-223 208 Ultra-bold 224-255 240 Black

fontCoding
fontCoding designates the character encoding sequence for this font. The character encoding defines the mapping between character values and the displayed character. The following character coding sequences are currently defined:

0 = ANSI (default) 1 = EBCDIC 2 = IBM 3 = ADOBE 4 = MAC 5 = KANJI

fontPtSize
fontPtSize is the designated font size as measured in points (1/72 of an inch) for this font when displayed on a device with the appropriate resolution (pixResX and pixResY) for which this font was created.

fontFamily
fontFamily identifies a generic font family grouping for this font and a unique font identification number assigned by Metagraphics. The fontFamily field is encoded in the following format:

Bit: FEDC BA98 7654 3210 Font Family ---- xxxx xxxx xxxx Font family ID number (0-4095) xxxx ---- ---- ---- Font family group (0-16): 0 = undefined 1 = Serif (Times, Century Schoolbook,etc.) 2 = Sans-Serif (Helvetica, Swiss,etc.) 3 = Modern (Pica, Elite, Courier,etc.) 4 = Script (Cursive) 5 = Symbol 7 = Decorative 8 = Icon 9-15 = (reserved)

fontStyle
fontStyle defines the font facing style characteristics for this font. fontStyle is defined in the following format:

Bit: FDEC BA98 7654 3210 Font Style ---- ---- ---- ---1 Bold ---- ---- ---- --1- Italic ---- ---- ---- -1-- Condensed ---- ---- ---- 1--- Extended ---- ---- ---1 ---- Underline ---- ---- --1- ---- Strikeout ---- ---- -1-- ---- Outline ---- ---- 1--- ---- Shadow

fontFlags
fontFlags defines miscellaneous detail information regarding this font:

Bit: FEDC BA98 7654 3210 FONT FLAGS ---- ---- ---- -xxx Geometry: 0 = bitmap font 1 = outline/stroked font 2 = outline font 3-7 = reserved ---- ---- ---- x--- Pitch: 0 = fixed spacing 1 = proportional spacing ---- ---- --xx ---- Compression: 0 = no compression 1 = 1D run-length encoding 2 = 2D run-length encoding ---- --xx ---- ---- Offset/Width Precision: 0 = integer 1 = 1/256 2 = 1/65535 ---- xx-- ---- ---- Pixel Order: 0 = PC (left=msb) 1 = TI (left=lsb)

fontColor
fontColor is the character color (fontColor[0]) and background color (fontColor[1]) of the font. Normally these values are set to 0xFFFFFFFF (white) and 0x00000000 (black) for the character foreground and background colors, respectively. These values are updated by MetaWINDOW during execution when a font needs to be color translated for multi-bit per pixel adapters.

minChar
For ASCII encoded fonts, minChar defines the minimum ASCII code for the font. Normally this value is fontMin mod 255.

maxChar
For ASCII encoded fonts, maxChar defines the maximum ASCII code for the font. Normally this value is fontMax mod 255.

chWidth
chWidth defines the default character width, in integer pixels, when fixed-width facing is active.

chHeight
chHeight defines the height of the character bit image in pixels. chHeight is equal to the sum of ascent + descent.

chKern
chKern specifies the default kerning offset, in integer pixels, when fixed-width facing is active (default 0).

ascent
ascent is the number of pixels above the baseline the font rises.

descent
descent is the number of pixels below the baseline descenders fall.

lnSpace
lnspace is the recommended vertical spacing, in integer pixels, to separate consecutive text lines (default is chHeight*1.2).

chBad
chBad is the character code to display for any undefined character codes.

chCenter[2]
chCenter defines the center x,y position for characters in symbol or marker fonts. chCenter is measured from the lower left corner of the Edit Window. For character fonts chCenter should be set equal to (0,0).

chAngle
chAngle specifies the recommended slant angle for synthesizing italic facing. chAngle is specified in integer tenth of degree increments (default -200 = -20.0 degrees).

chUnder
chUnder is the recommended number of pixels the synthesized underscore should lie below the baseline for this font (default = 1).

chScore
chScore is the recommended number of pixels to leave out of the synthesized underscore before and after a descender that would cross the underscore (default = 1).

locTbl
locTbl is the offset to the start of the Location Table array.

ofwdTbl
ofwdTbl is the offset to the start of the Offset/Width Table array.

kernTbl
kernTbl is the offset to the start of the kernTable array (not currently supported).

sizeTbl
sizeTbl is the offset to the start of the size/rotation table for stroked/outline fonts.

grafMapTbl
grafMapTbl is the offset to the start of the font's grafMap (bitmap) table.

rowTbl
rowTbl is the offset to the start of the font's rowTable space.

fontTbl
fontTbl is the offset to the start of the font's pixImage pixel data (for bitmap fonts), or to the font's geometry data (for stroked/outline fonts).

fontNotice
fontNotice is the offset to the start of the character string of the font's trademark/copyright notice.

fontSupplier
fontSupplier is the offset to the start of the character string of the font supplier's name.

fontAuthor
fontAuthor is the offset to the start of the character string of the font author's name.

fontInfo
fontInfo is the offset to the start of the character string containing miscellaneous information about this font.

Drawing Text Characters
In drawing text, MetaWINDOW follows a fairly simple sequence of steps in processing each character. A basic understanding of this operation is helpful to further understand the uses of the various font record elements. Let's look at a simple example (without synthesized facings) of drawing a string of ASCII text.

The current pen position of the graphics screen defines the baseline and starting left X position for the character to be drawn.
The character's ASCII value Ch, is subtracted from the font header's chMin value to obtain an index into the location table and offset/width table. If Ch is less than the font header's chMin or greater than chMax values, or if the offset/width table entry for Ch is undefined (all bits ON), then this character is missing, and the font's chBad character is drawn in place of Ch.
The ending pen position (i.e. starting pen position for the next character) is calculated by adding the width value of the offset/width table entry for Ch to the initial pen position.
The top edge of the character's destination rectangle is determined by moving the initial pen position up ascent pixels.
The top edge of the character's source rectangle in the font is always 0. The left edge of the source rectangle is defined by the location table entry for Ch.
The character's image width is calculated by subtracting the location table entry for Ch from the location table entry for Ch+1. This value is added to both the source and destination rectangles' left edge, yielding the values for their right edges. The lower edge of both rectangles is determined by moving down from the top edge chHeight pixels.
The rectangular area between the initial pen position and the left edge of the destination rectangle (if any) is filled using the current background color and text rasterOp of the active port.
The area contained by the source rectangle in the font's pixImage buffer is bitblt transferred to the area described by the destination rectangle using the port's current text rasterOp.
If the right edge of the destination rectangle is less than the ending pen position calculated in step 3, the rectangular area between these points is filled using the port's current background color and text rasterOp.
The current pen position is set to the value calculated in step 3.
Steps 1 through 10 are repeated for each character in the string.

Stroked font files differ from bitmapped files in that the character data is made up of a list of vertices rather than a monochome bit image. The font file header section is identical to the bitmapped font header as outlined with the following exceptions:

fontFlags are set to 2 indicating a stroked font.
There is no grafMap element in the file. The grafMapTbl field is not used.
There is no rowTable element in the file. The rowTbl field is not used.
The PixImage table is replaced by a geometry data table. This table is still located using the fontTbl field.
The location table contains unsigned offsets from start of geometry data table to the start of the geometry for each character.
The chBad field is really the geometry grid width value. The lnSpacing field is really the geometry grid height value. The chCenter field is used as the origin of the geometry.
The chBad field is not used to indicate the character to use for any missing characters. The character just beyond the last valid character is used as the missing character.

Geometery data
Each character in the font is represented by a variable length list of signed byte pairs for each x,y node of the geometry. The end of the list for each character is indicated by the special "control node" of the value -1,-1. Each node is connected to the next unless a node is followed by the control node value -1,-2. This indicates that the preceeding node should not be connected to the postceeding node and can be though of as a 'pen-up' or 'move-to' command. Each node specifies a point on the geometry grid which has it's origin in the lower left and a height indicated by the lnSpacing field and a width indicated by the chBad field.

For additional details on stroked font files, see the stroked font source code files contained in stroke.zip.