Skip to content

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).

      FT_EXPORT( FT_UInt )
      FT_Get_Name_Index( FT_Face           face,
                         const FT_String*  glyph_name );

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).

      FT_EXPORT( FT_UShort )
      FT_Get_FSType_Flags( FT_Face  face );

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://adobe-type-tools.github.io/font-tech-notes/pdfs/AcrobatDC_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 `glyph->num_subglyphs`.

#### output

p_index | The glyph index of the subglyph.
p_flags | The subglyph flags, see `FT_SUBGLYPH_FLAG_XXX`.
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://learn.microsoft.com/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://learn.microsoft.com/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 |