Skip to content

FreeType » Docs » Core API » Face Creation

# Face Creation

## Synopsis

The functions and structures collected in this section operate on fonts globally.

## FT_Face

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct FT_FaceRec_*  FT_Face;

A handle to a typographic face object. A face object models a given typeface, in a given style.

#### note

A face object also owns a single `FT_GlyphSlot` object, as well as one or more `FT_Size` objects.

Use `FT_New_Face` or `FT_Open_Face` to create a new face object from a given filepath or a custom input stream.

Use `FT_Done_Face` to destroy it (along with its slot and sizes).

An `FT_Face` object can only be safely used from one thread at a time. Similarly, creation and destruction of `FT_Face` with the same `FT_Library` object can only be done from one thread at a time. On the other hand, functions like `FT_Load_Glyph` and its siblings are thread-safe and do not need the lock to be held as long as the same `FT_Face` object is not used from multiple threads at the same time.

#### also

See `FT_FaceRec` for the publicly accessible fields of a given face object.

## FT_FaceRec

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_FaceRec_
      {
        FT_Long           num_faces;
        FT_Long           face_index;

        FT_Long           face_flags;
        FT_Long           style_flags;

        FT_Long           num_glyphs;

        FT_String*        family_name;
        FT_String*        style_name;

        FT_Int            num_fixed_sizes;
        FT_Bitmap_Size*   available_sizes;

        FT_Int            num_charmaps;
        FT_CharMap*       charmaps;

        FT_Generic        generic;

        /* The following member variables (down to `underline_thickness`) */
        /* are only relevant to scalable outlines; cf. @FT_Bitmap_Size    */
        /* for bitmap fonts.                                              */
        FT_BBox           bbox;

        FT_UShort         units_per_EM;
        FT_Short          ascender;
        FT_Short          descender;
        FT_Short          height;

        FT_Short          max_advance_width;
        FT_Short          max_advance_height;

        FT_Short          underline_position;
        FT_Short          underline_thickness;

        FT_GlyphSlot      glyph;
        FT_Size           size;
        FT_CharMap        charmap;

        /* private fields, internal to FreeType */

        FT_Driver         driver;
        FT_Memory         memory;
        FT_Stream         stream;

        FT_ListRec        sizes_list;

        FT_Generic        autohint;   /* face-specific auto-hinter data */
        void*             extensions; /* unused                         */

        FT_Face_Internal  internal;

      } FT_FaceRec;

FreeType root face class structure. A face object models a typeface in a font file.

#### fields

num_faces | The number of faces in the font file. Some font formats can have multiple faces in a single font file.

face_index

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.

