+ + + +

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://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 `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://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	+ +

+ +

+ + + + + + + +