1 /***************************************************************************/ 2 /* */ 3 /* ftdriver.h */ 4 /* */ 5 /* FreeType API for controlling driver modules (specification only). */ 6 /* */ 7 /* Copyright 2017-2018 by */ 8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 9 /* */ 10 /* This file is part of the FreeType project, and may only be used, */ 11 /* modified, and distributed under the terms of the FreeType project */ 12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 13 /* this file you indicate that you have read the license and */ 14 /* understand and accept it fully. */ 15 /* */ 16 /***************************************************************************/ 17 18 19 #ifndef FTDRIVER_H_ 20 #define FTDRIVER_H_ 21 22 #include <ft2build.h> 23 #include FT_FREETYPE_H 24 #include FT_PARAMETER_TAGS_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 * auto_hinter 40 * 41 * @title: 42 * The auto-hinter 43 * 44 * @abstract: 45 * Controlling the auto-hinting module. 46 * 47 * @description: 48 * While FreeType's auto-hinter doesn't expose API functions by itself, 49 * it is possible to control its behaviour with @FT_Property_Set and 50 * @FT_Property_Get. The following lists the available properties 51 * together with the necessary macros and structures. 52 * 53 * Note that the auto-hinter's module name is `autofitter' for 54 * historical reasons. 55 * 56 * Available properties are @increase-x-height, @no-stem-darkening 57 * (experimental), @darkening-parameters (experimental), @warping 58 * (experimental), @glyph-to-script-map (experimental), @fallback-script 59 * (experimental), and @default-script (experimental), as documented in 60 * the @properties section. 61 * 62 */ 63 64 65 /************************************************************************** 66 * 67 * @section: 68 * cff_driver 69 * 70 * @title: 71 * The CFF driver 72 * 73 * @abstract: 74 * Controlling the CFF driver module. 75 * 76 * @description: 77 * While FreeType's CFF driver doesn't expose API functions by itself, 78 * it is possible to control its behaviour with @FT_Property_Set and 79 * @FT_Property_Get. 80 * 81 * The CFF driver's module name is `cff'. 82 * 83 * Available properties are @hinting-engine, @no-stem-darkening, 84 * @darkening-parameters, and @random-seed, as documented in the 85 * @properties section. 86 * 87 * 88 * *Hinting* *and* *antialiasing* *principles* *of* *the* *new* *engine* 89 * 90 * The rasterizer is positioning horizontal features (e.g., ascender 91 * height & x-height, or crossbars) on the pixel grid and minimizing the 92 * amount of antialiasing applied to them, while placing vertical 93 * features (vertical stems) on the pixel grid without hinting, thus 94 * representing the stem position and weight accurately. Sometimes the 95 * vertical stems may be only partially black. In this context, 96 * `antialiasing' means that stems are not positioned exactly on pixel 97 * borders, causing a fuzzy appearance. 98 * 99 * There are two principles behind this approach. 100 * 101 * 1) No hinting in the horizontal direction: Unlike `superhinted' 102 * TrueType, which changes glyph widths to accommodate regular 103 * inter-glyph spacing, Adobe's approach is `faithful to the design' in 104 * representing both the glyph width and the inter-glyph spacing 105 * designed for the font. This makes the screen display as close as it 106 * can be to the result one would get with infinite resolution, while 107 * preserving what is considered the key characteristics of each glyph. 108 * Note that the distances between unhinted and grid-fitted positions at 109 * small sizes are comparable to kerning values and thus would be 110 * noticeable (and distracting) while reading if hinting were applied. 111 * 112 * One of the reasons to not hint horizontally is antialiasing for LCD 113 * screens: The pixel geometry of modern displays supplies three 114 * vertical sub-pixels as the eye moves horizontally across each visible 115 * pixel. On devices where we can be certain this characteristic is 116 * present a rasterizer can take advantage of the sub-pixels to add 117 * increments of weight. In Western writing systems this turns out to 118 * be the more critical direction anyway; the weights and spacing of 119 * vertical stems (see above) are central to Armenian, Cyrillic, Greek, 120 * and Latin type designs. Even when the rasterizer uses greyscale 121 * antialiasing instead of color (a necessary compromise when one 122 * doesn't know the screen characteristics), the unhinted vertical 123 * features preserve the design's weight and spacing much better than 124 * aliased type would. 125 * 126 * 2) Alignment in the vertical direction: Weights and spacing along the 127 * y~axis are less critical; what is much more important is the visual 128 * alignment of related features (like cap-height and x-height). The 129 * sense of alignment for these is enhanced by the sharpness of grid-fit 130 * edges, while the cruder vertical resolution (full pixels instead of 131 * 1/3 pixels) is less of a problem. 132 * 133 * On the technical side, horizontal alignment zones for ascender, 134 * x-height, and other important height values (traditionally called 135 * `blue zones') as defined in the font are positioned independently, 136 * each being rounded to the nearest pixel edge, taking care of 137 * overshoot suppression at small sizes, stem darkening, and scaling. 138 * 139 * Hstems (this is, hint values defined in the font to help align 140 * horizontal features) that fall within a blue zone are said to be 141 * `captured' and are aligned to that zone. Uncaptured stems are moved 142 * in one of four ways, top edge up or down, bottom edge up or down. 143 * Unless there are conflicting hstems, the smallest movement is taken 144 * to minimize distortion. 145 * 146 */ 147 148 149 /************************************************************************** 150 * 151 * @section: 152 * pcf_driver 153 * 154 * @title: 155 * The PCF driver 156 * 157 * @abstract: 158 * Controlling the PCF driver module. 159 * 160 * @description: 161 * While FreeType's PCF driver doesn't expose API functions by itself, 162 * it is possible to control its behaviour with @FT_Property_Set and 163 * @FT_Property_Get. Right now, there is a single property 164 * @no-long-family-names available if FreeType is compiled with 165 * PCF_CONFIG_OPTION_LONG_FAMILY_NAMES. 166 * 167 * The PCF driver's module name is `pcf'. 168 * 169 */ 170 171 172 /************************************************************************** 173 * 174 * @section: 175 * t1_cid_driver 176 * 177 * @title: 178 * The Type 1 and CID drivers 179 * 180 * @abstract: 181 * Controlling the Type~1 and CID driver modules. 182 * 183 * @description: 184 * It is possible to control the behaviour of FreeType's Type~1 and 185 * Type~1 CID drivers with @FT_Property_Set and @FT_Property_Get. 186 * 187 * Behind the scenes, both drivers use the Adobe CFF engine for hinting; 188 * however, the used properties must be specified separately. 189 * 190 * The Type~1 driver's module name is `type1'; the CID driver's module 191 * name is `t1cid'. 192 * 193 * Available properties are @hinting-engine, @no-stem-darkening, 194 * @darkening-parameters, and @random-seed, as documented in the 195 * @properties section. 196 * 197 * Please see the @cff_driver section for more details on the new 198 * hinting engine. 199 * 200 */ 201 202 203 /************************************************************************** 204 * 205 * @section: 206 * tt_driver 207 * 208 * @title: 209 * The TrueType driver 210 * 211 * @abstract: 212 * Controlling the TrueType driver module. 213 * 214 * @description: 215 * While FreeType's TrueType driver doesn't expose API functions by 216 * itself, it is possible to control its behaviour with @FT_Property_Set 217 * and @FT_Property_Get. The following lists the available properties 218 * together with the necessary macros and structures. 219 * 220 * The TrueType driver's module name is `truetype'. 221 * 222 * A single property @interpreter-version is available, as documented in 223 * the @properties section. 224 * 225 * We start with a list of definitions, kindly provided by Greg 226 * Hitchcock. 227 * 228 * _Bi-Level_ _Rendering_ 229 * 230 * Monochromatic rendering, exclusively used in the early days of 231 * TrueType by both Apple and Microsoft. Microsoft's GDI interface 232 * supported hinting of the right-side bearing point, such that the 233 * advance width could be non-linear. Most often this was done to 234 * achieve some level of glyph symmetry. To enable reasonable 235 * performance (e.g., not having to run hinting on all glyphs just to 236 * get the widths) there was a bit in the head table indicating if the 237 * side bearing was hinted, and additional tables, `hdmx' and `LTSH', to 238 * cache hinting widths across multiple sizes and device aspect ratios. 239 * 240 * _Font_ _Smoothing_ 241 * 242 * Microsoft's GDI implementation of anti-aliasing. Not traditional 243 * anti-aliasing as the outlines were hinted before the sampling. The 244 * widths matched the bi-level rendering. 245 * 246 * _ClearType_ _Rendering_ 247 * 248 * Technique that uses physical subpixels to improve rendering on LCD 249 * (and other) displays. Because of the higher resolution, many methods 250 * of improving symmetry in glyphs through hinting the right-side 251 * bearing were no longer necessary. This lead to what GDI calls 252 * `natural widths' ClearType, see 253 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec21. Since hinting 254 * has extra resolution, most non-linearity went away, but it is still 255 * possible for hints to change the advance widths in this mode. 256 * 257 * _ClearType_ _Compatible_ _Widths_ 258 * 259 * One of the earliest challenges with ClearType was allowing the 260 * implementation in GDI to be selected without requiring all UI and 261 * documents to reflow. To address this, a compatible method of 262 * rendering ClearType was added where the font hints are executed once 263 * to determine the width in bi-level rendering, and then re-run in 264 * ClearType, with the difference in widths being absorbed in the font 265 * hints for ClearType (mostly in the white space of hints); see 266 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec20. Somewhat by 267 * definition, compatible width ClearType allows for non-linear widths, 268 * but only when the bi-level version has non-linear widths. 269 * 270 * _ClearType_ _Subpixel_ _Positioning_ 271 * 272 * One of the nice benefits of ClearType is the ability to more crisply 273 * display fractional widths; unfortunately, the GDI model of integer 274 * bitmaps did not support this. However, the WPF and Direct Write 275 * frameworks do support fractional widths. DWrite calls this `natural 276 * mode', not to be confused with GDI's `natural widths'. Subpixel 277 * positioning, in the current implementation of Direct Write, 278 * unfortunately does not support hinted advance widths, see 279 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec22. Note that the 280 * TrueType interpreter fully allows the advance width to be adjusted in 281 * this mode, just the DWrite client will ignore those changes. 282 * 283 * _ClearType_ _Backward_ _Compatibility_ 284 * 285 * This is a set of exceptions made in the TrueType interpreter to 286 * minimize hinting techniques that were problematic with the extra 287 * resolution of ClearType; see 288 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec1 and 289 * https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx. 290 * This technique is not to be confused with ClearType compatible 291 * widths. ClearType backward compatibility has no direct impact on 292 * changing advance widths, but there might be an indirect impact on 293 * disabling some deltas. This could be worked around in backward 294 * compatibility mode. 295 * 296 * _Native_ _ClearType_ _Mode_ 297 * 298 * (Not to be confused with `natural widths'.) This mode removes all 299 * the exceptions in the TrueType interpreter when running with 300 * ClearType. Any issues on widths would still apply, though. 301 * 302 */ 303 304 305 /************************************************************************** 306 * 307 * @section: 308 * properties 309 * 310 * @title: 311 * Driver properties 312 * 313 * @abstract: 314 * Controlling driver modules. 315 * 316 * @description: 317 * Driver modules can be controlled by setting and unsetting properties, 318 * using the functions @FT_Property_Set and @FT_Property_Get. This 319 * section documents the available properties, together with auxiliary 320 * macros and structures. 321 * 322 */ 323 324 325 /************************************************************************** 326 * 327 * @enum: 328 * FT_HINTING_XXX 329 * 330 * @description: 331 * A list of constants used for the @hinting-engine property to 332 * select the hinting engine for CFF, Type~1, and CID fonts. 333 * 334 * @values: 335 * FT_HINTING_FREETYPE :: 336 * Use the old FreeType hinting engine. 337 * 338 * FT_HINTING_ADOBE :: 339 * Use the hinting engine contributed by Adobe. 340 * 341 * @since: 342 * 2.9 343 * 344 */ 345 #define FT_HINTING_FREETYPE 0 346 #define FT_HINTING_ADOBE 1 347 348 /* these constants (introduced in 2.4.12) are deprecated */ 349 #define FT_CFF_HINTING_FREETYPE FT_HINTING_FREETYPE 350 #define FT_CFF_HINTING_ADOBE FT_HINTING_ADOBE 351 352 353 /************************************************************************** 354 * 355 * @property: 356 * hinting-engine 357 * 358 * @description: 359 * Thanks to Adobe, which contributed a new hinting (and parsing) 360 * engine, an application can select between `freetype' and `adobe' if 361 * compiled with CFF_CONFIG_OPTION_OLD_ENGINE. If this configuration 362 * macro isn't defined, `hinting-engine' does nothing. 363 * 364 * The same holds for the Type~1 and CID modules if compiled with 365 * T1_CONFIG_OPTION_OLD_ENGINE. 366 * 367 * For the `cff' module, the default engine is `freetype' if 368 * CFF_CONFIG_OPTION_OLD_ENGINE is defined, and `adobe' otherwise. 369 * 370 * For both the `type1' and `t1cid' modules, the default engine is 371 * `freetype' if T1_CONFIG_OPTION_OLD_ENGINE is defined, and `adobe' 372 * otherwise. 373 * 374 * The following example code demonstrates how to select Adobe's hinting 375 * engine for the `cff' module (omitting the error handling). 376 * 377 * { 378 * FT_Library library; 379 * FT_UInt hinting_engine = FT_CFF_HINTING_ADOBE; 380 * 381 * 382 * FT_Init_FreeType( &library ); 383 * 384 * FT_Property_Set( library, "cff", 385 * "hinting-engine", &hinting_engine ); 386 * } 387 * 388 * @note: 389 * This property can be used with @FT_Property_Get also. 390 * 391 * This property can be set via the `FREETYPE_PROPERTIES' environment 392 * variable (using values `adobe' or `freetype'). 393 * 394 * @since: 395 * 2.4.12 (for `cff' module) 396 * 397 * 2.9 (for `type1' and `t1cid' modules) 398 * 399 */ 400 401 402 /************************************************************************** 403 * 404 * @property: 405 * no-stem-darkening 406 * 407 * @description: 408 * All glyphs that pass through the auto-hinter will be emboldened 409 * unless this property is set to TRUE. The same is true for the CFF, 410 * Type~1, and CID font modules if the `Adobe' engine is selected (which 411 * is the default). 412 * 413 * Stem darkening emboldens glyphs at smaller sizes to make them more 414 * readable on common low-DPI screens when using linear alpha blending 415 * and gamma correction, see @FT_Render_Glyph. When not using linear 416 * alpha blending and gamma correction, glyphs will appear heavy and 417 * fuzzy! 418 * 419 * Gamma correction essentially lightens fonts since shades of grey are 420 * shifted to higher pixel values (=~higher brightness) to match the 421 * original intention to the reality of our screens. The side-effect is 422 * that glyphs `thin out'. Mac OS~X and Adobe's proprietary font 423 * rendering library implement a counter-measure: stem darkening at 424 * smaller sizes where shades of gray dominate. By emboldening a glyph 425 * slightly in relation to its pixel size, individual pixels get higher 426 * coverage of filled-in outlines and are therefore `blacker'. This 427 * counteracts the `thinning out' of glyphs, making text remain readable 428 * at smaller sizes. 429 * 430 * By default, the Adobe engines for CFF, Type~1, and CID fonts darken 431 * stems at smaller sizes, regardless of hinting, to enhance contrast. 432 * Setting this property, stem darkening gets switched off. 433 * 434 * For the auto-hinter, stem-darkening is experimental currently and 435 * thus switched off by default (this is, `no-stem-darkening' is set to 436 * TRUE by default). Total consistency with the CFF driver is not 437 * achieved right now because the emboldening method differs and glyphs 438 * must be scaled down on the Y-axis to keep outline points inside their 439 * precomputed blue zones. The smaller the size (especially 9ppem and 440 * down), the higher the loss of emboldening versus the CFF driver. 441 * 442 * Note that stem darkening is never applied if @FT_LOAD_NO_SCALE is 443 * set. 444 * 445 * { 446 * FT_Library library; 447 * FT_Bool no_stem_darkening = TRUE; 448 * 449 * 450 * FT_Init_FreeType( &library ); 451 * 452 * FT_Property_Set( library, "cff", 453 * "no-stem-darkening", &no_stem_darkening ); 454 * } 455 * 456 * @note: 457 * This property can be used with @FT_Property_Get also. 458 * 459 * This property can be set via the `FREETYPE_PROPERTIES' environment 460 * variable (using values 1 and 0 for `on' and `off', respectively). 461 * It can also be set per face using @FT_Face_Properties with 462 * @FT_PARAM_TAG_STEM_DARKENING. 463 * 464 * @since: 465 * 2.4.12 (for `cff' module) 466 * 467 * 2.6.2 (for `autofitter' module) 468 * 469 * 2.9 (for `type1' and `t1cid' modules) 470 * 471 */ 472 473 474 /************************************************************************** 475 * 476 * @property: 477 * darkening-parameters 478 * 479 * @description: 480 * By default, the Adobe hinting engine, as used by the CFF, Type~1, and 481 * CID font drivers, darkens stems as follows (if the 482 * `no-stem-darkening' property isn't set): 483 * 484 * { 485 * stem width <= 0.5px: darkening amount = 0.4px 486 * stem width = 1px: darkening amount = 0.275px 487 * stem width = 1.667px: darkening amount = 0.275px 488 * stem width >= 2.333px: darkening amount = 0px 489 * } 490 * 491 * and piecewise linear in-between. At configuration time, these four 492 * control points can be set with the macro 493 * `CFF_CONFIG_OPTION_DARKENING_PARAMETERS'; the CFF, Type~1, and CID 494 * drivers share these values. At runtime, the control points can be 495 * changed using the `darkening-parameters' property, as the following 496 * example demonstrates for the Type~1 driver. 497 * 498 * { 499 * FT_Library library; 500 * FT_Int darken_params[8] = { 500, 300, // x1, y1 501 * 1000, 200, // x2, y2 502 * 1500, 100, // x3, y3 503 * 2000, 0 }; // x4, y4 504 * 505 * 506 * FT_Init_FreeType( &library ); 507 * 508 * FT_Property_Set( library, "type1", 509 * "darkening-parameters", darken_params ); 510 * } 511 * 512 * The x~values give the stem width, and the y~values the darkening 513 * amount. The unit is 1000th of pixels. All coordinate values must be 514 * positive; the x~values must be monotonically increasing; the 515 * y~values must be monotonically decreasing and smaller than or 516 * equal to 500 (corresponding to half a pixel); the slope of each 517 * linear piece must be shallower than -1 (e.g., -.4). 518 * 519 * The auto-hinter provides this property, too, as an experimental 520 * feature. See @no-stem-darkening for more. 521 * 522 * @note: 523 * This property can be used with @FT_Property_Get also. 524 * 525 * This property can be set via the `FREETYPE_PROPERTIES' environment 526 * variable, using eight comma-separated integers without spaces. Here 527 * the above example, using `\' to break the line for readability. 528 * 529 * { 530 * FREETYPE_PROPERTIES=\ 531 * type1:darkening-parameters=500,300,1000,200,1500,100,2000,0 532 * } 533 * 534 * @since: 535 * 2.5.1 (for `cff' module) 536 * 537 * 2.6.2 (for `autofitter' module) 538 * 539 * 2.9 (for `type1' and `t1cid' modules) 540 * 541 */ 542 543 544 /************************************************************************** 545 * 546 * @property: 547 * random-seed 548 * 549 * @description: 550 * By default, the seed value for the CFF `random' operator and the 551 * similar `0 28 callothersubr pop' command for the Type~1 and CID 552 * drivers is set to a random value. However, mainly for debugging 553 * purposes, it is often necessary to use a known value as a seed so 554 * that the pseudo-random number sequences generated by `random' are 555 * repeatable. 556 * 557 * The `random-seed' property does that. Its argument is a signed 32bit 558 * integer; if the value is zero or negative, the seed given by the 559 * `intitialRandomSeed' private DICT operator in a CFF file gets used 560 * (or a default value if there is no such operator). If the value is 561 * positive, use it instead of `initialRandomSeed', which is 562 * consequently ignored. 563 * 564 * @note: 565 * This property can be set via the `FREETYPE_PROPERTIES' environment 566 * variable. It can also be set per face using @FT_Face_Properties with 567 * @FT_PARAM_TAG_RANDOM_SEED. 568 * 569 * @since: 570 * 2.8 (for `cff' module) 571 * 572 * 2.9 (for `type1' and `t1cid' modules) 573 * 574 */ 575 576 577 /************************************************************************** 578 * 579 * @property: 580 * no-long-family-names 581 * 582 * @description: 583 * If PCF_CONFIG_OPTION_LONG_FAMILY_NAMES is active while compiling 584 * FreeType, the PCF driver constructs long family names. 585 * 586 * There are many PCF fonts just called `Fixed' which look completely 587 * different, and which have nothing to do with each other. When 588 * selecting `Fixed' in KDE or Gnome one gets results that appear rather 589 * random, the style changes often if one changes the size and one 590 * cannot select some fonts at all. The improve this situation, the PCF 591 * module prepends the foundry name (plus a space) to the family name. 592 * It also checks whether there are `wide' characters; all put together, 593 * family names like `Sony Fixed' or `Misc Fixed Wide' are constructed. 594 * 595 * If `no-long-family-names' is set, this feature gets switched off. 596 * 597 * { 598 * FT_Library library; 599 * FT_Bool no_long_family_names = TRUE; 600 * 601 * 602 * FT_Init_FreeType( &library ); 603 * 604 * FT_Property_Set( library, "pcf", 605 * "no-long-family-names", 606 * &no_long_family_names ); 607 * } 608 * 609 * @note: 610 * This property can be used with @FT_Property_Get also. 611 * 612 * This property can be set via the `FREETYPE_PROPERTIES' environment 613 * variable (using values 1 and 0 for `on' and `off', respectively). 614 * 615 * @since: 616 * 2.8 617 */ 618 619 620 /************************************************************************** 621 * 622 * @enum: 623 * TT_INTERPRETER_VERSION_XXX 624 * 625 * @description: 626 * A list of constants used for the @interpreter-version property to 627 * select the hinting engine for Truetype fonts. 628 * 629 * The numeric value in the constant names represents the version 630 * number as returned by the `GETINFO' bytecode instruction. 631 * 632 * @values: 633 * TT_INTERPRETER_VERSION_35 :: 634 * Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in 635 * Windows~98; only grayscale and B/W rasterizing is supported. 636 * 637 * TT_INTERPRETER_VERSION_38 :: 638 * Version~38 corresponds to MS rasterizer v.1.9; it is roughly 639 * equivalent to the hinting provided by DirectWrite ClearType (as can 640 * be found, for example, in the Internet Explorer~9 running on 641 * Windows~7). It is used in FreeType to select the `Infinality' 642 * subpixel hinting code. The code may be removed in a future 643 * version. 644 * 645 * TT_INTERPRETER_VERSION_40 :: 646 * Version~40 corresponds to MS rasterizer v.2.1; it is roughly 647 * equivalent to the hinting provided by DirectWrite ClearType (as can 648 * be found, for example, in Microsoft's Edge Browser on Windows~10). 649 * It is used in FreeType to select the `minimal' subpixel hinting 650 * code, a stripped-down and higher performance version of the 651 * `Infinality' code. 652 * 653 * @note: 654 * This property controls the behaviour of the bytecode interpreter 655 * and thus how outlines get hinted. It does *not* control how glyph 656 * get rasterized! In particular, it does not control subpixel color 657 * filtering. 658 * 659 * If FreeType has not been compiled with the configuration option 660 * TT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 or~40 causes 661 * an `FT_Err_Unimplemented_Feature' error. 662 * 663 * Depending on the graphics framework, Microsoft uses different 664 * bytecode and rendering engines. As a consequence, the version 665 * numbers returned by a call to the `GETINFO' bytecode instruction are 666 * more convoluted than desired. 667 * 668 * Here are two tables that try to shed some light on the possible 669 * values for the MS rasterizer engine, together with the additional 670 * features introduced by it. 671 * 672 * { 673 * GETINFO framework version feature 674 * ------------------------------------------------------------------- 675 * 3 GDI (Win 3.1), v1.0 16-bit, first version 676 * TrueImage 677 * 33 GDI (Win NT 3.1), v1.5 32-bit 678 * HP Laserjet 679 * 34 GDI (Win 95) v1.6 font smoothing, 680 * new SCANTYPE opcode 681 * 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET 682 * bits in composite glyphs 683 * 36 MGDI (Win CE 2) v1.6+ classic ClearType 684 * 37 GDI (XP and later), v1.8 ClearType 685 * GDI+ old (before Vista) 686 * 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType, 687 * WPF Y-direction ClearType, 688 * additional error checking 689 * 39 DWrite (before Win 8) v2.0 subpixel ClearType flags 690 * in GETINFO opcode, 691 * bug fixes 692 * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag 693 * DWrite (Win 8) in GETINFO opcode, 694 * Gray ClearType 695 * } 696 * 697 * The `version' field gives a rough orientation only, since some 698 * applications provided certain features much earlier (as an example, 699 * Microsoft Reader used subpixel and Y-direction ClearType already in 700 * Windows 2000). Similarly, updates to a given framework might include 701 * improved hinting support. 702 * 703 * { 704 * version sampling rendering comment 705 * x y x y 706 * -------------------------------------------------------------- 707 * v1.0 normal normal B/W B/W bi-level 708 * v1.6 high high gray gray grayscale 709 * v1.8 high normal color-filter B/W (GDI) ClearType 710 * v1.9 high high color-filter gray Color ClearType 711 * v2.1 high normal gray B/W Gray ClearType 712 * v2.1 high high gray gray Gray ClearType 713 * } 714 * 715 * Color and Gray ClearType are the two available variants of 716 * `Y-direction ClearType', meaning grayscale rasterization along the 717 * Y-direction; the name used in the TrueType specification for this 718 * feature is `symmetric smoothing'. `Classic ClearType' is the 719 * original algorithm used before introducing a modified version in 720 * Win~XP. Another name for v1.6's grayscale rendering is `font 721 * smoothing', and `Color ClearType' is sometimes also called `DWrite 722 * ClearType'. To differentiate between today's Color ClearType and the 723 * earlier ClearType variant with B/W rendering along the vertical axis, 724 * the latter is sometimes called `GDI ClearType'. 725 * 726 * `Normal' and `high' sampling describe the (virtual) resolution to 727 * access the rasterized outline after the hinting process. `Normal' 728 * means 1 sample per grid line (i.e., B/W). In the current Microsoft 729 * implementation, `high' means an extra virtual resolution of 16x16 (or 730 * 16x1) grid lines per pixel for bytecode instructions like `MIRP'. 731 * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid 732 * lines for color filtering if Color ClearType is activated. 733 * 734 * Note that `Gray ClearType' is essentially the same as v1.6's 735 * grayscale rendering. However, the GETINFO instruction handles it 736 * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1 737 * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing), 738 * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for 739 * the version~1 gasp table exclusively (like Color ClearType), while 740 * v1.6 only respects the values of version~0 (bits 0 and~1). 741 * 742 * Keep in mind that the features of the above interpreter versions 743 * might not map exactly to FreeType features or behavior because it is 744 * a fundamentally different library with different internals. 745 * 746 */ 747 #define TT_INTERPRETER_VERSION_35 35 748 #define TT_INTERPRETER_VERSION_38 38 749 #define TT_INTERPRETER_VERSION_40 40 750 751 752 /************************************************************************** 753 * 754 * @property: 755 * interpreter-version 756 * 757 * @description: 758 * Currently, three versions are available, two representing the 759 * bytecode interpreter with subpixel hinting support (old `Infinality' 760 * code and new stripped-down and higher performance `minimal' code) and 761 * one without, respectively. The default is subpixel support if 762 * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel support 763 * otherwise (since it isn't available then). 764 * 765 * If subpixel hinting is on, many TrueType bytecode instructions behave 766 * differently compared to B/W or grayscale rendering (except if `native 767 * ClearType' is selected by the font). Microsoft's main idea is to 768 * render at a much increased horizontal resolution, then sampling down 769 * the created output to subpixel precision. However, many older fonts 770 * are not suited to this and must be specially taken care of by 771 * applying (hardcoded) tweaks in Microsoft's interpreter. 772 * 773 * Details on subpixel hinting and some of the necessary tweaks can be 774 * found in Greg Hitchcock's whitepaper at 775 * `https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. 776 * Note that FreeType currently doesn't really `subpixel hint' (6x1, 6x2, 777 * or 6x5 supersampling) like discussed in the paper. Depending on the 778 * chosen interpreter, it simply ignores instructions on vertical stems 779 * to arrive at very similar results. 780 * 781 * The following example code demonstrates how to deactivate subpixel 782 * hinting (omitting the error handling). 783 * 784 * { 785 * FT_Library library; 786 * FT_Face face; 787 * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_35; 788 * 789 * 790 * FT_Init_FreeType( &library ); 791 * 792 * FT_Property_Set( library, "truetype", 793 * "interpreter-version", 794 * &interpreter_version ); 795 * } 796 * 797 * @note: 798 * This property can be used with @FT_Property_Get also. 799 * 800 * This property can be set via the `FREETYPE_PROPERTIES' environment 801 * variable (using values `35', `38', or `40'). 802 * 803 * @since: 804 * 2.5 805 */ 806 807 808 /************************************************************************** 809 * 810 * @property: 811 * glyph-to-script-map 812 * 813 * @description: 814 * *Experimental* *only* 815 * 816 * The auto-hinter provides various script modules to hint glyphs. 817 * Examples of supported scripts are Latin or CJK. Before a glyph is 818 * auto-hinted, the Unicode character map of the font gets examined, and 819 * the script is then determined based on Unicode character ranges, see 820 * below. 821 * 822 * OpenType fonts, however, often provide much more glyphs than 823 * character codes (small caps, superscripts, ligatures, swashes, etc.), 824 * to be controlled by so-called `features'. Handling OpenType features 825 * can be quite complicated and thus needs a separate library on top of 826 * FreeType. 827 * 828 * The mapping between glyph indices and scripts (in the auto-hinter 829 * sense, see the @FT_AUTOHINTER_SCRIPT_XXX values) is stored as an 830 * array with `num_glyphs' elements, as found in the font's @FT_Face 831 * structure. The `glyph-to-script-map' property returns a pointer to 832 * this array, which can be modified as needed. Note that the 833 * modification should happen before the first glyph gets processed by 834 * the auto-hinter so that the global analysis of the font shapes 835 * actually uses the modified mapping. 836 * 837 * The following example code demonstrates how to access it (omitting 838 * the error handling). 839 * 840 * { 841 * FT_Library library; 842 * FT_Face face; 843 * FT_Prop_GlyphToScriptMap prop; 844 * 845 * 846 * FT_Init_FreeType( &library ); 847 * FT_New_Face( library, "foo.ttf", 0, &face ); 848 * 849 * prop.face = face; 850 * 851 * FT_Property_Get( library, "autofitter", 852 * "glyph-to-script-map", &prop ); 853 * 854 * // adjust `prop.map' as needed right here 855 * 856 * FT_Load_Glyph( face, ..., FT_LOAD_FORCE_AUTOHINT ); 857 * } 858 * 859 * @since: 860 * 2.4.11 861 * 862 */ 863 864 865 /************************************************************************** 866 * 867 * @enum: 868 * FT_AUTOHINTER_SCRIPT_XXX 869 * 870 * @description: 871 * *Experimental* *only* 872 * 873 * A list of constants used for the @glyph-to-script-map property to 874 * specify the script submodule the auto-hinter should use for hinting a 875 * particular glyph. 876 * 877 * @values: 878 * FT_AUTOHINTER_SCRIPT_NONE :: 879 * Don't auto-hint this glyph. 880 * 881 * FT_AUTOHINTER_SCRIPT_LATIN :: 882 * Apply the latin auto-hinter. For the auto-hinter, `latin' is a 883 * very broad term, including Cyrillic and Greek also since characters 884 * from those scripts share the same design constraints. 885 * 886 * By default, characters from the following Unicode ranges are 887 * assigned to this submodule. 888 * 889 * { 890 * U+0020 - U+007F // Basic Latin (no control characters) 891 * U+00A0 - U+00FF // Latin-1 Supplement (no control characters) 892 * U+0100 - U+017F // Latin Extended-A 893 * U+0180 - U+024F // Latin Extended-B 894 * U+0250 - U+02AF // IPA Extensions 895 * U+02B0 - U+02FF // Spacing Modifier Letters 896 * U+0300 - U+036F // Combining Diacritical Marks 897 * U+0370 - U+03FF // Greek and Coptic 898 * U+0400 - U+04FF // Cyrillic 899 * U+0500 - U+052F // Cyrillic Supplement 900 * U+1D00 - U+1D7F // Phonetic Extensions 901 * U+1D80 - U+1DBF // Phonetic Extensions Supplement 902 * U+1DC0 - U+1DFF // Combining Diacritical Marks Supplement 903 * U+1E00 - U+1EFF // Latin Extended Additional 904 * U+1F00 - U+1FFF // Greek Extended 905 * U+2000 - U+206F // General Punctuation 906 * U+2070 - U+209F // Superscripts and Subscripts 907 * U+20A0 - U+20CF // Currency Symbols 908 * U+2150 - U+218F // Number Forms 909 * U+2460 - U+24FF // Enclosed Alphanumerics 910 * U+2C60 - U+2C7F // Latin Extended-C 911 * U+2DE0 - U+2DFF // Cyrillic Extended-A 912 * U+2E00 - U+2E7F // Supplemental Punctuation 913 * U+A640 - U+A69F // Cyrillic Extended-B 914 * U+A720 - U+A7FF // Latin Extended-D 915 * U+FB00 - U+FB06 // Alphab. Present. Forms (Latin Ligatures) 916 * U+1D400 - U+1D7FF // Mathematical Alphanumeric Symbols 917 * U+1F100 - U+1F1FF // Enclosed Alphanumeric Supplement 918 * } 919 * 920 * FT_AUTOHINTER_SCRIPT_CJK :: 921 * Apply the CJK auto-hinter, covering Chinese, Japanese, Korean, old 922 * Vietnamese, and some other scripts. 923 * 924 * By default, characters from the following Unicode ranges are 925 * assigned to this submodule. 926 * 927 * { 928 * U+1100 - U+11FF // Hangul Jamo 929 * U+2E80 - U+2EFF // CJK Radicals Supplement 930 * U+2F00 - U+2FDF // Kangxi Radicals 931 * U+2FF0 - U+2FFF // Ideographic Description Characters 932 * U+3000 - U+303F // CJK Symbols and Punctuation 933 * U+3040 - U+309F // Hiragana 934 * U+30A0 - U+30FF // Katakana 935 * U+3100 - U+312F // Bopomofo 936 * U+3130 - U+318F // Hangul Compatibility Jamo 937 * U+3190 - U+319F // Kanbun 938 * U+31A0 - U+31BF // Bopomofo Extended 939 * U+31C0 - U+31EF // CJK Strokes 940 * U+31F0 - U+31FF // Katakana Phonetic Extensions 941 * U+3200 - U+32FF // Enclosed CJK Letters and Months 942 * U+3300 - U+33FF // CJK Compatibility 943 * U+3400 - U+4DBF // CJK Unified Ideographs Extension A 944 * U+4DC0 - U+4DFF // Yijing Hexagram Symbols 945 * U+4E00 - U+9FFF // CJK Unified Ideographs 946 * U+A960 - U+A97F // Hangul Jamo Extended-A 947 * U+AC00 - U+D7AF // Hangul Syllables 948 * U+D7B0 - U+D7FF // Hangul Jamo Extended-B 949 * U+F900 - U+FAFF // CJK Compatibility Ideographs 950 * U+FE10 - U+FE1F // Vertical forms 951 * U+FE30 - U+FE4F // CJK Compatibility Forms 952 * U+FF00 - U+FFEF // Halfwidth and Fullwidth Forms 953 * U+1B000 - U+1B0FF // Kana Supplement 954 * U+1D300 - U+1D35F // Tai Xuan Hing Symbols 955 * U+1F200 - U+1F2FF // Enclosed Ideographic Supplement 956 * U+20000 - U+2A6DF // CJK Unified Ideographs Extension B 957 * U+2A700 - U+2B73F // CJK Unified Ideographs Extension C 958 * U+2B740 - U+2B81F // CJK Unified Ideographs Extension D 959 * U+2F800 - U+2FA1F // CJK Compatibility Ideographs Supplement 960 * } 961 * 962 * FT_AUTOHINTER_SCRIPT_INDIC :: 963 * Apply the indic auto-hinter, covering all major scripts from the 964 * Indian sub-continent and some other related scripts like Thai, Lao, 965 * or Tibetan. 966 * 967 * By default, characters from the following Unicode ranges are 968 * assigned to this submodule. 969 * 970 * { 971 * U+0900 - U+0DFF // Indic Range 972 * U+0F00 - U+0FFF // Tibetan 973 * U+1900 - U+194F // Limbu 974 * U+1B80 - U+1BBF // Sundanese 975 * U+A800 - U+A82F // Syloti Nagri 976 * U+ABC0 - U+ABFF // Meetei Mayek 977 * U+11800 - U+118DF // Sharada 978 * } 979 * 980 * Note that currently Indic support is rudimentary only, missing blue 981 * zone support. 982 * 983 * @since: 984 * 2.4.11 985 * 986 */ 987 #define FT_AUTOHINTER_SCRIPT_NONE 0 988 #define FT_AUTOHINTER_SCRIPT_LATIN 1 989 #define FT_AUTOHINTER_SCRIPT_CJK 2 990 #define FT_AUTOHINTER_SCRIPT_INDIC 3 991 992 993 /************************************************************************** 994 * 995 * @struct: 996 * FT_Prop_GlyphToScriptMap 997 * 998 * @description: 999 * *Experimental* *only* 1000 * 1001 * The data exchange structure for the @glyph-to-script-map property. 1002 * 1003 * @since: 1004 * 2.4.11 1005 * 1006 */ 1007 typedef struct FT_Prop_GlyphToScriptMap_ 1008 { 1009 FT_Face face; 1010 FT_UShort* map; 1011 1012 } FT_Prop_GlyphToScriptMap; 1013 1014 1015 /************************************************************************** 1016 * 1017 * @property: 1018 * fallback-script 1019 * 1020 * @description: 1021 * *Experimental* *only* 1022 * 1023 * If no auto-hinter script module can be assigned to a glyph, a 1024 * fallback script gets assigned to it (see also the 1025 * @glyph-to-script-map property). By default, this is 1026 * @FT_AUTOHINTER_SCRIPT_CJK. Using the `fallback-script' property, 1027 * this fallback value can be changed. 1028 * 1029 * { 1030 * FT_Library library; 1031 * FT_UInt fallback_script = FT_AUTOHINTER_SCRIPT_NONE; 1032 * 1033 * 1034 * FT_Init_FreeType( &library ); 1035 * 1036 * FT_Property_Set( library, "autofitter", 1037 * "fallback-script", &fallback_script ); 1038 * } 1039 * 1040 * @note: 1041 * This property can be used with @FT_Property_Get also. 1042 * 1043 * It's important to use the right timing for changing this value: The 1044 * creation of the glyph-to-script map that eventually uses the 1045 * fallback script value gets triggered either by setting or reading a 1046 * face-specific property like @glyph-to-script-map, or by auto-hinting 1047 * any glyph from that face. In particular, if you have already created 1048 * an @FT_Face structure but not loaded any glyph (using the 1049 * auto-hinter), a change of the fallback script will affect this face. 1050 * 1051 * @since: 1052 * 2.4.11 1053 * 1054 */ 1055 1056 1057 /************************************************************************** 1058 * 1059 * @property: 1060 * default-script 1061 * 1062 * @description: 1063 * *Experimental* *only* 1064 * 1065 * If FreeType gets compiled with FT_CONFIG_OPTION_USE_HARFBUZZ to make 1066 * the HarfBuzz library access OpenType features for getting better 1067 * glyph coverages, this property sets the (auto-fitter) script to be 1068 * used for the default (OpenType) script data of a font's GSUB table. 1069 * Features for the default script are intended for all scripts not 1070 * explicitly handled in GSUB; an example is a `dlig' feature, 1071 * containing the combination of the characters `T', `E', and `L' to 1072 * form a `TEL' ligature. 1073 * 1074 * By default, this is @FT_AUTOHINTER_SCRIPT_LATIN. Using the 1075 * `default-script' property, this default value can be changed. 1076 * 1077 * { 1078 * FT_Library library; 1079 * FT_UInt default_script = FT_AUTOHINTER_SCRIPT_NONE; 1080 * 1081 * 1082 * FT_Init_FreeType( &library ); 1083 * 1084 * FT_Property_Set( library, "autofitter", 1085 * "default-script", &default_script ); 1086 * } 1087 * 1088 * @note: 1089 * This property can be used with @FT_Property_Get also. 1090 * 1091 * It's important to use the right timing for changing this value: The 1092 * creation of the glyph-to-script map that eventually uses the 1093 * default script value gets triggered either by setting or reading a 1094 * face-specific property like @glyph-to-script-map, or by auto-hinting 1095 * any glyph from that face. In particular, if you have already created 1096 * an @FT_Face structure but not loaded any glyph (using the 1097 * auto-hinter), a change of the default script will affect this face. 1098 * 1099 * @since: 1100 * 2.5.3 1101 * 1102 */ 1103 1104 1105 /************************************************************************** 1106 * 1107 * @property: 1108 * increase-x-height 1109 * 1110 * @description: 1111 * For ppem values in the range 6~<= ppem <= `increase-x-height', round 1112 * up the font's x~height much more often than normally. If the value 1113 * is set to~0, which is the default, this feature is switched off. Use 1114 * this property to improve the legibility of small font sizes if 1115 * necessary. 1116 * 1117 * { 1118 * FT_Library library; 1119 * FT_Face face; 1120 * FT_Prop_IncreaseXHeight prop; 1121 * 1122 * 1123 * FT_Init_FreeType( &library ); 1124 * FT_New_Face( library, "foo.ttf", 0, &face ); 1125 * FT_Set_Char_Size( face, 10 * 64, 0, 72, 0 ); 1126 * 1127 * prop.face = face; 1128 * prop.limit = 14; 1129 * 1130 * FT_Property_Set( library, "autofitter", 1131 * "increase-x-height", &prop ); 1132 * } 1133 * 1134 * @note: 1135 * This property can be used with @FT_Property_Get also. 1136 * 1137 * Set this value right after calling @FT_Set_Char_Size, but before 1138 * loading any glyph (using the auto-hinter). 1139 * 1140 * @since: 1141 * 2.4.11 1142 * 1143 */ 1144 1145 1146 /************************************************************************** 1147 * 1148 * @struct: 1149 * FT_Prop_IncreaseXHeight 1150 * 1151 * @description: 1152 * The data exchange structure for the @increase-x-height property. 1153 * 1154 */ 1155 typedef struct FT_Prop_IncreaseXHeight_ 1156 { 1157 FT_Face face; 1158 FT_UInt limit; 1159 1160 } FT_Prop_IncreaseXHeight; 1161 1162 1163 /************************************************************************** 1164 * 1165 * @property: 1166 * warping 1167 * 1168 * @description: 1169 * *Experimental* *only* 1170 * 1171 * If FreeType gets compiled with option AF_CONFIG_OPTION_USE_WARPER to 1172 * activate the warp hinting code in the auto-hinter, this property 1173 * switches warping on and off. 1174 * 1175 * Warping only works in `normal' auto-hinting mode replacing it. 1176 * The idea of the code is to slightly scale and shift a glyph along 1177 * the non-hinted dimension (which is usually the horizontal axis) so 1178 * that as much of its segments are aligned (more or less) to the grid. 1179 * To find out a glyph's optimal scaling and shifting value, various 1180 * parameter combinations are tried and scored. 1181 * 1182 * By default, warping is off. The example below shows how to switch on 1183 * warping (omitting the error handling). 1184 * 1185 * { 1186 * FT_Library library; 1187 * FT_Bool warping = 1; 1188 * 1189 * 1190 * FT_Init_FreeType( &library ); 1191 * 1192 * FT_Property_Set( library, "autofitter", 1193 * "warping", &warping ); 1194 * } 1195 * 1196 * @note: 1197 * This property can be used with @FT_Property_Get also. 1198 * 1199 * This property can be set via the `FREETYPE_PROPERTIES' environment 1200 * variable (using values 1 and 0 for `on' and `off', respectively). 1201 * 1202 * The warping code can also change advance widths. Have a look at the 1203 * `lsb_delta' and `rsb_delta' fields in the @FT_GlyphSlotRec structure 1204 * for details on improving inter-glyph distances while rendering. 1205 * 1206 * Since warping is a global property of the auto-hinter it is best to 1207 * change its value before rendering any face. Otherwise, you should 1208 * reload all faces that get auto-hinted in `normal' hinting mode. 1209 * 1210 * @since: 1211 * 2.6 1212 * 1213 */ 1214 1215 1216 /* */ 1217 1218 1219 FT_END_HEADER 1220 1221 1222 #endif /* FTDRIVER_H_ */ 1223 1224 1225 /* END */ 1226
