
<!doctype html>
<html lang="en" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      
        <meta name="description" content="API Reference Documentation for FreeType-2.13.1">
      
      
      
        <meta name="author" content="FreeType Contributors">
      
      
      <link rel="icon" href="images/favico.ico">
      <meta name="generator" content="mkdocs-1.4.3, mkdocs-material-7.1.9">
    
    
      
        <title>Face Creation - FreeType-2.13.1 API Reference</title>
      
    
    
      <link rel="stylesheet" href="assets/stylesheets/main.ca7ac06f.min.css">
      
        
        <link rel="stylesheet" href="assets/stylesheets/palette.f1a3b89f.min.css">
        
          
          
          <meta name="theme-color" content="#4cae4f">
        
      
    
    
    
      
        
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Noto+Serif:300,400,400i,700%7CRoboto+Mono&display=fallback">
        <style>:root{--md-text-font-family:"Noto Serif";--md-code-font-family:"Roboto Mono"}</style>
      
    
    
    
      <link rel="stylesheet" href="stylesheets/extra.css">
    
    
      


    
    
  </head>
  
  
    
    
    
    
    
    <body dir="ltr" data-md-color-scheme="" data-md-color-primary="green" data-md-color-accent="green">
  
    
    <script>function __prefix(e){return new URL(".",location).pathname+"."+e}function __get(e,t=localStorage){return JSON.parse(t.getItem(__prefix(e)))}</script>
    
    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
    <label class="md-overlay" for="__drawer"></label>
    <div data-md-component="skip">
      
        
        <a href="#face-creation" class="md-skip">
          Skip to content
        </a>
      
    </div>
    <div data-md-component="announce">
      
    </div>
    
      <header class="md-header" data-md-component="header">
  <nav class="md-header__inner md-grid" aria-label="Header">
    <a href="index.html" title="FreeType-2.13.1 API Reference" class="md-header__button md-logo" aria-label="FreeType-2.13.1 API Reference" data-md-component="logo">
      
  <img src="images/favico.ico" alt="logo">

    </a>
    <label class="md-header__button md-icon" for="__drawer">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
    </label>
    <div class="md-header__title" data-md-component="header-title">
      <div class="md-header__ellipsis">
        <div class="md-header__topic">
          <span class="md-ellipsis">
            FreeType-2.13.1 API Reference
          </span>
        </div>
        <div class="md-header__topic" data-md-component="header-topic">
          <span class="md-ellipsis">
            
              Face Creation
            
          </span>
        </div>
      </div>
    </div>
    
    
    
      <label class="md-header__button md-icon" for="__search">
        <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>
      </label>
      
<div class="md-search" data-md-component="search" role="dialog">
  <label class="md-search__overlay" for="__search"></label>
  <div class="md-search__inner" role="search">
    <form class="md-search__form" name="search">
      <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>
      <label class="md-search__icon md-icon" for="__search">
        <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>
        <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>
      </label>
      <button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1">
        <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>
      </button>
    </form>
    <div class="md-search__output">
      <div class="md-search__scrollwrap" data-md-scrollfix>
        <div class="md-search-result" data-md-component="search-result">
          <div class="md-search-result__meta">
            Initializing search
          </div>
          <ol class="md-search-result__list"></ol>
        </div>
      </div>
    </div>
  </div>
</div>
    
    
  </nav>
</header>
    
    <div class="md-container" data-md-component="container">
      
      
        
      
      <main class="md-main" data-md-component="main">
        <div class="md-main__inner md-grid">
          
            
              
              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    


<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
  <label class="md-nav__title" for="__drawer">
    <a href="index.html" title="FreeType-2.13.1 API Reference" class="md-nav__button md-logo" aria-label="FreeType-2.13.1 API Reference" data-md-component="logo">
      
  <img src="images/favico.ico" alt="logo">

    </a>
    FreeType-2.13.1 API Reference
  </label>
  
  <ul class="md-nav__list" data-md-scrollfix>
    
      
      
      

  
  
  
    <li class="md-nav__item">
      <a href="index.html" class="md-nav__link">
        TOC
      </a>
    </li>
  

    
      
      
      

  
  
  
    <li class="md-nav__item">
      <a href="ft2-index.html" class="md-nav__link">
        Index
      </a>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" >
      
      <label class="md-nav__link" for="__nav_3">
        General Remarks
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="General Remarks" data-md-level="1">
        <label class="md-nav__title" for="__nav_3">
          <span class="md-nav__icon md-icon"></span>
          General Remarks
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-preamble.html" class="md-nav__link">
        Preamble
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-header_inclusion.html" class="md-nav__link">
        FreeType's header inclusion scheme
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-user_allocation.html" class="md-nav__link">
        User allocation
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
    
  
  
    
    <li class="md-nav__item md-nav__item--active md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" checked>
      
      <label class="md-nav__link" for="__nav_4">
        Core API
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Core API" data-md-level="1">
        <label class="md-nav__title" for="__nav_4">
          <span class="md-nav__icon md-icon"></span>
          Core API
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-basic_types.html" class="md-nav__link">
        Basic Data Types
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-library_setup.html" class="md-nav__link">
        Library Setup
      </a>
    </li>
  

          
            
  
  
    
  
  
    <li class="md-nav__item md-nav__item--active">
      
      <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
      
      
        
      
      
        <label class="md-nav__link md-nav__link--active" for="__toc">
          Face Creation
          <span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="ft2-face_creation.html" class="md-nav__link md-nav__link--active">
        Face Creation
      </a>
      
        
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  
  
  
    
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      Table of contents
    </label>
    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#synopsis" class="md-nav__link">
    Synopsis
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_face" class="md-nav__link">
    FT_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_facerec" class="md-nav__link">
    FT_FaceRec
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_face_flag_xxx" class="md-nav__link">
    FT_FACE_FLAG_XXX
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_style_flag_xxx" class="md-nav__link">
    FT_STYLE_FLAG_XXX
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_new_face" class="md-nav__link">
    FT_New_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_done_face" class="md-nav__link">
    FT_Done_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_reference_face" class="md-nav__link">
    FT_Reference_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_new_memory_face" class="md-nav__link">
    FT_New_Memory_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_face_properties" class="md-nav__link">
    FT_Face_Properties
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_open_face" class="md-nav__link">
    FT_Open_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_open_args" class="md-nav__link">
    FT_Open_Args
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_open_xxx" class="md-nav__link">
    FT_OPEN_XXX
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_parameter" class="md-nav__link">
    FT_Parameter
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_attach_file" class="md-nav__link">
    FT_Attach_File
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_attach_stream" class="md-nav__link">
    FT_Attach_Stream
  </a>
  
