Draw colour emoji by building a Type3 font from the colour font's bitmap tables

[jakejackson1]

Background

packages/Emoji gives us monochrome emoji: Noto Emoji registered as the emoji family and pulled in through getBackupSubsFonts(), so useSubstitution swaps in an outline glyph wherever the document font has none. Colour is not reachable by that route, and not by any route that embeds a font as we embed fonts now.

Colour emoji fonts keep their colour in tables PDF has no notion of: CBDT/CBLC (Noto Color Emoji — PNG bitmap strikes), sbix (Apple Color Emoji), COLR/CPAL (Segoe UI Emoji, Noto COLRv1), OT-SVG. A glyph drawn from a CIDFontType2 is a path filled with the current fill colour, so even a faithfully embedded NotoColorEmoji.ttf renders flat or blank. Two further blocks sit on top:

• Every font we embed is rebuilt from a fixed table whitelist — TTFontFile::makeSubset() emits cmap, glyf, hmtx, loca, head, hhea, maxp, OS/2, name, post, and repackageTTF() (src/TTFontFile.php:4860) keeps a similar list. Colour tables are dropped whether or not subsetting is on.
• Writer\FontWriter writes Type1, TrueType and Type0/CIDFontType2 only (src/Writer/FontWriter.php:125-144). There is no font type here whose glyphs are content streams.

Proposal

Add Type3 font support and build a Type3 font from a colour font's bitmap or layer tables. Type3 is the one place in PDF where colour lives inside a font: each glyph is a /CharProcs content stream, free to set colours, fill paths, or Do an image XObject. Text extraction survives via /ToUnicode, advances still come from hmtx, and the glyph remains a glyph — so shaping, line breaking, justification and Otl keep working on it rather than being handed an inline image to route around.

Sketch of the work:

• TTFontFile — parse CBDT/CBLC (start with bitmap format 17/18 PNG data, which is what Noto ships) and expose, per glyph, the PNG bytes plus the strike's placement metrics. COLR v0 + CPAL is a plausible second source: flat layer lists over existing glyf outlines, one fill colour per layer, no paint graph.
• Writer\FontWriter — a writeType3() alongside the existing three: /Subtype /Type3, /FontMatrix scaled from unitsPerEm, /FontBBox, /CharProcs, /Encoding with /Differences, /Widths, /ToUnicode, and /Resources. Each CharProc is a handful of operators: d0 with the advance, cm to place, Do the image XObject.
• Image XObjects — one per used glyph, ideally through ImageWriter so PNG alpha already becomes an /SMask. Resources are simple: there is a single shared resource dictionary (object 2, ResourceWriter::writeResources()), so the font's /Resources can point at it or carry its own narrow /XObject dict.
• Font registration — a colour emoji font needs to flow through SetFont(), available_unifonts and the backupSubsFont lookup like any other family, with cw populated so _charDefined() answers correctly for the substitution scan.

One constraint worth stating up front, because it turns out to be free: Type3 is a simple font, single-byte encoding, 255 glyphs to a font object. We already do exactly that chunking for SMP/SIP fonts — subsets/subsetfontids split a family across several PDF font objects and the writer switches /F<id> mid-string (src/Mpdf.php:5706-5729, 10968-10979). A Type3 emoji font can reuse that machinery instead of inventing its own.

Scope

In:

• CBDT/CBLC bitmap emoji, embedded as Type3 with image XObjects.
• Emoji sequence handling good enough to be honest: ZWJ sequences, U+FE0F, skin-tone modifiers, regional indicator pairs, keycaps. The font's cmap plus its GSUB ligatures already map these to single glyphs, so this is mostly a matter of letting Otl do its job before the substitution scan decides a character is undefined.
• Monochrome Noto Emoji stays the fallback when no colour font is registered.

Out, at least for now:

• COLR v1 — gradients, composites and transforms would mean translating a paint graph into PDF shadings.
• sbix and OT-SVG.

Open questions

