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 good 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.)

(hirez - another possible argument)

Geep: This is a future idea, but no promises on this.

Change code to allow export of 512x512 bitmaps with larger, thus crisper glyphs. Specifically, add a new command-line option, -hirez, that would

• output 512x512 TGAs and their DAT.
• internally, double the character glyph size; so if your requested 48pt, it would make 96pt glyphs. (This is more or less how /english/ 512x512 treats its hand-made glyphs.)
• make whatever other layout & metric adjustments needed. The imageHeight and imageWidth metrics will be as if the requested 48pt size was generated, so in effect scaling down by a factor of 2 from the 96pt glyph.

Changed Behavior

In ExportFontToDoom3All256, if the font title was more that 20 characters long, it would truncate it to fit in the DAT file as part of the shader names (i.e., paths to TGA files). But this threshold was wrong. Now, truncation and a warning happens if the font title is more that 17 characters long (or 16 if generated TGAs include any with a 2-digit count instead of 1-digit). If truncation occurs, the user is asked to consider using or revising the -name argument.

Downloads

[links to do]

Windows binary and required archived versions of FreeType and DevIL DLLs:

ExportUnicodeFontToDoom3 Release 1 of 09-10-2025.zip

The C++ project file with source code:

ExportUnicodeFontToDoom3_source_project.zip Release 1 of 09-10-2025. This zip is ... MB, includes source & build project of archived library.

The Cyrillic coverage of Lora Regular TTF font, projected to used as Russian Mason supplement in TDM 2.14, may be viewed and font downloaded here.