1 /****************************************************************************
2  *
3  * ftotval.h
4  *
5  *   FreeType API for validating OpenType tables (specification).
6  *
7  * Copyright (C) 2004-2020 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 /****************************************************************************
20  *
21  *
22  * Warning: This module might be moved to a different library in the
23  *          future to avoid a tight dependency between FreeType and the
24  *          OpenType specification.
25  *
26  *
27  */
28 
29 
30 #ifndef FTOTVAL_H_
31 #define FTOTVAL_H_
32 
33 #include <freetype/freetype.h>
34 
35 #ifdef FREETYPE_H
36 #error "freetype.h of FreeType 1 has been loaded!"
37 #error "Please fix the directory search order for header files"
38 #error "so that freetype.h of FreeType 2 is found first."
39 #endif
40 
41 
42 FT_BEGIN_HEADER
43 
44 
45   /**************************************************************************
46    *
47    * @section:
48    *   ot_validation
49    *
50    * @title:
51    *   OpenType Validation
52    *
53    * @abstract:
54    *   An API to validate OpenType tables.
55    *
56    * @description:
57    *   This section contains the declaration of functions to validate some
58    *   OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH).
59    *
60    * @order:
61    *   FT_OpenType_Validate
62    *   FT_OpenType_Free
63    *
64    *   FT_VALIDATE_OTXXX
65    *
66    */
67 
68 
69   /**************************************************************************
70    *
71    * @enum:
72    *    FT_VALIDATE_OTXXX
73    *
74    * @description:
75    *    A list of bit-field constants used with @FT_OpenType_Validate to
76    *    indicate which OpenType tables should be validated.
77    *
78    * @values:
79    *    FT_VALIDATE_BASE ::
80    *      Validate BASE table.
81    *
82    *    FT_VALIDATE_GDEF ::
83    *      Validate GDEF table.
84    *
85    *    FT_VALIDATE_GPOS ::
86    *      Validate GPOS table.
87    *
88    *    FT_VALIDATE_GSUB ::
89    *      Validate GSUB table.
90    *
91    *    FT_VALIDATE_JSTF ::
92    *      Validate JSTF table.
93    *
94    *    FT_VALIDATE_MATH ::
95    *      Validate MATH table.
96    *
97    *    FT_VALIDATE_OT ::
98    *      Validate all OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH).
99    *
100    */
101 #define FT_VALIDATE_BASE  0x0100
102 #define FT_VALIDATE_GDEF  0x0200
103 #define FT_VALIDATE_GPOS  0x0400
104 #define FT_VALIDATE_GSUB  0x0800
105 #define FT_VALIDATE_JSTF  0x1000
106 #define FT_VALIDATE_MATH  0x2000
107 
108 #define FT_VALIDATE_OT  ( FT_VALIDATE_BASE | \
109                           FT_VALIDATE_GDEF | \
110                           FT_VALIDATE_GPOS | \
111                           FT_VALIDATE_GSUB | \
112                           FT_VALIDATE_JSTF | \
113                           FT_VALIDATE_MATH )
114 
115 
116   /**************************************************************************
117    *
118    * @function:
119    *    FT_OpenType_Validate
120    *
121    * @description:
122    *    Validate various OpenType tables to assure that all offsets and
123    *    indices are valid.  The idea is that a higher-level library that
124    *    actually does the text layout can access those tables without error
125    *    checking (which can be quite time consuming).
126    *
127    * @input:
128    *    face ::
129    *      A handle to the input face.
130    *
131    *    validation_flags ::
132    *      A bit field that specifies the tables to be validated.  See
133    *      @FT_VALIDATE_OTXXX for possible values.
134    *
135    * @output:
136    *    BASE_table ::
137    *      A pointer to the BASE table.
138    *
139    *    GDEF_table ::
140    *      A pointer to the GDEF table.
141    *
142    *    GPOS_table ::
143    *      A pointer to the GPOS table.
144    *
145    *    GSUB_table ::
146    *      A pointer to the GSUB table.
147    *
148    *    JSTF_table ::
149    *      A pointer to the JSTF table.
150    *
151    * @return:
152    *   FreeType error code.  0~means success.
153    *
154    * @note:
155    *   This function only works with OpenType fonts, returning an error
156    *   otherwise.
157    *
158    *   After use, the application should deallocate the five tables with
159    *   @FT_OpenType_Free.  A `NULL` value indicates that the table either
160    *   doesn't exist in the font, or the application hasn't asked for
161    *   validation.
162    */
163   FT_EXPORT( FT_Error )
164   FT_OpenType_Validate( FT_Face    face,
165                         FT_UInt    validation_flags,
166                         FT_Bytes  *BASE_table,
167                         FT_Bytes  *GDEF_table,
168                         FT_Bytes  *GPOS_table,
169                         FT_Bytes  *GSUB_table,
170                         FT_Bytes  *JSTF_table );
171 
172 
173   /**************************************************************************
174    *
175    * @function:
176    *    FT_OpenType_Free
177    *
178    * @description:
179    *    Free the buffer allocated by OpenType validator.
180    *
181    * @input:
182    *    face ::
183    *      A handle to the input face.
184    *
185    *    table ::
186    *      The pointer to the buffer that is allocated by
187    *      @FT_OpenType_Validate.
188    *
189    * @note:
190    *   This function must be used to free the buffer allocated by
191    *   @FT_OpenType_Validate only.
192    */
193   FT_EXPORT( void )
194   FT_OpenType_Free( FT_Face   face,
195                     FT_Bytes  table );
196 
197 
198   /* */
199 
200 
201 FT_END_HEADER
202 
203 #endif /* FTOTVAL_H_ */
204 
205 
206 /* END */
207