FreeType » Docs » Core API » Information Retrieval
Information Retrieval¶
Synopsis¶
Functions to retrieve font and glyph information. Only some very basic data is covered; see also the chapter on the format-specific API for more.
FT_Get_Name_Index¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
Return the glyph index of a given glyph name. This only works for those faces where FT_HAS_GLYPH_NAMES returns true.
input
| face |
A handle to the source face object. |
| glyph_name |
The glyph name. |
return
The glyph index. 0 means ‘undefined character code’.
note
Acceptable glyph names might come from the Adobe Glyph List. See FT_Get_Glyph_Name for the inverse functionality.
This function has limited capabilities if the config macro FT_CONFIG_OPTION_POSTSCRIPT_NAMES is not defined in ftoption.h: It then works only for fonts that actually embed glyph names (which many recent OpenType fonts do not).
FT_Get_Glyph_Name¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
FT_EXPORT( FT_Error )
FT_Get_Glyph_Name( FT_Face face,
FT_UInt glyph_index,
FT_Pointer buffer,
FT_UInt buffer_max );
Retrieve the ASCII name of a given glyph in a face. This only works for those faces where FT_HAS_GLYPH_NAMES returns true.
input
| face |
A handle to a source face object. |
| glyph_index |
The glyph index. |
| buffer_max |
The maximum number of bytes available in the buffer. |
output
| buffer |
A pointer to a target buffer where the name is copied to. |
return
FreeType error code. 0 means success.
note
An error is returned if the face doesn't provide glyph names or if the glyph index is invalid. In all cases of failure, the first byte of buffer is set to 0 to indicate an empty name.
The glyph name is truncated to fit within the buffer if it is too long. The returned string is always zero-terminated.
Be aware that FreeType reorders glyph indices internally so that glyph index 0 always corresponds to the ‘missing glyph’ (called ‘.notdef’).
This function has limited capabilities if the config macro FT_CONFIG_OPTION_POSTSCRIPT_NAMES is not defined in ftoption.h: It then works only for fonts that actually embed glyph names (which many recent OpenType fonts do not).
FT_Get_Postscript_Name¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
FT_EXPORT( const char* )
FT_Get_Postscript_Name( FT_Face face );
Retrieve the ASCII PostScript name of a given face, if available. This only works with PostScript, TrueType, and OpenType fonts.
input
| face |
A handle to the source face object. |
return
A pointer to the face's PostScript name. NULL if unavailable.
note
The returned pointer is owned by the face and is destroyed with it.
For variation fonts, this string changes if you select a different instance, and you have to call FT_Get_PostScript_Name again to retrieve it. FreeType follows Adobe TechNote #5902, ‘Generating PostScript Names for Fonts Using OpenType Font Variations’.
https://download.macromedia.com/pub/developer/opentype/tech-notes/5902.AdobePSNameGeneration.html
[Since 2.9] Special PostScript names for named instances are only returned if the named instance is set with FT_Set_Named_Instance (and the font has corresponding entries in its ‘fvar’ table or is the default named instance). If FT_IS_VARIATION returns true, the algorithmically derived PostScript name is provided, not looking up special entries for named instances.
FT_Get_FSType_Flags¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
Return the fsType flags for a font.
input
| face |
A handle to the source face object. |
return
The fsType flags, see FT_FSTYPE_XXX.
note
Use this function rather than directly reading the fs_type field in the PS_FontInfoRec structure, which is only guaranteed to return the correct results for Type 1 fonts.
since
2.3.8
FT_FSTYPE_XXX¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
#define FT_FSTYPE_INSTALLABLE_EMBEDDING 0x0000
#define FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING 0x0002
#define FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING 0x0004
#define FT_FSTYPE_EDITABLE_EMBEDDING 0x0008
#define FT_FSTYPE_NO_SUBSETTING 0x0100
#define FT_FSTYPE_BITMAP_EMBEDDING_ONLY 0x0200
A list of bit flags used in the fsType field of the OS/2 table in a TrueType or OpenType font and the FSType entry in a PostScript font. These bit flags are returned by FT_Get_FSType_Flags; they inform client applications of embedding and subsetting restrictions associated with a font.
See https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf for more details.
values
| FT_FSTYPE_INSTALLABLE_EMBEDDING |
Fonts with no fsType bit set may be embedded and permanently installed on the remote system by an application. |
| FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING |
Fonts that have only this bit set must not be modified, embedded or exchanged in any manner without first obtaining permission of the font software copyright owner. |
| FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING |
The font may be embedded and temporarily loaded on the remote system. Documents containing Preview & Print fonts must be opened ‘read-only’; no edits can be applied to the document. |
| FT_FSTYPE_EDITABLE_EMBEDDING |
The font may be embedded but must only be installed temporarily on other systems. In contrast to Preview & Print fonts, documents containing editable fonts may be opened for reading, editing is permitted, and changes may be saved. |
| FT_FSTYPE_NO_SUBSETTING |
The font may not be subsetted prior to embedding. |
| FT_FSTYPE_BITMAP_EMBEDDING_ONLY |
Only bitmaps contained in the font may be embedded; no outline data may be embedded. If there are no bitmaps available in the font, then the font is unembeddable. |
note
The flags are ORed together, thus more than a single value can be returned.
While the fsType flags can indicate that a font may be embedded, a license with the font vendor may be separately required to use the font in this way.
FT_Get_SubGlyph_Info¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
FT_EXPORT( FT_Error )
FT_Get_SubGlyph_Info( FT_GlyphSlot glyph,
FT_UInt sub_index,
FT_Int *p_index,
FT_UInt *p_flags,
FT_Int *p_arg1,
FT_Int *p_arg2,
FT_Matrix *p_transform );
Retrieve a description of a given subglyph. Only use it if glyph->format is FT_GLYPH_FORMAT_COMPOSITE; an error is returned otherwise.
input
| glyph |
The source glyph slot. |
| sub_index |
The index of the subglyph. Must be less than |
output
| p_index |
The glyph index of the subglyph. |
| p_flags |
The subglyph flags, see |
| p_arg1 |
The subglyph's first argument (if any). |
| p_arg2 |
The subglyph's second argument (if any). |
| p_transform |
The subglyph transformation (if any). |
return
FreeType error code. 0 means success.
note
The values of *p_arg1, *p_arg2, and *p_transform must be interpreted depending on the flags returned in *p_flags. See the OpenType specification for details.
https://docs.microsoft.com/en-us/typography/opentype/spec/glyf#composite-glyph-description
FT_SUBGLYPH_FLAG_XXX¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
#define FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS 1
#define FT_SUBGLYPH_FLAG_ARGS_ARE_XY_VALUES 2
#define FT_SUBGLYPH_FLAG_ROUND_XY_TO_GRID 4
#define FT_SUBGLYPH_FLAG_SCALE 8
#define FT_SUBGLYPH_FLAG_XY_SCALE 0x40
#define FT_SUBGLYPH_FLAG_2X2 0x80
#define FT_SUBGLYPH_FLAG_USE_MY_METRICS 0x200
A list of constants describing subglyphs. Please refer to the ‘glyf’ table description in the OpenType specification for the meaning of the various flags (which get synthesized for non-OpenType subglyphs).
https://docs.microsoft.com/en-us/typography/opentype/spec/glyf#composite-glyph-description
values
| FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS | |
| FT_SUBGLYPH_FLAG_ARGS_ARE_XY_VALUES | |
| FT_SUBGLYPH_FLAG_ROUND_XY_TO_GRID | |
| FT_SUBGLYPH_FLAG_SCALE | |
| FT_SUBGLYPH_FLAG_XY_SCALE | |
| FT_SUBGLYPH_FLAG_2X2 | |
| FT_SUBGLYPH_FLAG_USE_MY_METRICS |