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