include/ftgxval.h

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