+ + + +

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

+

+ + + + + + + +