Face¶
-
class
freetype.
Face
(path_or_stream, index=0)¶ FT_Face wrapper
FreeType root face class structure. A face object models a typeface in a font file.
-
property
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.
-
attach_file
(filename)¶ 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
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 attachments.
-
property
available_sizes
¶ A list of FT_Bitmap_Size for all bitmap strikes in the face. It is set to NULL if there is no bitmap strike.
-
property
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 ‘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.
-
property
charmap
¶ The current active charmap for this face.
-
property
charmaps
¶ A list of the charmaps of the face.
-
property
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 usually negative. Only relevant for scalable formats.
-
property
face_flags
¶ A set of bit flags that give important information about the face; see FT_FACE_FLAG_XXX for the details.
-
property
face_index
¶ The index of the face in the font file. It is set to 0 if there is only one face in the font file.
-
property
family_name
¶ 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).
-
get_advance
(gindex, flags)¶ Retrieve the advance value of a given glyph outline in an FT_Face. By default, the unhinted advance is returned in font units.
- Parameters
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.
- Returns
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.
-
get_char_index
(charcode)¶ 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’.
-
get_chars
()¶ 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:
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.
-
get_first_char
()¶ 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.
Note:
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.
-
get_format
()¶ 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’.
-
get_fstype
()¶ 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
-
get_glyph_name
(agindex, buffer_max=64)¶ This function is used to return the glyph name for the given charcode.
- Parameters
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.
- Parameters
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.
-
get_name_index
(name)¶ Return the glyph index of a given glyph name. This function uses driver specific objects to do the translation.
- Parameters
name – The glyph name.
-
get_next_char
(charcode, agindex)¶ 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.
- Parameters
charcode – The starting character code.
agindex – Glyph index of next character code. 0 if charmap is empty.
Note:
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.
-
get_sfnt_name
(index)¶ Retrieve a string of the SFNT ‘name’ table for a given index
- Parameters
index – The index of the ‘name’ string.
Note:
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.
-
property
glyph
¶ The face’s associated glyph slot(s).
-
property
has_fixed_sizes
¶ True whenever a face object contains some embedded bitmaps. See the ‘available_sizes’ field of the FT_FaceRec structure.
-
property
has_glyph_names
¶ True whenever a face object contains some glyph names that can be accessed through FT_Get_Glyph_Name.
-
property
has_horizontal
¶ True whenever a face object contains horizontal metrics (this is true for all font formats though).
-
property
has_kerning
¶ True whenever a face object contains kerning data that can be accessed with FT_Get_Kerning.
-
property
has_multiple_masters
¶ 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.
-
property
has_vertical
¶ True whenever a face object contains vertical metrics.
-
property
height
¶ The height is the vertical distance between two consecutive baselines, expressed in font units. It is always positive. Only relevant for scalable formats.
-
property
is_cid_keyed
¶ 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.
-
property
is_fixed_width
¶ True whenever a face object contains a font face that contains fixed-width (or ‘monospace’, ‘fixed-pitch’, etc.) glyphs.
-
property
is_scalable
¶ true whenever a face object contains a scalable font face (true for TrueType, Type 1, Type 42, CID, OpenType/CFF, and PFR font formats.
-
property
is_sfnt
¶ 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.
-
property
is_tricky
¶ True whenever a face represents a ‘tricky’ font. See the discussion of FT_FACE_FLAG_TRICKY for more details.
-
load_char
(char, flags=4)¶ A function used to load a single glyph into the glyph slot of a face object, according to its character code.
- Parameters
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.
-
load_glyph
(index, flags=4)¶ A function used to load a single glyph into the glyph slot of a face object.
- Parameters
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.
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:
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.
-
property
max_advance_height
¶ 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.
-
property
max_advance_width
¶ 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.
-
property
num_faces
¶ The number of faces in the font file. Some font formats can have multiple faces in a font file.
-
property
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.
-
property
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, this value gives the highest CID used in the font.
-
property
postscript_name
¶ ASCII PostScript name of face, if available. This only works with PostScript and TrueType fonts.
-
select_charmap
(encoding)¶ Select a given charmap by its encoding tag (as listed in ‘freetype.h’).
Note:
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_size
(strike_index)¶ 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).
- Parameters
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.
Note
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.
-
set_charmap
(charmap)¶ 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[]
-
set_pixel_sizes
(width, height)¶ This function calls FT_Request_Size to request the nominal size (in pixels).
- Parameters
width – The nominal width, in pixels.
height – The nominal height, in pixels.
-
set_transform
(matrix, delta)¶ 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.
Note:
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’.
-
property
sfnt_name_count
¶ Number of name strings in the SFNT ‘name’ table.
-
property
size
¶ The current active size for this face.
-
property
style_flags
¶ A set of bit flags indicating the style of the face; see FT_STYLE_FLAG_XXX for the details.
-
property
style_name
¶ 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.
-
property
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.
-
property
underline_thickness
¶ The thickness, in font units, of the underline for this face. Only relevant for scalable formats.
-
property
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.
-
property