ExportUnicodeFontToDoom3

By Geep, 2025 [WORK IN PROGRESS]

Introduction

In 2025, kalinovka in Font localization sought to extend TDM’s Mason 48pt font, used in the main menu, to include missing Cyrillic glyphs. This would allow this font to be used in an FM and still support a Russian translation.

This offshoot of ExportFontToDoom3All256 is a generalized response to that. The main idea to select an input TTF font that includes not just ASCII or ANSI, but offers additional Unicode characters, like Cyrillic. The program still limits output to a maximum of 256 characters, consistent with the DAT format.

To achieve this, it reads in an external human-readable "unicodeMap" file, in Unicode.org’s "Format A". This format provides a mapping from the traditional 8-bit encoding that TDM uses to the corresponding UCS (Unicode 16-bit) value. Unicode.org provides stock files for standard ISO and Windows 8-bit encodings. Of specific interest here is cp1251.txt for Cyrillic. This requires just trivial editing for TDM-specific codepoints. As discussed below, you can further edit a unicodeMap file in advance, if you want to generate just a subset of glyphs.

New Command Line Arguments

These are in-addition to those of ExportFontToDoom3All256.

unicodeMap <file>

Example:

-unicodeMap "./Test/cp1251.txt"

You can edit the unicodeMap file in advance, to specify which particular glyphs you want to generate by suppressing unwanted glyphs, either by:

• Deleting an unwanted line (or block of lines) entirely, or
• Prepending a "#" to comment-out the line.

Also, this file format allows the Unicode value (e.g., "0x1234") to be replaced by 6 space characters, when the ISO or Windows standard leaves that character undefined.

In all 3 of those cases, every suppressed character in the output DAT file will be represented by the glyph that the font uses for U+0000. A hollow box is common.

startFileNumber <n>

When a set of TGA/DDS files are generated for a particular font size, by default the first file's name contains _0_, which increments for additional files. You can optionally specify a different 1- or 2-digit start number, e.g., "-startFileNumber 7". Why? Because...

• the file(s) you are generating are supplemental to, not replacements for, existing TGA/DDS files; and
• in this run, you are generating just one of the 3 possible font sizes (assuming each size has a different count of existing TGA/DDS files).

When you generate a supplemental set, the new DAT file has no knowledge of what's in the original set and its DAT file. You will have to interleave-edit the old and new DAT files (e.g., with reFont's REF files) to create a single DAT file spanning old and new glyphs. There may be a redundant NULL glyph in your new TGA set; just ignore it.

awayFromEdge <n>

Allows specifying in positive integer pixels (e.g., "-awayFromEdge 2") a small extra boundary at the top and left edges of the overall bitmap. This is for fonts like Mason where extra space (typically 2 pixels) is needed around every character to create a "glow variant". Routine glyph layout provides usually enough space for this except at the top and (arguably) left edges. See also the "compact" parameter.

compact

If specified (i.e, "-compact"), packs the character glyphs more closely together. Particularly recommended for 48pt fonts; it will generate roughly half the files.

Whether "compact" is specified or not, packing is controlled by simply "padding" each glyph’s bounding box. Specifically, this doesn’t change the bounding box, but adds pixel "padding" to just the right and bottom of the bounding box, a simple though asymmetric process. One reason for padding was given ExportFontToDoom3 author Grant Davies in code comments:

"Because of the way Doom 3 Indexes the texture page (using floating point numbers), it is unable to reference exact pixels – there is error. How much error, I don’t know. For this reason, the rectangles needs to be padded out."

Geep suspects that such error with the TDM engine is not really a problem. Likely some error in the past was due to editing with Q3Font and its low floating-point precision. Nevertheless, some padding is gppd because:

• For the Mason font, 2 pixels around each glyph are needed for "glow" effects (either done as a separate smudge font for /english/ or as a bidirection offset effect for /russian/.)
• Keeping glyphs separated improves visualization of boundaries with datBounds, and makes editing tweaks easier.

The "compact" setting restores Grant Davies' first algorithm, which just pads the bounding box by 5 pixels to the right and 5 pixels below.

Without "compact", the default is Grant Davies' second algorithm found in ExportFontToDoom3 v1.02. This likewise first pads each bounding box by 5 pixels to the right and 5 pixels below. It then further pads to make both the width and height a factor of 2; this makes 48pt quite sparse. (It is possible this improved rendering performance in 2005; not important now. Also, in practice for major fonts, much of this "factor of 2" spacing was overridden by subsequent Font Patcher work.)

[MORE TO COME]