[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, `face_index` is set to 0x00030004.

Bit 31 is always zero (that is, `face_index` is always a positive value).

[Since 2.9] Changing the design coordinates with `FT_Set_Var_Design_Coordinates` or `FT_Set_Var_Blend_Coordinates` does not influence the named instance index value (only `FT_Set_Named_Instance` does that).

face_flags | A set of bit flags that give important information about the face; see `FT_FACE_FLAG_XXX` for the details.

style_flags

The lower 16 bits contain a set of bit flags indicating the style of the face; see `FT_STYLE_FLAG_XXX` for the details.

[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, `style_flags` is always a positive value). Note that a variation font has always at least one named instance, namely the default instance.

num_glyphs | The number of glyphs in the face. If the face is scalable and has sbits (see `num_fixed_sizes`), it is set to the number of outline glyphs. For CID-keyed fonts (not in an SFNT wrapper) this value gives the highest CID used in the font.

family_name

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 `NULL` (e.g., in fonts embedded in a PDF file).

In case the font doesn't provide a specific family name entry, FreeType tries to synthesize one, deriving it from other name entries.

style_name

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 `NULL`. As for `family_name`, some formats provide localized and Unicode versions of this string. Applications should use the format-specific interface to access them.

num_fixed_sizes | 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.
available_sizes | An array of `FT_Bitmap_Size` for all bitmap strikes in the face. It is set to `NULL` if there is no bitmap strike. Note that FreeType tries to sanitize the strike data since they are sometimes sloppy or incorrect, but this can easily fail.
num_charmaps | The number of charmaps in the face.
charmaps | An array of the charmaps of the face.
generic | A field reserved for client uses. See the `FT_Generic` type description.

bbox

The font bounding box. Coordinates are expressed in font units (see `units_per_EM`). The box is large enough to contain any glyph from the font. Thus, `bbox.yMax` can be seen as the ‘maximum ascender’, and `bbox.yMin` as the ‘minimum descender’. Only relevant for scalable formats.

Note that the bounding box might be off by (at least) one pixel for hinted fonts. See `FT_Size_Metrics` for further discussion.

Note that the bounding box does not vary in OpenType variation fonts and should only be used in relation to the default instance.

units_per_EM | 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.
ascender | The typographic ascender of the face, expressed in font units. For font formats not having this information, it is set to `bbox.yMax`. Only relevant for scalable formats.
descender | The typographic descender of the face, expressed in font units. For font formats not having this information, it is set to `bbox.yMin`. Note that this field is negative for values below the baseline. Only relevant for scalable formats.
height | This value is the vertical distance between two consecutive baselines, expressed in font units. It is always positive. Only relevant for scalable formats. If you want the global glyph height, use `ascender - descender`.
max_advance_width | 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.
max_advance_height | The maximum advance height, in font units, for all glyphs in this face. This is only relevant for vertical layouts, and is set to `height` for fonts that do not provide vertical metrics. Only relevant for scalable formats.
underline_position | 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.
underline_thickness | The thickness, in font units, of the underline for this face. Only relevant for scalable formats.
glyph | The face's associated glyph slot(s).
size | The current active size for this face.
charmap | The current active charmap for this face.

#### note

Fields may be changed after a call to `FT_Attach_File` or `FT_Attach_Stream`.

For an OpenType variation font, the values of the following fields can change after a call to `FT_Set_Var_Design_Coordinates` (and friends) if the font contains an ‘MVAR’ table: `ascender`, `descender`, `height`, `underline_position`, and `underline_thickness`.

Especially for TrueType fonts see also the documentation for `FT_Size_Metrics`.

## FT_FACE_FLAG_XXX

Defined in FT_FREETYPE_H (freetype/freetype.h).

    #define FT_FACE_FLAG_SCALABLE          ( 1L <<  0 )
    #define FT_FACE_FLAG_FIXED_SIZES       ( 1L <<  1 )
    #define FT_FACE_FLAG_FIXED_WIDTH       ( 1L <<  2 )
    #define FT_FACE_FLAG_SFNT              ( 1L <<  3 )
    #define FT_FACE_FLAG_HORIZONTAL        ( 1L <<  4 )
    #define FT_FACE_FLAG_VERTICAL          ( 1L <<  5 )
    #define FT_FACE_FLAG_KERNING           ( 1L <<  6 )
    #define FT_FACE_FLAG_FAST_GLYPHS       ( 1L <<  7 )
    #define FT_FACE_FLAG_MULTIPLE_MASTERS  ( 1L <<  8 )
    #define FT_FACE_FLAG_GLYPH_NAMES       ( 1L <<  9 )
    #define FT_FACE_FLAG_EXTERNAL_STREAM   ( 1L << 10 )
    #define FT_FACE_FLAG_HINTER            ( 1L << 11 )
    #define FT_FACE_FLAG_CID_KEYED         ( 1L << 12 )
    #define FT_FACE_FLAG_TRICKY            ( 1L << 13 )
    #define FT_FACE_FLAG_COLOR             ( 1L << 14 )
    #define FT_FACE_FLAG_VARIATION         ( 1L << 15 )
    #define FT_FACE_FLAG_SVG               ( 1L << 16 )
    #define FT_FACE_FLAG_SBIX              ( 1L << 17 )
    #define FT_FACE_FLAG_SBIX_OVERLAY      ( 1L << 18 )

A list of bit flags used in the `face_flags` field of the `FT_FaceRec` structure. They inform client applications of properties of the corresponding face.

#### values

FT_FACE_FLAG_SCALABLE | The face contains outline glyphs. Note that a face can contain bitmap strikes also, i.e., a face can have both this flag and `FT_FACE_FLAG_FIXED_SIZES` set.
FT_FACE_FLAG_FIXED_SIZES | The face contains bitmap strikes. See also the `num_fixed_sizes` and `available_sizes` fields of `FT_FaceRec`.
FT_FACE_FLAG_FIXED_WIDTH | The face contains fixed-width characters (like Courier, Lucida, MonoType, etc.).
FT_FACE_FLAG_SFNT | The face uses the SFNT storage scheme. For now, this means TrueType and OpenType.
FT_FACE_FLAG_HORIZONTAL | The face contains horizontal glyph metrics. This should be set for all common formats.
FT_FACE_FLAG_VERTICAL | The face contains vertical glyph metrics. This is only available in some formats, not all of them.

FT_FACE_FLAG_KERNING

The face contains kerning information. If set, the kerning distance can be retrieved using the function `FT_Get_Kerning`. Otherwise the function always returns the vector (0,0).

Note that for TrueType fonts only, FreeType supports both the ‘kern’ table and the basic, pair-wise kerning feature from the ‘GPOS’ table (with `TT_CONFIG_OPTION_GPOS_KERNING` enabled), though FreeType does not support the more advanced GPOS layout features; use a library like HarfBuzz for those instead.

FT_FACE_FLAG_FAST_GLYPHS | THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT.
FT_FACE_FLAG_MULTIPLE_MASTERS | The face contains multiple masters and is capable of interpolating between them. Supported formats are Adobe MM, TrueType GX, and OpenType variation fonts. See section ‘Multiple Masters’ for API details.
FT_FACE_FLAG_GLYPH_NAMES | The face contains glyph names, which can be retrieved using `FT_Get_Glyph_Name`. Note that some TrueType fonts contain broken glyph name tables. Use the function `FT_Has_PS_Glyph_Names` when needed.
FT_FACE_FLAG_EXTERNAL_STREAM | Used internally by FreeType to indicate that a face's stream was provided by the client application and should not be destroyed when `FT_Done_Face` is called. Don't read or test this flag.
FT_FACE_FLAG_HINTER | 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.

FT_FACE_FLAG_CID_KEYED

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 `FT_Load_Glyph`. Only the CID values for which corresponding glyphs in the subsetted font exist make `FT_Load_Glyph` return successfully; in all other cases you get an `FT_Err_Invalid_Argument` error.

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.

FT_FACE_FLAG_TRICKY

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 `mingli.ttf` (but not `mingliu.ttc`) that uses TrueType bytecode instructions to move and scale all of its subglyphs.

It is not possible to auto-hint such fonts using `FT_LOAD_FORCE_AUTOHINT`; it will also ignore `FT_LOAD_NO_HINTING`. You have to set both `FT_LOAD_NO_HINTING` and `FT_LOAD_NO_AUTOHINT` to really disable hinting; however, you probably never want this except for demonstration purposes.

Currently, there are about a dozen TrueType fonts in the list of tricky fonts; they are hard-coded in file `ttobjs.c`.

FT_FACE_FLAG_COLOR | [Since 2.5.1] The face has color glyph tables. See `FT_LOAD_COLOR` for more information.
FT_FACE_FLAG_VARIATION | [Since 2.9] Set if the current face (or named instance) has been altered with `FT_Set_MM_Design_Coordinates`, `FT_Set_Var_Design_Coordinates`, `FT_Set_Var_Blend_Coordinates`, or `FT_Set_MM_WeightVector` to select a non-default instance.
FT_FACE_FLAG_SVG | [Since 2.12] The face has an ‘SVG ’ OpenType table.
FT_FACE_FLAG_SBIX | [Since 2.12] The face has an ‘sbix’ OpenType table and outlines. For such fonts, `FT_FACE_FLAG_SCALABLE` is not set by default to retain backward compatibility.
FT_FACE_FLAG_SBIX_OVERLAY | [Since 2.12] The face has an ‘sbix’ OpenType table where outlines should be drawn on top of bitmap strikes.

## FT_STYLE_FLAG_XXX

Defined in FT_FREETYPE_H (freetype/freetype.h).

    #define FT_STYLE_FLAG_ITALIC  ( 1 << 0 )
    #define FT_STYLE_FLAG_BOLD    ( 1 << 1 )

A list of bit flags to indicate the style of a given face. These are used in the `style_flags` field of `FT_FaceRec`.

#### values

FT_STYLE_FLAG_ITALIC | The face style is italic or oblique.
FT_STYLE_FLAG_BOLD | The face is bold.

#### note

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).

