FreeType » Docs » Core API » Character Mapping

Character Mapping¶

Synopsis¶

This section holds functions and structures that are related to mapping character input codes to glyph indices.

Note that for many scripts the simplistic approach used by FreeType of mapping a single character to a single glyph is not valid or possible! In general, a higher-level library like HarfBuzz or ICU should be used for handling text strings.

FT_CharMap¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  typedef struct FT_CharMapRec_*  FT_CharMap;

A handle to a character map (usually abbreviated to ‘charmap’). A charmap is used to translate character codes in a given encoding into glyph indexes for its parent's face. Some font formats may provide several charmaps per font.

Each face object owns zero or more charmaps, but only one of them can be ‘active’, providing the data used by FT_Get_Char_Index or FT_Load_Char.

The list of available charmaps in a face is available through the face->num_charmaps and face->charmaps fields of FT_FaceRec.

The currently active charmap is available as face->charmap. You should call FT_Set_Charmap to change it.

note

When a new face is created (either through FT_New_Face or FT_Open_Face), the library looks for a Unicode charmap within the list and automatically activates it. If there is no Unicode charmap, FreeType doesn't set an ‘active’ charmap.

also

See FT_CharMapRec for the publicly accessible fields of a given character map.

FT_CharMapRec¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  typedef struct  FT_CharMapRec_
  {
    FT_Face      face;
    FT_Encoding  encoding;
    FT_UShort    platform_id;
    FT_UShort    encoding_id;

  } FT_CharMapRec;

The base charmap structure.

fields

face	A handle to the parent face object.
encoding	An `FT_Encoding` tag identifying the charmap. Use this with `FT_Select_Charmap`.
platform_id	An ID number describing the platform for the following encoding ID. This comes directly from the TrueType specification and gets emulated for other formats.
encoding_id	A platform-specific encoding number. This also comes from the TrueType specification and gets emulated similarly.

FT_Encoding¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  typedef enum  FT_Encoding_
  {
    FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ),

    FT_ENC_TAG( FT_ENCODING_MS_SYMBOL, 's', 'y', 'm', 'b' ),
    FT_ENC_TAG( FT_ENCODING_UNICODE,   'u', 'n', 'i', 'c' ),

    FT_ENC_TAG( FT_ENCODING_SJIS,    's', 'j', 'i', 's' ),
    FT_ENC_TAG( FT_ENCODING_PRC,     'g', 'b', ' ', ' ' ),
    FT_ENC_TAG( FT_ENCODING_BIG5,    'b', 'i', 'g', '5' ),
    FT_ENC_TAG( FT_ENCODING_WANSUNG, 'w', 'a', 'n', 's' ),
    FT_ENC_TAG( FT_ENCODING_JOHAB,   'j', 'o', 'h', 'a' ),

    /* for backward compatibility */
    FT_ENCODING_GB2312     = FT_ENCODING_PRC,
    FT_ENCODING_MS_SJIS    = FT_ENCODING_SJIS,
    FT_ENCODING_MS_GB2312  = FT_ENCODING_PRC,
    FT_ENCODING_MS_BIG5    = FT_ENCODING_BIG5,
    FT_ENCODING_MS_WANSUNG = FT_ENCODING_WANSUNG,
    FT_ENCODING_MS_JOHAB   = FT_ENCODING_JOHAB,

    FT_ENC_TAG( FT_ENCODING_ADOBE_STANDARD, 'A', 'D', 'O', 'B' ),
    FT_ENC_TAG( FT_ENCODING_ADOBE_EXPERT,   'A', 'D', 'B', 'E' ),
    FT_ENC_TAG( FT_ENCODING_ADOBE_CUSTOM,   'A', 'D', 'B', 'C' ),
    FT_ENC_TAG( FT_ENCODING_ADOBE_LATIN_1,  'l', 'a', 't', '1' ),

    FT_ENC_TAG( FT_ENCODING_OLD_LATIN_2, 'l', 'a', 't', '2' ),

    FT_ENC_TAG( FT_ENCODING_APPLE_ROMAN, 'a', 'r', 'm', 'n' )

  } FT_Encoding;


  /* these constants are deprecated; use the corresponding `FT_Encoding` */
  /* values instead                                                      */
