Generic Font

OS/2 supports generic fonts which can be used for all installed presentation device drivers and which can support the character glyphs for all supported countries (will use "I18N character glyph" terminology from now on). In this sense, OS/2 can display and print I18N character glyphs even if no font is provided by presentation device drivers. The generic font can be either an image or an outline form. The outline font technology supported depends on the Intelligent Font Driver Interface (IFI) font drivers that are installed on OS/2.

The following font format will be supported by OS/2.
 * OS/2 2.1 PM font-file format (image/outline)
 * IBM Uni font-file format
 * Adobe type-1 font-file format
 * Adobe composite font-file format (called NCF format - CMap and CIDFont)
 * IBM Combined font-file format
 * Truetype

OS/2 2.1 supports only the character glyphs which are defined in the "PM383" glyphlist at present, however, OS/2 4.0 will support eight more glyphlists, "PMJPN", "PMKOR", "PMTWN", "PMPRC", "PMBG5", "PMKS",  "SYMBOL" and "UNICODE" in order for the graphics engine  support new country and new language fonts, and the PM383 glyphlist will be extended to 504 glyphs.

OS/2 PM font-file format and Adobe type-1 font format cannot support large character set fonts, such as DBCS and Unicode font. Large character set fonts must be provided either in Adobe composite font format, Truetype font format (No plan at this moment), Combined font-file format or the IBM Uni font-file format which will be supported by the raster IFI font driver.

Glyphlist
Every physical font is associate with a glyphlist name. The glyphlist name is the name that identifies a set of character glyph names and font index sequence of the character glyph set. The graphics engine decides translation from code point to font index (glyph index) by using the glyphlist name. The following glyphlists will be supported by the OS/2 graphics engine.


 * "PM383" The glyph index which is currently supported by OS/2 2.1. 383 character glyphs are defined in this glyphlist.
 * "UNICODE" This glyphlist consists of the Unicode specification adopted by the International Organization for Standardization (ISO) as ISO 10646.
 * "SYMBOL" or "" This is a font specific encoding which is usually used to define a symbol character set.
 * "PMJPN" This is a "PM383" extension for the Japanese language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 932 character glyphs. This glyphlist will be supported for the migration of existing font files.
 * "PMCHT" This is a "PM383" extension for the Traditional Chinese language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 938 character glyphs. This glyphlist will be supported for the migration of existing font files.
 * "PMKOR" This is a "PM383" extension for the Korean language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 934 character glyphs. This glyphlist will be supported for the migration of existing font files.
 * "PMPRC" This is a "PM383" extension for the Simplified Chinese language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 936 character glyphs. This glyphlist will be supported for the migration of existing font files.

To simplify the graphics engine design and implementation, we may prefer to have it support only the "UNICODE" glyphlist. However, this may decrease the performance of font drawing since the index translation from code page string to Unicode and Unicode to font indices occurs quite often, while most of the current applications and fonts are based on code page, not Unicode. The glyphlists of "PM383", "PMJPN", "PMCHT", "PMKOR" and "PMPRC" will be useful to support code page based applications and fonts without the performance degradation of index translation cost.

Graphics engine font
The graphics engine reads and parses the following font format directly.

OS/2 PM font-file format

This is the OS/2 2.1 PM font-file format designed for small character sets and is supported. "PM383" and "SYMBOL" glyphlists can be supported this format. See the OS/2 Technical Library Presentation Manager Programming Reference Volume III for more details.

IBM Combined font-file format

This a new format being supported by OS/2. The "UNICODE" glyphlist can be supported this format. The detailed format will be discussed in a later section.

ATM IFI font driver font

The ATM IFI font driver supports the following font file format.

Adobe Type1 font format

This is the Adobe Type 1 font file format designed for small character set fonts. "PM383", "SYMBOL" and "UNICODE" glyphlists can be supported by this format. See the Adobe Type 1 Font Format version 1.1 for details. The OFM (Object Font Metrics) file format will be enhanced in order to support the "UNICODE" glyphlist.

Adobe NCF font format

This is the Adobe new composite font format designed for small and large character set fonts. The "PM383", "SYMBOL", "UNICODE", "PMJPN", "PMKOR", "PMCHT" and "PMPRC" glyphlists can be supported by this format. See "Adobe CMap and CIDFont Files Specification" for NCF font format details.

Raster IFI font driver font

The Raster IFI font driver supports the following font file format. IBM Uni font-file format

This format is an extension of the OS/2 PM font-file format for large character set. The format will be discussed in a later section. The "PM383", "SYMBOL", "PMJPN", "PMCHT", "PMKOR" ,"PMPRC" and "UNICODE" glyphlists will be supported by this format.

Truetype IFI font driver font

The Truetype IFI font driver supports the following font file format.

Truetype font format

A Truetype IFI font driver was developed in order to support Truetype fonts which are widely available in the market.

Font Cache

The graphics engine implements character glyph (bitmap) caching for IFI font driver fonts. Total cache buffer limit or the number of cacheable typeface/size(s) will be customized for user through a Workplace Shell system setting object on OS/2. (Not implemented.) It is important that the caching is designed to work for large character set fonts with reasonable performance (hit ratio point of view). The following points have been considered for handling multiple large character set font for the caching. High hit ratio for the given buffer size. Linear search is prohibited. Fragmentation - glyphs have different sizes. A new font bitmap caching method will be used to support both small and large character set fonts. A prototype cache code is already used in OS/2 2.1 graphics engine for DBCS IFI font bitmap caching.

Intelligent Font Interface

The OS/2 graphics engine enhances the Intelligent Font Interface (IFI) in order to support raster IFI font drivers, additional glyphlists etc. This IFI driver version will be defined as IFI version 2.1.

Font Objects

Current Model
The following figure shows the architecture for font support in OS/2 2.1. The PMWIN component has a number of mapping tables from a set of supported codepages to a format called UGL PM383.

This is the same encoding used for the system bitmap fonts. For ATM outline fonts, the graphics engine's implementation of the ATM driver has a converter which maps ATM character names to the same UGL PM383 table. Therefore, all font manipulation is done through this internal encoding of characters. In the Asian versions of OS/2 we supply alternative mapping tables for the extended Asian character sets and use a different UGLs: PMJPN, PMKOR and PMCHT for Japan, Korea and Taiwan respectively. We also supply different system fonts which match these encodings.

The New Model
As we enter new markets with new character set requirements or attempt to support multilingual text we are faced with the problem of building new UGLs or hacking an existing one. An alternative approach is to design support for font objects which maintain the information about the character sets they support. Each font object will have an associated DLL which maps from the ASCII or Unicode character encodings to the character glyph definitions supplied by the font. In other words we remove the notion of the system maintaining a single list of supported characters (the UGL).

The advantages of this are: We isolate the dependencies of the GRE on Font encodings. We can easily add new character sets through new fonts. We can support multilingual text through the Unicode mapping support.

The new model is shown in the following figure. The font header identifies the glyphlist associated with the font. This could be PM383, Unicode, PMJPN or some other name. Current bitmap fonts have no header and will be assumed to be PM383 bitmap fonts. The GRE will use a table to asscoiate the font with a DLL. The default behavior will find the DLL based on the glyphlist name. This DLL supports three functions: Install, CodePointToGlyph and UnicodeToGlyph. The later map from either an ASCII codepoint to a 16bit glyph index representing the appropriate character.

The font glyph index is used to query the intelligent font interface (IFI) driver of the font to retrieve the rasterized character bitmap. The install function sets up the mapping tables needed for the conversions and establishes some of the font caching characteristics. Some of the values established at this point are: the number of glyphs in the font, the lowest value of the font index, the highest font index value and a set of index ranges which contain the entire set of glyphs in the font. The graphics engine deals with two kinds of fonts: engine fonts and IFI fonts. An engine font is a bitmap font with a defined structure. The engine fonts used today support only the characters in PM 383. Their layout is shown above. A table of 383 entries is built with a width entry (the size of the character) and an offset into a 64k heap pointing to the character bitmap definition. This table is part of the public interface to the graphics engine and is used by graphics device drivers. An IFI font is a font, outline or bitmap, accessed through a special interface called an IFI driver. The IFI driver accepts 16bit glyph index and returns a rasterized image. For each IFI font loaded, the graphis engine creates a fake representation of an engine font. As characters are rasterized, the entries in the header table are filled in. Thus the display devices are not aware of the differences between engine fonts and IFI fonts. This mechanism is also a simple cache mechanism for small fonts. Large fonts use a secondary cache to store the rasterized bitmaps. Just before the display device is called to render the characters, the bitmaps are copied to the fake engine font format. In this way, the display devices are also unaware of the difference between small or large fonts. However, this comes at a cost of performance for large fonts. Copying the bitmaps is a wasteful operation. We will call the engine font supplied to the display device the Font Transfer Area (FTA). This will be used for the existing support of PM display drivers. A different interface will be used for future support which removes the need to copy bitmaps.

The Algorithm
There are two cases to account for: Unicode encoded text and ASCII encoded text. Unicode or ASCII text is passed to the GRE to be rendered in a presentation space (PS). Identify the current logical font for the PS. If ASCII text is passed get the current PS codepage. Call the font's UnicodeToGlyph or CodePointToGlyph function which returns a font index, for each character in the string. Either the native glyphlist of the font object is Unicode => Noop or the font object converts from Unicode to the native encoding (e.g. PM 383) Look in the font cache for the bitmap If it is an engine font then the bitmap will always be there. It it is an IFI font, the bitmap may not yet be available. If the bitmap is not available, ask the font IFI driver for the glyph. Place it in the cache. Copy the bitmaps to the Font Transfer Area (FTA), if required. This is not required if the font caching mechanism uses the FTA directly (small ATM fonts). Call the graphics driver for the PS to render the bitmaps This algorithm, together with the font objects, will extensibly support multiple glyphlists and Unicode in an efficient manner. Even though the design supports multilingual text and large fonts, an application  using ASCII text and an exisiting PM383 font will not pay any penalty in performance.

Combined Font
The Goals of OS/2 I18N font support are :
 * Font support for drawing Unicode encoded text data.
 * Add-on font installation for newly supporting languages.

The first goal is for OS/2 Unicode support. OS/2 needs to provide a way to support Unicode encoded text, using existing font files. The second goal is to add new languages easily. This addresses the problem of the 383 limitation of OS/2 2.1 PM Universal Glyph List (UGL), which makes it difficult to support new languages and countries. OS/2 is designed to allow new countries to be supported easily. OS/2 proposes a "Combined Font" font architecture to achieve the above goal. The following section describes the combined font proposed design. This section shows the combined font design concept and how to implement the combined font in the graphics engine.

Combined Font - A graphics engine generic font that is dynamically created by combining several physical fonts. Application can select and use the font in the same way as the physical fonts.

Physical Font Entry
A physical font entry is a graphics engine heap representation for a graphics engine generic font. This contains font metrics, glyphlist name, use count and pointers or a cache keys to retrieve character glyph data and character attributes, such as character width or abc space. A physical font entry will be created when a new font, which is not an IBM combined font, is installed through the GreLoadFont function, and will be destroyed when it is unloaded through the GreUnloadFont function. There are two places to store the physical font entries in the graphics engine heap area. One is in a global shared heap which can be accessed by all processes, the other is in an instance heap which can be accessed by only one process. The physical font entries for public fonts are placed in the global shared heap, and the ones for private fonts are placed in the instance shared heap. The physical font entry will be designed to allow large character set encoding such as Unicode. An encoding table that consists of a set of ranges will be included in the physical font entry. Each range will point to an index of character glyph, which will be the starting index of the range.

Combined Font Entry
The combined font entry is a binary representation of IBM Combined font-file format which is located in the graphics engine heap. The combined font entry includes font metrics for the combined font, an array of component font entries, use count and a priority list of component fonts. The component fonts must be public fonts. The priority list of component fonts will be used to choose a component font from the "UNICODE" glyph index that is translated from the text string. Note that the only supported glyphlist for combine font is "UNICODE". Component fonts may have different glyphlists. In this case, the graphics engine will do the necessary conversion from Unicode indices to indices of the appropriate glyphlist, in order to retrieve character glyph from the component font. Since the combined font points to physical font entries in the graphics engine heap, the graphics engine must assure that all  component fonts are usable for the combined font. Therefore, the physical fonts installed to OS/2 as public fonts must be loaded prior to loading the combined font.

It is allowed to combine either raster fonts or outline fonts into a combined font. A raster font and an outline font cannot be combined into the same combined font.

A combined font entry will be created when an IBM combined font is installed through the GreLoadFont function, and will be destroyed when it is unloaded through the GreUnloadFont function.

IBM Combined Font-File Format
The font-file format for combined font will be defined and documented. The above figure shows an overall idea how the format is organized.

IBM Combined Font-File Creation Tool
A font creation tool for IBM combined font will be provided with so that users or national language feature developers can create an IBM combined font easily OS/2. (A proposal of the user interface for the font creation tool is written in the "User Interface for Combined Fonts section" in the OS/2 2.X NLF design workbook. See it for more details.)

Glyph Index Translation
When an application draws a text string, the graphics engine parses the text string using a code page associated with the device context of the target device and translate into font indices for the physical font. (called glyph index translation). The physical font images are extracted from the graphics engine supported font files (OS/2 PM font-file format and IBM Combined font-file format) or IFI font drivers. They are maintained in the graphics engine heap. The glyph index translation will be performed by using ICONV functions which are being supported as a part of OS/2 I18N subsystem. It is necessary that the ICONV functions can support the translation from code points of all code pages to the supported glyphlist indices.

Generic Font
The glyph index translation and the preparation of character glyph bitmaps will be performed by the graphics engine. The graphics engine will call the device driver (using DDI entries) in order to draw the character glyphs on the target devices. For generic fonts, there will be no change required for OS/2 2.X device drivers that will be ported to OS/2.

