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