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