freetype1/lib/extend/ftxgsub.h

   1 /*******************************************************************
   2  *
   3  *  ftxgsub.h
   4  *
   5  *    TrueType Open GSUB table support
   6  *
   7  *  Copyright 1996-1999 by
   8  *  David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  *  This file is part of the FreeType project, and may only be used
  11  *  modified and distributed under the terms of the FreeType project
  12  *  license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  *  this file you indicate that you have read the license and
  14  *  understand and accept it fully.
  15  *
  16  ******************************************************************/
  17
  18 #ifndef FTXOPEN_H
  19 #error "Don't include this file! Use ftxopen.h instead."
  20 #endif
  21
  22 #ifndef FTXGSUB_H
  23 #define FTXGSUB_H
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 #define TTO_Err_Invalid_GSUB_SubTable_Format  0x1010
  30 #define TTO_Err_Invalid_GSUB_SubTable         0x1011
  31
  32
  33 /* Lookup types for glyph substitution */
  34
  35 #define GSUB_LOOKUP_SINGLE     1
  36 #define GSUB_LOOKUP_MULTIPLE   2
  37 #define GSUB_LOOKUP_ALTERNATE  3
  38 #define GSUB_LOOKUP_LIGATURE   4
  39 #define GSUB_LOOKUP_CONTEXT    5
  40 #define GSUB_LOOKUP_CHAIN      6
  41
  42
  43 /* Use this if a feature applies to all glyphs */
  44
  45 #define ALL_GLYPHS  0xFFFF
  46
  47
  48   /* A pointer to a function which selects the alternate glyph.  `pos' is
  49      the position of the glyph with index `glyphID', `num_alternates'
  50      gives the number of alternates in the `alternates' array.  `data'
  51      points to the user-defined structure specified during a call to
  52      TT_GSUB_Register_Alternate_Function().  The function must return an
  53      index into the `alternates' array.                                   */
  54
  55   typedef TT_UShort  (*TTO_AltFunction)(TT_ULong    pos,
  56                                         TT_UShort   glyphID,
  57                                         TT_UShort   num_alternates,
  58                                         TT_UShort*  alternates,
  59                                         void*       data );
  60
  61
  62   struct  TTO_GSUBHeader_
  63   {
  64     TT_Bool          loaded;
  65     TT_ULong         offset;
  66
  67     TT_Fixed         Version;
  68
  69     TTO_ScriptList   ScriptList;
  70     TTO_FeatureList  FeatureList;
  71     TTO_LookupList   LookupList;
  72
  73     TTO_GDEFHeader*  gdef;
  74
  75     /* the next two fields are used for an alternate substitution callback
  76        function to select the proper alternate glyph.                      */
  77
  78     TTO_AltFunction  alt;
  79     void*            data;
  80   };
  81
  82   typedef struct TTO_GSUBHeader_  TTO_GSUBHeader;
  83
  84
  85   /* LookupType 1 */
  86
  87   struct  TTO_SingleSubstFormat1_
  88   {
  89     TT_Short  DeltaGlyphID;             /* constant added to get
  90                                            substitution glyph index */
  91   };
  92
  93   typedef struct TTO_SingleSubstFormat1_  TTO_SingleSubstFormat1;
  94
  95
  96   struct  TTO_SingleSubstFormat2_
  97   {
  98     TT_UShort   GlyphCount;             /* number of glyph IDs in
  99                                            Substitute array              */
 100     TT_UShort*  Substitute;             /* array of substitute glyph IDs */
 101   };
 102
 103   typedef struct TTO_SingleSubstFormat2_  TTO_SingleSubstFormat2;
 104
 105
 106   struct  TTO_SingleSubst_
 107   {
 108     TT_UShort     SubstFormat;          /* 1 or 2         */
 109     TTO_Coverage  Coverage;             /* Coverage table */
 110
 111     union
 112     {
 113       TTO_SingleSubstFormat1  ssf1;
 114       TTO_SingleSubstFormat2  ssf2;
 115     } ssf;
 116   };
 117
 118   typedef struct TTO_SingleSubst_  TTO_SingleSubst;
 119
 120
 121   /* LookupType 2 */
 122
 123   struct  TTO_Sequence_
 124   {
 125     TT_UShort   GlyphCount;             /* number of glyph IDs in the
 126                                            Substitute array           */
 127     TT_UShort*  Substitute;             /* string of glyph IDs to
 128                                            substitute                 */
 129   };
 130
 131   typedef struct TTO_Sequence_  TTO_Sequence;
 132
 133
 134   struct  TTO_MultipleSubst_
 135   {
 136     TT_UShort      SubstFormat;         /* always 1                  */
 137     TTO_Coverage   Coverage;            /* Coverage table            */
 138     TT_UShort      SequenceCount;       /* number of Sequence tables */
 139     TTO_Sequence*  Sequence;            /* array of Sequence tables  */
 140   };
 141
 142   typedef struct TTO_MultipleSubst_  TTO_MultipleSubst;
 143
 144
 145   /* LookupType 3 */
 146
 147   struct  TTO_AlternateSet_
 148   {
 149     TT_UShort   GlyphCount;             /* number of glyph IDs in the
 150                                            Alternate array              */
 151     TT_UShort*  Alternate;              /* array of alternate glyph IDs */
 152   };
 153
 154   typedef struct TTO_AlternateSet_  TTO_AlternateSet;
 155
 156
 157   struct  TTO_AlternateSubst_
 158   {
 159     TT_UShort          SubstFormat;     /* always 1                      */
 160     TTO_Coverage       Coverage;        /* Coverage table                */
 161     TT_UShort          AlternateSetCount;
 162                                         /* number of AlternateSet tables */
 163     TTO_AlternateSet*  AlternateSet;    /* array of AlternateSet tables  */
 164   };
 165
 166   typedef struct TTO_AlternateSubst_  TTO_AlternateSubst;
 167
 168
 169   /* LookupType 4 */
 170
 171   struct  TTO_Ligature_
 172   {
 173     TT_UShort   LigGlyph;               /* glyphID of ligature
 174                                            to substitute                    */
 175     TT_UShort   ComponentCount;         /* number of components in ligature */
 176     TT_UShort*  Component;              /* array of component glyph IDs     */
 177   };
 178
 179   typedef struct TTO_Ligature_  TTO_Ligature;
 180
 181
 182   struct  TTO_LigatureSet_
 183   {
 184     TT_UShort      LigatureCount;       /* number of Ligature tables */
 185     TTO_Ligature*  Ligature;            /* array of Ligature tables  */
 186   };
 187
 188   typedef struct TTO_LigatureSet_  TTO_LigatureSet;
 189
 190
 191   struct  TTO_LigatureSubst_
 192   {
 193     TT_UShort         SubstFormat;      /* always 1                     */
 194     TTO_Coverage      Coverage;         /* Coverage table               */
 195     TT_UShort         LigatureSetCount; /* number of LigatureSet tables */
 196     TTO_LigatureSet*  LigatureSet;      /* array of LigatureSet tables  */
 197   };
 198
 199   typedef struct TTO_LigatureSubst_  TTO_LigatureSubst;
 200
 201
 202   /* needed by both lookup type 5 and 6 */
 203
 204   struct  TTO_SubstLookupRecord_
 205   {
 206     TT_UShort  SequenceIndex;           /* index into current
 207                                            glyph sequence               */
 208     TT_UShort  LookupListIndex;         /* Lookup to apply to that pos. */
 209   };
 210
 211   typedef struct TTO_SubstLookupRecord_  TTO_SubstLookupRecord;
 212
 213
 214   /* LookupType 5 */
 215
 216   struct  TTO_SubRule_
 217   {
 218     TT_UShort               GlyphCount; /* total number of input glyphs */
 219     TT_UShort               SubstCount; /* number of SubstLookupRecord
 220                                            tables                       */
 221     TT_UShort*              Input;      /* array of input glyph IDs     */
 222     TTO_SubstLookupRecord*  SubstLookupRecord;
 223                                         /* array of SubstLookupRecord
 224                                            tables                       */
 225   };
 226
 227   typedef struct TTO_SubRule_  TTO_SubRule;
 228
 229
 230   struct  TTO_SubRuleSet_
 231   {
 232     TT_UShort     SubRuleCount;         /* number of SubRule tables */
 233     TTO_SubRule*  SubRule;              /* array of SubRule tables  */
 234   };
 235
 236   typedef struct TTO_SubRuleSet_  TTO_SubRuleSet;
 237
 238
 239   struct  TTO_ContextSubstFormat1_
 240   {
 241     TTO_Coverage     Coverage;          /* Coverage table              */
 242     TT_UShort        SubRuleSetCount;   /* number of SubRuleSet tables */
 243     TTO_SubRuleSet*  SubRuleSet;        /* array of SubRuleSet tables  */
 244   };
 245
 246   typedef struct TTO_ContextSubstFormat1_  TTO_ContextSubstFormat1;
 247
 248
 249   struct  TTO_SubClassRule_
 250   {
 251     TT_UShort               GlyphCount; /* total number of context classes */
 252     TT_UShort               SubstCount; /* number of SubstLookupRecord
 253                                            tables                          */
 254     TT_UShort*              Class;      /* array of classes                */
 255     TTO_SubstLookupRecord*  SubstLookupRecord;
 256                                         /* array of SubstLookupRecord
 257                                            tables                          */
 258   };
 259
 260   typedef struct TTO_SubClassRule_  TTO_SubClassRule;
 261
 262
 263   struct  TTO_SubClassSet_
 264   {
 265     TT_UShort          SubClassRuleCount;
 266                                         /* number of SubClassRule tables */
 267     TTO_SubClassRule*  SubClassRule;    /* array of SubClassRule tables  */
 268   };
 269
 270   typedef struct TTO_SubClassSet_  TTO_SubClassSet;
 271
 272
 273   /* The `MaxContextLength' field is not defined in the TTO specification
 274      but simplifies the implementation of this format.  It holds the
 275      maximal context length used in the context rules.                    */
 276
 277   struct  TTO_ContextSubstFormat2_
 278   {
 279     TT_UShort            MaxContextLength;
 280                                         /* maximal context length       */
 281     TTO_Coverage         Coverage;      /* Coverage table               */
 282     TTO_ClassDefinition  ClassDef;      /* ClassDef table               */
 283     TT_UShort            SubClassSetCount;
 284                                         /* number of SubClassSet tables */
 285     TTO_SubClassSet*     SubClassSet;   /* array of SubClassSet tables  */
 286   };
 287
 288   typedef struct TTO_ContextSubstFormat2_  TTO_ContextSubstFormat2;
 289
 290
 291   struct  TTO_ContextSubstFormat3_
 292   {
 293     TT_UShort               GlyphCount; /* number of input glyphs        */
 294     TT_UShort               SubstCount; /* number of SubstLookupRecords  */
 295     TTO_Coverage*           Coverage;   /* array of Coverage tables      */
 296     TTO_SubstLookupRecord*  SubstLookupRecord;
 297                                         /* array of substitution lookups */
 298   };
 299
 300   typedef struct TTO_ContextSubstFormat3_  TTO_ContextSubstFormat3;
 301
 302
 303   struct  TTO_ContextSubst_
 304   {
 305     TT_UShort  SubstFormat;             /* 1, 2, or 3 */
 306
 307     union
 308     {
 309       TTO_ContextSubstFormat1  csf1;
 310       TTO_ContextSubstFormat2  csf2;
 311       TTO_ContextSubstFormat3  csf3;
 312     } csf;
 313   };
 314
 315   typedef struct TTO_ContextSubst_  TTO_ContextSubst;
 316
 317
 318   /* LookupType 6 */
 319
 320   struct  TTO_ChainSubRule_
 321   {
 322     TT_UShort               BacktrackGlyphCount;
 323                                         /* total number of backtrack glyphs */
 324     TT_UShort*              Backtrack;  /* array of backtrack glyph IDs     */
 325     TT_UShort               InputGlyphCount;
 326                                         /* total number of input glyphs     */
 327     TT_UShort*              Input;      /* array of input glyph IDs         */
 328     TT_UShort               LookaheadGlyphCount;
 329                                         /* total number of lookahead glyphs */
 330     TT_UShort*              Lookahead;  /* array of lookahead glyph IDs     */
 331     TT_UShort               SubstCount; /* number of SubstLookupRecords     */
 332     TTO_SubstLookupRecord*  SubstLookupRecord;
 333                                         /* array of SubstLookupRecords      */
 334   };
 335
 336   typedef struct TTO_ChainSubRule_  TTO_ChainSubRule;
 337
 338
 339   struct  TTO_ChainSubRuleSet_
 340   {
 341     TT_UShort          ChainSubRuleCount;
 342                                         /* number of ChainSubRule tables */
 343     TTO_ChainSubRule*  ChainSubRule;    /* array of ChainSubRule tables  */
 344   };
 345
 346   typedef struct TTO_ChainSubRuleSet_  TTO_ChainSubRuleSet;
 347
 348
 349   struct  TTO_ChainContextSubstFormat1_
 350   {
 351     TTO_Coverage          Coverage;     /* Coverage table                   */
 352     TT_UShort             ChainSubRuleSetCount;
 353                                         /* number of ChainSubRuleSet tables */
 354     TTO_ChainSubRuleSet*  ChainSubRuleSet;
 355                                         /* array of ChainSubRuleSet tables  */
 356   };
 357
 358   typedef struct TTO_ChainContextSubstFormat1_  TTO_ChainContextSubstFormat1;
 359
 360
 361   struct  TTO_ChainSubClassRule_
 362   {
 363     TT_UShort               BacktrackGlyphCount;
 364                                         /* total number of backtrack
 365                                            classes                         */
 366     TT_UShort*              Backtrack;  /* array of backtrack classes      */
 367     TT_UShort               InputGlyphCount;
 368                                         /* total number of context classes */
 369     TT_UShort*              Input;      /* array of context classes        */
 370     TT_UShort               LookaheadGlyphCount;
 371                                         /* total number of lookahead
 372                                            classes                         */
 373     TT_UShort*              Lookahead;  /* array of lookahead classes      */
 374     TT_UShort               SubstCount; /* number of SubstLookupRecords    */
 375     TTO_SubstLookupRecord*  SubstLookupRecord;
 376                                         /* array of substitution lookups   */
 377   };
 378
 379   typedef struct TTO_ChainSubClassRule_  TTO_ChainSubClassRule;
 380
 381
 382   struct  TTO_ChainSubClassSet_
 383   {
 384     TT_UShort               ChainSubClassRuleCount;
 385                                         /* number of ChainSubClassRule
 386                                            tables                      */
 387     TTO_ChainSubClassRule*  ChainSubClassRule;
 388                                         /* array of ChainSubClassRule
 389                                            tables                      */
 390   };
 391
 392   typedef struct TTO_ChainSubClassSet_  TTO_ChainSubClassSet;
 393
 394
 395   /* The `MaxXXXLength' fields are not defined in the TTO specification
 396      but simplifies the implementation of this format.  It holds the
 397      maximal context length used in the specific context rules.         */
 398
 399   struct  TTO_ChainContextSubstFormat2_
 400   {
 401     TTO_Coverage           Coverage;    /* Coverage table             */
 402
 403     TT_UShort              MaxBacktrackLength;
 404                                         /* maximal backtrack length   */
 405     TTO_ClassDefinition    BacktrackClassDef;
 406                                         /* BacktrackClassDef table    */
 407     TT_UShort              MaxInputLength;
 408                                         /* maximal input length       */
 409     TTO_ClassDefinition    InputClassDef;
 410                                         /* InputClassDef table        */
 411     TT_UShort              MaxLookaheadLength;
 412                                         /* maximal lookahead length   */
 413     TTO_ClassDefinition    LookaheadClassDef;
 414                                         /* LookaheadClassDef table    */
 415
 416     TT_UShort              ChainSubClassSetCount;
 417                                         /* number of ChainSubClassSet
 418                                            tables                     */
 419     TTO_ChainSubClassSet*  ChainSubClassSet;
 420                                         /* array of ChainSubClassSet
 421                                            tables                     */
 422   };
 423
 424   typedef struct TTO_ChainContextSubstFormat2_  TTO_ChainContextSubstFormat2;
 425
 426
 427   struct  TTO_ChainContextSubstFormat3_
 428   {
 429     TT_UShort               BacktrackGlyphCount;
 430                                         /* number of backtrack glyphs    */
 431     TTO_Coverage*           BacktrackCoverage;
 432                                         /* array of backtrack Coverage
 433                                            tables                        */
 434     TT_UShort               InputGlyphCount;
 435                                         /* number of input glyphs        */
 436     TTO_Coverage*           InputCoverage;
 437                                         /* array of input coverage
 438                                            tables                        */
 439     TT_UShort               LookaheadGlyphCount;
 440                                         /* number of lookahead glyphs    */
 441     TTO_Coverage*           LookaheadCoverage;
 442                                         /* array of lookahead coverage
 443                                            tables                        */
 444     TT_UShort               SubstCount; /* number of SubstLookupRecords  */
 445     TTO_SubstLookupRecord*  SubstLookupRecord;
 446                                         /* array of substitution lookups */
 447   };
 448
 449   typedef struct TTO_ChainContextSubstFormat3_  TTO_ChainContextSubstFormat3;
 450
 451
 452   struct  TTO_ChainContextSubst_
 453   {
 454     TT_UShort  SubstFormat;             /* 1, 2, or 3 */
 455
 456     union
 457     {
 458       TTO_ChainContextSubstFormat1  ccsf1;
 459       TTO_ChainContextSubstFormat2  ccsf2;
 460       TTO_ChainContextSubstFormat3  ccsf3;
 461     } ccsf;
 462   };
 463
 464   typedef struct TTO_ChainContextSubst_  TTO_ChainContextSubst;
 465
 466
 467   union  TTO_GSUB_SubTable_
 468   {
 469     TTO_SingleSubst        single;
 470     TTO_MultipleSubst      multiple;
 471     TTO_AlternateSubst     alternate;
 472     TTO_LigatureSubst      ligature;
 473     TTO_ContextSubst       context;
 474     TTO_ChainContextSubst  chain;
 475   };
 476
 477   typedef union TTO_GSUB_SubTable_  TTO_GSUB_SubTable;
 478
 479
 480   /* A simple string object.  It can both `send' and `receive' data.
 481      In case of sending, `length' and `pos' will be used.  In case of
 482      receiving, `pos' points to the first free slot, and `allocated'
 483      specifies the amount of allocated memory (and the `length' field
 484      will be ignored).  The routine TT_Add_String() will increase the
 485      amount of memory if necessary.  After end of receive, `length'
 486      should be set to the value of `pos', and `pos' will be set to zero.
 487
 488      `properties' (which is treated as a bit field) gives the glyph's
 489      properties: If a certain bit is set for a glyph, the feature which
 490      has the same bit set in its property value is applied.
 491
 492      NEVER modify any elements of the structure!  You should rather copy
 493      its contents if necessary.
 494
 495      TT_Add_String() will also handle allocation; you should use
 496      free() in case you want to destroy the arrays in the object. */
 497
 498   struct  TTO_GSUB_String_
 499   {
 500     TT_ULong    length;
 501     TT_ULong    pos;
 502     TT_ULong    allocated;
 503     TT_UShort*  string;
 504     TT_UShort*  properties;
 505   };
 506
 507   typedef struct TTO_GSUB_String_  TTO_GSUB_String;
 508
 509
 510   /* finally, the GSUB API */
 511
 512   EXPORT_DEF
 513   TT_Error  TT_Init_GSUB_Extension( TT_Engine  engine );
 514
 515   EXPORT_DEF
 516   TT_Error  TT_Load_GSUB_Table( TT_Face          face,
 517                                 TTO_GSUBHeader*  gsub,
 518                                 TTO_GDEFHeader*  gdef );
 519
 520   EXPORT_DEF
 521   TT_Error  TT_GSUB_Select_Script( TTO_GSUBHeader*  gsub,
 522                                    TT_ULong         script_tag,
 523                                    TT_UShort*       script_index );
 524   EXPORT_DEF
 525   TT_Error  TT_GSUB_Select_Language( TTO_GSUBHeader*  gsub,
 526                                      TT_ULong         language_tag,
 527                                      TT_UShort        script_index,
 528                                      TT_UShort*       language_index,
 529                                      TT_UShort*       req_feature_index );
 530   EXPORT_DEF
 531   TT_Error  TT_GSUB_Select_Feature( TTO_GSUBHeader*  gsub,
 532                                     TT_ULong         feature_tag,
 533                                     TT_UShort        script_index,
 534                                     TT_UShort        language_index,
 535                                     TT_UShort*       feature_index );
 536
 537   EXPORT_DEF
 538   TT_Error  TT_GSUB_Query_Scripts( TTO_GSUBHeader*  gsub,
 539                                    TT_ULong**       script_tag_list );
 540   EXPORT_DEF
 541   TT_Error  TT_GSUB_Query_Languages( TTO_GSUBHeader*  gsub,
 542                                      TT_UShort        script_index,
 543                                      TT_ULong**       language_tag_list );
 544   EXPORT_DEF
 545   TT_Error  TT_GSUB_Query_Features( TTO_GSUBHeader*  gsub,
 546                                     TT_UShort        script_index,
 547                                     TT_UShort        language_index,
 548                                     TT_ULong**       feature_tag_list );
 549
 550   EXPORT_DEF
 551   TT_Error  TT_GSUB_Add_Feature( TTO_GSUBHeader*  gsub,
 552                                  TT_UShort        feature_index,
 553                                  TT_UShort        property );
 554   EXPORT_DEF
 555   TT_Error  TT_GSUB_Clear_Features( TTO_GSUBHeader*  gsub );
 556
 557   EXPORT_DEF
 558   TT_Error  TT_GSUB_Register_Alternate_Function( TTO_GSUBHeader*  gsub,
 559                                                  TTO_AltFunction  alt,
 560                                                  void*            data );
 561
 562   EXPORT_DEF
 563   TT_Error  TT_GSUB_Apply_String( TTO_GSUBHeader*   gsub,
 564                                   TTO_GSUB_String*  in,
 565                                   TTO_GSUB_String*  out );
 566
 567   EXPORT_DEF
 568   TT_Error  TT_GSUB_Add_String( TTO_GSUB_String*  in,
 569                                 TT_UShort         num_in,
 570                                 TTO_GSUB_String*  out,
 571                                 TT_UShort         num_out,
 572                                 TT_UShort*        data );
 573
 574 #ifdef __cplusplus
 575 }
 576 #endif
 577
 578 #endif /* FTXGSUB_H */
 579
 580
 581 /* END */