ftgxval.h (10625B)
1 /**************************************************************************** 2 * 3 * ftgxval.h 4 * 5 * FreeType API for validating TrueTypeGX/AAT tables (specification). 6 * 7 * Copyright (C) 2004-2025 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 */