</li>
      
    </ul>
  
</nav>
      
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-font_testing_macros.html" class="md-nav__link">
        Font Testing Macros
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-sizing_and_scaling.html" class="md-nav__link">
        Sizing and Scaling
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-glyph_retrieval.html" class="md-nav__link">
        Glyph Retrieval
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-character_mapping.html" class="md-nav__link">
        Character Mapping
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-information_retrieval.html" class="md-nav__link">
        Information Retrieval
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-other_api_data.html" class="md-nav__link">
        Other API Data
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
      
      <label class="md-nav__link" for="__nav_5">
        Extended API
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Extended API" data-md-level="1">
        <label class="md-nav__title" for="__nav_5">
          <span class="md-nav__icon md-icon"></span>
          Extended API
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-glyph_variants.html" class="md-nav__link">
        Unicode Variation Sequences
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-color_management.html" class="md-nav__link">
        Glyph Color Management
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-layer_management.html" class="md-nav__link">
        Glyph Layer Management
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-glyph_management.html" class="md-nav__link">
        Glyph Management
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-mac_specific.html" class="md-nav__link">
        Mac Specific Interface
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-sizes_management.html" class="md-nav__link">
        Size Management
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-header_file_macros.html" class="md-nav__link">
        Header File Macros
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" >
      
      <label class="md-nav__link" for="__nav_6">
        Format-Specific API
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Format-Specific API" data-md-level="1">
        <label class="md-nav__title" for="__nav_6">
          <span class="md-nav__icon md-icon"></span>
          Format-Specific API
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-multiple_masters.html" class="md-nav__link">
        Multiple Masters
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-truetype_tables.html" class="md-nav__link">
        TrueType Tables
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-type1_tables.html" class="md-nav__link">
        Type 1 Tables
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-sfnt_names.html" class="md-nav__link">
        SFNT Names
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-bdf_fonts.html" class="md-nav__link">
        BDF and PCF Files
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-cid_fonts.html" class="md-nav__link">
        CID Fonts
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-pfr_fonts.html" class="md-nav__link">
        PFR Fonts
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-winfnt_fonts.html" class="md-nav__link">
        Window FNT Files
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-svg_fonts.html" class="md-nav__link">
        OpenType SVG Fonts
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-font_formats.html" class="md-nav__link">
        Font Formats
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-gasp_table.html" class="md-nav__link">
        Gasp Table
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" >
      
      <label class="md-nav__link" for="__nav_7">
        Controlling FreeType Modules
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Controlling FreeType Modules" data-md-level="1">
        <label class="md-nav__title" for="__nav_7">
          <span class="md-nav__icon md-icon"></span>
          Controlling FreeType Modules
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-auto_hinter.html" class="md-nav__link">
        The auto-hinter
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-cff_driver.html" class="md-nav__link">
        The CFF driver
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-t1_cid_driver.html" class="md-nav__link">
        The Type 1 and CID drivers
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-tt_driver.html" class="md-nav__link">
        The TrueType driver
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-pcf_driver.html" class="md-nav__link">
        The PCF driver
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-ot_svg_driver.html" class="md-nav__link">
        The SVG driver
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-properties.html" class="md-nav__link">
        Driver properties
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-parameter_tags.html" class="md-nav__link">
        Parameter Tags
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-lcd_rendering.html" class="md-nav__link">
        Subpixel Rendering
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_8" type="checkbox" id="__nav_8" >
      
      <label class="md-nav__link" for="__nav_8">
        Cache Sub-System
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Cache Sub-System" data-md-level="1">
        <label class="md-nav__title" for="__nav_8">
          <span class="md-nav__icon md-icon"></span>
          Cache Sub-System
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-cache_subsystem.html" class="md-nav__link">
        Cache Sub-System
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_9" type="checkbox" id="__nav_9" >
      
      <label class="md-nav__link" for="__nav_9">
        Support API
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Support API" data-md-level="1">
        <label class="md-nav__title" for="__nav_9">
          <span class="md-nav__icon md-icon"></span>
          Support API
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-computations.html" class="md-nav__link">
        Computations
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-list_processing.html" class="md-nav__link">
        List Processing
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-outline_processing.html" class="md-nav__link">
        Outline Processing
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-quick_advance.html" class="md-nav__link">
        Quick retrieval of advance values
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-bitmap_handling.html" class="md-nav__link">
        Bitmap Handling
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-raster.html" class="md-nav__link">
        Scanline Converter
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-glyph_stroker.html" class="md-nav__link">
        Glyph Stroker
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-system_interface.html" class="md-nav__link">
        System Interface
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-module_management.html" class="md-nav__link">
        Module Management
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-gzip.html" class="md-nav__link">
        GZIP Streams
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-lzw.html" class="md-nav__link">
        LZW Streams
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-bzip2.html" class="md-nav__link">
        BZIP2 Streams
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-debugging_apis.html" class="md-nav__link">
        External Debugging APIs
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_10" type="checkbox" id="__nav_10" >
      
      <label class="md-nav__link" for="__nav_10">
        Error Codes
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Error Codes" data-md-level="1">
        <label class="md-nav__title" for="__nav_10">
          <span class="md-nav__icon md-icon"></span>
          Error Codes
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-error_enumerations.html" class="md-nav__link">
        Error Enumerations
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-error_code_values.html" class="md-nav__link">
        Error Code Values
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_11" type="checkbox" id="__nav_11" >
      
      <label class="md-nav__link" for="__nav_11">
        Miscellaneous
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Miscellaneous" data-md-level="1">
        <label class="md-nav__title" for="__nav_11">
          <span class="md-nav__icon md-icon"></span>
          Miscellaneous
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-gx_validation.html" class="md-nav__link">
        TrueTypeGX/AAT Validation
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-incremental.html" class="md-nav__link">
        Incremental Loading
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-truetype_engine.html" class="md-nav__link">
        The TrueType Engine
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="ft2-ot_validation.html" class="md-nav__link">
        OpenType Validation
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
  </ul>
