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