## FT_New_Face

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_New_Face( FT_Library   library,
                   const char*  filepathname,
                   FT_Long      face_index,
                   FT_Face     *aface );

Call `FT_Open_Face` to open a font by its pathname.

#### inout

library | A handle to the library resource.

#### input

pathname | A path to the font file.
face_index | See `FT_Open_Face` for a detailed description of this parameter.

#### output

aface | A handle to a new face object. If `face_index` is greater than or equal to zero, it must be non-`NULL`.

#### return

FreeType error code. 0 means success.

#### note

The `pathname` string should be recognizable as such by a standard `fopen` call on your system; in particular, this means that `pathname` 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 `FT_Open_Face` to pass a memory array or a stream object instead.

Use `FT_Done_Face` to destroy the created `FT_Face` object (along with its slot and sizes).

## FT_Done_Face

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Done_Face( FT_Face  face );

Discard a given face object, as well as all of its child slots and sizes.

#### input

face | A handle to a target face object.

#### return

FreeType error code. 0 means success.

#### note

See the discussion of reference counters in the description of `FT_Reference_Face`.

## FT_Reference_Face

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Reference_Face( FT_Face  face );

A counter gets initialized to 1 at the time an `FT_Face` structure is created. This function increments the counter. `FT_Done_Face` then only destroys a face if the counter is 1, otherwise it simply decrements the counter.

