text: /****************************************************************************
   *
   * ftgxval.h
   *
   *   FreeType API for validating TrueTypeGX/AAT tables (specification).
   *
   * Copyright (C) 2004-2021 by
   * Masatake YAMATO, Redhat K.K,
   * David Turner, Robert Wilhelm, and Werner Lemberg.
   *
   * This file is part of the FreeType project, and may only be used,
   * modified, and distributed under the terms of the FreeType project
   * license, LICENSE.TXT.  By continuing to use, modify, or distribute
   * this file you indicate that you have read the license and
   * understand and accept it fully.
   *
   */
  
  /****************************************************************************
   *
   * gxvalid is derived from both gxlayout module and otvalid module.
   * Development of gxlayout is supported by the Information-technology
   * Promotion Agency(IPA), Japan.
   *
   */
  
  
  #ifndef FTGXVAL_H_
  #define FTGXVAL_H_
  
  #include <freetype/freetype.h>
  
  #ifdef FREETYPE_H
  #error "freetype.h of FreeType 1 has been loaded!"
  #error "Please fix the directory search order for header files"
  #error "so that freetype.h of FreeType 2 is found first."
  #endif
  
  
  FT_BEGIN_HEADER
  
  
    /**************************************************************************
     *
     * @section:
     *   gx_validation
     *
     * @title:
     *   TrueTypeGX/AAT Validation
     *
     * @abstract:
     *   An API to validate TrueTypeGX/AAT tables.
     *
     * @description:
     *   This section contains the declaration of functions to validate some
     *   TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd, trak,
     *   prop, lcar).
     *
     * @order:
     *   FT_TrueTypeGX_Validate
     *   FT_TrueTypeGX_Free
     *
     *   FT_ClassicKern_Validate
     *   FT_ClassicKern_Free
     *
     *   FT_VALIDATE_GX_LENGTH
     *   FT_VALIDATE_GXXXX
     *   FT_VALIDATE_CKERNXXX
     *
     */
  
    /**************************************************************************
     *
     *
     * Warning: Use `FT_VALIDATE_XXX` to validate a table.
     *          Following definitions are for gxvalid developers.
     *
     *
     */
  
  #define FT_VALIDATE_feat_INDEX     0
  #define FT_VALIDATE_mort_INDEX     1
  #define FT_VALIDATE_morx_INDEX     2
  #define FT_VALIDATE_bsln_INDEX     3
  #define FT_VALIDATE_just_INDEX     4
  #define FT_VALIDATE_kern_INDEX     5
  #define FT_VALIDATE_opbd_INDEX     6
  #define FT_VALIDATE_trak_INDEX     7
  #define FT_VALIDATE_prop_INDEX     8
  #define FT_VALIDATE_lcar_INDEX     9
  #define FT_VALIDATE_GX_LAST_INDEX  FT_VALIDATE_lcar_INDEX
  
  
    /**************************************************************************
     *
     * @macro:
     *   FT_VALIDATE_GX_LENGTH
     *
     * @description:
     *   The number of tables checked in this module.  Use it as a parameter
     *   for the `table-length` argument of function @FT_TrueTypeGX_Validate.
     */
  #define FT_VALIDATE_GX_LENGTH  ( FT_VALIDATE_GX_LAST_INDEX + 1 )
  
    /* */
  
    /* Up to 0x1000 is used by otvalid.
       Ox2xxx is reserved for feature OT extension. */
  #define FT_VALIDATE_GX_START  0x4000
  #define FT_VALIDATE_GX_BITFIELD( tag ) \
            ( FT_VALIDATE_GX_START << FT_VALIDATE_##tag##_INDEX )
  
  
    /**************************************************************************
     *
     * @enum:
     *    FT_VALIDATE_GXXXX
     *
     * @description:
     *    A list of bit-field constants used with @FT_TrueTypeGX_Validate to
     *    indicate which TrueTypeGX/AAT Type tables should be validated.
     *
     * @values:
     *    FT_VALIDATE_feat ::
     *      Validate 'feat' table.
     *
     *    FT_VALIDATE_mort ::
     *      Validate 'mort' table.
     *
     *    FT_VALIDATE_morx ::
     *      Validate 'morx' table.
     *
     *    FT_VALIDATE_bsln ::
     *      Validate 'bsln' table.
     *
     *    FT_VALIDATE_just ::
     *      Validate 'just' table.
     *
     *    FT_VALIDATE_kern ::
     *      Validate 'kern' table.
     *
     *    FT_VALIDATE_opbd ::
     *      Validate 'opbd' table.
     *
     *    FT_VALIDATE_trak ::
     *      Validate 'trak' table.
     *
     *    FT_VALIDATE_prop ::
     *      Validate 'prop' table.
     *
     *    FT_VALIDATE_lcar ::
     *      Validate 'lcar' table.
     *
     *    FT_VALIDATE_GX ::
     *      Validate all TrueTypeGX tables (feat, mort, morx, bsln, just, kern,
     *      opbd, trak, prop and lcar).
     *
     */
  
  #define FT_VALIDATE_feat  FT_VALIDATE_GX_BITFIELD( feat )
  #define FT_VALIDATE_mort  FT_VALIDATE_GX_BITFIELD( mort )
  #define FT_VALIDATE_morx  FT_VALIDATE_GX_BITFIELD( morx )
  #define FT_VALIDATE_bsln  FT_VALIDATE_GX_BITFIELD( bsln )
  #define FT_VALIDATE_just  FT_VALIDATE_GX_BITFIELD( just )
  #define FT_VALIDATE_kern  FT_VALIDATE_GX_BITFIELD( kern )
  #define FT_VALIDATE_opbd  FT_VALIDATE_GX_BITFIELD( opbd )
  #define FT_VALIDATE_trak  FT_VALIDATE_GX_BITFIELD( trak )
  #define FT_VALIDATE_prop  FT_VALIDATE_GX_BITFIELD( prop )
  #define FT_VALIDATE_lcar  FT_VALIDATE_GX_BITFIELD( lcar )
  
  #define FT_VALIDATE_GX  ( FT_VALIDATE_feat | \
                            FT_VALIDATE_mort | \
                            FT_VALIDATE_morx | \
                            FT_VALIDATE_bsln | \
                            FT_VALIDATE_just | \
                            FT_VALIDATE_kern | \
                            FT_VALIDATE_opbd | \
                            FT_VALIDATE_trak | \
                            FT_VALIDATE_prop | \
                            FT_VALIDATE_lcar )
  
  
    /**************************************************************************
     *
     * @function:
     *    FT_TrueTypeGX_Validate
     *
     * @description:
     *    Validate various TrueTypeGX tables to assure that all offsets and
     *    indices are valid.  The idea is that a higher-level library that
     *    actually does the text layout can access those tables without error
     *    checking (which can be quite time consuming).
     *
     * @input:
     *    face ::
     *      A handle to the input face.
     *
     *    validation_flags ::
     *      A bit field that specifies the tables to be validated.  See
     *      @FT_VALIDATE_GXXXX for possible values.
     *
     *    table_length ::
     *      The size of the `tables` array.  Normally, @FT_VALIDATE_GX_LENGTH
     *      should be passed.
     *
     * @output:
     *    tables ::
     *      The array where all validated sfnt tables are stored.  The array
     *      itself must be allocated by a client.
     *
     * @return:
     *   FreeType error code.  0~means success.
     *
     * @note:
     *   This function only works with TrueTypeGX fonts, returning an error
     *   otherwise.
     *
     *   After use, the application should deallocate the buffers pointed to by
     *   each `tables` element, by calling @FT_TrueTypeGX_Free.  A `NULL` value
     *   indicates that the table either doesn't exist in the font, the
     *   application hasn't asked for validation, or the validator doesn't have
     *   the ability to validate the sfnt table.
     */
    FT_EXPORT( FT_Error )
    FT_TrueTypeGX_Validate( FT_Face   face,
                            FT_UInt   validation_flags,
                            FT_Bytes  tables[FT_VALIDATE_GX_LENGTH],
                            FT_UInt   table_length );
  
  
    /**************************************************************************
     *
     * @function:
     *    FT_TrueTypeGX_Free
     *
     * @description:
     *    Free the buffer allocated by TrueTypeGX validator.
     *
     * @input:
     *    face ::
     *      A handle to the input face.
     *
     *    table ::
     *      The pointer to the buffer allocated by @FT_TrueTypeGX_Validate.
     *
     * @note:
     *   This function must be used to free the buffer allocated by
     *   @FT_TrueTypeGX_Validate only.
     */
    FT_EXPORT( void )
    FT_TrueTypeGX_Free( FT_Face   face,
                        FT_Bytes  table );
  
  
    /**************************************************************************
     *
     * @enum:
     *    FT_VALIDATE_CKERNXXX
     *
     * @description:
     *    A list of bit-field constants used with @FT_ClassicKern_Validate to
     *    indicate the classic kern dialect or dialects.  If the selected type
     *    doesn't fit, @FT_ClassicKern_Validate regards the table as invalid.
     *
     * @values:
     *    FT_VALIDATE_MS ::
     *      Handle the 'kern' table as a classic Microsoft kern table.
     *
     *    FT_VALIDATE_APPLE ::
     *      Handle the 'kern' table as a classic Apple kern table.
     *
     *    FT_VALIDATE_CKERN ::
     *      Handle the 'kern' as either classic Apple or Microsoft kern table.
     */
  #define FT_VALIDATE_MS     ( FT_VALIDATE_GX_START << 0 )
  #define FT_VALIDATE_APPLE  ( FT_VALIDATE_GX_START << 1 )
  
  #define FT_VALIDATE_CKERN  ( FT_VALIDATE_MS | FT_VALIDATE_APPLE )
  
  
    /**************************************************************************
     *
     * @function:
     *    FT_ClassicKern_Validate
     *
     * @description:
     *    Validate classic (16-bit format) kern table to assure that the
     *    offsets and indices are valid.  The idea is that a higher-level
     *    library that actually does the text layout can access those tables
     *    without error checking (which can be quite time consuming).
     *
     *    The 'kern' table validator in @FT_TrueTypeGX_Validate deals with both
     *    the new 32-bit format and the classic 16-bit format, while
     *    FT_ClassicKern_Validate only supports the classic 16-bit format.
     *
     * @input:
     *    face ::
     *      A handle to the input face.
     *
     *    validation_flags ::
     *      A bit field that specifies the dialect to be validated.  See
     *      @FT_VALIDATE_CKERNXXX for possible values.
     *
     * @output:
     *    ckern_table ::
     *      A pointer to the kern table.
     *
     * @return:
     *   FreeType error code.  0~means success.
     *
     * @note:
     *   After use, the application should deallocate the buffers pointed to by
     *   `ckern_table`, by calling @FT_ClassicKern_Free.  A `NULL` value
     *   indicates that the table doesn't exist in the font.
     */
    FT_EXPORT( FT_Error )
    FT_ClassicKern_Validate( FT_Face    face,
                             FT_UInt    validation_flags,
                             FT_Bytes  *ckern_table );
  
  
    /**************************************************************************
     *
     * @function:
     *    FT_ClassicKern_Free
     *
     * @description:
     *    Free the buffer allocated by classic Kern validator.
     *
     * @input:
     *    face ::
     *      A handle to the input face.
     *
     *    table ::
     *      The pointer to the buffer that is allocated by
     *      @FT_ClassicKern_Validate.
     *
     * @note:
     *   This function must be used to free the buffer allocated by
     *   @FT_ClassicKern_Validate only.
     */
    FT_EXPORT( void )
    FT_ClassicKern_Free( FT_Face   face,
                         FT_Bytes  table );
  
    /* */
  
  
  FT_END_HEADER
  
  #endif /* FTGXVAL_H_ */
  
  
  /* END */
  