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