1 /***************************************************************************/ 2 /* */ 3 /* ftttdrv.h */ 4 /* */ 5 /* FreeType API for controlling the TrueType driver */ 6 /* (specification only). */ 7 /* */ 8 /* Copyright 2013-2017 by */ 9 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 10 /* */ 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. */ 16 /* */ 17 /***************************************************************************/ 18 19 20 #ifndef FTTTDRV_H_ 21 #define FTTTDRV_H_ 22 23 #include <ft2build.h> 24 #include FT_FREETYPE_H 25 26 #ifdef 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." 30 #endif 31 32 33 FT_BEGIN_HEADER 34 35 36 /************************************************************************** 37 * 38 * @section: 39 * tt_driver 40 * 41 * @title: 42 * The TrueType driver 43 * 44 * @abstract: 45 * Controlling the TrueType driver module. 46 * 47 * @description: 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. 52 * 53 * The TrueType driver's module name is `truetype'. 54 * 55 * We start with a list of definitions, kindly provided by Greg 56 * Hitchcock. 57 * 58 * _Bi-Level_ _Rendering_ 59 * 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. 69 * 70 * _Font_ _Smoothing_ 71 * 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. 75 * 76 * _ClearType_ _Rendering_ 77 * 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. 86 * 87 * _ClearType_ _Compatible_ _Widths_ 88 * 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. 99 * 100 * _ClearType_ _Subpixel_ _Positioning_ 101 * 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. 112 * 113 * _ClearType_ _Backwards_ _Compatibility_ 114 * 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. 125 * 126 * _Native_ _ClearType_ _Mode_ 127 * 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. 131 * 132 */ 133 134 135 /************************************************************************** 136 * 137 * @property: 138 * interpreter-version 139 * 140 * @description: 141 * Currently, three versions are available, two representing the 142 * bytecode interpreter with subpixel hinting support (old `Infinality' 143 * code and new stripped-down and higher performance `minimal' code) and 144 * one without, respectively. The default is subpixel support if 145 * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel support 146 * otherwise (since it isn't available then). 147 * 148 * If subpixel hinting is on, many TrueType bytecode instructions behave 149 * differently compared to B/W or grayscale rendering (except if `native 150 * ClearType' is selected by the font). Microsoft's main idea is to 151 * render at a much increased horizontal resolution, then sampling down 152 * the created output to subpixel precision. However, many older fonts 153 * are not suited to this and must be specially taken care of by 154 * applying (hardcoded) tweaks in Microsoft's interpreter. 155 * 156 * Details on subpixel hinting and some of the necessary tweaks can be 157 * found in Greg Hitchcock's whitepaper at 158 * `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. 159 * Note that FreeType currently doesn't really `subpixel hint' (6x1, 6x2, 160 * or 6x5 supersampling) like discussed in the paper. Depending on the 161 * chosen interpreter, it simply ignores instructions on vertical stems 162 * to arrive at very similar results. 163 * 164 * The following example code demonstrates how to deactivate subpixel 165 * hinting (omitting the error handling). 166 * 167 * { 168 * FT_Library library; 169 * FT_Face face; 170 * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_35; 171 * 172 * 173 * FT_Init_FreeType( &library ); 174 * 175 * FT_Property_Set( library, "truetype", 176 * "interpreter-version", 177 * &interpreter_version ); 178 * } 179 * 180 * @note: 181 * This property can be used with @FT_Property_Get also. 182 * 183 * This property can be set via the `FREETYPE_PROPERTIES' environment 184 * variable (using values `35', `38', or `40'). 185 */ 186 187 188 /************************************************************************** 189 * 190 * @enum: 191 * TT_INTERPRETER_VERSION_XXX 192 * 193 * @description: 194 * A list of constants used for the @interpreter-version property to 195 * select the hinting engine for Truetype fonts. 196 * 197 * The numeric value in the constant names represents the version 198 * number as returned by the `GETINFO' bytecode instruction. 199 * 200 * @values: 201 * TT_INTERPRETER_VERSION_35 :: 202 * Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in 203 * Windows~98; only grayscale and B/W rasterizing is supported. 204 * 205 * TT_INTERPRETER_VERSION_38 :: 206 * Version~38 corresponds to MS rasterizer v.1.9; it is roughly 207 * equivalent to the hinting provided by DirectWrite ClearType (as can 208 * be found, for example, in the Internet Explorer~9 running on 209 * Windows~7). It is used in FreeType to select the `Infinality' 210 * subpixel hinting code. The code may be removed in a future 211 * version. 212 * 213 * TT_INTERPRETER_VERSION_40 :: 214 * Version~40 corresponds to MS rasterizer v.2.1; it is roughly 215 * equivalent to the hinting provided by DirectWrite ClearType (as can 216 * be found, for example, in Microsoft's Edge Browser on Windows~10). 217 * It is used in FreeType to select the `minimal' subpixel hinting 218 * code, a stripped-down and higher performance version of the 219 * `Infinality' code. 220 * 221 * @note: 222 * This property controls the behaviour of the bytecode interpreter 223 * and thus how outlines get hinted. It does *not* control how glyph 224 * get rasterized! In particular, it does not control subpixel color 225 * filtering. 226 * 227 * If FreeType has not been compiled with the configuration option 228 * FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 or~40 causes 229 * an `FT_Err_Unimplemented_Feature' error. 230 * 231 * Depending on the graphics framework, Microsoft uses different 232 * bytecode and rendering engines. As a consequence, the version 233 * numbers returned by a call to the `GETINFO' bytecode instruction are 234 * more convoluted than desired. 235 * 236 * Here are two tables that try to shed some light on the possible 237 * values for the MS rasterizer engine, together with the additional 238 * features introduced by it. 239 * 240 * { 241 * GETINFO framework version feature 242 * ------------------------------------------------------------------- 243 * 3 GDI (Win 3.1), v1.0 16-bit, first version 244 * TrueImage 245 * 33 GDI (Win NT 3.1), v1.5 32-bit 246 * HP Laserjet 247 * 34 GDI (Win 95) v1.6 font smoothing, 248 * new SCANTYPE opcode 249 * 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET 250 * bits in composite glyphs 251 * 36 MGDI (Win CE 2) v1.6+ classic ClearType 252 * 37 GDI (XP and later), v1.8 ClearType 253 * GDI+ old (before Vista) 254 * 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType, 255 * WPF Y-direction ClearType, 256 * additional error checking 257 * 39 DWrite (before Win 8) v2.0 subpixel ClearType flags 258 * in GETINFO opcode, 259 * bug fixes 260 * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag 261 * DWrite (Win 8) in GETINFO opcode, 262 * Gray ClearType 263 * } 264 * 265 * The `version' field gives a rough orientation only, since some 266 * applications provided certain features much earlier (as an example, 267 * Microsoft Reader used subpixel and Y-direction ClearType already in 268 * Windows 2000). Similarly, updates to a given framework might include 269 * improved hinting support. 270 * 271 * { 272 * version sampling rendering comment 273 * x y x y 274 * -------------------------------------------------------------- 275 * v1.0 normal normal B/W B/W bi-level 276 * v1.6 high high gray gray grayscale 277 * v1.8 high normal color-filter B/W (GDI) ClearType 278 * v1.9 high high color-filter gray Color ClearType 279 * v2.1 high normal gray B/W Gray ClearType 280 * v2.1 high high gray gray Gray ClearType 281 * } 282 * 283 * Color and Gray ClearType are the two available variants of 284 * `Y-direction ClearType', meaning grayscale rasterization along the 285 * Y-direction; the name used in the TrueType specification for this 286 * feature is `symmetric smoothing'. `Classic ClearType' is the 287 * original algorithm used before introducing a modified version in 288 * Win~XP. Another name for v1.6's grayscale rendering is `font 289 * smoothing', and `Color ClearType' is sometimes also called `DWrite 290 * ClearType'. To differentiate between today's Color ClearType and the 291 * earlier ClearType variant with B/W rendering along the vertical axis, 292 * the latter is sometimes called `GDI ClearType'. 293 * 294 * `Normal' and `high' sampling describe the (virtual) resolution to 295 * access the rasterized outline after the hinting process. `Normal' 296 * means 1 sample per grid line (i.e., B/W). In the current Microsoft 297 * implementation, `high' means an extra virtual resolution of 16x16 (or 298 * 16x1) grid lines per pixel for bytecode instructions like `MIRP'. 299 * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid 300 * lines for color filtering if Color ClearType is activated. 301 * 302 * Note that `Gray ClearType' is essentially the same as v1.6's 303 * grayscale rendering. However, the GETINFO instruction handles it 304 * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1 305 * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing), 306 * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for 307 * the version~1 gasp table exclusively (like Color ClearType), while 308 * v1.6 only respects the values of version~0 (bits 0 and~1). 309 * 310 * Keep in mind that the features of the above interpreter versions 311 * might not map exactly to FreeType features or behavior because it is 312 * a fundamentally different library with different internals. 313 * 314 */ 315 #define TT_INTERPRETER_VERSION_35 35 316 #define TT_INTERPRETER_VERSION_38 38 317 #define TT_INTERPRETER_VERSION_40 40 318 319 /* */ 320 321 322 FT_END_HEADER 323 324 325 #endif /* FTTTDRV_H_ */ 326 327 328 /* END */ 329