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 subpixels 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 subpixels 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 * @note: 375 * This property can be used with @FT_Property_Get also. 376 * 377 * This property can be set via the `FREETYPE_PROPERTIES' environment 378 * variable (using values `adobe' or `freetype'). 379 * 380 * @example: 381 * The following example code demonstrates how to select Adobe's hinting 382 * engine for the `cff' module (omitting the error handling). 383 * 384 * { 385 * FT_Library library; 386 * FT_UInt hinting_engine = FT_CFF_HINTING_ADOBE; 387 * 388 * 389 * FT_Init_FreeType( &library ); 390 * 391 * FT_Property_Set( library, "cff", 392 * "hinting-engine", &hinting_engine ); 393 * } 394 * 395 * @since: 396 * 2.4.12 (for `cff' module) 397 * 398 * 2.9 (for `type1' and `t1cid' modules) 399 * 400 */ 401 402 403 /************************************************************************** 404 * 405 * @property: 406 * no-stem-darkening 407 * 408 * @description: 409 * All glyphs that pass through the auto-hinter will be emboldened 410 * unless this property is set to TRUE. The same is true for the CFF, 411 * Type~1, and CID font modules if the `Adobe' engine is selected (which 412 * is the default). 413 * 414 * Stem darkening emboldens glyphs at smaller sizes to make them more 415 * readable on common low-DPI screens when using linear alpha blending 416 * and gamma correction, see @FT_Render_Glyph. When not using linear 417 * alpha blending and gamma correction, glyphs will appear heavy and 418 * fuzzy! 419 * 420 * Gamma correction essentially lightens fonts since shades of grey are 421 * shifted to higher pixel values (=~higher brightness) to match the 422 * original intention to the reality of our screens. The side-effect is 423 * that glyphs `thin out'. Mac OS~X and Adobe's proprietary font 424 * rendering library implement a counter-measure: stem darkening at 425 * smaller sizes where shades of gray dominate. By emboldening a glyph 426 * slightly in relation to its pixel size, individual pixels get higher 427 * coverage of filled-in outlines and are therefore `blacker'. This 428 * counteracts the `thinning out' of glyphs, making text remain readable 429 * at smaller sizes. 430 * 431 * By default, the Adobe engines for CFF, Type~1, and CID fonts darken 432 * stems at smaller sizes, regardless of hinting, to enhance contrast. 433 * Setting this property, stem darkening gets switched off. 434 * 435 * For the auto-hinter, stem-darkening is experimental currently and 436 * thus switched off by default (this is, `no-stem-darkening' is set to 437 * TRUE by default). Total consistency with the CFF driver is not 438 * achieved right now because the emboldening method differs and glyphs 439 * must be scaled down on the Y-axis to keep outline points inside their 440 * precomputed blue zones. The smaller the size (especially 9ppem and 441 * down), the higher the loss of emboldening versus the CFF driver. 442 * 443 * Note that stem darkening is never applied if @FT_LOAD_NO_SCALE is 444 * set. 445 * 446 * @note: 447 * This property can be used with @FT_Property_Get also. 448 * 449 * This property can be set via the `FREETYPE_PROPERTIES' environment 450 * variable (using values 1 and 0 for `on' and `off', respectively). 451 * It can also be set per face using @FT_Face_Properties with 452 * @FT_PARAM_TAG_STEM_DARKENING. 453 * 454 * @example: 455 * { 456 * FT_Library library; 457 * FT_Bool no_stem_darkening = TRUE; 458 * 459 * 460 * FT_Init_FreeType( &library ); 461 * 462 * FT_Property_Set( library, "cff", 463 * "no-stem-darkening", &no_stem_darkening ); 464 * } 465 * 466 * @since: 467 * 2.4.12 (for `cff' module) 468 * 469 * 2.6.2 (for `autofitter' module) 470 * 471 * 2.9 (for `type1' and `t1cid' modules) 472 * 473 */ 474 475 476 /************************************************************************** 477 * 478 * @property: 479 * darkening-parameters 480 * 481 * @description: 482 * By default, the Adobe hinting engine, as used by the CFF, Type~1, and 483 * CID font drivers, darkens stems as follows (if the 484 * `no-stem-darkening' property isn't set): 485 * 486 * { 487 * stem width <= 0.5px: darkening amount = 0.4px 488 * stem width = 1px: darkening amount = 0.275px 489 * stem width = 1.667px: darkening amount = 0.275px 490 * stem width >= 2.333px: darkening amount = 0px 491 * } 492 * 493 * and piecewise linear in-between. At configuration time, these four 494 * control points can be set with the macro 495 * `CFF_CONFIG_OPTION_DARKENING_PARAMETERS'; the CFF, Type~1, and CID 496 * drivers share these values. At runtime, the control points can be 497 * changed using the `darkening-parameters' property (see the example 498 * below that demonstrates this for the Type~1 driver). 499 * 500 * The x~values give the stem width, and the y~values the darkening 501 * amount. The unit is 1000th of pixels. All coordinate values must be 502 * positive; the x~values must be monotonically increasing; the 503 * y~values must be monotonically decreasing and smaller than or 504 * equal to 500 (corresponding to half a pixel); the slope of each 505 * linear piece must be shallower than -1 (e.g., -.4). 506 * 507 * The auto-hinter provides this property, too, as an experimental 508 * feature. See @no-stem-darkening for more. 509 * 510 * @note: 511 * This property can be used with @FT_Property_Get also. 512 * 513 * This property can be set via the `FREETYPE_PROPERTIES' environment 514 * variable, using eight comma-separated integers without spaces. Here 515 * the above example, using `\' to break the line for readability. 516 * 517 * { 518 * FREETYPE_PROPERTIES=\ 519 * type1:darkening-parameters=500,300,1000,200,1500,100,2000,0 520 * } 521 * 522 * @example: 523 * { 524 * FT_Library library; 525 * FT_Int darken_params[8] = { 500, 300, // x1, y1 526 * 1000, 200, // x2, y2 527 * 1500, 100, // x3, y3 528 * 2000, 0 }; // x4, y4 529 * 530 * 531 * FT_Init_FreeType( &library ); 532 * 533 * FT_Property_Set( library, "type1", 534 * "darkening-parameters", darken_params ); 535 * } 536 * 537 * @since: 538 * 2.5.1 (for `cff' module) 539 * 540 * 2.6.2 (for `autofitter' module) 541 * 542 * 2.9 (for `type1' and `t1cid' modules) 543 * 544 */ 545 546 547 /************************************************************************** 548 * 549 * @property: 550 * random-seed 551 * 552 * @description: 553 * By default, the seed value for the CFF `random' operator and the 554 * similar `0 28 callothersubr pop' command for the Type~1 and CID 555 * drivers is set to a random value. However, mainly for debugging 556 * purposes, it is often necessary to use a known value as a seed so 557 * that the pseudo-random number sequences generated by `random' are 558 * repeatable. 559 * 560 * The `random-seed' property does that. Its argument is a signed 32bit 561 * integer; if the value is zero or negative, the seed given by the 562 * `intitialRandomSeed' private DICT operator in a CFF file gets used 563 * (or a default value if there is no such operator). If the value is 564 * positive, use it instead of `initialRandomSeed', which is 565 * consequently ignored. 566 * 567 * @note: 568 * This property can be set via the `FREETYPE_PROPERTIES' environment 569 * variable. It can also be set per face using @FT_Face_Properties with 570 * @FT_PARAM_TAG_RANDOM_SEED. 571 * 572 * @since: 573 * 2.8 (for `cff' module) 574 * 575 * 2.9 (for `type1' and `t1cid' modules) 576 * 577 */ 578 579 580 /************************************************************************** 581 * 582 * @property: 583 * no-long-family-names 584 * 585 * @description: 586 * If PCF_CONFIG_OPTION_LONG_FAMILY_NAMES is active while compiling 587 * FreeType, the PCF driver constructs long family names. 588 * 589 * There are many PCF fonts just called `Fixed' which look completely 590 * different, and which have nothing to do with each other. When 591 * selecting `Fixed' in KDE or Gnome one gets results that appear rather 592 * random, the style changes often if one changes the size and one 593 * cannot select some fonts at all. The improve this situation, the PCF 594 * module prepends the foundry name (plus a space) to the family name. 595 * It also checks whether there are `wide' characters; all put together, 596 * family names like `Sony Fixed' or `Misc Fixed Wide' are constructed. 597 * 598 * If `no-long-family-names' is set, this feature gets switched off. 599 * 600 * @note: 601 * This property can be used with @FT_Property_Get also. 602 * 603 * This property can be set via the `FREETYPE_PROPERTIES' environment 604 * variable (using values 1 and 0 for `on' and `off', respectively). 605 * 606 * @example: 607 * { 608 * FT_Library library; 609 * FT_Bool no_long_family_names = TRUE; 610 * 611 * 612 * FT_Init_FreeType( &library ); 613 * 614 * FT_Property_Set( library, "pcf", 615 * "no-long-family-names", 616 * &no_long_family_names ); 617 * } 618 * 619 * @since: 620 * 2.8 621 */ 622 623 624 /************************************************************************** 625 * 626 * @enum: 627 * TT_INTERPRETER_VERSION_XXX 628 * 629 * @description: 630 * A list of constants used for the @interpreter-version property to 631 * select the hinting engine for Truetype fonts. 632 * 633 * The numeric value in the constant names represents the version 634 * number as returned by the `GETINFO' bytecode instruction. 635 * 636 * @values: 637 * TT_INTERPRETER_VERSION_35 :: 638 * Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in 639 * Windows~98; only grayscale and B/W rasterizing is supported. 640 * 641 * TT_INTERPRETER_VERSION_38 :: 642 * Version~38 corresponds to MS rasterizer v.1.9; it is roughly 643 * equivalent to the hinting provided by DirectWrite ClearType (as can 644 * be found, for example, in the Internet Explorer~9 running on 645 * Windows~7). It is used in FreeType to select the `Infinality' 646 * subpixel hinting code. The code may be removed in a future 647 * version. 648 * 649 * TT_INTERPRETER_VERSION_40 :: 650 * Version~40 corresponds to MS rasterizer v.2.1; it is roughly 651 * equivalent to the hinting provided by DirectWrite ClearType (as can 652 * be found, for example, in Microsoft's Edge Browser on Windows~10). 653 * It is used in FreeType to select the `minimal' subpixel hinting 654 * code, a stripped-down and higher performance version of the 655 * `Infinality' code. 656 * 657 * @note: 658 * This property controls the behaviour of the bytecode interpreter 659 * and thus how outlines get hinted. It does *not* control how glyph 660 * get rasterized! In particular, it does not control subpixel color 661 * filtering. 662 * 663 * If FreeType has not been compiled with the configuration option 664 * TT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 or~40 causes 665 * an `FT_Err_Unimplemented_Feature' error. 666 * 667 * Depending on the graphics framework, Microsoft uses different 668 * bytecode and rendering engines. As a consequence, the version 669 * numbers returned by a call to the `GETINFO' bytecode instruction are 670 * more convoluted than desired. 671 * 672 * Here are two tables that try to shed some light on the possible 673 * values for the MS rasterizer engine, together with the additional 674 * features introduced by it. 675 * 676 * { 677 * GETINFO framework version feature 678 * ------------------------------------------------------------------- 679 * 3 GDI (Win 3.1), v1.0 16-bit, first version 680 * TrueImage 681 * 33 GDI (Win NT 3.1), v1.5 32-bit 682 * HP Laserjet 683 * 34 GDI (Win 95) v1.6 font smoothing, 684 * new SCANTYPE opcode 685 * 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET 686 * bits in composite glyphs 687 * 36 MGDI (Win CE 2) v1.6+ classic ClearType 688 * 37 GDI (XP and later), v1.8 ClearType 689 * GDI+ old (before Vista) 690 * 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType, 691 * WPF Y-direction ClearType, 692 * additional error checking 693 * 39 DWrite (before Win 8) v2.0 subpixel ClearType flags 694 * in GETINFO opcode, 695 * bug fixes 696 * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag 697 * DWrite (Win 8) in GETINFO opcode, 698 * Gray ClearType 699 * } 700 * 701 * The `version' field gives a rough orientation only, since some 702 * applications provided certain features much earlier (as an example, 703 * Microsoft Reader used subpixel and Y-direction ClearType already in 704 * Windows 2000). Similarly, updates to a given framework might include 705 * improved hinting support. 706 * 707 * { 708 * version sampling rendering comment 709 * x y x y 710 * -------------------------------------------------------------- 711 * v1.0 normal normal B/W B/W bi-level 712 * v1.6 high high gray gray grayscale 713 * v1.8 high normal color-filter B/W (GDI) ClearType 714 * v1.9 high high color-filter gray Color ClearType 715 * v2.1 high normal gray B/W Gray ClearType 716 * v2.1 high high gray gray Gray ClearType 717 * } 718 * 719 * Color and Gray ClearType are the two available variants of 720 * `Y-direction ClearType', meaning grayscale rasterization along the 721 * Y-direction; the name used in the TrueType specification for this 722 * feature is `symmetric smoothing'. `Classic ClearType' is the 723 * original algorithm used before introducing a modified version in 724 * Win~XP. Another name for v1.6's grayscale rendering is `font 725 * smoothing', and `Color ClearType' is sometimes also called `DWrite 726 * ClearType'. To differentiate between today's Color ClearType and the 727 * earlier ClearType variant with B/W rendering along the vertical axis, 728 * the latter is sometimes called `GDI ClearType'. 729 * 730 * `Normal' and `high' sampling describe the (virtual) resolution to 731 * access the rasterized outline after the hinting process. `Normal' 732 * means 1 sample per grid line (i.e., B/W). In the current Microsoft 733 * implementation, `high' means an extra virtual resolution of 16x16 (or 734 * 16x1) grid lines per pixel for bytecode instructions like `MIRP'. 735 * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid 736 * lines for color filtering if Color ClearType is activated. 737 * 738 * Note that `Gray ClearType' is essentially the same as v1.6's 739 * grayscale rendering. However, the GETINFO instruction handles it 740 * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1 741 * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing), 742 * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for 743 * the version~1 gasp table exclusively (like Color ClearType), while 744 * v1.6 only respects the values of version~0 (bits 0 and~1). 745 * 746 * Keep in mind that the features of the above interpreter versions 747 * might not map exactly to FreeType features or behavior because it is 748 * a fundamentally different library with different internals. 749 * 750 */ 751 #define TT_INTERPRETER_VERSION_35 35 752 #define TT_INTERPRETER_VERSION_38 38 753 #define TT_INTERPRETER_VERSION_40 40 754 755 756 /************************************************************************** 757 * 758 * @property: 759 * interpreter-version 760 * 761 * @description: 762 * Currently, three versions are available, two representing the 763 * bytecode interpreter with subpixel hinting support (old `Infinality' 764 * code and new stripped-down and higher performance `minimal' code) and 765 * one without, respectively. The default is subpixel support if 766 * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel support 767 * otherwise (since it isn't available then). 768 * 769 * If subpixel hinting is on, many TrueType bytecode instructions behave 770 * differently compared to B/W or grayscale rendering (except if `native 771 * ClearType' is selected by the font). Microsoft's main idea is to 772 * render at a much increased horizontal resolution, then sampling down 773 * the created output to subpixel precision. However, many older fonts 774 * are not suited to this and must be specially taken care of by 775 * applying (hardcoded) tweaks in Microsoft's interpreter. 776 * 777 * Details on subpixel hinting and some of the necessary tweaks can be 778 * found in Greg Hitchcock's whitepaper at 779 * `https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. 780 * Note that FreeType currently doesn't really `subpixel hint' (6x1, 6x2, 781 * or 6x5 supersampling) like discussed in the paper. Depending on the 782 * chosen interpreter, it simply ignores instructions on vertical stems 783 * to arrive at very similar results. 784 * 785 * @note: 786 * This property can be used with @FT_Property_Get also. 787 * 788 * This property can be set via the `FREETYPE_PROPERTIES' environment 789 * variable (using values `35', `38', or `40'). 790 * 791 * @example: 792 * The following example code demonstrates how to deactivate subpixel 793 * hinting (omitting the error handling). 794 * 795 * { 796 * FT_Library library; 797 * FT_Face face; 798 * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_35; 799 * 800 * 801 * FT_Init_FreeType( &library ); 802 * 803 * FT_Property_Set( library, "truetype", 804 * "interpreter-version", 805 * &interpreter_version ); 806 * } 807 * 808 * @since: 809 * 2.5 810 */ 811 812 813 /************************************************************************** 814 * 815 * @property: 816 * glyph-to-script-map 817 * 818 * @description: 819 * *Experimental* *only* 820 * 821 * The auto-hinter provides various script modules to hint glyphs. 822 * Examples of supported scripts are Latin or CJK. Before a glyph is 823 * auto-hinted, the Unicode character map of the font gets examined, and 824 * the script is then determined based on Unicode character ranges, see 825 * below. 826 * 827 * OpenType fonts, however, often provide much more glyphs than 828 * character codes (small caps, superscripts, ligatures, swashes, etc.), 829 * to be controlled by so-called `features'. Handling OpenType features 830 * can be quite complicated and thus needs a separate library on top of 831 * FreeType. 832 * 833 * The mapping between glyph indices and scripts (in the auto-hinter 834 * sense, see the @FT_AUTOHINTER_SCRIPT_XXX values) is stored as an 835 * array with `num_glyphs' elements, as found in the font's @FT_Face 836 * structure. The `glyph-to-script-map' property returns a pointer to 837 * this array, which can be modified as needed. Note that the 838 * modification should happen before the first glyph gets processed by 839 * the auto-hinter so that the global analysis of the font shapes 840 * actually uses the modified mapping. 841 * 842 * @example: 843 * The following example code demonstrates how to access it (omitting 844 * the error handling). 845 * 846 * { 847 * FT_Library library; 848 * FT_Face face; 849 * FT_Prop_GlyphToScriptMap prop; 850 * 851 * 852 * FT_Init_FreeType( &library ); 853 * FT_New_Face( library, "foo.ttf", 0, &face ); 854 * 855 * prop.face = face; 856 * 857 * FT_Property_Get( library, "autofitter", 858 * "glyph-to-script-map", &prop ); 859 * 860 * // adjust `prop.map' as needed right here 861 * 862 * FT_Load_Glyph( face, ..., FT_LOAD_FORCE_AUTOHINT ); 863 * } 864 * 865 * @since: 866 * 2.4.11 867 * 868 */ 869 870 871 /************************************************************************** 872 * 873 * @enum: 874 * FT_AUTOHINTER_SCRIPT_XXX 875 * 876 * @description: 877 * *Experimental* *only* 878 * 879 * A list of constants used for the @glyph-to-script-map property to 880 * specify the script submodule the auto-hinter should use for hinting a 881 * particular glyph. 882 * 883 * @values: 884 * FT_AUTOHINTER_SCRIPT_NONE :: 885 * Don't auto-hint this glyph. 886 * 887 * FT_AUTOHINTER_SCRIPT_LATIN :: 888 * Apply the latin auto-hinter. For the auto-hinter, `latin' is a 889 * very broad term, including Cyrillic and Greek also since characters 890 * from those scripts share the same design constraints. 891 * 892 * By default, characters from the following Unicode ranges are 893 * assigned to this submodule. 894 * 895 * { 896 * U+0020 - U+007F // Basic Latin (no control characters) 897 * U+00A0 - U+00FF // Latin-1 Supplement (no control characters) 898 * U+0100 - U+017F // Latin Extended-A 899 * U+0180 - U+024F // Latin Extended-B 900 * U+0250 - U+02AF // IPA Extensions 901 * U+02B0 - U+02FF // Spacing Modifier Letters 902 * U+0300 - U+036F // Combining Diacritical Marks 903 * U+0370 - U+03FF // Greek and Coptic 904 * U+0400 - U+04FF // Cyrillic 905 * U+0500 - U+052F // Cyrillic Supplement 906 * U+1D00 - U+1D7F // Phonetic Extensions 907 * U+1D80 - U+1DBF // Phonetic Extensions Supplement 908 * U+1DC0 - U+1DFF // Combining Diacritical Marks Supplement 909 * U+1E00 - U+1EFF // Latin Extended Additional 910 * U+1F00 - U+1FFF // Greek Extended 911 * U+2000 - U+206F // General Punctuation 912 * U+2070 - U+209F // Superscripts and Subscripts 913 * U+20A0 - U+20CF // Currency Symbols 914 * U+2150 - U+218F // Number Forms 915 * U+2460 - U+24FF // Enclosed Alphanumerics 916 * U+2C60 - U+2C7F // Latin Extended-C 917 * U+2DE0 - U+2DFF // Cyrillic Extended-A 918 * U+2E00 - U+2E7F // Supplemental Punctuation 919 * U+A640 - U+A69F // Cyrillic Extended-B 920 * U+A720 - U+A7FF // Latin Extended-D 921 * U+FB00 - U+FB06 // Alphab. Present. Forms (Latin Ligatures) 922 * U+1D400 - U+1D7FF // Mathematical Alphanumeric Symbols 923 * U+1F100 - U+1F1FF // Enclosed Alphanumeric Supplement 924 * } 925 * 926 * FT_AUTOHINTER_SCRIPT_CJK :: 927 * Apply the CJK auto-hinter, covering Chinese, Japanese, Korean, old 928 * Vietnamese, and some other scripts. 929 * 930 * By default, characters from the following Unicode ranges are 931 * assigned to this submodule. 932 * 933 * { 934 * U+1100 - U+11FF // Hangul Jamo 935 * U+2E80 - U+2EFF // CJK Radicals Supplement 936 * U+2F00 - U+2FDF // Kangxi Radicals 937 * U+2FF0 - U+2FFF // Ideographic Description Characters 938 * U+3000 - U+303F // CJK Symbols and Punctuation 939 * U+3040 - U+309F // Hiragana 940 * U+30A0 - U+30FF // Katakana 941 * U+3100 - U+312F // Bopomofo 942 * U+3130 - U+318F // Hangul Compatibility Jamo 943 * U+3190 - U+319F // Kanbun 944 * U+31A0 - U+31BF // Bopomofo Extended 945 * U+31C0 - U+31EF // CJK Strokes 946 * U+31F0 - U+31FF // Katakana Phonetic Extensions 947 * U+3200 - U+32FF // Enclosed CJK Letters and Months 948 * U+3300 - U+33FF // CJK Compatibility 949 * U+3400 - U+4DBF // CJK Unified Ideographs Extension A 950 * U+4DC0 - U+4DFF // Yijing Hexagram Symbols 951 * U+4E00 - U+9FFF // CJK Unified Ideographs 952 * U+A960 - U+A97F // Hangul Jamo Extended-A 953 * U+AC00 - U+D7AF // Hangul Syllables 954 * U+D7B0 - U+D7FF // Hangul Jamo Extended-B 955 * U+F900 - U+FAFF // CJK Compatibility Ideographs 956 * U+FE10 - U+FE1F // Vertical forms 957 * U+FE30 - U+FE4F // CJK Compatibility Forms 958 * U+FF00 - U+FFEF // Halfwidth and Fullwidth Forms 959 * U+1B000 - U+1B0FF // Kana Supplement 960 * U+1D300 - U+1D35F // Tai Xuan Hing Symbols 961 * U+1F200 - U+1F2FF // Enclosed Ideographic Supplement 962 * U+20000 - U+2A6DF // CJK Unified Ideographs Extension B 963 * U+2A700 - U+2B73F // CJK Unified Ideographs Extension C 964 * U+2B740 - U+2B81F // CJK Unified Ideographs Extension D 965 * U+2F800 - U+2FA1F // CJK Compatibility Ideographs Supplement 966 * } 967 * 968 * FT_AUTOHINTER_SCRIPT_INDIC :: 969 * Apply the indic auto-hinter, covering all major scripts from the 970 * Indian sub-continent and some other related scripts like Thai, Lao, 971 * or Tibetan. 972 * 973 * By default, characters from the following Unicode ranges are 974 * assigned to this submodule. 975 * 976 * { 977 * U+0900 - U+0DFF // Indic Range 978 * U+0F00 - U+0FFF // Tibetan 979 * U+1900 - U+194F // Limbu 980 * U+1B80 - U+1BBF // Sundanese 981 * U+A800 - U+A82F // Syloti Nagri 982 * U+ABC0 - U+ABFF // Meetei Mayek 983 * U+11800 - U+118DF // Sharada 984 * } 985 * 986 * Note that currently Indic support is rudimentary only, missing blue 987 * zone support. 988 * 989 * @since: 990 * 2.4.11 991 * 992 */ 993 #define FT_AUTOHINTER_SCRIPT_NONE 0 994 #define FT_AUTOHINTER_SCRIPT_LATIN 1 995 #define FT_AUTOHINTER_SCRIPT_CJK 2 996 #define FT_AUTOHINTER_SCRIPT_INDIC 3 997 998 999 /************************************************************************** 1000 * 1001 * @struct: 1002 * FT_Prop_GlyphToScriptMap 1003 * 1004 * @description: 1005 * *Experimental* *only* 1006 * 1007 * The data exchange structure for the @glyph-to-script-map property. 1008 * 1009 * @since: 1010 * 2.4.11 1011 * 1012 */ 1013 typedef struct FT_Prop_GlyphToScriptMap_ 1014 { 1015 FT_Face face; 1016 FT_UShort* map; 1017 1018 } FT_Prop_GlyphToScriptMap; 1019 1020 1021 /************************************************************************** 1022 * 1023 * @property: 1024 * fallback-script 1025 * 1026 * @description: 1027 * *Experimental* *only* 1028 * 1029 * If no auto-hinter script module can be assigned to a glyph, a 1030 * fallback script gets assigned to it (see also the 1031 * @glyph-to-script-map property). By default, this is 1032 * @FT_AUTOHINTER_SCRIPT_CJK. Using the `fallback-script' property, 1033 * this fallback value can be changed. 1034 * 1035 * @note: 1036 * This property can be used with @FT_Property_Get also. 1037 * 1038 * It's important to use the right timing for changing this value: The 1039 * creation of the glyph-to-script map that eventually uses the 1040 * fallback script value gets triggered either by setting or reading a 1041 * face-specific property like @glyph-to-script-map, or by auto-hinting 1042 * any glyph from that face. In particular, if you have already created 1043 * an @FT_Face structure but not loaded any glyph (using the 1044 * auto-hinter), a change of the fallback script will affect this face. 1045 * 1046 * @example: 1047 * { 1048 * FT_Library library; 1049 * FT_UInt fallback_script = FT_AUTOHINTER_SCRIPT_NONE; 1050 * 1051 * 1052 * FT_Init_FreeType( &library ); 1053 * 1054 * FT_Property_Set( library, "autofitter", 1055 * "fallback-script", &fallback_script ); 1056 * } 1057 * 1058 * @since: 1059 * 2.4.11 1060 * 1061 */ 1062 1063 1064 /************************************************************************** 1065 * 1066 * @property: 1067 * default-script 1068 * 1069 * @description: 1070 * *Experimental* *only* 1071 * 1072 * If FreeType gets compiled with FT_CONFIG_OPTION_USE_HARFBUZZ to make 1073 * the HarfBuzz library access OpenType features for getting better 1074 * glyph coverages, this property sets the (auto-fitter) script to be 1075 * used for the default (OpenType) script data of a font's GSUB table. 1076 * Features for the default script are intended for all scripts not 1077 * explicitly handled in GSUB; an example is a `dlig' feature, 1078 * containing the combination of the characters `T', `E', and `L' to 1079 * form a `TEL' ligature. 1080 * 1081 * By default, this is @FT_AUTOHINTER_SCRIPT_LATIN. Using the 1082 * `default-script' property, this default value can be changed. 1083 * 1084 * @note: 1085 * This property can be used with @FT_Property_Get also. 1086 * 1087 * It's important to use the right timing for changing this value: The 1088 * creation of the glyph-to-script map that eventually uses the 1089 * default script value gets triggered either by setting or reading a 1090 * face-specific property like @glyph-to-script-map, or by auto-hinting 1091 * any glyph from that face. In particular, if you have already created 1092 * an @FT_Face structure but not loaded any glyph (using the 1093 * auto-hinter), a change of the default script will affect this face. 1094 * 1095 * @example: 1096 * { 1097 * FT_Library library; 1098 * FT_UInt default_script = FT_AUTOHINTER_SCRIPT_NONE; 1099 * 1100 * 1101 * FT_Init_FreeType( &library ); 1102 * 1103 * FT_Property_Set( library, "autofitter", 1104 * "default-script", &default_script ); 1105 * } 1106 * 1107 * @since: 1108 * 2.5.3 1109 * 1110 */ 1111 1112 1113 /************************************************************************** 1114 * 1115 * @property: 1116 * increase-x-height 1117 * 1118 * @description: 1119 * For ppem values in the range 6~<= ppem <= `increase-x-height', round 1120 * up the font's x~height much more often than normally. If the value 1121 * is set to~0, which is the default, this feature is switched off. Use 1122 * this property to improve the legibility of small font sizes if 1123 * necessary. 1124 * 1125 * @note: 1126 * This property can be used with @FT_Property_Get also. 1127 * 1128 * Set this value right after calling @FT_Set_Char_Size, but before 1129 * loading any glyph (using the auto-hinter). 1130 * 1131 * @example: 1132 * { 1133 * FT_Library library; 1134 * FT_Face face; 1135 * FT_Prop_IncreaseXHeight prop; 1136 * 1137 * 1138 * FT_Init_FreeType( &library ); 1139 * FT_New_Face( library, "foo.ttf", 0, &face ); 1140 * FT_Set_Char_Size( face, 10 * 64, 0, 72, 0 ); 1141 * 1142 * prop.face = face; 1143 * prop.limit = 14; 1144 * 1145 * FT_Property_Set( library, "autofitter", 1146 * "increase-x-height", &prop ); 1147 * } 1148 * 1149 * @since: 1150 * 2.4.11 1151 * 1152 */ 1153 1154 1155 /************************************************************************** 1156 * 1157 * @struct: 1158 * FT_Prop_IncreaseXHeight 1159 * 1160 * @description: 1161 * The data exchange structure for the @increase-x-height property. 1162 * 1163 */ 1164 typedef struct FT_Prop_IncreaseXHeight_ 1165 { 1166 FT_Face face; 1167 FT_UInt limit; 1168 1169 } FT_Prop_IncreaseXHeight; 1170 1171 1172 /************************************************************************** 1173 * 1174 * @property: 1175 * warping 1176 * 1177 * @description: 1178 * *Experimental* *only* 1179 * 1180 * If FreeType gets compiled with option AF_CONFIG_OPTION_USE_WARPER to 1181 * activate the warp hinting code in the auto-hinter, this property 1182 * switches warping on and off. 1183 * 1184 * Warping only works in `normal' auto-hinting mode replacing it. 1185 * The idea of the code is to slightly scale and shift a glyph along 1186 * the non-hinted dimension (which is usually the horizontal axis) so 1187 * that as much of its segments are aligned (more or less) to the grid. 1188 * To find out a glyph's optimal scaling and shifting value, various 1189 * parameter combinations are tried and scored. 1190 * 1191 * By default, warping is off. 1192 * 1193 * @note: 1194 * This property can be used with @FT_Property_Get also. 1195 * 1196 * This property can be set via the `FREETYPE_PROPERTIES' environment 1197 * variable (using values 1 and 0 for `on' and `off', respectively). 1198 * 1199 * The warping code can also change advance widths. Have a look at the 1200 * `lsb_delta' and `rsb_delta' fields in the @FT_GlyphSlotRec structure 1201 * for details on improving inter-glyph distances while rendering. 1202 * 1203 * Since warping is a global property of the auto-hinter it is best to 1204 * change its value before rendering any face. Otherwise, you should 1205 * reload all faces that get auto-hinted in `normal' hinting mode. 1206 * 1207 * @example: 1208 * This example shows how to switch on warping (omitting the error 1209 * handling). 1210 * 1211 * { 1212 * FT_Library library; 1213 * FT_Bool warping = 1; 1214 * 1215 * 1216 * FT_Init_FreeType( &library ); 1217 * 1218 * FT_Property_Set( library, "autofitter", "warping", &warping ); 1219 * } 1220 * 1221 * @since: 1222 * 2.6 1223 * 1224 */ 1225 1226 1227 /* */ 1228 1229 1230 FT_END_HEADER 1231 1232 1233 #endif /* FTDRIVER_H_ */ 1234 1235 1236 /* END */ 1237