Character Table

Defines mappings between UTF-8 codepoint sequences (characters) and their visual representations (pixmaps).

Use Cases

• Character-to-glyph mapping - Associates text characters, including single utf8 codepoints, ligatures, and grapheme clusters, with their pixmap representation.

Table Structure

Identifier

• Value: 0x01

Modifier Flags

Bit	Name	Description
0	use_advance_x	Each record includes an advance_x field specifying horizontal pixel advance after rendering.
1	use_pixmap_index	Each record includes a pixmap_index field to explicitly reference a pixmap by index.
2	use_pixmap_table_index	Each record includes a pixmap_table_index field to specify which linked Pixmap Table to reference.
3-7	—	Reserved for future use.

Flag Details

• use_advance_x: When disabled, the default advance is the pixmap's width. Letter spacing, if any, is added to the advance value.
• use_pixmap_index: When disabled, the pixmap index defaults to match the character record index creating a one to one mapping.
• use_pixmap_table_index: When disabled, the renderer searches linked Pixmap Tables in order until finding a valid pixmap at the character's index. The first pixmap linked will have priority over the last.

Configuration Flags

Bit	Name	Description
0	use_constant_code_point_count	All characters in this table have the same number of code points.
1-7	—	Reserved for future use.

Configuration Values

Name	Type	Condition	Description
constant_code_point_count	u8	If use_constant_code_point_count is enabled.	The exact code point length of each code_points field in this table

Table Links

Bit	Name	Description
0	link_pixmap_tables	This table links to one or more Pixmap Tables.
1-7	—	Reserved for future use.

Link Arrays

Name	Type	Condition	Description
pixmap_tables	Vec<u8>	If link_pixmap_tables is enabled.	Length byte followed by that many Pixmap Table indices this character table may reference.

Character Record

Each character record contains the following fields in order:

Field	Type	Condition	Description
advance_x	u8	If use_advance_x modifier is enabled.	Number of pixels to advance horizontally after rendering this character.
pixmap_index	u8	If use_pixmap_index modifier is enabled.	Index of the pixmap within the referenced Pixmap Tables.
pixmap_table_index	u8	If use_pixmap_table_index modifier is enabled.	Index of the specific Pixmap Table to use for this character.
code_points	String	Always present	UTF-8 encoded code point sequence, null-terminated unless constant_code_point_count is set.

Record Layout Examples

Example 1: Minimal record (no modifier flags enabled)

Character A, using the default advance and the default pixmap index.

Byte	Field	Binary	Hex	Description
1	code_points	01000001	41	A (U+0041)
2	—	00000000	00	Null terminator

Example 2: With custom advance (use_advance_x)

Character W with a custom 12 pixel advance.

Byte	Field	Binary	Hex	Description
1	advance_x	00001100	0C	Advance 12 pixels
2	code_points	01010111	57	W (U+0057)
3	—	00000000	00	Null terminator

Example 3: With pixmap index (use_pixmap_index)

Character é drawn with the pixmap at index 5. The code point needs two UTF-8 bytes.

Byte	Field	Binary	Hex	Description
1	pixmap_index	00000101	05	Pixmap 5
2	code_points	11000011	C3	é (U+00E9), byte 1 of 2
3	code_points	10101001	A9	é (U+00E9), byte 2 of 2
4	—	00000000	00	Null terminator

Example 4: With all optional fields

Character 👍 with advance 16, pixmap index 42, drawn from linked Pixmap Table 1.

Byte	Field	Binary	Hex	Description
1	advance_x	00010000	10	Advance 16 pixels
2	pixmap_index	00101010	2A	Pixmap 42
3	pixmap_table_index	00000001	01	Pixmap Table 1
4	code_points	11110000	F0	👍 (U+1F44D), byte 1 of 4
5	code_points	10011111	9F	👍 (U+1F44D), byte 2 of 4
6	code_points	10010001	91	👍 (U+1F44D), byte 3 of 4
7	code_points	10001101	8D	👍 (U+1F44D), byte 4 of 4
8	—	00000000	00	Null terminator

Example 5: With a constant code point count

Configuration: constant_code_point_count = 1, so every character in the table is exactly one code point.

Byte	Field	Binary	Hex	Description
1	code_points	01000010	42	B (U+0042), no terminator required

Example 6: Multi-code-point cluster

The ligature != stored as a single character, with no constant code point count set.

Byte	Field	Binary	Hex	Description
1	code_points	00100001	21	! (U+0021), code point 1 of 2
2	code_points	00111101	3D	= (U+003D), code point 2 of 2
3	—	00000000	00	Null terminator ends the cluster

Complete Table Example

The following byte sequence defines a minimal Character Table with two characters (A and B), using custom advance values and linking to one Pixmap Table:

Byte(s)	Binary	Hex	Description
1	00000001	01	Table identifier for Character Table
2	00000011	03	Modifier flags: use_advance_x and use_pixmap_index enabled
3	00000001	01	Configuration flags: use_constant_code_point_count enabled
4	00000001	01	constant_code_point_count = 1 code point
5	00000001	01	Table links: link_pixmap_tables enabled
6	00000001	01	Pixmap table array length = 1
7	00000000	00	Link to Pixmap Table at index 0
8	00000010	02	Record count = 2 characters
9	00001000	08	Character 0: advance_x = 8 pixels
10	00000000	00	Character 0: pixmap_index = 0
11	01000001	41	Character 0: code_points = A
12	00001000	08	Character 1: advance_x = 8 pixels
13	00000001	01	Character 1: pixmap_index = 1
14	01000010	42	Character 1: code_points = B