include/freetype/ftgxval.h

   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 */