• Resolution and size. Noto's CBDT strike is 136px; a document with many distinct emoji embeds a PNG each and grows accordingly. Do we cap, downsample, or leave it to the caller?
• PDF/A and PDF/X. Type3 is restricted under PDF/A-1 and we would need to decide whether to refuse it and fall back to monochrome, which is probably the right answer.
• Viewer support. Type3 with image XObjects is old and widely handled, but worth confirming against Acrobat, Preview, pdf.js, Poppler and Ghostscript — the last two matter for our own snapshot suite.
• Whether the colour font ships as another packages/* package or stays caller-supplied. Noto Color Emoji is ~10MB.
• Upstreamability: the Type3 writer and CBDT parsing belong upstream on their merits; the registration side leans on FontRegistry, which is ours.

Alternative considered

Substituting an <img> per emoji — splice image tokens in a sibling of SubstituteCharsMB() (src/Mpdf.php:25836) and let the existing inline-image path place them. Cheaper to build and PDF/A-safe, but it hands us ~3.7k assets to ship, makes us own sequence segmentation by hand, and silently drops the emoji from text extraction and copy-paste, since we emit no /Span <</ActualText …>> BDC anywhere. Worth keeping as a second, separately configurable mode rather than as the answer.

Testing

A snapshot fixture per source table, plus unit coverage of the CBDT parse against a small purpose-built font rather than a 10MB download. Note that snapshot comparison rasterises through Ghostscript, so a Type3 fixture also tells us whether Ghostscript agrees with us.

[jakejackson1]

Checked against the real fonts

Google ships two builds, and they land very differently against this proposal.

NotoColorEmoji.ttf — 10,673,480 bytes, 4027 glyphs, unitsPerEm 2048, 13 tables:

CBDT CBLC GSUB OS/2 cmap head hhea hmtx maxp name post vhea vmtx

No glyf. No loca. A pure bitmap font: every pixel of art is in CBDT. cmap carries format 12 (platform 3, encoding 10) and format 14 (platform 0, encoding 5), no format 4.

Noto-COLRv1.ttf — 4,991,984 bytes, 41863 glyphs, unitsPerEm 1024, 15 tables, including glyf + loca (3.4MB of outlines) alongside COLR + CPAL, and a fuller cmap with both format 4 and format 12 subtables.

What they do today

Both load, both produce a PDF, and both render blank — not a monochrome silhouette, nothing at all. Embedding 😀👍 at 40pt from each and rasterising page 1 at 100 DPI with pdftoppm gives 0 non-white pixels out of 967,590, for both. Each output embeds a ~3.5KB /Subtype /TrueType subset named MPDFAA+NotoColorEmoji with the colour tables stripped, as described above. The CBDT build additionally warns from makeSubsetSIP() at src/TTFontFile.php:4438-4441, reading $this->glyphPos for a loca table that does not exist.

Consequences for the plan

The CBDT build is the right target and is better suited than the issue assumes. Having no outlines at all means Type3 is not an alternative path competing with glyf — it is the only path, and there is no fallback rendering to reconcile with. But makeSubsetSIP() has to learn to skip TrueType subsetting outright for a bitmap-only font rather than reading off the end of an empty glyphPos.

GDEF is a prerequisite we do not currently meet. Neither build ships one, and TTFontFile::getMetrics() with useOTL set throws before anything else happens:

Unable to set font "…/NotoColorEmoji.ttf" to use OTL as it does not include OTL tables (or at least not a GDEF table).

GDEF is optional per the OpenType spec, and both fonts carry a real GSUB — 53,788 bytes in the CBDT build — holding the ligature lookups that collapse ZWJ sequences, regional indicator pairs and keycaps into single glyphs. With OTL refused outright those lookups never run, so the sequence handling listed in scope above cannot work: 👨‍👩‍👧 stays three glyphs. Relaxing that requirement, or synthesising a minimal GDEF, has to land before the Type3 work is worth anything. It is arguably a bug in its own right and may be worth splitting out and sending upstream separately.

COLRv1 is out, and that has a cost worth naming. Ruling out COLR v1 means targeting the build Google still publishes but no longer serves from Google Fonts, at 10.7MB with a PNG embedded per used glyph. The COLRv1 build's base glyphs render blank too, for the same reason — its visible shapes live in the COLR layers, not in the outlines its glyf table does contain.

One earlier worry that turned out not to apply: makeSubset() and repackageTTF() do require a format 4 cmap subtable, which NotoColorEmoji.ttf lacks, but sipset/smpset are properties of the font rather than of the character being written, so this font always routes through makeSubsetSIP(), which accepts format 12. Even a BMP emoji such as ❤ U+2764 takes that path.

[jakejackson1]

Correcting the COLRv1 exclusion

The reason given above for putting COLR v1 out of scope — that gradients, composites and transforms would mean translating a paint graph into PDF shadings — does not survive contact with the font. Walking the paint graph of Noto-COLRv1.ttf (3993 base glyph records, 72825 layer paints) gives:

Paint type	Count	PDF equivalent	Present in mPDF
PaintGlyph	129,823	clip to outline (W n)	no — see below
PaintSolid	111,668	rg and fill	yes
PaintTransform / Scale / Translate / ScaleAroundCenter	35,981	cm	yes
PaintColrLayers	14,565	draw layers in order	trivial
PaintRadialGradient	9,844	ShadingType 3, two circles — a direct match	BackgroundWriter::writeShaders()
PaintLinearGradient	8,627	ShadingType 2	same
PaintComposite	578	two modes only, below	partly

The awkward parts of the COLRv1 spec are simply not used here:

• No PaintSweepGradient at all. Conic gradients have no PDF shading type and would have needed a mesh approximation. There are none.
• All 18,471 colour lines use ExtendMode.PAD, which is exactly and only what PDF's /Extend [true true] provides. Nothing to emulate for repeat or reflect.
• No fvar — it is a static font, so no Var* paints and no variation machinery.
• PaintComposite uses two modes out of the spec's 28: SOFT_LIGHT (262), which SetAlpha($alpha, 'SoftLight') already writes as /BM /SoftLight through AddExtGState() (src/Mpdf.php:2001-2027), and SRC_IN (316), which does need a transparency group plus a soft mask.
• Maximum paint graph depth is 9, so plain recursion suffices.

The real blocker, which is a different one

PaintGlyph clips to a glyph outline, so COLRv1 needs glyph outlines expressed as PDF path operators — and mPDF has never decoded a contour. It embeds font programs and lets the viewer rasterise. getGlyphData() (src/TTFontFile.php:4525) walks composite glyph trees but only accumulates nContours and nPoints; it never reads a coordinate, and Fonts\GlyphOperator is only the composite flag constants.

So COLRv1 costs a real glyf outline decoder: point flags with repeat compression, short and long coordinate deltas, on- and off-curve points with implied midpoints, quadratic to cubic conversion for PDF's c, and composite component transforms. Contained and very testable, but genuinely new.

Re-scoping

COLRv1 moves from out of scope to a second phase, blocked on that decoder rather than ruled out. It is in one respect the better target: Type3 CharProcs of pure vector operators, resolution independent, no PNG per glyph, no 10.7MB source, and it is the build Google Fonts actually serves. CBDT stays phase one only because it needs no outline decoder at all.

SRC_IN is the one corner worth deciding in advance. 316 occurrences across 3993 glyphs, so drawing the source paint unclipped and accepting the artefact is a defensible fallback if transparency groups prove troublesome.

Both builds also depend on the GSUB work

Neither font has GDEF, so the check at src/TTFontFile.php:1358 still refuses OTL for both, as noted above. Past that, their GSUB lookups differ in a way that matters here:

• NotoColorEmoji.ttf — LookupType 1, 2, 4, 5 Format 2, 6 Format 2.
• Noto-COLRv1.ttf — LookupType 1, 2, 4, 5 Format 3, 6 Format 3.

So the COLRv1 build needs #77 resolved before its ZWJ ligatures can run at all, while the CBDT build's Type 5 Format 2 is already handled. Worth knowing that the two phases have different prerequisites on that side too.