1 /***************************************************************************/
5 /* FreeType API for controlling the TrueType driver */
6 /* (specification only). */
8 /* Copyright 2013-2015 by */
9 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
11 /* This file is part of the FreeType project, and may only be used, */
12 /* modified, and distributed under the terms of the FreeType project */
13 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
14 /* this file you indicate that you have read the license and */
15 /* understand and accept it fully. */
17 /***************************************************************************/
24 #include FT_FREETYPE_H
27 #error "freetype.h of FreeType 1 has been loaded!"
28 #error "Please fix the directory search order for header files"
29 #error "so that freetype.h of FreeType 2 is found first."
36 /**************************************************************************
45 * Controlling the TrueType driver module.
48 * While FreeType's TrueType driver doesn't expose API functions by
49 * itself, it is possible to control its behaviour with @FT_Property_Set
50 * and @FT_Property_Get. The following lists the available properties
51 * together with the necessary macros and structures.
53 * The TrueType driver's module name is `truetype'.
55 * We start with a list of definitions, kindly provided by Greg
58 * _Bi-Level_ _Rendering_
60 * Monochromatic rendering, exclusively used in the early days of
61 * TrueType by both Apple and Microsoft. Microsoft's GDI interface
62 * supported hinting of the right-side bearing point, such that the
63 * advance width could be non-linear. Most often this was done to
64 * achieve some level of glyph symmetry. To enable reasonable
65 * performance (e.g., not having to run hinting on all glyphs just to
66 * get the widths) there was a bit in the head table indicating if the
67 * side bearing was hinted, and additional tables, `hdmx' and `LTSH', to
68 * cache hinting widths across multiple sizes and device aspect ratios.
72 * Microsoft's GDI implementation of anti-aliasing. Not traditional
73 * anti-aliasing as the outlines were hinted before the sampling. The
74 * widths matched the bi-level rendering.
76 * _ClearType_ _Rendering_
78 * Technique that uses physical subpixels to improve rendering on LCD
79 * (and other) displays. Because of the higher resolution, many methods
80 * of improving symmetry in glyphs through hinting the right-side
81 * bearing were no longer necessary. This lead to what GDI calls
82 * `natural widths' ClearType, see
83 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec21. Since hinting
84 * has extra resolution, most non-linearity went away, but it is still
85 * possible for hints to change the advance widths in this mode.
87 * _ClearType_ _Compatible_ _Widths_
89 * One of the earliest challenges with ClearType was allowing the
90 * implementation in GDI to be selected without requiring all UI and
91 * documents to reflow. To address this, a compatible method of
92 * rendering ClearType was added where the font hints are executed once
93 * to determine the width in bi-level rendering, and then re-run in
94 * ClearType, with the difference in widths being absorbed in the font
95 * hints for ClearType (mostly in the white space of hints); see
96 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec20. Somewhat by
97 * definition, compatible width ClearType allows for non-linear widths,
98 * but only when the bi-level version has non-linear widths.
100 * _ClearType_ _Subpixel_ _Positioning_
102 * One of the nice benefits of ClearType is the ability to more crisply
103 * display fractional widths; unfortunately, the GDI model of integer
104 * bitmaps did not support this. However, the WPF and Direct Write
105 * frameworks do support fractional widths. DWrite calls this `natural
106 * mode', not to be confused with GDI's `natural widths'. Subpixel
107 * positioning, in the current implementation of Direct Write,
108 * unfortunately does not support hinted advance widths, see
109 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec22. Note that the
110 * TrueType interpreter fully allows the advance width to be adjusted in
111 * this mode, just the DWrite client will ignore those changes.
113 * _ClearType_ _Backwards_ _Compatibility_
115 * This is a set of exceptions made in the TrueType interpreter to
116 * minimize hinting techniques that were problematic with the extra
117 * resolution of ClearType; see
118 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec1 and
119 * http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx.
120 * This technique is not to be confused with ClearType compatible
121 * widths. ClearType backwards compatibility has no direct impact on
122 * changing advance widths, but there might be an indirect impact on
123 * disabling some deltas. This could be worked around in backwards
124 * compatibility mode.
126 * _Native_ _ClearType_ _Mode_
128 * (Not to be confused with `natural widths'.) This mode removes all
129 * the exceptions in the TrueType interpreter when running with
130 * ClearType. Any issues on widths would still apply, though.
135 /**************************************************************************
138 * interpreter-version
141 * Currently, two versions are available, representing the bytecode
142 * interpreter with and without subpixel hinting support,
143 * respectively. The default is subpixel support if
144 * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel
145 * support otherwise (since it isn't available then).
147 * If subpixel hinting is on, many TrueType bytecode instructions behave
148 * differently compared to B/W or grayscale rendering (except if `native
149 * ClearType' is selected by the font). The main idea is to render at a
150 * much increased horizontal resolution, then sampling down the created
151 * output to subpixel precision. However, many older fonts are not
152 * suited to this and must be specially taken care of by applying
153 * (hardcoded) font-specific tweaks.
155 * Details on subpixel hinting and some of the necessary tweaks can be
156 * found in Greg Hitchcock's whitepaper at
157 * `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'.
159 * The following example code demonstrates how to activate subpixel
160 * hinting (omitting the error handling).
163 * FT_Library library;
165 * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_38;
168 * FT_Init_FreeType( &library );
170 * FT_Property_Set( library, "truetype",
171 * "interpreter-version",
172 * &interpreter_version );
176 * This property can be used with @FT_Property_Get also.
181 /**************************************************************************
184 * TT_INTERPRETER_VERSION_XXX
187 * A list of constants used for the @interpreter-version property to
188 * select the hinting engine for Truetype fonts.
190 * The numeric value in the constant names represents the version
191 * number as returned by the `GETINFO' bytecode instruction.
194 * TT_INTERPRETER_VERSION_35 ::
195 * Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in
196 * Windows~98; only grayscale and B/W rasterizing is supported.
198 * TT_INTERPRETER_VERSION_38 ::
199 * Version~38 corresponds to MS rasterizer v.1.9; it is roughly
200 * equivalent to the hinting provided by DirectWrite ClearType (as
201 * can be found, for example, in the Internet Explorer~9 running on
205 * This property controls the behaviour of the bytecode interpreter
206 * and thus how outlines get hinted. It does *not* control how glyph
207 * get rasterized! In particular, it does not control subpixel color
210 * If FreeType has not been compiled with configuration option
211 * FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 causes an
212 * `FT_Err_Unimplemented_Feature' error.
214 * Depending on the graphics framework, Microsoft uses different
215 * bytecode and rendering engines. As a consequence, the version
216 * numbers returned by a call to the `GETINFO' bytecode instruction are
217 * more convoluted than desired.
219 * Here are two tables that try to shed some light on the possible
220 * values for the MS rasterizer engine, together with the additional
221 * features introduced by it.
224 * GETINFO framework version feature
225 * -------------------------------------------------------------------
226 * 3 GDI (Win 3.1), v1.0 16-bit, first version
228 * 33 GDI (Win NT 3.1), v1.5 32-bit
230 * 34 GDI (Win 95) v1.6 font smoothing,
231 * new SCANTYPE opcode
232 * 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET
233 * bits in composite glyphs
234 * 36 MGDI (Win CE 2) v1.6+ classic ClearType
235 * 37 GDI (XP and later), v1.8 ClearType
236 * GDI+ old (before Vista)
237 * 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType,
238 * WPF Y-direction ClearType,
239 * additional error checking
240 * 39 DWrite (before Win 8) v2.0 subpixel ClearType flags
243 * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag
244 * DWrite (Win 8) in GETINFO opcode,
248 * The `version' field gives a rough orientation only, since some
249 * applications provided certain features much earlier (as an example,
250 * Microsoft Reader used subpixel and Y-direction ClearType already in
251 * Windows 2000). Similarly, updates to a given framework might include
252 * improved hinting support.
255 * version sampling rendering comment
257 * --------------------------------------------------------------
258 * v1.0 normal normal B/W B/W bi-level
259 * v1.6 high high gray gray grayscale
260 * v1.8 high normal color-filter B/W (GDI) ClearType
261 * v1.9 high high color-filter gray Color ClearType
262 * v2.1 high normal gray B/W Gray ClearType
263 * v2.1 high high gray gray Gray ClearType
266 * Color and Gray ClearType are the two available variants of
267 * `Y-direction ClearType', meaning grayscale rasterization along the
268 * Y-direction; the name used in the TrueType specification for this
269 * feature is `symmetric smoothing'. `Classic ClearType' is the
270 * original algorithm used before introducing a modified version in
271 * Win~XP. Another name for v1.6's grayscale rendering is `font
272 * smoothing', and `Color ClearType' is sometimes also called `DWrite
273 * ClearType'. To differentiate between today's Color ClearType and the
274 * earlier ClearType variant with B/W rendering along the vertical axis,
275 * the latter is sometimes called `GDI ClearType'.
277 * `Normal' and `high' sampling describe the (virtual) resolution to
278 * access the rasterized outline after the hinting process. `Normal'
279 * means 1 sample per grid line (i.e., B/W). In the current Microsoft
280 * implementation, `high' means an extra virtual resolution of 16x16 (or
281 * 16x1) grid lines per pixel for bytecode instructions like `MIRP'.
282 * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid
283 * lines for color filtering if Color ClearType is activated.
285 * Note that `Gray ClearType' is essentially the same as v1.6's
286 * grayscale rendering. However, the GETINFO instruction handles it
287 * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1
288 * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing),
289 * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for
290 * the version~1 gasp table exclusively (like Color ClearType), while
291 * v1.6 only respects the values of version~0 (bits 0 and~1).
293 * FreeType doesn't provide all capabilities of the most recent
294 * ClearType incarnation, thus we identify our subpixel support as
298 #define TT_INTERPRETER_VERSION_35 35
299 #define TT_INTERPRETER_VERSION_38 38
307 #endif /* __FTTTDRV_H__ */