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