Font Handling

Drawings SDK requires access to font files in order to calculate text extents and to vectorize text. Drawings SDK supports both SHX fonts and Truetype fonts. However, the target system must have the correct font files installed for the Drawings to vectorize and find the extents of text that uses a particular font. One of the most common causes for incorrect text vectorization/extents is a missing font file. In such cases, the Drawings will substitute a new font for the missing font, but normally this will cause vectorization and extents differences as the dimensions of the characters in the substituted font will be different from those in the missing font.

Font Libraries

Drawings SDK contains platform neutral code to read and process SHX font files. Truetype fonts are handled in a platform-specific manner. For Windows, the Drawings SDK uses Windows calls to stroke out TTF characters. For other platforms, the Drawings SDK uses the Freetype font library (TD_XXXX_Freetype.*).

Font Representation

SHX fonts (both regular SHX fonts and bigfonts) are represented by a file name, for example, txt.shx. Truetype fonts can be represented be a file name, for example arial.ttf, or a typeface name such as "Times New Roman".

Locating Fonts and Font Files

Drawings SDK performs the following steps when attempting to access a font file:

OdDbHostAppServices::getPreferableFont() is called, which allows the client application to substitute one font name for another before the fonts get used by Drawings. The default implementation tries to substitute the current font based on the contents of the current font mapping file.
If OdDbHostAppServices::getPreferableFont() returned a substitute font name, this name is passed to the OdDbHostAppServices::findFile function (which can be overridden by the user). The default implementation of this function does the following, stopping as soon as one of the steps finds the desired file:
- Attempts to access the file as-is (without modifying the path).
- Attempts to access the file in the current directory.
- Retrieves the system environment variable "ACAD", and attempts to locate the font file in one of the paths stored in this variable (the ACAD variable should contain a set of paths, separated by semi-colons).
- Attempts to access the file in the same directory that the current drawing resides (if applicable).
- For Truetype font files, attempts to locate the font file in the Windows directory (Windows systems only).
If no substitute font was returned by getPreferrableFont() or if the findFile() call for the substitute font failed to locate a valid font, the following actions are performed:
- If a font file name is available, the Drawings SDK calls OdDbHostAppServices::findFile() with this file name.
- If only a typeface name is available, the Drawings calls OdDbHostAppServices::ttfFileNameByDescriptor() to map the typeface to a file name, and then calls OdDbHostAppServices::findFile() for the resulting file name. There is also Truetype font mapping in OdDbHostAppServices, which is useful on non-Windows platforms for font collection. Methods OdDbHostAppServices::getSystemFontFolders() and OdDbHostAppServices::collectFilePathsInDirectory() are called during font map creation in the default implementation of OdDbHostAppServices::ttfFileNameByDescriptor().
If the above steps fail to locate a font file and if a typeface name is present, the Drawings attempts to create a Windows font without using a file name (Windows systems only).
If all of the above steps fail, the Drawings calls OdDbHostAppServices::getSubstituteFont to obtain a substitute for the missing font. The default implementation of OdDbHostAppServices::getSubstituteFont returns the result of calling OdDbHostAppServices::getAlternateFontName(), which returns the FONTALT system variable.

Note: The MTEXT rendering engine uses the OdDbHostAppServices::getSubstituteFontByChar() method if the current font (TTF or SHX) doesn’t contain a necessary character. The method returns the type face for the substituted current font.

Default Fonts

Drawings SDK contains two built-in default SHX fonts, a simple font similar to txt.shx, and a gdt font. These fonts are used during vectorization and extents calculations when all of the above methods fail to yield a valid font or font file. The tables below represent sets of characters with corresponding hex-codes for each of the default fonts.

Set of characters for default gdt font:

Set of characters for default simple font:

Encoding

Operation platforms (macOS, Unix, Windows) can have different encoding types. In this case, convert a string from one codepage to another. It is much better to use the OdCharMapper class. For example, to get a correct string from UTF8 to Unicode, use the OdCharMapper::utf8ToUnicode() method:


