1 /**************************************************************************** 2 * 3 * ftsnames.h 4 * 5 * Simple interface to access SFNT `name' tables (which are used 6 * to hold font names, copyright info, notices, etc.) (specification). 7 * 8 * This is _not_ used to retrieve glyph names! 9 * 10 * Copyright 1996-2018 by 11 * David Turner, Robert Wilhelm, and Werner Lemberg. 12 * 13 * This file is part of the FreeType project, and may only be used, 14 * modified, and distributed under the terms of the FreeType project 15 * license, LICENSE.TXT. By continuing to use, modify, or distribute 16 * this file you indicate that you have read the license and 17 * understand and accept it fully. 18 * 19 */ 20 21 22 #ifndef FTSNAMES_H_ 23 #define FTSNAMES_H_ 24 25 26 #include <ft2build.h> 27 #include FT_FREETYPE_H 28 #include FT_PARAMETER_TAGS_H 29 30 #ifdef FREETYPE_H 31 #error "freetype.h of FreeType 1 has been loaded!" 32 #error "Please fix the directory search order for header files" 33 #error "so that freetype.h of FreeType 2 is found first." 34 #endif 35 36 37 FT_BEGIN_HEADER 38 39 40 /************************************************************************** 41 * 42 * @section: 43 * sfnt_names 44 * 45 * @title: 46 * SFNT Names 47 * 48 * @abstract: 49 * Access the names embedded in TrueType and OpenType files. 50 * 51 * @description: 52 * The TrueType and OpenType specifications allow the inclusion of 53 * a special names table (`name') in font files. This table contains 54 * textual (and internationalized) information regarding the font, 55 * like family name, copyright, version, etc. 56 * 57 * The definitions below are used to access them if available. 58 * 59 * Note that this has nothing to do with glyph names! 60 * 61 */ 62 63 64 /************************************************************************** 65 * 66 * @struct: 67 * FT_SfntName 68 * 69 * @description: 70 * A structure used to model an SFNT `name' table entry. 71 * 72 * @fields: 73 * platform_id :: 74 * The platform ID for `string'. 75 * See @TT_PLATFORM_XXX for possible values. 76 * 77 * encoding_id :: 78 * The encoding ID for `string'. 79 * See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, 80 * @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX 81 * for possible values. 82 * 83 * language_id :: 84 * The language ID for `string'. 85 * See @TT_MAC_LANGID_XXX and @TT_MS_LANGID_XXX for 86 * possible values. 87 * 88 * Registered OpenType values for `language_id' are 89 * always smaller than 0x8000; values equal or larger 90 * than 0x8000 usually indicate a language tag string 91 * (introduced in OpenType version 1.6). Use function 92 * @FT_Get_Sfnt_LangTag with `language_id' as its 93 * argument to retrieve the associated language tag. 94 * 95 * name_id :: 96 * An identifier for `string'. 97 * See @TT_NAME_ID_XXX for possible values. 98 * 99 * string :: 100 * The `name' string. Note that its format differs 101 * depending on the (platform,encoding) pair, being 102 * either a string of bytes (without a terminating 103 * NULL byte) or containing UTF-16BE entities. 104 * 105 * string_len :: 106 * The length of `string' in bytes. 107 * 108 * @note: 109 * Please refer to the TrueType or OpenType specification for more 110 * details. 111 */ 112 typedef struct FT_SfntName_ 113 { 114 FT_UShort platform_id; 115 FT_UShort encoding_id; 116 FT_UShort language_id; 117 FT_UShort name_id; 118 119 FT_Byte* string; /* this string is *not* null-terminated! */ 120 FT_UInt string_len; /* in bytes */ 121 122 } FT_SfntName; 123 124 125 /************************************************************************** 126 * 127 * @function: 128 * FT_Get_Sfnt_Name_Count 129 * 130 * @description: 131 * Retrieve the number of name strings in the SFNT `name' table. 132 * 133 * @input: 134 * face :: 135 * A handle to the source face. 136 * 137 * @return: 138 * The number of strings in the `name' table. 139 * 140 * @note: 141 * This function always returns an error if the config macro 142 * `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. 143 */ 144 FT_EXPORT( FT_UInt ) 145 FT_Get_Sfnt_Name_Count( FT_Face face ); 146 147 148 /************************************************************************** 149 * 150 * @function: 151 * FT_Get_Sfnt_Name 152 * 153 * @description: 154 * Retrieve a string of the SFNT `name' table for a given index. 155 * 156 * @input: 157 * face :: 158 * A handle to the source face. 159 * 160 * idx :: 161 * The index of the `name' string. 162 * 163 * @output: 164 * aname :: 165 * The indexed @FT_SfntName structure. 166 * 167 * @return: 168 * FreeType error code. 0~means success. 169 * 170 * @note: 171 * The `string' array returned in the `aname' structure is not 172 * null-terminated. Note that you don't have to deallocate `string' 173 * by yourself; FreeType takes care of it if you call @FT_Done_Face. 174 * 175 * Use @FT_Get_Sfnt_Name_Count to get the total number of available 176 * `name' table entries, then do a loop until you get the right 177 * platform, encoding, and name ID. 178 * 179 * `name' table format~1 entries can use language tags also, see 180 * @FT_Get_Sfnt_LangTag. 181 * 182 * This function always returns an error if the config macro 183 * `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. 184 */ 185 FT_EXPORT( FT_Error ) 186 FT_Get_Sfnt_Name( FT_Face face, 187 FT_UInt idx, 188 FT_SfntName *aname ); 189 190 191 /************************************************************************** 192 * 193 * @struct: 194 * FT_SfntLangTag 195 * 196 * @description: 197 * A structure to model a language tag entry from an SFNT `name' 198 * table. 199 * 200 * @fields: 201 * string :: 202 * The language tag string, encoded in UTF-16BE 203 * (without trailing NULL bytes). 204 * 205 * string_len :: 206 * The length of `string' in *bytes*. 207 * 208 * @note: 209 * Please refer to the TrueType or OpenType specification for more 210 * details. 211 * 212 * @since: 213 * 2.8 214 */ 215 typedef struct FT_SfntLangTag_ 216 { 217 FT_Byte* string; /* this string is *not* null-terminated! */ 218 FT_UInt string_len; /* in bytes */ 219 220 } FT_SfntLangTag; 221 222 223 /************************************************************************** 224 * 225 * @function: 226 * FT_Get_Sfnt_LangTag 227 * 228 * @description: 229 * Retrieve the language tag associated with a language ID of an SFNT 230 * `name' table entry. 231 * 232 * @input: 233 * face :: 234 * A handle to the source face. 235 * 236 * langID :: 237 * The language ID, as returned by @FT_Get_Sfnt_Name. 238 * This is always a value larger than 0x8000. 239 * 240 * @output: 241 * alangTag :: 242 * The language tag associated with the `name' table 243 * entry's language ID. 244 * 245 * @return: 246 * FreeType error code. 0~means success. 247 * 248 * @note: 249 * The `string' array returned in the `alangTag' structure is not 250 * null-terminated. Note that you don't have to deallocate `string' 251 * by yourself; FreeType takes care of it if you call @FT_Done_Face. 252 * 253 * Only `name' table format~1 supports language tags. For format~0 254 * tables, this function always returns FT_Err_Invalid_Table. For 255 * invalid format~1 language ID values, FT_Err_Invalid_Argument is 256 * returned. 257 * 258 * This function always returns an error if the config macro 259 * `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'. 260 * 261 * @since: 262 * 2.8 263 */ 264 FT_EXPORT( FT_Error ) 265 FT_Get_Sfnt_LangTag( FT_Face face, 266 FT_UInt langID, 267 FT_SfntLangTag *alangTag ); 268 269 270 /* */ 271 272 273 FT_END_HEADER 274 275 #endif /* FTSNAMES_H_ */ 276 277 278 /* END */ 279