/***************************************************************************/ | |
/* */ | |
/* ftttdrv.h */ | |
/* */ | |
/* FreeType API for controlling the TrueType driver */ | |
/* (specification only). */ | |
/* */ | |
/* Copyright 2013-2015 by */ | |
/* David Turner, Robert Wilhelm, and Werner Lemberg. */ | |
/* */ | |
/* This file is part of the FreeType project, and may only be used, */ | |
/* modified, and distributed under the terms of the FreeType project */ | |
/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ | |
/* this file you indicate that you have read the license and */ | |
/* understand and accept it fully. */ | |
/* */ | |
/***************************************************************************/ | |
#ifndef __FTTTDRV_H__ | |
#define __FTTTDRV_H__ | |
#include <ft2build.h> | |
#include FT_FREETYPE_H | |
#ifdef FREETYPE_H | |
#error "freetype.h of FreeType 1 has been loaded!" | |
#error "Please fix the directory search order for header files" | |
#error "so that freetype.h of FreeType 2 is found first." | |
#endif | |
FT_BEGIN_HEADER | |
/************************************************************************** | |
* | |
* @section: | |
* tt_driver | |
* | |
* @title: | |
* The TrueType driver | |
* | |
* @abstract: | |
* Controlling the TrueType driver module. | |
* | |
* @description: | |
* While FreeType's TrueType driver doesn't expose API functions by | |
* itself, it is possible to control its behaviour with @FT_Property_Set | |
* and @FT_Property_Get. The following lists the available properties | |
* together with the necessary macros and structures. | |
* | |
* The TrueType driver's module name is `truetype'. | |
* | |
* We start with a list of definitions, kindly provided by Greg | |
* Hitchcock. | |
* | |
* _Bi-Level_ _Rendering_ | |
* | |
* Monochromatic rendering, exclusively used in the early days of | |
* TrueType by both Apple and Microsoft. Microsoft's GDI interface | |
* supported hinting of the right-side bearing point, such that the | |
* advance width could be non-linear. Most often this was done to | |
* achieve some level of glyph symmetry. To enable reasonable | |
* performance (e.g., not having to run hinting on all glyphs just to | |
* get the widths) there was a bit in the head table indicating if the | |
* side bearing was hinted, and additional tables, `hdmx' and `LTSH', to | |
* cache hinting widths across multiple sizes and device aspect ratios. | |
* | |
* _Font_ _Smoothing_ | |
* | |
* Microsoft's GDI implementation of anti-aliasing. Not traditional | |
* anti-aliasing as the outlines were hinted before the sampling. The | |
* widths matched the bi-level rendering. | |
* | |
* _ClearType_ _Rendering_ | |
* | |
* Technique that uses physical subpixels to improve rendering on LCD | |
* (and other) displays. Because of the higher resolution, many methods | |
* of improving symmetry in glyphs through hinting the right-side | |
* bearing were no longer necessary. This lead to what GDI calls | |
* `natural widths' ClearType, see | |
* http://www.beatstamm.com/typography/RTRCh4.htm#Sec21. Since hinting | |
* has extra resolution, most non-linearity went away, but it is still | |
* possible for hints to change the advance widths in this mode. | |
* | |
* _ClearType_ _Compatible_ _Widths_ | |
* | |
* One of the earliest challenges with ClearType was allowing the | |
* implementation in GDI to be selected without requiring all UI and | |
* documents to reflow. To address this, a compatible method of | |
* rendering ClearType was added where the font hints are executed once | |
* to determine the width in bi-level rendering, and then re-run in | |
* ClearType, with the difference in widths being absorbed in the font | |
* hints for ClearType (mostly in the white space of hints); see | |
* http://www.beatstamm.com/typography/RTRCh4.htm#Sec20. Somewhat by | |
* definition, compatible width ClearType allows for non-linear widths, | |
* but only when the bi-level version has non-linear widths. | |
* | |
* _ClearType_ _Subpixel_ _Positioning_ | |
* | |
* One of the nice benefits of ClearType is the ability to more crisply | |
* display fractional widths; unfortunately, the GDI model of integer | |
* bitmaps did not support this. However, the WPF and Direct Write | |
* frameworks do support fractional widths. DWrite calls this `natural | |
* mode', not to be confused with GDI's `natural widths'. Subpixel | |
* positioning, in the current implementation of Direct Write, | |
* unfortunately does not support hinted advance widths, see | |
* http://www.beatstamm.com/typography/RTRCh4.htm#Sec22. Note that the | |
* TrueType interpreter fully allows the advance width to be adjusted in | |
* this mode, just the DWrite client will ignore those changes. | |
* | |
* _ClearType_ _Backwards_ _Compatibility_ | |
* | |
* This is a set of exceptions made in the TrueType interpreter to | |
* minimize hinting techniques that were problematic with the extra | |
* resolution of ClearType; see | |
* http://www.beatstamm.com/typography/RTRCh4.htm#Sec1 and | |
* http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx. | |
* This technique is not to be confused with ClearType compatible | |
* widths. ClearType backwards compatibility has no direct impact on | |
* changing advance widths, but there might be an indirect impact on | |
* disabling some deltas. This could be worked around in backwards | |
* compatibility mode. | |
* | |
* _Native_ _ClearType_ _Mode_ | |
* | |
* (Not to be confused with `natural widths'.) This mode removes all | |
* the exceptions in the TrueType interpreter when running with | |
* ClearType. Any issues on widths would still apply, though. | |
* | |
*/ | |
/************************************************************************** | |
* | |
* @property: | |
* interpreter-version | |
* | |
* @description: | |
* Currently, two versions are available, representing the bytecode | |
* interpreter with and without subpixel hinting support, | |
* respectively. The default is subpixel support if | |
* TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel | |
* support otherwise (since it isn't available then). | |
* | |
* If subpixel hinting is on, many TrueType bytecode instructions behave | |
* differently compared to B/W or grayscale rendering (except if `native | |
* ClearType' is selected by the font). The main idea is to render at a | |
* much increased horizontal resolution, then sampling down the created | |
* output to subpixel precision. However, many older fonts are not | |
* suited to this and must be specially taken care of by applying | |
* (hardcoded) font-specific tweaks. | |
* | |
* Details on subpixel hinting and some of the necessary tweaks can be | |
* found in Greg Hitchcock's whitepaper at | |
* `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'. | |
* | |
* The following example code demonstrates how to activate subpixel | |
* hinting (omitting the error handling). | |
* | |
* { | |
* FT_Library library; | |
* FT_Face face; | |
* FT_UInt interpreter_version = TT_INTERPRETER_VERSION_38; | |
* | |
* | |
* FT_Init_FreeType( &library ); | |
* | |
* FT_Property_Set( library, "truetype", | |
* "interpreter-version", | |
* &interpreter_version ); | |
* } | |
* | |
* @note: | |
* This property can be used with @FT_Property_Get also. | |
* | |
*/ | |
/************************************************************************** | |
* | |
* @enum: | |
* TT_INTERPRETER_VERSION_XXX | |
* | |
* @description: | |
* A list of constants used for the @interpreter-version property to | |
* select the hinting engine for Truetype fonts. | |
* | |
* The numeric value in the constant names represents the version | |
* number as returned by the `GETINFO' bytecode instruction. | |
* | |
* @values: | |
* TT_INTERPRETER_VERSION_35 :: | |
* Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in | |
* Windows~98; only grayscale and B/W rasterizing is supported. | |
* | |
* TT_INTERPRETER_VERSION_38 :: | |
* Version~38 corresponds to MS rasterizer v.1.9; it is roughly | |
* equivalent to the hinting provided by DirectWrite ClearType (as | |
* can be found, for example, in the Internet Explorer~9 running on | |
* Windows~7). | |
* | |
* @note: | |
* This property controls the behaviour of the bytecode interpreter | |
* and thus how outlines get hinted. It does *not* control how glyph | |
* get rasterized! In particular, it does not control subpixel color | |
* filtering. | |
* | |
* If FreeType has not been compiled with configuration option | |
* FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 causes an | |
* `FT_Err_Unimplemented_Feature' error. | |
* | |
* Depending on the graphics framework, Microsoft uses different | |
* bytecode and rendering engines. As a consequence, the version | |
* numbers returned by a call to the `GETINFO' bytecode instruction are | |
* more convoluted than desired. | |
* | |
* Here are two tables that try to shed some light on the possible | |
* values for the MS rasterizer engine, together with the additional | |
* features introduced by it. | |
* | |
* { | |
* GETINFO framework version feature | |
* ------------------------------------------------------------------- | |
* 3 GDI (Win 3.1), v1.0 16-bit, first version | |
* TrueImage | |
* 33 GDI (Win NT 3.1), v1.5 32-bit | |
* HP Laserjet | |
* 34 GDI (Win 95) v1.6 font smoothing, | |
* new SCANTYPE opcode | |
* 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET | |
* bits in composite glyphs | |
* 36 MGDI (Win CE 2) v1.6+ classic ClearType | |
* 37 GDI (XP and later), v1.8 ClearType | |
* GDI+ old (before Vista) | |
* 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType, | |
* WPF Y-direction ClearType, | |
* additional error checking | |
* 39 DWrite (before Win 8) v2.0 subpixel ClearType flags | |
* in GETINFO opcode, | |
* bug fixes | |
* 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag | |
* DWrite (Win 8) in GETINFO opcode, | |
* Gray ClearType | |
* } | |
* | |
* The `version' field gives a rough orientation only, since some | |
* applications provided certain features much earlier (as an example, | |
* Microsoft Reader used subpixel and Y-direction ClearType already in | |
* Windows 2000). Similarly, updates to a given framework might include | |
* improved hinting support. | |
* | |
* { | |
* version sampling rendering comment | |
* x y x y | |
* -------------------------------------------------------------- | |
* v1.0 normal normal B/W B/W bi-level | |
* v1.6 high high gray gray grayscale | |
* v1.8 high normal color-filter B/W (GDI) ClearType | |
* v1.9 high high color-filter gray Color ClearType | |
* v2.1 high normal gray B/W Gray ClearType | |
* v2.1 high high gray gray Gray ClearType | |
* } | |
* | |
* Color and Gray ClearType are the two available variants of | |
* `Y-direction ClearType', meaning grayscale rasterization along the | |
* Y-direction; the name used in the TrueType specification for this | |
* feature is `symmetric smoothing'. `Classic ClearType' is the | |
* original algorithm used before introducing a modified version in | |
* Win~XP. Another name for v1.6's grayscale rendering is `font | |
* smoothing', and `Color ClearType' is sometimes also called `DWrite | |
* ClearType'. To differentiate between today's Color ClearType and the | |
* earlier ClearType variant with B/W rendering along the vertical axis, | |
* the latter is sometimes called `GDI ClearType'. | |
* | |
* `Normal' and `high' sampling describe the (virtual) resolution to | |
* access the rasterized outline after the hinting process. `Normal' | |
* means 1 sample per grid line (i.e., B/W). In the current Microsoft | |
* implementation, `high' means an extra virtual resolution of 16x16 (or | |
* 16x1) grid lines per pixel for bytecode instructions like `MIRP'. | |
* After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid | |
* lines for color filtering if Color ClearType is activated. | |
* | |
* Note that `Gray ClearType' is essentially the same as v1.6's | |
* grayscale rendering. However, the GETINFO instruction handles it | |
* differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1 | |
* returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing), | |
* and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for | |
* the version~1 gasp table exclusively (like Color ClearType), while | |
* v1.6 only respects the values of version~0 (bits 0 and~1). | |
* | |
* FreeType doesn't provide all capabilities of the most recent | |
* ClearType incarnation, thus we identify our subpixel support as | |
* version~38. | |
* | |
*/ | |
#define TT_INTERPRETER_VERSION_35 35 | |
#define TT_INTERPRETER_VERSION_38 38 | |
/* */ | |
FT_END_HEADER | |
#endif /* __FTTTDRV_H__ */ | |
/* END */ |