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.

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.