ref: a56e4bf7a243f46632e4e2ccf25d2f50ca132b23
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 1996-2018 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 <ft2build.h> #include FT_FREETYPE_H #include FT_PARAMETER_TAGS_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 */