Skip to content

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