This function helps in managing life-cycles of structures that reference `FT_Face` objects.

#### input

face | A handle to a target face object.

#### return

FreeType error code. 0 means success.

#### since

2.4.2

## FT_New_Memory_Face

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_New_Memory_Face( FT_Library      library,
                          const FT_Byte*  file_base,
                          FT_Long         file_size,
                          FT_Long         face_index,
                          FT_Face        *aface );

Call `FT_Open_Face` to open a font that has been loaded into memory.

#### inout

library | A handle to the library resource.

#### input

file_base | A pointer to the beginning of the font data.
file_size | The size of the memory chunk used by the font data.
face_index | See `FT_Open_Face` for a detailed description of this parameter.

#### output

aface | A handle to a new face object. If `face_index` is greater than or equal to zero, it must be non-`NULL`.

#### return

FreeType error code. 0 means success.

#### note

You must not deallocate the memory before calling `FT_Done_Face`.

## FT_Face_Properties

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Face_Properties( FT_Face        face,
                          FT_UInt        num_properties,
                          FT_Parameter*  properties );

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).

Contrary to `FT_Property_Set`, this function uses `FT_Parameter` 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.

- `FT_PARAM_TAG_STEM_DARKENING` (stem darkening, corresponding to the property `no-stem-darkening` provided by the ‘autofit’, ‘cff’, ‘type1’, and ‘t1cid’ modules; see `no-stem-darkening`).

- `FT_PARAM_TAG_LCD_FILTER_WEIGHTS` (LCD filter weights, corresponding to function `FT_Library_SetLcdFilterWeights`).

- `FT_PARAM_TAG_RANDOM_SEED` (seed value for the CFF, Type 1, and CID ‘random’ operator, corresponding to the `random-seed` property provided by the ‘cff’, ‘type1’, and ‘t1cid’ modules; see `random-seed`).

Pass `NULL` as `data` in `FT_Parameter` for a given tag to reset the option and use the library or module default again.

#### input

face | A handle to the source face object.
num_properties | The number of properties that follow.
properties | A handle to an `FT_Parameter` array with `num_properties` elements.

#### return

FreeType error code. 0 means success.

#### example

Here is an example that sets three properties. You must define `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` to make the LCD filter examples work.

      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 );

The next example resets a single property to its default value.

      FT_Parameter  property;

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

      FT_Face_Properties( face, 1, &property );

#### since

2.8

## FT_Open_Face

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Open_Face( FT_Library           library,
                    const FT_Open_Args*  args,
                    FT_Long              face_index,
                    FT_Face             *aface );

Create a face object from a given resource described by `FT_Open_Args`.

#### inout

library | A handle to the library resource.

#### input

args | A pointer to an `FT_Open_Args` structure that must be filled by the caller.

face_index

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.

[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, `face_index` should be set to 0x00030004. If you want to access face 4 without variation handling, simply set `face_index` to value 4.

`FT_Open_Face` 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 `face_index` 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 `*aface` (if `aface` isn't `NULL`); the only two useful fields in this special case are `face->num_faces` and `face->style_flags`. For any negative value of `face_index`, `face->num_faces` 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 `face->style_flags` give the number of named instances in face ‘N’ if we have a variation font (or zero otherwise). After examination, the returned `FT_Face` structure should be deallocated with a call to `FT_Done_Face`.

#### output

aface | A handle to a new face object. If `face_index` is greater than or equal to zero, it must be non-`NULL`.

#### return

FreeType error code. 0 means success.

#### note

Unlike FreeType 1.x, this function automatically creates a glyph slot for the face object that can be accessed directly through `face->glyph`.

Each new face object created with this function also owns a default `FT_Size` object, accessible as `face->size`.

One `FT_Library` instance can have multiple face objects, that is, `FT_Open_Face` and its siblings can be called multiple times using the same `library` argument.

See the discussion of reference counters in the description of `FT_Reference_Face`.

If `FT_OPEN_STREAM` is set in `args->flags`, the stream in `args->stream` is automatically closed before this function returns any error (including `FT_Err_Invalid_Argument`).

#### example

To loop over all faces, use code similar to the following snippet (omitting the error handling).

      ...
      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 );
        ...
      }

