1 /****************************************************************************
2 *
3 * ftgxval.h
4 *
5 * FreeType API for validating TrueTypeGX/AAT tables (specification).
6 *
7 * Copyright (C) 2004-2023 by
8 * Masatake YAMATO, Redhat K.K,
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 *
21 * gxvalid is derived from both gxlayout module and otvalid module.
22 * Development of gxlayout is supported by the Information-technology
23 * Promotion Agency(IPA), Japan.
24 *
25 */
26
27
28 #ifndef FTGXVAL_H_
29 #define FTGXVAL_H_
30
31 #include <freetype/freetype.h>
32
33 #ifdef FREETYPE_H
34 #error "freetype.h of FreeType 1 has been loaded!"
35 #error "Please fix the directory search order for header files"
36 #error "so that freetype.h of FreeType 2 is found first."
37 #endif
38
39
40 FT_BEGIN_HEADER
41
42
43 /**************************************************************************
44 *
45 * @section:
46 * gx_validation
47 *
48 * @title:
49 * TrueTypeGX/AAT Validation
50 *
51 * @abstract:
52 * An API to validate TrueTypeGX/AAT tables.
53 *
54 * @description:
55 * This section contains the declaration of functions to validate some
56 * TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd, trak,
57 * prop, lcar).
58 *
59 * @order:
60 * FT_TrueTypeGX_Validate
61 * FT_TrueTypeGX_Free
62 *
63 * FT_ClassicKern_Validate
64 * FT_ClassicKern_Free
65 *
66 * FT_VALIDATE_GX_LENGTH
67 * FT_VALIDATE_GXXXX
68 * FT_VALIDATE_CKERNXXX
69 *
70 */
71
72 /**************************************************************************
73 *
74 *
75 * Warning: Use `FT_VALIDATE_XXX` to validate a table.
76 * Following definitions are for gxvalid developers.
77 *
78 *
79 */
80
81 #define FT_VALIDATE_feat_INDEX 0
82 #define FT_VALIDATE_mort_INDEX 1
83 #define FT_VALIDATE_morx_INDEX 2
84 #define FT_VALIDATE_bsln_INDEX 3
85 #define FT_VALIDATE_just_INDEX 4
86 #define FT_VALIDATE_kern_INDEX 5
87 #define FT_VALIDATE_opbd_INDEX 6
88 #define FT_VALIDATE_trak_INDEX 7
89 #define FT_VALIDATE_prop_INDEX 8
90 #define FT_VALIDATE_lcar_INDEX 9
91 #define FT_VALIDATE_GX_LAST_INDEX FT_VALIDATE_lcar_INDEX
92
93
94 /**************************************************************************
95 *
96 * @macro:
97 * FT_VALIDATE_GX_LENGTH
98 *
99 * @description:
100 * The number of tables checked in this module. Use it as a parameter
101 * for the `table-length` argument of function @FT_TrueTypeGX_Validate.
102 */
103 #define FT_VALIDATE_GX_LENGTH ( FT_VALIDATE_GX_LAST_INDEX + 1 )
104
105 /* */
106
107 /* Up to 0x1000 is used by otvalid.
108 Ox2xxx is reserved for feature OT extension. */
109 #define FT_VALIDATE_GX_START 0x4000
110 #define FT_VALIDATE_GX_BITFIELD( tag ) \
111 ( FT_VALIDATE_GX_START << FT_VALIDATE_##tag##_INDEX )
112
113
114 /**************************************************************************
115 *
116 * @enum:
117 * FT_VALIDATE_GXXXX
118 *
119 * @description:
120 * A list of bit-field constants used with @FT_TrueTypeGX_Validate to
121 * indicate which TrueTypeGX/AAT Type tables should be validated.
122 *
123 * @values:
124 * FT_VALIDATE_feat ::
125 * Validate 'feat' table.
126 *
127 * FT_VALIDATE_mort ::
128 * Validate 'mort' table.
129 *
130 * FT_VALIDATE_morx ::
131 * Validate 'morx' table.
132 *
133 * FT_VALIDATE_bsln ::
134 * Validate 'bsln' table.
135 *
136 * FT_VALIDATE_just ::
137 * Validate 'just' table.
138 *
139 * FT_VALIDATE_kern ::
140 * Validate 'kern' table.
141 *
142 * FT_VALIDATE_opbd ::
143 * Validate 'opbd' table.
144 *
145 * FT_VALIDATE_trak ::
146 * Validate 'trak' table.
147 *
148 * FT_VALIDATE_prop ::
149 * Validate 'prop' table.
150 *
151 * FT_VALIDATE_lcar ::
152 * Validate 'lcar' table.
153 *
154 * FT_VALIDATE_GX ::
155 * Validate all TrueTypeGX tables (feat, mort, morx, bsln, just, kern,
156 * opbd, trak, prop and lcar).
157 *
158 */
159
160 #define FT_VALIDATE_feat FT_VALIDATE_GX_BITFIELD( feat )
161 #define FT_VALIDATE_mort FT_VALIDATE_GX_BITFIELD( mort )
162 #define FT_VALIDATE_morx FT_VALIDATE_GX_BITFIELD( morx )
163 #define FT_VALIDATE_bsln FT_VALIDATE_GX_BITFIELD( bsln )
164 #define FT_VALIDATE_just FT_VALIDATE_GX_BITFIELD( just )
165 #define FT_VALIDATE_kern FT_VALIDATE_GX_BITFIELD( kern )
166 #define FT_VALIDATE_opbd FT_VALIDATE_GX_BITFIELD( opbd )
167 #define FT_VALIDATE_trak FT_VALIDATE_GX_BITFIELD( trak )
168 #define FT_VALIDATE_prop FT_VALIDATE_GX_BITFIELD( prop )
169 #define FT_VALIDATE_lcar FT_VALIDATE_GX_BITFIELD( lcar )
170
171 #define FT_VALIDATE_GX ( FT_VALIDATE_feat | \
172 FT_VALIDATE_mort | \
173 FT_VALIDATE_morx | \
174 FT_VALIDATE_bsln | \
175 FT_VALIDATE_just | \
176 FT_VALIDATE_kern | \
177 FT_VALIDATE_opbd | \
178 FT_VALIDATE_trak | \
179 FT_VALIDATE_prop | \
180 FT_VALIDATE_lcar )
181
182
183 /**************************************************************************
184 *
185 * @function:
186 * FT_TrueTypeGX_Validate
187 *
188 * @description:
189 * Validate various TrueTypeGX tables to assure that all offsets and
190 * indices are valid. The idea is that a higher-level library that
191 * actually does the text layout can access those tables without error
192 * checking (which can be quite time consuming).
193 *
194 * @input:
195 * face ::
196 * A handle to the input face.
197 *
198 * validation_flags ::
199 * A bit field that specifies the tables to be validated. See
200 * @FT_VALIDATE_GXXXX for possible values.
201 *
202 * table_length ::
203 * The size of the `tables` array. Normally, @FT_VALIDATE_GX_LENGTH
204 * should be passed.
205 *
206 * @output:
207 * tables ::
208 * The array where all validated sfnt tables are stored. The array
209 * itself must be allocated by a client.
210 *
211 * @return:
212 * FreeType error code. 0~means success.
213 *
214 * @note:
215 * This function only works with TrueTypeGX fonts, returning an error
216 * otherwise.
217 *
218 * After use, the application should deallocate the buffers pointed to by
219 * each `tables` element, by calling @FT_TrueTypeGX_Free. A `NULL` value
220 * indicates that the table either doesn't exist in the font, the
221 * application hasn't asked for validation, or the validator doesn't have
222 * the ability to validate the sfnt table.
223 */
224 FT_EXPORT( FT_Error )
225 FT_TrueTypeGX_Validate( FT_Face face,
226 FT_UInt validation_flags,
227 FT_Bytes tables[FT_VALIDATE_GX_LENGTH],
228 FT_UInt table_length );
229
230
231 /**************************************************************************
232 *
233 * @function:
234 * FT_TrueTypeGX_Free
235 *
236 * @description:
237 * Free the buffer allocated by TrueTypeGX validator.
238 *
239 * @input:
240 * face ::
241 * A handle to the input face.
242 *
243 * table ::
244 * The pointer to the buffer allocated by @FT_TrueTypeGX_Validate.
245 *
246 * @note:
247 * This function must be used to free the buffer allocated by
248 * @FT_TrueTypeGX_Validate only.
249 */
250 FT_EXPORT( void )
251 FT_TrueTypeGX_Free( FT_Face face,
252 FT_Bytes table );
253
254
255 /**************************************************************************
256 *
257 * @enum:
258 * FT_VALIDATE_CKERNXXX
259 *
260 * @description:
261 * A list of bit-field constants used with @FT_ClassicKern_Validate to
262 * indicate the classic kern dialect or dialects. If the selected type
263 * doesn't fit, @FT_ClassicKern_Validate regards the table as invalid.
264 *
265 * @values:
266 * FT_VALIDATE_MS ::
267 * Handle the 'kern' table as a classic Microsoft kern table.
268 *
269 * FT_VALIDATE_APPLE ::
270 * Handle the 'kern' table as a classic Apple kern table.
271 *
272 * FT_VALIDATE_CKERN ::
273 * Handle the 'kern' as either classic Apple or Microsoft kern table.
274 */
275 #define FT_VALIDATE_MS ( FT_VALIDATE_GX_START << 0 )
276 #define FT_VALIDATE_APPLE ( FT_VALIDATE_GX_START << 1 )
277
278 #define FT_VALIDATE_CKERN ( FT_VALIDATE_MS | FT_VALIDATE_APPLE )
279
280
281 /**************************************************************************
282 *
283 * @function:
284 * FT_ClassicKern_Validate
285 *
286 * @description:
287 * Validate classic (16-bit format) kern table to assure that the
288 * offsets and indices are valid. The idea is that a higher-level
289 * library that actually does the text layout can access those tables
290 * without error checking (which can be quite time consuming).
291 *
292 * The 'kern' table validator in @FT_TrueTypeGX_Validate deals with both
293 * the new 32-bit format and the classic 16-bit format, while
294 * FT_ClassicKern_Validate only supports the classic 16-bit format.
295 *
296 * @input:
297 * face ::
298 * A handle to the input face.
299 *
300 * validation_flags ::
301 * A bit field that specifies the dialect to be validated. See
302 * @FT_VALIDATE_CKERNXXX for possible values.
303 *
304 * @output:
305 * ckern_table ::
306 * A pointer to the kern table.
307 *
308 * @return:
309 * FreeType error code. 0~means success.
310 *
311 * @note:
312 * After use, the application should deallocate the buffers pointed to by
313 * `ckern_table`, by calling @FT_ClassicKern_Free. A `NULL` value
314 * indicates that the table doesn't exist in the font.
315 */
316 FT_EXPORT( FT_Error )
317 FT_ClassicKern_Validate( FT_Face face,
318 FT_UInt validation_flags,
319 FT_Bytes *ckern_table );
320
321
322 /**************************************************************************
323 *
324 * @function:
325 * FT_ClassicKern_Free
326 *
327 * @description:
328 * Free the buffer allocated by classic Kern validator.
329 *
330 * @input:
331 * face ::
332 * A handle to the input face.
333 *
334 * table ::
335 * The pointer to the buffer that is allocated by
336 * @FT_ClassicKern_Validate.
337 *
338 * @note:
339 * This function must be used to free the buffer allocated by
340 * @FT_ClassicKern_Validate only.
341 */
342 FT_EXPORT( void )
343 FT_ClassicKern_Free( FT_Face face,
344 FT_Bytes table );
345
346 /* */
347
348
349 FT_END_HEADER
350
351 #endif /* FTGXVAL_H_ */
352
353
354 /* END */