docs/reference/ft2-face_creation.html

   1
   2 <!doctype html>
   3 <html lang="en" class="no-js">
   4   <head>
   5
   6       <meta charset="utf-8">
   7       <meta name="viewport" content="width=device-width,initial-scale=1">
   8
   9         <meta name="description" content="API Reference Documentation for FreeType-2.13.2">
  10
  11
  12
  13         <meta name="author" content="FreeType Contributors">
  14
  15
  16       <link rel="icon" href="images/favico.ico">
  17       <meta name="generator" content="mkdocs-1.4.3, mkdocs-material-7.1.9">
  18
  19
  20
  21         <title>Face Creation - FreeType-2.13.2 API Reference</title>
  22
  23
  24
  25       <link rel="stylesheet" href="assets/stylesheets/main.ca7ac06f.min.css">
  26
  27
  28         <link rel="stylesheet" href="assets/stylesheets/palette.f1a3b89f.min.css">
  29
  30
  31
  32           <meta name="theme-color" content="#4cae4f">
  33
  34
  35
  36
  37
  38
  39
  40         <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  41         <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Noto+Serif:300,400,400i,700%7CRoboto+Mono&display=fallback">
  42         <style>:root{--md-text-font-family:"Noto Serif";--md-code-font-family:"Roboto Mono"}</style>
  43
  44
  45
  46
  47       <link rel="stylesheet" href="stylesheets/extra.css">
  48
  49
  50
  51
  52
  53
  54
  55   </head>
  56
  57
  58
  59
  60
  61
  62
  63     <body dir="ltr" data-md-color-scheme="" data-md-color-primary="green" data-md-color-accent="green">
  64
  65
  66     <script>function __prefix(e){return new URL(".",location).pathname+"."+e}function __get(e,t=localStorage){return JSON.parse(t.getItem(__prefix(e)))}</script>
  67
  68     <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
  69     <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
  70     <label class="md-overlay" for="__drawer"></label>
  71     <div data-md-component="skip">
  72
  73
  74         <a href="#face-creation" class="md-skip">
  75           Skip to content
  76         </a>
  77
  78     </div>
  79     <div data-md-component="announce">
  80
  81     </div>
  82
  83       <header class="md-header" data-md-component="header">
  84   <nav class="md-header__inner md-grid" aria-label="Header">
  85     <a href="index.html" title="FreeType-2.13.2 API Reference" class="md-header__button md-logo" aria-label="FreeType-2.13.2 API Reference" data-md-component="logo">
  86
  87   <img src="images/favico.ico" alt="logo">
  88
  89     </a>
  90     <label class="md-header__button md-icon" for="__drawer">
  91       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
  92     </label>
  93     <div class="md-header__title" data-md-component="header-title">
  94       <div class="md-header__ellipsis">
  95         <div class="md-header__topic">
  96           <span class="md-ellipsis">
  97             FreeType-2.13.2 API Reference
  98           </span>
  99         </div>
 100         <div class="md-header__topic" data-md-component="header-topic">
 101           <span class="md-ellipsis">
 102
 103               Face Creation
 104
 105           </span>
 106         </div>
 107       </div>
 108     </div>
 109
 110
 111
 112       <label class="md-header__button md-icon" for="__search">
 113         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
 114       </label>
 115
 116 <div class="md-search" data-md-component="search" role="dialog">
 117   <label class="md-search__overlay" for="__search"></label>
 118   <div class="md-search__inner" role="search">
 119     <form class="md-search__form" name="search">
 120       <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
 121       <label class="md-search__icon md-icon" for="__search">
 122         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
 123         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
 124       </label>
 125       <button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1">
 126         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg>
 127       </button>
 128     </form>
 129     <div class="md-search__output">
 130       <div class="md-search__scrollwrap" data-md-scrollfix>
 131         <div class="md-search-result" data-md-component="search-result">
 132           <div class="md-search-result__meta">
 133             Initializing search
 134           </div>
 135           <ol class="md-search-result__list"></ol>
 136         </div>
 137       </div>
 138     </div>
 139   </div>
 140 </div>
 141
 142
 143   </nav>
 144 </header>
 145
 146     <div class="md-container" data-md-component="container">
 147
 148
 149
 150
 151       <main class="md-main" data-md-component="main">
 152         <div class="md-main__inner md-grid">
 153
 154
 155
 156               <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
 157                 <div class="md-sidebar__scrollwrap">
 158                   <div class="md-sidebar__inner">
 159
 160
 161
 162 <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
 163   <label class="md-nav__title" for="__drawer">
 164     <a href="index.html" title="FreeType-2.13.2 API Reference" class="md-nav__button md-logo" aria-label="FreeType-2.13.2 API Reference" data-md-component="logo">
 165
 166   <img src="images/favico.ico" alt="logo">
 167
 168     </a>
 169     FreeType-2.13.2 API Reference
 170   </label>
 171
 172   <ul class="md-nav__list" data-md-scrollfix>
 173
 174
 175
 176
 177
 178
 179
 180
 181     <li class="md-nav__item">
 182       <a href="index.html" class="md-nav__link">
 183         TOC
 184       </a>
 185     </li>
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196     <li class="md-nav__item">
 197       <a href="ft2-index.html" class="md-nav__link">
 198         Index
 199       </a>
 200     </li>
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212     <li class="md-nav__item md-nav__item--nested">
 213
 214
 215         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" >
 216
 217       <label class="md-nav__link" for="__nav_3">
 218         General Remarks
 219         <span class="md-nav__icon md-icon"></span>
 220       </label>
 221       <nav class="md-nav" aria-label="General Remarks" data-md-level="1">
 222         <label class="md-nav__title" for="__nav_3">
 223           <span class="md-nav__icon md-icon"></span>
 224           General Remarks
 225         </label>
 226         <ul class="md-nav__list" data-md-scrollfix>
 227
 228
 229
 230
 231
 232     <li class="md-nav__item">
 233       <a href="ft2-preamble.html" class="md-nav__link">
 234         Preamble
 235       </a>
 236     </li>
 237
 238
 239
 240
 241
 242
 243
 244     <li class="md-nav__item">
 245       <a href="ft2-header_inclusion.html" class="md-nav__link">
 246         FreeType's header inclusion scheme
 247       </a>
 248     </li>
 249
 250
 251
 252
 253
 254
 255
 256     <li class="md-nav__item">
 257       <a href="ft2-user_allocation.html" class="md-nav__link">
 258         User allocation
 259       </a>
 260     </li>
 261
 262
 263
 264         </ul>
 265       </nav>
 266     </li>
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280     <li class="md-nav__item md-nav__item--active md-nav__item--nested">
 281
 282
 283         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" checked>
 284
 285       <label class="md-nav__link" for="__nav_4">
 286         Core API
 287         <span class="md-nav__icon md-icon"></span>
 288       </label>
 289       <nav class="md-nav" aria-label="Core API" data-md-level="1">
 290         <label class="md-nav__title" for="__nav_4">
 291           <span class="md-nav__icon md-icon"></span>
 292           Core API
 293         </label>
 294         <ul class="md-nav__list" data-md-scrollfix>
 295
 296
 297
 298
 299
 300     <li class="md-nav__item">
 301       <a href="ft2-basic_types.html" class="md-nav__link">
 302         Basic Data Types
 303       </a>
 304     </li>
 305
 306
 307
 308
 309
 310
 311
 312     <li class="md-nav__item">
 313       <a href="ft2-library_setup.html" class="md-nav__link">
 314         Library Setup
 315       </a>
 316     </li>
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326     <li class="md-nav__item md-nav__item--active">
 327
 328       <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
 329
 330
 331
 332
 333
 334         <label class="md-nav__link md-nav__link--active" for="__toc">
 335           Face Creation
 336           <span class="md-nav__icon md-icon"></span>
 337         </label>
 338
 339       <a href="ft2-face_creation.html" class="md-nav__link md-nav__link--active">
 340         Face Creation
 341       </a>
 342
 343
 344 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
 345
 346
 347
 348
 349
 350
 351     <label class="md-nav__title" for="__toc">
 352       <span class="md-nav__icon md-icon"></span>
 353       Table of contents
 354     </label>
 355     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 356
 357         <li class="md-nav__item">
 358   <a href="#synopsis" class="md-nav__link">
 359     Synopsis
 360   </a>
 361
 362 </li>
 363
 364         <li class="md-nav__item">
 365   <a href="#ft_face" class="md-nav__link">
 366     FT_Face
 367   </a>
 368
 369 </li>
 370
 371         <li class="md-nav__item">
 372   <a href="#ft_facerec" class="md-nav__link">
 373     FT_FaceRec
 374   </a>
 375
 376 </li>
 377
 378         <li class="md-nav__item">
 379   <a href="#ft_face_flag_xxx" class="md-nav__link">
 380     FT_FACE_FLAG_XXX
 381   </a>
 382
 383 </li>
 384
 385         <li class="md-nav__item">
 386   <a href="#ft_style_flag_xxx" class="md-nav__link">
 387     FT_STYLE_FLAG_XXX
 388   </a>
 389
 390 </li>
 391
 392         <li class="md-nav__item">
 393   <a href="#ft_new_face" class="md-nav__link">
 394     FT_New_Face
 395   </a>
 396
 397 </li>
 398
 399         <li class="md-nav__item">
 400   <a href="#ft_done_face" class="md-nav__link">
 401     FT_Done_Face
 402   </a>
 403
 404 </li>
 405
 406         <li class="md-nav__item">
 407   <a href="#ft_reference_face" class="md-nav__link">
 408     FT_Reference_Face
 409   </a>
 410
 411 </li>
 412
 413         <li class="md-nav__item">
 414   <a href="#ft_new_memory_face" class="md-nav__link">
 415     FT_New_Memory_Face
 416   </a>
 417
 418 </li>
 419
 420         <li class="md-nav__item">
 421   <a href="#ft_face_properties" class="md-nav__link">
 422     FT_Face_Properties
 423   </a>
 424
 425 </li>
 426
 427         <li class="md-nav__item">
 428   <a href="#ft_open_face" class="md-nav__link">
 429     FT_Open_Face
 430   </a>
 431
 432 </li>
 433
 434         <li class="md-nav__item">
 435   <a href="#ft_open_args" class="md-nav__link">
 436     FT_Open_Args
 437   </a>
 438
 439 </li>
 440
 441         <li class="md-nav__item">
 442   <a href="#ft_open_xxx" class="md-nav__link">
 443     FT_OPEN_XXX
 444   </a>
 445
 446 </li>
 447
 448         <li class="md-nav__item">
 449   <a href="#ft_parameter" class="md-nav__link">
 450     FT_Parameter
 451   </a>
 452
 453 </li>
 454
 455         <li class="md-nav__item">
 456   <a href="#ft_attach_file" class="md-nav__link">
 457     FT_Attach_File
 458   </a>
 459
 460 </li>
 461
 462         <li class="md-nav__item">
 463   <a href="#ft_attach_stream" class="md-nav__link">
 464     FT_Attach_Stream
 465   </a>
 466
 467 </li>
 468
 469     </ul>
 470
 471 </nav>
 472
 473     </li>
 474
 475
 476
 477
 478
 479
 480
 481     <li class="md-nav__item">
 482       <a href="ft2-font_testing_macros.html" class="md-nav__link">
 483         Font Testing Macros
 484       </a>
 485     </li>
 486
 487
 488
 489
 490
 491
 492
 493     <li class="md-nav__item">
 494       <a href="ft2-sizing_and_scaling.html" class="md-nav__link">
 495         Sizing and Scaling
 496       </a>
 497     </li>
 498
 499
 500
 501
 502
 503
 504
 505     <li class="md-nav__item">
 506       <a href="ft2-glyph_retrieval.html" class="md-nav__link">
 507         Glyph Retrieval
 508       </a>
 509     </li>
 510
 511
 512
 513
 514
 515
 516
 517     <li class="md-nav__item">
 518       <a href="ft2-character_mapping.html" class="md-nav__link">
 519         Character Mapping
 520       </a>
 521     </li>
 522
 523
 524
 525
 526
 527
 528
 529     <li class="md-nav__item">
 530       <a href="ft2-information_retrieval.html" class="md-nav__link">
 531         Information Retrieval
 532       </a>
 533     </li>
 534
 535
 536
 537
 538
 539
 540
 541     <li class="md-nav__item">
 542       <a href="ft2-other_api_data.html" class="md-nav__link">
 543         Other API Data
 544       </a>
 545     </li>
 546
 547
 548
 549         </ul>
 550       </nav>
 551     </li>
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563     <li class="md-nav__item md-nav__item--nested">
 564
 565
 566         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
 567
 568       <label class="md-nav__link" for="__nav_5">
 569         Extended API
 570         <span class="md-nav__icon md-icon"></span>
 571       </label>
 572       <nav class="md-nav" aria-label="Extended API" data-md-level="1">
 573         <label class="md-nav__title" for="__nav_5">
 574           <span class="md-nav__icon md-icon"></span>
 575           Extended API
 576         </label>
 577         <ul class="md-nav__list" data-md-scrollfix>
 578
 579
 580
 581
 582
 583     <li class="md-nav__item">
 584       <a href="ft2-glyph_variants.html" class="md-nav__link">
 585         Unicode Variation Sequences
 586       </a>
 587     </li>
 588
 589
 590
 591
 592
 593
 594
 595     <li class="md-nav__item">
 596       <a href="ft2-color_management.html" class="md-nav__link">
 597         Glyph Color Management
 598       </a>
 599     </li>
 600
 601
 602
 603
 604
 605
 606
 607     <li class="md-nav__item">
 608       <a href="ft2-layer_management.html" class="md-nav__link">
 609         Glyph Layer Management
 610       </a>
 611     </li>
 612
 613
 614
 615
 616
 617
 618
 619     <li class="md-nav__item">
 620       <a href="ft2-glyph_management.html" class="md-nav__link">
 621         Glyph Management
 622       </a>
 623     </li>
 624
 625
 626
 627
 628
 629
 630
 631     <li class="md-nav__item">
 632       <a href="ft2-mac_specific.html" class="md-nav__link">
 633         Mac Specific Interface
 634       </a>
 635     </li>
 636
 637
 638
 639
 640
 641
 642
 643     <li class="md-nav__item">
 644       <a href="ft2-sizes_management.html" class="md-nav__link">
 645         Size Management
 646       </a>
 647     </li>
 648
 649
 650
 651
 652
 653
 654
 655     <li class="md-nav__item">
 656       <a href="ft2-header_file_macros.html" class="md-nav__link">
 657         Header File Macros
 658       </a>
 659     </li>
 660
 661
 662
 663         </ul>
 664       </nav>
 665     </li>
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677     <li class="md-nav__item md-nav__item--nested">
 678
 679
 680         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" >
 681
 682       <label class="md-nav__link" for="__nav_6">
 683         Format-Specific API
 684         <span class="md-nav__icon md-icon"></span>
 685       </label>
 686       <nav class="md-nav" aria-label="Format-Specific API" data-md-level="1">
 687         <label class="md-nav__title" for="__nav_6">
 688           <span class="md-nav__icon md-icon"></span>
 689           Format-Specific API
 690         </label>
 691         <ul class="md-nav__list" data-md-scrollfix>
 692
 693
 694
 695
 696
 697     <li class="md-nav__item">
 698       <a href="ft2-multiple_masters.html" class="md-nav__link">
 699         Multiple Masters
 700       </a>
 701     </li>
 702
 703
 704
 705
 706
 707
 708
 709     <li class="md-nav__item">
 710       <a href="ft2-truetype_tables.html" class="md-nav__link">
 711         TrueType Tables
 712       </a>
 713     </li>
 714
 715
 716
 717
 718
 719
 720
 721     <li class="md-nav__item">
 722       <a href="ft2-type1_tables.html" class="md-nav__link">
 723         Type 1 Tables
 724       </a>
 725     </li>
 726
 727
 728
 729
 730
 731
 732
 733     <li class="md-nav__item">
 734       <a href="ft2-sfnt_names.html" class="md-nav__link">
 735         SFNT Names
 736       </a>
 737     </li>
 738
 739
 740
 741
 742
 743
 744
 745     <li class="md-nav__item">
 746       <a href="ft2-bdf_fonts.html" class="md-nav__link">
 747         BDF and PCF Files
 748       </a>
 749     </li>
 750
 751
 752
 753
 754
 755
 756
 757     <li class="md-nav__item">
 758       <a href="ft2-cid_fonts.html" class="md-nav__link">
 759         CID Fonts
 760       </a>
 761     </li>
 762
 763
 764
 765
 766
 767
 768
 769     <li class="md-nav__item">
 770       <a href="ft2-pfr_fonts.html" class="md-nav__link">
 771         PFR Fonts
 772       </a>
 773     </li>
 774
 775
 776
 777
 778
 779
 780
 781     <li class="md-nav__item">
 782       <a href="ft2-winfnt_fonts.html" class="md-nav__link">
 783         Window FNT Files
 784       </a>
 785     </li>
 786
 787
 788
 789
 790
 791
 792
 793     <li class="md-nav__item">
 794       <a href="ft2-svg_fonts.html" class="md-nav__link">
 795         OpenType SVG Fonts
 796       </a>
 797     </li>
 798
 799
 800
 801
 802
 803
 804
 805     <li class="md-nav__item">
 806       <a href="ft2-font_formats.html" class="md-nav__link">
 807         Font Formats
 808       </a>
 809     </li>
 810
 811
 812
 813
 814
 815
 816
 817     <li class="md-nav__item">
 818       <a href="ft2-gasp_table.html" class="md-nav__link">
 819         Gasp Table
 820       </a>
 821     </li>
 822
 823
 824
 825         </ul>
 826       </nav>
 827     </li>
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839     <li class="md-nav__item md-nav__item--nested">
 840
 841
 842         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" >
 843
 844       <label class="md-nav__link" for="__nav_7">
 845         Controlling FreeType Modules
 846         <span class="md-nav__icon md-icon"></span>
 847       </label>
 848       <nav class="md-nav" aria-label="Controlling FreeType Modules" data-md-level="1">
 849         <label class="md-nav__title" for="__nav_7">
 850           <span class="md-nav__icon md-icon"></span>
 851           Controlling FreeType Modules
 852         </label>
 853         <ul class="md-nav__list" data-md-scrollfix>
 854
 855
 856
 857
 858
 859     <li class="md-nav__item">
 860       <a href="ft2-auto_hinter.html" class="md-nav__link">
 861         The auto-hinter
 862       </a>
 863     </li>
 864
 865
 866
 867
 868
 869
 870
 871     <li class="md-nav__item">
 872       <a href="ft2-cff_driver.html" class="md-nav__link">
 873         The CFF driver
 874       </a>
 875     </li>
 876
 877
 878
 879
 880
 881
 882
 883     <li class="md-nav__item">
 884       <a href="ft2-t1_cid_driver.html" class="md-nav__link">
 885         The Type 1 and CID drivers
 886       </a>
 887     </li>
 888
 889
 890
 891
 892
 893
 894
 895     <li class="md-nav__item">
 896       <a href="ft2-tt_driver.html" class="md-nav__link">
 897         The TrueType driver
 898       </a>
 899     </li>
 900
 901
 902
 903
 904
 905
 906
 907     <li class="md-nav__item">
 908       <a href="ft2-pcf_driver.html" class="md-nav__link">
 909         The PCF driver
 910       </a>
 911     </li>
 912
 913
 914
 915
 916
 917
 918
 919     <li class="md-nav__item">
 920       <a href="ft2-ot_svg_driver.html" class="md-nav__link">
 921         The SVG driver
 922       </a>
 923     </li>
 924
 925
 926
 927
 928
 929
 930
 931     <li class="md-nav__item">
 932       <a href="ft2-properties.html" class="md-nav__link">
 933         Driver properties
 934       </a>
 935     </li>
 936
 937
 938
 939
 940
 941
 942
 943     <li class="md-nav__item">
 944       <a href="ft2-parameter_tags.html" class="md-nav__link">
 945         Parameter Tags
 946       </a>
 947     </li>
 948
 949
 950
 951
 952
 953
 954
 955     <li class="md-nav__item">
 956       <a href="ft2-lcd_rendering.html" class="md-nav__link">
 957         Subpixel Rendering
 958       </a>
 959     </li>
 960
 961
 962
 963         </ul>
 964       </nav>
 965     </li>
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977     <li class="md-nav__item md-nav__item--nested">
 978
 979
 980         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_8" type="checkbox" id="__nav_8" >
 981
 982       <label class="md-nav__link" for="__nav_8">
 983         Cache Sub-System
 984         <span class="md-nav__icon md-icon"></span>
 985       </label>
 986       <nav class="md-nav" aria-label="Cache Sub-System" data-md-level="1">
 987         <label class="md-nav__title" for="__nav_8">
 988           <span class="md-nav__icon md-icon"></span>
 989           Cache Sub-System
 990         </label>
 991         <ul class="md-nav__list" data-md-scrollfix>
 992
 993
 994
 995
 996
 997     <li class="md-nav__item">
 998       <a href="ft2-cache_subsystem.html" class="md-nav__link">
 999         Cache Sub-System
