freetype2/freetype/ftotval.h

0001 /****************************************************************************
0002  *
0003  * ftotval.h
0004  *
0005  *   FreeType API for validating OpenType tables (specification).
0006  *
0007  * Copyright (C) 2004-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 /****************************************************************************
0020  *
0021  *
0022  * Warning: This module might be moved to a different library in the
0023  *          future to avoid a tight dependency between FreeType and the
0024  *          OpenType specification.
0025  *
0026  *
0027  */
0028
0029
0030 #ifndef FTOTVAL_H_
0031 #define FTOTVAL_H_
0032
0033 #include <freetype/freetype.h>
0034
0035 #ifdef FREETYPE_H
0036 #error "freetype.h of FreeType 1 has been loaded!"
0037 #error "Please fix the directory search order for header files"
0038 #error "so that freetype.h of FreeType 2 is found first."
0039 #endif
0040
0041
0042 FT_BEGIN_HEADER
0043
0044
0045   /**************************************************************************
0046    *
0047    * @section:
0048    *   ot_validation
0049    *
0050    * @title:
0051    *   OpenType Validation
0052    *
0053    * @abstract:
0054    *   An API to validate OpenType tables.
0055    *
0056    * @description:
0057    *   This section contains the declaration of functions to validate some
0058    *   OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH).
0059    *
0060    * @order:
0061    *   FT_OpenType_Validate
0062    *   FT_OpenType_Free
0063    *
0064    *   FT_VALIDATE_OTXXX
0065    *
0066    */
0067
0068
0069   /**************************************************************************
0070    *
0071    * @enum:
0072    *    FT_VALIDATE_OTXXX
0073    *
0074    * @description:
0075    *    A list of bit-field constants used with @FT_OpenType_Validate to
0076    *    indicate which OpenType tables should be validated.
0077    *
0078    * @values:
0079    *    FT_VALIDATE_BASE ::
0080    *      Validate BASE table.
0081    *
0082    *    FT_VALIDATE_GDEF ::
0083    *      Validate GDEF table.
0084    *
0085    *    FT_VALIDATE_GPOS ::
0086    *      Validate GPOS table.
0087    *
0088    *    FT_VALIDATE_GSUB ::
0089    *      Validate GSUB table.
0090    *
0091    *    FT_VALIDATE_JSTF ::
0092    *      Validate JSTF table.
0093    *
0094    *    FT_VALIDATE_MATH ::
0095    *      Validate MATH table.
0096    *
0097    *    FT_VALIDATE_OT ::
0098    *      Validate all OpenType tables (BASE, GDEF, GPOS, GSUB, JSTF, MATH).
0099    *
0100    */
0101 #define FT_VALIDATE_BASE  0x0100
0102 #define FT_VALIDATE_GDEF  0x0200
0103 #define FT_VALIDATE_GPOS  0x0400
0104 #define FT_VALIDATE_GSUB  0x0800
0105 #define FT_VALIDATE_JSTF  0x1000
0106 #define FT_VALIDATE_MATH  0x2000
0107
0108 #define FT_VALIDATE_OT  ( FT_VALIDATE_BASE | \
0109                           FT_VALIDATE_GDEF | \
0110                           FT_VALIDATE_GPOS | \
0111                           FT_VALIDATE_GSUB | \
0112                           FT_VALIDATE_JSTF | \
0113                           FT_VALIDATE_MATH )
0114
0115
0116   /**************************************************************************
0117    *
0118    * @function:
0119    *    FT_OpenType_Validate
0120    *
0121    * @description:
0122    *    Validate various OpenType tables to assure that all offsets and
0123    *    indices are valid.  The idea is that a higher-level library that
0124    *    actually does the text layout can access those tables without error
0125    *    checking (which can be quite time consuming).
0126    *
0127    * @input:
0128    *    face ::
0129    *      A handle to the input face.
0130    *
0131    *    validation_flags ::
0132    *      A bit field that specifies the tables to be validated.  See
0133    *      @FT_VALIDATE_OTXXX for possible values.
0134    *
0135    * @output:
0136    *    BASE_table ::
0137    *      A pointer to the BASE table.
0138    *
0139    *    GDEF_table ::
0140    *      A pointer to the GDEF table.
0141    *
0142    *    GPOS_table ::
0143    *      A pointer to the GPOS table.
0144    *
0145    *    GSUB_table ::
0146    *      A pointer to the GSUB table.
0147    *
0148    *    JSTF_table ::
0149    *      A pointer to the JSTF table.
0150    *
0151    * @return:
0152    *   FreeType error code.  0~means success.
0153    *
0154    * @note:
0155    *   This function only works with OpenType fonts, returning an error
0156    *   otherwise.
0157    *
0158    *   After use, the application should deallocate the five tables with
0159    *   @FT_OpenType_Free.  A `NULL` value indicates that the table either
0160    *   doesn't exist in the font, or the application hasn't asked for
0161    *   validation.
0162    */
0163   FT_EXPORT( FT_Error )
0164   FT_OpenType_Validate( FT_Face    face,
0165                         FT_UInt    validation_flags,
0166                         FT_Bytes  *BASE_table,
0167                         FT_Bytes  *GDEF_table,
0168                         FT_Bytes  *GPOS_table,
0169                         FT_Bytes  *GSUB_table,
0170                         FT_Bytes  *JSTF_table );
0171
0172
0173   /**************************************************************************
0174    *
0175    * @function:
0176    *    FT_OpenType_Free
0177    *
0178    * @description:
0179    *    Free the buffer allocated by OpenType validator.
0180    *
0181    * @input:
0182    *    face ::
0183    *      A handle to the input face.
0184    *
0185    *    table ::
0186    *      The pointer to the buffer that is allocated by
0187    *      @FT_OpenType_Validate.
0188    *
0189    * @note:
0190    *   This function must be used to free the buffer allocated by
0191    *   @FT_OpenType_Validate only.
0192    */
0193   FT_EXPORT( void )
0194   FT_OpenType_Free( FT_Face   face,
0195                     FT_Bytes  table );
0196
0197
0198   /* */
0199
0200
0201 FT_END_HEADER
0202
0203 #endif /* FTOTVAL_H_ */
0204
0205
0206 /* END */