Device Specific Font
A presentation device driver can provide device specific fonts for the built-in fonts in the hardware such as a printer or a display adapter card. For the device specific fonts, the responsibility of the glyph index translation resides at the device driver. Device drivers must recognize which code page is associated with the text string and do the proper conversion to the font indices of the device specific font.

Unicode with device specific font
Presentation device drivers will inform to the graphics engine whether it can translate Unicode string to font indices of the device specific font or not. This will be done by turning the CAPS_ADDTIONAL_GRAPHICS Unicode flag field on for the GreQueryDeviceCaps DDI function (The default is to turn the flag off). The graphics engine passes the Unicode text string on to the presentation device driver if the presentation device driver declares the Unicode glyph index translation support, otherwise, the Unicode text string will be translated in the indices of PM383 (the default behavior the for non Unicode device specific font to handle the Unicode text string at most). There is no way that the graphics engine takes over the glyph index translation from Unicode to the font indices of the device specific font when the presentation device driver does not support the glyph index translation for Unicode.

Combined Font
There are two passes in the process of the glyph index translation of a combined font. The first pass is to translate from code points to indices of the "UNICODE" glyphlist. The second pass is to translate the indices of the "UNICODE" glyphlist to the indices of the component font glyphlist. If the component font glyphlist is the "UNICODE" glyphlist, no translation will be performed in the second pass. The indices returned from the second pass will be used to extract font images and attributes from the component font file.

GreQueryCodePageVector
GreQueryCodePageVector is an API that is already supported by OS/2 2.X graphics engine and is being used by presentation device drivers. The graphics engine will provide the same interface and the same result as OS/2 2.X in order that existing presentation device drivers that will be ported to OS/2 will work properly.

Vertical Drawing
In Asian countries such as Japan, traditional drawing direction is top to bottom. Newspapers are still written in top to bottom format today. Besides, IBM Font Object Content Architecture (FOCA) has provision for fonts used in vertical drawing.

According to FOCA, the fonts for vertical drawing should have the following characteristic in the font metrics:


 * Inline Direction 		= 90 degree
 * Character Rotation 		= 270 degree

The graphics engine should utilize these parameters in its drawing. Currently, an application can use GpiSetCharAngle to change the inline direction, however, there is not interface or mechanism which can be used to take the character rotation in account. The graphics engine needs to multiply another matrix which is the required rotation and retrieved the character rotation in the font metrics, right before the shear matrix.

The Uni Font-file format
The Uni Font-file format is designed for image fonts which has large character set in the font file such as the DBCS (Double Byte Character Set) and the UNICODE encoding. The Uni Font-file format is a super set format of the OS/2 2.1 PM Font-file format. The Uni Font-file consists of a Uni font directory and several Uni font resources which are included in the font file. The font directory and the font resource are a set of self-defining records of the form:

typedef struct _RECORD {	UCHAR  Identity[4]; 	/* structure identity code */ ULONG  ulSize;   		/* structure size in bytes */ .                    			/* data */ .	. } RECORD;

The notation of bit order defined in this document is that bit 0 is LSB. The elements in the stuructures defined in this document must be aligned in 1 byte boundaries. OS/2 4.0 will support only image fonts for the Uni font-file format.

The Uni Font Directory
This section describes the directory section of a Uni font resource. A Uni font directory contains a directory consisting of a set of structures. Each structure contains the flags, the offset to a Uni font resource, the index to a base Uni font resource if the font is a virtual font. Several Uni font resources can be contained in a Uni font-file by specifying them in the FontResEntry array in the UNIFONTDIRECTORY structure. All values in the UNIFONTDIRECTORY structure is stored in the little endian format. The format of the font directory is:

typedef struct _UNIFONTDIRECTORY {	ULONG		Identity[4]; ULONG		ulSize; ULONG		ulUniFontResources; ULONG		flEndian; ULONG		flFileMode; UNIFONTRESOURCEENTRY FontResEntry[1]; } UNIFONTDIRECTORY;

where:

Identity		4 byte. Must be 0x554E4644 ('UNFD') ulSize			4 byte unsigned integer. The size of the structure, in bytes, which includes all entries of UNIFONTRESOURCEENTRY. (i.e. sizeof(UNIFONTDIRECTORY) + sizeof(UNIFONTRESOURCEENTRY) * (ulUniFontResources - 1)) ulUniFontResources	4 byte unsigned integer. The number of the Uni font resources in the Uni font file. flEndian		4 bytes of flags to specify the byte order and the bit order of the font file. UNIFONT_ENDIAN_BYTEOREDER (bit 0)	Must be ZERO. UNIFONT_ENDIAN_BITORDER (bit 1)		Must be ZERO. Other bits must be ZERO. flFileMode		4 byte of flags to specify file mode. UNIFONT_WRITABLE (bit 1)	This flag is on if the font file is designated to be updated, such as the user defined font. FontResEntry		ulUniFontResources size of array of the UNIFONTRESOURCEENTRY structure.

The format of the Uni font resource entry is

typedef struct _UNIFONTRESOURCEENTRY {	ULONG		flUniFont; LONG			offsetUniFont; ULONG		ulBaseUniFont; } UNIFONTRESOURCEENTRY;

where:

flUniFont		4 bytes of flags. UNIFONT_VIRTUAL_FONT (bit 0) 	This flag is on if the font is a virtual font. The font character group definition and the font character definitions are not included in the font resource. The virtual font consists of only the font signature, the font metrics, the font end signature and the font definition header. Other bits must be ZERO. offsetUniFont		4 byte signed integer. The offset from the beginning of the file at which the Uni font resource begins. ulBaseUniFont	4 bytes unsigned integer. The index in the FontResEntry array in UNIFONTDIRECTORY which specifies the base Uni font resource used by the virtual font. This field will be specified only when the font is defined as a virtual font.

The Uni Font Resource
The Uni font resource format consists of two sections. The first section contains the general attributes of the Uni font resource and describes features such as its typeface, style and nominal size. The second section contains the actual definitions of the characters belonging to the Uni font resource. There are four to six records in a Uni font resource in a Uni font file between the font signature and the font end resource:

The font signature (UNIFONTSIGNATURE) The font metrics (UNIFONTMETRICS) The font definition header (UNIFONTDEFINITIONHEADER) The font character group definitions (UNICHARGROUPDEFINITION) The pair kerning table. (Option) (UNIKERNPAIRTABLE) The font character definitions The font end signature (UNIENDFONTRESOURCE)

The records in the Uni font resource must be in the order defined above. Earlier records have lower numbers in the identity field. The font character definition of the image format is only supported.

The next figure shows an example of a Uni font resource which has N character group definitions.

The Font Signature

A Uni font resource starts with a special font-signature structure and ends with an ending structure. The font signature has the form:

typedef struct _UNIFONTSIGNATURE {	UCHAR	Identity[4]; ULONG	ulSize; UCHAR	szSignature [24]; UCHAR	szTechnology[64]; LONG		offsetCompressTable; ULONG	flFontResource; } UNIFONTSIGNATURE;

where: Identity		4 bytes. Must be 0x554E4653 ('UNFS'). ulSize			4 byte unsigned integer. The size of the structure, in bytes. szSignature		A NULL terminated string. Must be "UNI FONT". The future enhancement of the Uni font-file format may have a different signature in this field. szTechnology		A NULL terminated string which represents the compress technology of the character glyph images. If the charcater glyph images are not compressed, the NULL string "" must be placed. This field must be NULL string for WPOS and OS/2 2.2. This field is reserved for the future compressed font support. offsetCompressTable	4 byte signed integer. The offset from the beginning of the file at which the compress table begins. This field will be used only if the compress technology name is specifed in the szTechnology field. This field must be ZERO and reserve for the future compressed font support. flFontResource	4 Bytes of flags. UNIFONT_KERNINGPAIRS_EXIST (bit 0) 	Indicates that the font has the kerning pairs table UNIFONT_PANOSE_EXIST (bit 1)		Indicates that the font has PANOSE description Other bits must be ZERO.

The Font End Signature
The font end structure has the form:

typedef struct _UNIENDFONTRESOURCE {	UCHAR	Identity[4]; ULONG	ulSize; } UNIENDFONTRESOURCE;

where: ulIdentity	4 bytes. Must be 0x554E4645 ('UNFE'). ulSize		4 byte unsigned integer. The size of the structure, in bytes.

The Font Metrics

This section gives an explanation of how to set the fields of the UNIFONTMETRICS structure which contains the physical font metrics used when creating fonts.

/* #defines for fsType in IFIMETRICS */


 * 1) define IFIMETRICS32_FIXED      0x0001
 * 2) define IFIMETRICS32_LICENSED   0x0002
 * 3) define IFIMETRICS32_KERNING    0x0004
 * 4) define IFIMETRICS32_DBCS       0x0010
 * 5) define IFIMETRICS32_MBCS       0x0018
 * 6) define IFIMETRICS32_UNICODE	  0x0020
 * 7) define IFIMETRICS32_FACETRUNC  0x1000
 * 8) define IFIMETRICS32_FAMTRUNC   0x2000
 * 9) define IFIMETRICS32_NO_CACHE	  0x4000

/* #defines for fsDefn in IFIMETRICS */


 * 1) define IFIMETRICS_OUTLINE      0x0001
 * 2) define IFIMETRICS32_UDC	  0x0002
 * 3) define IFIMETRICS32_ANTI_ALIAS 0x0004

/* #defines for fsSelection in IFIMETRICS */


 * 1) define IFIMETRICS32_ITALIC     0x8000
 * 2) define IFIMETRICS32_UNDERSCORE 0x4000
 * 3) define IFIMETRICS32_OVERSTRUCK 0x2000
 * 4) define IFIMETRICS32_NEGATIVE   0x1000
 * 5) define IFIMETRICS32_HOLLOW     0x0800

typedef struct _IFIMETRICS32 {  UCHAR   szFamilyname[32]; UCHAR  szFacename[32]; UCHAR  szGlyphlistName[16]; ULONG  idRegistry; LONG   lCapEmHeight; LONG   lXHeight; LONG   lMaxAscender; LONG   lMaxDescender; LONG   lLowerCaseAscent; LONG   lLowerCaseDescent; LONG   lInternalLeading; LONG   lExternalLeading; LONG   lAveCharWidth; LONG   lMaxCharInc; LONG   lEmInc; LONG   lMaxBaselineExt; FIXED  fxCharSlope; FIXED  fxInlineDir; FIXED  fxCharRot; ULONG  ulWeightClass; ULONG  ulWidthClass; LONG   lEmSquareSizeX; LONG   lEmSquareSizeY; GLYPH  giFirstChar; GLYPH  giLastChar; GLYPH  giDefaultChar; GLYPH  giBreakChar; ULONG  ulNominalPointSize; ULONG  ulMinimumPointSize; ULONG  ulMaximumPointSize; ULONG  flType; ULONG  flDefn; ULONG  flSelection; ULONG  flCapabilities; LONG   lSubscriptXSize; LONG   lSubscriptYSize; LONG   lSubscriptXOffset; LONG   lSubscriptYOffset; LONG   lSuperscriptXSize; LONG   lSuperscriptYSize; LONG   lSuperscriptXOffset; LONG   lSuperscriptYOffset; LONG   lUnderscoreSize; LONG   lUnderscorePosition; LONG   lStrikeoutSize; LONG   lStrikeoutPosition; ULONG  ulKerningPairs; ULONG  ulFontClass; } IFIMETRICS32; typedef IFIMETRICS32 *PIFIMETRICS32;

typedef struct _UNIFONTMETRICS {	UCHAR		Identity[4]; ULONG		ulSize; IFIMETRICS32	ifiMetrics; ULONG		flOptions; PANOSE		panose; UCHAR		szFullFamilyname[256]; UCHAR		szFullFacename[256]; } UNIFONTMETRICS; typedef UNIFONTMETRICS *PUNIFONTMETRICS;

UNIFONTMETRICS is an extension of IFIMETRICS32 which is redefined for the 32 bit environment by assuring the 4 byte alignment. UNIFONTMETRICS has the following additional fields.

Identity		4 bytes. This must be 0x554E464D ('UNFM'). ulSize			4 byte unsigned integer. The size of the UNIFONTMETRICS structure, in bytes. Note that the size includes the variable length of the FullFamilyname and the FullFacename string. flOptions		4 byte unsigned integer. Option flags. UNIFONTMETRICS_PANOSE_EXIST (bit 0) The panose structure is represented in the Uni font metrics. UNIFONTMETRICS_FULLFAMILYNAME_EXIST (bit 1) The Full familyname string is represented in the Uni font metrics. UNIFONTMETRICS_FULLFACENAME_EXIST (bit 2) The full facename string is represented in the Uni font metrics.

szFullFamilyname[256]	256 byte unsigned character array. The full familyname string of the Uni font resource. szFullFacename[256]		256 byte unsigned character array. The full facename string of the Unifont resource. panose		PANOSE structure. The ten digit PANOSE number with two bytes of padding.

The PANOSE definition consists of ten digits, each of which describes one of up to sixteen variations. The current digits are:

typedef struct _PANOSE { BYTE		bFamilyType; BYTE		bSerifStyle; BYTE		bWeight; BYTE		bProportion; BYTE		bContrast; BYTE		bStrokeVariation; BYTE		bArmStyle; BYTE		bLetterform; BYTE		bMidline; BYTE		bXHeight; BYTE		fbPassedISO; BYTE		fbFailedISO; } PANOSE;

1. Family Kind (bFamilyType - 6 variations) 0   = Any 1   = No Fit 2   = Text and Display 3   = Script 4   = Decorative 5   = Pictorial

2. Serif Style (bSerifStyle - 16 variations) 0   = Any 1   = No Fit 2   = Cove 3   = Obtuse Cove 4   = Square Cove 5   = Obtuse Square Cove 6   = Square 7   = Thin 8   = Bone 9   = Exaggerated 10  = Triangle 11  = Normal Sans 12  = Obtuse Sans 13  = Perp Sans 14  = Flared 15  = Rounded

