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 */