</nav>
                  </div>
                </div>
              </div>
            
            
              
              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  
  
  
    
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      Table of contents
    </label>
    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#synopsis" class="md-nav__link">
    Synopsis
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_face" class="md-nav__link">
    FT_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_facerec" class="md-nav__link">
    FT_FaceRec
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_face_flag_xxx" class="md-nav__link">
    FT_FACE_FLAG_XXX
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_style_flag_xxx" class="md-nav__link">
    FT_STYLE_FLAG_XXX
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_new_face" class="md-nav__link">
    FT_New_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_done_face" class="md-nav__link">
    FT_Done_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_reference_face" class="md-nav__link">
    FT_Reference_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_new_memory_face" class="md-nav__link">
    FT_New_Memory_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_face_properties" class="md-nav__link">
    FT_Face_Properties
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_open_face" class="md-nav__link">
    FT_Open_Face
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_open_args" class="md-nav__link">
    FT_Open_Args
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_open_xxx" class="md-nav__link">
    FT_OPEN_XXX
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_parameter" class="md-nav__link">
    FT_Parameter
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_attach_file" class="md-nav__link">
    FT_Attach_File
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ft_attach_stream" class="md-nav__link">
    FT_Attach_Stream
  </a>
  
</li>
      
    </ul>
  
</nav>
                  </div>
                </div>
              </div>
            
          
          <div class="md-content" data-md-component="content">
            <article class="md-content__inner md-typeset">
              
                
                
                <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>
<hr />
<h1 id="face-creation">Face Creation<a class="headerlink" href="#face-creation" title="Permanent link">&para;</a></h1>
<h2 id="synopsis">Synopsis<a class="headerlink" href="#synopsis" title="Permanent link">&para;</a></h2>
<p>The functions and structures collected in this section operate on fonts globally.</p>
<h2 id="ft_face">FT_Face<a class="headerlink" href="#ft_face" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span> FT_FaceRec_*  <b>FT_Face</b>;
</code></pre></div>

<p>A handle to a typographic face object. A face object models a given typeface, in a given style.</p>
<h4>note</h4>

<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>
<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>
<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>
<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>
<h4>also</h4>

<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>
<hr>