3. Weight (bWeight - 12 variations) 0   = Any 1   = No Fit 2   = Very Light 3   = Light 4   = Thin 5   = Book 6   = Medium 7   = Demi 8   = Bold 9   = Heavy 10  = Black 11  = Nord

4. Proportion (bProportion - 10 variations) 0   = Any 1   = No Fit 2   = Old Style 3   = Modern 4   = Even Width 5   = Expanded 6   = Condensed 7   = Very Expanded 8   = Very Condensed 9   = Monospaced

5. Contrast (bContrast - 10 variations) 0   = Any 1   = No Fit 2   = None 3   = Very Low 4   = Low 5   = Medium Low 6   = Medium 7   = Medium High 8   = High 9   = Very High

6. Stroke Variation (bStorokeVariation - 9 variations) 0   = Any 1   = No Fit 2   = Gradual/Diagonal 3   = Gradual/Transitional 4   = Gradual/Vertical 5   = Gradual/Horizontal 6   = Rapid/Vertical 7   = Rapid/Horizontal 8   = Instant/Vertical

7. Arm Style (bArmStyle - 12 variations) 0   = Any 1   = No Fit 2   = Straight Arms/Horizontal 3   = Straight Arms/Wedge 4   = Straight Arms/Vertical 5   = Straight Arms/Single Serif 6   = Straight Arms/Double Serif 7   = Non-Straight Arms/Horizontal 8   = Non-Straight Arms/Wedge 9   = Non-Straight Arms/Vertical 10  = Non-Straight Arms/Single Serif 11  = Non-Straight Arms/Double Serif

8. Letterform (bLetterform - 16 variations) 0   = Any 1   = No Fit 2   = Normal/Contact 3   = Normal/Weighted 4   = Normal/Boxed 5   = Normal/Flattened 6   = Normal/Rounded 7   = Normal/Off Center 8   = Normal/Square 9   = Oblique/Contact 10  = Oblique/Weighted 11  = Oblique/Boxed 12  = Oblique/Flattened 13  = Oblique/Rounded 14  = Oblique/Off Center 15  = Oblique/Square

9. Midline (bMidline - 14 variations) 0   = Any 1   = No Fit 2   = Standard/Trimmed 3   = Standard/Pointed 4   = Standard/Serifed 5   = High/Trimmed 6   = High/Pointed 7   = High/Serifed 8   = Constant/Trimmed 9   = Constant/Pointed 10  = Constant/Serifed 11  = Low/Trimmed 12  = Low/Pointed 13  = Low/Serifed

10. X-height (bXHeight - 8 variations) 0   = Any 1   = No Fit 2   = Constant/Small 3   = Constant/Standard 4   = Constant/Large 5   = Ducking/Small 6   = Ducking/Standard 7   = Ducking/Large

11. fbPassedISO Reserved - must be zero

12. fbFailedISO Reserved - must be zero

When using the PANOSE number to match fonts, the ordering of the PANOSE digit is the key to finding the closest match. The most significant digit is the first digit, and the least significant digit is number ten. To find matches, the digits need to be compared, in the order given. A font mapper may want to change the precedence of the digits, to give higher weightings to other font features.

See the definition of IFIMETRICS in the IFI specification for a detailed explanation of the IFIMETRICS fields.

The Font Definition Header

The font definition header contains information about the format of the character definitions, the character group definitions, data about each group, each character including width data and the offset into the definition section at which the character glyph definition begins. This structure defines the format of the character group definition records and the character definition records that follow:

typedef struct _UNIFONTDEFINITIONHEADER {	UCHAR	Identity[4]; ULONG	ulSize; ULONG	flFontDef; ULONG	flGroupDef; ULONG	flCharDef; ULONG	ulCharDefSize; SHORT	xCellWidth; SHORT	yCellHeight; SHORT	xCellIncrement; SHORT	xCellA; SHORT	xCellB; SHORT	xCellC; SHORT	yCellBaseOffset; USHORT	usReserved; GLYPH	giFirstChar; GLYPH	giLastChar; ULONG	ulCharDefNum; } UNIFONTDEFINITIONHEADER;

Identity		4 bytes. Must be equal to 0x554E4648 ('UNFH'). ulSize			4 byte unsigned integer. Size of this structure in bytes. flFontDef 		4 bytes of flags. Indicates which fields are present in the font definition data in the header.

Bit 0	1 = character width is defined in the font definition header (fixed pitch) 0 = character width is not defined in the font definition header

Bit 1	1 = character height is defined in the font definition header (same for all		 characters) 0 = character height is not defined in the font definition header

Bit 2	1 = character increment is defined in the font definition header (same for		 all characters) 0 = character increment is not defined in the font definition header

Bit 3	1 = a_space is defined in the font definition header (same for all		characters) 0 = a_space is not defined in the font definition header (non abc_space		font or defined for each character)

Bit 4	1 = b_space is defined in the font definition header (same for all		characters) 0 = b_space is not defined in the font definition header (non abc_space		font or defined for each character)

Bit 5	1 = c_space is defined in the font definition header (same for all		characters) 0 = c_space is not defined in the font definition header (non abc_space		font or defined for each character)

Bit 6	1 = base offset is defined in the font definition header (same for all		chracters) 0 = base offset is not defined in the font definition header

flGroupDef		4 bytes of flags. Indicates which fields are present on a per character group basis. Each flag is valid only when the correnponding flFontDef flag bit is on (= 1).

Bit 0	1 = character width is defined in the character group definitions (defined		for each character group) 0 = character width is not defined in the character group definition (same		for all characters)

Bit 1	1 = character height is defined in the character group definitions (defined		for each character group) 0 = character height is not defined in the character group definitions (same		for all characters)

Bit 2	1 = character increment is defined in the the character group definitions (defined for each character group) 0 = character increment is not defined in the character group definitions (same for all characters)

Bit 3	1 = a_space is defined in the character group definitions (defined for each		character group) 0 = a_space is not defined in the character group definitions (same for all		characters)

Bit 4	1 = b_space is defined in the character group definitions (defined for each		character group) 0 = b_space is not defined in the character group definitions (same for all		characters)

Bit 5	1 = c_space is defined in the character group definitions (defined for each		character group) 0 = c_space is not defined in the character group definitions (same for all		characters) Bit 6	1 = base offset is defined in the character group definitions (defined for		each character group) 0 = base offset is not defined in the character group definitions (same for		all characters)

flCharDef		4 bytes of flags. Indicates which fields are present on a per character basis.

Bit 0	1 = character width is defined in the character definitions (defined for each		character definition) 0 = character width is not defined in the character definitions

Bit 1	1 = character height is defined in the character definitions (defined for		each character definition) 0 = character height is not defined in the character definitions

Bit 2	1 = character increment is defined in the the character definitions (defined		for each character definition) 0 = character increment is not defined in the character definitions

Bit 3	1 = a_space is defined in the character definitions (defined for each		character definition) 0 = a_space is not defined in the character definitions

Bit 4	1 = b_space is defined in the character definitions (defined for each		character definition) 0 = b_space is not defined in the character definitions

Bit 5	1 = c_space is defined in the character definitions (defined for each		character definition) 0 = c_space is not defined in the character definitions Bit 6	1 = base offset is defined in the character definitions (defined for each		character definition) 0 = base offset is not defined in the character definitions

Bit 7	1 = offset to glyph is defined 0 = offset to glyph is not defined Bit 7 must be ON for OS/2 4.0.

ulCharDefSize		4-byte unsigned integer. Indicates the length in bytes of each character definition record (the per character data). xCellWidth		2-byte signed integer. The width of the characters, in pels for image fonts. yCellHeight		2-byte signed integer. The height of the characters, in pels for image fonts. xCellIncrement	2-byte signed integer. The distance, in pels for image fonts, along with the character baseline required to step from one character to the next (when forming a character string). xCellA			2-byte signed integer. The width of the space before a character in the inline direction (the a_space), in pels for image fonts. xCellB			2-byte signed integer. The width of a character (inline direction), in pels for image fonts. (the b_space). xCellC			2-byte signed integer. The width of the space after a character in the inline direction, in pels for image fonts (the c_space). yCellBaseOffset	2-byte signed integer. The position of the top of a character definition relative to the baseline in the direction perpendicular to the baseline, in pels for image fonts. usReserved		2 byte unsigned integer. Must be ZERO. giFirstChar		4 byte unsigned integer. The index of the first character glyph in the font file. giLastChar		4 byte unsigned integer. The index of the last character glyph in the font file. ulCharDefNum	4 byte unsigned integer. The number of the character definitions in the font file. If all of the characters between the first and the last character are defined, the value in this field will be giLastChar - giFirstChar + 1.

OS/2 4.0 will support only type1, type2 and type3 font as the font defintion header records are defined as follows.

Type 1 - fixed pitch width and height font ulIdentity		= 0x554E4648; ulSIze			= 64; flFontDef		= 0x00000047; flGroupDef		= 0x00000000; flCharDef		= 0x00000081; (width defined for each character for the performance even		 if the font is defined as a fixed pitch width font) ulCharDefSize		= 6; xCellWidth		= Width of the characters yCellHeight		= Height of the characters xCellIncrement	= Width of the characters xCellA			= 0 xCellB			= 0 xCellC			= 0 yCellBaseOffset	= Baseline offset for all characters ulFirstChar		= The glyph index of the first character ulLastChar		= The glyph index of the last character ulCharDefNum	= The number of the character definitions

Type2 - Proportional width and fixed pitch height font ulIdentity		= 0x554E4648; ulSIze			= 64; flFontDef		= 0x00000042; flGroupDef		= 0x00000000; flCharDef		= 0x00000081; ulCharDefSize		= 6; xCellWidth		= 0 yCellHeight		= Height of the characters xCellIncrement	= 0 xCellA			= 0 xCellB			= 0 xCellC			= 0 yCellBaseOffset	= Baseline offset for all characters ulFirstChar		= The glyph index of the first character ulLastChar		= The glyph index of the last character ulCharDefNum	= The number of the character definitions

Type3 - ABC_space width and fixed pitch height font ulIdentity		= 0x554E4648; ulSIze			= 64; flFontDef		= 0x00000042; flGroupDef		= 0x00000000; flCharDef		= 0x000000B9; ulCharDefSize		= 10; xCellWidth		= 0 yCellHeight		= Height of the characters xCellIncrement	= 0 xCellA			= 0 xCellB			= 0 xCellC			= 0 yCellBaseOffset	= Baseline offset for all characters ulFirstChar		= The glyph index of the first character ulLastChar		= The glyph index of the last character ulCharDefNum	= The number of the character definitions

The following is an explanation of a_space, b_space and c_space definition.

1. Proportional characters (a+b+c = character increment) for each character: a,b,c >= 0 2. Characters where a, b, and c are definitions for all characters: b >= 0 a, c any integer

The Font Character Group Definition

The character group definition record is defined to support the font indices of a large character set of which indices may consist of sparse ranges.

typedef struct _UNICHARGROUPDEFINITION {	UCHAR			Identity[4]; ULONG			ulSize; ULONG			ulCharGroups; UNICHARGROUPENTRY	CharGroupEntry[1]; } UNICHARGROUPDEFINITION; Identity		4 bytes. Must be 0x554E4748 ('UNGH'). ulSize			4 byte unsigned integer. Size of this structure, in bytes, which includes all entries of UNICHARGROUPENTRY. (i.e. sizeof(UNICHARGROUPDEFINITION) + sizeof(UNICHARGROUPENTRY) * (ulCharGroups - 1)) ulCharGroups		4 byte unsigned integer. The number of the character groups in the record. CharGroupEntry	ulCharGroups size of array of the UNICHARGROUPENTRY structure.

The format of the UNICHARGROUPENTRY is :

typedef struct _UNICHARGROUPENTRY {	ULONG		flCharGroupEntry; GLYPH		giFirstChar; GLYPH		giLastChar; LONG			offsetCharDef; SHORT		xCellWidth; SHORT		yCellHeight; SHORT		xCellIncrement; SHORT		xCellA; SHORT		xCellB; SHORT		xCellC; SHORT		yCellBaseOffset; USHORT		usReserved; } UNICHARGROUPENTRY;

where: flCharGroupEntry	4 bytes of flags. Indicates which fields are present in the character definition data in the header. If the font file is created for a single repository, UNIFONT_FREQUENT_GROUP (Bit 0) Indicate that this character group may be frequently used. It is recommended that the font subsystem cache the character definitions of this group in memory for the performance when this bit is ON. giFirstChar		4 byte unsigned integer. Indicates the start font index of the character group. giLastChar		4 byte unsigned integer. Indicates the end font index of the character group. offsetCharDef		4 bytes signed integer. The offset from the beginning of the Uni font resource (the beginning of the font signature structure) at which the character definition record of this character group begins. The following field are defined in the UNICHARGROUPENTRY structure, however, the values may or may not be present in them according to the ulGroupDef field in UNIFONTDEFINITIONHEADER. If the values are present, they are applied for only the character group. xCellWidth		2-byte signed integer. The width of the characters in the character group definition in pels. yCellHeight		2-byte signed integer. The height of the characters in the character group definition in pels. xCellIncrement	2-byte signed integer. The length along the character baseline required to step from this character to the next in pels(when forming a character string). xCellA			2-byte signed integer. The width of the space before the character in the inline direction in pels. (a_space) xCellB			2-byte signed integer. The width of the character shape in the inline direction in pels. (b_space) xCellC			2-byte signed integer. The width of the space after the character in the inline direction in pels. (c_space) yCellBaseOffset	2-byte signed integer. The position of the top of the chraacters in the character group definition relative to the baseline in the direction perpendicular to the baseline in pels. usReserved		2-byte unsigned integer. Must be ZERO.

The Kerning Pair Table

This record will exist in a Uni font-file format if the UNIFONT_KERNINGPAIRS_EXIST flag in the flFontSignature field in the UNIFONTSIGNATE structure is on. The kerning pair table record is not present if the cKerningPairs field in the UNIFONTMETRICS structure is zero. This table should be sorted by the first character (usFirstChar) and the second character (usSecondChar) order to allow binary searches.

