FreeType root face class structure. A face object models a typeface in a font file.
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.
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.
Parameters: filename – Filename to attach
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 attachments.
A list of FT_Bitmap_Size for all bitmap strikes in the face. It is set to NULL if there is no bitmap strike.
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 ‘maximal ascender’, and ‘bbox.yMin’ as the ‘minimal 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.
The current active charmap for this face.
A list of the charmaps of the face.
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 usually negative. Only relevant for scalable formats.
A set of bit flags that give important information about the face; see FT_FACE_FLAG_XXX for the details.
The index of the face in the font file. It is set to 0 if there is only one face in the font file.
The face’s family name. This is an ASCII string, usually in English, which 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).
Retrieve the advance value of a given glyph outline in an FT_Face. By default, the unhinted advance is returned in font units.
- gindex – The glyph index.
- flags – A set of bit flags similar to those used when calling FT_Load_Glyph, used to determine what kind of advances you need.
The advance value, in either font units or 16.16 format.
If FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance corresponding to a vertical layout. Otherwise, it is the horizontal advance in a horizontal layout.
Return the glyph index of a given character code. This function uses a charmap object to do the mapping.
Parameters: charcode – The character code.
Note:If you use FreeType to manipulate the contents of font files directly, be aware that the glyph index returned by this function doesn’t always correspond to the internal indices used within the file. This is done to ensure that value 0 always corresponds to the ‘missing glyph’.
This generator function is used to return all unicode character codes in the current charmap of a given face. For each character it also returns the corresponding glyph index.
Returns: character code, glyph index
- Note that ‘agindex’ is set to 0 if the charmap is empty. The character code itself can be 0 in two cases: if the charmap is empty or if the value 0 is the first valid character code.
This function is used to return the first character code in the current charmap of a given face. It also returns the corresponding glyph index.
Returns: Glyph index of first character code. 0 if charmap is empty.
You should use this function with get_next_char to be able to parse all character codes available in a given charmap. The code should look like this:
Note that ‘agindex’ is set to 0 if the charmap is empty. The result itself can be 0 in two cases: if the charmap is empty or if the value 0 is the first valid character code.
Return a string describing the format of a given face, using values which can be used as an X11 FONT_PROPERTY. Possible values are ‘TrueType’, ‘Type 1’, ‘BDF’, ‘PCF’, ‘Type 42’, ‘CID Type 1’, ‘CFF’, ‘PFR’, and ‘Windows FNT’.
Return the fsType flags for a font (embedding permissions).
The return value is a tuple containing the freetype enum name as a string and the actual flag as an int
This function is used to return the glyph name for the given charcode.
- agindex – The glyph index.
- buffer_max – The maximum number of bytes to use to store the glyph name.
- glyph_name – The glyph name, possibly truncated.
get_kerning(left, right, mode=0)¶
Return the kerning vector between two glyphs of a same face.
- left – The index of the left glyph in the kern pair.
- right – The index of the right glyph in the kern pair.
- mode – See FT_Kerning_Mode for more information. Determines the scale and dimension of the returned kerning vector.
Note:Only horizontal layouts (left-to-right & right-to-left) are supported by this method. Other layouts, or more sophisticated kernings, are out of the scope of this API function – they can be implemented through format-specific interfaces.
Return the glyph index of a given glyph name. This function uses driver specific objects to do the translation.
Parameters: name – The glyph name.
This function is used to return the next character code in the current charmap of a given face following the value ‘charcode’, as well as the corresponding glyph index.
- charcode – The starting character code.
- agindex – Glyph index of next character code. 0 if charmap is empty.
You should use this function with FT_Get_First_Char to walk over all character codes available in a given charmap. See the note for this function for a simple code example.
Note that ‘agindex’ is set to 0 when there are no more codes in the charmap.
Retrieve a string of the SFNT ‘name’ table for a given index
Parameters: index – The index of the ‘name’ string.
The ‘string’ array returned in the ‘aname’ structure is not null-terminated. The application should deallocate it if it is no longer in use.
Use FT_Get_Sfnt_Name_Count to get the total number of available ‘name’ table entries, then do a loop until you get the right platform, encoding, and name ID.
The face’s associated glyph slot(s).
True whenever a face object contains some embedded bitmaps. See the ‘available_sizes’ field of the FT_FaceRec structure.
True whenever a face object contains some glyph names that can be accessed through FT_Get_Glyph_Name.
True whenever a face object contains horizontal metrics (this is true for all font formats though).
True whenever a face object contains kerning data that can be accessed with FT_Get_Kerning.
True whenever a face object contains some multiple masters. The functions provided by FT_MULTIPLE_MASTERS_H are then available to choose the exact design you want.
True whenever a face object contains vertical metrics.
The height is the vertical distance between two consecutive baselines, expressed in font units. It is always positive. Only relevant for scalable formats.
True whenever a face object contains a CID-keyed font. See the discussion of FT_FACE_FLAG_CID_KEYED for more details.
If this macro is true, all functions defined in FT_CID_H are available.
True whenever a face object contains a font face that contains fixed-width (or ‘monospace’, ‘fixed-pitch’, etc.) glyphs.
true whenever a face object contains a scalable font face (true for TrueType, Type 1, Type 42, CID, OpenType/CFF, and PFR font formats.
true whenever a face object contains a font whose format is based on the SFNT storage scheme. This usually means: TrueType fonts, OpenType fonts, as well as SFNT-based embedded bitmap fonts.
If this macro is true, all functions defined in FT_SFNT_NAMES_H and FT_TRUETYPE_TABLES_H are available.
True whenever a face represents a ‘tricky’ font. See the discussion of FT_FACE_FLAG_TRICKY for more details.
A function used to load a single glyph into the glyph slot of a face object, according to its character code.
- char – The glyph’s character code, according to the current charmap used in the face.
- flags – A flag indicating what to load for this glyph. The FT_LOAD_XXX constants can be used to control the glyph loading process (e.g., whether the outline should be scaled, whether to load bitmaps or not, whether to hint the outline, etc).
Note:This function simply calls FT_Get_Char_Index and FT_Load_Glyph.
A function used to load a single glyph into the glyph slot of a face object.
- index – The index of the glyph in the font file. For CID-keyed fonts (either in PS or in CFF format) this argument specifies the CID value.
The loaded glyph may be transformed. See FT_Set_Transform for the details.
For subsetted CID-keyed fonts, ‘FT_Err_Invalid_Argument’ is returned for invalid CID values (this is, for CID values which don’t have a corresponding glyph in the font). See the discussion of the FT_FACE_FLAG_CID_KEYED flag for more details.
The maximal 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.
The maximal 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.
The number of faces in the font file. Some font formats can have multiple faces in a font file.
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.
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, this value gives the highest CID used in the font.
ASCII PostScript name of face, if available. This only works with PostScript and TrueType fonts.
Select a given charmap by its encoding tag (as listed in ‘freetype.h’).
This function returns an error if no charmap in the face corresponds to the encoding queried here.
Because many fonts contain more than a single cmap for Unicode encoding, this function has some special code to select the one which covers Unicode best (‘best’ in the sense that a UCS-4 cmap is preferred to a UCS-2 cmap). It is thus preferable to FT_Set_Charmap in this case.
Select a bitmap strike.
Parameters: strike_index – The index of the bitmap strike in the ‘available_sizes’ field of Face object.
set_char_size(width=0, height=0, hres=72, vres=72)¶
This function calls FT_Request_Size to request the nominal size (in points).
- width (float) – The nominal width, in 26.6 fractional points.
- height (float) – The nominal height, in 26.6 fractional points.
- hres (float) – The horizontal resolution in dpi.
- vres (float) – The vertical resolution in dpi.
If either the character width or height is zero, it is set equal to the other value.
If either the horizontal or vertical resolution is zero, it is set equal to the other value.
A character width or height smaller than 1pt is set to 1pt; if both resolution values are zero, they are set to 72dpi.
Don’t use this function if you are using the FreeType cache API.
Select a given charmap for character code to glyph index mapping.
Parameters: charmap – A handle to the selected charmap, or an index to face->charmaps
This function calls FT_Request_Size to request the nominal size (in pixels).
- width – The nominal width, in pixels.
- height – The nominal height, in pixels.
A function used to set the transformation that is applied to glyph images when they are loaded into a glyph slot through FT_Load_Glyph.
Parameters: matrix – A pointer to the transformation’s 2x2 matrix. Use 0 for the identity matrix. Parm delta: A pointer to the translation vector. Use 0 for the null vector.
The transformation is only applied to scalable image formats after the glyph has been loaded. It means that hinting is unaltered by the transformation and is performed on the character size given in the last call to FT_Set_Char_Size or FT_Set_Pixel_Sizes.
Note that this also transforms the ‘face.glyph.advance’ field, but not the values in ‘face.glyph.metrics’.
Number of name strings in the SFNT ‘name’ table.
The current active size for this face.
A set of bit flags indicating the style of the face; see FT_STYLE_FLAG_XXX for the details.
The face’s style name. This is an ASCII string, usually in English, which 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.
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.
The thickness, in font units, of the underline for this face. Only relevant for scalable formats.
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.