<h2 id="ft_facerec">FT_FaceRec<a class="headerlink" href="#ft_facerec" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span>  FT_FaceRec_
  {
    <a href="ft2-basic_types.html#ft_long">FT_Long</a>           num_faces;
    <a href="ft2-basic_types.html#ft_long">FT_Long</a>           face_index;

    <a href="ft2-basic_types.html#ft_long">FT_Long</a>           face_flags;
    <a href="ft2-basic_types.html#ft_long">FT_Long</a>           style_flags;

    <a href="ft2-basic_types.html#ft_long">FT_Long</a>           num_glyphs;

    <a href="ft2-basic_types.html#ft_string">FT_String</a>*        family_name;
    <a href="ft2-basic_types.html#ft_string">FT_String</a>*        style_name;

    <a href="ft2-basic_types.html#ft_int">FT_Int</a>            num_fixed_sizes;
    <a href="ft2-sizing_and_scaling.html#ft_bitmap_size">FT_Bitmap_Size</a>*   available_sizes;

    <a href="ft2-basic_types.html#ft_int">FT_Int</a>            num_charmaps;
    <a href="ft2-character_mapping.html#ft_charmap">FT_CharMap</a>*       charmaps;

    <a href="ft2-basic_types.html#ft_generic">FT_Generic</a>        generic;

    /* The following member variables (down to `underline_thickness`) */
    /* are only relevant to scalable outlines; cf. @<a href="ft2-sizing_and_scaling.html#ft_bitmap_size">FT_Bitmap_Size</a>    */
    /* for bitmap fonts.                                              */
    <a href="ft2-basic_types.html#ft_bbox">FT_BBox</a>           bbox;

    <a href="ft2-basic_types.html#ft_ushort">FT_UShort</a>         units_per_EM;
    <a href="ft2-basic_types.html#ft_short">FT_Short</a>          ascender;
    <a href="ft2-basic_types.html#ft_short">FT_Short</a>          descender;
    <a href="ft2-basic_types.html#ft_short">FT_Short</a>          height;

    <a href="ft2-basic_types.html#ft_short">FT_Short</a>          max_advance_width;
    <a href="ft2-basic_types.html#ft_short">FT_Short</a>          max_advance_height;

    <a href="ft2-basic_types.html#ft_short">FT_Short</a>          underline_position;
    <a href="ft2-basic_types.html#ft_short">FT_Short</a>          underline_thickness;

    <a href="ft2-glyph_retrieval.html#ft_glyphslot">FT_GlyphSlot</a>      glyph;
    <a href="ft2-sizing_and_scaling.html#ft_size">FT_Size</a>           size;
    <a href="ft2-character_mapping.html#ft_charmap">FT_CharMap</a>        charmap;

    /* private fields, internal to FreeType */

    <a href="ft2-module_management.html#ft_driver">FT_Driver</a>         driver;
    <a href="ft2-system_interface.html#ft_memory">FT_Memory</a>         memory;
    <a href="ft2-system_interface.html#ft_stream">FT_Stream</a>         stream;

    <a href="ft2-list_processing.html#ft_listrec">FT_ListRec</a>        sizes_list;

    <a href="ft2-basic_types.html#ft_generic">FT_Generic</a>        autohint;   /* face-specific auto-hinter data */
    <span class="keyword">void</span>*             extensions; /* unused                         */

    <a href="ft2-other_api_data.html#ft_face_internal">FT_Face_Internal</a>  internal;

  } <b>FT_FaceRec</b>;
</code></pre></div>

<p>FreeType root face class structure. A face object models a typeface in a font file.</p>
<h4>fields</h4>
<table class="fields">
<tr><td class="val" id="num_faces">num_faces</td><td class="desc">
<p>The number of faces in the font file. Some font formats can have multiple faces in a single font file.</p>
</td></tr>
<tr><td class="val" id="face_index">face_index</td><td class="desc">
<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>
<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>
<p>Bit 31 is always zero (that is, <code>face_index</code> is always a positive value).</p>
<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>
</td></tr>
<tr><td class="val" id="face_flags">face_flags</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="style_flags">style_flags</td><td class="desc">
<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>
<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>
</td></tr>
<tr><td class="val" id="num_glyphs">num_glyphs</td><td class="desc">
<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>
<p>For CID-keyed fonts (not in an SFNT wrapper) this value gives the highest CID used in the font.</p>
</td></tr>
<tr><td class="val" id="family_name">family_name</td><td class="desc">
<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>
<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>
</td></tr>
<tr><td class="val" id="style_name">style_name</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="num_fixed_sizes">num_fixed_sizes</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="available_sizes">available_sizes</td><td class="desc">
<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>
<p>Note that FreeType tries to sanitize the strike data since they are sometimes sloppy or incorrect, but this can easily fail.</p>
</td></tr>
<tr><td class="val" id="num_charmaps">num_charmaps</td><td class="desc">
<p>The number of charmaps in the face.</p>
</td></tr>
<tr><td class="val" id="charmaps">charmaps</td><td class="desc">
<p>An array of the charmaps of the face.</p>
</td></tr>
<tr><td class="val" id="generic">generic</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="bbox">bbox</td><td class="desc">
<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>
<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>
<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>
</td></tr>
<tr><td class="val" id="units_per_em">units_per_EM</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ascender">ascender</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="descender">descender</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="height">height</td><td class="desc">
<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>
<p>If you want the global glyph height, use <code>ascender - descender</code>.</p>
</td></tr>
<tr><td class="val" id="max_advance_width">max_advance_width</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="max_advance_height">max_advance_height</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="underline_position">underline_position</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="underline_thickness">underline_thickness</td><td class="desc">
<p>The thickness, in font units, of the underline for this face. Only relevant for scalable formats.</p>
</td></tr>
<tr><td class="val" id="glyph">glyph</td><td class="desc">
<p>The face's associated glyph slot(s).</p>
</td></tr>
<tr><td class="val" id="size">size</td><td class="desc">
<p>The current active size for this face.</p>
</td></tr>
<tr><td class="val" id="charmap">charmap</td><td class="desc">
<p>The current active charmap for this face.</p>
</td></tr>
</table>

<h4>note</h4>

<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>
<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>
<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>
<hr>