typedef struct _UNIKERNPAIRTABLE {	UCHAR	Identity[4]; ULONG	ulSize; ULONG	ulKernPairs; KERNINGPAIRS KernPairs[1]; } UNIKERNPAIRTABLE;

where: Identity	4bytes. Must be 0x554E4B54 ('UNKT'). ulSize		4 byte unsigned integer. The size of the stucture in bytes, which includes all entries of KERNINGPAIRS. (i.e. sizeof(UNIKERNINGPAIRTABLE) + sizeof(KERNINGPAIRS) * (ulKernPairs - 1)) ulKernPairs	4 byte unsigned integer. The number of kerning pairs in the record. KernPairs	ulKernPairs size of array of the KERNINGPAIR structure.

typedef struct _KERNINGPAIRS {	ULONG	ulFirstChar; ULONG	ulSecondChar; LONG		lKerningAmount; } KERNINGPAIRS;

where: ulFirstChar		4 byte unsigned integer. First character of the kerning pair. This value must be zero-extended when converted to the GLYPH type. ulSecondChar		4 byte unsigned integer. Second character of the kerning pair. This value must be zero-extended when converted to the GLYPH type. lKerningAmount	4 byte signed integer. Kerning value in pels for image fonts. Positive values increase the inter-character spacing while negative values bring the characters closer together.

The Font Character Definition

Character Definition Record

The following fields may or may not be present, according to the font character definition fields flags. If a field is present, it is present for each character and the value applies to that character only. The fields in the record should be in the order of the following. There are ulCharNumber of the records for image fonts.

Character Glyph Definition Offset (offsetImageData) 4 byte signed integer. The offset from the beginning of the Uni font resource at which the character glyph definition begins. This field should be set to zero if the character glyph is not defined in the font file. If the font subsystem detect the zero value in this field, it should return the character glyph image of giDefaultChar index which is specified in UNIFONTMETRICS. This field must be presented. Character Cell Width (xCellWidth) 2-byte integer. The width of the character definition in pels. Character Cell Height (xCellHeight) 2-byte integer. The height of the character definition in pels. Character Increment (xCellIncrement) 2-byte integer. The length along the character baseline required to step from this character to the next in pels (when forming a character string). Character a-space (xCellA) 2-byte signed integer. The width of the space before the character in the inline direction in pels. Character b-space (xCellB) 2-byte integer. The width of the character shape in the inline direction in pels. Character c-space (xCellC) 2-byte signed integer. The width of the space after the character in the inline direction in pels. Character Baseline Offset (xCellBaseOffset) 2-byte signed integer. The position of the top of a character definition relative to the baseline in the direction perpendicular to the baseline in pels.

The xCellWidth and the xCellIncrement field in the FONTDEFINITIONHEADER structure are nonzero and that represents a fixed pitch width font for the type 1 font. However, the type 1 fonts have offset (offsetImageData) and width (xCellWidth) pairs in the character definition records and the proportional-space flag, bit 0, is set in the fsType field of the UNIFONTMETRICS structure. OS/2 2.1 PM font-file format has the same definition for the type 1 fonts.

Image Data Format

The bits for each character are stored separately, and start on a byte boundary. Sequential bytes represent horizontal pieces of the character image. For example, a 15-bit-wide H is stored as follows:

byte                  byte 0  00000000 0000000-   1 2   01100000 0000110-   3 4   01100000 0000110-   5 6   01100000 0000110-   7 8   01100000 0000110-   9 10  01111111 1111110-  11 12  01111111 1111110-  13 14  01100000 0000110-  15 16  01100000 0000110-  17 18  01100000 0000110-  19 20  01100000 0000110-  21 22  00000000 0000000-  23

The format is the same as the OS/2 bitmap format of one bit per pel.

Graphics Engine New API

GreRealizeString


 * 1) define	INCL_GRE_STRINGS

LONG GreRealizeString (hdc, pGlyph, cChar, pFont, 						ulLen, fl, pInstance, lFunction )

This function processes a character string as if it were being drawn, however, the character glyph bitmap will not be drawn on the target device but placed into the 32 bit font transfer area (FTA) defined as the FOCAFONT32 structure. The graphics engine fills the character glyph bitmaps as many as it can put into FTA designated by pFont. The string will be translated into the font glyph indices by the code page of the currently selected font unless the RS_NO_TRANSLATION or the RS_UNICODE option is specified.

Support: This function is supported by the graphics engine.

Stack Frame:

pGlyph	The code points must be stored in the array of GLYPH (= ULONG) type. Each element will be updated to the indices in FTA by the graphics engine. pFont		Applications should use the sturucture as read-only area. The inside data is managed by the graphics engine. ulLen		The caller needs to allocate enough memory to store the character glyph bitmaps of the string. It is recommended that the caller look into the font metrics of the current selected font or use some of the graphics engine text functions in order to find the suitable size of memory. The size must be at least larger than the size of the FOCAFONT32 structure + the size to store the minimum number of characters. The following is an example how to calculate the minimum required size.

ULONG	ulMinSize; PFONTMETRICS pfm;

cbMaxChar = (pfm->lMaxCharInc + 7 >> 3) * 				pfm->lMaxBaselineExt; ulMinSize = SIZE_FTA_CONTROL + (cbMaxChar + 				SIZE_FTA_CELL) * 10;

fl		Valid flags are: RS_NO_TRANSLATION	No translation from code points to glyph indices will be performed. The font glyph indices are passed. RS_UNICODE		Code points are Unicode. RS_FONT_CACHE		The character glyph bitmap will be stored in the graphics engine global font cache. The caller needs to grab the graphics engine font cache semaphore while accessing the FOCAFONT32 structure returned. RS_CREATE_FTA		The graphics engine will initialize and set up the font cache in the FTA pointed by pFont. RS_DESTROY_FTA	The graphics engine will free all allocated resources for the FTA. RS_PUT_GLYPHS		The graphics engine will validate the FTA font cache so that contained the requested character glyph images. RS_DELETE_GLYPHS	The graphics engine will delete the requested character glyph images from the FTA font cache.

Applications can calculate the number of cached characters by :

pFont->fmMetrics.usLastChar - pFont->fmMetrics.usFirstChar + 1 Angle, Shear, Italic and Bold character attributes are not support.

Return Codes:

This function returns the number of character which are stored in the FTA, or GPI_ALT_ERROR if an error occurs.

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_OR_IMCOMPAT_OPTIONS

GreQueryCharOutline


 * 1) define	INCL_GRE_STRINGS

LONG GreQueryCharOutline( hdc, ulCode, pOutline, ulLen,						fl, pInstance, lFunction )

This functions returns outline data information of the specified character glyph.

Support:

This function is supported by the graphics engine.

Stack Frame:

pOutline	The following graphics orders are possible to be returned as the character glyph outline data. (fl & QCO_GOCA_FORMAT) == TRUE Line at given position (GLINE) Line at current position (GCLINE) Bezier curve at given position (GBEZ) Bezier curve at current position (GCBEZ) No operation (GNOP1) End of symbol definition (GESD)

GLENGTH (1 byte)

GPOINT (4 byte) GSHORT(2 byte) x	GSHORT(2 byte) y

See the Graphics Orders section in OS/2 Graphics Programming Interface Programming Reference for more details.

(fl & QCO_IFI_FORMAT) == TRUE The outline is provided as a list of line, polygons and splines in the given buffer. The polygons are made up of primitives whose vertices are given relative to the character origin. A polygon is a self describing record with a header POLYGONHEADER containing the following fields.

typedef struct _POLYGONHEADER { ULONG cb; ULONG iType;	// Must be FD_POLYGON_TYPE } POLYGONHEADER; cb		The size of this particular polygon record in bytes. This is used to determine how many primitives make up the polygon. All fields of the header and the following primitives are included in this size. iType		This must be FD_POLYGON_TYPE to identify this as a POLYGON record.

The POLYGONHEADER is followed by a list of polygon primitive records. There are two types of primitives allowed, lines and cubic splines. Line primitives are defined as follows:

typedef struct _PRIMLINE /* lnp */ {    ULONG	  iType;	// Must be PRIM_LINE. POINTFX pte;	// Starting vertex of line. } PRIMLINE; Likewise, spline primitives are defined as:

typedef struct _PRIMSPLINE /* splnp */ ULONG	 iType;	// Must be PRIM_SPLINE. POINTFX pte[3];	// Starting vertex of spline, // control points. } PRIMSPLINE;

For both primitive types, the ending vertex is omitted. It can be found as the starting vertex of the following primitive. The ending vertex of the last primitive can be found as the starting vertex of the first primitive. I.e. every polygon record describes a closed figure. All points in the polygon are relative to the character origin in the requested coordinates. Any number of POLYGON records may be put in the buffer, one for each disconnected section of the character outline.

ulLen		The number in bytes which is required to store the character glyph outline data. If ZERO is specified, only the number of bytes will be returned. fl		Valid flags are: QCO_FORMAT_GOCA	The format of outline data to be returned is the GOCA format QCO_FORMAT_IFI	The format outline data to be returned is the IFI format. QCO_NO_TRANSFORM	The coordinates of the character outline data will be returned in the font design space (notional coordinates). QCO_UNICODE		Code point is Unicode.

Return Codes:

This function returns the number of bytes which needs to be stored the character glyph outline data, or GPI_ALT_ERROR if an error occurs.

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INSUFFICIENT_MEMORY PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_FIRST_CHAR PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE PMERR_INV_OR_IMCOMPAT_OPTIONS

GreQueryCharMetricsTable


 * 1) define	INCL_GRE_STRINGS

BOOL GreQueryCharMetricsTable( hdc, lFirstChar, 					cCharMetrics, paCharMetrics,						cCharMetricsLen, fl, pInstance, 					lFunction )

This function stores, at the location addressed by paCharMetrics, an array of world coordinates representing the character metrics table information of the currently selected font.

Support:

This function is supported by the graphics engine.

Stack Frame:

paCharMetrics		This is a pointer to an array of up to cChars character metrics records, each of which contains a maximum of cCharMetrics bytes.

typedef struct _CHARMETRICS { LONG		lA; ULONG		ulB; LONG		lC; RECTL		rclBoundBox; } CHARMETRICS;

lA		Character a_space ulB		Character b_space lC		Character c_space rclBoundBox	Character boundary box. All points in the coundary box are relative to the character origin in the requested coordinates.

fl		Option flags. QCMT_NO_TRANSFORM	The abc space and the boundary box will be returned in the font design space (notional coordinates)

Return Codes:

On completion, BOOLEAN will be returned. TRUE		Successful FALSE	Error

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INSUFFICIENT_MEMORY PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_FIRST_CHAR PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE PMERR_INV_OR_IMCOMPAT_OPTIONS

GreQueryCodePageObject


 * 1) define	INCL_GRE_FONTS

PCODEPAGEOBJECT GreQueryCodePageObject ( hdc,							ulCodePage, szGlyphlist,							pInstance, lFunction )

This function returns a pointer to a CODEPAGEOBJECT structure in which contains the code point to the glyph mapping attributes and services.

Support:

This function is supported by the graphics engine.

Stack Frame:

Return Codes:

This function returns a pointer to the code page object structure, or GPI_ERROR if an error occurs. The following is the code page object definition.

// Code page object structure definition

typedef struct _CODEPAGEOBJECT { UCHAR		Identity; ULONG		ulCodePage; UCHAR		glyphlist[16]; ULONG		fl; PUSHORT		pCpXlate; PUCHAR		pDbcsEnv; ULONG		ulReserved; CPOMEMBERS	mem; } CODEPAGEOBJECT; typedef CODEPAGEOBJECT *PCODEPAGEOBJECT;

Identity	Indentifier. ('CPOB'). ulCodePage	Code Page number of the code page object. szGlyphlist	Glyphlist name of the code page object. fl		Flags. CPO_SBCS_CODEPAGE	The code page is SBCS. CPO_MBCS_CODEPAGE	The code page is MBCS. CPO_DBCS_CODEPAGE	The code page is DBCS. CPO_TABLE_XLATION	The translation will be done by mapping by  pCpXlate. CPO_NO_TRANSLATION	No translation will be performed. (Passthru) pCpXlate	The code point to the glyph index mapping vector. This field is only represented for the code pages that can be supported by the "PM383" glyphlist, otherwise NULL. pDbcsEnv	DBCS environment vector. This field is only represented for MBCS code pages, otherwise NULL. ulReserved	Reserved - 0. mem		Code page object member functions. (See CPOMEMBERS)

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_INSUFFICIENT_MEMORY PMERR_INV_CODEPAGE

// Member function structure definition

typedef struct _CPOMEMBERS { PXLATECHAR			pfnXlateChar; PXLATESTRING		pfnXlateString; PINVXLATECHAR		pfnInvXlateChar; PINVXLATESTRING		pfnInvXlateString; } CPOMEMBERS;

typedef CPOMEMBERS *PCPOMEMBERS;

pfnXlateChar		Pointer to the function to translate a code point to a glyph index

typedef ULONG (* APIENTRY PXLATECHAR)(PVOID pCpObj,		     			ULONG ulCod, PGLYPH pgGly);

pfnXlateString		Pointer to the function to translate code point strings to an array of glyph index

typedef ULONG (* APIENTRY PXLATESTRING)(PVOID pCpObj,                              PUCHAR pchCod, ULONG  ulCodLen,                              PGLYPH pgGly, PULONG pulGlyLen,                              ULONG flOptions);

pfnInvXlateChar	Pointer to the function to translate a glyph index to a code point

typedef ULONG (* APIENTRY PINVXLATECHAR)(PVOID pCpObj,                              GLYPH gGly, PULONG pulCod);

pfnInvXlateString	Pointer to the function to translate an array of the glyph index to an array of code point.

typedef ULONG (* APIENTRY PINVXLATESTRING)(PVOID  pCpObj,                              PGLYPH pgGly, ULONG ulGlyLen,                              PUCHAR pchCod, PULONG pulCodLen,                              ULONG  flOptions);