To loop over all valid values for `face_index`, use something similar to the following snippet, again without error handling. The code accesses all faces immediately (thus only a single call of `FT_Open_Face` within the do-loop), with and without named instances.

      ...
      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 )

## FT_Open_Args

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_Open_Args_
      {
        FT_UInt         flags;
        const FT_Byte*  memory_base;
        FT_Long         memory_size;
        FT_String*      pathname;
        FT_Stream       stream;
        FT_Module       driver;
        FT_Int          num_params;
        FT_Parameter*   params;

      } FT_Open_Args;

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 `FT_Open_Face` and `FT_Attach_Stream`.

#### fields

flags | A set of bit flags indicating how to use the structure.
memory_base | The first byte of the file in memory.
memory_size | The size in bytes of the file in memory.
pathname | 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.
stream | A handle to a source stream object.
driver | This field is exclusively used by `FT_Open_Face`; it simply specifies the font driver to use for opening the face. If set to `NULL`, FreeType tries to load the face with each one of the drivers in its list.
num_params | The number of extra parameters.
params | Extra parameters passed to the font driver when opening a new face.

#### note

The stream type is determined by the contents of `flags`:

If the `FT_OPEN_MEMORY` bit is set, assume that this is a memory file of `memory_size` bytes, located at `memory_address`. The data are not copied, and the client is responsible for releasing and destroying them after the corresponding call to `FT_Done_Face`.

Otherwise, if the `FT_OPEN_STREAM` bit is set, assume that a custom input stream `stream` is used.

Otherwise, if the `FT_OPEN_PATHNAME` bit is set, assume that this is a normal file and use `pathname` to open it.

If none of the above bits are set or if multiple are set at the same time, the flags are invalid and `FT_Open_Face` fails.

If the `FT_OPEN_DRIVER` bit is set, `FT_Open_Face` only tries to open the file with the driver whose handler is in `driver`.

If the `FT_OPEN_PARAMS` bit is set, the parameters given by `num_params` and `params` is used. They are ignored otherwise.

Ideally, both the `pathname` and `params` fields should be tagged as ‘const’; this is missing for API backward compatibility. In other words, applications should treat them as read-only.

## FT_OPEN_XXX

Defined in FT_FREETYPE_H (freetype/freetype.h).

    #define FT_OPEN_MEMORY    0x1
    #define FT_OPEN_STREAM    0x2
    #define FT_OPEN_PATHNAME  0x4
    #define FT_OPEN_DRIVER    0x8
    #define FT_OPEN_PARAMS    0x10

      /* these constants are deprecated; use the corresponding `FT_OPEN_XXX` */
      /* values instead                                                      */
    #define ft_open_memory    FT_OPEN_MEMORY
    #define ft_open_stream    FT_OPEN_STREAM
    #define ft_open_pathname  FT_OPEN_PATHNAME
    #define ft_open_driver    FT_OPEN_DRIVER
    #define ft_open_params    FT_OPEN_PARAMS

A list of bit field constants used within the `flags` field of the `FT_Open_Args` structure.

#### values

FT_OPEN_MEMORY | This is a memory-based stream.
FT_OPEN_STREAM | Copy the stream from the `stream` field.
FT_OPEN_PATHNAME | Create a new input stream from a C path name.
FT_OPEN_DRIVER | Use the `driver` field.
FT_OPEN_PARAMS | Use the `num_params` and `params` fields.

#### note

The `FT_OPEN_MEMORY`, `FT_OPEN_STREAM`, and `FT_OPEN_PATHNAME` flags are mutually exclusive.

## FT_Parameter

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct  FT_Parameter_
      {
        FT_ULong    tag;
        FT_Pointer  data;

      } FT_Parameter;

A simple structure to pass more or less generic parameters to `FT_Open_Face` and `FT_Face_Properties`.

#### fields

tag | A four-byte identification tag.
data | A pointer to the parameter data.

#### note

The ID and function of parameters are driver-specific. See section ‘Parameter Tags’ for more information.

## FT_Attach_File

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Attach_File( FT_Face      face,
                      const char*  filepathname );

Call `FT_Attach_Stream` to attach a file.

#### inout

face | The target face object.

#### input

filepathname | The pathname.

#### return

FreeType error code. 0 means success.

## FT_Attach_Stream

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Attach_Stream( FT_Face              face,
                        const FT_Open_Args*  parameters );

‘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.

#### inout

face | The target face object.

#### input

parameters | A pointer to `FT_Open_Args` that must be filled by the caller.

#### return

FreeType error code. 0 means success.

#### note

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).

Client applications are expected to know what they are doing when invoking this function. Most drivers simply do not implement file or stream attachments.