<h2 id="ft_face_flag_xxx">FT_FACE_FLAG_XXX<a class="headerlink" href="#ft_face_flag_xxx" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<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 )
#<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 )
#<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 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sfnt">FT_FACE_FLAG_SFNT</a>              ( 1L &lt;&lt;  3 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_horizontal">FT_FACE_FLAG_HORIZONTAL</a>        ( 1L &lt;&lt;  4 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_vertical">FT_FACE_FLAG_VERTICAL</a>          ( 1L &lt;&lt;  5 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_kerning">FT_FACE_FLAG_KERNING</a>           ( 1L &lt;&lt;  6 )
#<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 )
#<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 )
#<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 )
#<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 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_hinter">FT_FACE_FLAG_HINTER</a>            ( 1L &lt;&lt; 11 )
#<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 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_tricky">FT_FACE_FLAG_TRICKY</a>            ( 1L &lt;&lt; 13 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_color">FT_FACE_FLAG_COLOR</a>             ( 1L &lt;&lt; 14 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_variation">FT_FACE_FLAG_VARIATION</a>         ( 1L &lt;&lt; 15 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_svg">FT_FACE_FLAG_SVG</a>               ( 1L &lt;&lt; 16 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sbix">FT_FACE_FLAG_SBIX</a>              ( 1L &lt;&lt; 17 )
#<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 )
</code></pre></div>

<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>
<h4>values</h4>
<table class="fields long">
<tr><td class="val" id="ft_face_flag_scalable">FT_FACE_FLAG_SCALABLE</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_fixed_sizes">FT_FACE_FLAG_FIXED_SIZES</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_fixed_width">FT_FACE_FLAG_FIXED_WIDTH</td><td class="desc">
<p>The face contains fixed-width characters (like Courier, Lucida, MonoType, etc.).</p>
</td></tr>
<tr><td class="val" id="ft_face_flag_sfnt">FT_FACE_FLAG_SFNT</td><td class="desc">
<p>The face uses the SFNT storage scheme. For now, this means TrueType and OpenType.</p>
</td></tr>
<tr><td class="val" id="ft_face_flag_horizontal">FT_FACE_FLAG_HORIZONTAL</td><td class="desc">
<p>The face contains horizontal glyph metrics. This should be set for all common formats.</p>
</td></tr>
<tr><td class="val" id="ft_face_flag_vertical">FT_FACE_FLAG_VERTICAL</td><td class="desc">
<p>The face contains vertical glyph metrics. This is only available in some formats, not all of them.</p>
</td></tr>
<tr><td class="val" id="ft_face_flag_kerning">FT_FACE_FLAG_KERNING</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_fast_glyphs">FT_FACE_FLAG_FAST_GLYPHS</td><td class="desc">
<p>THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT.</p>
</td></tr>
<tr><td class="val" id="ft_face_flag_multiple_masters">FT_FACE_FLAG_MULTIPLE_MASTERS</td><td class="desc">
<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>
<p>See section &lsquo;<a href="ft2-multiple_masters.html#multiple_masters">Multiple Masters</a>&rsquo; for API details.</p>
</td></tr>
<tr><td class="val" id="ft_face_flag_glyph_names">FT_FACE_FLAG_GLYPH_NAMES</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_external_stream">FT_FACE_FLAG_EXTERNAL_STREAM</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_hinter">FT_FACE_FLAG_HINTER</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_cid_keyed">FT_FACE_FLAG_CID_KEYED</td><td class="desc">
<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>
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_tricky">FT_FACE_FLAG_TRICKY</td><td class="desc">
<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>
<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>
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_color">FT_FACE_FLAG_COLOR</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_variation">FT_FACE_FLAG_VARIATION</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_svg">FT_FACE_FLAG_SVG</td><td class="desc">
<p>[Since 2.12] The face has an &lsquo;SVG&nbsp;&rsquo; OpenType table.</p>
</td></tr>
<tr><td class="val" id="ft_face_flag_sbix">FT_FACE_FLAG_SBIX</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="ft_face_flag_sbix_overlay">FT_FACE_FLAG_SBIX_OVERLAY</td><td class="desc">
<p>[Since 2.12] The face has an &lsquo;sbix&rsquo; OpenType table where outlines should be drawn on top of bitmap strikes.</p>
</td></tr>
</table>

<hr>

<h2 id="ft_style_flag_xxx">FT_STYLE_FLAG_XXX<a class="headerlink" href="#ft_style_flag_xxx" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<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 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_style_flag_bold">FT_STYLE_FLAG_BOLD</a>    ( 1 &lt;&lt; 1 )
</code></pre></div>

<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>
<h4>values</h4>
<table class="fields">
<tr><td class="val" id="ft_style_flag_italic">FT_STYLE_FLAG_ITALIC</td><td class="desc">
<p>The face style is italic or oblique.</p>
</td></tr>
<tr><td class="val" id="ft_style_flag_bold">FT_STYLE_FLAG_BOLD</td><td class="desc">
<p>The face is bold.</p>
</td></tr>
</table>

<h4>note</h4>

<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>
<hr>

<h2 id="ft_new_face">FT_New_Face<a class="headerlink" href="#ft_new_face" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_New_Face</b>( <a href="ft2-library_setup.html#ft_library">FT_Library</a>   library,
               <span class="keyword">const</span> <span class="keyword">char</span>*  filepathname,
               <a href="ft2-basic_types.html#ft_long">FT_Long</a>      face_index,
               <a href="ft2-face_creation.html#ft_face">FT_Face</a>     *aface );
</code></pre></div>

<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>
<h4>inout</h4>
<table class="fields">
<tr><td class="val" id="library">library</td><td class="desc">
<p>A handle to the library resource.</p>
</td></tr>
</table>

<h4>input</h4>
<table class="fields">
<tr><td class="val" id="pathname">pathname</td><td class="desc">
<p>A path to the font file.</p>
</td></tr>
<tr><td class="val" id="face_index">face_index</td><td class="desc">
<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>
</td></tr>
</table>

<h4>output</h4>
<table class="fields">
<tr><td class="val" id="aface">aface</td><td class="desc">
<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>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<h4>note</h4>

