1 /**************************************************************************** 2 * 3 * ftgxval.h 4 * 5 * FreeType API for validating TrueTypeGX/AAT tables (specification). 6 * 7 * Copyright (C) 2004-2019 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 some 57 * TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd, trak, 58 * 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 error 193 * 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. The array 210 * 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 @FT_TrueTypeGX_Validate. 246 * 247 * @note: 248 * This function must be used to free the buffer allocated by 249 * @FT_TrueTypeGX_Validate only. 250 */ 251 FT_EXPORT( void ) 252 FT_TrueTypeGX_Free( FT_Face face, 253 FT_Bytes table ); 254 255 256 /************************************************************************** 257 * 258 * @enum: 259 * FT_VALIDATE_CKERNXXX 260 * 261 * @description: 262 * A list of bit-field constants used with @FT_ClassicKern_Validate to 263 * indicate the classic kern dialect or dialects. If the selected type 264 * doesn't fit, @FT_ClassicKern_Validate regards the table as invalid. 265 * 266 * @values: 267 * FT_VALIDATE_MS :: 268 * Handle the 'kern' table as a classic Microsoft kern table. 269 * 270 * FT_VALIDATE_APPLE :: 271 * Handle the 'kern' table as a classic Apple kern table. 272 * 273 * FT_VALIDATE_CKERN :: 274 * Handle the 'kern' as either classic Apple or Microsoft kern table. 275 */ 276 #define FT_VALIDATE_MS ( FT_VALIDATE_GX_START << 0 ) 277 #define FT_VALIDATE_APPLE ( FT_VALIDATE_GX_START << 1 ) 278 279 #define FT_VALIDATE_CKERN ( FT_VALIDATE_MS | FT_VALIDATE_APPLE ) 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 289 * offsets and indices are valid. The idea is that a higher-level 290 * library that actually does the text layout can access those tables 291 * without error 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 that 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 * @function: 326 * FT_ClassicKern_Free 327 * 328 * @description: 329 * Free the buffer allocated by classic Kern validator. 330 * 331 * @input: 332 * face :: 333 * A handle to the input face. 334 * 335 * table :: 336 * The pointer to the buffer that is allocated by 337 * @FT_ClassicKern_Validate. 338 * 339 * @note: 340 * This function must be used to free the buffer allocated by 341 * @FT_ClassicKern_Validate only. 342 */ 343 FT_EXPORT( void ) 344 FT_ClassicKern_Free( FT_Face face, 345 FT_Bytes table ); 346 347 /* */ 348 349 350 FT_END_HEADER 351 352 #endif /* FTGXVAL_H_ */ 353 354 355 /* END */ 356