#define ft_encoding_none            FT_ENCODING_NONE
#define ft_encoding_unicode         FT_ENCODING_UNICODE
#define ft_encoding_symbol          FT_ENCODING_MS_SYMBOL
#define ft_encoding_latin_1         FT_ENCODING_ADOBE_LATIN_1
#define ft_encoding_latin_2         FT_ENCODING_OLD_LATIN_2
#define ft_encoding_sjis            FT_ENCODING_SJIS
#define ft_encoding_gb2312          FT_ENCODING_PRC
#define ft_encoding_big5            FT_ENCODING_BIG5
#define ft_encoding_wansung         FT_ENCODING_WANSUNG
#define ft_encoding_johab           FT_ENCODING_JOHAB

#define ft_encoding_adobe_standard  FT_ENCODING_ADOBE_STANDARD
#define ft_encoding_adobe_expert    FT_ENCODING_ADOBE_EXPERT
#define ft_encoding_adobe_custom    FT_ENCODING_ADOBE_CUSTOM
#define ft_encoding_apple_roman     FT_ENCODING_APPLE_ROMAN

An enumeration to specify character sets supported by charmaps. Used in the FT_Select_Charmap API function.

note

Despite the name, this enumeration lists specific character repertoires (i.e., charsets), and not text encoding methods (e.g., UTF-8, UTF-16, etc.).

Other encodings might be defined in the future.

values

FT_ENCODING_NONE	The encoding value 0 is reserved for all formats except BDF, PCF, and Windows FNT; see below for more information.
FT_ENCODING_UNICODE	The Unicode character set. This value covers all versions of the Unicode repertoire, including ASCII and Latin-1. Most fonts include a Unicode charmap, but not all of them. For example, if you want to access Unicode value U+1F028 (and the font contains it), use value 0x1F028 as the input value for `FT_Get_Char_Index`.
FT_ENCODING_MS_SYMBOL	Microsoft Symbol encoding, used to encode mathematical symbols and wingdings. For more information, see ‘https://www.microsoft.com/typography/otspec/recom.htm#non-standard-symbol-fonts’, ‘http://www.kostis.net/charsets/symbol.htm’, and ‘http://www.kostis.net/charsets/wingding.htm’. This encoding uses character codes from the PUA (Private Unicode Area) in the range U+F020-U+F0FF.
FT_ENCODING_SJIS	Shift JIS encoding for Japanese. More info at ‘https://en.wikipedia.org/wiki/Shift_JIS’. See note on multi-byte encodings below.
FT_ENCODING_PRC	Corresponds to encoding systems mainly for Simplified Chinese as used in People's Republic of China (PRC). The encoding layout is based on GB 2312 and its supersets GBK and GB 18030.
FT_ENCODING_BIG5	Corresponds to an encoding system for Traditional Chinese as used in Taiwan and Hong Kong.
FT_ENCODING_WANSUNG	Corresponds to the Korean encoding system known as Extended Wansung (MS Windows code page 949). For more information see ‘https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt’.
FT_ENCODING_JOHAB	The Korean standard character set (KS C 5601-1992), which corresponds to MS Windows code page 1361. This character set includes all possible Hangul character combinations.
FT_ENCODING_ADOBE_LATIN_1	Corresponds to a Latin-1 encoding as defined in a Type 1 PostScript font. It is limited to 256 character codes.
FT_ENCODING_ADOBE_STANDARD	Adobe Standard encoding, as found in Type 1, CFF, and OpenType/CFF fonts. It is limited to 256 character codes.
FT_ENCODING_ADOBE_EXPERT	Adobe Expert encoding, as found in Type 1, CFF, and OpenType/CFF fonts. It is limited to 256 character codes.
FT_ENCODING_ADOBE_CUSTOM	Corresponds to a custom encoding, as found in Type 1, CFF, and OpenType/CFF fonts. It is limited to 256 character codes.
FT_ENCODING_APPLE_ROMAN	Apple roman encoding. Many TrueType and OpenType fonts contain a charmap for this 8-bit encoding, since older versions of Mac OS are able to use it.
FT_ENCODING_OLD_LATIN_2	This value is deprecated and was neither used nor reported by FreeType. Don't use or test for it.
FT_ENCODING_MS_SJIS	Same as FT_ENCODING_SJIS. Deprecated.
FT_ENCODING_MS_GB2312	Same as FT_ENCODING_PRC. Deprecated.
FT_ENCODING_MS_BIG5	Same as FT_ENCODING_BIG5. Deprecated.
FT_ENCODING_MS_WANSUNG	Same as FT_ENCODING_WANSUNG. Deprecated.
FT_ENCODING_MS_JOHAB	Same as FT_ENCODING_JOHAB. Deprecated.

