skia2/site/dev/testing/fonts.md

Fonts and GM Tests

Overview

Each test in the gm directory draws a reference image. Their primary purpose is to detect when images change unexpectedly, indicating that a rendering bug has been introduced.

The gm tests have a secondary purpose: they detect when rendering is different across platforms and configurations.

The dm Diamond Master tool supports flags that minimize or eliminate the differences introduced by the font scaler native to each platform.

Portable fonts

The most portable font format uses Skia to draw characters directly from paths, and contains a idealized set of font metrics. This does not exercise platform specific fonts at all, but does support specifying the font name, font size, font style, and attributes like fakeBold. The paths are generated on a reference platform currently a Mac and are stored as data in 'tools/test_font_data.cpp' .

To use portable fonts, pass '--portableFonts' to dm.

Resource fonts

The '--resourceFonts' flag directs dm to use font files present in the resources directory. By using the same font set on all buildbots, the generated gm images become more uniform across platforms.

Today, the set of fonts used by gm, and present in my resources directory, include:

• Courier New Bold Italic.ttf
• Courier New Bold.ttf
• Courier New Italic.ttf
• Courier New.ttf
• LiberationSans-Bold.ttf
• LiberationSans-BoldItalic.ttf
• LiberationSans-Italic.ttf
• LiberationSans-Regular.ttf
• Papyrus.ttc
• Pro W4.otf
• Times New Roman Bold Italic.ttf
• Times New Roman Bold.ttf
• Times New Roman Italic.ttf
• Times New Roman.ttf

System fonts

If neither '--portableFonts' nor '--resourceFonts' is specified, dm uses the fonts present on the system. Also, if '--portableFonts' or '--resourceFonts' is specified and the desired font is not available, the native font lookup algorithm is invoked.

GM font selection

Each gm specifies the typeface to use when drawing text. For now, to set the portable typeface on the paint, call:

sk_tool_utils::set_portable_typeface(SkPaint* , const char* name = NULL,
SkTypeface::Style style = SkTypeface::kNormal );

To create a portable typeface, use:

SkTypeface* typeface = sk_tool_utils::create_portable_typeface(const char* name,
SkTypeface::Style style);

Eventually, both 'set_portable_typeface()' and 'create_portable_typeface()' will be removed. Instead, a test-wide 'SkFontMgr' will be selected to choose portable fonts or resource fonts.

Adding new fonts and glyphs to a GM

If a font is missing from the portable data or the resource directory, the system font is used instead. If a glyph is missing from the portable data, the first character, usually a space, is drawn instead.

Running dm with '--portableFonts' and '--reportUsedChars' generates 'tools/test_font_data_chars.cpp', which describes the fonts and characters used by all gm tests. Subsequently running the 'create_test_font' tool generates new paths and writes them into 'tools/test_font_data.cpp' .

Future work

The font set used by gm tests today is arbitrary and not intended to be cross-platform. By choosing fonts without licensing issues, all bots can freely contain the same fonts. By narrowing the font selection, the size of the test font data will be more manageable.

Adding support for selecting from multiple font managers at runtime permits removing manual typeface selection in the gm tests. Today, options to dm like '--pipe' fail with '--portableFonts' because we're hard-coded to using the default font manage when pictures are serialized.

Some gm tests explicitly always want to use system fonts and system metrics; other gm tests use text only to label the drawing; yet other gm tests use text to generate paths for testing. Additional discrimination is needed to distinguish these cases.