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