1Fonts and GM Tests
2==================
3
4Overview
5--------
6
7Each test in the gm directory draws a reference image. Their primary purpose is
8to detect when images change unexpectedly, indicating that a rendering bug has
9been introduced.
10
11The gm tests have a secondary purpose: they detect when rendering is different
12across platforms and configurations.
13
14The dm \(Diamond Master\) tool supports flags that minimize or eliminate the
15differences introduced by the font scaler native to each platform.
16
17
18Portable fonts
19--------------
20
21The most portable font format uses Skia to draw characters directly from paths,
22and contains a idealized set of font metrics. This does not exercise platform
23specific fonts at all, but does support specifying the font name, font size,
24font style, and attributes like fakeBold. The paths are generated on a reference
25platform \(currently a Mac\) and are stored as data in
26'tools/test_font_data.cpp' .
27
28To use portable fonts, pass '\-\-portableFonts' to dm.
29
30
31Resource fonts
32--------------
33
34The '\-\-resourceFonts' flag directs dm to use font files present in the resources
35directory. By using the same font set on all buildbots, the generated gm images
36become more uniform across platforms.
37
38Today, the set of fonts used by gm, and present in my resources directory,
39include:
40
41  * Courier New Bold Italic.ttf
42  * Courier New Bold.ttf
43  * Courier New Italic.ttf
44  * Courier New.ttf
45  * LiberationSans-Bold.ttf
46  * LiberationSans-BoldItalic.ttf
47  * LiberationSans-Italic.ttf
48  * LiberationSans-Regular.ttf
49  * Papyrus.ttc
50  * Pro W4.otf
51  * Times New Roman Bold Italic.ttf
52  * Times New Roman Bold.ttf
53  * Times New Roman Italic.ttf
54  * Times New Roman.ttf
55
56
57System fonts
58------------
59
60If neither '\-\-portableFonts' nor '\-\-resourceFonts' is specified, dm uses the fonts
61present on the system. Also, if '\-\-portableFonts' or '\-\-resourceFonts' is specified
62and the desired font is not available, the native font lookup algorithm is
63invoked.
64
65
66GM font selection
67-----------------
68
69Each gm specifies the typeface to use when drawing text. For now, to set the
70portable typeface on the paint, call:
71
72~~~~
73sk_tool_utils::set_portable_typeface(SkPaint* , const char* name = nullptr,
74SkTypeface::Style style = SkTypeface::kNormal );
75~~~~
76
77To create a portable typeface, use:
78
79~~~~
80SkTypeface* typeface = sk_tool_utils::create_portable_typeface(const char* name,
81SkTypeface::Style style);
82~~~~
83
84Eventually, both 'set_portable_typeface()' and 'create_portable_typeface()' will be
85removed. Instead, a test-wide 'SkFontMgr' will be selected to choose portable
86fonts or resource fonts.
87
88
89Adding new fonts and glyphs to a GM
90-----------------------------------
91
92If a font is missing from the portable data or the resource directory, the
93system font is used instead. If a glyph is missing from the portable data, the
94first character, usually a space, is drawn instead.
95
96Running dm with '\-\-portableFonts' and '\-\-reportUsedChars' generates
97'tools/test_font_data_chars.cpp', which describes the fonts and characters used by
98all gm tests. Subsequently running the 'create_test_font' tool generates new paths
99and writes them into 'tools/test_font_data.cpp' .
100
101
102Future work
103-----------
104
105The font set used by gm tests today is arbitrary and not intended to be
106cross-platform. By choosing fonts without licensing issues, all bots can freely
107contain the same fonts. By narrowing the font selection, the size of the test
108font data will be more manageable.
109
110Adding support for selecting from multiple font managers at runtime permits
111removing manual typeface selection in the gm tests. Today, options to dm like
112'\-\-pipe' fail with '\-\-portableFonts' because we're hard-coded to using the default
113font manage when pictures are serialized.
114
115Some gm tests explicitly always want to use system fonts and system metrics;
116other gm tests use text only to label the drawing; yet other gm tests use text
117to generate paths for testing. Additional discrimination is needed to
118distinguish these cases.
119