FONTS

Generic Font

OS/2 supports generic fonts which can be used for all installed presentation device drivers and which can support the character glyphs for all supported countries (will use "I18N character glyph" terminology from now on). In this sense, OS/2 can display and print I18N character glyphs even if no font is provided by presentation device drivers. The generic font can be either an image or an outline form. The outline font technology supported depends on the Intelligent Font Driver Interface (IFI) font drivers that are installed on OS/2.

The following font format will be supported by OS/2. OS/2 2.1 PM font-file format (image/outline) IBM Uni font-file format Adobe type-1 font-file format Adobe composite font-file format (called NCF format - CMap and CIDFont) IBM Combined font-file format Truetype

OS/2 2.1 supports only the character glyphs which are defined in the "PM383" glyphlist at present, however, OS/2 4.0 will support eight more glyphlists, "PMJPN", "PMKOR", "PMTWN", "PMPRC", "PMBG5", "PMKS",  "SYMBOL" and "UNICODE" in order for the graphics engine  support new country and new language fonts, and the PM383 glyphlist will be extended to 504 glyphs. OS/2 PM font-file format and Adobe type-1 font format cannot support large character set fonts, such as DBCS and Unicode font. Large character set fonts must be provided either in Adobe composite font format, Truetype font format (No plan at this moment), Combined font-file format or the IBM Uni font-file format which will be supported by the raster IFI font driver.

Glyphlist

Every physical font is associate with a glyphlist name. The glyphlist name is the name that identifies a set of character glyph names and font index sequence of the character glyph set. The graphics engine decides translation from code point to font index (glyph index) by using the glyphlist name. The following glyphlists will be supported by the OS/2 graphics engine.

"PM383" The glyph index which is currently supported by OS/2 2.1. 383 character glyphs are defined in this glyphlist. "UNICODE" This glyphlist consists of the Unicode specification adopted by the International Organization for Standardization (ISO) as ISO 10646. "SYMBOL" or "" This is a font specific encoding which is usually used to define a symbol character set. "PMJPN" This is a "PM383" extension for the Japanese language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 932 character glyphs. This glyphlist will be supported for the migration of existing font files. "PMCHT" This is a "PM383" extension for the Traditional Chinese language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 938 character glyphs. This glyphlist will be supported for the migration of existing font files. "PMKOR" This is a "PM383" extension for the Korean language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 934 character glyphs. This glyphlist will be supported for the migration of existing font files. "PMPRC" This is a "PM383" extension for the Simplified Chinese language. The content of this glyphlist is "PM383" set + DBCS part (ideograph) of the code page 936 character glyphs. This glyphlist will be supported for the migration of existing font files.

To simplify the graphics engine design and implementation, we may prefer to have it support only the "UNICODE" glyphlist. However, this may decrease the performance of font drawing since the index translation from code page string to Unicode and Unicode to font indices occurs quite often, while most of the current applications and fonts are based on code page, not Unicode. The glyphlists of "PM383", "PMJPN", "PMCHT", "PMKOR" and "PMPRC" will be useful to support code page based applications and fonts without the performance degradation of index translation cost.

Graphics engine font

The graphics engine reads and parses the following font format directly.

OS/2 PM font-file format

This is the OS/2 2.1 PM font-file format designed for small character sets and is supported. "PM383" and "SYMBOL" glyphlists can be supported this format. See the OS/2 Technical Library Presentation Manager Programming Reference Volume III for more details.

IBM Combined font-file format

This a new format being supported by OS/2. The "UNICODE" glyphlist can be supported this format. The detailed format will be discussed in a later section.

ATM IFI font driver font

The ATM IFI font driver supports the following font file format.

Adobe Type1 font format

This is the Adobe Type 1 font file format designed for small character set fonts. "PM383", "SYMBOL" and "UNICODE" glyphlists can be supported by this format. See the Adobe Type 1 Font Format version 1.1 for details. The OFM (Object Font Metrics) file format will be enhanced in order to support the "UNICODE" glyphlist.

Adobe NCF font format

This is the Adobe new composite font format designed for small and large character set fonts. The "PM383", "SYMBOL", "UNICODE", "PMJPN", "PMKOR", "PMCHT" and "PMPRC" glyphlists can be supported by this format. See "Adobe CMap and CIDFont Files Specification" for NCF font format details.

Raster IFI font driver font

The Raster IFI font driver supports the following font file format. IBM Uni font-file format

This format is an extension of the OS/2 PM font-file format for large character set. The format will be discussed in a later section. The "PM383", "SYMBOL", "PMJPN", "PMCHT", "PMKOR" ,"PMPRC" and "UNICODE" glyphlists will be supported by this format.

Truetype IFI font driver font

The Truetype IFI font driver supports the following font file format.

Truetype font format

A Truetype IFI font driver was developed in order to support Truetype fonts which are widely available in the market.

Font Cache

The graphics engine implements character glyph (bitmap) caching for IFI font driver fonts. Total cache buffer limit or the number of cacheable typeface/size(s) will be customized for user through a Workplace Shell system setting object on OS/2. (Not implemented.) It is important that the caching is designed to work for large character set fonts with reasonable performance (hit ratio point of view). The following points have been considered for handling multiple large character set font for the caching. High hit ratio for the given buffer size. Linear search is prohibited. Fragmentation - glyphs have different sizes. A new font bitmap caching method will be used to support both small and large character set fonts. A prototype cache code is already used in OS/2 2.1 graphics engine for DBCS IFI font bitmap caching.

Intelligent Font Interface

The OS/2 graphics engine enhances the Intelligent Font Interface (IFI) in order to support raster IFI font drivers, additional glyphlists etc. This IFI driver version will be defined as IFI version 2.1.

Font Objects

Current Model

The following figure shows the architecture for font support in OS/2 2.1. The PMWIN component has a number of mapping tables from a set of supported codepages to a format called UGL PM383. This is the same encoding used for the system bitmap fonts. For ATM outline fonts, the graphics engine's implementation of the ATM driver has a converter which maps ATM character names to the same UGL PM383 table. Therefore, all font manipulation is done through this internal encoding of characters. In the Asian versions of OS/2 we supply alternative mapping tables for the extended Asian character sets and use a different UGLs: PMJPN, PMKOR and PMCHT for Japan, Korea and Taiwan respectively. We also supply different system fonts which match these encodings.

The New Model

As we enter new markets with new character set requirements or attempt to support multilingual text we are faced with the problem of building new UGLs or hacking an existing one. An alternative approach is to design support for font objects which maintain the information about the character sets they support. Each font object will have an associated DLL which maps from the ASCII or Unicode character encodings to the character glyph definitions supplied by the font. In other words we remove the notion of the system maintaining a single list of supported characters (the UGL).

The advantages of this are: We isolate the dependencies of the GRE on Font encodings. We can easily add new character sets through new fonts. We can support multilingual text through the Unicode mapping support.

The new model is shown in the following figure. The font header identifies the glyphlist associated with the font. This could be PM383, Unicode, PMJPN or some other name. Current bitmap fonts have no header and will be assumed to be PM383 bitmap fonts. The GRE will use a table to asscoiate the font with a DLL. The default behavior will find the DLL based on the glyphlist name. This DLL supports three functions: Install, CodePointToGlyph and UnicodeToGlyph. The later map from either an ASCII codepoint to a 16bit glyph index representing the appropriate character.

The font glyph index is used to query the intelligent font interface (IFI) driver of the font to retrieve the rasterized character bitmap. The install function sets up the mapping tables needed for the conversions and establishes some of the font caching characteristics. Some of the values established at this point are: the number of glyphs in the font, the lowest value of the font index, the highest font index value and a set of index ranges which contain the entire set of glyphs in the font. The graphics engine deals with two kinds of fonts: engine fonts and IFI fonts. An engine font is a bitmap font with a defined structure. The engine fonts used today support only the characters in PM 383. Their layout is shown above. A table of 383 entries is built with a width entry (the size of the character) and an offset into a 64k heap pointing to the character bitmap definition. This table is part of the public interface to the graphics engine and is used by graphics device drivers. An IFI font is a font, outline or bitmap, accessed through a special interface called an IFI driver. The IFI driver accepts 16bit glyph index and returns a rasterized image. For each IFI font loaded, the graphis engine creates a fake representation of an engine font. As characters are rasterized, the entries in the header table are filled in. Thus the display devices are not aware of the differences between engine fonts and IFI fonts. This mechanism is also a simple cache mechanism for small fonts. Large fonts use a secondary cache to store the rasterized bitmaps. Just before the display device is called to render the characters, the bitmaps are copied to the fake engine font format. In this way, the display devices are also unaware of the difference between small or large fonts. However, this comes at a cost of performance for large fonts. Copying the bitmaps is a wasteful operation. We will call the engine font supplied to the display device the Font Transfer Area (FTA). This will be used for the existing support of PM display drivers. A different interface will be used for future support which removes the need to copy bitmaps.

The Algorithm

There are two cases to account for: Unicode encoded text and ASCII encoded text. Unicode or ASCII text is passed to the GRE to be rendered in a presentation space (PS). Identify the current logical font for the PS. If ASCII text is passed get the current PS codepage. Call the font's UnicodeToGlyph or CodePointToGlyph function which returns a font index, for each character in the string. Either the native glyphlist of the font object is Unicode => Noop or the font object converts from Unicode to the native encoding (e.g. PM 383) Look in the font cache for the bitmap If it is an engine font then the bitmap will always be there. It it is an IFI font, the bitmap may not yet be available. If the bitmap is not available, ask the font IFI driver for the glyph. Place it in the cache. Copy the bitmaps to the Font Transfer Area (FTA), if required. This is not required if the font caching mechanism uses the FTA directly (small ATM fonts). Call the graphics driver for the PS to render the bitmaps This algorithm, together with the font objects, will extensibly support multiple glyphlists and Unicode in an efficient manner. Even though the design supports multilingual text and large fonts, an application  using ASCII text and an exisiting PM383 font will not pay any penalty in performance.

Combined Font

The Goals of OS/2 I18N font support are : Font support for drawing Unicode encoded text data. Add-on font installation for newly supporting languages.

The first goal is for OS/2 Unicode support. OS/2 needs to provide a way to support Unicode encoded text, using existing font files. The second goal is to add new languages easily. This addresses the problem of the 383 limitation of OS/2 2.1 PM Universal Glyph List (UGL), which makes it difficult to support new languages and countries. OS/2 is designed to allow new countries to be supported easily. OS/2 proposes a "Combined Font" font architecture to achieve the above goal. The following section describes the combined font proposed design. This section shows the combined font design concept and how to implement the combined font in the graphics engine.

Combined Font - A graphics engine generic font that is dynamically created by combining several physical fonts. Application can select and use the font in the same way as the physical fonts.

Physical Font Entry

A physical font entry is a graphics engine heap representation for a graphics engine generic font. This contains font metrics, glyphlist name, use count and pointers or a cache keys to retrieve character glyph data and character attributes, such as character width or abc space. A physical font entry will be created when a new font, which is not an IBM combined font, is installed through the GreLoadFont function, and will be destroyed when it is unloaded through the GreUnloadFont function. There are two places to store the physical font entries in the graphics engine heap area. One is in a global shared heap which can be accessed by all processes, the other is in an instance heap which can be accessed by only one process. The physical font entries for public fonts are placed in the global shared heap, and the ones for private fonts are placed in the instance shared heap. The physical font entry will be designed to allow large character set encoding such as Unicode. An encoding table that consists of a set of ranges will be included in the physical font entry. Each range will point to an index of character glyph, which will be the starting index of the range.

Combined Font Entry

The combined font entry is a binary representation of IBM Combined font-file format which is located in the graphics engine heap. The combined font entry includes font metrics for the combined font, an array of component font entries, use count and a priority list of component fonts. The component fonts must be public fonts. The priority list of component fonts will be used to choose a component font from the "UNICODE" glyph index that is translated from the text string. Note that the only supported glyphlist for combine font is "UNICODE". Component fonts may have different glyphlists. In this case, the graphics engine will do the necessary conversion from Unicode indices to indices of the appropriate glyphlist, in order to retrieve character glyph from the component font. Since the combined font points to physical font entries in the graphics engine heap, the graphics engine must assure that all  component fonts are usable for the combined font. Therefore, the physical fonts installed to OS/2 as public fonts must be loaded prior to loading the combined font. It is allowed to combine either raster fonts or outline fonts into a combined font. A raster font and an outline font cannot be combined into the same combined font. A combined font entry will be created when an IBM combined font is installed through the GreLoadFont function, and will be destroyed when it is unloaded through the GreUnloadFont function.

IBM Combined Font-File Format

The font-file format for combined font will be defined and documented. The above figure shows an overall idea how the format is organized.

IBM Combined Font-File Creation Tool

A font creation tool for IBM combined font will be provided with so that users or national language feature developers can create an IBM combined font easily OS/2. (A proposal of the user interface for the font creation tool is written in the "User Interface for Combined Fonts section" in the OS/2 2.X NLF design workbook. See it for more details.)

Glyph Index Translation

When an application draws a text string, the graphics engine parses the text string using a code page associated with the device context of the target device and translate into font indices for the physical font. (called glyph index translation). The physical font images are extracted from the graphics engine supported font files (OS/2 PM font-file format and IBM Combined font-file format) or IFI font drivers. They are maintained in the graphics engine heap. The glyph index translation will be performed by using ICONV functions which are being supported as a part of OS/2 I18N subsystem. It is necessary that the ICONV functions can support the translation from code points of all code pages to the supported glyphlist indices.

Generic Font

The glyph index translation and the preparation of character glyph bitmaps will be performed by the graphics engine. The graphics engine will call the device driver (using DDI entries) in order to draw the character glyphs on the target devices. For generic fonts, there will be no change required for OS/2 2.X device drivers that will be ported to OS/2.

Device Specific Font

A presentation device driver can provide device specific fonts for the built-in fonts in the hardware such as a printer or a display adapter card. For the device specific fonts, the responsibility of the glyph index translation resides at the device driver. Device drivers must recognize which code page is associated with the text string and do the proper conversion to the font indices of the device specific font.