<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>
<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>
<hr>

<h2 id="ft_done_face">FT_Done_Face<a class="headerlink" href="#ft_done_face" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_Done_Face</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>  face );
</code></pre></div>

<p>Discard a given face object, as well as all of its child slots and sizes.</p>
<h4>input</h4>
<table class="fields">
<tr><td class="val" id="face">face</td><td class="desc">
<p>A handle to a target face object.</p>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<h4>note</h4>

<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>
<hr>

<h2 id="ft_reference_face">FT_Reference_Face<a class="headerlink" href="#ft_reference_face" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_Reference_Face</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>  face );
</code></pre></div>

<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>
<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>
<h4>input</h4>
<table class="fields">
<tr><td class="val" id="face">face</td><td class="desc">
<p>A handle to a target face object.</p>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<h4>since</h4>

<p>2.4.2</p>
<hr>

<h2 id="ft_new_memory_face">FT_New_Memory_Face<a class="headerlink" href="#ft_new_memory_face" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_New_Memory_Face</b>( <a href="ft2-library_setup.html#ft_library">FT_Library</a>      library,
                      <span class="keyword">const</span> <a href="ft2-basic_types.html#ft_byte">FT_Byte</a>*  file_base,
                      <a href="ft2-basic_types.html#ft_long">FT_Long</a>         file_size,
                      <a href="ft2-basic_types.html#ft_long">FT_Long</a>         face_index,
                      <a href="ft2-face_creation.html#ft_face">FT_Face</a>        *aface );
</code></pre></div>

<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>
<h4>inout</h4>
<table class="fields">
<tr><td class="val" id="library">library</td><td class="desc">
<p>A handle to the library resource.</p>
</td></tr>
</table>

<h4>input</h4>
<table class="fields">
<tr><td class="val" id="file_base">file_base</td><td class="desc">
<p>A pointer to the beginning of the font data.</p>
</td></tr>
<tr><td class="val" id="file_size">file_size</td><td class="desc">
<p>The size of the memory chunk used by the font data.</p>
</td></tr>
<tr><td class="val" id="face_index">face_index</td><td class="desc">
<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>
</td></tr>
</table>

<h4>output</h4>
<table class="fields">
<tr><td class="val" id="aface">aface</td><td class="desc">
<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>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<h4>note</h4>

<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>
<hr>

<h2 id="ft_face_properties">FT_Face_Properties<a class="headerlink" href="#ft_face_properties" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_Face_Properties</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>        face,
                      <a href="ft2-basic_types.html#ft_uint">FT_UInt</a>        num_properties,
                      <a href="ft2-face_creation.html#ft_parameter">FT_Parameter</a>*  properties );
</code></pre></div>

<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>
<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>
<ul>
<li>
<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>
</li>
<li>
<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>
</li>
<li>
<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>
</li>
</ul>
<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>
<h4>input</h4>
<table class="fields">
<tr><td class="val" id="face">face</td><td class="desc">
<p>A handle to the source face object.</p>
</td></tr>
<tr><td class="val" id="num_properties">num_properties</td><td class="desc">
<p>The number of properties that follow.</p>
</td></tr>
<tr><td class="val" id="properties">properties</td><td class="desc">
<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>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<h4>example</h4>

<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.
<div class="highlight"><pre><span></span><code>  FT_Parameter         property1;
  FT_Bool              darken_stems = 1;

  FT_Parameter         property2;
  FT_LcdFiveTapFilter  custom_weight =
                         { 0x11, 0x44, 0x56, 0x44, 0x11 };

  FT_Parameter         property3;
  FT_Int32             random_seed = 314159265;

  FT_Parameter         properties[3] = { property1,
                                         property2,
                                         property3 };


  property1.tag  = FT_PARAM_TAG_STEM_DARKENING;
  property1.data = &amp;darken_stems;

  property2.tag  = FT_PARAM_TAG_LCD_FILTER_WEIGHTS;
  property2.data = custom_weight;

  property3.tag  = FT_PARAM_TAG_RANDOM_SEED;
  property3.data = &amp;random_seed;

  FT_Face_Properties( face, 3, properties );
</code></pre></div></p>
<p>The next example resets a single property to its default value.
<div class="highlight"><pre><span></span><code>  FT_Parameter  property;


  property.tag  = FT_PARAM_TAG_LCD_FILTER_WEIGHTS;
  property.data = NULL;

  FT_Face_Properties( face, 1, &amp;property );
</code></pre></div></p>
<h4>since</h4>

<p>2.8</p>
<hr>

<h2 id="ft_open_face">FT_Open_Face<a class="headerlink" href="#ft_open_face" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_Open_Face</b>( <a href="ft2-library_setup.html#ft_library">FT_Library</a>           library,
                <span class="keyword">const</span> <a href="ft2-face_creation.html#ft_open_args">FT_Open_Args</a>*  args,
                <a href="ft2-basic_types.html#ft_long">FT_Long</a>              face_index,
                <a href="ft2-face_creation.html#ft_face">FT_Face</a>             *aface );
</code></pre></div>

<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>
<h4>inout</h4>
<table class="fields">
<tr><td class="val" id="library">library</td><td class="desc">
<p>A handle to the library resource.</p>
</td></tr>
</table>

