XFA: merge patch from CL 817753002
[pdfium.git] / core / include / thirdparties / freetype / freetype / ftttdrv.h
1 /***************************************************************************/
2 /*                                                                         */
3 /*  ftttdrv.h                                                              */
4 /*                                                                         */
5 /*    FreeType API for controlling the TrueType driver                     */
6 /*    (specification only).                                                */
7 /*                                                                         */
8 /*  Copyright 2013 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 "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
33 FT_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    */
56
57
58   /**************************************************************************
59    *
60    * @property:
61    *   interpreter-version
62    *
63    * @description:
64    *   Currently, two versions are available which represent the bytecode
65    *   interpreter with and without subpixel hinting support,
66    *   respectively.  The default is subpixel support if
67    *   TT_CONFIG_OPTION_SUBPIXEL_HINTING is defined, and no subpixel
68    *   support otherwise (since it isn't available then).
69    *
70    *   If subpixel hinting is on, many TrueType bytecode instructions
71    *   behave differently compared to B/W or grayscale rendering.  The
72    *   main idea is to render at a much increased horizontal resolution,
73    *   then sampling down the created output to subpixel precision.
74    *   However, many older fonts are not suited to this and must be
75    *   specially taken care of by applying (hardcoded) font-specific
76    *   tweaks.
77    *
78    *   Details on subpixel hinting and some of the necessary tweaks can be
79    *   found in Greg Hitchcock's whitepaper at
80    *   `http://www.microsoft.com/typography/cleartype/truetypecleartype.aspx'.
81    *
82    *   The following example code demonstrates how to activate subpixel
83    *   hinting (omitting the error handling).
84    *
85    *   {
86    *     FT_Library  library;
87    *     FT_Face     face;
88    *     FT_UInt     interpreter_version = TT_INTERPRETER_VERSION_38;
89    *
90    *
91    *     FT_Init_FreeType( &library );
92    *
93    *     FT_Property_Set( library, "truetype",
94    *                               "interpreter-version",
95    *                               &interpreter_version );
96    *   }
97    *
98    * @note:
99    *   This property can be used with @FT_Property_Get also.
100    *
101    */
102
103
104   /**************************************************************************
105    *
106    * @enum:
107    *   TT_INTERPRETER_VERSION_XXX
108    *
109    * @description:
110    *   A list of constants used for the @interpreter-version property to
111    *   select the hinting engine for Truetype fonts.
112    *
113    *   The numeric value in the constant names represents the version
114    *   number as returned by the `GETINFO' bytecode instruction.
115    *
116    * @values:
117    *   TT_INTERPRETER_VERSION_35 ::
118    *     Version~35 corresponds to MS rasterizer v.1.7 as used e.g. in
119    *     Windows~98; only grayscale and B/W rasterizing is supported.
120    *
121    *   TT_INTERPRETER_VERSION_38 ::
122    *     Version~38 corresponds to MS rasterizer v.1.9; it is roughly
123    *     equivalent to the hinting provided by DirectWrite ClearType (as
124    *     can be found, for example, in the Internet Explorer~9 running on
125    *     Windows~7).
126    *
127    * @note:
128    *   This property controls the behaviour of the bytecode interpreter
129    *   and thus how outlines get hinted.  It does *not* control how glyph
130    *   get rasterized!  In particular, it does not control subpixel color
131    *   filtering.
132    *
133    *   If FreeType has not been compiled with configuration option
134    *   FT_CONFIG_OPTION_SUBPIXEL_HINTING, selecting version~38 causes an
135    *   `FT_Err_Unimplemented_Feature' error.
136    *
137    */
138 #define TT_INTERPRETER_VERSION_35  35
139 #define TT_INTERPRETER_VERSION_38  38
140
141
142  /* */
143
144 FT_END_HEADER
145
146
147 #endif /* __FTTTDRV_H__ */
148
149
150 /* END */