Unicode with device specific font

Presentation device drivers will inform to the graphics engine whether it can translate Unicode string to font indices of the device specific font or not. This will be done by turning the CAPS_ADDTIONAL_GRAPHICS Unicode flag field on for the GreQueryDeviceCaps DDI function (The default is to turn the flag off). The graphics engine passes the Unicode text string on to the presentation device driver if the presentation device driver declares the Unicode glyph index translation support, otherwise, the Unicode text string will be translated in the indices of PM383 (the default behavior the for non Unicode device specific font to handle the Unicode text string at most). There is no way that the graphics engine takes over the glyph index translation from Unicode to the font indices of the device specific font when the presentation device driver does not support the glyph index translation for Unicode.

Combined Font

There are two passes in the process of the glyph index translation of a combined font. The first pass is to translate from code points to indices of the "UNICODE" glyphlist. The second pass is to translate the indices of the "UNICODE" glyphlist to the indices of the component font glyphlist. If the component font glyphlist is the "UNICODE" glyphlist, no translation will be performed in the second pass. The indices returned from the second pass will be used to extract font images and attributes from the component font file.

GreQueryCodePageVector

GreQueryCodePageVector is an API that is already supported by OS/2 2.X graphics engine and is being used by presentation device drivers. The graphics engine will provide the same interface and the same result as OS/2 2.X in order that existing presentation device drivers that will be ported to OS/2 will work properly.

Vertical Drawing

In Asian countries such as Japan, traditional drawing direction is top to bottom. Newspapers are still written in top to bottom format today. Besides, IBM Font Object Content Architecture (FOCA) has provision for fonts used in vertical drawing. According to FOCA, the fonts for vertical drawing should have the following characteristic in the font metrics:

Inline Direction 		= 90 degree Character Rotation 		= 270 degree

The graphics engine should utilize these parameters in its drawing. Currently, an application can use GpiSetCharAngle to change the inline direction, however, there is not interface or mechanism which can be used to take the character rotation in account. The graphics engine needs to multiply another matrix which is the required rotation and retrieved the character rotation in the font metrics, right before the shear matrix. The Uni Font-file format

The Uni Font-file format is designed for image fonts which has large character set in the font file such as the DBCS (Double Byte Character Set) and the UNICODE encoding. The Uni Font-file format is a super set format of the OS/2 2.1 PM Font-file format. The Uni Font-file consists of a Uni font directory and several Uni font resources which are included in the font file. The font directory and the font resource are a set of self-defining records of the form:

typedef struct _RECORD {	UCHAR  Identity[4]; 	/* structure identity code */ ULONG  ulSize;   		/* structure size in bytes */ .                    			/* data */ .	. } RECORD;

The notation of bit order defined in this document is that bit 0 is LSB. The elements in the stuructures defined in this document must be aligned in 1 byte boundaries. OS/2 4.0 will support only image fonts for the Uni font-file format.

The Uni Font Directory

This section describes the directory section of a Uni font resource. A Uni font directory contains a directory consisting of a set of structures. Each structure contains the flags, the offset to a Uni font resource, the index to a base Uni font resource if the font is a virtual font. Several Uni font resources can be contained in a Uni font-file by specifying them in the FontResEntry array in the UNIFONTDIRECTORY structure. All values in the UNIFONTDIRECTORY structure is stored in the little endian format. The format of the font directory is:

typedef struct _UNIFONTDIRECTORY {	ULONG		Identity[4]; ULONG		ulSize; ULONG		ulUniFontResources; ULONG		flEndian; ULONG		flFileMode; UNIFONTRESOURCEENTRY FontResEntry[1]; } UNIFONTDIRECTORY;

where: Identity		4 byte. Must be 0x554E4644 ('UNFD') ulSize			4 byte unsigned integer. The size of the structure, in bytes, which includes all entries of UNIFONTRESOURCEENTRY. (i.e. sizeof(UNIFONTDIRECTORY) + sizeof(UNIFONTRESOURCEENTRY) * (ulUniFontResources - 1)) ulUniFontResources	4 byte unsigned integer. The number of the Uni font resources in the Uni font file. flEndian		4 bytes of flags to specify the byte order and the bit order of the font file. UNIFONT_ENDIAN_BYTEOREDER (bit 0)	Must be ZERO. UNIFONT_ENDIAN_BITORDER (bit 1)		Must be ZERO. Other bits must be ZERO. flFileMode		4 byte of flags to specify file mode. UNIFONT_WRITABLE (bit 1)	This flag is on if the font file is designated to be updated, such as the user defined font. FontResEntry		ulUniFontResources size of array of the UNIFONTRESOURCEENTRY structure.

The format of the Uni font resource entry is

typedef struct _UNIFONTRESOURCEENTRY {	ULONG		flUniFont; LONG			offsetUniFont; ULONG		ulBaseUniFont; } UNIFONTRESOURCEENTRY;

where: flUniFont		4 bytes of flags. UNIFONT_VIRTUAL_FONT (bit 0) 	This flag is on if the font is a virtual font. The font character group definition and the font character definitions are not included in the font resource. The virtual font consists of only the font signature, the font metrics, the font end signature and the font definition header. Other bits must be ZERO. offsetUniFont		4 byte signed integer. The offset from the beginning of the file at which the Uni font resource begins. ulBaseUniFont	4 bytes unsigned integer. The index in the FontResEntry array in UNIFONTDIRECTORY which specifies the base Uni font resource used by the virtual font. This field will be specified only when the font is defined as a virtual font.

The Uni Font Resource

The Uni font resource format consists of two sections. The first section contains the general attributes of the Uni font resource and describes features such as its typeface, style and nominal size. The second section contains the actual definitions of the characters belonging to the Uni font resource. There are four to six records in a Uni font resource in a Uni font file between the font signature and the font end resource:

The font signature (UNIFONTSIGNATURE) The font metrics (UNIFONTMETRICS) The font definition header (UNIFONTDEFINITIONHEADER) The font character group definitions (UNICHARGROUPDEFINITION) The pair kerning table. (Option) (UNIKERNPAIRTABLE) The font character definitions The font end signature (UNIENDFONTRESOURCE)

The records in the Uni font resource must be in the order defined above. Earlier records have lower numbers in the identity field. The font character definition of the image format is only supported.

The next figure shows an example of a Uni font resource which has N character group definitions.

The Font Signature

A Uni font resource starts with a special font-signature structure and ends with an ending structure. The font signature has the form:

typedef struct _UNIFONTSIGNATURE {	UCHAR	Identity[4]; ULONG	ulSize; UCHAR	szSignature [24]; UCHAR	szTechnology[64]; LONG		offsetCompressTable; ULONG	flFontResource; } UNIFONTSIGNATURE;

where: Identity		4 bytes. Must be 0x554E4653 ('UNFS'). ulSize			4 byte unsigned integer. The size of the structure, in bytes. szSignature		A NULL terminated string. Must be "UNI FONT". The future enhancement of the Uni font-file format may have a different signature in this field. szTechnology		A NULL terminated string which represents the compress technology of the character glyph images. If the charcater glyph images are not compressed, the NULL string "" must be placed. This field must be NULL string for WPOS and OS/2 2.2. This field is reserved for the future compressed font support. offsetCompressTable	4 byte signed integer. The offset from the beginning of the file at which the compress table begins. This field will be used only if the compress technology name is specifed in the szTechnology field. This field must be ZERO and reserve for the future compressed font support. flFontResource	4 Bytes of flags. UNIFONT_KERNINGPAIRS_EXIST (bit 0) 	Indicates that the font has the kerning pairs table UNIFONT_PANOSE_EXIST (bit 1)		Indicates that the font has PANOSE description Other bits must be ZERO.

The Font End Signature

The font end structure has the form:

typedef struct _UNIENDFONTRESOURCE {	UCHAR	Identity[4]; ULONG	ulSize; } UNIENDFONTRESOURCE;

where: ulIdentity	4 bytes. Must be 0x554E4645 ('UNFE'). ulSize		4 byte unsigned integer. The size of the structure, in bytes.

The Font Metrics

This section gives an explanation of how to set the fields of the UNIFONTMETRICS structure which contains the physical font metrics used when creating fonts.

/* #defines for fsType in IFIMETRICS */


 * 1) define IFIMETRICS32_FIXED      0x0001
 * 2) define IFIMETRICS32_LICENSED   0x0002
 * 3) define IFIMETRICS32_KERNING    0x0004
 * 4) define IFIMETRICS32_DBCS       0x0010
 * 5) define IFIMETRICS32_MBCS       0x0018
 * 6) define IFIMETRICS32_UNICODE	  0x0020
 * 7) define IFIMETRICS32_FACETRUNC  0x1000
 * 8) define IFIMETRICS32_FAMTRUNC   0x2000
 * 9) define IFIMETRICS32_NO_CACHE	  0x4000

/* #defines for fsDefn in IFIMETRICS */


 * 1) define IFIMETRICS_OUTLINE      0x0001
 * 2) define IFIMETRICS32_UDC	  0x0002
 * 3) define IFIMETRICS32_ANTI_ALIAS 0x0004

/* #defines for fsSelection in IFIMETRICS */


 * 1) define IFIMETRICS32_ITALIC     0x8000
 * 2) define IFIMETRICS32_UNDERSCORE 0x4000
 * 3) define IFIMETRICS32_OVERSTRUCK 0x2000
 * 4) define IFIMETRICS32_NEGATIVE   0x1000
 * 5) define IFIMETRICS32_HOLLOW     0x0800

typedef struct _IFIMETRICS32 {  UCHAR   szFamilyname[32]; UCHAR  szFacename[32]; UCHAR  szGlyphlistName[16]; ULONG  idRegistry; LONG   lCapEmHeight; LONG   lXHeight; LONG   lMaxAscender; LONG   lMaxDescender; LONG   lLowerCaseAscent; LONG   lLowerCaseDescent; LONG   lInternalLeading; LONG   lExternalLeading; LONG   lAveCharWidth; LONG   lMaxCharInc; LONG   lEmInc; LONG   lMaxBaselineExt; FIXED  fxCharSlope; FIXED  fxInlineDir; FIXED  fxCharRot; ULONG  ulWeightClass; ULONG  ulWidthClass; LONG   lEmSquareSizeX; LONG   lEmSquareSizeY; GLYPH  giFirstChar; GLYPH  giLastChar; GLYPH  giDefaultChar; GLYPH  giBreakChar; ULONG  ulNominalPointSize; ULONG  ulMinimumPointSize; ULONG  ulMaximumPointSize; ULONG  flType; ULONG  flDefn; ULONG  flSelection; ULONG  flCapabilities; LONG   lSubscriptXSize; LONG   lSubscriptYSize; LONG   lSubscriptXOffset; LONG   lSubscriptYOffset; LONG   lSuperscriptXSize; LONG   lSuperscriptYSize; LONG   lSuperscriptXOffset; LONG   lSuperscriptYOffset; LONG   lUnderscoreSize; LONG   lUnderscorePosition; LONG   lStrikeoutSize; LONG   lStrikeoutPosition; ULONG  ulKerningPairs; ULONG  ulFontClass; } IFIMETRICS32; typedef IFIMETRICS32 *PIFIMETRICS32;

typedef struct _UNIFONTMETRICS {	UCHAR		Identity[4]; ULONG		ulSize; IFIMETRICS32	ifiMetrics; ULONG		flOptions; PANOSE		panose; UCHAR		szFullFamilyname[256]; UCHAR		szFullFacename[256]; } UNIFONTMETRICS; typedef UNIFONTMETRICS *PUNIFONTMETRICS;

UNIFONTMETRICS is an extension of IFIMETRICS32 which is redefined for the 32 bit environment by assuring the 4 byte alignment. UNIFONTMETRICS has the following additional fields.

Identity		4 bytes. This must be 0x554E464D ('UNFM'). ulSize			4 byte unsigned integer. The size of the UNIFONTMETRICS structure, in bytes. Note that the size includes the variable length of the FullFamilyname and the FullFacename string. flOptions		4 byte unsigned integer. Option flags. UNIFONTMETRICS_PANOSE_EXIST (bit 0) The panose structure is represented in the Uni font metrics. UNIFONTMETRICS_FULLFAMILYNAME_EXIST (bit 1) The Full familyname string is represented in the Uni font metrics. UNIFONTMETRICS_FULLFACENAME_EXIST (bit 2) The full facename string is represented in the Uni font metrics.

szFullFamilyname[256]	256 byte unsigned character array. The full familyname string of the Uni font resource. szFullFacename[256]		256 byte unsigned character array. The full facename string of the Unifont resource. panose		PANOSE structure. The ten digit PANOSE number with two bytes of padding.

The PANOSE definition consists of ten digits, each of which describes one of up to sixteen variations. The current digits are:

typedef struct _PANOSE { BYTE		bFamilyType; BYTE		bSerifStyle; BYTE		bWeight; BYTE		bProportion; BYTE		bContrast; BYTE		bStrokeVariation; BYTE		bArmStyle; BYTE		bLetterform; BYTE		bMidline; BYTE		bXHeight; BYTE		fbPassedISO; BYTE		fbFailedISO; } PANOSE;

1. Family Kind (bFamilyType - 6 variations) 0   = Any 1   = No Fit 2   = Text and Display 3   = Script 4   = Decorative 5   = Pictorial

2. Serif Style (bSerifStyle - 16 variations) 0   = Any 1   = No Fit 2   = Cove 3   = Obtuse Cove 4   = Square Cove 5   = Obtuse Square Cove 6   = Square 7   = Thin 8   = Bone 9   = Exaggerated 10  = Triangle 11  = Normal Sans 12  = Obtuse Sans 13  = Perp Sans 14  = Flared 15  = Rounded

3. Weight (bWeight - 12 variations) 0   = Any 1   = No Fit 2   = Very Light 3   = Light 4   = Thin 5   = Book 6   = Medium 7   = Demi 8   = Bold 9   = Heavy 10  = Black 11  = Nord

