Clutter Engine 0.0.1
Loading...
Searching...
No Matches
ftttdrv.h
1/***************************************************************************/
2/* */
3/* ftttdrv.h */
4/* */
5/* FreeType API for controlling the TrueType driver */
6/* (specification only). */
7/* */
8/* Copyright 2013-2016 by */
9/* David Turner, Robert Wilhelm, and Werner Lemberg. */
10/* */
11/* This file is part of the FreeType project, and may only be used, */
12/* modified, and distributed under the terms of the FreeType project */
13/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
14/* this file you indicate that you have read the license and */
15/* understand and accept it fully. */
16/* */
17/***************************************************************************/
18
19
20#ifndef FTTTDRV_H_
21#define FTTTDRV_H_
22
23#include <ft2build.h>
24#include FT_FREETYPE_H
25
26#ifdef FREETYPE_H
27#error "freetype.h of FreeType 1 has been loaded!"
28#error "Please fix the directory search order for header files"
29#error "so that freetype.h of FreeType 2 is found first."
30#endif
31
32
33FT_BEGIN_HEADER
34
35
36 /**************************************************************************
37 *
38 * @section:
39 * tt_driver
40 *
41 * @title:
42 * The TrueType driver
43 *
44 * @abstract:
45 * Controlling the TrueType driver module.
46 *
47 * @description:
48 * While FreeType's TrueType driver doesn't expose API functions by
49 * itself, it is possible to control its behaviour with @FT_Property_Set
50 * and @FT_Property_Get. The following lists the available properties
51 * together with the necessary macros and structures.
52 *
53 * The TrueType driver's module name is `truetype'.
54 *
55 * We start with a list of definitions, kindly provided by Greg
56 * Hitchcock.
57 *
58 * _Bi-Level_ _Rendering_
59 *
60 * Monochromatic rendering, exclusively used in the early days of
61 * TrueType by both Apple and Microsoft. Microsoft's GDI interface
62 * supported hinting of the right-side bearing point, such that the
63 * advance width could be non-linear. Most often this was done to
64 * achieve some level of glyph symmetry. To enable reasonable
65 * performance (e.g., not having to run hinting on all glyphs just to
66 * get the widths) there was a bit in the head table indicating if the
67 * side bearing was hinted, and additional tables, `hdmx' and `LTSH', to
68 * cache hinting widths across multiple sizes and device aspect ratios.
69 *
70 * _Font_ _Smoothing_
71 *
72 * Microsoft's GDI implementation of anti-aliasing. Not traditional
73 * anti-aliasing as the outlines were hinted before the sampling. The
74 * widths matched the bi-level rendering.
75 *
76 * _ClearType_ _Rendering_
77 *
78 * Technique that uses physical subpixels to improve rendering on LCD
79 * (and other) displays. Because of the higher resolution, many methods
80 * of improving symmetry in glyphs through hinting the right-side
81 * bearing were no longer necessary. This lead to what GDI calls
82 * `natural widths' ClearType, see
83 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec21. Since hinting
84 * has extra resolution, most non-linearity went away, but it is still
85 * possible for hints to change the advance widths in this mode.
86 *
87 * _ClearType_ _Compatible_ _Widths_
88 *
89 * One of the earliest challenges with ClearType was allowing the
90 * implementation in GDI to be selected without requiring all UI and
91 * documents to reflow. To address this, a compatible method of
92 * rendering ClearType was added where the font hints are executed once
93 * to determine the width in bi-level rendering, and then re-run in
94 * ClearType, with the difference in widths being absorbed in the font
95 * hints for ClearType (mostly in the white space of hints); see
96 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec20. Somewhat by
97 * definition, compatible width ClearType allows for non-linear widths,
98 * but only when the bi-level version has non-linear widths.
99 *
100 * _ClearType_ _Subpixel_ _Positioning_
101 *
102 * One of the nice benefits of ClearType is the ability to more crisply
103 * display fractional widths; unfortunately, the GDI model of integer
104 * bitmaps did not support this. However, the WPF and Direct Write
105 * frameworks do support fractional widths. DWrite calls this `natural
106 * mode', not to be confused with GDI's `natural widths'. Subpixel
107 * positioning, in the current implementation of Direct Write,
108 * unfortunately does not support hinted advance widths, see
109 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec22. Note that the
110 * TrueType interpreter fully allows the advance width to be adjusted in
111 * this mode, just the DWrite client will ignore those changes.
112 *
113 * _ClearType_ _Backwards_ _Compatibility_
114 *
115 * This is a set of exceptions made in the TrueType interpreter to
116 * minimize hinting techniques that were problematic with the extra
117 * resolution of ClearType; see
118 * http://www.beatstamm.com/typography/RTRCh4.htm#Sec1 and
119 * http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx.
120 * This technique is not to be confused with ClearType compatible
121 * widths. ClearType backwards compatibility has no direct impact on
122 * changing advance widths, but there might be an indirect impact on
123 * disabling some deltas. This could be worked around in backwards
124 * compatibility mode.
125 *
126 * _Native_ _ClearType_ _Mode_
127 *
128 * (Not to be confused with `natural widths'.) This mode removes all
129 * the exceptions in the TrueType interpreter when running with
130 * ClearType. Any issues on widths would still apply, though.
131 *
132 */
133
134
135 /**************************************************************************
136 *
137 * @property:
138 * interpreter-version
139 *
140 * @description:
141 * Currently, two versions are available, representing the bytecode
142 * interpreter with and without subpixel hinting support,
143 * respectively. The default is subpixel support if
144 * TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel
145 * support otherwise (since it isn't available then).
146 *
147 * If subpixel hinting is on, many TrueType bytecode instructions behave
148 * differently compared to B/W or grayscale rendering (except if `native
149 * ClearType' is selected by the font). The main idea is to render at a
150 * much increased horizontal resolution, then sampling down the created
151 * output to subpixel precision. However, many older fonts are not
152 * suited to this and must be specially taken care of by applying
153 * (hardcoded) font-specific tweaks.
154 *
155 * Details on subpixel hinting and some of the necessary tweaks can be
156 * found in Greg Hitchcock's whitepaper at
157 * `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'.
158 *
159 * The following example code demonstrates how to activate subpixel
160 * hinting (omitting the error handling).
161 *
162 * {
163 * FT_Library library;
164 * FT_Face face;
165 * FT_UInt interpreter_version = TT_INTERPRETER_VERSION_38;
166 *
167 *
168 * FT_Init_FreeType( &library );
169 *
170 * FT_Property_Set( library, "truetype",
171 * "interpreter-version",
172 * &interpreter_version );
173 * }
174 *
175 * @note:
176 * This property can be used with @FT_Property_Get also.
177 *
178 */
179
180
181 /**************************************************************************
182 *
183 * @enum:
184 * TT_INTERPRETER_VERSION_XXX
185 *
186 * @description:
187 * A list of constants used for the @interpreter-version property to
188 * select the hinting engine for Truetype fonts.
189 *
190 * The numeric value in the constant names represents the version
191 * number as returned by the `GETINFO' bytecode instruction.
192 *
193 * @values:
194 * TT_INTERPRETER_VERSION_35 ::
195 * Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in
196 * Windows~98; only grayscale and B/W rasterizing is supported.
197 *
198 * TT_INTERPRETER_VERSION_38 ::
199 * Version~38 corresponds to MS rasterizer v.1.9; it is roughly
200 * equivalent to the hinting provided by DirectWrite ClearType (as
201 * can be found, for example, in the Internet Explorer~9 running on
202 * Windows~7).
203 *
204 * @note:
205 * This property controls the behaviour of the bytecode interpreter
206 * and thus how outlines get hinted. It does *not* control how glyph
207 * get rasterized! In particular, it does not control subpixel color
208 * filtering.
209 *
210 * If FreeType has not been compiled with configuration option
211 * FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 causes an
212 * `FT_Err_Unimplemented_Feature' error.
213 *
214 * Depending on the graphics framework, Microsoft uses different
215 * bytecode and rendering engines. As a consequence, the version
216 * numbers returned by a call to the `GETINFO' bytecode instruction are
217 * more convoluted than desired.
218 *
219 * Here are two tables that try to shed some light on the possible
220 * values for the MS rasterizer engine, together with the additional
221 * features introduced by it.
222 *
223 * {
224 * GETINFO framework version feature
225 * -------------------------------------------------------------------
226 * 3 GDI (Win 3.1), v1.0 16-bit, first version
227 * TrueImage
228 * 33 GDI (Win NT 3.1), v1.5 32-bit
229 * HP Laserjet
230 * 34 GDI (Win 95) v1.6 font smoothing,
231 * new SCANTYPE opcode
232 * 35 GDI (Win 98/2000) v1.7 (UN)SCALED_COMPONENT_OFFSET
233 * bits in composite glyphs
234 * 36 MGDI (Win CE 2) v1.6+ classic ClearType
235 * 37 GDI (XP and later), v1.8 ClearType
236 * GDI+ old (before Vista)
237 * 38 GDI+ old (Vista, Win 7), v1.9 subpixel ClearType,
238 * WPF Y-direction ClearType,
239 * additional error checking
240 * 39 DWrite (before Win 8) v2.0 subpixel ClearType flags
241 * in GETINFO opcode,
242 * bug fixes
243 * 40 GDI+ (after Win 7), v2.1 Y-direction ClearType flag
244 * DWrite (Win 8) in GETINFO opcode,
245 * Gray ClearType
246 * }
247 *
248 * The `version' field gives a rough orientation only, since some
249 * applications provided certain features much earlier (as an example,
250 * Microsoft Reader used subpixel and Y-direction ClearType already in
251 * Windows 2000). Similarly, updates to a given framework might include
252 * improved hinting support.
253 *
254 * {
255 * version sampling rendering comment
256 * x y x y
257 * --------------------------------------------------------------
258 * v1.0 normal normal B/W B/W bi-level
259 * v1.6 high high gray gray grayscale
260 * v1.8 high normal color-filter B/W (GDI) ClearType
261 * v1.9 high high color-filter gray Color ClearType
262 * v2.1 high normal gray B/W Gray ClearType
263 * v2.1 high high gray gray Gray ClearType
264 * }
265 *
266 * Color and Gray ClearType are the two available variants of
267 * `Y-direction ClearType', meaning grayscale rasterization along the
268 * Y-direction; the name used in the TrueType specification for this
269 * feature is `symmetric smoothing'. `Classic ClearType' is the
270 * original algorithm used before introducing a modified version in
271 * Win~XP. Another name for v1.6's grayscale rendering is `font
272 * smoothing', and `Color ClearType' is sometimes also called `DWrite
273 * ClearType'. To differentiate between today's Color ClearType and the
274 * earlier ClearType variant with B/W rendering along the vertical axis,
275 * the latter is sometimes called `GDI ClearType'.
276 *
277 * `Normal' and `high' sampling describe the (virtual) resolution to
278 * access the rasterized outline after the hinting process. `Normal'
279 * means 1 sample per grid line (i.e., B/W). In the current Microsoft
280 * implementation, `high' means an extra virtual resolution of 16x16 (or
281 * 16x1) grid lines per pixel for bytecode instructions like `MIRP'.
282 * After hinting, these 16 grid lines are mapped to 6x5 (or 6x1) grid
283 * lines for color filtering if Color ClearType is activated.
284 *
285 * Note that `Gray ClearType' is essentially the same as v1.6's
286 * grayscale rendering. However, the GETINFO instruction handles it
287 * differently: v1.6 returns bit~12 (hinting for grayscale), while v2.1
288 * returns bits~13 (hinting for ClearType), 18 (symmetrical smoothing),
289 * and~19 (Gray ClearType). Also, this mode respects bits 2 and~3 for
290 * the version~1 gasp table exclusively (like Color ClearType), while
291 * v1.6 only respects the values of version~0 (bits 0 and~1).
292 *
293 * FreeType doesn't provide all capabilities of the most recent
294 * ClearType incarnation, thus we identify our subpixel support as
295 * version~38.
296 *
297 */
298#define TT_INTERPRETER_VERSION_35 35
299#define TT_INTERPRETER_VERSION_38 38
300
301 /* */
302
303
304FT_END_HEADER
305
306
307#endif /* FTTTDRV_H_ */
308
309
310/* END */
Generated by doxygen 1.12.0