1000       </a>
1001     </li>
1002
1003
1004
1005         </ul>
1006       </nav>
1007     </li>
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019     <li class="md-nav__item md-nav__item--nested">
1020
1021
1022         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_9" type="checkbox" id="__nav_9" >
1023
1024       <label class="md-nav__link" for="__nav_9">
1025         Support API
1026         <span class="md-nav__icon md-icon"></span>
1027       </label>
1028       <nav class="md-nav" aria-label="Support API" data-md-level="1">
1029         <label class="md-nav__title" for="__nav_9">
1030           <span class="md-nav__icon md-icon"></span>
1031           Support API
1032         </label>
1033         <ul class="md-nav__list" data-md-scrollfix>
1034
1035
1036
1037
1038
1039     <li class="md-nav__item">
1040       <a href="ft2-computations.html" class="md-nav__link">
1041         Computations
1042       </a>
1043     </li>
1044
1045
1046
1047
1048
1049
1050
1051     <li class="md-nav__item">
1052       <a href="ft2-list_processing.html" class="md-nav__link">
1053         List Processing
1054       </a>
1055     </li>
1056
1057
1058
1059
1060
1061
1062
1063     <li class="md-nav__item">
1064       <a href="ft2-outline_processing.html" class="md-nav__link">
1065         Outline Processing
1066       </a>
1067     </li>
1068
1069
1070
1071
1072
1073
1074
1075     <li class="md-nav__item">
1076       <a href="ft2-quick_advance.html" class="md-nav__link">
1077         Quick retrieval of advance values
1078       </a>
1079     </li>
1080
1081
1082
1083
1084
1085
1086
1087     <li class="md-nav__item">
1088       <a href="ft2-bitmap_handling.html" class="md-nav__link">
1089         Bitmap Handling
1090       </a>
1091     </li>
1092
1093
1094
1095
1096
1097
1098
1099     <li class="md-nav__item">
1100       <a href="ft2-raster.html" class="md-nav__link">
1101         Scanline Converter
1102       </a>
1103     </li>
1104
1105
1106
1107
1108
1109
1110
1111     <li class="md-nav__item">
1112       <a href="ft2-glyph_stroker.html" class="md-nav__link">
1113         Glyph Stroker
1114       </a>
1115     </li>
1116
1117
1118
1119
1120
1121
1122
1123     <li class="md-nav__item">
1124       <a href="ft2-system_interface.html" class="md-nav__link">
1125         System Interface
1126       </a>
1127     </li>
1128
1129
1130
1131
1132
1133
1134
1135     <li class="md-nav__item">
1136       <a href="ft2-module_management.html" class="md-nav__link">
1137         Module Management
1138       </a>
1139     </li>
1140
1141
1142
1143
1144
1145
1146
1147     <li class="md-nav__item">
1148       <a href="ft2-gzip.html" class="md-nav__link">
1149         GZIP Streams
1150       </a>
1151     </li>
1152
1153
1154
1155
1156
1157
1158
1159     <li class="md-nav__item">
1160       <a href="ft2-lzw.html" class="md-nav__link">
1161         LZW Streams
1162       </a>
1163     </li>
1164
1165
1166
1167
1168
1169
1170
1171     <li class="md-nav__item">
1172       <a href="ft2-bzip2.html" class="md-nav__link">
1173         BZIP2 Streams
1174       </a>
1175     </li>
1176
1177
1178
1179
1180
1181
1182
1183     <li class="md-nav__item">
1184       <a href="ft2-debugging_apis.html" class="md-nav__link">
1185         External Debugging APIs
1186       </a>
1187     </li>
1188
1189
1190
1191         </ul>
1192       </nav>
1193     </li>
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205     <li class="md-nav__item md-nav__item--nested">
1206
1207
1208         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_10" type="checkbox" id="__nav_10" >
1209
1210       <label class="md-nav__link" for="__nav_10">
1211         Error Codes
1212         <span class="md-nav__icon md-icon"></span>
1213       </label>
1214       <nav class="md-nav" aria-label="Error Codes" data-md-level="1">
1215         <label class="md-nav__title" for="__nav_10">
1216           <span class="md-nav__icon md-icon"></span>
1217           Error Codes
1218         </label>
1219         <ul class="md-nav__list" data-md-scrollfix>
1220
1221
1222
1223
1224
1225     <li class="md-nav__item">
1226       <a href="ft2-error_enumerations.html" class="md-nav__link">
1227         Error Enumerations
1228       </a>
1229     </li>
1230
1231
1232
1233
1234
1235
1236
1237     <li class="md-nav__item">
1238       <a href="ft2-error_code_values.html" class="md-nav__link">
1239         Error Code Values
1240       </a>
1241     </li>
1242
1243
1244
1245         </ul>
1246       </nav>
1247     </li>
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259     <li class="md-nav__item md-nav__item--nested">
1260
1261
1262         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_11" type="checkbox" id="__nav_11" >
1263
1264       <label class="md-nav__link" for="__nav_11">
1265         Miscellaneous
1266         <span class="md-nav__icon md-icon"></span>
1267       </label>
1268       <nav class="md-nav" aria-label="Miscellaneous" data-md-level="1">
1269         <label class="md-nav__title" for="__nav_11">
1270           <span class="md-nav__icon md-icon"></span>
1271           Miscellaneous
1272         </label>
1273         <ul class="md-nav__list" data-md-scrollfix>
1274
1275
1276
1277
1278
1279     <li class="md-nav__item">
1280       <a href="ft2-gx_validation.html" class="md-nav__link">
1281         TrueTypeGX/AAT Validation
1282       </a>
1283     </li>
1284
1285
1286
1287
1288
1289
1290
1291     <li class="md-nav__item">
1292       <a href="ft2-incremental.html" class="md-nav__link">
1293         Incremental Loading
1294       </a>
1295     </li>
1296
1297
1298
1299
1300
1301
1302
1303     <li class="md-nav__item">
1304       <a href="ft2-truetype_engine.html" class="md-nav__link">
1305         The TrueType Engine
1306       </a>
1307     </li>
1308
1309
1310
1311
1312
1313
1314
1315     <li class="md-nav__item">
1316       <a href="ft2-ot_validation.html" class="md-nav__link">
1317         OpenType Validation
1318       </a>
1319     </li>
1320
1321
1322
1323         </ul>
1324       </nav>
1325     </li>
1326
1327
1328
1329   </ul>
1330 </nav>
1331                   </div>
1332                 </div>
1333               </div>
1334
1335
1336
1337               <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
1338                 <div class="md-sidebar__scrollwrap">
1339                   <div class="md-sidebar__inner">
1340
1341 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1342
1343
1344
1345
1346
1347
1348     <label class="md-nav__title" for="__toc">
1349       <span class="md-nav__icon md-icon"></span>
1350       Table of contents
1351     </label>
1352     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1353
1354         <li class="md-nav__item">
1355   <a href="#synopsis" class="md-nav__link">
1356     Synopsis
1357   </a>
1358
1359 </li>
1360
1361         <li class="md-nav__item">
1362   <a href="#ft_face" class="md-nav__link">
1363     FT_Face
1364   </a>
1365
1366 </li>
1367
1368         <li class="md-nav__item">
1369   <a href="#ft_facerec" class="md-nav__link">
1370     FT_FaceRec
1371   </a>
1372
1373 </li>
1374
1375         <li class="md-nav__item">
1376   <a href="#ft_face_flag_xxx" class="md-nav__link">
1377     FT_FACE_FLAG_XXX
1378   </a>
1379
1380 </li>
1381
1382         <li class="md-nav__item">
1383   <a href="#ft_style_flag_xxx" class="md-nav__link">
1384     FT_STYLE_FLAG_XXX
1385   </a>
1386
1387 </li>
1388
1389         <li class="md-nav__item">
1390   <a href="#ft_new_face" class="md-nav__link">
1391     FT_New_Face
1392   </a>
1393
1394 </li>
1395
1396         <li class="md-nav__item">
1397   <a href="#ft_done_face" class="md-nav__link">
1398     FT_Done_Face
1399   </a>
1400
1401 </li>
1402
1403         <li class="md-nav__item">
1404   <a href="#ft_reference_face" class="md-nav__link">
1405     FT_Reference_Face
1406   </a>
1407
1408 </li>
1409
1410         <li class="md-nav__item">
1411   <a href="#ft_new_memory_face" class="md-nav__link">
1412     FT_New_Memory_Face
1413   </a>
1414
1415 </li>
1416
1417         <li class="md-nav__item">
1418   <a href="#ft_face_properties" class="md-nav__link">
1419     FT_Face_Properties
1420   </a>
1421
1422 </li>
1423
1424         <li class="md-nav__item">
1425   <a href="#ft_open_face" class="md-nav__link">
1426     FT_Open_Face
1427   </a>
1428
1429 </li>
1430
1431         <li class="md-nav__item">
1432   <a href="#ft_open_args" class="md-nav__link">
1433     FT_Open_Args
1434   </a>
1435
1436 </li>
1437
1438         <li class="md-nav__item">
1439   <a href="#ft_open_xxx" class="md-nav__link">
1440     FT_OPEN_XXX
1441   </a>
1442
1443 </li>
1444
1445         <li class="md-nav__item">
1446   <a href="#ft_parameter" class="md-nav__link">
1447     FT_Parameter
1448   </a>
1449
1450 </li>
1451
1452         <li class="md-nav__item">
1453   <a href="#ft_attach_file" class="md-nav__link">
1454     FT_Attach_File
1455   </a>
1456
1457 </li>
1458
1459         <li class="md-nav__item">
1460   <a href="#ft_attach_stream" class="md-nav__link">
1461     FT_Attach_Stream
1462   </a>
1463
1464 </li>
1465
1466     </ul>
1467
1468 </nav>
1469                   </div>
1470                 </div>
1471               </div>
1472
1473
1474           <div class="md-content" data-md-component="content">
1475             <article class="md-content__inner md-typeset">
1476
1477
1478
1479                 <p><a href="https://www.freetype.org">FreeType</a> &raquo; <a href="../">Docs</a> &raquo; <a href="index.html#core-api">Core API</a> &raquo; Face Creation</p>
1480 <hr />
1481 <h1 id="face-creation">Face Creation<a class="headerlink" href="#face-creation" title="Permanent link">&para;</a></h1>
1482 <h2 id="synopsis">Synopsis<a class="headerlink" href="#synopsis" title="Permanent link">&para;</a></h2>
1483 <p>The functions and structures collected in this section operate on fonts globally.</p>
1484 <h2 id="ft_face">FT_Face<a class="headerlink" href="#ft_face" title="Permanent link">&para;</a></h2>
1485 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1486 <div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span> FT_FaceRec_*  <b>FT_Face</b>;
1487 </code></pre></div>
1488
1489 <p>A handle to a typographic face object. A face object models a given typeface, in a given style.</p>
1490 <h4>note</h4>
1491
1492 <p>A face object also owns a single <code><a href="ft2-glyph_retrieval.html#ft_glyphslot">FT_GlyphSlot</a></code> object, as well as one or more <code><a href="ft2-sizing_and_scaling.html#ft_size">FT_Size</a></code> objects.</p>
1493 <p>Use <code><a href="ft2-face_creation.html#ft_new_face">FT_New_Face</a></code> or <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> to create a new face object from a given filepath or a custom input stream.</p>
1494 <p>Use <code><a href="ft2-face_creation.html#ft_done_face">FT_Done_Face</a></code> to destroy it (along with its slot and sizes).</p>
1495 <p>An <code>FT_Face</code> object can only be safely used from one thread at a time. Similarly, creation and destruction of <code>FT_Face</code> with the same <code><a href="ft2-library_setup.html#ft_library">FT_Library</a></code> object can only be done from one thread at a time. On the other hand, functions like <code><a href="ft2-glyph_retrieval.html#ft_load_glyph">FT_Load_Glyph</a></code> and its siblings are thread-safe and do not need the lock to be held as long as the same <code>FT_Face</code> object is not used from multiple threads at the same time.</p>
1496 <h4>also</h4>
1497
1498 <p>See <code><a href="ft2-face_creation.html#ft_facerec">FT_FaceRec</a></code> for the publicly accessible fields of a given face object.</p>
1499 <hr>
1500
1501 <h2 id="ft_facerec">FT_FaceRec<a class="headerlink" href="#ft_facerec" title="Permanent link">&para;</a></h2>
1502 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1503 <div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span>  FT_FaceRec_
1504   {
1505     <a href="ft2-basic_types.html#ft_long">FT_Long</a>           num_faces;
1506     <a href="ft2-basic_types.html#ft_long">FT_Long</a>           face_index;
1507
1508     <a href="ft2-basic_types.html#ft_long">FT_Long</a>           face_flags;
1509     <a href="ft2-basic_types.html#ft_long">FT_Long</a>           style_flags;
1510
1511     <a href="ft2-basic_types.html#ft_long">FT_Long</a>           num_glyphs;
1512
1513     <a href="ft2-basic_types.html#ft_string">FT_String</a>*        family_name;
1514     <a href="ft2-basic_types.html#ft_string">FT_String</a>*        style_name;
1515
1516     <a href="ft2-basic_types.html#ft_int">FT_Int</a>            num_fixed_sizes;
1517     <a href="ft2-sizing_and_scaling.html#ft_bitmap_size">FT_Bitmap_Size</a>*   available_sizes;
1518
1519     <a href="ft2-basic_types.html#ft_int">FT_Int</a>            num_charmaps;
1520     <a href="ft2-character_mapping.html#ft_charmap">FT_CharMap</a>*       charmaps;
1521
1522     <a href="ft2-basic_types.html#ft_generic">FT_Generic</a>        generic;
1523
1524     /* The following member variables (down to `underline_thickness`) */
1525     /* are only relevant to scalable outlines; cf. @<a href="ft2-sizing_and_scaling.html#ft_bitmap_size">FT_Bitmap_Size</a>    */
1526     /* for bitmap fonts.                                              */
1527     <a href="ft2-basic_types.html#ft_bbox">FT_BBox</a>           bbox;
1528
1529     <a href="ft2-basic_types.html#ft_ushort">FT_UShort</a>         units_per_EM;
1530     <a href="ft2-basic_types.html#ft_short">FT_Short</a>          ascender;
1531     <a href="ft2-basic_types.html#ft_short">FT_Short</a>          descender;
1532     <a href="ft2-basic_types.html#ft_short">FT_Short</a>          height;
1533
1534     <a href="ft2-basic_types.html#ft_short">FT_Short</a>          max_advance_width;
1535     <a href="ft2-basic_types.html#ft_short">FT_Short</a>          max_advance_height;
1536
1537     <a href="ft2-basic_types.html#ft_short">FT_Short</a>          underline_position;
1538     <a href="ft2-basic_types.html#ft_short">FT_Short</a>          underline_thickness;
1539
1540     <a href="ft2-glyph_retrieval.html#ft_glyphslot">FT_GlyphSlot</a>      glyph;
1541     <a href="ft2-sizing_and_scaling.html#ft_size">FT_Size</a>           size;
1542     <a href="ft2-character_mapping.html#ft_charmap">FT_CharMap</a>        charmap;
1543
1544     /* private fields, internal to FreeType */
1545
1546     <a href="ft2-module_management.html#ft_driver">FT_Driver</a>         driver;
1547     <a href="ft2-system_interface.html#ft_memory">FT_Memory</a>         memory;
1548     <a href="ft2-system_interface.html#ft_stream">FT_Stream</a>         stream;
1549
1550     <a href="ft2-list_processing.html#ft_listrec">FT_ListRec</a>        sizes_list;
1551
1552     <a href="ft2-basic_types.html#ft_generic">FT_Generic</a>        autohint;   /* face-specific auto-hinter data */
1553     <span class="keyword">void</span>*             extensions; /* unused                         */
1554
1555     <a href="ft2-other_api_data.html#ft_face_internal">FT_Face_Internal</a>  internal;
1556
1557   } <b>FT_FaceRec</b>;
1558 </code></pre></div>
1559
1560 <p>FreeType root face class structure. A face object models a typeface in a font file.</p>
1561 <h4>fields</h4>
1562 <table class="fields">
1563 <tr><td class="val" id="num_faces">num_faces</td><td class="desc">
1564 <p>The number of faces in the font file. Some font formats can have multiple faces in a single font file.</p>
1565 </td></tr>
1566 <tr><td class="val" id="face_index">face_index</td><td class="desc">
1567 <p>This field holds two different values. Bits 0-15 are the index of the face in the font file (starting with value&nbsp;0). They are set to&nbsp;0 if there is only one face in the font file.</p>
1568 <p>[Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation fonts only, holding the named instance index for the current face index (starting with value&nbsp;1; value&nbsp;0 indicates font access without a named instance). For non-variation fonts, bits 16-30 are ignored. If we have the third named instance of face&nbsp;4, say, <code>face_index</code> is set to 0x00030004.</p>
1569 <p>Bit 31 is always zero (that is, <code>face_index</code> is always a positive value).</p>
1570 <p>[Since 2.9] Changing the design coordinates with <code><a href="ft2-multiple_masters.html#ft_set_var_design_coordinates">FT_Set_Var_Design_Coordinates</a></code> or <code><a href="ft2-multiple_masters.html#ft_set_var_blend_coordinates">FT_Set_Var_Blend_Coordinates</a></code> does not influence the named instance index value (only <code><a href="ft2-multiple_masters.html#ft_set_named_instance">FT_Set_Named_Instance</a></code> does that).</p>
1571 </td></tr>
1572 <tr><td class="val" id="face_flags">face_flags</td><td class="desc">
1573 <p>A set of bit flags that give important information about the face; see <code><a href="ft2-face_creation.html#ft_face_flag_xxx">FT_FACE_FLAG_XXX</a></code> for the details.</p>
1574 </td></tr>
1575 <tr><td class="val" id="style_flags">style_flags</td><td class="desc">
1576 <p>The lower 16&nbsp;bits contain a set of bit flags indicating the style of the face; see <code><a href="ft2-face_creation.html#ft_style_flag_xxx">FT_STYLE_FLAG_XXX</a></code> for the details.</p>
1577 <p>[Since 2.6.1] Bits 16-30 hold the number of named instances available for the current face if we have a GX or OpenType variation (sub)font. Bit 31 is always zero (that is, <code>style_flags</code> is always a positive value). Note that a variation font has always at least one named instance, namely the default instance.</p>
1578 </td></tr>
1579 <tr><td class="val" id="num_glyphs">num_glyphs</td><td class="desc">
1580 <p>The number of glyphs in the face. If the face is scalable and has sbits (see <code>num_fixed_sizes</code>), it is set to the number of outline glyphs.</p>
1581 <p>For CID-keyed fonts (not in an SFNT wrapper) this value gives the highest CID used in the font.</p>
1582 </td></tr>
1583 <tr><td class="val" id="family_name">family_name</td><td class="desc">
1584 <p>The face's family name. This is an ASCII string, usually in English, that describes the typeface's family (like &lsquo;Times New Roman&rsquo;, &lsquo;Bodoni&rsquo;, &lsquo;Garamond&rsquo;, etc). This is a least common denominator used to list fonts. Some formats (TrueType &amp; OpenType) provide localized and Unicode versions of this string. Applications should use the format-specific interface to access them. Can be <code>NULL</code> (e.g., in fonts embedded in a PDF file).</p>
1585 <p>In case the font doesn't provide a specific family name entry, FreeType tries to synthesize one, deriving it from other name entries.</p>
1586 </td></tr>
1587 <tr><td class="val" id="style_name">style_name</td><td class="desc">
1588 <p>The face's style name. This is an ASCII string, usually in English, that describes the typeface's style (like &lsquo;Italic&rsquo;, &lsquo;Bold&rsquo;, &lsquo;Condensed&rsquo;, etc). Not all font formats provide a style name, so this field is optional, and can be set to <code>NULL</code>. As for <code>family_name</code>, some formats provide localized and Unicode versions of this string. Applications should use the format-specific interface to access them.</p>
1589 </td></tr>
1590 <tr><td class="val" id="num_fixed_sizes">num_fixed_sizes</td><td class="desc">
1591 <p>The number of bitmap strikes in the face. Even if the face is scalable, there might still be bitmap strikes, which are called &lsquo;sbits&rsquo; in that case.</p>
1592 </td></tr>
1593 <tr><td class="val" id="available_sizes">available_sizes</td><td class="desc">
1594 <p>An array of <code><a href="ft2-sizing_and_scaling.html#ft_bitmap_size">FT_Bitmap_Size</a></code> for all bitmap strikes in the face. It is set to <code>NULL</code> if there is no bitmap strike.</p>
1595 <p>Note that FreeType tries to sanitize the strike data since they are sometimes sloppy or incorrect, but this can easily fail.</p>
1596 </td></tr>
1597 <tr><td class="val" id="num_charmaps">num_charmaps</td><td class="desc">
1598 <p>The number of charmaps in the face.</p>
1599 </td></tr>
1600 <tr><td class="val" id="charmaps">charmaps</td><td class="desc">
1601 <p>An array of the charmaps of the face.</p>
1602 </td></tr>
1603 <tr><td class="val" id="generic">generic</td><td class="desc">
1604 <p>A field reserved for client uses. See the <code><a href="ft2-basic_types.html#ft_generic">FT_Generic</a></code> type description.</p>
1605 </td></tr>
1606 <tr><td class="val" id="bbox">bbox</td><td class="desc">
1607 <p>The font bounding box. Coordinates are expressed in font units (see <code>units_per_EM</code>). The box is large enough to contain any glyph from the font. Thus, <code>bbox.yMax</code> can be seen as the &lsquo;maximum ascender&rsquo;, and <code>bbox.yMin</code> as the &lsquo;minimum descender&rsquo;. Only relevant for scalable formats.</p>
1608 <p>Note that the bounding box might be off by (at least) one pixel for hinted fonts. See <code><a href="ft2-sizing_and_scaling.html#ft_size_metrics">FT_Size_Metrics</a></code> for further discussion.</p>
1609 <p>Note that the bounding box does not vary in OpenType variation fonts and should only be used in relation to the default instance.</p>
1610 </td></tr>
1611 <tr><td class="val" id="units_per_em">units_per_EM</td><td class="desc">
1612 <p>The number of font units per EM square for this face. This is typically 2048 for TrueType fonts, and 1000 for Type&nbsp;1 fonts. Only relevant for scalable formats.</p>
1613 </td></tr>
1614 <tr><td class="val" id="ascender">ascender</td><td class="desc">
1615 <p>The typographic ascender of the face, expressed in font units. For font formats not having this information, it is set to <code>bbox.yMax</code>. Only relevant for scalable formats.</p>
1616 </td></tr>
1617 <tr><td class="val" id="descender">descender</td><td class="desc">
1618 <p>The typographic descender of the face, expressed in font units. For font formats not having this information, it is set to <code>bbox.yMin</code>. Note that this field is negative for values below the baseline. Only relevant for scalable formats.</p>
1619 </td></tr>
1620 <tr><td class="val" id="height">height</td><td class="desc">
1621 <p>This value is the vertical distance between two consecutive baselines, expressed in font units. It is always positive. Only relevant for scalable formats.</p>
1622 <p>If you want the global glyph height, use <code>ascender - descender</code>.</p>
1623 </td></tr>
1624 <tr><td class="val" id="max_advance_width">max_advance_width</td><td class="desc">
1625 <p>The maximum advance width, in font units, for all glyphs in this face. This can be used to make word wrapping computations faster. Only relevant for scalable formats.</p>
1626 </td></tr>
1627 <tr><td class="val" id="max_advance_height">max_advance_height</td><td class="desc">
1628 <p>The maximum advance height, in font units, for all glyphs in this face. This is only relevant for vertical layouts, and is set to <code>height</code> for fonts that do not provide vertical metrics. Only relevant for scalable formats.</p>
1629 </td></tr>
1630 <tr><td class="val" id="underline_position">underline_position</td><td class="desc">
1631 <p>The position, in font units, of the underline line for this face. It is the center of the underlining stem. Only relevant for scalable formats.</p>
1632 </td></tr>
1633 <tr><td class="val" id="underline_thickness">underline_thickness</td><td class="desc">
1634 <p>The thickness, in font units, of the underline for this face. Only relevant for scalable formats.</p>
1635 </td></tr>
1636 <tr><td class="val" id="glyph">glyph</td><td class="desc">
1637 <p>The face's associated glyph slot(s).</p>
1638 </td></tr>
1639 <tr><td class="val" id="size">size</td><td class="desc">
1640 <p>The current active size for this face.</p>
1641 </td></tr>
1642 <tr><td class="val" id="charmap">charmap</td><td class="desc">
1643 <p>The current active charmap for this face.</p>
1644 </td></tr>
1645 </table>
1646
1647 <h4>note</h4>
1648
1649 <p>Fields may be changed after a call to <code><a href="ft2-face_creation.html#ft_attach_file">FT_Attach_File</a></code> or <code><a href="ft2-face_creation.html#ft_attach_stream">FT_Attach_Stream</a></code>.</p>
1650 <p>For an OpenType variation font, the values of the following fields can change after a call to <code><a href="ft2-multiple_masters.html#ft_set_var_design_coordinates">FT_Set_Var_Design_Coordinates</a></code> (and friends) if the font contains an &lsquo;MVAR&rsquo; table: <code>ascender</code>, <code>descender</code>, <code>height</code>, <code>underline_position</code>, and <code>underline_thickness</code>.</p>
1651 <p>Especially for TrueType fonts see also the documentation for <code><a href="ft2-sizing_and_scaling.html#ft_size_metrics">FT_Size_Metrics</a></code>.</p>
1652 <hr>
1653
1654 <h2 id="ft_face_flag_xxx">FT_FACE_FLAG_XXX<a class="headerlink" href="#ft_face_flag_xxx" title="Permanent link">&para;</a></h2>
1655 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1656 <div class = "codehilite"><pre><code>#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_scalable">FT_FACE_FLAG_SCALABLE</a>          ( 1L &lt;&lt;  0 )
1657 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_fixed_sizes">FT_FACE_FLAG_FIXED_SIZES</a>       ( 1L &lt;&lt;  1 )
1658 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_fixed_width">FT_FACE_FLAG_FIXED_WIDTH</a>       ( 1L &lt;&lt;  2 )
1659 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sfnt">FT_FACE_FLAG_SFNT</a>              ( 1L &lt;&lt;  3 )
1660 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_horizontal">FT_FACE_FLAG_HORIZONTAL</a>        ( 1L &lt;&lt;  4 )
1661 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_vertical">FT_FACE_FLAG_VERTICAL</a>          ( 1L &lt;&lt;  5 )
1662 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_kerning">FT_FACE_FLAG_KERNING</a>           ( 1L &lt;&lt;  6 )
1663 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_fast_glyphs">FT_FACE_FLAG_FAST_GLYPHS</a>       ( 1L &lt;&lt;  7 )
1664 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_multiple_masters">FT_FACE_FLAG_MULTIPLE_MASTERS</a>  ( 1L &lt;&lt;  8 )
1665 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_glyph_names">FT_FACE_FLAG_GLYPH_NAMES</a>       ( 1L &lt;&lt;  9 )
1666 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_external_stream">FT_FACE_FLAG_EXTERNAL_STREAM</a>   ( 1L &lt;&lt; 10 )
1667 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_hinter">FT_FACE_FLAG_HINTER</a>            ( 1L &lt;&lt; 11 )
1668 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_cid_keyed">FT_FACE_FLAG_CID_KEYED</a>         ( 1L &lt;&lt; 12 )
1669 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_tricky">FT_FACE_FLAG_TRICKY</a>            ( 1L &lt;&lt; 13 )
1670 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_color">FT_FACE_FLAG_COLOR</a>             ( 1L &lt;&lt; 14 )
1671 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_variation">FT_FACE_FLAG_VARIATION</a>         ( 1L &lt;&lt; 15 )
1672 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_svg">FT_FACE_FLAG_SVG</a>               ( 1L &lt;&lt; 16 )
1673 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sbix">FT_FACE_FLAG_SBIX</a>              ( 1L &lt;&lt; 17 )
1674 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sbix_overlay">FT_FACE_FLAG_SBIX_OVERLAY</a>      ( 1L &lt;&lt; 18 )
1675 </code></pre></div>
1676
1677 <p>A list of bit flags used in the <code>face_flags</code> field of the <code><a href="ft2-face_creation.html#ft_facerec">FT_FaceRec</a></code> structure. They inform client applications of properties of the corresponding face.</p>
1678 <h4>values</h4>
1679 <table class="fields long">
1680 <tr><td class="val" id="ft_face_flag_scalable">FT_FACE_FLAG_SCALABLE</td><td class="desc">
1681 <p>The face contains outline glyphs. Note that a face can contain bitmap strikes also, i.e., a face can have both this flag and <code><a href="ft2-face_creation.html#ft_face_flag_xxx">FT_FACE_FLAG_FIXED_SIZES</a></code> set.</p>
1682 </td></tr>
1683 <tr><td class="val" id="ft_face_flag_fixed_sizes">FT_FACE_FLAG_FIXED_SIZES</td><td class="desc">
1684 <p>The face contains bitmap strikes. See also the <code>num_fixed_sizes</code> and <code>available_sizes</code> fields of <code><a href="ft2-face_creation.html#ft_facerec">FT_FaceRec</a></code>.</p>
1685 </td></tr>
1686 <tr><td class="val" id="ft_face_flag_fixed_width">FT_FACE_FLAG_FIXED_WIDTH</td><td class="desc">
1687 <p>The face contains fixed-width characters (like Courier, Lucida, MonoType, etc.).</p>
1688 </td></tr>
1689 <tr><td class="val" id="ft_face_flag_sfnt">FT_FACE_FLAG_SFNT</td><td class="desc">
1690 <p>The face uses the SFNT storage scheme. For now, this means TrueType and OpenType.</p>
1691 </td></tr>
1692 <tr><td class="val" id="ft_face_flag_horizontal">FT_FACE_FLAG_HORIZONTAL</td><td class="desc">
1693 <p>The face contains horizontal glyph metrics. This should be set for all common formats.</p>
1694 </td></tr>
1695 <tr><td class="val" id="ft_face_flag_vertical">FT_FACE_FLAG_VERTICAL</td><td class="desc">
1696 <p>The face contains vertical glyph metrics. This is only available in some formats, not all of them.</p>
1697 </td></tr>
1698 <tr><td class="val" id="ft_face_flag_kerning">FT_FACE_FLAG_KERNING</td><td class="desc">
1699 <p>The face contains kerning information. If set, the kerning distance can be retrieved using the function <code><a href="ft2-glyph_retrieval.html#ft_get_kerning">FT_Get_Kerning</a></code>. Otherwise the function always returns the vector (0,0). Note that FreeType doesn't handle kerning data from the SFNT &lsquo;GPOS&rsquo; table (as present in many OpenType fonts).</p>
1700 </td></tr>
1701 <tr><td class="val" id="ft_face_flag_fast_glyphs">FT_FACE_FLAG_FAST_GLYPHS</td><td class="desc">
1702 <p>THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT.</p>
1703 </td></tr>
1704 <tr><td class="val" id="ft_face_flag_multiple_masters">FT_FACE_FLAG_MULTIPLE_MASTERS</td><td class="desc">
1705 <p>The face contains multiple masters and is capable of interpolating between them. Supported formats are Adobe MM, TrueType GX, and OpenType variation fonts.</p>
1706 <p>See section &lsquo;<a href="ft2-multiple_masters.html#multiple_masters">Multiple Masters</a>&rsquo; for API details.</p>
1707 </td></tr>
1708 <tr><td class="val" id="ft_face_flag_glyph_names">FT_FACE_FLAG_GLYPH_NAMES</td><td class="desc">
1709 <p>The face contains glyph names, which can be retrieved using <code><a href="ft2-information_retrieval.html#ft_get_glyph_name">FT_Get_Glyph_Name</a></code>. Note that some TrueType fonts contain broken glyph name tables. Use the function <code><a href="ft2-type1_tables.html#ft_has_ps_glyph_names">FT_Has_PS_Glyph_Names</a></code> when needed.</p>
1710 </td></tr>
1711 <tr><td class="val" id="ft_face_flag_external_stream">FT_FACE_FLAG_EXTERNAL_STREAM</td><td class="desc">
1712 <p>Used internally by FreeType to indicate that a face's stream was provided by the client application and should not be destroyed when <code><a href="ft2-face_creation.html#ft_done_face">FT_Done_Face</a></code> is called. Don't read or test this flag.</p>
1713 </td></tr>
1714 <tr><td class="val" id="ft_face_flag_hinter">FT_FACE_FLAG_HINTER</td><td class="desc">
1715 <p>The font driver has a hinting machine of its own. For example, with TrueType fonts, it makes sense to use data from the SFNT &lsquo;gasp&rsquo; table only if the native TrueType hinting engine (with the bytecode interpreter) is available and active.</p>
1716 </td></tr>
1717 <tr><td class="val" id="ft_face_flag_cid_keyed">FT_FACE_FLAG_CID_KEYED</td><td class="desc">
1718 <p>The face is CID-keyed. In that case, the face is not accessed by glyph indices but by CID values. For subsetted CID-keyed fonts this has the consequence that not all index values are a valid argument to <code><a href="ft2-glyph_retrieval.html#ft_load_glyph">FT_Load_Glyph</a></code>. Only the CID values for which corresponding glyphs in the subsetted font exist make <code>FT_Load_Glyph</code> return successfully; in all other cases you get an <code>FT_Err_Invalid_Argument</code> error.</p>
1719 <p>Note that CID-keyed fonts that are in an SFNT wrapper (that is, all OpenType/CFF fonts) don't have this flag set since the glyphs are accessed in the normal way (using contiguous indices); the &lsquo;CID-ness&rsquo; isn't visible to the application.</p>
1720 </td></tr>
1721 <tr><td class="val" id="ft_face_flag_tricky">FT_FACE_FLAG_TRICKY</td><td class="desc">
1722 <p>The face is &lsquo;tricky&rsquo;, that is, it always needs the font format's native hinting engine to get a reasonable result. A typical example is the old Chinese font <code>mingli.ttf</code> (but not <code>mingliu.ttc</code>) that uses TrueType bytecode instructions to move and scale all of its subglyphs.</p>
1723 <p>It is not possible to auto-hint such fonts using <code><a href="ft2-glyph_retrieval.html#ft_load_xxx">FT_LOAD_FORCE_AUTOHINT</a></code>; it will also ignore <code><a href="ft2-glyph_retrieval.html#ft_load_xxx">FT_LOAD_NO_HINTING</a></code>. You have to set both <code><a href="ft2-glyph_retrieval.html#ft_load_xxx">FT_LOAD_NO_HINTING</a></code> and <code><a href="ft2-glyph_retrieval.html#ft_load_xxx">FT_LOAD_NO_AUTOHINT</a></code> to really disable hinting; however, you probably never want this except for demonstration purposes.</p>
1724 <p>Currently, there are about a dozen TrueType fonts in the list of tricky fonts; they are hard-coded in file <code>ttobjs.c</code>.</p>
1725 </td></tr>
1726 <tr><td class="val" id="ft_face_flag_color">FT_FACE_FLAG_COLOR</td><td class="desc">
1727 <p>[Since 2.5.1] The face has color glyph tables. See <code><a href="ft2-glyph_retrieval.html#ft_load_xxx">FT_LOAD_COLOR</a></code> for more information.</p>
1728 </td></tr>
1729 <tr><td class="val" id="ft_face_flag_variation">FT_FACE_FLAG_VARIATION</td><td class="desc">
1730 <p>[Since 2.9] Set if the current face (or named instance) has been altered with <code><a href="ft2-multiple_masters.html#ft_set_mm_design_coordinates">FT_Set_MM_Design_Coordinates</a></code>, <code><a href="ft2-multiple_masters.html#ft_set_var_design_coordinates">FT_Set_Var_Design_Coordinates</a></code>, <code><a href="ft2-multiple_masters.html#ft_set_var_blend_coordinates">FT_Set_Var_Blend_Coordinates</a></code>, or <code><a href="ft2-multiple_masters.html#ft_set_mm_weightvector">FT_Set_MM_WeightVector</a></code> to select a non-default instance.</p>
1731 </td></tr>
1732 <tr><td class="val" id="ft_face_flag_svg">FT_FACE_FLAG_SVG</td><td class="desc">
1733 <p>[Since 2.12] The face has an &lsquo;SVG&nbsp;&rsquo; OpenType table.</p>
1734 </td></tr>
1735 <tr><td class="val" id="ft_face_flag_sbix">FT_FACE_FLAG_SBIX</td><td class="desc">
1736 <p>[Since 2.12] The face has an &lsquo;sbix&rsquo; OpenType table <em>and</em> outlines. For such fonts, <code><a href="ft2-face_creation.html#ft_face_flag_xxx">FT_FACE_FLAG_SCALABLE</a></code> is not set by default to retain backward compatibility.</p>
1737 </td></tr>
1738 <tr><td class="val" id="ft_face_flag_sbix_overlay">FT_FACE_FLAG_SBIX_OVERLAY</td><td class="desc">
1739 <p>[Since 2.12] The face has an &lsquo;sbix&rsquo; OpenType table where outlines should be drawn on top of bitmap strikes.</p>
1740 </td></tr>
1741 </table>
1742
1743 <hr>
1744
1745 <h2 id="ft_style_flag_xxx">FT_STYLE_FLAG_XXX<a class="headerlink" href="#ft_style_flag_xxx" title="Permanent link">&para;</a></h2>
1746 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1747 <div class = "codehilite"><pre><code>#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_style_flag_italic">FT_STYLE_FLAG_ITALIC</a>  ( 1 &lt;&lt; 0 )
1748 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_style_flag_bold">FT_STYLE_FLAG_BOLD</a>    ( 1 &lt;&lt; 1 )
1749 </code></pre></div>
1750
1751 <p>A list of bit flags to indicate the style of a given face. These are used in the <code>style_flags</code> field of <code><a href="ft2-face_creation.html#ft_facerec">FT_FaceRec</a></code>.</p>
1752 <h4>values</h4>
1753 <table class="fields">
1754 <tr><td class="val" id="ft_style_flag_italic">FT_STYLE_FLAG_ITALIC</td><td class="desc">
1755 <p>The face style is italic or oblique.</p>
1756 </td></tr>
1757 <tr><td class="val" id="ft_style_flag_bold">FT_STYLE_FLAG_BOLD</td><td class="desc">
1758 <p>The face is bold.</p>
1759 </td></tr>
1760 </table>
1761
1762 <h4>note</h4>
1763
1764 <p>The style information as provided by FreeType is very basic. More details are beyond the scope and should be done on a higher level (for example, by analyzing various fields of the &lsquo;OS/2&rsquo; table in SFNT based fonts).</p>
1765 <hr>
1766
1767 <h2 id="ft_new_face">FT_New_Face<a class="headerlink" href="#ft_new_face" title="Permanent link">&para;</a></h2>
1768 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1769 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
1770   <b>FT_New_Face</b>( <a href="ft2-library_setup.html#ft_library">FT_Library</a>   library,
1771                <span class="keyword">const</span> <span class="keyword">char</span>*  filepathname,
1772                <a href="ft2-basic_types.html#ft_long">FT_Long</a>      face_index,
1773                <a href="ft2-face_creation.html#ft_face">FT_Face</a>     *aface );
1774 </code></pre></div>
1775
1776 <p>Call <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> to open a font by its pathname.</p>
1777 <h4>inout</h4>
1778 <table class="fields">
1779 <tr><td class="val" id="library">library</td><td class="desc">
1780 <p>A handle to the library resource.</p>
1781 </td></tr>
1782 </table>
1783
1784 <h4>input</h4>
1785 <table class="fields">
1786 <tr><td class="val" id="pathname">pathname</td><td class="desc">
1787 <p>A path to the font file.</p>
1788 </td></tr>
1789 <tr><td class="val" id="face_index">face_index</td><td class="desc">
1790 <p>See <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> for a detailed description of this parameter.</p>
1791 </td></tr>
1792 </table>
1793
1794 <h4>output</h4>
1795 <table class="fields">
1796 <tr><td class="val" id="aface">aface</td><td class="desc">
1797 <p>A handle to a new face object. If <code>face_index</code> is greater than or equal to zero, it must be non-<code>NULL</code>.</p>
1798 </td></tr>
1799 </table>
1800
1801 <h4>return</h4>
1802
1803 <p>FreeType error code. 0&nbsp;means success.</p>
1804 <h4>note</h4>
1805
1806 <p>The <code>pathname</code> string should be recognizable as such by a standard <code>fopen</code> call on your system; in particular, this means that <code>pathname</code> must not contain null bytes. If that is not sufficient to address all file name possibilities (for example, to handle wide character file names on Windows in UTF-16 encoding) you might use <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> to pass a memory array or a stream object instead.</p>
1807 <p>Use <code><a href="ft2-face_creation.html#ft_done_face">FT_Done_Face</a></code> to destroy the created <code><a href="ft2-face_creation.html#ft_face">FT_Face</a></code> object (along with its slot and sizes).</p>
1808 <hr>
1809
1810 <h2 id="ft_done_face">FT_Done_Face<a class="headerlink" href="#ft_done_face" title="Permanent link">&para;</a></h2>
1811 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1812 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
1813   <b>FT_Done_Face</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>  face );
1814 </code></pre></div>
1815
1816 <p>Discard a given face object, as well as all of its child slots and sizes.</p>
1817 <h4>input</h4>
1818 <table class="fields">
1819 <tr><td class="val" id="face">face</td><td class="desc">
1820 <p>A handle to a target face object.</p>
1821 </td></tr>
1822 </table>
1823
1824 <h4>return</h4>
1825
1826 <p>FreeType error code. 0&nbsp;means success.</p>
1827 <h4>note</h4>
1828
1829 <p>See the discussion of reference counters in the description of <code><a href="ft2-face_creation.html#ft_reference_face">FT_Reference_Face</a></code>.</p>
1830 <hr>
1831
1832 <h2 id="ft_reference_face">FT_Reference_Face<a class="headerlink" href="#ft_reference_face" title="Permanent link">&para;</a></h2>
1833 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1834 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
1835   <b>FT_Reference_Face</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>  face );
1836 </code></pre></div>
1837
1838 <p>A counter gets initialized to&nbsp;1 at the time an <code><a href="ft2-face_creation.html#ft_face">FT_Face</a></code> structure is created. This function increments the counter. <code><a href="ft2-face_creation.html#ft_done_face">FT_Done_Face</a></code> then only destroys a face if the counter is&nbsp;1, otherwise it simply decrements the counter.</p>
1839 <p>This function helps in managing life-cycles of structures that reference <code><a href="ft2-face_creation.html#ft_face">FT_Face</a></code> objects.</p>
1840 <h4>input</h4>
1841 <table class="fields">
1842 <tr><td class="val" id="face">face</td><td class="desc">
1843 <p>A handle to a target face object.</p>
1844 </td></tr>
1845 </table>
1846
1847 <h4>return</h4>
1848
1849 <p>FreeType error code. 0&nbsp;means success.</p>
1850 <h4>since</h4>
1851
1852 <p>2.4.2</p>
1853 <hr>
1854
1855 <h2 id="ft_new_memory_face">FT_New_Memory_Face<a class="headerlink" href="#ft_new_memory_face" title="Permanent link">&para;</a></h2>
1856 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1857 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
1858   <b>FT_New_Memory_Face</b>( <a href="ft2-library_setup.html#ft_library">FT_Library</a>      library,
1859                       <span class="keyword">const</span> <a href="ft2-basic_types.html#ft_byte">FT_Byte</a>*  file_base,
1860                       <a href="ft2-basic_types.html#ft_long">FT_Long</a>         file_size,
1861                       <a href="ft2-basic_types.html#ft_long">FT_Long</a>         face_index,
1862                       <a href="ft2-face_creation.html#ft_face">FT_Face</a>        *aface );
1863 </code></pre></div>
1864
1865 <p>Call <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> to open a font that has been loaded into memory.</p>
1866 <h4>inout</h4>
1867 <table class="fields">
1868 <tr><td class="val" id="library">library</td><td class="desc">
1869 <p>A handle to the library resource.</p>
1870 </td></tr>
1871 </table>
1872
1873 <h4>input</h4>
1874 <table class="fields">
1875 <tr><td class="val" id="file_base">file_base</td><td class="desc">
1876 <p>A pointer to the beginning of the font data.</p>
1877 </td></tr>
1878 <tr><td class="val" id="file_size">file_size</td><td class="desc">
1879 <p>The size of the memory chunk used by the font data.</p>
1880 </td></tr>
1881 <tr><td class="val" id="face_index">face_index</td><td class="desc">
1882 <p>See <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> for a detailed description of this parameter.</p>
1883 </td></tr>
1884 </table>
1885
1886 <h4>output</h4>
1887 <table class="fields">
1888 <tr><td class="val" id="aface">aface</td><td class="desc">
1889 <p>A handle to a new face object. If <code>face_index</code> is greater than or equal to zero, it must be non-<code>NULL</code>.</p>
1890 </td></tr>
1891 </table>
1892
1893 <h4>return</h4>
1894
1895 <p>FreeType error code. 0&nbsp;means success.</p>
1896 <h4>note</h4>
1897
1898 <p>You must not deallocate the memory before calling <code><a href="ft2-face_creation.html#ft_done_face">FT_Done_Face</a></code>.</p>
1899 <hr>
1900
1901 <h2 id="ft_face_properties">FT_Face_Properties<a class="headerlink" href="#ft_face_properties" title="Permanent link">&para;</a></h2>
1902 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1903 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
1904   <b>FT_Face_Properties</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>        face,
1905                       <a href="ft2-basic_types.html#ft_uint">FT_UInt</a>        num_properties,
1906                       <a href="ft2-face_creation.html#ft_parameter">FT_Parameter</a>*  properties );
1907 </code></pre></div>
1908
1909 <p>Set or override certain (library or module-wide) properties on a face-by-face basis. Useful for finer-grained control and avoiding locks on shared structures (threads can modify their own faces as they see fit).</p>
1910 <p>Contrary to <code><a href="ft2-module_management.html#ft_property_set">FT_Property_Set</a></code>, this function uses <code><a href="ft2-face_creation.html#ft_parameter">FT_Parameter</a></code> so that you can pass multiple properties to the target face in one call. Note that only a subset of the available properties can be controlled.</p>
1911 <ul>
1912 <li>
1913 <p><code><a href="ft2-parameter_tags.html#ft_param_tag_stem_darkening">FT_PARAM_TAG_STEM_DARKENING</a></code> (stem darkening, corresponding to the property <code>no-stem-darkening</code> provided by the &lsquo;autofit&rsquo;, &lsquo;cff&rsquo;, &lsquo;type1&rsquo;, and &lsquo;t1cid&rsquo; modules; see <code><a href="ft2-properties.html#no-stem-darkening">no-stem-darkening</a></code>).</p>
1914 </li>
1915 <li>
1916 <p><code><a href="ft2-parameter_tags.html#ft_param_tag_lcd_filter_weights">FT_PARAM_TAG_LCD_FILTER_WEIGHTS</a></code> (LCD filter weights, corresponding to function <code><a href="ft2-lcd_rendering.html#ft_library_setlcdfilterweights">FT_Library_SetLcdFilterWeights</a></code>).</p>
1917 </li>
1918 <li>
1919 <p><code><a href="ft2-parameter_tags.html#ft_param_tag_random_seed">FT_PARAM_TAG_RANDOM_SEED</a></code> (seed value for the CFF, Type&nbsp;1, and CID &lsquo;random&rsquo; operator, corresponding to the <code>random-seed</code> property provided by the &lsquo;cff&rsquo;, &lsquo;type1&rsquo;, and &lsquo;t1cid&rsquo; modules; see <code><a href="ft2-properties.html#random-seed">random-seed</a></code>).</p>
1920 </li>
1921 </ul>
1922 <p>Pass <code>NULL</code> as <code>data</code> in <code><a href="ft2-face_creation.html#ft_parameter">FT_Parameter</a></code> for a given tag to reset the option and use the library or module default again.</p>
1923 <h4>input</h4>
1924 <table class="fields">
1925 <tr><td class="val" id="face">face</td><td class="desc">
1926 <p>A handle to the source face object.</p>
1927 </td></tr>
1928 <tr><td class="val" id="num_properties">num_properties</td><td class="desc">
1929 <p>The number of properties that follow.</p>
1930 </td></tr>
1931 <tr><td class="val" id="properties">properties</td><td class="desc">
1932 <p>A handle to an <code><a href="ft2-face_creation.html#ft_parameter">FT_Parameter</a></code> array with <code>num_properties</code> elements.</p>
1933 </td></tr>
1934 </table>
1935
1936 <h4>return</h4>
1937
1938 <p>FreeType error code. 0&nbsp;means success.</p>
1939 <h4>example</h4>
1940
1941 <p>Here is an example that sets three properties. You must define <code>FT_CONFIG_OPTION_SUBPIXEL_RENDERING</code> to make the LCD filter examples work.
1942 <div class="highlight"><pre><span></span><code>  FT_Parameter         property1;
1943   FT_Bool              darken_stems = 1;
1944
1945   FT_Parameter         property2;
1946   FT_LcdFiveTapFilter  custom_weight =
1947                          { 0x11, 0x44, 0x56, 0x44, 0x11 };
1948
1949   FT_Parameter         property3;
1950   FT_Int32             random_seed = 314159265;
1951
1952   FT_Parameter         properties[3] = { property1,
1953                                          property2,
1954                                          property3 };
1955
1956
1957   property1.tag  = FT_PARAM_TAG_STEM_DARKENING;
1958   property1.data = &amp;darken_stems;
1959
1960   property2.tag  = FT_PARAM_TAG_LCD_FILTER_WEIGHTS;
1961   property2.data = custom_weight;
1962
1963   property3.tag  = FT_PARAM_TAG_RANDOM_SEED;
1964   property3.data = &amp;random_seed;
1965
1966   FT_Face_Properties( face, 3, properties );
1967 </code></pre></div></p>
1968 <p>The next example resets a single property to its default value.
1969 <div class="highlight"><pre><span></span><code>  FT_Parameter  property;
1970
1971
1972   property.tag  = FT_PARAM_TAG_LCD_FILTER_WEIGHTS;
1973   property.data = NULL;
1974
1975   FT_Face_Properties( face, 1, &amp;property );
1976 </code></pre></div></p>
1977 <h4>since</h4>
1978
1979 <p>2.8</p>
1980 <hr>
1981
1982 <h2 id="ft_open_face">FT_Open_Face<a class="headerlink" href="#ft_open_face" title="Permanent link">&para;</a></h2>
1983 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
1984 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
1985   <b>FT_Open_Face</b>( <a href="ft2-library_setup.html#ft_library">FT_Library</a>           library,
1986                 <span class="keyword">const</span> <a href="ft2-face_creation.html#ft_open_args">FT_Open_Args</a>*  args,
1987                 <a href="ft2-basic_types.html#ft_long">FT_Long</a>              face_index,
1988                 <a href="ft2-face_creation.html#ft_face">FT_Face</a>             *aface );
1989 </code></pre></div>
1990
1991 <p>Create a face object from a given resource described by <code><a href="ft2-face_creation.html#ft_open_args">FT_Open_Args</a></code>.</p>
1992 <h4>inout</h4>
1993 <table class="fields">
1994 <tr><td class="val" id="library">library</td><td class="desc">
1995 <p>A handle to the library resource.</p>
1996 </td></tr>
1997 </table>
1998
1999 <h4>input</h4>
2000 <table class="fields">
2001 <tr><td class="val" id="args">args</td><td class="desc">
2002 <p>A pointer to an <code>FT_Open_Args</code> structure that must be filled by the caller.</p>
2003 </td></tr>
2004 <tr><td class="val" id="face_index">face_index</td><td class="desc">
2005 <p>This field holds two different values. Bits 0-15 are the index of the face in the font file (starting with value&nbsp;0). Set it to&nbsp;0 if there is only one face in the font file.</p>
2006 <p>[Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation fonts only, specifying the named instance index for the current face index (starting with value&nbsp;1; value&nbsp;0 makes FreeType ignore named instances). For non-variation fonts, bits 16-30 are ignored. Assuming that you want to access the third named instance in face&nbsp;4, <code>face_index</code> should be set to 0x00030004. If you want to access face&nbsp;4 without variation handling, simply set <code>face_index</code> to value&nbsp;4.</p>
2007 <p><code>FT_Open_Face</code> and its siblings can be used to quickly check whether the font format of a given font resource is supported by FreeType. In general, if the <code>face_index</code> argument is negative, the function's return value is&nbsp;0 if the font format is recognized, or non-zero otherwise. The function allocates a more or less empty face handle in <code>*aface</code> (if <code>aface</code> isn't <code>NULL</code>); the only two useful fields in this special case are <code>face-&gt;num_faces</code> and <code>face-&gt;style_flags</code>. For any negative value of <code>face_index</code>, <code>face-&gt;num_faces</code> gives the number of faces within the font file. For the negative value &lsquo;-(N+1)&rsquo; (with &lsquo;N&rsquo; a non-negative 16-bit value), bits 16-30 in <code>face-&gt;style_flags</code> give the number of named instances in face &lsquo;N&rsquo; if we have a variation font (or zero otherwise). After examination, the returned <code><a href="ft2-face_creation.html#ft_face">FT_Face</a></code> structure should be deallocated with a call to <code><a href="ft2-face_creation.html#ft_done_face">FT_Done_Face</a></code>.</p>
2008 </td></tr>
2009 </table>
2010
2011 <h4>output</h4>
2012 <table class="fields">
2013 <tr><td class="val" id="aface">aface</td><td class="desc">
2014 <p>A handle to a new face object. If <code>face_index</code> is greater than or equal to zero, it must be non-<code>NULL</code>.</p>
2015 </td></tr>
2016 </table>
2017
2018 <h4>return</h4>
2019
2020 <p>FreeType error code. 0&nbsp;means success.</p>
2021 <h4>note</h4>
2022
2023 <p>Unlike FreeType 1.x, this function automatically creates a glyph slot for the face object that can be accessed directly through <code>face-&gt;glyph</code>.</p>
2024 <p>Each new face object created with this function also owns a default <code><a href="ft2-sizing_and_scaling.html#ft_size">FT_Size</a></code> object, accessible as <code>face-&gt;size</code>.</p>
2025 <p>One <code><a href="ft2-library_setup.html#ft_library">FT_Library</a></code> instance can have multiple face objects, that is, <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> and its siblings can be called multiple times using the same <code>library</code> argument.</p>
2026 <p>See the discussion of reference counters in the description of <code><a href="ft2-face_creation.html#ft_reference_face">FT_Reference_Face</a></code>.</p>
2027 <p>If <code>FT_OPEN_STREAM</code> is set in <code>args-&gt;flags</code>, the stream in <code>args-&gt;stream</code> is automatically closed before this function returns any error (including <code>FT_Err_Invalid_Argument</code>).</p>
2028 <h4>example</h4>
2029
2030 <p>To loop over all faces, use code similar to the following snippet (omitting the error handling).
2031 <div class="highlight"><pre><span></span><code>  ...
2032   FT_Face  face;
2033   FT_Long  i, num_faces;
2034
2035
2036   error = FT_Open_Face( library, args, -1, &amp;face );
2037   if ( error ) { ... }
2038
2039   num_faces = face-&gt;num_faces;
2040   FT_Done_Face( face );
2041
2042   for ( i = 0; i &lt; num_faces; i++ )
2043   {
2044     ...
2045     error = FT_Open_Face( library, args, i, &amp;face );
2046     ...
2047     FT_Done_Face( face );
2048     ...
2049   }
2050 </code></pre></div></p>
2051 <p>To loop over all valid values for <code>face_index</code>, use something similar to the following snippet, again without error handling. The code accesses all faces immediately (thus only a single call of <code>FT_Open_Face</code> within the do-loop), with and without named instances.
2052 <div class="highlight"><pre><span></span><code>  ...
2053   FT_Face  face;
2054
2055   FT_Long  num_faces     = 0;
2056   FT_Long  num_instances = 0;
2057
2058   FT_Long  face_idx     = 0;
2059   FT_Long  instance_idx = 0;
2060
2061
2062   do
2063   {
2064     FT_Long  id = ( instance_idx &lt;&lt; 16 ) + face_idx;
2065
2066
2067     error = FT_Open_Face( library, args, id, &amp;face );
2068     if ( error ) { ... }
2069
2070     num_faces     = face-&gt;num_faces;
2071     num_instances = face-&gt;style_flags &gt;&gt; 16;
2072
2073     ...
2074
2075     FT_Done_Face( face );
2076
2077     if ( instance_idx &lt; num_instances )
2078       instance_idx++;
2079     else
2080     {
2081       face_idx++;
2082       instance_idx = 0;
2083     }
2084
2085   } while ( face_idx &lt; num_faces )
2086 </code></pre></div></p>
2087 <hr>
2088
2089 <h2 id="ft_open_args">FT_Open_Args<a class="headerlink" href="#ft_open_args" title="Permanent link">&para;</a></h2>
2090 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
2091 <div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span>  FT_Open_Args_
2092   {
2093     <a href="ft2-basic_types.html#ft_uint">FT_UInt</a>         flags;
2094     <span class="keyword">const</span> <a href="ft2-basic_types.html#ft_byte">FT_Byte</a>*  memory_base;
2095     <a href="ft2-basic_types.html#ft_long">FT_Long</a>         memory_size;
2096     <a href="ft2-basic_types.html#ft_string">FT_String</a>*      pathname;
2097     <a href="ft2-system_interface.html#ft_stream">FT_Stream</a>       stream;
2098     <a href="ft2-module_management.html#ft_module">FT_Module</a>       driver;
2099     <a href="ft2-basic_types.html#ft_int">FT_Int</a>          num_params;
2100     <a href="ft2-face_creation.html#ft_parameter">FT_Parameter</a>*   params;
2101
2102   } <b>FT_Open_Args</b>;
2103 </code></pre></div>
2104
2105 <p>A structure to indicate how to open a new font file or stream. A pointer to such a structure can be used as a parameter for the functions <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> and <code><a href="ft2-face_creation.html#ft_attach_stream">FT_Attach_Stream</a></code>.</p>
2106 <h4>fields</h4>
2107 <table class="fields">
2108 <tr><td class="val" id="flags">flags</td><td class="desc">
2109 <p>A set of bit flags indicating how to use the structure.</p>
2110 </td></tr>
2111 <tr><td class="val" id="memory_base">memory_base</td><td class="desc">
2112 <p>The first byte of the file in memory.</p>
2113 </td></tr>
2114 <tr><td class="val" id="memory_size">memory_size</td><td class="desc">
2115 <p>The size in bytes of the file in memory.</p>
2116 </td></tr>
2117 <tr><td class="val" id="pathname">pathname</td><td class="desc">
2118 <p>A pointer to an 8-bit file pathname, which must be a C&nbsp;string (i.e., no null bytes except at the very end). The pointer is not owned by FreeType.</p>
2119 </td></tr>
2120 <tr><td class="val" id="stream">stream</td><td class="desc">
2121 <p>A handle to a source stream object.</p>
2122 </td></tr>
2123 <tr><td class="val" id="driver">driver</td><td class="desc">
2124 <p>This field is exclusively used by <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code>; it simply specifies the font driver to use for opening the face. If set to <code>NULL</code>, FreeType tries to load the face with each one of the drivers in its list.</p>
2125 </td></tr>
2126 <tr><td class="val" id="num_params">num_params</td><td class="desc">
2127 <p>The number of extra parameters.</p>
2128 </td></tr>
2129 <tr><td class="val" id="params">params</td><td class="desc">
2130 <p>Extra parameters passed to the font driver when opening a new face.</p>
2131 </td></tr>
2132 </table>
2133
2134 <h4>note</h4>
2135
2136 <p>The stream type is determined by the contents of <code>flags</code>:</p>
2137 <p>If the <code><a href="ft2-face_creation.html#ft_open_xxx">FT_OPEN_MEMORY</a></code> bit is set, assume that this is a memory file of <code>memory_size</code> bytes, located at <code>memory_address</code>. The data are not copied, and the client is responsible for releasing and destroying them <em>after</em> the corresponding call to <code><a href="ft2-face_creation.html#ft_done_face">FT_Done_Face</a></code>.</p>
2138 <p>Otherwise, if the <code><a href="ft2-face_creation.html#ft_open_xxx">FT_OPEN_STREAM</a></code> bit is set, assume that a custom input stream <code>stream</code> is used.</p>
2139 <p>Otherwise, if the <code><a href="ft2-face_creation.html#ft_open_xxx">FT_OPEN_PATHNAME</a></code> bit is set, assume that this is a normal file and use <code>pathname</code> to open it.</p>
2140 <p>If none of the above bits are set or if multiple are set at the same time, the flags are invalid and <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> fails.</p>
2141 <p>If the <code><a href="ft2-face_creation.html#ft_open_xxx">FT_OPEN_DRIVER</a></code> bit is set, <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> only tries to open the file with the driver whose handler is in <code>driver</code>.</p>
2142 <p>If the <code><a href="ft2-face_creation.html#ft_open_xxx">FT_OPEN_PARAMS</a></code> bit is set, the parameters given by <code>num_params</code> and <code>params</code> is used. They are ignored otherwise.</p>
2143 <p>Ideally, both the <code>pathname</code> and <code>params</code> fields should be tagged as &lsquo;const&rsquo;; this is missing for API backward compatibility. In other words, applications should treat them as read-only.</p>
2144 <hr>
2145
2146 <h2 id="ft_open_xxx">FT_OPEN_XXX<a class="headerlink" href="#ft_open_xxx" title="Permanent link">&para;</a></h2>
2147 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
2148 <div class = "codehilite"><pre><code>#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_memory">FT_OPEN_MEMORY</a>    0x1
2149 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_stream">FT_OPEN_STREAM</a>    0x2
2150 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_pathname">FT_OPEN_PATHNAME</a>  0x4
2151 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_driver">FT_OPEN_DRIVER</a>    0x8
2152 #<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_params">FT_OPEN_PARAMS</a>    0x10
2153
2154
2155   /* these constants are deprecated; use the corresponding `<b>FT_OPEN_XXX</b>` */
2156   /* values instead                                                      */
2157 #<span class="keyword">define</span> ft_open_memory    <a href="ft2-face_creation.html#ft_open_memory">FT_OPEN_MEMORY</a>
2158 #<span class="keyword">define</span> ft_open_stream    <a href="ft2-face_creation.html#ft_open_stream">FT_OPEN_STREAM</a>
2159 #<span class="keyword">define</span> ft_open_pathname  <a href="ft2-face_creation.html#ft_open_pathname">FT_OPEN_PATHNAME</a>
2160 #<span class="keyword">define</span> ft_open_driver    <a href="ft2-face_creation.html#ft_open_driver">FT_OPEN_DRIVER</a>
2161 #<span class="keyword">define</span> ft_open_params    <a href="ft2-face_creation.html#ft_open_params">FT_OPEN_PARAMS</a>
2162 </code></pre></div>
2163
2164 <p>A list of bit field constants used within the <code>flags</code> field of the <code><a href="ft2-face_creation.html#ft_open_args">FT_Open_Args</a></code> structure.</p>
2165 <h4>values</h4>
2166 <table class="fields">
2167 <tr><td class="val" id="ft_open_memory">FT_OPEN_MEMORY</td><td class="desc">
2168 <p>This is a memory-based stream.</p>
2169 </td></tr>
2170 <tr><td class="val" id="ft_open_stream">FT_OPEN_STREAM</td><td class="desc">
2171 <p>Copy the stream from the <code>stream</code> field.</p>
2172 </td></tr>
2173 <tr><td class="val" id="ft_open_pathname">FT_OPEN_PATHNAME</td><td class="desc">
2174 <p>Create a new input stream from a C&nbsp;path name.</p>
2175 </td></tr>
2176 <tr><td class="val" id="ft_open_driver">FT_OPEN_DRIVER</td><td class="desc">
2177 <p>Use the <code>driver</code> field.</p>
2178 </td></tr>
2179 <tr><td class="val" id="ft_open_params">FT_OPEN_PARAMS</td><td class="desc">
2180 <p>Use the <code>num_params</code> and <code>params</code> fields.</p>
2181 </td></tr>
2182 </table>
2183
2184 <h4>note</h4>
2185
2186 <p>The <code>FT_OPEN_MEMORY</code>, <code>FT_OPEN_STREAM</code>, and <code>FT_OPEN_PATHNAME</code> flags are mutually exclusive.</p>
2187 <hr>
2188
2189 <h2 id="ft_parameter">FT_Parameter<a class="headerlink" href="#ft_parameter" title="Permanent link">&para;</a></h2>
2190 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
2191 <div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span>  FT_Parameter_
2192   {
2193     <a href="ft2-basic_types.html#ft_ulong">FT_ULong</a>    tag;
2194     <a href="ft2-basic_types.html#ft_pointer">FT_Pointer</a>  data;
2195
2196   } <b>FT_Parameter</b>;
2197 </code></pre></div>
2198
2199 <p>A simple structure to pass more or less generic parameters to <code><a href="ft2-face_creation.html#ft_open_face">FT_Open_Face</a></code> and <code><a href="ft2-face_creation.html#ft_face_properties">FT_Face_Properties</a></code>.</p>
2200 <h4>fields</h4>
2201 <table class="fields">
2202 <tr><td class="val" id="tag">tag</td><td class="desc">
2203 <p>A four-byte identification tag.</p>
2204 </td></tr>
2205 <tr><td class="val" id="data">data</td><td class="desc">
2206 <p>A pointer to the parameter data.</p>
2207 </td></tr>
2208 </table>
2209
2210 <h4>note</h4>
2211
2212 <p>The ID and function of parameters are driver-specific. See section &lsquo;<a href="ft2-parameter_tags.html#parameter_tags">Parameter Tags</a>&rsquo; for more information.</p>
2213 <hr>
2214
2215 <h2 id="ft_attach_file">FT_Attach_File<a class="headerlink" href="#ft_attach_file" title="Permanent link">&para;</a></h2>
2216 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
2217 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
2218   <b>FT_Attach_File</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>      face,
2219                   <span class="keyword">const</span> <span class="keyword">char</span>*  filepathname );
2220 </code></pre></div>
2221
2222 <p>Call <code><a href="ft2-face_creation.html#ft_attach_stream">FT_Attach_Stream</a></code> to attach a file.</p>
2223 <h4>inout</h4>
2224 <table class="fields">
2225 <tr><td class="val" id="face">face</td><td class="desc">
2226 <p>The target face object.</p>
2227 </td></tr>
2228 </table>
2229
2230 <h4>input</h4>
2231 <table class="fields">
2232 <tr><td class="val" id="filepathname">filepathname</td><td class="desc">
2233 <p>The pathname.</p>
2234 </td></tr>
2235 </table>
2236
2237 <h4>return</h4>
2238
2239 <p>FreeType error code. 0&nbsp;means success.</p>
2240 <hr>
2241
2242 <h2 id="ft_attach_stream">FT_Attach_Stream<a class="headerlink" href="#ft_attach_stream" title="Permanent link">&para;</a></h2>
2243 <p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
2244 <div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
2245   <b>FT_Attach_Stream</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>              face,
2246                     <span class="keyword">const</span> <a href="ft2-face_creation.html#ft_open_args">FT_Open_Args</a>*  parameters );
2247 </code></pre></div>
2248
2249 <p>&lsquo;Attach&rsquo; data to a face object. Normally, this is used to read additional information for the face object. For example, you can attach an AFM file that comes with a Type&nbsp;1 font to get the kerning values and other metrics.</p>
2250 <h4>inout</h4>
2251 <table class="fields">
2252 <tr><td class="val" id="face">face</td><td class="desc">
2253 <p>The target face object.</p>
2254 </td></tr>
2255 </table>
2256
2257 <h4>input</h4>
2258 <table class="fields">
2259 <tr><td class="val" id="parameters">parameters</td><td class="desc">
2260 <p>A pointer to <code><a href="ft2-face_creation.html#ft_open_args">FT_Open_Args</a></code> that must be filled by the caller.</p>
2261 </td></tr>
2262 </table>
2263
2264 <h4>return</h4>
2265
2266 <p>FreeType error code. 0&nbsp;means success.</p>
2267 <h4>note</h4>
2268
2269 <p>The meaning of the &lsquo;attach&rsquo; (i.e., what really happens when the new file is read) is not fixed by FreeType itself. It really depends on the font format (and thus the font driver).</p>
2270 <p>Client applications are expected to know what they are doing when invoking this function. Most drivers simply do not implement file or stream attachments.</p>
2271 <hr>
2272
2273
2274
2275
2276
2277
2278
2279             </article>
2280           </div>
2281         </div>
2282
2283       </main>
2284
2285
2286 <footer class="md-footer">
2287
2288     <nav class="md-footer__inner md-grid" aria-label="Footer">
2289
2290
2291         <a href="ft2-library_setup.html" class="md-footer__link md-footer__link--prev" aria-label="Previous: Library Setup" rel="prev">
2292           <div class="md-footer__button md-icon">
2293             <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
2294           </div>
2295           <div class="md-footer__title">
2296             <div class="md-ellipsis">
2297               <span class="md-footer__direction">
2298                 Previous
2299               </span>
2300               Library Setup
2301             </div>
2302           </div>
2303         </a>
2304
2305
2306
2307         <a href="ft2-font_testing_macros.html" class="md-footer__link md-footer__link--next" aria-label="Next: Font Testing Macros" rel="next">
2308           <div class="md-footer__title">
2309             <div class="md-ellipsis">
2310               <span class="md-footer__direction">
2311                 Next
2312               </span>
2313               Font Testing Macros
2314             </div>
2315           </div>
2316           <div class="md-footer__button md-icon">
2317             <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg>
2318           </div>
2319         </a>
2320
2321     </nav>
2322
2323   <div class="md-footer-meta md-typeset">
2324     <div class="md-footer-meta__inner md-grid">
2325       <div class="md-footer-copyright">
2326
2327           <div class="md-footer-copyright__highlight">
2328             Copyright 2023 <a href = "https://www.freetype.org/license.html">The FreeType Project</a>.
2329           </div>
2330
2331         Made with
2332         <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
2333           Material for MkDocs
2334         </a>
2335
2336       </div>
2337
2338     </div>
2339   </div>
2340 </footer>
2341
2342     </div>
2343     <div class="md-dialog" data-md-component="dialog">
2344       <div class="md-dialog__inner md-typeset"></div>
2345     </div>
2346     <script id="__config" type="application/json">{"base": ".", "features": [], "search": "assets/javascripts/workers/search.477d984a.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version.title": "Select version"}, "version": null}</script>
2347
2348
2349       <script src="assets/javascripts/bundle.82b56eb2.min.js"></script>
2350
2351         <script src="javascripts/extra.js"></script>
2352
2353
2354   </body>
2355 </html>