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 :: The platform ID for `string'. */ 74 /* See @TT_PLATFORM_XXX for possible values. */ 75 /* */ 76 /* encoding_id :: The encoding ID for `string'. */ 77 /* See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX, */ 78 /* @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX */ 79 /* for possible values. */ 80 /* */ 81 /* language_id :: The language ID for `string'. */ 82 /* See @TT_MAC_LANGID_XXX and @TT_MS_LANGID_XXX for */ 83 /* possible values. */ 84 /* */ 85 /* Registered OpenType values for `language_id' are */ 86 /* always smaller than 0x8000; values equal or larger */ 87 /* than 0x8000 usually indicate a language tag string */ 88 /* (introduced in OpenType version 1.6). Use function */ 89 /* @FT_Get_Sfnt_LangTag with `language_id' as its */ 90 /* argument to retrieve the associated language tag. */ 91 /* */ 92 /* name_id :: An identifier for `string'. */ 93 /* See @TT_NAME_ID_XXX for possible values. */ 94 /* */ 95 /* string :: The `name' string. Note that its format differs */ 96 /* depending on the (platform,encoding) pair, being */ 97 /* either a string of bytes (without a terminating */ 98 /* NULL byte) or containing UTF-16BE entities. */ 99 /* */ 100 /* string_len :: The length of `string' in bytes. */ 101 /* */ 102 /* <Note> */ 103 /* Please refer to the TrueType or OpenType specification for more */ 104 /* details. */ 105 /* */ 106 typedef struct FT_SfntName_ 107 { 108 FT_UShort platform_id; 109 FT_UShort encoding_id; 110 FT_UShort language_id; 111 FT_UShort name_id; 112 113 FT_Byte* string; /* this string is *not* null-terminated! */ 114 FT_UInt string_len; /* in bytes */ 115 116 } FT_SfntName; 117 118 119 /*************************************************************************/ 120 /* */ 121 /* <Function> */ 122 /* FT_Get_Sfnt_Name_Count */ 123 /* */ 124 /* <Description> */ 125 /* Retrieve the number of name strings in the SFNT `name' table. */ 126 /* */ 127 /* <Input> */ 128 /* face :: A handle to the source face. */ 129 /* */ 130 /* <Return> */ 131 /* The number of strings in the `name' table. */ 132 /* */ 133 FT_EXPORT( FT_UInt ) 134 FT_Get_Sfnt_Name_Count( FT_Face face ); 135 136 137 /*************************************************************************/ 138 /* */ 139 /* <Function> */ 140 /* FT_Get_Sfnt_Name */ 141 /* */ 142 /* <Description> */ 143 /* Retrieve a string of the SFNT `name' table for a given index. */ 144 /* */ 145 /* <Input> */ 146 /* face :: A handle to the source face. */ 147 /* */ 148 /* idx :: The index of the `name' string. */ 149 /* */ 150 /* <Output> */ 151 /* aname :: The indexed @FT_SfntName structure. */ 152 /* */ 153 /* <Return> */ 154 /* FreeType error code. 0~means success. */ 155 /* */ 156 /* <Note> */ 157 /* The `string' array returned in the `aname' structure is not */ 158 /* null-terminated. Note that you don't have to deallocate `string' */ 159 /* by yourself; FreeType takes care of it if you call @FT_Done_Face. */ 160 /* */ 161 /* Use @FT_Get_Sfnt_Name_Count to get the total number of available */ 162 /* `name' table entries, then do a loop until you get the right */ 163 /* platform, encoding, and name ID. */ 164 /* */ 165 /* `name' table format~1 entries can use language tags also, see */ 166 /* @FT_Get_Sfnt_LangTag. */ 167 /* */ 168 FT_EXPORT( FT_Error ) 169 FT_Get_Sfnt_Name( FT_Face face, 170 FT_UInt idx, 171 FT_SfntName *aname ); 172 173 174 /*************************************************************************/ 175 /* */ 176 /* <Struct> */ 177 /* FT_SfntLangTag */ 178 /* */ 179 /* <Description> */ 180 /* A structure to model a language tag entry from an SFNT `name' */ 181 /* table. */ 182 /* */ 183 /* <Fields> */ 184 /* string :: The language tag string, encoded in UTF-16BE */ 185 /* (without trailing NULL bytes). */ 186 /* */ 187 /* string_len :: The length of `string' in *bytes*. */ 188 /* */ 189 /* <Note> */ 190 /* Please refer to the TrueType or OpenType specification for more */ 191 /* details. */ 192 /* */ 193 /* <Since> */ 194 /* 2.8 */ 195 /* */ 196 typedef struct FT_SfntLangTag_ 197 { 198 FT_Byte* string; /* this string is *not* null-terminated! */ 199 FT_UInt string_len; /* in bytes */ 200 201 } FT_SfntLangTag; 202 203 204 /*************************************************************************/ 205 /* */ 206 /* <Function> */ 207 /* FT_Get_Sfnt_LangTag */ 208 /* */ 209 /* <Description> */ 210 /* Retrieve the language tag associated with a language ID of an SFNT */ 211 /* `name' table entry. */ 212 /* */ 213 /* <Input> */ 214 /* face :: A handle to the source face. */ 215 /* */ 216 /* langID :: The language ID, as returned by @FT_Get_Sfnt_Name. */ 217 /* This is always a value larger than 0x8000. */ 218 /* */ 219 /* <Output> */ 220 /* alangTag :: The language tag associated with the `name' table */ 221 /* entry's language ID. */ 222 /* */ 223 /* <Return> */ 224 /* FreeType error code. 0~means success. */ 225 /* */ 226 /* <Note> */ 227 /* The `string' array returned in the `alangTag' structure is not */ 228 /* null-terminated. Note that you don't have to deallocate `string' */ 229 /* by yourself; FreeType takes care of it if you call @FT_Done_Face. */ 230 /* */ 231 /* Only `name' table format~1 supports language tags. For format~0 */ 232 /* tables, this function always returns FT_Err_Invalid_Table. For */ 233 /* invalid format~1 language ID values, FT_Err_Invalid_Argument is */ 234 /* returned. */ 235 /* */ 236 /* <Since> */ 237 /* 2.8 */ 238 /* */ 239 FT_EXPORT( FT_Error ) 240 FT_Get_Sfnt_LangTag( FT_Face face, 241 FT_UInt langID, 242 FT_SfntLangTag *alangTag ); 243 244 245 /* */ 246 247 248 FT_END_HEADER 249 250 #endif /* FTSNAMES_H_ */ 251 252 253 /* END */ 254