OdArray buf;
OdCharMapper::utf8ToUnicode(DWG.szDWGFilePath, 512, buf);
OdString sFilePath(buf.getPtr());

Loading older versions of drawings without DWG code page

Starting with the file format version AC21, a drawing stores text in Unicode. Before this version, strings are stored in the drawing with MBCS (multi-byte character set) coding. There are early versions of drawings that don't have code page information. So in the case of a .dwg file version AC18 and later, Big Font code page is used for converting multi-byte to Unicode. In the case of DXF file loading, system code (system locale) page is used. This is the same behavior as with Autodesk AutoCAD.

Drawings SDK supports the following code page identifications declared by the OdAsianCpIndex enumeration:

Id	Number	Language	Enumeration
0	undefined	undefined
1	932	Japanese (Shift-JIS)	JAPANESE_CP_INDEX
2	950	Traditional Chinese (Big 5)	TRADITIONAL_CHINESE_CP_INDEX
3	949	Wansung (KS C-5601-1987)	KOREAN_WANSUNG_CP_INDEX
4	1361	Johab (KS C-5601-1992)	KOREAN_JOHAB_CP_INDEX
5	936	Simplified Chinese (GB 2312-80)	SIMPLIFIED_CHINESE_CP_INDEX

Font Mapping File Format

A font mapping file is a text file where each line specifies a font substitution. A font substitution is of the form:

<original font>;<font to substitute>

The original font can be either a typeface name or a file name. However, the substitute font should be a file name. For example:


romb;ROMAB___.TTF
romi;ROMAI___.TTF

Support of Big Font coding (mapping)

Asian Language Big Fonts included in the Drawings SDK map by default:

Font File Name	Description	Index
@extfont2.shx	Japanese vertical font	1
bigfont.shx	Japanese font, subset of characters	1
chineset.shx	Traditional Chinese font	2
extfont.shx	Japanese extended font, level 1	1
extfont2.shx	Japanese extended font, level 2	1
gbcbig.shx	Simplified Chinese font	5
whgdtxt.shx	Korean font	3
whgtxt.shx	Korean font	3
whgtxt.shx	Korean font	3
whtmtxt.shx	Korean font	3

A different big font must be added to the map for correct conversion from Unicode to MBCS. The next two methods can be used to populate the map with the font — code page pairs:


void OdCharMapper::addBigFontWithIndex (const OdString& bigFont, OdInt32 cpIndex);
void OdCharMapper::addBigFontWithCodepage (const OdString& bigFont, OdCodePageId acad_cp);

Get the index and code page using the next methods:


OdCodePageId OdCharMapper::getCpByBigFont(const OdString& bigFont);
OdInt32 OdCharMapper::getCpIndexByBigFont(const OdString& bigFont);

A list of big fonts may be added with the next method:


OdResult OdCharMapper::addBigFonts(OdStreamBuf* io);

Format "io" stream is:

Anything after a '#' character until the end of a line is a comment (and ignored)
The ';' character is used to separate the file name from the code page index
Lines with pair:

<BIGFONTFILENAME.SHX> ; <CODE PAGE INDEX>

where CODE PAGE INDEX can be a value as in "enum OdAsianCpIndex".

For custom big fonts, use a "bigfont.ini" file, which specifies code pages for custom double-byte SHX big fonts.

Support of Big Font during rendering

Big fonts are used as an additional font only together with a main font. A big font cannot be used as a single font and also it cannot be used with Truetype fonts. The text style record object has the fileName() method that returns the main font and the bigFontFileName() method that returns the big font.

Unicode characters are converted to MBCB using the big font codepage when they are rendered. Therefore, the big font must be added in the big font mapping using the OdCharMapper class. The big font is used for rendering of characters when it exists.

Relief for ODA Team in Ukraine