1 /****************************************************************************
2 *
3 * ftadvanc.h
4 *
5 * Quick computation of advance widths (specification only).
6 *
7 * Copyright (C) 2008-2023 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 FTADVANC_H_
20 #define FTADVANC_H_
21
22
23 #include <freetype/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 * quick_advance
39 *
40 * @title:
41 * Quick retrieval of advance values
42 *
43 * @abstract:
44 * Retrieve horizontal and vertical advance values without processing
45 * glyph outlines, if possible.
46 *
47 * @description:
48 * This section contains functions to quickly extract advance values
49 * without handling glyph outlines, if possible.
50 *
51 * @order:
52 * FT_Get_Advance
53 * FT_Get_Advances
54 *
55 */
56
57
58 /**************************************************************************
59 *
60 * @enum:
61 * FT_ADVANCE_FLAG_FAST_ONLY
62 *
63 * @description:
64 * A bit-flag to be OR-ed with the `flags` parameter of the
65 * @FT_Get_Advance and @FT_Get_Advances functions.
66 *
67 * If set, it indicates that you want these functions to fail if the
68 * corresponding hinting mode or font driver doesn't allow for very quick
69 * advance computation.
70 *
71 * Typically, glyphs that are either unscaled, unhinted, bitmapped, or
72 * light-hinted can have their advance width computed very quickly.
73 *
74 * Normal and bytecode hinted modes that require loading, scaling, and
75 * hinting of the glyph outline, are extremely slow by comparison.
76 */
77 #define FT_ADVANCE_FLAG_FAST_ONLY 0x20000000L
78
79
80 /**************************************************************************
81 *
82 * @function:
83 * FT_Get_Advance
84 *
85 * @description:
86 * Retrieve the advance value of a given glyph outline in an @FT_Face.
87 *
88 * @input:
89 * face ::
90 * The source @FT_Face handle.
91 *
92 * gindex ::
93 * The glyph index.
94 *
95 * load_flags ::
96 * A set of bit flags similar to those used when calling
97 * @FT_Load_Glyph, used to determine what kind of advances you need.
98 *
99 * @output:
100 * padvance ::
101 * The advance value. If scaling is performed (based on the value of
102 * `load_flags`), the advance value is in 16.16 format. Otherwise, it
103 * is in font units.
104 *
105 * If @FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance
106 * corresponding to a vertical layout. Otherwise, it is the horizontal
107 * advance in a horizontal layout.
108 *
109 * @return:
110 * FreeType error code. 0 means success.
111 *
112 * @note:
113 * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if
114 * the corresponding font backend doesn't have a quick way to retrieve
115 * the advances.
116 *
117 * A scaled advance is returned in 16.16 format but isn't transformed by
118 * the affine transformation specified by @FT_Set_Transform.
119 */
120 FT_EXPORT( FT_Error )
121 FT_Get_Advance( FT_Face face,
122 FT_UInt gindex,
123 FT_Int32 load_flags,
124 FT_Fixed *padvance );
125
126
127 /**************************************************************************
128 *
129 * @function:
130 * FT_Get_Advances
131 *
132 * @description:
133 * Retrieve the advance values of several glyph outlines in an @FT_Face.
134 *
135 * @input:
136 * face ::
137 * The source @FT_Face handle.
138 *
139 * start ::
140 * The first glyph index.
141 *
142 * count ::
143 * The number of advance values you want to retrieve.
144 *
145 * load_flags ::
146 * A set of bit flags similar to those used when calling
147 * @FT_Load_Glyph.
148 *
149 * @output:
150 * padvance ::
151 * The advance values. This array, to be provided by the caller, must
152 * contain at least `count` elements.
153 *
154 * If scaling is performed (based on the value of `load_flags`), the
155 * advance values are in 16.16 format. Otherwise, they are in font
156 * units.
157 *
158 * If @FT_LOAD_VERTICAL_LAYOUT is set, these are the vertical advances
159 * corresponding to a vertical layout. Otherwise, they are the
160 * horizontal advances in a horizontal layout.
161 *
162 * @return:
163 * FreeType error code. 0 means success.
164 *
165 * @note:
166 * This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if
167 * the corresponding font backend doesn't have a quick way to retrieve
168 * the advances.
169 *
170 * Scaled advances are returned in 16.16 format but aren't transformed by
171 * the affine transformation specified by @FT_Set_Transform.
172 */
173 FT_EXPORT( FT_Error )
174 FT_Get_Advances( FT_Face face,
175 FT_UInt start,
176 FT_UInt count,
177 FT_Int32 load_flags,
178 FT_Fixed *padvances );
179
180 /* */
181
182
183 FT_END_HEADER
184
185 #endif /* FTADVANC_H_ */
186
187
188 /* END */