1 /***************************************************************************/ 2 /* */ 3 /* ftttdrv.h */ 4 /* */ 5 /* FreeType API for controlling the TrueType driver */ 6 /* (specification only). */ 7 /* */ 8 /* Copyright 2013-2015 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 */ 56 57 58 /************************************************************************** 59 * 60 * @property: 61 * interpreter-version 62 * 63 * @description: 64 * Currently, two versions are available, representing the bytecode 65 * interpreter with and without subpixel hinting support, 66 * respectively. The default is subpixel support if 67 * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel 68 * support otherwise (since it isn't available then). 69 * 70 * If subpixel hinting is on, many TrueType bytecode instructions behave 71 * differently compared to B/W or grayscale rendering (except if `native 72 * ClearType' is selected by the font). The main idea is to render at a 73 * much increased horizontal resolution, then sampling down the created 74 * output to subpixel precision. However, many older fonts are not 75 * suited to this and must be specially taken care of by applying 76 * (hardcoded) font-specific tweaks. 77 * 78 * Details on subpixel hinting and some of the necessary tweaks can be 79 * found in Greg Hitchcock's whitepaper at 80 * `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. 81 * 82 * The following example code demonstrates how to activate subpixel 83 * hinting (omitting the error handling). 84 * 85 * { 86 * FT_Library library; 87 * FT_Face face; 88 * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_38; 89 * 90 * 91 * FT_Init_FreeType( &library ); 92 * 93 * FT_Property_Set( library, "truetype", 94 * "interpreter-version", 95 * &interpreter_version ); 96 * } 97 * 98 * @note: 99 * This property can be used with @FT_Property_Get also. 100 * 101 */ 102 103 104 /************************************************************************** 105 * 106 * @enum: 107 * TT_INTERPRETER_VERSION_XXX 108 * 109 * @description: 110 * A list of constants used for the @interpreter-version property to 111 * select the hinting engine for Truetype fonts. 112 * 113 * The numeric value in the constant names represents the version 114 * number as returned by the `GETINFO' bytecode instruction. 115 * 116 * @values: 117 * TT_INTERPRETER_VERSION_35 :: 118 * Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in 119 * Windows~98; only grayscale and B/W rasterizing is supported. 120 * 121 * TT_INTERPRETER_VERSION_38 :: 122 * Version~38 corresponds to MS rasterizer v.1.9; it is roughly 123 * equivalent to the hinting provided by DirectWrite ClearType (as 124 * can be found, for example, in the Internet Explorer~9 running on 125 * Windows~7). 126 * 127 * @note: 128 * This property controls the behaviour of the bytecode interpreter 129 * and thus how outlines get hinted. It does *not* control how glyph 130 * get rasterized! In particular, it does not control subpixel color 131 * filtering. 132 * 133 * If FreeType has not been compiled with configuration option 134 * FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 causes an 135 * `FT_Err_Unimplemented_Feature' error. 136 * 137 * Depending on the graphics framework, Microsoft uses different 138 * bytecode and rendering engines. As a consequence, the version 139 * numbers returned by a call to the `GETINFO' bytecode instruction are 140 * more convoluted than desired. 141 * 142 * Here are two tables that try to shed some light on the possible 143 * values for the MS rasterizer engine, together with the additional 144 * features introduced by it. 145 * 146 * { 147 * GETINFO framework version feature 148 * ------------------------------------------------------------------- 149 * 3 GDI (Win 3.1), v1.0 16-bit, first version 150 * TrueImage 151 * 33 GDI (Win NT 3.1), v1.5 32-bit 152 * HP Laserjet 153 * 34 GDI (Win 95) v1.6 font smoothing, 154 * new SCANTYPE opcode 155 * 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET 156 * bits in composite glyphs 157 * 36 MGDI (Win CE 2) v1.6+ classic ClearType 158 * 37 GDI (XP and later), v1.8 ClearType 159 * GDI+ old (before Vista) 160 * 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType, 161 * WPF Y-direction ClearType, 162 * additional error checking 163 * 39 DWrite (before Win 8) v2.0 subpixel ClearType flags 164 * in GETINFO opcode, 165 * bug fixes 166 * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag 167 * DWrite (Win 8) in GETINFO opcode, 168 * Gray ClearType 169 * } 170 * 171 * The `version' field gives a rough orientation only, since some 172 * applications provided certain features much earlier (as an example, 173 * Microsoft Reader used subpixel and Y-direction ClearType already in 174 * Windows 2000). Similarly, updates to a given framework might include 175 * improved hinting support. 176 * 177 * { 178 * version sampling rendering comment 179 * x y x y 180 * -------------------------------------------------------------- 181 * v1.0 normal normal B/W B/W bi-level 182 * v1.6 high high gray gray grayscale 183 * v1.8 high normal color-filter B/W (GDI) ClearType 184 * v1.9 high high color-filter gray Color ClearType 185 * v2.1 high normal gray B/W Gray ClearType 186 * v2.1 high high gray gray Gray ClearType 187 * } 188 * 189 * Color and Gray ClearType are the two available variants of 190 * `Y-direction ClearType', meaning grayscale rasterization along the 191 * Y-direction; the name used in the TrueType specification for this 192 * feature is `symmetric smoothing'. `Classic ClearType' is the 193 * original algorithm used before introducing a modified version in 194 * Win~XP. Another name for v1.6's grayscale rendering is `font 195 * smoothing', and `Color ClearType' is sometimes also called `DWrite 196 * ClearType'. To differentiate between today's Color ClearType and the 197 * earlier ClearType variant with B/W rendering along the vertical axis, 198 * the latter is sometimes called `GDI ClearType'. 199 * 200 * `Normal' and `high' sampling describe the (virtual) resolution to 201 * access the rasterized outline after the hinting process. `Normal' 202 * means 1 sample per grid line (i.e., B/W). In the current Microsoft 203 * implementation, `high' means an extra virtual resolution of 16x16 (or 204 * 16x1) grid lines per pixel for bytecode instructions like `MIRP'. 205 * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid 206 * lines for color filtering if Color ClearType is activated. 207 * 208 * Note that `Gray ClearType' is essentially the same as v1.6's 209 * grayscale rendering. However, the GETINFO instruction handles it 210 * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1 211 * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing), 212 * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for 213 * the version~1 gasp table exclusively (like Color ClearType), while 214 * v1.6 only respects the values of version~0 (bits 0 and~1). 215 * 216 * FreeType doesn't provide all capabilities of the most recent 217 * ClearType incarnation, thus we identify our subpixel support as 218 * version~38. 219 * 220 */ 221 #define TT_INTERPRETER_VERSION_35 35 222 #define TT_INTERPRETER_VERSION_38 38 223 224 /* */ 225 226 227 FT_END_HEADER 228 229 230 #endif /* __FTTTDRV_H__ */ 231 232 233 /* END */ 234