bgcl: Apple Color Emoji Background Color table

The bgcl table is an Apple private table used in Apple Color Emoji fonts. It stores a JSON blob describing background color palettes used when rendering emoji wallpapers on iOS 16 and later.

The JSON payload contains:

  • colors: a list of palette entries, each an [R, G, B, A] array where R/G/B are 0–255 and A is 0–1.

  • emojicolors: per-emoji palette assignments referencing entries in colors.

Support for the bgcl (Apple Color Emoji background) table.

This table stores a JSON blob. We decode it to a Python object on decompile and emit human readable JSON in the TTX via a <json> element. On compile we re-encode the JSON to UTF-8 bytes which is what Apple code reads via CTFontCopyTable then JSONDecoder.

On iOS 16 and later the bgcl payload is used as the wallpaper background when the user selects an emoji wallpaper.

Fields:

  • colors: list of palette entries. Each entry is an array of four

    integers [R, G, B, A]. R/G/B are 0-255. A is 0-1.

  • emojicolors: list of per-emoji palettes. Each item is an array of

    three sublists: primary/dominant, accent, contextual (names inferred). Each sublist contains integer indexes referencing entries in colors; the runtime uses these to assemble layered background tints for an emoji.

  • indexmap: mapping (glyph identifier → palette index). The map

    maps a glyph identity to an integer index selecting an entry in emojicolors. The font/UI uses this to pick the correct palette for a glyph when rendering wallpaper backgrounds.

  • version: integer table version used for parsing/compatibility.

Runtime usage summary:

  • The system fetches the table bytes with CTFontCopyTable('bgcl'),

    decodes the bytes as UTF‑8 JSON and runs the JSON through the app’s decoder into an internal BgclTable structure. The app looks up a glyph’s entry in indexmap, retrieves the corresponding emojicolors palette, then converts the referenced colors entries into color objects (normalizing channels/alpha as needed). This resulting color(s) drive the wallpaper background appearance for emoji wallpapers on supported iOS versions.

This implementation preserves the JSON payload and exposes convenience attributes colors, emojicolors, indexmap and version when available.

class fontTools.ttLib.tables._b_g_c_l.table__b_g_c_l(tag: str | bytes | None = None)[source]

Bases: DefaultTable

bgcl table: stores a JSON blob describing background palettes.

The JSON structure typically contains the top-level keys:

  • colors: [[R,G,B,A], …]

  • emojicolors: [[[dominant…],[accent…],[contextual…]], …]

  • indexmap: {“glyphIndex”: emojicolors_index, …}

  • version: int

decompile(data: bytes, ttFont: TTFont) → None[source]

Store raw bytes and attempt to parse JSON.

The JSON commonly includes palette/lookup data used at runtime to construct wallpaper/background colors for emoji wallpapers on recent iOS releases.

compile(ttFont: TTFont) → bytes[source]

Encode the JSON object to UTF-8 bytes for font binary storage.

toXML(writer: XMLWriter, ttFont: TTFont) → None[source]

Emit pretty-printed JSON inside a <json> element for human inspection.

fromXML(name: str, attrs: dict[str, str], content, ttFont: TTFont) → None[source]

Read JSON from the <json> element. content may be a list.

This mirrors SVG/other table fromXML handlers which accept a list of content chunks.