misc/libfreetype/include/freetype/ftgxval.h
changeset 5172 88f2e05288ba
equal deleted inserted replaced
5171:f9283dc4860d 5172:88f2e05288ba
       
     1 /***************************************************************************/
       
     2 /*                                                                         */
       
     3 /*  ftgxval.h                                                              */
       
     4 /*                                                                         */
       
     5 /*    FreeType API for validating TrueTypeGX/AAT tables (specification).   */
       
     6 /*                                                                         */
       
     7 /*  Copyright 2004, 2005, 2006 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     */
       
    57   /*    some TrueTypeGX tables (feat, mort, morx, bsln, just, kern, opbd,  */
       
    58   /*    trak, prop, lcar).                                                 */
       
    59   /*                                                                       */
       
    60   /*************************************************************************/
       
    61 
       
    62 
       
    63   /*************************************************************************/
       
    64   /*                                                                       */
       
    65   /*                                                                       */
       
    66   /* Warning: Use FT_VALIDATE_XXX to validate a table.                     */
       
    67   /*          Following definitions are for gxvalid developers.            */
       
    68   /*                                                                       */
       
    69   /*                                                                       */
       
    70   /*************************************************************************/
       
    71 
       
    72 #define FT_VALIDATE_feat_INDEX     0
       
    73 #define FT_VALIDATE_mort_INDEX     1
       
    74 #define FT_VALIDATE_morx_INDEX     2
       
    75 #define FT_VALIDATE_bsln_INDEX     3
       
    76 #define FT_VALIDATE_just_INDEX     4
       
    77 #define FT_VALIDATE_kern_INDEX     5
       
    78 #define FT_VALIDATE_opbd_INDEX     6
       
    79 #define FT_VALIDATE_trak_INDEX     7
       
    80 #define FT_VALIDATE_prop_INDEX     8
       
    81 #define FT_VALIDATE_lcar_INDEX     9
       
    82 #define FT_VALIDATE_GX_LAST_INDEX  FT_VALIDATE_lcar_INDEX
       
    83 
       
    84 
       
    85   /*************************************************************************
       
    86    *
       
    87    * @macro:
       
    88    *   FT_VALIDATE_GX_LENGTH
       
    89    *
       
    90    * @description:
       
    91    *   The number of tables checked in this module.  Use it as a parameter
       
    92    *   for the `table-length' argument of function @FT_TrueTypeGX_Validate.
       
    93    */
       
    94 #define FT_VALIDATE_GX_LENGTH     (FT_VALIDATE_GX_LAST_INDEX + 1)
       
    95 
       
    96   /* */
       
    97 
       
    98   /* Up to 0x1000 is used by otvalid.
       
    99      Ox2xxx is reserved for feature OT extension. */
       
   100 #define FT_VALIDATE_GX_START 0x4000
       
   101 #define FT_VALIDATE_GX_BITFIELD( tag )                  \
       
   102   ( FT_VALIDATE_GX_START << FT_VALIDATE_##tag##_INDEX )
       
   103 
       
   104 
       
   105  /**********************************************************************
       
   106   *
       
   107   * @enum:
       
   108   *    FT_VALIDATE_GXXXX
       
   109   *
       
   110   * @description:
       
   111   *    A list of bit-field constants used with @FT_TrueTypeGX_Validate to
       
   112   *    indicate which TrueTypeGX/AAT Type tables should be validated.
       
   113   *
       
   114   * @values:
       
   115   *    FT_VALIDATE_feat ::
       
   116   *      Validate `feat' table.
       
   117   *
       
   118   *    FT_VALIDATE_mort ::
       
   119   *      Validate `mort' table.
       
   120   *
       
   121   *    FT_VALIDATE_morx ::
       
   122   *      Validate `morx' table.
       
   123   *
       
   124   *    FT_VALIDATE_bsln ::
       
   125   *      Validate `bsln' table.
       
   126   *
       
   127   *    FT_VALIDATE_just ::
       
   128   *      Validate `just' table.
       
   129   *
       
   130   *    FT_VALIDATE_kern ::
       
   131   *      Validate `kern' table.
       
   132   *
       
   133   *    FT_VALIDATE_opbd ::
       
   134   *      Validate `opbd' table.
       
   135   *
       
   136   *    FT_VALIDATE_trak ::
       
   137   *      Validate `trak' table.
       
   138   *
       
   139   *    FT_VALIDATE_prop ::
       
   140   *      Validate `prop' table.
       
   141   *
       
   142   *    FT_VALIDATE_lcar ::
       
   143   *      Validate `lcar' table.
       
   144   *
       
   145   *    FT_VALIDATE_GX ::
       
   146   *      Validate all TrueTypeGX tables (feat, mort, morx, bsln, just, kern,
       
   147   *      opbd, trak, prop and lcar).
       
   148   *
       
   149   */
       
   150 
       
   151 #define FT_VALIDATE_feat  FT_VALIDATE_GX_BITFIELD( feat )
       
   152 #define FT_VALIDATE_mort  FT_VALIDATE_GX_BITFIELD( mort )
       
   153 #define FT_VALIDATE_morx  FT_VALIDATE_GX_BITFIELD( morx )
       
   154 #define FT_VALIDATE_bsln  FT_VALIDATE_GX_BITFIELD( bsln )
       
   155 #define FT_VALIDATE_just  FT_VALIDATE_GX_BITFIELD( just )
       
   156 #define FT_VALIDATE_kern  FT_VALIDATE_GX_BITFIELD( kern )
       
   157 #define FT_VALIDATE_opbd  FT_VALIDATE_GX_BITFIELD( opbd )
       
   158 #define FT_VALIDATE_trak  FT_VALIDATE_GX_BITFIELD( trak )
       
   159 #define FT_VALIDATE_prop  FT_VALIDATE_GX_BITFIELD( prop )
       
   160 #define FT_VALIDATE_lcar  FT_VALIDATE_GX_BITFIELD( lcar )
       
   161 
       
   162 #define FT_VALIDATE_GX  ( FT_VALIDATE_feat | \
       
   163                           FT_VALIDATE_mort | \
       
   164                           FT_VALIDATE_morx | \
       
   165                           FT_VALIDATE_bsln | \
       
   166                           FT_VALIDATE_just | \
       
   167                           FT_VALIDATE_kern | \
       
   168                           FT_VALIDATE_opbd | \
       
   169                           FT_VALIDATE_trak | \
       
   170                           FT_VALIDATE_prop | \
       
   171                           FT_VALIDATE_lcar )
       
   172 
       
   173 
       
   174   /* */
       
   175 
       
   176  /**********************************************************************
       
   177   *
       
   178   * @function:
       
   179   *    FT_TrueTypeGX_Validate
       
   180   *
       
   181   * @description:
       
   182   *    Validate various TrueTypeGX tables to assure that all offsets and
       
   183   *    indices are valid.  The idea is that a higher-level library which
       
   184   *    actually does the text layout can access those tables without
       
   185   *    error checking (which can be quite time consuming).
       
   186   *
       
   187   * @input:
       
   188   *    face ::
       
   189   *       A handle to the input face.
       
   190   *
       
   191   *    validation_flags ::
       
   192   *       A bit field which specifies the tables to be validated.  See
       
   193   *       @FT_VALIDATE_GXXXX for possible values.
       
   194   *
       
   195   *    table_length ::
       
   196   *       The size of the `tables' array.  Normally, @FT_VALIDATE_GX_LENGTH
       
   197   *       should be passed.
       
   198   *
       
   199   * @output:
       
   200   *    tables ::
       
   201   *       The array where all validated sfnt tables are stored.
       
   202   *       The array itself must be allocated by a client.
       
   203   *
       
   204   * @return:
       
   205   *   FreeType error code.  0~means success.
       
   206   *
       
   207   * @note:
       
   208   *   This function only works with TrueTypeGX fonts, returning an error
       
   209   *   otherwise.
       
   210   *
       
   211   *   After use, the application should deallocate the buffers pointed to by
       
   212   *   each `tables' element, by calling @FT_TrueTypeGX_Free.  A NULL value
       
   213   *   indicates that the table either doesn't exist in the font, the
       
   214   *   application hasn't asked for validation, or the validator doesn't have
       
   215   *   the ability to validate the sfnt table.
       
   216   */
       
   217   FT_EXPORT( FT_Error )
       
   218   FT_TrueTypeGX_Validate( FT_Face   face,
       
   219                           FT_UInt   validation_flags,
       
   220                           FT_Bytes  tables[FT_VALIDATE_GX_LENGTH],
       
   221                           FT_UInt   table_length );
       
   222 
       
   223 
       
   224   /* */
       
   225 
       
   226  /**********************************************************************
       
   227   *
       
   228   * @function:
       
   229   *    FT_TrueTypeGX_Free
       
   230   *
       
   231   * @description:
       
   232   *    Free the buffer allocated by TrueTypeGX validator.
       
   233   *
       
   234   * @input:
       
   235   *    face ::
       
   236   *       A handle to the input face.
       
   237   *
       
   238   *    table ::
       
   239   *       The pointer to the buffer allocated by
       
   240   *       @FT_TrueTypeGX_Validate.
       
   241   *
       
   242   * @note:
       
   243   *   This function must be used to free the buffer allocated by
       
   244   *   @FT_TrueTypeGX_Validate only.
       
   245   */
       
   246   FT_EXPORT( void )
       
   247   FT_TrueTypeGX_Free( FT_Face   face,
       
   248                       FT_Bytes  table );
       
   249 
       
   250 
       
   251   /* */
       
   252 
       
   253  /**********************************************************************
       
   254   *
       
   255   * @enum:
       
   256   *    FT_VALIDATE_CKERNXXX
       
   257   *
       
   258   * @description:
       
   259   *    A list of bit-field constants used with @FT_ClassicKern_Validate
       
   260   *    to indicate the classic kern dialect or dialects.  If the selected
       
   261   *    type doesn't fit, @FT_ClassicKern_Validate regards the table as
       
   262   *    invalid.
       
   263   *
       
   264   * @values:
       
   265   *    FT_VALIDATE_MS ::
       
   266   *      Handle the `kern' table as a classic Microsoft kern table.
       
   267   *
       
   268   *    FT_VALIDATE_APPLE ::
       
   269   *      Handle the `kern' table as a classic Apple kern table.
       
   270   *
       
   271   *    FT_VALIDATE_CKERN ::
       
   272   *      Handle the `kern' as either classic Apple or Microsoft kern table.
       
   273   */
       
   274 #define FT_VALIDATE_MS     ( FT_VALIDATE_GX_START << 0 )
       
   275 #define FT_VALIDATE_APPLE  ( FT_VALIDATE_GX_START << 1 )
       
   276 
       
   277 #define FT_VALIDATE_CKERN  ( FT_VALIDATE_MS | FT_VALIDATE_APPLE )
       
   278 
       
   279 
       
   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 offsets
       
   289   *    and indices are valid.  The idea is that a higher-level library which
       
   290   *    actually does the text layout can access those tables without error
       
   291   *    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 which 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  /**********************************************************************
       
   326   *
       
   327   * @function:
       
   328   *    FT_ClassicKern_Free
       
   329   *
       
   330   * @description:
       
   331   *    Free the buffer allocated by classic Kern validator.
       
   332   *
       
   333   * @input:
       
   334   *    face ::
       
   335   *       A handle to the input face.
       
   336   *
       
   337   *    table ::
       
   338   *       The pointer to the buffer that is allocated by
       
   339   *       @FT_ClassicKern_Validate.
       
   340   *
       
   341   * @note:
       
   342   *   This function must be used to free the buffer allocated by
       
   343   *   @FT_ClassicKern_Validate only.
       
   344   */
       
   345   FT_EXPORT( void )
       
   346   FT_ClassicKern_Free( FT_Face   face,
       
   347                        FT_Bytes  table );
       
   348 
       
   349 
       
   350  /* */
       
   351 
       
   352 
       
   353 FT_END_HEADER
       
   354 
       
   355 #endif /* __FTGXVAL_H__ */
       
   356 
       
   357 
       
   358 /* END */