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.