4. Proportion (bProportion - 10 variations) 0   = Any 1   = No Fit 2   = Old Style 3   = Modern 4   = Even Width 5   = Expanded 6   = Condensed 7   = Very Expanded 8   = Very Condensed 9   = Monospaced

5. Contrast (bContrast - 10 variations) 0   = Any 1   = No Fit 2   = None 3   = Very Low 4   = Low 5   = Medium Low 6   = Medium 7   = Medium High 8   = High 9   = Very High

6. Stroke Variation (bStorokeVariation - 9 variations) 0   = Any 1   = No Fit 2   = Gradual/Diagonal 3   = Gradual/Transitional 4   = Gradual/Vertical 5   = Gradual/Horizontal 6   = Rapid/Vertical 7   = Rapid/Horizontal 8   = Instant/Vertical

7. Arm Style (bArmStyle - 12 variations) 0   = Any 1   = No Fit 2   = Straight Arms/Horizontal 3   = Straight Arms/Wedge 4   = Straight Arms/Vertical 5   = Straight Arms/Single Serif 6   = Straight Arms/Double Serif 7   = Non-Straight Arms/Horizontal 8   = Non-Straight Arms/Wedge 9   = Non-Straight Arms/Vertical 10  = Non-Straight Arms/Single Serif 11  = Non-Straight Arms/Double Serif

8. Letterform (bLetterform - 16 variations) 0   = Any 1   = No Fit 2   = Normal/Contact 3   = Normal/Weighted 4   = Normal/Boxed 5   = Normal/Flattened 6   = Normal/Rounded 7   = Normal/Off Center 8   = Normal/Square 9   = Oblique/Contact 10  = Oblique/Weighted 11  = Oblique/Boxed 12  = Oblique/Flattened 13  = Oblique/Rounded 14  = Oblique/Off Center 15  = Oblique/Square

9. Midline (bMidline - 14 variations) 0   = Any 1   = No Fit 2   = Standard/Trimmed 3   = Standard/Pointed 4   = Standard/Serifed 5   = High/Trimmed 6   = High/Pointed 7   = High/Serifed 8   = Constant/Trimmed 9   = Constant/Pointed 10  = Constant/Serifed 11  = Low/Trimmed 12  = Low/Pointed 13  = Low/Serifed

10. X-height (bXHeight - 8 variations) 0   = Any 1   = No Fit 2   = Constant/Small 3   = Constant/Standard 4   = Constant/Large 5   = Ducking/Small 6   = Ducking/Standard 7   = Ducking/Large

11. fbPassedISO Reserved - must be zero

12. fbFailedISO Reserved - must be zero

When using the PANOSE number to match fonts, the ordering of the PANOSE digit is the key to finding the closest match. The most significant digit is the first digit, and the least significant digit is number ten. To find matches, the digits need to be compared, in the order given. A font mapper may want to change the precedence of the digits, to give higher weightings to other font features.

See the definition of IFIMETRICS in the IFI specification for a detailed explanation of the IFIMETRICS fields.

The Font Definition Header

The font definition header contains information about the format of the character definitions, the character group definitions, data about each group, each character including width data and the offset into the definition section at which the character glyph definition begins. This structure defines the format of the character group definition records and the character definition records that follow:

typedef struct _UNIFONTDEFINITIONHEADER {	UCHAR	Identity[4]; ULONG	ulSize; ULONG	flFontDef; ULONG	flGroupDef; ULONG	flCharDef; ULONG	ulCharDefSize; SHORT	xCellWidth; SHORT	yCellHeight; SHORT	xCellIncrement; SHORT	xCellA; SHORT	xCellB; SHORT	xCellC; SHORT	yCellBaseOffset; USHORT	usReserved; GLYPH	giFirstChar; GLYPH	giLastChar; ULONG	ulCharDefNum; } UNIFONTDEFINITIONHEADER;

Identity		4 bytes. Must be equal to 0x554E4648 ('UNFH'). ulSize			4 byte unsigned integer. Size of this structure in bytes. flFontDef 		4 bytes of flags. Indicates which fields are present in the font definition data in the header.

Bit 0	1 = character width is defined in the font definition header (fixed pitch) 0 = character width is not defined in the font definition header

Bit 1	1 = character height is defined in the font definition header (same for all		 characters) 0 = character height is not defined in the font definition header

Bit 2	1 = character increment is defined in the font definition header (same for		 all characters) 0 = character increment is not defined in the font definition header

Bit 3	1 = a_space is defined in the font definition header (same for all		characters) 0 = a_space is not defined in the font definition header (non abc_space		font or defined for each character)

Bit 4	1 = b_space is defined in the font definition header (same for all		characters) 0 = b_space is not defined in the font definition header (non abc_space		font or defined for each character)

Bit 5	1 = c_space is defined in the font definition header (same for all		characters) 0 = c_space is not defined in the font definition header (non abc_space		font or defined for each character)

Bit 6	1 = base offset is defined in the font definition header (same for all		chracters) 0 = base offset is not defined in the font definition header

flGroupDef		4 bytes of flags. Indicates which fields are present on a per character group basis. Each flag is valid only when the correnponding flFontDef flag bit is on (= 1).

Bit 0	1 = character width is defined in the character group definitions (defined		for each character group) 0 = character width is not defined in the character group definition (same		for all characters)

Bit 1	1 = character height is defined in the character group definitions (defined		for each character group) 0 = character height is not defined in the character group definitions (same		for all characters)

Bit 2	1 = character increment is defined in the the character group definitions (defined for each character group) 0 = character increment is not defined in the character group definitions (same for all characters)

Bit 3	1 = a_space is defined in the character group definitions (defined for each		character group) 0 = a_space is not defined in the character group definitions (same for all		characters)

Bit 4	1 = b_space is defined in the character group definitions (defined for each		character group) 0 = b_space is not defined in the character group definitions (same for all		characters)

Bit 5	1 = c_space is defined in the character group definitions (defined for each		character group) 0 = c_space is not defined in the character group definitions (same for all		characters) Bit 6	1 = base offset is defined in the character group definitions (defined for		each character group) 0 = base offset is not defined in the character group definitions (same for		all characters)

flCharDef		4 bytes of flags. Indicates which fields are present on a per character basis.

Bit 0	1 = character width is defined in the character definitions (defined for each		character definition) 0 = character width is not defined in the character definitions

Bit 1	1 = character height is defined in the character definitions (defined for		each character definition) 0 = character height is not defined in the character definitions

Bit 2	1 = character increment is defined in the the character definitions (defined		for each character definition) 0 = character increment is not defined in the character definitions

Bit 3	1 = a_space is defined in the character definitions (defined for each		character definition) 0 = a_space is not defined in the character definitions

Bit 4	1 = b_space is defined in the character definitions (defined for each		character definition) 0 = b_space is not defined in the character definitions

Bit 5	1 = c_space is defined in the character definitions (defined for each		character definition) 0 = c_space is not defined in the character definitions Bit 6	1 = base offset is defined in the character definitions (defined for each		character definition) 0 = base offset is not defined in the character definitions

Bit 7	1 = offset to glyph is defined 0 = offset to glyph is not defined Bit 7 must be ON for OS/2 4.0.

ulCharDefSize		4-byte unsigned integer. Indicates the length in bytes of each character definition record (the per character data). xCellWidth		2-byte signed integer. The width of the characters, in pels for image fonts. yCellHeight		2-byte signed integer. The height of the characters, in pels for image fonts. xCellIncrement	2-byte signed integer. The distance, in pels for image fonts, along with the character baseline required to step from one character to the next (when forming a character string). xCellA			2-byte signed integer. The width of the space before a character in the inline direction (the a_space), in pels for image fonts. xCellB			2-byte signed integer. The width of a character (inline direction), in pels for image fonts. (the b_space). xCellC			2-byte signed integer. The width of the space after a character in the inline direction, in pels for image fonts (the c_space). yCellBaseOffset	2-byte signed integer. The position of the top of a character definition relative to the baseline in the direction perpendicular to the baseline, in pels for image fonts. usReserved		2 byte unsigned integer. Must be ZERO. giFirstChar		4 byte unsigned integer. The index of the first character glyph in the font file. giLastChar		4 byte unsigned integer. The index of the last character glyph in the font file. ulCharDefNum	4 byte unsigned integer. The number of the character definitions in the font file. If all of the characters between the first and the last character are defined, the value in this field will be giLastChar - giFirstChar + 1.

OS/2 4.0 will support only type1, type2 and type3 font as the font defintion header records are defined as follows.

Type 1 - fixed pitch width and height font ulIdentity		= 0x554E4648; ulSIze			= 64; flFontDef		= 0x00000047; flGroupDef		= 0x00000000; flCharDef		= 0x00000081; (width defined for each character for the performance even		 if the font is defined as a fixed pitch width font) ulCharDefSize		= 6; xCellWidth		= Width of the characters yCellHeight		= Height of the characters xCellIncrement	= Width of the characters xCellA			= 0 xCellB			= 0 xCellC			= 0 yCellBaseOffset	= Baseline offset for all characters ulFirstChar		= The glyph index of the first character ulLastChar		= The glyph index of the last character ulCharDefNum	= The number of the character definitions

Type2 - Proportional width and fixed pitch height font ulIdentity		= 0x554E4648; ulSIze			= 64; flFontDef		= 0x00000042; flGroupDef		= 0x00000000; flCharDef		= 0x00000081; ulCharDefSize		= 6; xCellWidth		= 0 yCellHeight		= Height of the characters xCellIncrement	= 0 xCellA			= 0 xCellB			= 0 xCellC			= 0 yCellBaseOffset	= Baseline offset for all characters ulFirstChar		= The glyph index of the first character ulLastChar		= The glyph index of the last character ulCharDefNum	= The number of the character definitions

Type3 - ABC_space width and fixed pitch height font ulIdentity		= 0x554E4648; ulSIze			= 64; flFontDef		= 0x00000042; flGroupDef		= 0x00000000; flCharDef		= 0x000000B9; ulCharDefSize		= 10; xCellWidth		= 0 yCellHeight		= Height of the characters xCellIncrement	= 0 xCellA			= 0 xCellB			= 0 xCellC			= 0 yCellBaseOffset	= Baseline offset for all characters ulFirstChar		= The glyph index of the first character ulLastChar		= The glyph index of the last character ulCharDefNum	= The number of the character definitions

The following is an explanation of a_space, b_space and c_space definition.

1. Proportional characters (a+b+c = character increment) for each character: a,b,c >= 0 2. Characters where a, b, and c are definitions for all characters: b >= 0 a, c any integer

The Font Character Group Definition

The character group definition record is defined to support the font indices of a large character set of which indices may consist of sparse ranges.

typedef struct _UNICHARGROUPDEFINITION {	UCHAR			Identity[4]; ULONG			ulSize; ULONG			ulCharGroups; UNICHARGROUPENTRY	CharGroupEntry[1]; } UNICHARGROUPDEFINITION; Identity		4 bytes. Must be 0x554E4748 ('UNGH'). ulSize			4 byte unsigned integer. Size of this structure, in bytes, which includes all entries of UNICHARGROUPENTRY. (i.e. sizeof(UNICHARGROUPDEFINITION) + sizeof(UNICHARGROUPENTRY) * (ulCharGroups - 1)) ulCharGroups		4 byte unsigned integer. The number of the character groups in the record. CharGroupEntry	ulCharGroups size of array of the UNICHARGROUPENTRY structure.

The format of the UNICHARGROUPENTRY is :

typedef struct _UNICHARGROUPENTRY {	ULONG		flCharGroupEntry; GLYPH		giFirstChar; GLYPH		giLastChar; LONG			offsetCharDef; SHORT		xCellWidth; SHORT		yCellHeight; SHORT		xCellIncrement; SHORT		xCellA; SHORT		xCellB; SHORT		xCellC; SHORT		yCellBaseOffset; USHORT		usReserved; } UNICHARGROUPENTRY;

where:

flCharGroupEntry	4 bytes of flags. Indicates which fields are present in the character definition data in the header. If the font file is created for a single repository, UNIFONT_FREQUENT_GROUP (Bit 0) Indicate that this character group may be frequently used. It is recommended that the font subsystem cache the character definitions of this group in memory for the performance when this bit is ON. giFirstChar		4 byte unsigned integer. Indicates the start font index of the character group. giLastChar		4 byte unsigned integer. Indicates the end font index of the character group. offsetCharDef		4 bytes signed integer. The offset from the beginning of the Uni font resource (the beginning of the font signature structure) at which the character definition record of this character group begins. The following field are defined in the UNICHARGROUPENTRY structure, however, the values may or may not be present in them according to the ulGroupDef field in UNIFONTDEFINITIONHEADER. If the values are present, they are applied for only the character group. xCellWidth		2-byte signed integer. The width of the characters in the character group definition in pels. yCellHeight		2-byte signed integer. The height of the characters in the character group definition in pels. xCellIncrement	2-byte signed integer. The length along the character baseline required to step from this character to the next in pels(when forming a character string). xCellA			2-byte signed integer. The width of the space before the character in the inline direction in pels. (a_space) xCellB			2-byte signed integer. The width of the character shape in the inline direction in pels. (b_space) xCellC			2-byte signed integer. The width of the space after the character in the inline direction in pels. (c_space) yCellBaseOffset	2-byte signed integer. The position of the top of the chraacters in the character group definition relative to the baseline in the direction perpendicular to the baseline in pels. usReserved		2-byte unsigned integer. Must be ZERO.

The Kerning Pair Table
This record will exist in a Uni font-file format if the UNIFONT_KERNINGPAIRS_EXIST flag in the flFontSignature field in the UNIFONTSIGNATE structure is on. The kerning pair table record is not present if the cKerningPairs field in the UNIFONTMETRICS structure is zero. This table should be sorted by the first character (usFirstChar) and the second character (usSecondChar) order to allow binary searches.