note

When loading a font, FreeType makes a Unicode charmap active if possible (either if the font provides such a charmap, or if FreeType can synthesize one from PostScript glyph name dictionaries; in either case, the charmap is tagged with FT_ENCODING_UNICODE). If such a charmap is synthesized, it is placed at the first position of the charmap array.

All other encodings are considered legacy and tagged only if explicitly defined in the font file. Otherwise, FT_ENCODING_NONE is used.

FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap is neither Unicode nor ISO-8859-1 (otherwise it is set to FT_ENCODING_UNICODE). Use FT_Get_BDF_Charset_ID to find out which encoding is really present. If, for example, the cs_registry field is ‘KOI8’ and the cs_encoding field is ‘R’, the font is encoded in KOI8-R.

FT_ENCODING_NONE is always set (with a single exception) by the winfonts driver. Use FT_Get_WinFNT_Header and examine the charset field of the FT_WinFNT_HeaderRec structure to find out which encoding is really present. For example, FT_WinFNT_ID_CP1251 (204) means Windows code page 1251 (for Russian).

FT_ENCODING_NONE is set if platform_id is TT_PLATFORM_MACINTOSH and encoding_id is not TT_MAC_ID_ROMAN (otherwise it is set to FT_ENCODING_APPLE_ROMAN).

If platform_id is TT_PLATFORM_MACINTOSH, use the function FT_Get_CMap_Language_ID to query the Mac language ID that may be needed to be able to distinguish Apple encoding variants. See

https://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt

to get an idea how to do that. Basically, if the language ID is 0, don't use it, otherwise subtract 1 from the language ID. Then examine encoding_id. If, for example, encoding_id is TT_MAC_ID_ROMAN and the language ID (minus 1) is TT_MAC_LANGID_GREEK, it is the Greek encoding, not Roman. TT_MAC_ID_ARABIC with TT_MAC_LANGID_FARSI means the Farsi variant of the Arabic encoding.

FT_ENC_TAG¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

#ifndef FT_ENC_TAG

#define FT_ENC_TAG( value, a, b, c, d )                             \
          value = ( ( FT_STATIC_BYTE_CAST( FT_UInt32, a ) << 24 ) | \
                    ( FT_STATIC_BYTE_CAST( FT_UInt32, b ) << 16 ) | \
                    ( FT_STATIC_BYTE_CAST( FT_UInt32, c ) <<  8 ) | \
                      FT_STATIC_BYTE_CAST( FT_UInt32, d )         )

#endif /* FT_ENC_TAG */

This macro converts four-letter tags into an unsigned long. It is used to define ‘encoding’ identifiers (see FT_Encoding).

note

Since many 16-bit compilers don't like 32-bit enumerations, you should redefine this macro in case of problems to something like this:

  #define FT_ENC_TAG( value, a, b, c, d )  value

to get a simple enumeration without assigning special numbers.

FT_Select_Charmap¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  FT_EXPORT( FT_Error )
  FT_Select_Charmap( FT_Face      face,
                     FT_Encoding  encoding );

Select a given charmap by its encoding tag (as listed in freetype.h).

inout

face	A handle to the source face object.

input

encoding

A handle to the selected encoding.

return

FreeType error code. 0 means success.

note

This function returns an error if no charmap in the face corresponds to the encoding queried here.

Because many fonts contain more than a single cmap for Unicode encoding, this function has some special code to select the one that covers Unicode best (‘best’ in the sense that a UCS-4 cmap is preferred to a UCS-2 cmap). It is thus preferable to FT_Set_Charmap in this case.

FT_Set_Charmap¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  FT_EXPORT( FT_Error )
  FT_Set_Charmap( FT_Face     face,
                  FT_CharMap  charmap );

Select a given charmap for character code to glyph index mapping.

inout

face	A handle to the source face object.

input

charmap

A handle to the selected charmap.

return

FreeType error code. 0 means success.

note

This function returns an error if the charmap is not part of the face (i.e., if it is not listed in the face->charmaps table).

