Commit 8013d89f7fe7da123e3cd5708e501caf88405226
2017-01-17T12:39:53
ftsnames.h, ttnameid.h, tttables.h: Revise documentation. Show more macros in the reference: TT_MAC_LANGID_XXX, TT_MS_LANGID_XXX, TT_NAME_ID_XXX, TT_UCR_XXX. This commit is viewed best with git diff --color-words='[^*/ ]+'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index b6c6032..0084262 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -734,7 +734,7 @@ FT_BEGIN_HEADER
/* Russian). */
/* */
/* FT_ENCODING_NONE is set if `platform_id' is @TT_PLATFORM_MACINTOSH */
- /* and `encoding_id' is not @TT_MAC_ID_ROMAN (otherwise it is set to */
+ /* and `encoding_id' is not `TT_MAC_ID_ROMAN' (otherwise it is set to */
/* FT_ENCODING_APPLE_ROMAN). */
/* */
/* If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function */
@@ -746,9 +746,9 @@ FT_BEGIN_HEADER
/* to get an idea how to do that. Basically, if the language ID */
/* is~0, don't use it, otherwise subtract 1 from the language ID. */
/* Then examine `encoding_id'. If, for example, `encoding_id' is */
- /* @TT_MAC_ID_ROMAN and the language ID (minus~1) is */
+ /* `TT_MAC_ID_ROMAN' and the language ID (minus~1) is */
/* `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman. */
- /* @TT_MAC_ID_ARABIC with `TT_MAC_LANGID_FARSI' means the Farsi */
+ /* `TT_MAC_ID_ARABIC' with `TT_MAC_LANGID_FARSI' means the Farsi */
/* variant the Arabic encoding. */
/* */
typedef enum FT_Encoding_
diff --git a/include/freetype/ftsnames.h b/include/freetype/ftsnames.h
index f6daf8c..6162ead 100644
--- a/include/freetype/ftsnames.h
+++ b/include/freetype/ftsnames.h
@@ -2,7 +2,7 @@
/* */
/* ftsnames.h */
/* */
-/* Simple interface to access SFNT name tables (which are used */
+/* Simple interface to access SFNT `name' tables (which are used */
/* to hold font names, copyright info, notices, etc.) (specification). */
/* */
/* This is _not_ used to retrieve glyph names! */
@@ -49,7 +49,7 @@ FT_BEGIN_HEADER
/* */
/* <Description> */
/* The TrueType and OpenType specifications allow the inclusion of */
- /* a special `names table' in font files. This table contains */
+ /* a special names table (`name') in font files. This table contains */
/* textual (and internationalized) information regarding the font, */
/* like family name, copyright, version, etc. */
/* */
@@ -70,30 +70,29 @@ FT_BEGIN_HEADER
/* */
/* <Fields> */
/* platform_id :: The platform ID for `string'. */
+ /* See @TT_PLATFORM_XXX for possible values. */
/* */
/* encoding_id :: The encoding ID for `string'. */
+ /* See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, */
+ /* @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX */
+ /* for possible values. */
/* */
/* language_id :: The language ID for `string'. */
+ /* See @TT_MAC_LANGID_XXX and @TT_MS_LANGID_XXX for */
+ /* possible values. */
/* */
/* name_id :: An identifier for `string'. */
+ /* See @TT_NAME_ID_XXX for possible values. */
/* */
/* string :: The `name' string. Note that its format differs */
/* depending on the (platform,encoding) pair. It can */
/* be a Pascal String, a UTF-16 one, etc. */
/* */
- /* Generally speaking, the string is not */
- /* zero-terminated. Please refer to the TrueType */
- /* specification for details. */
- /* */
/* string_len :: The length of `string' in bytes. */
/* */
/* <Note> */
- /* Possible values for `platform_id', `encoding_id', `language_id', */
- /* and `name_id' are given in the file `ttnameid.h'. For details */
- /* please refer to the TrueType or OpenType specification. */
- /* */
- /* See also @TT_PLATFORM_XXX, @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, */
- /* @TT_ISO_ID_XXX, and @TT_MS_ID_XXX. */
+ /* Please refer to the TrueType or OpenType specification for more */
+ /* details. */
/* */
typedef struct FT_SfntName_
{
@@ -103,7 +102,7 @@ FT_BEGIN_HEADER
FT_UShort name_id;
FT_Byte* string; /* this string is *not* null-terminated! */
- FT_UInt string_len; /* in bytes */
+ FT_UInt string_len; /* in bytes */
} FT_SfntName;
diff --git a/include/freetype/ttnameid.h b/include/freetype/ttnameid.h
index adddd94..f8b2a8d 100644
--- a/include/freetype/ttnameid.h
+++ b/include/freetype/ttnameid.h
@@ -36,7 +36,7 @@ FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* Possible values for the `platform' identifier code in the name */
- /* records of the TTF `name' table. */
+ /* records of an SFNT `name' table. */
/* */
/*************************************************************************/
@@ -142,42 +142,6 @@ FT_BEGIN_HEADER
* @description:
* A list of valid values for the `encoding_id' for
* @TT_PLATFORM_MACINTOSH charmaps and name entries.
- *
- * @values:
- * TT_MAC_ID_ROMAN ::
- * TT_MAC_ID_JAPANESE ::
- * TT_MAC_ID_TRADITIONAL_CHINESE ::
- * TT_MAC_ID_KOREAN ::
- * TT_MAC_ID_ARABIC ::
- * TT_MAC_ID_HEBREW ::
- * TT_MAC_ID_GREEK ::
- * TT_MAC_ID_RUSSIAN ::
- * TT_MAC_ID_RSYMBOL ::
- * TT_MAC_ID_DEVANAGARI ::
- * TT_MAC_ID_GURMUKHI ::
- * TT_MAC_ID_GUJARATI ::
- * TT_MAC_ID_ORIYA ::
- * TT_MAC_ID_BENGALI ::
- * TT_MAC_ID_TAMIL ::
- * TT_MAC_ID_TELUGU ::
- * TT_MAC_ID_KANNADA ::
- * TT_MAC_ID_MALAYALAM ::
- * TT_MAC_ID_SINHALESE ::
- * TT_MAC_ID_BURMESE ::
- * TT_MAC_ID_KHMER ::
- * TT_MAC_ID_THAI ::
- * TT_MAC_ID_LAOTIAN ::
- * TT_MAC_ID_GEORGIAN ::
- * TT_MAC_ID_ARMENIAN ::
- * TT_MAC_ID_MALDIVIAN ::
- * TT_MAC_ID_SIMPLIFIED_CHINESE ::
- * TT_MAC_ID_TIBETAN ::
- * TT_MAC_ID_MONGOLIAN ::
- * TT_MAC_ID_GEEZ ::
- * TT_MAC_ID_SLAVIC ::
- * TT_MAC_ID_VIETNAMESE ::
- * TT_MAC_ID_SINDHI ::
- * TT_MAC_ID_UNINTERP ::
*/
#define TT_MAC_ID_ROMAN 0
@@ -252,33 +216,32 @@ FT_BEGIN_HEADER
*
* @values:
* TT_MS_ID_SYMBOL_CS ::
- * Corresponds to Microsoft symbol encoding. See
- * @FT_ENCODING_MS_SYMBOL.
+ * Microsoft symbol encoding. See @FT_ENCODING_MS_SYMBOL.
*
* TT_MS_ID_UNICODE_CS ::
- * Corresponds to a Microsoft WGL4 charmap, matching Unicode. See
+ * Microsoft WGL4 charmap, matching Unicode. See
* @FT_ENCODING_UNICODE.
*
* TT_MS_ID_SJIS ::
- * Corresponds to SJIS Japanese encoding. See @FT_ENCODING_SJIS.
+ * Shift JIS Japanese encoding. See @FT_ENCODING_SJIS.
*
* TT_MS_ID_GB2312 ::
- * Corresponds to Simplified Chinese as used in Mainland China. See
+ * Simplified Chinese as used in Mainland China. See
* @FT_ENCODING_GB2312.
*
* TT_MS_ID_BIG_5 ::
- * Corresponds to Traditional Chinese as used in Taiwan and Hong Kong.
- * See @FT_ENCODING_BIG5.
+ * Traditional Chinese as used in Taiwan and Hong Kong. See
+ * @FT_ENCODING_BIG5.
*
* TT_MS_ID_WANSUNG ::
- * Corresponds to Korean Wansung encoding. See @FT_ENCODING_WANSUNG.
+ * Korean Extended Wansung encoding. See @FT_ENCODING_WANSUNG.
*
* TT_MS_ID_JOHAB ::
- * Corresponds to Johab encoding. See @FT_ENCODING_JOHAB.
+ * Korean Johab encoding. See @FT_ENCODING_JOHAB.
*
* TT_MS_ID_UCS_4 ::
- * Corresponds to UCS-4 or UTF-32 charmaps. This has been added to
- * the OpenType specification version 1.4 (mid-2001.)
+ * UCS-4 or UTF-32 charmaps. This has been added to the OpenType
+ * specification version 1.4 (mid-2001).
*/
#define TT_MS_ID_SYMBOL_CS 0
@@ -317,17 +280,22 @@ FT_BEGIN_HEADER
#define TT_ADOBE_ID_LATIN_1 3
- /*************************************************************************/
- /* */
- /* Possible values of the language identifier field in the name records */
- /* of the TTF `name' table if the `platform' identifier code is */
- /* TT_PLATFORM_MACINTOSH. These values are also used as return values */
- /* for function @FT_Get_CMap_Language_ID. */
- /* */
- /* The canonical source for the Apple assigned Language ID's is at */
- /* */
- /* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6name.html */
- /* */
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_MAC_LANGID_XXX
+ *
+ * @description:
+ * Possible values of the language identifier field in the name records
+ * of the SFNT `name' table if the `platform' identifier code is
+ * @TT_PLATFORM_MACINTOSH. These values are also used as return values
+ * for function @FT_Get_CMap_Language_ID.
+ *
+ * The canonical source for Apple's IDs is
+ *
+ * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6name.html
+ */
+
#define TT_MAC_LANGID_ENGLISH 0
#define TT_MAC_LANGID_FRENCH 1
#define TT_MAC_LANGID_GERMAN 2
@@ -438,15 +406,6 @@ FT_BEGIN_HEADER
#define TT_MAC_LANGID_JAVANESE 138
#define TT_MAC_LANGID_SUNDANESE 139
-
-#if 0 /* these seem to be errors that have been dropped */
-
-#define TT_MAC_LANGID_SCOTTISH_GAELIC 140
-#define TT_MAC_LANGID_IRISH_GAELIC 141
-
-#endif
-
-
/* The following codes are new as of 2000-03-10 */
#define TT_MAC_LANGID_GALICIAN 140
#define TT_MAC_LANGID_AFRIKAANS 141
@@ -461,16 +420,29 @@ FT_BEGIN_HEADER
#define TT_MAC_LANGID_AZERBAIJANI_ROMAN_SCRIPT 150
- /*************************************************************************/
- /* */
- /* Possible values of the language identifier field in the name records */
- /* of the TTF `name' table if the `platform' identifier code is */
- /* TT_PLATFORM_MICROSOFT. */
- /* */
- /* The canonical source for the MS assigned LCIDs is */
- /* */
- /* http://www.microsoft.com/globaldev/reference/lcid-all.mspx */
- /* */
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_MS_LANGID_XXX
+ *
+ * @description:
+ * Possible values of the language identifier field in the name records
+ * of the SFNT `name' table if the `platform' identifier code is
+ * @TT_PLATFORM_MICROSOFT. These values are also used as return values
+ * for function @FT_Get_CMap_Language_ID.
+ *
+ * The canonical source for Microsoft's IDs is
+ *
+ * http://www.microsoft.com/globaldev/reference/lcid-all.mspx ,
+ *
+ * however, we only provide macros for language identifiers present in
+ * the OpenType specification: Microsoft has abandoned the concept of
+ * LCIDs (language code identifiers), and format~1 of the `name' table
+ * provides a better mechanism for languages not covered here.
+ *
+ * More legacy values not listed in the reference can be found in the
+ * @FT_TRUETYPE_IDS_H header file.
+ */
#define TT_MS_LANGID_ARABIC_SAUDI_ARABIA 0x0401
#define TT_MS_LANGID_ARABIC_IRAQ 0x0801
@@ -804,11 +776,16 @@ FT_BEGIN_HEADER
TT_MS_LANGID_UIGHUR_PRC
- /*************************************************************************/
- /* */
- /* Possible values of the `name' identifier field in the name records of */
- /* the TTF `name' table. These values are platform independent. */
- /* */
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_NAME_ID_XXX
+ *
+ * @description:
+ * Possible values of the `name' identifier field in the name records of
+ * an SFNT `name' table. These values are platform independent.
+ */
+
#define TT_NAME_ID_COPYRIGHT 0
#define TT_NAME_ID_FONT_FAMILY 1
#define TT_NAME_ID_FONT_SUBFAMILY 2
@@ -848,13 +825,21 @@ FT_BEGIN_HEADER
/* This is new in OpenType 1.8 */
#define TT_NAME_ID_VARIATIONS_PREFIX 25
+ /* */
- /*************************************************************************/
- /* */
- /* Bit mask values for the Unicode Ranges from the TTF `OS2 ' table. */
- /* */
- /* Updated 08-Nov-2008. */
- /* */
+
+ /***********************************************************************
+ *
+ * @enum:
+ * TT_UCR_XXX
+ *
+ * @description:
+ * Possible bit mask values for the `ulUnicodeRangeX' fields in an SFNT
+ * `OS/2' table.
+ */
+
+ /* ulUnicodeRange1 */
+ /* --------------- */
/* Bit 0 Basic Latin */
#define TT_UCR_BASIC_LATIN (1L << 0) /* U+0020-U+007E */
@@ -944,6 +929,10 @@ FT_BEGIN_HEADER
/* Supplemental Punctuation */
#define TT_UCR_GENERAL_PUNCTUATION (1L << 31) /* U+2000-U+206F */
/* U+2E00-U+2E7F */
+
+ /* ulUnicodeRange2 */
+ /* --------------- */
+
/* Bit 32 Superscripts And Subscripts */
#define TT_UCR_SUPERSCRIPTS_SUBSCRIPTS (1L << 0) /* U+2070-U+209F */
/* Bit 33 Currency Symbols */
@@ -1016,13 +1005,13 @@ FT_BEGIN_HEADER
/* Bit 57 High Surrogates */
/* High Private Use Surrogates */
/* Low Surrogates */
- /* */
+
/* According to OpenType specs v.1.3+, */
/* setting bit 57 implies that there is */
/* at least one codepoint beyond the */
/* Basic Multilingual Plane that is */
/* supported by this font. So it really */
- /* means >= U+10000 */
+ /* means >= U+10000. */
#define TT_UCR_SURROGATES (1L << 25) /* U+D800-U+DB7F */
/* U+DB80-U+DBFF */
/* U+DC00-U+DFFF */
@@ -1055,6 +1044,10 @@ FT_BEGIN_HEADER
#define TT_UCR_ALPHABETIC_PRESENTATION_FORMS (1L << 30) /* U+FB00-U+FB4F */
/* Bit 63 Arabic Presentation Forms-A */
#define TT_UCR_ARABIC_PRESENTATION_FORMS_A (1L << 31) /* U+FB50-U+FDFF */
+
+ /* ulUnicodeRange3 */
+ /* --------------- */
+
/* Bit 64 Combining Half Marks */
#define TT_UCR_COMBINING_HALF_MARKS (1L << 0) /* U+FE20-U+FE2F */
/* Bit 65 Vertical forms */
@@ -1143,6 +1136,10 @@ FT_BEGIN_HEADER
#define TT_UCR_TAI_LE (1L << 30) /* U+1950-U+197F */
/* Bit 95 New Tai Lue */
#define TT_UCR_NEW_TAI_LUE (1L << 31) /* U+1980-U+19DF */
+
+ /* ulUnicodeRange4 */
+ /* --------------- */
+
/* Bit 96 Buginese */
#define TT_UCR_BUGINESE (1L << 0) /* U+1A00-U+1A1F */
/* Bit 97 Glagolitic */
@@ -1211,6 +1208,7 @@ FT_BEGIN_HEADER
/*U+1F000-U+1F02F*/
/* Bit 123-127 Reserved for process-internal usage */
+ /* */
/* for backwards compatibility with older FreeType versions */
#define TT_UCR_ARABIC_PRESENTATION_A \
diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h
index 7a278e2..5831204 100644
--- a/include/freetype/tttables.h
+++ b/include/freetype/tttables.h
@@ -45,8 +45,9 @@ FT_BEGIN_HEADER
/* TrueType specific table types and functions. */
/* */
/* <Description> */
- /* This section contains the definition of TrueType-specific tables */
- /* as well as some routines used to access and process them. */
+ /* This section contains definitions of some basic tables specific to */
+ /* TrueType and OpenType as well as some routines used to access and */
+ /* process them. */
/* */
/* <Order> */
/* TT_Header */
@@ -76,8 +77,8 @@ FT_BEGIN_HEADER
/* TT_Header */
/* */
/* <Description> */
- /* A structure used to model a TrueType font header table. All */
- /* fields follow the TrueType specification. */
+ /* A structure to model a TrueType font header table. All fields */
+ /* follow the OpenType specification. */
/* */
typedef struct TT_Header_
{
@@ -114,9 +115,9 @@ FT_BEGIN_HEADER
/* TT_HoriHeader */
/* */
/* <Description> */
- /* A structure used to model a TrueType horizontal header, the `hhea' */
+ /* A structure to model a TrueType horizontal header, the `hhea' */
/* table, as well as the corresponding horizontal metrics table, */
- /* i.e., the `hmtx' table. */
+ /* `hmtx'. */
/* */
/* <Fields> */
/* Version :: The table version. */
@@ -131,7 +132,7 @@ FT_BEGIN_HEADER
/* glyphs found in the font (maybe ASCII). */
/* */
/* You should use the `sTypoAscender' field */
- /* of the OS/2 table instead if you want */
+ /* of the `OS/2' table instead if you want */
/* the correct one. */
/* */
/* Descender :: The font's descender, i.e., the distance */
@@ -145,7 +146,7 @@ FT_BEGIN_HEADER
/* glyphs found in the font (maybe ASCII). */
/* */
/* You should use the `sTypoDescender' */
- /* field of the OS/2 table instead if you */
+ /* field of the `OS/2' table instead if you */
/* want the correct one. */
/* */
/* Line_Gap :: The font's line gap, i.e., the distance */
@@ -195,14 +196,6 @@ FT_BEGIN_HEADER
/* friends) if the font contains an `MVAR' table: `caret_Slope_Rise', */
/* `caret_Slope_Run', and `caret_Offset'. */
/* */
- /* IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should */
- /* be identical except for the names of their fields, */
- /* which are different. */
- /* */
- /* This ensures that a single function in the `ttload' */
- /* module is able to read both the horizontal and vertical */
- /* headers. */
- /* */
typedef struct TT_HoriHeader_
{
FT_Fixed Version;
@@ -224,7 +217,7 @@ FT_BEGIN_HEADER
FT_Short metric_Data_Format;
FT_UShort number_Of_HMetrics;
- /* The following fields are not defined by the TrueType specification */
+ /* The following fields are not defined by the OpenType specification */
/* but they are used to connect the metrics header to the relevant */
/* `hmtx' table. */
@@ -241,8 +234,8 @@ FT_BEGIN_HEADER
/* */
/* <Description> */
/* A structure used to model a TrueType vertical header, the `vhea' */
- /* table, as well as the corresponding vertical metrics table, i.e., */
- /* the `vmtx' table. */
+ /* table, as well as the corresponding vertical metrics table, */
+ /* `vmtx'. */
/* */
/* <Fields> */
/* Version :: The table version. */
@@ -258,8 +251,8 @@ FT_BEGIN_HEADER
/* ASCII). */
/* */
/* You should use the `sTypoAscender' */
- /* field of the OS/2 table instead if you */
- /* want the correct one. */
+ /* field of the `OS/2' table instead if */
+ /* you want the correct one. */
/* */
/* Descender :: The font's descender, i.e., the */
/* distance from the baseline to the */
@@ -273,8 +266,8 @@ FT_BEGIN_HEADER
/* ASCII). */
/* */
/* You should use the `sTypoDescender' */
- /* field of the OS/2 table instead if you */
- /* want the correct one. */
+ /* field of the `OS/2' table instead if */
+ /* you want the correct one. */
/* */
/* Line_Gap :: The font's line gap, i.e., the distance */
/* to add to the ascender and descender to */
@@ -309,7 +302,7 @@ FT_BEGIN_HEADER
/* */
/* metric_Data_Format :: Always~0. */
/* */
- /* number_Of_HMetrics :: Number of VMetrics entries in the */
+ /* number_Of_VMetrics :: Number of VMetrics entries in the */
/* `vmtx' table -- this value can be */
/* smaller than the total number of glyphs */
/* in the font. */
@@ -325,14 +318,6 @@ FT_BEGIN_HEADER
/* `Descender', `Line_Gap', `caret_Slope_Rise', `caret_Slope_Run', */
/* and `caret_Offset'. */
/* */
- /* IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should */
- /* be identical except for the names of their fields, */
- /* which are different. */
- /* */
- /* This ensures that a single function in the `ttload' */
- /* module is able to read both the horizontal and vertical */
- /* headers. */
- /* */
typedef struct TT_VertHeader_
{
FT_Fixed Version;
@@ -342,9 +327,9 @@ FT_BEGIN_HEADER
FT_UShort advance_Height_Max; /* advance height maximum */
- FT_Short min_Top_Side_Bearing; /* minimum left-sb or top-sb */
- FT_Short min_Bottom_Side_Bearing; /* minimum right-sb or bottom-sb */
- FT_Short yMax_Extent; /* xmax or ymax extents */
+ FT_Short min_Top_Side_Bearing; /* minimum top-sb */
+ FT_Short min_Bottom_Side_Bearing; /* minimum bottom-sb */
+ FT_Short yMax_Extent; /* ymax extents */
FT_Short caret_Slope_Rise;
FT_Short caret_Slope_Run;
FT_Short caret_Offset;
@@ -354,9 +339,9 @@ FT_BEGIN_HEADER
FT_Short metric_Data_Format;
FT_UShort number_Of_VMetrics;
- /* The following fields are not defined by the TrueType specification */
+ /* The following fields are not defined by the OpenType specification */
/* but they are used to connect the metrics header to the relevant */
- /* `hmtx' or `vmtx' table. */
+ /* `vmtx' table. */
void* long_metrics;
void* short_metrics;
@@ -370,12 +355,14 @@ FT_BEGIN_HEADER
/* TT_OS2 */
/* */
/* <Description> */
- /* A structure used to model a TrueType `OS/2' table. All fields */
- /* comply to the OpenType specification. */
+ /* A structure to model a TrueType `OS/2' table. All fields comply */
+ /* to the OpenType specification. */
/* */
- /* Note that we now support old Mac fonts that do not include an OS/2 */
- /* table. In this case, the `version' field is always set to 0xFFFF. */
+ /* Note that we now support old Mac fonts that do not include an */
+ /* `OS/2' table. In this case, the `version' field is always set to */
+ /* 0xFFFF. */
/* */
+ /* <Note> */
/* For an OpenType variation font, the values of the following fields */
/* can change after a call to @FT_Set_Var_Design_Coordinates (and */
/* friends) if the font contains an `MVAR' table: `sCapHeight', */
@@ -385,6 +372,10 @@ FT_BEGIN_HEADER
/* `ySubscriptYOffset', `ySubscriptYSize', `ySuperscriptXOffset', */
/* `ySuperscriptXSize', `ySuperscriptYOffset', and */
/* `ySuperscriptYSize'. */
+ /* */
+ /* Possible values for bits in the `ulUnicodeRangeX' fields are given */
+ /* by the @TT_UCR_XXX macros. */
+ /* */
typedef struct TT_OS2_
{
@@ -450,10 +441,10 @@ FT_BEGIN_HEADER
/* TT_Postscript */
/* */
/* <Description> */
- /* A structure used to model a TrueType `post' table. All fields */
- /* comply to the TrueType specification. This structure does not */
- /* reference the PostScript glyph names, which can be nevertheless */
- /* accessed with the `ttpost' module. */
+ /* A structure to model a TrueType `post' table. All fields comply */
+ /* to the OpenType specification. This structure does not reference */
+ /* a font's PostScript glyph names; use @FT_Get_Glyph_Name to */
+ /* retrieve them. */
/* */
/* <Note> */
/* For an OpenType variation font, the values of the following fields */
@@ -473,8 +464,8 @@ FT_BEGIN_HEADER
FT_ULong minMemType1;
FT_ULong maxMemType1;
- /* Glyph names follow in the file, but we don't */
- /* load them by default. See file `ttpost.c'. */
+ /* Glyph names follow in the `post' table, but we don't */
+ /* load them by default. */
} TT_Postscript;
@@ -485,8 +476,8 @@ FT_BEGIN_HEADER
/* TT_PCLT */
/* */
/* <Description> */
- /* A structure used to model a TrueType `PCLT' table. All fields */
- /* comply to the TrueType specification. */
+ /* A structure to model a TrueType `PCLT' table. All fields comply */
+ /* to the OpenType specification. */
/* */
typedef struct TT_PCLT_
{
@@ -516,8 +507,8 @@ FT_BEGIN_HEADER
/* */
/* <Description> */
/* The maximum profile (`maxp') table contains many max values, which */
- /* can be used to pre-allocate arrays. This ensures that no memory */
- /* allocation occurs during a glyph load. */
+ /* can be used to pre-allocate arrays for speeding up glyph loading */
+ /* and hinting. */
/* */
/* <Fields> */
/* version :: The version number. */
@@ -527,21 +518,19 @@ FT_BEGIN_HEADER
/* */
/* maxPoints :: The maximum number of points in a */
/* non-composite TrueType glyph. See also */
- /* the structure element */
/* `maxCompositePoints'. */
/* */
/* maxContours :: The maximum number of contours in a */
/* non-composite TrueType glyph. See also */
- /* the structure element */
/* `maxCompositeContours'. */
/* */
/* maxCompositePoints :: The maximum number of points in a */
- /* composite TrueType glyph. See also the */
- /* structure element `maxPoints'. */
+ /* composite TrueType glyph. See also */
+ /* `maxPoints'. */
/* */
/* maxCompositeContours :: The maximum number of contours in a */
- /* composite TrueType glyph. See also the */
- /* structure element `maxContours'. */
+ /* composite TrueType glyph. See also */
+ /* `maxContours'. */
/* */
/* maxZones :: The maximum number of zones used for */
/* glyph hinting. */
@@ -602,8 +591,9 @@ FT_BEGIN_HEADER
/* FT_Sfnt_Tag */
/* */
/* <Description> */
- /* An enumeration used to specify the index of an SFNT table. */
- /* Used in the @FT_Get_Sfnt_Table API function. */
+ /* An enumeration to specify indices of SFNT tables loaded and parsed */
+ /* by FreeType during initialization of an SFNT font. Used in the */
+ /* @FT_Get_Sfnt_Table API function. */
/* */
/* <Values> */
/* FT_SFNT_HEAD :: To access the font's @TT_Header structure. */
@@ -651,7 +641,7 @@ FT_BEGIN_HEADER
/* FT_Get_Sfnt_Table */
/* */
/* <Description> */
- /* Return a pointer to a given SFNT table within a face. */
+ /* Return a pointer to a given SFNT table stored within a face. */
/* */
/* <Input> */
/* face :: A handle to the source. */
@@ -659,7 +649,7 @@ FT_BEGIN_HEADER
/* tag :: The index of the SFNT table. */
/* */
/* <Return> */
- /* A type-less pointer to the table. This will be~0 in case of */
+ /* A type-less pointer to the table. This will be NULL in case of */
/* error, or if the corresponding table was not found *OR* loaded */
/* from the file. */
/* */
@@ -688,70 +678,70 @@ FT_BEGIN_HEADER
FT_Sfnt_Tag tag );
- /**************************************************************************
- *
- * @function:
- * FT_Load_Sfnt_Table
- *
- * @description:
- * Load any font table into client memory.
- *
- * @input:
- * face ::
- * A handle to the source face.
- *
- * tag ::
- * The four-byte tag of the table to load. Use the value~0 if you want
- * to access the whole font file. Otherwise, you can use one of the
- * definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
- * one with @FT_MAKE_TAG.
- *
- * offset ::
- * The starting offset in the table (or file if tag == 0).
- *
- * @output:
- * buffer ::
- * The target buffer address. The client must ensure that the memory
- * array is big enough to hold the data.
- *
- * @inout:
- * length ::
- * If the `length' parameter is NULL, then try to load the whole table.
- * Return an error code if it fails.
- *
- * Else, if `*length' is~0, exit immediately while returning the
- * table's (or file) full size in it.
- *
- * Else the number of bytes to read from the table or file, from the
- * starting offset.
- *
- * @return:
- * FreeType error code. 0~means success.
- *
- * @note:
- * If you need to determine the table's length you should first call this
- * function with `*length' set to~0, as in the following example:
- *
- * {
- * FT_ULong length = 0;
- *
- *
- * error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
- * if ( error ) { ... table does not exist ... }
- *
- * buffer = malloc( length );
- * if ( buffer == NULL ) { ... not enough memory ... }
- *
- * error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
- * if ( error ) { ... could not load table ... }
- * }
- *
- * Note that structures like @TT_Header or @TT_OS2 can't be used with
- * this function; they are limited to @FT_Get_Sfnt_Table. Reason is that
- * those structures depend on the processor architecture, with varying
- * size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
- *
- */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Load_Sfnt_Table
+ *
+ * @description:
+ * Load any SFNT font table into client memory.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face.
+ *
+ * tag ::
+ * The four-byte tag of the table to load. Use value~0 if you want
+ * to access the whole font file. Otherwise, you can use one of the
+ * definitions found in the @FT_TRUETYPE_TAGS_H file, or forge a new
+ * one with @FT_MAKE_TAG.
+ *
+ * offset ::
+ * The starting offset in the table (or file if tag~==~0).
+ *
+ * @output:
+ * buffer ::
+ * The target buffer address. The client must ensure that the memory
+ * array is big enough to hold the data.
+ *
+ * @inout:
+ * length ::
+ * If the `length' parameter is NULL, try to load the whole table.
+ * Return an error code if it fails.
+ *
+ * Else, if `*length' is~0, exit immediately while returning the
+ * table's (or file) full size in it.
+ *
+ * Else the number of bytes to read from the table or file, from the
+ * starting offset.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * If you need to determine the table's length you should first call this
+ * function with `*length' set to~0, as in the following example:
+ *
+ * {
+ * FT_ULong length = 0;
+ *
+ *
+ * error = FT_Load_Sfnt_Table( face, tag, 0, NULL, &length );
+ * if ( error ) { ... table does not exist ... }
+ *
+ * buffer = malloc( length );
+ * if ( buffer == NULL ) { ... not enough memory ... }
+ *
+ * error = FT_Load_Sfnt_Table( face, tag, 0, buffer, &length );
+ * if ( error ) { ... could not load table ... }
+ * }
+ *
+ * Note that structures like @TT_Header or @TT_OS2 can't be used with
+ * this function; they are limited to @FT_Get_Sfnt_Table. Reason is that
+ * those structures depend on the processor architecture, with varying
+ * size (e.g. 32bit vs. 64bit) or order (big endian vs. little endian).
+ *
+ */
FT_EXPORT( FT_Error )
FT_Load_Sfnt_Table( FT_Face face,
FT_ULong tag,
@@ -760,41 +750,41 @@ FT_BEGIN_HEADER
FT_ULong* length );
- /**************************************************************************
- *
- * @function:
- * FT_Sfnt_Table_Info
- *
- * @description:
- * Return information on an SFNT table.
- *
- * @input:
- * face ::
- * A handle to the source face.
- *
- * table_index ::
- * The index of an SFNT table. The function returns
- * FT_Err_Table_Missing for an invalid value.
- *
- * @inout:
- * tag ::
- * The name tag of the SFNT table. If the value is NULL, `table_index'
- * is ignored, and `length' returns the number of SFNT tables in the
- * font.
- *
- * @output:
- * length ::
- * The length of the SFNT table (or the number of SFNT tables, depending
- * on `tag').
- *
- * @return:
- * FreeType error code. 0~means success.
- *
- * @note:
- * While parsing fonts, FreeType handles SFNT tables with length zero as
- * missing.
- *
- */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Sfnt_Table_Info
+ *
+ * @description:
+ * Return information on an SFNT table.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face.
+ *
+ * table_index ::
+ * The index of an SFNT table. The function returns
+ * FT_Err_Table_Missing for an invalid value.
+ *
+ * @inout:
+ * tag ::
+ * The name tag of the SFNT table. If the value is NULL, `table_index'
+ * is ignored, and `length' returns the number of SFNT tables in the
+ * font.
+ *
+ * @output:
+ * length ::
+ * The length of the SFNT table (or the number of SFNT tables, depending
+ * on `tag').
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * While parsing fonts, FreeType handles SFNT tables with length zero as
+ * missing.
+ *
+ */
FT_EXPORT( FT_Error )
FT_Sfnt_Table_Info( FT_Face face,
FT_UInt table_index,
@@ -808,16 +798,16 @@ FT_BEGIN_HEADER
/* FT_Get_CMap_Language_ID */
/* */
/* <Description> */
- /* Return TrueType/sfnt specific cmap language ID. Definitions of */
- /* language ID values are in `ttnameid.h'. */
+ /* Return cmap language ID as specified in the OpenType standard. */
+ /* Definitions of language ID values are in file @FT_TRUETYPE_IDS_H. */
/* */
/* <Input> */
/* charmap :: */
/* The target charmap. */
/* */
/* <Return> */
- /* The language ID of `charmap'. If `charmap' doesn't belong to a */
- /* TrueType/sfnt face, just return~0 as the default value. */
+ /* The language ID of `charmap'. If `charmap' doesn't belong to an */
+ /* SFNT face, just return~0 as the default value. */
/* */
/* For a format~14 cmap (to access Unicode IVS), the return value is */
/* 0xFFFFFFFF. */
@@ -832,15 +822,15 @@ FT_BEGIN_HEADER
/* FT_Get_CMap_Format */
/* */
/* <Description> */
- /* Return TrueType/sfnt specific cmap format. */
+ /* Return the format of an SFNT `cmap' table. */
/* */
/* <Input> */
/* charmap :: */
/* The target charmap. */
/* */
/* <Return> */
- /* The format of `charmap'. If `charmap' doesn't belong to a */
- /* TrueType/sfnt face, return -1. */
+ /* The format of `charmap'. If `charmap' doesn't belong to an SFNT */
+ /* face, return -1. */
/* */
FT_EXPORT( FT_Long )
FT_Get_CMap_Format( FT_CharMap charmap );
diff --git a/src/sfnt/ttmtx.c b/src/sfnt/ttmtx.c
index f2e5541..394c6db 100644
--- a/src/sfnt/ttmtx.c
+++ b/src/sfnt/ttmtx.c
@@ -30,6 +30,14 @@
#include "sferrors.h"
+ /* IMPORTANT: The TT_HoriHeader and TT_VertHeader structures should */
+ /* be identical except for the names of their fields, */
+ /* which are different. */
+ /* */
+ /* This ensures that `tt_face_load_hmtx' is able to read */
+ /* both the horizontal and vertical headers. */
+
+
/*************************************************************************/
/* */
/* The macro FT_COMPONENT is used in trace mode. It is an implicit */