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