It also fails if an OpenType type 14 charmap is selected (which doesn't map character codes to glyph indices at all).

FT_Get_Charmap_Index¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  FT_EXPORT( FT_Int )
  FT_Get_Charmap_Index( FT_CharMap  charmap );

Retrieve index of a given charmap.

input

charmap

A handle to a charmap.

return

The index into the array of character maps within the face to which charmap belongs. If an error occurs, -1 is returned.

FT_Get_Char_Index¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  FT_EXPORT( FT_UInt )
  FT_Get_Char_Index( FT_Face   face,
                     FT_ULong  charcode );

Return the glyph index of a given character code. This function uses the currently selected charmap to do the mapping.

input

face	A handle to the source face object.
charcode	The character code.

return

The glyph index. 0 means ‘undefined character code’.

note

If you use FreeType to manipulate the contents of font files directly, be aware that the glyph index returned by this function doesn't always correspond to the internal indices used within the file. This is done to ensure that value 0 always corresponds to the ‘missing glyph’. If the first glyph is not named ‘.notdef’, then for Type 1 and Type 42 fonts, ‘.notdef’ will be moved into the glyph ID 0 position, and whatever was there will be moved to the position ‘.notdef’ had. For Type 1 fonts, if there is no ‘.notdef’ glyph at all, then one will be created at index 0 and whatever was there will be moved to the last index – Type 42 fonts are considered invalid under this condition.

FT_Get_First_Char¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  FT_EXPORT( FT_ULong )
  FT_Get_First_Char( FT_Face   face,
                     FT_UInt  *agindex );

Return the first character code in the current charmap of a given face, together with its corresponding glyph index.

input

face	A handle to the source face object.

output

agindex

Glyph index of first character code. 0 if charmap is empty.

return

The charmap's first character code.

note

You should use this function together with FT_Get_Next_Char to parse all character codes available in a given charmap. The code should look like this:

  FT_ULong  charcode;
  FT_UInt   gindex;


  charcode = FT_Get_First_Char( face, &gindex );
  while ( gindex != 0 )
  {
    ... do something with (charcode,gindex) pair ...

    charcode = FT_Get_Next_Char( face, charcode, &gindex );
  }

Be aware that character codes can have values up to 0xFFFFFFFF; this might happen for non-Unicode or malformed cmaps. However, even with regular Unicode encoding, so-called ‘last resort fonts’ (using SFNT cmap format 13, see function FT_Get_CMap_Format) normally have entries for all Unicode characters up to 0x1FFFFF, which can cause a lot of iterations.

Note that *agindex is set to 0 if the charmap is empty. The result itself can be 0 in two cases: if the charmap is empty or if the value 0 is the first valid character code.

FT_Get_Next_Char¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  FT_EXPORT( FT_ULong )
  FT_Get_Next_Char( FT_Face    face,
                    FT_ULong   char_code,
                    FT_UInt   *agindex );

Return the next character code in the current charmap of a given face following the value char_code, as well as the corresponding glyph index.

input

face	A handle to the source face object.
char_code	The starting character code.

output

agindex

Glyph index of next character code. 0 if charmap is empty.

return

The charmap's next character code.

note

You should use this function with FT_Get_First_Char to walk over all character codes available in a given charmap. See the note for that function for a simple code example.

Note that *agindex is set to 0 when there are no more codes in the charmap.

FT_Load_Char¶

Defined in FT_FREETYPE_H (freetype/freetype.h).

  FT_EXPORT( FT_Error )
  FT_Load_Char( FT_Face   face,
                FT_ULong  char_code,
                FT_Int32  load_flags );

Load a glyph into the glyph slot of a face object, accessed by its character code.

inout

face	A handle to a target face object where the glyph is loaded.

input

char_code	The glyph's character code, according to the current charmap used in the face.
load_flags	A flag indicating what to load for this glyph. The `FT_LOAD_XXX` constants can be used to control the glyph loading process (e.g., whether the outline should be scaled, whether to load bitmaps or not, whether to hint the outline, etc).

return

FreeType error code. 0 means success.

note

This function simply calls FT_Get_Char_Index and FT_Load_Glyph.

Many fonts contain glyphs that can't be loaded by this function since its glyph indices are not listed in any of the font's charmaps.

If no active cmap is set up (i.e., face->charmap is zero), the call to FT_Get_Char_Index is omitted, and the function behaves identically to FT_Load_Glyph.