<h4>input</h4>
<table class="fields">
<tr><td class="val" id="args">args</td><td class="desc">
<p>A pointer to an <code>FT_Open_Args</code> structure that must be filled by the caller.</p>
</td></tr>
<tr><td class="val" id="face_index">face_index</td><td class="desc">
<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>
<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>
<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>
</td></tr>
</table>

<h4>output</h4>
<table class="fields">
<tr><td class="val" id="aface">aface</td><td class="desc">
<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>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<h4>note</h4>

<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>
<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>
<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>
<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>
<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>
<h4>example</h4>

<p>To loop over all faces, use code similar to the following snippet (omitting the error handling).
<div class="highlight"><pre><span></span><code>  ...
  FT_Face  face;
  FT_Long  i, num_faces;


  error = FT_Open_Face( library, args, -1, &amp;face );
  if ( error ) { ... }

  num_faces = face-&gt;num_faces;
  FT_Done_Face( face );

  for ( i = 0; i &lt; num_faces; i++ )
  {
    ...
    error = FT_Open_Face( library, args, i, &amp;face );
    ...
    FT_Done_Face( face );
    ...
  }
</code></pre></div></p>
<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.
<div class="highlight"><pre><span></span><code>  ...
  FT_Face  face;

  FT_Long  num_faces     = 0;
  FT_Long  num_instances = 0;

  FT_Long  face_idx     = 0;
  FT_Long  instance_idx = 0;


  do
  {
    FT_Long  id = ( instance_idx &lt;&lt; 16 ) + face_idx;


    error = FT_Open_Face( library, args, id, &amp;face );
    if ( error ) { ... }

    num_faces     = face-&gt;num_faces;
    num_instances = face-&gt;style_flags &gt;&gt; 16;

    ...

    FT_Done_Face( face );

    if ( instance_idx &lt; num_instances )
      instance_idx++;
    else
    {
      face_idx++;
      instance_idx = 0;
    }

  } while ( face_idx &lt; num_faces )
</code></pre></div></p>
<hr>

<h2 id="ft_open_args">FT_Open_Args<a class="headerlink" href="#ft_open_args" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span>  FT_Open_Args_
  {
    <a href="ft2-basic_types.html#ft_uint">FT_UInt</a>         flags;
    <span class="keyword">const</span> <a href="ft2-basic_types.html#ft_byte">FT_Byte</a>*  memory_base;
    <a href="ft2-basic_types.html#ft_long">FT_Long</a>         memory_size;
    <a href="ft2-basic_types.html#ft_string">FT_String</a>*      pathname;
    <a href="ft2-system_interface.html#ft_stream">FT_Stream</a>       stream;
    <a href="ft2-module_management.html#ft_module">FT_Module</a>       driver;
    <a href="ft2-basic_types.html#ft_int">FT_Int</a>          num_params;
    <a href="ft2-face_creation.html#ft_parameter">FT_Parameter</a>*   params;

  } <b>FT_Open_Args</b>;
</code></pre></div>

<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>
<h4>fields</h4>
<table class="fields">
<tr><td class="val" id="flags">flags</td><td class="desc">
<p>A set of bit flags indicating how to use the structure.</p>
</td></tr>
<tr><td class="val" id="memory_base">memory_base</td><td class="desc">
<p>The first byte of the file in memory.</p>
</td></tr>
<tr><td class="val" id="memory_size">memory_size</td><td class="desc">
<p>The size in bytes of the file in memory.</p>
</td></tr>
<tr><td class="val" id="pathname">pathname</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="stream">stream</td><td class="desc">
<p>A handle to a source stream object.</p>
</td></tr>
<tr><td class="val" id="driver">driver</td><td class="desc">
<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>
</td></tr>
<tr><td class="val" id="num_params">num_params</td><td class="desc">
<p>The number of extra parameters.</p>
</td></tr>
<tr><td class="val" id="params">params</td><td class="desc">
<p>Extra parameters passed to the font driver when opening a new face.</p>
</td></tr>
</table>

<h4>note</h4>

<p>The stream type is determined by the contents of <code>flags</code>:</p>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<hr>

<h2 id="ft_open_xxx">FT_OPEN_XXX<a class="headerlink" href="#ft_open_xxx" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_memory">FT_OPEN_MEMORY</a>    0x1
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_stream">FT_OPEN_STREAM</a>    0x2
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_pathname">FT_OPEN_PATHNAME</a>  0x4
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_driver">FT_OPEN_DRIVER</a>    0x8
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_open_params">FT_OPEN_PARAMS</a>    0x10


  /* these constants are deprecated; use the corresponding `<b>FT_OPEN_XXX</b>` */
  /* values instead                                                      */
#<span class="keyword">define</span> ft_open_memory    <a href="ft2-face_creation.html#ft_open_memory">FT_OPEN_MEMORY</a>
#<span class="keyword">define</span> ft_open_stream    <a href="ft2-face_creation.html#ft_open_stream">FT_OPEN_STREAM</a>
#<span class="keyword">define</span> ft_open_pathname  <a href="ft2-face_creation.html#ft_open_pathname">FT_OPEN_PATHNAME</a>
#<span class="keyword">define</span> ft_open_driver    <a href="ft2-face_creation.html#ft_open_driver">FT_OPEN_DRIVER</a>
#<span class="keyword">define</span> ft_open_params    <a href="ft2-face_creation.html#ft_open_params">FT_OPEN_PARAMS</a>
</code></pre></div>

