ref: 7438235b42e9d425888c68519d1e05dd2b69fff7
dir: /include/freetype/ftsnames.h/
/**************************************************************************** * * ftsnames.h * * Simple interface to access SFNT 'name' tables (which are used * to hold font names, copyright info, notices, etc.) (specification). * * This is _not_ used to retrieve glyph names! * * Copyright (C) 1996-2020 by * David Turner, Robert Wilhelm, and Werner Lemberg. * * This file is part of the FreeType project, and may only be used, * modified, and distributed under the terms of the FreeType project * license, LICENSE.TXT. By continuing to use, modify, or distribute * this file you indicate that you have read the license and * understand and accept it fully. * */ #ifndef FTSNAMES_H_ #define FTSNAMES_H_ #include <freetype/freetype.h> #include <freetype/ftparams.h> #ifdef FREETYPE_H #error "freetype.h of FreeType 1 has been loaded!" #error "Please fix the directory search order for header files" #error "so that freetype.h of FreeType 2 is found first." #endif FT_BEGIN_HEADER /************************************************************************** * * @section: * sfnt_names * * @title: * SFNT Names * * @abstract: * Access the names embedded in TrueType and OpenType files. * * @description: * 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! * */ /************************************************************************** * * @struct: * FT_SfntName * * @description: * 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. */ 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; /************************************************************************** * * @function: * FT_Get_Sfnt_Name_Count * * @description: * 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_EXPORT( FT_UInt ) FT_Get_Sfnt_Name_Count( FT_Face face ); /************************************************************************** * * @function: * FT_Get_Sfnt_Name * * @description: * 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_EXPORT( FT_Error ) FT_Get_Sfnt_Name( FT_Face face, FT_UInt idx, FT_SfntName *aname ); /************************************************************************** * * @struct: * FT_SfntLangTag * * @description: * 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 */ typedef struct FT_SfntLangTag_ { FT_Byte* string; /* this string is *not* null-terminated! */ FT_UInt string_len; /* in bytes */ } FT_SfntLangTag; /************************************************************************** * * @function: * FT_Get_Sfnt_LangTag * * @description: * 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 */ FT_EXPORT( FT_Error ) FT_Get_Sfnt_LangTag( FT_Face face, FT_UInt langID, FT_SfntLangTag *alangTag ); /* */ FT_END_HEADER #endif /* FTSNAMES_H_ */ /* END */