CBDF Specification: Font System

1. Overview

CBDF uses a fixed font lookup table embedded in the client software. Fonts are referenced by a 2-byte (16-bit) Font ID in text style records. This eliminates the need to transmit font names or font files (unless a custom font is required via the Resources section).

2. Font ID Encoding (2 bytes)

Bit layout:

Byte layout (little-endian):

Byte 0 (low):  Lower 8 bits of Font Family Index
Byte 1 (high): Upper 4 bits of Font Family Index + 4 Sub-variant bits

2A. Font Family Index (12 bits, 0-4095)

Font family 0 ("default") means the client uses its own default font. The exact font varies by client but should be a readable sans-serif.

Fonts 1-2000 are assigned from https://cooltext.com/Fonts. The canonical font table is maintained separately and distributed with all CBDF-compliant clients.

Fonts 4000-4094 reference custom font files stored in the Resources section (resource type = 4, "font"). The Font Family Index minus 4000 gives the ordinal position of the custom font in the Resources section (e.g., 4000 = first custom font resource, 4001 = second, etc.).

2B. Sub-Variant Hints (4 bits)

These bits provide HINTS for sub-variant selection when a font family includes multiple variants beyond bold/italic (which are in the flags byte of the text style record).

These are HINTS, not requirements. If the requested sub-variant does not exist for the font family, the client falls back to the base variant.

Bold, Italic, Underline, and Strikethrough are NOT part of the Font ID. They are in the Flags byte (byte 3) of the text style record.

3. Font Effects (4-bit ID)

Font effects are visual filters applied to rendered text. Each text style's rare tier includes a 4-bit effect ID (0-15) and a 4-bit intensity value.

3A. Standard Effect Table

Effects 1-14 use standardized rendering with default parameters. The intensity nibble (0-15) scales the effect's prominence. Intensity 0 with a non-zero effect ID means "use the effect at minimum intensity."

Effect 15 ("Custom") references the Font Effects sub-table in the Styles section for full parameterization (see Styles spec, Section 6G).

3B. Effect Color

The text style rare tier includes an Effect Color (bytes 14-15, R5G6B5). This color is used by effects that need a secondary color:

If the effect doesn't use a secondary color, the Effect Color is ignored.

3C. Animated Effects

Effects 3 (Pulsing Glow), 8 (Glitter), and 9 (Flames) are animated.

Animation parameters for standard effects:

• Speed: Controlled by the intensity nibble (0=paused, 15=fastest).
• Loop: All standard animated effects loop continuously.

For custom animated effects (ID=15): The Font Effects sub-table record includes explicit animation parameters:

• Speed (4 bits): 0=paused, 1=slow, 15=fast
• Loop mode (2 bits): 0=loop, 1=bounce, 2=play once, 3=random

4. Font Table Maintenance

The canonical font table (mapping Font Family Index to font files) is:

• Maintained outside the CBDF format specification.
• Distributed with all CBDF-compliant client software.
• Versioned independently (the table can grow without changing the CBDF format version).
• The first 2000 entries are sourced from CoolText.com free fonts.
• New entries are appended (never reordered) to maintain backward compatibility.

If a client encounters a Font Family Index it does not have in its table, it falls back to the default system font (index 0) and may display a warning to the user.

5. Custom Fonts

Documents that need fonts not in the standard table can embed them:

1. Font file stored in the Resources section (type = 4, "font").
2. Font Family Index set to 4000-4094 in the text style record.
3. Client loads the custom font from the resource and uses it for rendering.

Supported custom font formats:

• WOFF2 (preferred, smallest)
• TTF/OTF
• WOFF