Source code
Revision control
Copy as Markdown
Other Tools
<!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.2">
<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.2 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="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.2 API Reference" class="md-header__button md-logo" aria-label="FreeType-2.13.2 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.2 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.2 API Reference" class="md-nav__button md-logo" aria-label="FreeType-2.13.2 API Reference" data-md-component="logo">
<img src="images/favico.ico" alt="logo">
</a>
FreeType-2.13.2 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> » <a href="../">Docs</a> » <a href="index.html#core-api">Core API</a> » Face Creation</p>
<hr />
<h1 id="face-creation">Face Creation<a class="headerlink" href="#face-creation" title="Permanent link">¶</a></h1>
<h2 id="synopsis">Synopsis<a class="headerlink" href="#synopsis" title="Permanent link">¶</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">¶</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">¶</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 0). They are set to 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 1; value 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 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 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 ‘Times New Roman’, ‘Bodoni’, ‘Garamond’, etc). This is a least common denominator used to list fonts. Some formats (TrueType & 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 ‘Italic’, ‘Bold’, ‘Condensed’, 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 ‘sbits’ 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 ‘maximum ascender’, and <code>bbox.yMin</code> as the ‘minimum descender’. 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 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 ‘MVAR’ 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">¶</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 << 0 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_fixed_sizes">FT_FACE_FLAG_FIXED_SIZES</a> ( 1L << 1 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_fixed_width">FT_FACE_FLAG_FIXED_WIDTH</a> ( 1L << 2 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sfnt">FT_FACE_FLAG_SFNT</a> ( 1L << 3 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_horizontal">FT_FACE_FLAG_HORIZONTAL</a> ( 1L << 4 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_vertical">FT_FACE_FLAG_VERTICAL</a> ( 1L << 5 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_kerning">FT_FACE_FLAG_KERNING</a> ( 1L << 6 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_fast_glyphs">FT_FACE_FLAG_FAST_GLYPHS</a> ( 1L << 7 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_multiple_masters">FT_FACE_FLAG_MULTIPLE_MASTERS</a> ( 1L << 8 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_glyph_names">FT_FACE_FLAG_GLYPH_NAMES</a> ( 1L << 9 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_external_stream">FT_FACE_FLAG_EXTERNAL_STREAM</a> ( 1L << 10 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_hinter">FT_FACE_FLAG_HINTER</a> ( 1L << 11 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_cid_keyed">FT_FACE_FLAG_CID_KEYED</a> ( 1L << 12 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_tricky">FT_FACE_FLAG_TRICKY</a> ( 1L << 13 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_color">FT_FACE_FLAG_COLOR</a> ( 1L << 14 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_variation">FT_FACE_FLAG_VARIATION</a> ( 1L << 15 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_svg">FT_FACE_FLAG_SVG</a> ( 1L << 16 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sbix">FT_FACE_FLAG_SBIX</a> ( 1L << 17 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_face_flag_sbix_overlay">FT_FACE_FLAG_SBIX_OVERLAY</a> ( 1L << 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 ‘GPOS’ 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 ‘<a href="ft2-multiple_masters.html#multiple_masters">Multiple Masters</a>’ 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 ‘gasp’ 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 ‘CID-ness’ 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 ‘tricky’, 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 ‘SVG ’ 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 ‘sbix’ 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 ‘sbix’ 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">¶</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 << 0 )
#<span class="keyword">define</span> <a href="ft2-face_creation.html#ft_style_flag_bold">FT_STYLE_FLAG_BOLD</a> ( 1 << 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 ‘OS/2’ 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">¶</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 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">¶</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 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">¶</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 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 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 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">¶</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 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">¶</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 ‘autofit’, ‘cff’, ‘type1’, and ‘t1cid’ 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 1, and CID ‘random’ operator, corresponding to the <code>random-seed</code> property provided by the ‘cff’, ‘type1’, and ‘t1cid’ 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 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 = &darken_stems;
property2.tag = FT_PARAM_TAG_LCD_FILTER_WEIGHTS;
property2.data = custom_weight;
property3.tag = FT_PARAM_TAG_RANDOM_SEED;
property3.data = &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, &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">¶</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 0). Set it to 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 1; value 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 4, <code>face_index</code> should be set to 0x00030004. If you want to access face 4 without variation handling, simply set <code>face_index</code> to value 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 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->num_faces</code> and <code>face->style_flags</code>. For any negative value of <code>face_index</code>, <code>face->num_faces</code> gives the number of faces within the font file. For the negative value ‘-(N+1)’ (with ‘N’ a non-negative 16-bit value), bits 16-30 in <code>face->style_flags</code> give the number of named instances in face ‘N’ 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 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->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->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->flags</code>, the stream in <code>args->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, &face );
if ( error ) { ... }
num_faces = face->num_faces;
FT_Done_Face( face );
for ( i = 0; i < num_faces; i++ )
{
...
error = FT_Open_Face( library, args, i, &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 << 16 ) + face_idx;
error = FT_Open_Face( library, args, id, &face );
if ( error ) { ... }
num_faces = face->num_faces;
num_instances = face->style_flags >> 16;
...
FT_Done_Face( face );
if ( instance_idx < num_instances )
instance_idx++;
else
{
face_idx++;
instance_idx = 0;
}
} while ( face_idx < 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">¶</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 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 ‘const’; 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">¶</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 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">¶</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 ‘<a href="ft2-parameter_tags.html#parameter_tags">Parameter Tags</a>’ for more information.</p>
<hr>
<h2 id="ft_attach_file">FT_Attach_File<a class="headerlink" href="#ft_attach_file" title="Permanent link">¶</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 means success.</p>
<hr>
<h2 id="ft_attach_stream">FT_Attach_Stream<a class="headerlink" href="#ft_attach_stream" title="Permanent link">¶</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>‘Attach’ 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 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 means success.</p>
<h4>note</h4>
<p>The meaning of the ‘attach’ (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">
</div>
Made with
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>