1 /****************************************************************************
2 *
3 * ftotval.h
4 *
5 * FreeType API for validating OpenType tables (specification).
6 *
7 * Copyright (C) 2004-2023 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 */