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