<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>
<h4>values</h4>
<table class="fields">
<tr><td class="val" id="ft_open_memory">FT_OPEN_MEMORY</td><td class="desc">
<p>This is a memory-based stream.</p>
</td></tr>
<tr><td class="val" id="ft_open_stream">FT_OPEN_STREAM</td><td class="desc">
<p>Copy the stream from the <code>stream</code> field.</p>
</td></tr>
<tr><td class="val" id="ft_open_pathname">FT_OPEN_PATHNAME</td><td class="desc">
<p>Create a new input stream from a C&nbsp;path name.</p>
</td></tr>
<tr><td class="val" id="ft_open_driver">FT_OPEN_DRIVER</td><td class="desc">
<p>Use the <code>driver</code> field.</p>
</td></tr>
<tr><td class="val" id="ft_open_params">FT_OPEN_PARAMS</td><td class="desc">
<p>Use the <code>num_params</code> and <code>params</code> fields.</p>
</td></tr>
</table>

<h4>note</h4>

<p>The <code>FT_OPEN_MEMORY</code>, <code>FT_OPEN_STREAM</code>, and <code>FT_OPEN_PATHNAME</code> flags are mutually exclusive.</p>
<hr>

<h2 id="ft_parameter">FT_Parameter<a class="headerlink" href="#ft_parameter" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  <span class="keyword">typedef</span> <span class="keyword">struct</span>  FT_Parameter_
  {
    <a href="ft2-basic_types.html#ft_ulong">FT_ULong</a>    tag;
    <a href="ft2-basic_types.html#ft_pointer">FT_Pointer</a>  data;

  } <b>FT_Parameter</b>;
</code></pre></div>

<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>
<h4>fields</h4>
<table class="fields">
<tr><td class="val" id="tag">tag</td><td class="desc">
<p>A four-byte identification tag.</p>
</td></tr>
<tr><td class="val" id="data">data</td><td class="desc">
<p>A pointer to the parameter data.</p>
</td></tr>
</table>

<h4>note</h4>

<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>
<hr>

<h2 id="ft_attach_file">FT_Attach_File<a class="headerlink" href="#ft_attach_file" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_Attach_File</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>      face,
                  <span class="keyword">const</span> <span class="keyword">char</span>*  filepathname );
</code></pre></div>

<p>Call <code><a href="ft2-face_creation.html#ft_attach_stream">FT_Attach_Stream</a></code> to attach a file.</p>
<h4>inout</h4>
<table class="fields">
<tr><td class="val" id="face">face</td><td class="desc">
<p>The target face object.</p>
</td></tr>
</table>

<h4>input</h4>
<table class="fields">
<tr><td class="val" id="filepathname">filepathname</td><td class="desc">
<p>The pathname.</p>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<hr>

<h2 id="ft_attach_stream">FT_Attach_Stream<a class="headerlink" href="#ft_attach_stream" title="Permanent link">&para;</a></h2>
<p>Defined in FT_FREETYPE_H (freetype/freetype.h).</p>
<div class = "codehilite"><pre><code>  FT_EXPORT( <a href="ft2-basic_types.html#ft_error">FT_Error</a> )
  <b>FT_Attach_Stream</b>( <a href="ft2-face_creation.html#ft_face">FT_Face</a>              face,
                    <span class="keyword">const</span> <a href="ft2-face_creation.html#ft_open_args">FT_Open_Args</a>*  parameters );
</code></pre></div>

<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>
<h4>inout</h4>
<table class="fields">
<tr><td class="val" id="face">face</td><td class="desc">
<p>The target face object.</p>
</td></tr>
</table>

<h4>input</h4>
<table class="fields">
<tr><td class="val" id="parameters">parameters</td><td class="desc">
<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>
</td></tr>
</table>

<h4>return</h4>

<p>FreeType error code. 0&nbsp;means success.</p>
<h4>note</h4>

<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>
<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>
<hr>
                
              
              
                


              
            </article>
          </div>
        </div>
        
      </main>
      
        
<footer class="md-footer">
  
    <nav class="md-footer__inner md-grid" aria-label="Footer">
      
        
        <a href="ft2-library_setup.html" class="md-footer__link md-footer__link--prev" aria-label="Previous: Library Setup" rel="prev">
          <div class="md-footer__button md-icon">
            <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>
          </div>
          <div class="md-footer__title">
            <div class="md-ellipsis">
              <span class="md-footer__direction">
                Previous
              </span>
              Library Setup
            </div>
          </div>
        </a>
      
      
        
        <a href="ft2-font_testing_macros.html" class="md-footer__link md-footer__link--next" aria-label="Next: Font Testing Macros" rel="next">
          <div class="md-footer__title">
            <div class="md-ellipsis">
              <span class="md-footer__direction">
                Next
              </span>
              Font Testing Macros
            </div>
          </div>
          <div class="md-footer__button md-icon">
            <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>
          </div>
        </a>
      
    </nav>
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-footer-copyright">
        
          <div class="md-footer-copyright__highlight">
            Copyright 2023 <a href = "https://www.freetype.org/license.html">The FreeType Project</a>.
          </div>
        
        Made with
        <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
          Material for MkDocs
        </a>
        
      </div>
      
    </div>
  </div>
</footer>
      
    </div>
    <div class="md-dialog" data-md-component="dialog">
      <div class="md-dialog__inner md-typeset"></div>
    </div>
    <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>
    
    
      <script src="assets/javascripts/bundle.82b56eb2.min.js"></script>
      
        <script src="javascripts/extra.js"></script>
      
    
  </body>
</html>