typedef struct _UNIKERNPAIRTABLE {	UCHAR	Identity[4]; ULONG	ulSize; ULONG	ulKernPairs; KERNINGPAIRS KernPairs[1]; } UNIKERNPAIRTABLE;

where: Identity	4bytes. Must be 0x554E4B54 ('UNKT'). ulSize		4 byte unsigned integer. The size of the stucture in bytes, which includes all entries of KERNINGPAIRS. (i.e. sizeof(UNIKERNINGPAIRTABLE) + sizeof(KERNINGPAIRS) * (ulKernPairs - 1)) ulKernPairs	4 byte unsigned integer. The number of kerning pairs in the record. KernPairs	ulKernPairs size of array of the KERNINGPAIR structure.

typedef struct _KERNINGPAIRS {	ULONG	ulFirstChar; ULONG	ulSecondChar; LONG		lKerningAmount; } KERNINGPAIRS;

where:

ulFirstChar		4 byte unsigned integer. First character of the kerning pair. This value must be zero-extended when converted to the GLYPH type. ulSecondChar		4 byte unsigned integer. Second character of the kerning pair. This value must be zero-extended when converted to the GLYPH type. lKerningAmount	4 byte signed integer. Kerning value in pels for image fonts. Positive values increase the inter-character spacing while negative values bring the characters closer together.

The Font Character Definition
Character Definition Record

The following fields may or may not be present, according to the font character definition fields flags. If a field is present, it is present for each character and the value applies to that character only. The fields in the record should be in the order of the following. There are ulCharNumber of the records for image fonts.

Character Glyph Definition Offset (offsetImageData) 4 byte signed integer. The offset from the beginning of the Uni font resource at which the character glyph definition begins. This field should be set to zero if the character glyph is not defined in the font file. If the font subsystem detect the zero value in this field, it should return the character glyph image of giDefaultChar index which is specified in UNIFONTMETRICS. This field must be presented. Character Cell Width (xCellWidth) 2-byte integer. The width of the character definition in pels. Character Cell Height (xCellHeight) 2-byte integer. The height of the character definition in pels. Character Increment (xCellIncrement) 2-byte integer. The length along the character baseline required to step from this character to the next in pels (when forming a character string). Character a-space (xCellA) 2-byte signed integer. The width of the space before the character in the inline direction in pels. Character b-space (xCellB) 2-byte integer. The width of the character shape in the inline direction in pels. Character c-space (xCellC) 2-byte signed integer. The width of the space after the character in the inline direction in pels. Character Baseline Offset (xCellBaseOffset) 2-byte signed integer. The position of the top of a character definition relative to the baseline in the direction perpendicular to the baseline in pels.

The xCellWidth and the xCellIncrement field in the FONTDEFINITIONHEADER structure are nonzero and that represents a fixed pitch width font for the type 1 font. However, the type 1 fonts have offset (offsetImageData) and width (xCellWidth) pairs in the character definition records and the proportional-space flag, bit 0, is set in the fsType field of the UNIFONTMETRICS structure. OS/2 2.1 PM font-file format has the same definition for the type 1 fonts.

Image Data Format

The bits for each character are stored separately, and start on a byte boundary. Sequential bytes represent horizontal pieces of the character image. For example, a 15-bit-wide H is stored as follows:

byte                  byte 0  00000000 0000000-   1 2   01100000 0000110-   3 4   01100000 0000110-   5 6   01100000 0000110-   7 8   01100000 0000110-   9 10  01111111 1111110-  11 12  01111111 1111110-  13 14  01100000 0000110-  15 16  01100000 0000110-  17 18  01100000 0000110-  19 20  01100000 0000110-  21 22  00000000 0000000-  23

The format is the same as the OS/2 bitmap format of one bit per pel.

Graphics Engine New API
GreRealizeString


 * 1) define	INCL_GRE_STRINGS

LONG GreRealizeString (hdc, pGlyph, cChar, pFont, 						ulLen, fl, pInstance, lFunction )

This function processes a character string as if it were being drawn, however, the character glyph bitmap will not be drawn on the target device but placed into the 32 bit font transfer area (FTA) defined as the FOCAFONT32 structure. The graphics engine fills the character glyph bitmaps as many as it can put into FTA designated by pFont. The string will be translated into the font glyph indices by the code page of the currently selected font unless the RS_NO_TRANSLATION or the RS_UNICODE option is specified.

Support: This function is supported by the graphics engine.

Stack Frame:

pGlyph	The code points must be stored in the array of GLYPH (= ULONG) type. Each element will be updated to the indices in FTA by the graphics engine. pFont		Applications should use the sturucture as read-only area. The inside data is managed by the graphics engine. ulLen		The caller needs to allocate enough memory to store the character glyph bitmaps of the string. It is recommended that the caller look into the font metrics of the current selected font or use some of the graphics engine text functions in order to find the suitable size of memory. The size must be at least larger than the size of the FOCAFONT32 structure + the size to store the minimum number of characters. The following is an example how to calculate the minimum required size.

ULONG	ulMinSize; PFONTMETRICS pfm;

cbMaxChar = (pfm->lMaxCharInc + 7 >> 3) * 				pfm->lMaxBaselineExt; ulMinSize = SIZE_FTA_CONTROL + (cbMaxChar + 				SIZE_FTA_CELL) * 10;

fl		Valid flags are: RS_NO_TRANSLATION	No translation from code points to glyph indices will be performed. The font glyph indices are passed. RS_UNICODE		Code points are Unicode. RS_FONT_CACHE		The character glyph bitmap will be stored in the graphics engine global font cache. The caller needs to grab the graphics engine font cache semaphore while accessing the FOCAFONT32 structure returned. RS_CREATE_FTA		The graphics engine will initialize and set up the font cache in the FTA pointed by pFont. RS_DESTROY_FTA	The graphics engine will free all allocated resources for the FTA. RS_PUT_GLYPHS		The graphics engine will validate the FTA font cache so that contained the requested character glyph images. RS_DELETE_GLYPHS	The graphics engine will delete the requested character glyph images from the FTA font cache.

Applications can calculate the number of cached characters by :

pFont->fmMetrics.usLastChar - pFont->fmMetrics.usFirstChar + 1 Angle, Shear, Italic and Bold character attributes are not support.

Return Codes:

This function returns the number of character which are stored in the FTA, or GPI_ALT_ERROR if an error occurs.

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_OR_IMCOMPAT_OPTIONS

GreQueryCharOutline


 * 1) define	INCL_GRE_STRINGS

LONG GreQueryCharOutline( hdc, ulCode, pOutline, ulLen,						fl, pInstance, lFunction )

This functions returns outline data information of the specified character glyph.

Support:

This function is supported by the graphics engine.

Stack Frame:

pOutline	The following graphics orders are possible to be returned as the character glyph outline data. (fl & QCO_GOCA_FORMAT) == TRUE Line at given position (GLINE) Line at current position (GCLINE) Bezier curve at given position (GBEZ) Bezier curve at current position (GCBEZ) No operation (GNOP1) End of symbol definition (GESD)

GLENGTH (1 byte)

GPOINT (4 byte) GSHORT(2 byte) x	GSHORT(2 byte) y

See the Graphics Orders section in OS/2 Graphics Programming Interface Programming Reference for more details.

(fl & QCO_IFI_FORMAT) == TRUE The outline is provided as a list of line, polygons and splines in the given buffer. The polygons are made up of primitives whose vertices are given relative to the character origin. A polygon is a self describing record with a header POLYGONHEADER containing the following fields.

typedef struct _POLYGONHEADER { ULONG cb; ULONG iType;	// Must be FD_POLYGON_TYPE } POLYGONHEADER; cb		The size of this particular polygon record in bytes. This is used to determine how many primitives make up the polygon. All fields of the header and the following primitives are included in this size. iType		This must be FD_POLYGON_TYPE to identify this as a POLYGON record.

The POLYGONHEADER is followed by a list of polygon primitive records. There are two types of primitives allowed, lines and cubic splines. Line primitives are defined as follows:

typedef struct _PRIMLINE /* lnp */ {    ULONG	  iType;	// Must be PRIM_LINE. POINTFX pte;	// Starting vertex of line. } PRIMLINE; Likewise, spline primitives are defined as:

typedef struct _PRIMSPLINE /* splnp */ ULONG	 iType;	// Must be PRIM_SPLINE. POINTFX pte[3];	// Starting vertex of spline, // control points. } PRIMSPLINE;

For both primitive types, the ending vertex is omitted. It can be found as the starting vertex of the following primitive. The ending vertex of the last primitive can be found as the starting vertex of the first primitive. I.e. every polygon record describes a closed figure. All points in the polygon are relative to the character origin in the requested coordinates. Any number of POLYGON records may be put in the buffer, one for each disconnected section of the character outline.

ulLen		The number in bytes which is required to store the character glyph outline data. If ZERO is specified, only the number of bytes will be returned. fl		Valid flags are: QCO_FORMAT_GOCA	The format of outline data to be returned is the GOCA format QCO_FORMAT_IFI	The format outline data to be returned is the IFI format. QCO_NO_TRANSFORM	The coordinates of the character outline data will be returned in the font design space (notional coordinates). QCO_UNICODE		Code point is Unicode.

Return Codes:

This function returns the number of bytes which needs to be stored the character glyph outline data, or GPI_ALT_ERROR if an error occurs.

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INSUFFICIENT_MEMORY PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_FIRST_CHAR PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE PMERR_INV_OR_IMCOMPAT_OPTIONS

GreQueryCharMetricsTable

 * 1) define	INCL_GRE_STRINGS

BOOL GreQueryCharMetricsTable( hdc, lFirstChar, 					cCharMetrics, paCharMetrics,						cCharMetricsLen, fl, pInstance, 					lFunction )

This function stores, at the location addressed by paCharMetrics, an array of world coordinates representing the character metrics table information of the currently selected font.

Support:

This function is supported by the graphics engine.

Stack Frame:

paCharMetrics		This is a pointer to an array of up to cChars character metrics records, each of which contains a maximum of cCharMetrics bytes.

typedef struct _CHARMETRICS { LONG		lA; ULONG		ulB; LONG		lC; RECTL		rclBoundBox; } CHARMETRICS;

lA		Character a_space ulB		Character b_space lC		Character c_space rclBoundBox	Character boundary box. All points in the coundary box are relative to the character origin in the requested coordinates.

fl		Option flags. QCMT_NO_TRANSFORM	The abc space and the boundary box will be returned in the font design space (notional coordinates)

Return Codes:

On completion, BOOLEAN will be returned. TRUE		Successful FALSE	Error

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INSUFFICIENT_MEMORY PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_FIRST_CHAR PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE PMERR_INV_OR_IMCOMPAT_OPTIONS

GreQueryCodePageObject

 * 1) define	INCL_GRE_FONTS

PCODEPAGEOBJECT GreQueryCodePageObject ( hdc,							ulCodePage, szGlyphlist,							pInstance, lFunction )

This function returns a pointer to a CODEPAGEOBJECT structure in which contains the code point to the glyph mapping attributes and services.

Support:

This function is supported by the graphics engine.

Stack Frame:

Return Codes:

This function returns a pointer to the code page object structure, or GPI_ERROR if an error occurs. The following is the code page object definition.

// Code page object structure definition

typedef struct _CODEPAGEOBJECT { UCHAR		Identity; ULONG		ulCodePage; UCHAR		glyphlist[16]; ULONG		fl; PUSHORT		pCpXlate; PUCHAR		pDbcsEnv; ULONG		ulReserved; CPOMEMBERS	mem; } CODEPAGEOBJECT; typedef CODEPAGEOBJECT *PCODEPAGEOBJECT;

Identity	Indentifier. ('CPOB'). ulCodePage	Code Page number of the code page object. szGlyphlist	Glyphlist name of the code page object. fl		Flags. CPO_SBCS_CODEPAGE	The code page is SBCS. CPO_MBCS_CODEPAGE	The code page is MBCS. CPO_DBCS_CODEPAGE	The code page is DBCS. CPO_TABLE_XLATION	The translation will be done by mapping by  pCpXlate. CPO_NO_TRANSLATION	No translation will be performed. (Passthru) pCpXlate	The code point to the glyph index mapping vector. This field is only represented for the code pages that can be supported by the "PM383" glyphlist, otherwise NULL. pDbcsEnv	DBCS environment vector. This field is only represented for MBCS code pages, otherwise NULL. ulReserved	Reserved - 0. mem		Code page object member functions. (See CPOMEMBERS)

Possible Errors Detected:

When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

PMERR_INSUFFICIENT_MEMORY PMERR_INV_CODEPAGE

// Member function structure definition

typedef struct _CPOMEMBERS { PXLATECHAR			pfnXlateChar; PXLATESTRING		pfnXlateString; PINVXLATECHAR		pfnInvXlateChar; PINVXLATESTRING		pfnInvXlateString; } CPOMEMBERS;

typedef CPOMEMBERS *PCPOMEMBERS;

pfnXlateChar		Pointer to the function to translate a code point to a glyph index

typedef ULONG (* APIENTRY PXLATECHAR)(PVOID pCpObj,		     			ULONG ulCod, PGLYPH pgGly);

pfnXlateString		Pointer to the function to translate code point strings to an array of glyph index

typedef ULONG (* APIENTRY PXLATESTRING)(PVOID pCpObj,                              PUCHAR pchCod, ULONG  ulCodLen,                              PGLYPH pgGly, PULONG pulGlyLen,                              ULONG flOptions);

pfnInvXlateChar	Pointer to the function to translate a glyph index to a code point

typedef ULONG (* APIENTRY PINVXLATECHAR)(PVOID pCpObj,                              GLYPH gGly, PULONG pulCod);

pfnInvXlateString	Pointer to the function to translate an array of the glyph index to an array of code point.

typedef ULONG (* APIENTRY PINVXLATESTRING)(PVOID  pCpObj,                              PGLYPH pgGly, ULONG ulGlyLen,                              PUCHAR pchCod, PULONG pulCodLen,                              ULONG  flOptions);