include/freetype/tttables.h

   1 /****************************************************************************
   2  *
   3  * tttables.h
   4  *
   5  *   Basic SFNT/TrueType tables definitions and interface
   6  *   (specification only).
   7  *
   8  * Copyright (C) 1996-2020 by
   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 #ifndef TTTABLES_H_
  21 #define TTTABLES_H_
  22
  23
  24 #include <freetype/freetype.h>
  25
  26 #ifdef FREETYPE_H
  27 #error "freetype.h of FreeType 1 has been loaded!"
  28 #error "Please fix the directory search order for header files"
  29 #error "so that freetype.h of FreeType 2 is found first."
  30 #endif
  31
  32
  33 FT_BEGIN_HEADER
  34
  35   /**************************************************************************
  36    *
  37    * @section:
  38    *   truetype_tables
  39    *
  40    * @title:
  41    *   TrueType Tables
  42    *
  43    * @abstract:
  44    *   TrueType-specific table types and functions.
  45    *
  46    * @description:
  47    *   This section contains definitions of some basic tables specific to
  48    *   TrueType and OpenType as well as some routines used to access and
  49    *   process them.
  50    *
  51    * @order:
  52    *   TT_Header
  53    *   TT_HoriHeader
  54    *   TT_VertHeader
  55    *   TT_OS2
  56    *   TT_Postscript
  57    *   TT_PCLT
  58    *   TT_MaxProfile
  59    *
  60    *   FT_Sfnt_Tag
  61    *   FT_Get_Sfnt_Table
  62    *   FT_Load_Sfnt_Table
  63    *   FT_Sfnt_Table_Info
  64    *
  65    *   FT_Get_CMap_Language_ID
  66    *   FT_Get_CMap_Format
  67    *
  68    *   FT_PARAM_TAG_UNPATENTED_HINTING
  69    *
  70    */
  71
  72
  73   /**************************************************************************
  74    *
  75    * @struct:
  76    *   TT_Header
  77    *
  78    * @description:
  79    *   A structure to model a TrueType font header table.  All fields follow
  80    *   the OpenType specification.  The 64-bit timestamps are stored in
  81    *   two-element arrays `Created` and `Modified`, first the upper then
  82    *   the lower 32~bits.
  83    */
  84   typedef struct  TT_Header_
  85   {
  86     FT_Fixed   Table_Version;
  87     FT_Fixed   Font_Revision;
  88
  89     FT_Long    CheckSum_Adjust;
  90     FT_Long    Magic_Number;
  91
  92     FT_UShort  Flags;
  93     FT_UShort  Units_Per_EM;
  94
  95     FT_ULong   Created [2];
  96     FT_ULong   Modified[2];
  97
  98     FT_Short   xMin;
  99     FT_Short   yMin;
 100     FT_Short   xMax;
 101     FT_Short   yMax;
 102
 103     FT_UShort  Mac_Style;
 104     FT_UShort  Lowest_Rec_PPEM;
 105
 106     FT_Short   Font_Direction;
 107     FT_Short   Index_To_Loc_Format;
 108     FT_Short   Glyph_Data_Format;
 109
 110   } TT_Header;
 111
 112
 113   /**************************************************************************
 114    *
 115    * @struct:
 116    *   TT_HoriHeader
 117    *
 118    * @description:
 119    *   A structure to model a TrueType horizontal header, the 'hhea' table,
 120    *   as well as the corresponding horizontal metrics table, 'hmtx'.
 121    *
 122    * @fields:
 123    *   Version ::
 124    *     The table version.
 125    *
 126    *   Ascender ::
 127    *     The font's ascender, i.e., the distance from the baseline to the
 128    *     top-most of all glyph points found in the font.
 129    *
 130    *     This value is invalid in many fonts, as it is usually set by the
 131    *     font designer, and often reflects only a portion of the glyphs found
 132    *     in the font (maybe ASCII).
 133    *
 134    *     You should use the `sTypoAscender` field of the 'OS/2' table instead
 135    *     if you want the correct one.
 136    *
 137    *   Descender ::
 138    *     The font's descender, i.e., the distance from the baseline to the
 139    *     bottom-most of all glyph points found in the font.  It is negative.
 140    *
 141    *     This value is invalid in many fonts, as it is usually set by the
 142    *     font designer, and often reflects only a portion of the glyphs found
 143    *     in the font (maybe ASCII).
 144    *
 145    *     You should use the `sTypoDescender` field of the 'OS/2' table
 146    *     instead if you want the correct one.
 147    *
 148    *   Line_Gap ::
 149    *     The font's line gap, i.e., the distance to add to the ascender and
 150    *     descender to get the BTB, i.e., the baseline-to-baseline distance
 151    *     for the font.
 152    *
 153    *   advance_Width_Max ::
 154    *     This field is the maximum of all advance widths found in the font.
 155    *     It can be used to compute the maximum width of an arbitrary string
 156    *     of text.
 157    *
 158    *   min_Left_Side_Bearing ::
 159    *     The minimum left side bearing of all glyphs within the font.
 160    *
 161    *   min_Right_Side_Bearing ::
 162    *     The minimum right side bearing of all glyphs within the font.
 163    *
 164    *   xMax_Extent ::
 165    *     The maximum horizontal extent (i.e., the 'width' of a glyph's
 166    *     bounding box) for all glyphs in the font.
 167    *
 168    *   caret_Slope_Rise ::
 169    *     The rise coefficient of the cursor's slope of the cursor
 170    *     (slope=rise/run).
 171    *
 172    *   caret_Slope_Run ::
 173    *     The run coefficient of the cursor's slope.
 174    *
 175    *   caret_Offset ::
 176    *     The cursor's offset for slanted fonts.
 177    *
 178    *   Reserved ::
 179    *     8~reserved bytes.
 180    *
 181    *   metric_Data_Format ::
 182    *     Always~0.
 183    *
 184    *   number_Of_HMetrics ::
 185    *     Number of HMetrics entries in the 'hmtx' table -- this value can be
 186    *     smaller than the total number of glyphs in the font.
 187    *
 188    *   long_metrics ::
 189    *     A pointer into the 'hmtx' table.
 190    *
 191    *   short_metrics ::
 192    *     A pointer into the 'hmtx' table.
 193    *
 194    * @note:
 195    *   For an OpenType variation font, the values of the following fields can
 196    *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
 197    *   the font contains an 'MVAR' table: `caret_Slope_Rise`,
 198    *   `caret_Slope_Run`, and `caret_Offset`.
 199    */
 200   typedef struct  TT_HoriHeader_
 201   {
 202     FT_Fixed   Version;
 203     FT_Short   Ascender;
 204     FT_Short   Descender;
 205     FT_Short   Line_Gap;
 206
 207     FT_UShort  advance_Width_Max;      /* advance width maximum */
 208
 209     FT_Short   min_Left_Side_Bearing;  /* minimum left-sb       */
 210     FT_Short   min_Right_Side_Bearing; /* minimum right-sb      */
 211     FT_Short   xMax_Extent;            /* xmax extents          */
 212     FT_Short   caret_Slope_Rise;
 213     FT_Short   caret_Slope_Run;
 214     FT_Short   caret_Offset;
 215
 216     FT_Short   Reserved[4];
 217
 218     FT_Short   metric_Data_Format;
 219     FT_UShort  number_Of_HMetrics;
 220
 221     /* The following fields are not defined by the OpenType specification */
 222     /* but they are used to connect the metrics header to the relevant    */
 223     /* 'hmtx' table.                                                      */
 224
 225     void*      long_metrics;
 226     void*      short_metrics;
 227
 228   } TT_HoriHeader;
 229
 230
 231   /**************************************************************************
 232    *
 233    * @struct:
 234    *   TT_VertHeader
 235    *
 236    * @description:
 237    *   A structure used to model a TrueType vertical header, the 'vhea'
 238    *   table, as well as the corresponding vertical metrics table, 'vmtx'.
 239    *
 240    * @fields:
 241    *   Version ::
 242    *     The table version.
 243    *
 244    *   Ascender ::
 245    *     The font's ascender, i.e., the distance from the baseline to the
 246    *     top-most of all glyph points found in the font.
 247    *
 248    *     This value is invalid in many fonts, as it is usually set by the
 249    *     font designer, and often reflects only a portion of the glyphs found
 250    *     in the font (maybe ASCII).
 251    *
 252    *     You should use the `sTypoAscender` field of the 'OS/2' table instead
 253    *     if you want the correct one.
 254    *
 255    *   Descender ::
 256    *     The font's descender, i.e., the distance from the baseline to the
 257    *     bottom-most of all glyph points found in the font.  It is negative.
 258    *
 259    *     This value is invalid in many fonts, as it is usually set by the
 260    *     font designer, and often reflects only a portion of the glyphs found
 261    *     in the font (maybe ASCII).
 262    *
 263    *     You should use the `sTypoDescender` field of the 'OS/2' table
 264    *     instead if you want the correct one.
 265    *
 266    *   Line_Gap ::
 267    *     The font's line gap, i.e., the distance to add to the ascender and
 268    *     descender to get the BTB, i.e., the baseline-to-baseline distance
 269    *     for the font.
 270    *
 271    *   advance_Height_Max ::
 272    *     This field is the maximum of all advance heights found in the font.
 273    *     It can be used to compute the maximum height of an arbitrary string
 274    *     of text.
 275    *
 276    *   min_Top_Side_Bearing ::
 277    *     The minimum top side bearing of all glyphs within the font.
 278    *
 279    *   min_Bottom_Side_Bearing ::
 280    *     The minimum bottom side bearing of all glyphs within the font.
 281    *
 282    *   yMax_Extent ::
 283    *     The maximum vertical extent (i.e., the 'height' of a glyph's
 284    *     bounding box) for all glyphs in the font.
 285    *
 286    *   caret_Slope_Rise ::
 287    *     The rise coefficient of the cursor's slope of the cursor
 288    *     (slope=rise/run).
 289    *
 290    *   caret_Slope_Run ::
 291    *     The run coefficient of the cursor's slope.
 292    *
 293    *   caret_Offset ::
 294    *     The cursor's offset for slanted fonts.
 295    *
 296    *   Reserved ::
 297    *     8~reserved bytes.
 298    *
 299    *   metric_Data_Format ::
 300    *     Always~0.
 301    *
 302    *   number_Of_VMetrics ::
 303    *     Number of VMetrics entries in the 'vmtx' table -- this value can be
 304    *     smaller than the total number of glyphs in the font.
 305    *
 306    *   long_metrics ::
 307    *     A pointer into the 'vmtx' table.
 308    *
 309    *   short_metrics ::
 310    *     A pointer into the 'vmtx' table.
 311    *
 312    * @note:
 313    *   For an OpenType variation font, the values of the following fields can
 314    *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
 315    *   the font contains an 'MVAR' table: `Ascender`, `Descender`,
 316    *   `Line_Gap`, `caret_Slope_Rise`, `caret_Slope_Run`, and `caret_Offset`.
 317    */
 318   typedef struct  TT_VertHeader_
 319   {
 320     FT_Fixed   Version;
 321     FT_Short   Ascender;
 322     FT_Short   Descender;
 323     FT_Short   Line_Gap;
 324
 325     FT_UShort  advance_Height_Max;      /* advance height maximum */
 326
 327     FT_Short   min_Top_Side_Bearing;    /* minimum top-sb          */
 328     FT_Short   min_Bottom_Side_Bearing; /* minimum bottom-sb       */
 329     FT_Short   yMax_Extent;             /* ymax extents            */
 330     FT_Short   caret_Slope_Rise;
 331     FT_Short   caret_Slope_Run;
 332     FT_Short   caret_Offset;
 333
 334     FT_Short   Reserved[4];
 335
 336     FT_Short   metric_Data_Format;
 337     FT_UShort  number_Of_VMetrics;
 338
 339     /* The following fields are not defined by the OpenType specification */
 340     /* but they are used to connect the metrics header to the relevant    */
 341     /* 'vmtx' table.                                                      */
 342
 343     void*      long_metrics;
 344     void*      short_metrics;
 345
 346   } TT_VertHeader;
 347
 348
 349   /**************************************************************************
 350    *
 351    * @struct:
 352    *   TT_OS2
 353    *
 354    * @description:
 355    *   A structure to model a TrueType 'OS/2' table.  All fields comply to
 356    *   the OpenType specification.
 357    *
 358    *   Note that we now support old Mac fonts that do not include an 'OS/2'
 359    *   table.  In this case, the `version` field is always set to 0xFFFF.
 360    *
 361    * @note:
 362    *   For an OpenType variation font, the values of the following fields can
 363    *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
 364    *   the font contains an 'MVAR' table: `sCapHeight`, `sTypoAscender`,
 365    *   `sTypoDescender`, `sTypoLineGap`, `sxHeight`, `usWinAscent`,
 366    *   `usWinDescent`, `yStrikeoutPosition`, `yStrikeoutSize`,
 367    *   `ySubscriptXOffset`, `ySubScriptXSize`, `ySubscriptYOffset`,
 368    *   `ySubscriptYSize`, `ySuperscriptXOffset`, `ySuperscriptXSize`,
 369    *   `ySuperscriptYOffset`, and `ySuperscriptYSize`.
 370    *
 371    *   Possible values for bits in the `ulUnicodeRangeX` fields are given by
 372    *   the @TT_UCR_XXX macros.
 373    */
 374
 375   typedef struct  TT_OS2_
 376   {
 377     FT_UShort  version;                /* 0x0001 - more or 0xFFFF */
 378     FT_Short   xAvgCharWidth;
 379     FT_UShort  usWeightClass;
 380     FT_UShort  usWidthClass;
 381     FT_UShort  fsType;
 382     FT_Short   ySubscriptXSize;
 383     FT_Short   ySubscriptYSize;
 384     FT_Short   ySubscriptXOffset;
 385     FT_Short   ySubscriptYOffset;
 386     FT_Short   ySuperscriptXSize;
 387     FT_Short   ySuperscriptYSize;
 388     FT_Short   ySuperscriptXOffset;
 389     FT_Short   ySuperscriptYOffset;
 390     FT_Short   yStrikeoutSize;
 391     FT_Short   yStrikeoutPosition;
 392     FT_Short   sFamilyClass;
 393
 394     FT_Byte    panose[10];
 395
 396     FT_ULong   ulUnicodeRange1;        /* Bits 0-31   */
 397     FT_ULong   ulUnicodeRange2;        /* Bits 32-63  */
 398     FT_ULong   ulUnicodeRange3;        /* Bits 64-95  */
 399     FT_ULong   ulUnicodeRange4;        /* Bits 96-127 */
 400
 401     FT_Char    achVendID[4];
 402
 403     FT_UShort  fsSelection;
 404     FT_UShort  usFirstCharIndex;
 405     FT_UShort  usLastCharIndex;
 406     FT_Short   sTypoAscender;
 407     FT_Short   sTypoDescender;
 408     FT_Short   sTypoLineGap;
 409     FT_UShort  usWinAscent;
 410     FT_UShort  usWinDescent;
 411
 412     /* only version 1 and higher: */
 413
 414     FT_ULong   ulCodePageRange1;       /* Bits 0-31   */
 415     FT_ULong   ulCodePageRange2;       /* Bits 32-63  */
 416
 417     /* only version 2 and higher: */
 418
 419     FT_Short   sxHeight;
 420     FT_Short   sCapHeight;
 421     FT_UShort  usDefaultChar;
 422     FT_UShort  usBreakChar;
 423     FT_UShort  usMaxContext;
 424
 425     /* only version 5 and higher: */
 426
 427     FT_UShort  usLowerOpticalPointSize;       /* in twips (1/20th points) */
 428     FT_UShort  usUpperOpticalPointSize;       /* in twips (1/20th points) */
 429
 430   } TT_OS2;
 431
 432
 433   /**************************************************************************
 434    *
 435    * @struct:
 436    *   TT_Postscript
 437    *
 438    * @description:
 439    *   A structure to model a TrueType 'post' table.  All fields comply to
 440    *   the OpenType specification.  This structure does not reference a
 441    *   font's PostScript glyph names; use @FT_Get_Glyph_Name to retrieve
 442    *   them.
 443    *
 444    * @note:
 445    *   For an OpenType variation font, the values of the following fields can
 446    *   change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
 447    *   the font contains an 'MVAR' table: `underlinePosition` and
 448    *   `underlineThickness`.
 449    */
 450   typedef struct  TT_Postscript_
 451   {
 452     FT_Fixed  FormatType;
 453     FT_Fixed  italicAngle;
 454     FT_Short  underlinePosition;
 455     FT_Short  underlineThickness;
 456     FT_ULong  isFixedPitch;
 457     FT_ULong  minMemType42;
 458     FT_ULong  maxMemType42;
 459     FT_ULong  minMemType1;
 460     FT_ULong  maxMemType1;
 461
 462     /* Glyph names follow in the 'post' table, but we don't */
 463     /* load them by default.                                */
 464
 465   } TT_Postscript;
 466
 467
 468   /**************************************************************************
 469    *
 470    * @struct:
 471    *   TT_PCLT
 472    *
 473    * @description:
 474    *   A structure to model a TrueType 'PCLT' table.  All fields comply to
 475    *   the OpenType specification.
 476    */
 477   typedef struct  TT_PCLT_
 478   {
 479     FT_Fixed   Version;
 480     FT_ULong   FontNumber;
 481     FT_UShort  Pitch;
 482     FT_UShort  xHeight;
 483     FT_UShort  Style;
 484     FT_UShort  TypeFamily;
 485     FT_UShort  CapHeight;
 486     FT_UShort  SymbolSet;
 487     FT_Char    TypeFace[16];
 488     FT_Char    CharacterComplement[8];
 489     FT_Char    FileName[6];
 490     FT_Char    StrokeWeight;
 491     FT_Char    WidthType;
 492     FT_Byte    SerifStyle;
 493     FT_Byte    Reserved;
 494
 495   } TT_PCLT;
 496
 497
 498   /**************************************************************************
 499    *
 500    * @struct:
 501    *   TT_MaxProfile
 502    *
 503    * @description:
 504    *   The maximum profile ('maxp') table contains many max values, which can
 505    *   be used to pre-allocate arrays for speeding up glyph loading and
 506    *   hinting.
 507    *
 508    * @fields:
 509    *   version ::
 510    *     The version number.
 511    *
 512    *   numGlyphs ::
 513    *     The number of glyphs in this TrueType font.
 514    *
 515    *   maxPoints ::
 516    *     The maximum number of points in a non-composite TrueType glyph.  See
 517    *     also `maxCompositePoints`.
 518    *
 519    *   maxContours ::
 520    *     The maximum number of contours in a non-composite TrueType glyph.
 521    *     See also `maxCompositeContours`.
 522    *
 523    *   maxCompositePoints ::
 524    *     The maximum number of points in a composite TrueType glyph.  See
 525    *     also `maxPoints`.
 526    *
 527    *   maxCompositeContours ::
 528    *     The maximum number of contours in a composite TrueType glyph.  See
 529    *     also `maxContours`.
 530    *
 531    *   maxZones ::
 532    *     The maximum number of zones used for glyph hinting.
 533    *
 534    *   maxTwilightPoints ::
 535    *     The maximum number of points in the twilight zone used for glyph
 536    *     hinting.
 537    *
 538    *   maxStorage ::
 539    *     The maximum number of elements in the storage area used for glyph
 540    *     hinting.
 541    *
 542    *   maxFunctionDefs ::
 543    *     The maximum number of function definitions in the TrueType bytecode
 544    *     for this font.
 545    *
 546    *   maxInstructionDefs ::
 547    *     The maximum number of instruction definitions in the TrueType
 548    *     bytecode for this font.
 549    *
 550    *   maxStackElements ::
 551    *     The maximum number of stack elements used during bytecode
 552    *     interpretation.
 553    *
 554    *   maxSizeOfInstructions ::
 555    *     The maximum number of TrueType opcodes used for glyph hinting.
 556    *
 557    *   maxComponentElements ::
 558    *     The maximum number of simple (i.e., non-composite) glyphs in a
 559    *     composite glyph.
 560    *
 561    *   maxComponentDepth ::
 562    *     The maximum nesting depth of composite glyphs.
 563    *
 564    * @note:
 565    *   This structure is only used during font loading.
 566    */
 567   typedef struct  TT_MaxProfile_
 568   {
 569     FT_Fixed   version;
 570     FT_UShort  numGlyphs;
 571     FT_UShort  maxPoints;
 572     FT_UShort  maxContours;
 573     FT_UShort  maxCompositePoints;
 574     FT_UShort  maxCompositeContours;
 575     FT_UShort  maxZones;
 576     FT_UShort  maxTwilightPoints;
 577     FT_UShort  maxStorage;
 578     FT_UShort  maxFunctionDefs;
 579     FT_UShort  maxInstructionDefs;
 580     FT_UShort  maxStackElements;
 581     FT_UShort  maxSizeOfInstructions;
 582     FT_UShort  maxComponentElements;
 583     FT_UShort  maxComponentDepth;
 584
 585   } TT_MaxProfile;
 586
 587
 588   /**************************************************************************
 589    *
 590    * @enum:
 591    *   FT_Sfnt_Tag
 592    *
 593    * @description:
 594    *   An enumeration to specify indices of SFNT tables loaded and parsed by
 595    *   FreeType during initialization of an SFNT font.  Used in the
 596    *   @FT_Get_Sfnt_Table API function.
 597    *
 598    * @values:
 599    *   FT_SFNT_HEAD ::
 600    *     To access the font's @TT_Header structure.
 601    *
 602    *   FT_SFNT_MAXP ::
 603    *     To access the font's @TT_MaxProfile structure.
 604    *
 605    *   FT_SFNT_OS2 ::
 606    *     To access the font's @TT_OS2 structure.
 607    *
 608    *   FT_SFNT_HHEA ::
 609    *     To access the font's @TT_HoriHeader structure.
 610    *
 611    *   FT_SFNT_VHEA ::
 612    *     To access the font's @TT_VertHeader structure.
 613    *
 614    *   FT_SFNT_POST ::
 615    *     To access the font's @TT_Postscript structure.
 616    *
 617    *   FT_SFNT_PCLT ::
 618    *     To access the font's @TT_PCLT structure.
 619    */
 620   typedef enum  FT_Sfnt_Tag_
 621   {
 622     FT_SFNT_HEAD,
 623     FT_SFNT_MAXP,
 624     FT_SFNT_OS2,
 625     FT_SFNT_HHEA,
 626     FT_SFNT_VHEA,
 627     FT_SFNT_POST,
 628     FT_SFNT_PCLT,
 629
 630     FT_SFNT_MAX
 631
 632   } FT_Sfnt_Tag;
 633
 634   /* these constants are deprecated; use the corresponding `FT_Sfnt_Tag` */
 635   /* values instead                                                      */
 636 #define ft_sfnt_head  FT_SFNT_HEAD
 637 #define ft_sfnt_maxp  FT_SFNT_MAXP
 638 #define ft_sfnt_os2   FT_SFNT_OS2
 639 #define ft_sfnt_hhea  FT_SFNT_HHEA
 640 #define ft_sfnt_vhea  FT_SFNT_VHEA
 641 #define ft_sfnt_post  FT_SFNT_POST
 642 #define ft_sfnt_pclt  FT_SFNT_PCLT
 643
 644
 645   /**************************************************************************
 646    *
 647    * @function:
 648    *   FT_Get_Sfnt_Table
 649    *
 650    * @description:
 651    *   Return a pointer to a given SFNT table stored within a face.
 652    *
 653    * @input:
 654    *   face ::
 655    *     A handle to the source.
 656    *
 657    *   tag ::
 658    *     The index of the SFNT table.
 659    *
 660    * @return:
 661    *   A type-less pointer to the table.  This will be `NULL` in case of
 662    *   error, or if the corresponding table was not found **OR** loaded from
 663    *   the file.
 664    *
 665    *   Use a typecast according to `tag` to access the structure elements.
 666    *
 667    * @note:
 668    *   The table is owned by the face object and disappears with it.
 669    *
 670    *   This function is only useful to access SFNT tables that are loaded by
 671    *   the sfnt, truetype, and opentype drivers.  See @FT_Sfnt_Tag for a
 672    *   list.
 673    *
 674    * @example:
 675    *   Here is an example demonstrating access to the 'vhea' table.
 676    *
 677    *   ```
 678    *     TT_VertHeader*  vert_header;
 679    *
 680    *
 681    *     vert_header =
 682    *       (TT_VertHeader*)FT_Get_Sfnt_Table( face, FT_SFNT_VHEA );
 683    *   ```
 684    */
 685   FT_EXPORT( void* )
 686   FT_Get_Sfnt_Table( FT_Face      face,
 687                      FT_Sfnt_Tag  tag );
 688
 689
 690   /**************************************************************************
 691    *
 692    * @function:
 693    *   FT_Load_Sfnt_Table
 694    *
 695    * @description:
 696    *   Load any SFNT font table into client memory.
 697    *
 698    * @input:
 699    *   face ::
 700    *     A handle to the source face.
 701    *
 702    *   tag ::
 703    *     The four-byte tag of the table to load.  Use value~0 if you want to
 704    *     access the whole font file.  Otherwise, you can use one of the
 705    *     definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
 706    *     one with @FT_MAKE_TAG.
 707    *
 708    *   offset ::
 709    *     The starting offset in the table (or file if tag~==~0).
 710    *
 711    * @output:
 712    *   buffer ::
 713    *     The target buffer address.  The client must ensure that the memory
 714    *     array is big enough to hold the data.
 715    *
 716    * @inout:
 717    *   length ::
 718    *     If the `length` parameter is `NULL`, try to load the whole table.
 719    *     Return an error code if it fails.
 720    *
 721    *     Else, if `*length` is~0, exit immediately while returning the
 722    *     table's (or file) full size in it.
 723    *
 724    *     Else the number of bytes to read from the table or file, from the
 725    *     starting offset.
 726    *
 727    * @return:
 728    *   FreeType error code.  0~means success.
 729    *
 730    * @note:
 731    *   If you need to determine the table's length you should first call this
 732    *   function with `*length` set to~0, as in the following example:
 733    *
 734    *   ```
 735    *     FT_ULong  length = 0;
 736    *
 737    *
 738    *     error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
 739    *     if ( error ) { ... table does not exist ... }
 740    *
 741    *     buffer = malloc( length );
 742    *     if ( buffer == NULL ) { ... not enough memory ... }
 743    *
 744    *     error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
 745    *     if ( error ) { ... could not load table ... }
 746    *   ```
 747    *
 748    *   Note that structures like @TT_Header or @TT_OS2 can't be used with
 749    *   this function; they are limited to @FT_Get_Sfnt_Table.  Reason is that
 750    *   those structures depend on the processor architecture, with varying
 751    *   size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
 752    *
 753    */
 754   FT_EXPORT( FT_Error )
 755   FT_Load_Sfnt_Table( FT_Face    face,
 756                       FT_ULong   tag,
 757                       FT_Long    offset,
 758                       FT_Byte*   buffer,
 759                       FT_ULong*  length );
 760
 761
 762   /**************************************************************************
 763    *
 764    * @function:
 765    *   FT_Sfnt_Table_Info
 766    *
 767    * @description:
 768    *   Return information on an SFNT table.
 769    *
 770    * @input:
 771    *   face ::
 772    *     A handle to the source face.
 773    *
 774    *   table_index ::
 775    *     The index of an SFNT table.  The function returns
 776    *     FT_Err_Table_Missing for an invalid value.
 777    *
 778    * @inout:
 779    *   tag ::
 780    *     The name tag of the SFNT table.  If the value is `NULL`,
 781    *     `table_index` is ignored, and `length` returns the number of SFNT
 782    *     tables in the font.
 783    *
 784    * @output:
 785    *   length ::
 786    *     The length of the SFNT table (or the number of SFNT tables,
 787    *     depending on `tag`).
 788    *
 789    * @return:
 790    *   FreeType error code.  0~means success.
 791    *
 792    * @note:
 793    *   While parsing fonts, FreeType handles SFNT tables with length zero as
 794    *   missing.
 795    *
 796    */
 797   FT_EXPORT( FT_Error )
 798   FT_Sfnt_Table_Info( FT_Face    face,
 799                       FT_UInt    table_index,
 800                       FT_ULong  *tag,
 801                       FT_ULong  *length );
 802
 803
 804   /**************************************************************************
 805    *
 806    * @function:
 807    *   FT_Get_CMap_Language_ID
 808    *
 809    * @description:
 810    *   Return cmap language ID as specified in the OpenType standard.
 811    *   Definitions of language ID values are in file @FT_TRUETYPE_IDS_H.
 812    *
 813    * @input:
 814    *   charmap ::
 815    *     The target charmap.
 816    *
 817    * @return:
 818    *   The language ID of `charmap`.  If `charmap` doesn't belong to an SFNT
 819    *   face, just return~0 as the default value.
 820    *
 821    *   For a format~14 cmap (to access Unicode IVS), the return value is
 822    *   0xFFFFFFFF.
 823    */
 824   FT_EXPORT( FT_ULong )
 825   FT_Get_CMap_Language_ID( FT_CharMap  charmap );
 826
 827
 828   /**************************************************************************
 829    *
 830    * @function:
 831    *   FT_Get_CMap_Format
 832    *
 833    * @description:
 834    *   Return the format of an SFNT 'cmap' table.
 835    *
 836    * @input:
 837    *   charmap ::
 838    *     The target charmap.
 839    *
 840    * @return:
 841    *   The format of `charmap`.  If `charmap` doesn't belong to an SFNT face,
 842    *   return -1.
 843    */
 844   FT_EXPORT( FT_Long )
 845   FT_Get_CMap_Format( FT_CharMap  charmap );
 846
 847   /* */
 848
 849
 850 FT_END_HEADER
 851
 852 #endif /* TTTABLES_H_ */
 853
 854
 855 /* END */