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, Bit 31 is always zero (that is, [Since 2.9] Changing the design coordinates with |
| face_flags |
A set of bit flags that give important information about the face; see |
| style_flags |
The lower 16 bits contain a set of bit flags indicating the style of the face; see [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, |
| num_glyphs |
The number of glyphs in the face. If the face is scalable and has sbits (see 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 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 |
| 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 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 |
| bbox |
The font bounding box. Coordinates are expressed in font units (see Note that the bounding box might be off by (at least) one pixel for hinted fonts. See 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 |
| descender |
The typographic descender of the face, expressed in font units. For font formats not having this information, it is set to |
| 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 |
| 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 |
| 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 |
The face contains bitmap strikes. See also the |
| 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 Note that for TrueType fonts only, FreeType supports both the ‘kern’ table and the basic, pair-wise kerning feature from the ‘GPOS’ table (with |
| 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_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_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 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 It is not possible to auto-hint such fonts using Currently, there are about a dozen TrueType fonts in the list of tricky fonts; they are hard-coded in file |
| FT_FACE_FLAG_COLOR |
[Since 2.5.1] The face has color glyph tables. See |
| FT_FACE_FLAG_VARIATION |
[Since 2.9] Set if the current face (or named instance) has been altered with |
| 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_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 |
output
| aface |
A handle to a new face object. If |
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).
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).
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 |
output
| aface |
A handle to a new face object. If |
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 propertyno-stem-darkeningprovided by the ‘autofit’, ‘cff’, ‘type1’, and ‘t1cid’ modules; seeno-stem-darkening). -
FT_PARAM_TAG_LCD_FILTER_WEIGHTS(LCD filter weights, corresponding to functionFT_Library_SetLcdFilterWeights). -
FT_PARAM_TAG_RANDOM_SEED(seed value for the CFF, Type 1, and CID ‘random’ operator, corresponding to therandom-seedproperty provided by the ‘cff’, ‘type1’, and ‘t1cid’ modules; seerandom-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 |
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 |
| 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,
|
output
| aface |
A handle to a new face object. If |
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 |
| 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 |
| FT_OPEN_PATHNAME |
Create a new input stream from a C path name. |
| FT_OPEN_DRIVER |
Use the |
| FT_OPEN_PARAMS |
Use the |
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).
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 |
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.