FreeType » Docs » Format-Specific API » SFNT Names

SFNT Names¶

Synopsis¶

The TrueType and OpenType specifications allow the inclusion of a special names table (‘name’) in font files. This table contains textual (and internationalized) information regarding the font, like family name, copyright, version, etc.

The definitions below are used to access them if available.

Note that this has nothing to do with glyph names!

FT_SfntName¶

Defined in FT_SFNT_NAMES_H (freetype/ftsnames.h).

  typedef struct  FT_SfntName_
  {
    FT_UShort  platform_id;
    FT_UShort  encoding_id;
    FT_UShort  language_id;
    FT_UShort  name_id;

    FT_Byte*   string;      /* this string is *not* null-terminated! */
    FT_UInt    string_len;  /* in bytes                              */

  } FT_SfntName;

A structure used to model an SFNT ‘name’ table entry.

fields

platform_id	The platform ID for `string`. See `TT_PLATFORM_XXX` for possible values.
encoding_id	The encoding ID for `string`. See `TT_APPLE_ID_XXX`, `TT_MAC_ID_XXX`, `TT_ISO_ID_XXX`, `TT_MS_ID_XXX`, and `TT_ADOBE_ID_XXX` for possible values.
language_id	The language ID for `string`. See `TT_MAC_LANGID_XXX` and `TT_MS_LANGID_XXX` for possible values. Registered OpenType values for `language_id` are always smaller than 0x8000; values equal or larger than 0x8000 usually indicate a language tag string (introduced in OpenType version 1.6). Use function `FT_Get_Sfnt_LangTag` with `language_id` as its argument to retrieve the associated language tag.
name_id	An identifier for `string`. See `TT_NAME_ID_XXX` for possible values.
string	The ‘name’ string. Note that its format differs depending on the (platform,encoding) pair, being either a string of bytes (without a terminating `NULL` byte) or containing UTF-16BE entities.
string_len	The length of `string` in bytes.

note

Please refer to the TrueType or OpenType specification for more details.

FT_Get_Sfnt_Name_Count¶

Defined in FT_SFNT_NAMES_H (freetype/ftsnames.h).

  FT_EXPORT( FT_UInt )
  FT_Get_Sfnt_Name_Count( FT_Face  face );

Retrieve the number of name strings in the SFNT ‘name’ table.

input

face	A handle to the source face.

return

The number of strings in the ‘name’ table.

note

This function always returns an error if the config macro TT_CONFIG_OPTION_SFNT_NAMES is not defined in ftoption.h.

FT_Get_Sfnt_Name¶

Defined in FT_SFNT_NAMES_H (freetype/ftsnames.h).

  FT_EXPORT( FT_Error )
  FT_Get_Sfnt_Name( FT_Face       face,
                    FT_UInt       idx,
                    FT_SfntName  *aname );

Retrieve a string of the SFNT ‘name’ table for a given index.

input

face	A handle to the source face.
idx	The index of the ‘name’ string.

output

aname

The indexed FT_SfntName structure.

return

FreeType error code. 0 means success.

note

The string array returned in the aname structure is not null-terminated. Note that you don't have to deallocate string by yourself; FreeType takes care of it if you call FT_Done_Face.

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.

‘name’ table format 1 entries can use language tags also, see FT_Get_Sfnt_LangTag.

This function always returns an error if the config macro TT_CONFIG_OPTION_SFNT_NAMES is not defined in ftoption.h.

FT_SfntLangTag¶

Defined in FT_SFNT_NAMES_H (freetype/ftsnames.h).

  typedef struct  FT_SfntLangTag_
  {
    FT_Byte*  string;      /* this string is *not* null-terminated! */
    FT_UInt   string_len;  /* in bytes                              */

  } FT_SfntLangTag;

A structure to model a language tag entry from an SFNT ‘name’ table.

fields

string	The language tag string, encoded in UTF-16BE (without trailing `NULL` bytes).
string_len	The length of `string` in bytes.

note

Please refer to the TrueType or OpenType specification for more details.

since

2.8

FT_Get_Sfnt_LangTag¶

Defined in FT_SFNT_NAMES_H (freetype/ftsnames.h).

  FT_EXPORT( FT_Error )
  FT_Get_Sfnt_LangTag( FT_Face          face,
                       FT_UInt          langID,
                       FT_SfntLangTag  *alangTag );

Retrieve the language tag associated with a language ID of an SFNT ‘name’ table entry.

input

face	A handle to the source face.
langID	The language ID, as returned by `FT_Get_Sfnt_Name`. This is always a value larger than 0x8000.

output

alangTag

The language tag associated with the ‘name’ table entry's language ID.

return

FreeType error code. 0 means success.

note

The string array returned in the alangTag structure is not null-terminated. Note that you don't have to deallocate string by yourself; FreeType takes care of it if you call FT_Done_Face.

Only ‘name’ table format 1 supports language tags. For format 0 tables, this function always returns FT_Err_Invalid_Table. For invalid format 1 language ID values, FT_Err_Invalid_Argument is returned.

This function always returns an error if the config macro TT_CONFIG_OPTION_SFNT_NAMES is not defined in ftoption.h.

since

2.8