freetype2/freetype/ftgxval.h

0001 /****************************************************************************
0002  *
0003  * ftgxval.h
0004  *
0005  *   FreeType API for validating TrueTypeGX/AAT tables (specification).
0006  *
0007  * Copyright (C) 2004-2023 by
0008  * Masatake YAMATO, Redhat K.K,
0009  * David Turner, Robert Wilhelm, and Werner Lemberg.
0010  *
0011  * This file is part of the FreeType project, and may only be used,
0012  * modified, and distributed under the terms of the FreeType project
0013  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0014  * this file you indicate that you have read the license and
0015  * understand and accept it fully.
0016  *
0017  */
0018
0019 /****************************************************************************
0020  *
0021  * gxvalid is derived from both gxlayout module and otvalid module.
0022  * Development of gxlayout is supported by the Information-technology
0023  * Promotion Agency(IPA), Japan.
0024  *
0025  */
0026
0027
0028 #ifndef FTGXVAL_H_
0029 #define FTGXVAL_H_
0030
0031 #include <freetype/freetype.h>
0032
0033 #ifdef FREETYPE_H
0034 #error "freetype.h of FreeType 1 has been loaded!"
0035 #error "Please fix the directory search order for header files"
0036 #error "so that freetype.h of FreeType 2 is found first."
0037 #endif
0038
0039
0040 FT_BEGIN_HEADER
0041
0042
0043   /**************************************************************************
0044    *
0045    * @section:
0046    *   gx_validation
0047    *
0048    * @title:
0049    *   TrueTypeGX/AAT Validation
0050    *
0051    * @abstract:
0052    *   An API to validate TrueTypeGX/AAT tables.
0053    *
0054    * @description:
0055    *   This section contains the declaration of functions to validate some
0056    *   TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd, trak,
0057    *   prop, lcar).
0058    *
0059    * @order:
0060    *   FT_TrueTypeGX_Validate
0061    *   FT_TrueTypeGX_Free
0062    *
0063    *   FT_ClassicKern_Validate
0064    *   FT_ClassicKern_Free
0065    *
0066    *   FT_VALIDATE_GX_LENGTH
0067    *   FT_VALIDATE_GXXXX
0068    *   FT_VALIDATE_CKERNXXX
0069    *
0070    */
0071
0072   /**************************************************************************
0073    *
0074    *
0075    * Warning: Use `FT_VALIDATE_XXX` to validate a table.
0076    *          Following definitions are for gxvalid developers.
0077    *
0078    *
0079    */
0080
0081 #define FT_VALIDATE_feat_INDEX     0
0082 #define FT_VALIDATE_mort_INDEX     1
0083 #define FT_VALIDATE_morx_INDEX     2
0084 #define FT_VALIDATE_bsln_INDEX     3
0085 #define FT_VALIDATE_just_INDEX     4
0086 #define FT_VALIDATE_kern_INDEX     5
0087 #define FT_VALIDATE_opbd_INDEX     6
0088 #define FT_VALIDATE_trak_INDEX     7
0089 #define FT_VALIDATE_prop_INDEX     8
0090 #define FT_VALIDATE_lcar_INDEX     9
0091 #define FT_VALIDATE_GX_LAST_INDEX  FT_VALIDATE_lcar_INDEX
0092
0093
0094   /**************************************************************************
0095    *
0096    * @macro:
0097    *   FT_VALIDATE_GX_LENGTH
0098    *
0099    * @description:
0100    *   The number of tables checked in this module.  Use it as a parameter
0101    *   for the `table-length` argument of function @FT_TrueTypeGX_Validate.
0102    */
0103 #define FT_VALIDATE_GX_LENGTH  ( FT_VALIDATE_GX_LAST_INDEX + 1 )
0104
0105   /* */
0106
0107   /* Up to 0x1000 is used by otvalid.
0108      Ox2xxx is reserved for feature OT extension. */
0109 #define FT_VALIDATE_GX_START  0x4000
0110 #define FT_VALIDATE_GX_BITFIELD( tag ) \
0111           ( FT_VALIDATE_GX_START << FT_VALIDATE_##tag##_INDEX )
0112
0113
0114   /**************************************************************************
0115    *
0116    * @enum:
0117    *    FT_VALIDATE_GXXXX
0118    *
0119    * @description:
0120    *    A list of bit-field constants used with @FT_TrueTypeGX_Validate to
0121    *    indicate which TrueTypeGX/AAT Type tables should be validated.
0122    *
0123    * @values:
0124    *    FT_VALIDATE_feat ::
0125    *      Validate 'feat' table.
0126    *
0127    *    FT_VALIDATE_mort ::
0128    *      Validate 'mort' table.
0129    *
0130    *    FT_VALIDATE_morx ::
0131    *      Validate 'morx' table.
0132    *
0133    *    FT_VALIDATE_bsln ::
0134    *      Validate 'bsln' table.
0135    *
0136    *    FT_VALIDATE_just ::
0137    *      Validate 'just' table.
0138    *
0139    *    FT_VALIDATE_kern ::
0140    *      Validate 'kern' table.
0141    *
0142    *    FT_VALIDATE_opbd ::
0143    *      Validate 'opbd' table.
0144    *
0145    *    FT_VALIDATE_trak ::
0146    *      Validate 'trak' table.
0147    *
0148    *    FT_VALIDATE_prop ::
0149    *      Validate 'prop' table.
0150    *
0151    *    FT_VALIDATE_lcar ::
0152    *      Validate 'lcar' table.
0153    *
0154    *    FT_VALIDATE_GX ::
0155    *      Validate all TrueTypeGX tables (feat, mort, morx, bsln, just, kern,
0156    *      opbd, trak, prop and lcar).
0157    *
0158    */
0159
0160 #define FT_VALIDATE_feat  FT_VALIDATE_GX_BITFIELD( feat )
0161 #define FT_VALIDATE_mort  FT_VALIDATE_GX_BITFIELD( mort )
0162 #define FT_VALIDATE_morx  FT_VALIDATE_GX_BITFIELD( morx )
0163 #define FT_VALIDATE_bsln  FT_VALIDATE_GX_BITFIELD( bsln )
0164 #define FT_VALIDATE_just  FT_VALIDATE_GX_BITFIELD( just )
0165 #define FT_VALIDATE_kern  FT_VALIDATE_GX_BITFIELD( kern )
0166 #define FT_VALIDATE_opbd  FT_VALIDATE_GX_BITFIELD( opbd )
0167 #define FT_VALIDATE_trak  FT_VALIDATE_GX_BITFIELD( trak )
0168 #define FT_VALIDATE_prop  FT_VALIDATE_GX_BITFIELD( prop )
0169 #define FT_VALIDATE_lcar  FT_VALIDATE_GX_BITFIELD( lcar )
0170
0171 #define FT_VALIDATE_GX  ( FT_VALIDATE_feat | \
0172                           FT_VALIDATE_mort | \
0173                           FT_VALIDATE_morx | \
0174                           FT_VALIDATE_bsln | \
0175                           FT_VALIDATE_just | \
0176                           FT_VALIDATE_kern | \
0177                           FT_VALIDATE_opbd | \
0178                           FT_VALIDATE_trak | \
0179                           FT_VALIDATE_prop | \
0180                           FT_VALIDATE_lcar )
0181
0182
0183   /**************************************************************************
0184    *
0185    * @function:
0186    *    FT_TrueTypeGX_Validate
0187    *
0188    * @description:
0189    *    Validate various TrueTypeGX tables to assure that all offsets and
0190    *    indices are valid.  The idea is that a higher-level library that
0191    *    actually does the text layout can access those tables without error
0192    *    checking (which can be quite time consuming).
0193    *
0194    * @input:
0195    *    face ::
0196    *      A handle to the input face.
0197    *
0198    *    validation_flags ::
0199    *      A bit field that specifies the tables to be validated.  See
0200    *      @FT_VALIDATE_GXXXX for possible values.
0201    *
0202    *    table_length ::
0203    *      The size of the `tables` array.  Normally, @FT_VALIDATE_GX_LENGTH
0204    *      should be passed.
0205    *
0206    * @output:
0207    *    tables ::
0208    *      The array where all validated sfnt tables are stored.  The array
0209    *      itself must be allocated by a client.
0210    *
0211    * @return:
0212    *   FreeType error code.  0~means success.
0213    *
0214    * @note:
0215    *   This function only works with TrueTypeGX fonts, returning an error
0216    *   otherwise.
0217    *
0218    *   After use, the application should deallocate the buffers pointed to by
0219    *   each `tables` element, by calling @FT_TrueTypeGX_Free.  A `NULL` value
0220    *   indicates that the table either doesn't exist in the font, the
0221    *   application hasn't asked for validation, or the validator doesn't have
0222    *   the ability to validate the sfnt table.
0223    */
0224   FT_EXPORT( FT_Error )
0225   FT_TrueTypeGX_Validate( FT_Face   face,
0226                           FT_UInt   validation_flags,
0227                           FT_Bytes  tables[FT_VALIDATE_GX_LENGTH],
0228                           FT_UInt   table_length );
0229
0230
0231   /**************************************************************************
0232    *
0233    * @function:
0234    *    FT_TrueTypeGX_Free
0235    *
0236    * @description:
0237    *    Free the buffer allocated by TrueTypeGX validator.
0238    *
0239    * @input:
0240    *    face ::
0241    *      A handle to the input face.
0242    *
0243    *    table ::
0244    *      The pointer to the buffer allocated by @FT_TrueTypeGX_Validate.
0245    *
0246    * @note:
0247    *   This function must be used to free the buffer allocated by
0248    *   @FT_TrueTypeGX_Validate only.
0249    */
0250   FT_EXPORT( void )
0251   FT_TrueTypeGX_Free( FT_Face   face,
0252                       FT_Bytes  table );
0253
0254
0255   /**************************************************************************
0256    *
0257    * @enum:
0258    *    FT_VALIDATE_CKERNXXX
0259    *
0260    * @description:
0261    *    A list of bit-field constants used with @FT_ClassicKern_Validate to
0262    *    indicate the classic kern dialect or dialects.  If the selected type
0263    *    doesn't fit, @FT_ClassicKern_Validate regards the table as invalid.
0264    *
0265    * @values:
0266    *    FT_VALIDATE_MS ::
0267    *      Handle the 'kern' table as a classic Microsoft kern table.
0268    *
0269    *    FT_VALIDATE_APPLE ::
0270    *      Handle the 'kern' table as a classic Apple kern table.
0271    *
0272    *    FT_VALIDATE_CKERN ::
0273    *      Handle the 'kern' as either classic Apple or Microsoft kern table.
0274    */
0275 #define FT_VALIDATE_MS     ( FT_VALIDATE_GX_START << 0 )
0276 #define FT_VALIDATE_APPLE  ( FT_VALIDATE_GX_START << 1 )
0277
0278 #define FT_VALIDATE_CKERN  ( FT_VALIDATE_MS | FT_VALIDATE_APPLE )
0279
0280
0281   /**************************************************************************
0282    *
0283    * @function:
0284    *    FT_ClassicKern_Validate
0285    *
0286    * @description:
0287    *    Validate classic (16-bit format) kern table to assure that the
0288    *    offsets and indices are valid.  The idea is that a higher-level
0289    *    library that actually does the text layout can access those tables
0290    *    without error checking (which can be quite time consuming).
0291    *
0292    *    The 'kern' table validator in @FT_TrueTypeGX_Validate deals with both
0293    *    the new 32-bit format and the classic 16-bit format, while
0294    *    FT_ClassicKern_Validate only supports the classic 16-bit format.
0295    *
0296    * @input:
0297    *    face ::
0298    *      A handle to the input face.
0299    *
0300    *    validation_flags ::
0301    *      A bit field that specifies the dialect to be validated.  See
0302    *      @FT_VALIDATE_CKERNXXX for possible values.
0303    *
0304    * @output:
0305    *    ckern_table ::
0306    *      A pointer to the kern table.
0307    *
0308    * @return:
0309    *   FreeType error code.  0~means success.
0310    *
0311    * @note:
0312    *   After use, the application should deallocate the buffers pointed to by
0313    *   `ckern_table`, by calling @FT_ClassicKern_Free.  A `NULL` value
0314    *   indicates that the table doesn't exist in the font.
0315    */
0316   FT_EXPORT( FT_Error )
0317   FT_ClassicKern_Validate( FT_Face    face,
0318                            FT_UInt    validation_flags,
0319                            FT_Bytes  *ckern_table );
0320
0321
0322   /**************************************************************************
0323    *
0324    * @function:
0325    *    FT_ClassicKern_Free
0326    *
0327    * @description:
0328    *    Free the buffer allocated by classic Kern validator.
0329    *
0330    * @input:
0331    *    face ::
0332    *      A handle to the input face.
0333    *
0334    *    table ::
0335    *      The pointer to the buffer that is allocated by
0336    *      @FT_ClassicKern_Validate.
0337    *
0338    * @note:
0339    *   This function must be used to free the buffer allocated by
0340    *   @FT_ClassicKern_Validate only.
0341    */
0342   FT_EXPORT( void )
0343   FT_ClassicKern_Free( FT_Face   face,
0344                        FT_Bytes  table );
0345
0346   /* */
0347
0348
0349 FT_END_HEADER
0350
0351 #endif /* FTGXVAL_H_ */
0352
0353
0354 /* END */