1 /****************************************************************************
2  *
3  * ftgasp.h
4  *
5  *   Access of TrueType's 'gasp' table (specification).
6  *
7  * Copyright (C) 2007-2019 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 FTGASP_H_
20 #define FTGASP_H_
21 
22 #include <ft2build.h>
23 #include FT_FREETYPE_H
24 
25 #ifdef FREETYPE_H
26 #error "freetype.h of FreeType 1 has been loaded!"
27 #error "Please fix the directory search order for header files"
28 #error "so that freetype.h of FreeType 2 is found first."
29 #endif
30 
31 
32 FT_BEGIN_HEADER
33 
34 
35   /**************************************************************************
36    *
37    * @section:
38    *   gasp_table
39    *
40    * @title:
41    *   Gasp Table
42    *
43    * @abstract:
44    *   Retrieving TrueType 'gasp' table entries.
45    *
46    * @description:
47    *   The function @FT_Get_Gasp can be used to query a TrueType or OpenType
48    *   font for specific entries in its 'gasp' table, if any.  This is mainly
49    *   useful when implementing native TrueType hinting with the bytecode
50    *   interpreter to duplicate the Windows text rendering results.
51    */
52 
53   /**************************************************************************
54    *
55    * @enum:
56    *   FT_GASP_XXX
57    *
58    * @description:
59    *   A list of values and/or bit-flags returned by the @FT_Get_Gasp
60    *   function.
61    *
62    * @values:
63    *   FT_GASP_NO_TABLE ::
64    *     This special value means that there is no GASP table in this face.
65    *     It is up to the client to decide what to do.
66    *
67    *   FT_GASP_DO_GRIDFIT ::
68    *     Grid-fitting and hinting should be performed at the specified ppem.
69    *     This **really** means TrueType bytecode interpretation.  If this bit
70    *     is not set, no hinting gets applied.
71    *
72    *   FT_GASP_DO_GRAY ::
73    *     Anti-aliased rendering should be performed at the specified ppem.
74    *     If not set, do monochrome rendering.
75    *
76    *   FT_GASP_SYMMETRIC_SMOOTHING ::
77    *     If set, smoothing along multiple axes must be used with ClearType.
78    *
79    *   FT_GASP_SYMMETRIC_GRIDFIT ::
80    *     Grid-fitting must be used with ClearType's symmetric smoothing.
81    *
82    * @note:
83    *   The bit-flags `FT_GASP_DO_GRIDFIT` and `FT_GASP_DO_GRAY` are to be
84    *   used for standard font rasterization only.  Independently of that,
85    *   `FT_GASP_SYMMETRIC_SMOOTHING` and `FT_GASP_SYMMETRIC_GRIDFIT` are to
86    *   be used if ClearType is enabled (and `FT_GASP_DO_GRIDFIT` and
87    *   `FT_GASP_DO_GRAY` are consequently ignored).
88    *
89    *   'ClearType' is Microsoft's implementation of LCD rendering, partly
90    *   protected by patents.
91    *
92    * @since:
93    *   2.3.0
94    */
95 #define FT_GASP_NO_TABLE               -1
96 #define FT_GASP_DO_GRIDFIT           0x01
97 #define FT_GASP_DO_GRAY              0x02
98 #define FT_GASP_SYMMETRIC_GRIDFIT    0x04
99 #define FT_GASP_SYMMETRIC_SMOOTHING  0x08
100 
101 
102   /**************************************************************************
103    *
104    * @function:
105    *   FT_Get_Gasp
106    *
107    * @description:
108    *   For a TrueType or OpenType font file, return the rasterizer behaviour
109    *   flags from the font's 'gasp' table corresponding to a given character
110    *   pixel size.
111    *
112    * @input:
113    *   face ::
114    *     The source face handle.
115    *
116    *   ppem ::
117    *     The vertical character pixel size.
118    *
119    * @return:
120    *   Bit flags (see @FT_GASP_XXX), or @FT_GASP_NO_TABLE if there is no
121    *   'gasp' table in the face.
122    *
123    * @note:
124    *   If you want to use the MM functionality of OpenType variation fonts
125    *   (i.e., using @FT_Set_Var_Design_Coordinates and friends), call this
126    *   function **after** setting an instance since the return values can
127    *   change.
128    *
129    * @since:
130    *   2.3.0
131    */
132   FT_EXPORT( FT_Int )
133   FT_Get_Gasp( FT_Face  face,
134                FT_UInt  ppem );
135 
136   /* */
137 
138 
139 FT_END_HEADER
140 
141 #endif /* FTGASP_H_ */
142 
143 
144 /* END */
145