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
33FT_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 * 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
1219FT_END_HEADER
1220
1221
1222#endif /* FTDRIVER_H_ */
1223
1224
1225/* END */
1226