1 | /* SPDX-License-Identifier: MIT OR MPL-2.0 OR LGPL-2.1-or-later OR GPL-2.0-or-later */ |
2 | /* Copyright 2010, SIL International, All rights reserved. */ |
3 | #pragma once |
4 | |
5 | #include "graphite2/Types.h" |
6 | |
7 | #define GR2_VERSION_MAJOR 1 |
8 | #define GR2_VERSION_MINOR 3 |
9 | #define GR2_VERSION_BUGFIX 14 |
10 | |
11 | #ifdef __cplusplus |
12 | extern "C" |
13 | { |
14 | #endif |
15 | |
16 | typedef struct gr_face gr_face; |
17 | typedef struct gr_font gr_font; |
18 | typedef struct gr_feature_ref gr_feature_ref; |
19 | typedef struct gr_feature_val gr_feature_val; |
20 | |
21 | /** |
22 | * Returns version information on this engine |
23 | */ |
24 | GR2_API void gr_engine_version(int *nMajor, int *nMinor, int *nBugFix); |
25 | |
26 | /** |
27 | * The Face Options allow the application to require that certain tables are |
28 | * read during face construction. This may be of concern if the appFaceHandle |
29 | * used in the gr_get_table_fn may change. |
30 | * The values can be combined |
31 | */ |
32 | enum gr_face_options { |
33 | /** No preload, no cmap caching, fail if the graphite tables are invalid */ |
34 | gr_face_default = 0, |
35 | /** Dumb rendering will be enabled if the graphite tables are invalid. @deprecated Since 1.311 */ |
36 | gr_face_dumbRendering = 1, |
37 | /** preload glyphs at construction time */ |
38 | gr_face_preloadGlyphs = 2, |
39 | /** Cache the lookup from code point to glyph ID at construction time */ |
40 | gr_face_cacheCmap = 4, |
41 | /** Preload everything */ |
42 | gr_face_preloadAll = gr_face_preloadGlyphs | gr_face_cacheCmap |
43 | }; |
44 | |
45 | /** Holds information about a particular Graphite silf table that has been loaded */ |
46 | struct gr_faceinfo { |
47 | gr_uint16 ; /**< The extra_ascent in the GDL, in design units */ |
48 | gr_uint16 ; /**< The extra_descent in the GDL, in design units */ |
49 | gr_uint16 upem; /**< The design units for the font */ |
50 | enum gr_space_contextuals { |
51 | gr_space_unknown = 0, /**< no information is known. */ |
52 | gr_space_none = 1, /**< the space character never occurs in any rules. */ |
53 | gr_space_left_only = 2, /**< the space character only occurs as the first element in a rule. */ |
54 | gr_space_right_only = 3, /**< the space character only occurs as the last element in a rule. */ |
55 | gr_space_either_only = 4, /**< the space character only occurs as the only element in a rule. */ |
56 | gr_space_both = 5, /**< the space character may occur as the first or last element of a rule. */ |
57 | gr_space_cross = 6 /**< the space character occurs in a rule not as a first or last element. */ |
58 | } space_contextuals; |
59 | unsigned int has_bidi_pass : 1; /**< the table specifies that a bidirectional pass should run */ |
60 | unsigned int line_ends : 1; /**< there are line end contextuals somewhere */ |
61 | unsigned int justifies : 1; /**< there are .justify properties set somewhere on some glyphs */ |
62 | }; |
63 | |
64 | typedef struct gr_faceinfo gr_faceinfo; |
65 | |
66 | /** type describing function to retrieve font table information |
67 | * |
68 | * @return a pointer to the table in memory. The pointed to memory must exist as |
69 | * long as the gr_face which makes the call. |
70 | * @param appFaceHandle is the unique information passed to gr_make_face() |
71 | * @param name is a 32bit tag to the table name. |
72 | * @param len returned by this function to say how long the table is in memory. |
73 | */ |
74 | typedef const void *(*gr_get_table_fn)(const void* appFaceHandle, unsigned int name, size_t *len); |
75 | |
76 | /** type describing function to release any resources allocated by the above get_table table function |
77 | * |
78 | * @param appFaceHandle is the unique information passed to gr_make_face() |
79 | * @param pointer to table memory returned by get_table. |
80 | */ |
81 | typedef void (*gr_release_table_fn)(const void* appFaceHandle, const void *table_buffer); |
82 | |
83 | /** struct housing function pointers to manage font table buffers for the graphite engine. */ |
84 | struct gr_face_ops |
85 | { |
86 | /** size in bytes of this structure */ |
87 | size_t size; |
88 | /** a pointer to a function to request a table from the client. */ |
89 | gr_get_table_fn get_table; |
90 | /** is a pointer to a function to notify the client the a table can be released. |
91 | * This can be NULL to signify that the client does not wish to do any release handling. */ |
92 | gr_release_table_fn release_table; |
93 | }; |
94 | typedef struct gr_face_ops gr_face_ops; |
95 | |
96 | /** Create a gr_face object given application information and a table functions. |
97 | * |
98 | * @return gr_face or NULL if the font fails to load for some reason. |
99 | * @param appFaceHandle This is application specific information that is passed |
100 | * to the getTable function. The appFaceHandle must stay |
101 | * alive as long as the gr_face is alive. |
102 | * @param face_ops Pointer to face specific callback structure for table |
103 | * management. Must stay alive for the duration of the |
104 | * call only. |
105 | * @param faceOptions Bitfield describing various options. See enum gr_face_options for details. |
106 | */ |
107 | GR2_API gr_face* gr_make_face_with_ops(const void* appFaceHandle/*non-NULL*/, const gr_face_ops *face_ops, unsigned int faceOptions); |
108 | |
109 | /** @deprecated Since v1.2.0 in favour of gr_make_face_with_ops. |
110 | * Create a gr_face object given application information and a getTable function. |
111 | * |
112 | * @return gr_face or NULL if the font fails to load for some reason. |
113 | * @param appFaceHandle This is application specific information that is passed |
114 | * to the getTable function. The appFaceHandle must stay |
115 | * alive as long as the gr_face is alive. |
116 | * @param getTable Callback function to get table data. |
117 | * @param faceOptions Bitfield describing various options. See enum gr_face_options for details. |
118 | */ |
119 | GR2_DEPRECATED_API gr_face* gr_make_face(const void* appFaceHandle/*non-NULL*/, gr_get_table_fn getTable, unsigned int faceOptions); |
120 | |
121 | /** @deprecated Since 1.3.7 this function is now an alias for gr_make_face_with_ops(). |
122 | * |
123 | * Create a gr_face object given application information, with subsegmental caching support |
124 | * |
125 | * @return gr_face or NULL if the font fails to load. |
126 | * @param appFaceHandle is a pointer to application specific information that is passed to getTable. |
127 | * This may not be NULL and must stay alive as long as the gr_face is alive. |
128 | * @param face_ops Pointer to face specific callback structure for table management. Must stay |
129 | * alive for the duration of the call only. |
130 | * @param segCacheMaxSize Unused. |
131 | * @param faceOptions Bitfield of values from enum gr_face_options |
132 | */ |
133 | GR2_DEPRECATED_API gr_face* gr_make_face_with_seg_cache_and_ops(const void* appFaceHandle, const gr_face_ops *face_ops, unsigned int segCacheMaxSize, unsigned int faceOptions); |
134 | |
135 | /** @deprecated Since 1.3.7 this function is now an alias for gr_make_face(). |
136 | * |
137 | * Create a gr_face object given application information, with subsegmental caching support. |
138 | * This function is deprecated as of v1.2.0 in favour of gr_make_face_with_seg_cache_and_ops. |
139 | * |
140 | * @return gr_face or NULL if the font fails to load. |
141 | * @param appFaceHandle is a pointer to application specific information that is passed to getTable. |
142 | * This may not be NULL and must stay alive as long as the gr_face is alive. |
143 | * @param getTable The function graphite calls to access font table data |
144 | * @param segCacheMaxSize How large the segment cache is. |
145 | * @param faceOptions Bitfield of values from enum gr_face_options |
146 | */ |
147 | GR2_DEPRECATED_API gr_face* gr_make_face_with_seg_cache(const void* appFaceHandle, gr_get_table_fn getTable, unsigned int segCacheMaxSize, unsigned int faceOptions); |
148 | |
149 | /** Convert a tag in a string into a gr_uint32 |
150 | * |
151 | * @return gr_uint32 tag, zero padded |
152 | * @param str a nul terminated string of which at most the first 4 characters are read |
153 | */ |
154 | GR2_API gr_uint32 gr_str_to_tag(const char *str); |
155 | |
156 | /** Convert a gr_uint32 tag into a string |
157 | * |
158 | * @param tag contains the tag to convert |
159 | * @param str is a pointer to a char array of at least size 4 bytes. The first 4 bytes of this array |
160 | * will be overwritten by this function. No nul is appended. |
161 | */ |
162 | GR2_API void gr_tag_to_str(gr_uint32 tag, char *str); |
163 | |
164 | /** Get feature values for a given language or default |
165 | * |
166 | * @return a copy of the default feature values for a given language. The application must call |
167 | * gr_featureval_destroy() to free this object when done. |
168 | * @param pFace The font face to get feature values from |
169 | * @param langname The language tag to get feature values for. If there is no such language or |
170 | * langname is 0, the default feature values for the font are returned. |
171 | * langname is right 0 padded and assumes lowercase. Thus the en langauge |
172 | * would be 0x656E0000. Langname may also be space padded, thus 0x656E2020. |
173 | */ |
174 | GR2_API gr_feature_val* gr_face_featureval_for_lang(const gr_face* pFace, gr_uint32 langname); |
175 | |
176 | /** Get feature reference for a given feature id from a face |
177 | * |
178 | * @return a feature reference corresponding to the given id. This data is part of the gr_face and |
179 | * will be freed when the face is destroyed. |
180 | * @param pFace Font face to get information on. |
181 | * @param featId Feature id tag to get reference to. |
182 | */ |
183 | GR2_API const gr_feature_ref* gr_face_find_fref(const gr_face* pFace, gr_uint32 featId); |
184 | |
185 | /** Returns number of feature references in a face **/ |
186 | GR2_API gr_uint16 gr_face_n_fref(const gr_face* pFace); |
187 | |
188 | /** Returns feature reference at given index in face **/ |
189 | GR2_API const gr_feature_ref* gr_face_fref(const gr_face* pFace, gr_uint16 i); |
190 | |
191 | /** Return number of languages the face knows about **/ |
192 | GR2_API unsigned short gr_face_n_languages(const gr_face* pFace); |
193 | |
194 | /** Returns a language id corresponding to a language of given index in the face **/ |
195 | GR2_API gr_uint32 gr_face_lang_by_index(const gr_face* pFace, gr_uint16 i); |
196 | |
197 | /** Destroy the given face and free its memory **/ |
198 | GR2_API void gr_face_destroy(gr_face *face); |
199 | |
200 | /** Returns the number of glyphs in the face **/ |
201 | GR2_API unsigned short gr_face_n_glyphs(const gr_face* pFace); |
202 | |
203 | /** Returns a faceinfo for the face and script **/ |
204 | GR2_API const gr_faceinfo *gr_face_info(const gr_face *pFace, gr_uint32 script); |
205 | |
206 | /** Returns whether the font supports a given Unicode character |
207 | * |
208 | * @return true if the character is supported. |
209 | * @param pFace face to test within |
210 | * @param usv Unicode Scalar Value of character to test |
211 | * @param script Tag of script for selecting which set of pseudo glyphs to test. May be NULL. |
212 | */ |
213 | GR2_API int gr_face_is_char_supported(const gr_face *pFace, gr_uint32 usv, gr_uint32 script); |
214 | |
215 | #ifndef GRAPHITE2_NFILEFACE |
216 | /** Create gr_face from a font file |
217 | * |
218 | * @return gr_face that accesses a font file directly. Returns NULL on failure. |
219 | * @param filename Full path and filename to font file |
220 | * @param faceOptions Bitfile from enum gr_face_options to control face options. |
221 | */ |
222 | GR2_API gr_face* gr_make_file_face(const char *filename, unsigned int faceOptions); |
223 | |
224 | /** @deprecated Since 1.3.7. This function is now an alias for gr_make_file_face(). |
225 | * |
226 | * Create gr_face from a font file, with subsegment caching support. |
227 | * |
228 | * @return gr_face that accesses a font file directly. Returns NULL on failure. |
229 | * @param filename Full path and filename to font file |
230 | * @param segCacheMaxSize Specifies how big to make the cache in segments. |
231 | * @param faceOptions Bitfield from enum gr_face_options to control face options. |
232 | */ |
233 | GR2_DEPRECATED_API gr_face* gr_make_file_face_with_seg_cache(const char *filename, unsigned int segCacheMaxSize, unsigned int faceOptions); |
234 | #endif // !GRAPHITE2_NFILEFACE |
235 | |
236 | /** Create a font from a face |
237 | * |
238 | * @return gr_font Call font_destroy to free this font |
239 | * @param ppm Resolution of the font in pixels per em |
240 | * @param face Face this font corresponds to. This must stay alive as long as the font is alive. |
241 | */ |
242 | GR2_API gr_font* gr_make_font(float ppm, const gr_face *face); |
243 | |
244 | /** query function to find the hinted advance of a glyph |
245 | * |
246 | * @param appFontHandle is the unique information passed to gr_make_font_with_advance() |
247 | * @param glyphid is the glyph to retireve the hinted advance for. |
248 | */ |
249 | typedef float (*gr_advance_fn)(const void* appFontHandle, gr_uint16 glyphid); |
250 | |
251 | /** struct housing function pointers to manage font hinted metrics for the |
252 | * graphite engine. */ |
253 | struct gr_font_ops |
254 | { |
255 | /** size of the structure in bytes to allow for future extensibility */ |
256 | size_t size; |
257 | /** a pointer to a function to retrieve the hinted |
258 | * advance width of a glyph which the font cannot |
259 | * provide without client assistance. This can be |
260 | * NULL to signify no horizontal hinted metrics are necessary. */ |
261 | gr_advance_fn glyph_advance_x; |
262 | /** a pointer to a function to retrieve the hinted |
263 | * advance height of a glyph which the font cannot |
264 | * provide without client assistance. This can be |
265 | * NULL to signify no horizontal hinted metrics are necessary. */ |
266 | gr_advance_fn glyph_advance_y; |
267 | }; |
268 | typedef struct gr_font_ops gr_font_ops; |
269 | |
270 | /** Creates a font with hinted advance width query functions |
271 | * |
272 | * @return gr_font to be destroyed via font_destroy |
273 | * @param ppm size of font in pixels per em |
274 | * @param appFontHandle font specific information that must stay alive as long |
275 | * as the font does |
276 | * @param font_ops pointer font specific callback structure for hinted metrics. |
277 | * Need only stay alive for the duration of the call. |
278 | * @param face the face this font corresponds to. Must stay alive as long as |
279 | * the font does. |
280 | */ |
281 | GR2_API gr_font* gr_make_font_with_ops(float ppm, const void* appFontHandle, const gr_font_ops * font_ops, const gr_face *face); |
282 | |
283 | /** Creates a font with hinted advance width query function. |
284 | * This function is deprecated. Use gr_make_font_with_ops instead. |
285 | * |
286 | * @return gr_font to be destroyed via font_destroy |
287 | * @param ppm size of font in pixels per em |
288 | * @param appFontHandle font specific information that must stay alive as long |
289 | * as the font does |
290 | * @param getAdvance callback function reference that returns horizontal advance in pixels for a glyph. |
291 | * @param face the face this font corresponds to. Must stay alive as long as |
292 | * the font does. |
293 | */ |
294 | GR2_API gr_font* gr_make_font_with_advance_fn(float ppm, const void* appFontHandle, gr_advance_fn getAdvance, const gr_face *face); |
295 | |
296 | /** Free a font **/ |
297 | GR2_API void gr_font_destroy(gr_font *font); |
298 | |
299 | /** get a feature value |
300 | * |
301 | * @return value of specific feature or 0 if any problems. |
302 | * @param pfeatureref gr_feature_ref to the feature |
303 | * @param feats gr_feature_val containing all the values |
304 | */ |
305 | GR2_API gr_uint16 gr_fref_feature_value(const gr_feature_ref* pfeatureref, const gr_feature_val* feats); |
306 | |
307 | /** set a feature value |
308 | * |
309 | * @return false if there were any problems (value out of range, etc.) |
310 | * @param pfeatureref gr_feature_ref to the feature |
311 | * @param val value to set the feature to |
312 | * @param pDest the gr_feature_val containing all the values for all the features |
313 | */ |
314 | GR2_API int gr_fref_set_feature_value(const gr_feature_ref* pfeatureref, gr_uint16 val, gr_feature_val* pDest); |
315 | |
316 | /** Returns the id tag for a gr_feature_ref **/ |
317 | GR2_API gr_uint32 gr_fref_id(const gr_feature_ref* pfeatureref); |
318 | |
319 | /** Returns number of values a feature may take, given a gr_feature_ref **/ |
320 | GR2_API gr_uint16 gr_fref_n_values(const gr_feature_ref* pfeatureref); |
321 | |
322 | /** Returns the value associated with a particular value in a feature |
323 | * |
324 | * @return value |
325 | * @param pfeatureref gr_feature_ref of the feature of interest |
326 | * @param settingno Index up to the return value of gr_fref_n_values() of the value |
327 | */ |
328 | GR2_API gr_int16 gr_fref_value(const gr_feature_ref* pfeatureref, gr_uint16 settingno); |
329 | |
330 | /** Returns a string of the UI name of a feature |
331 | * |
332 | * @return string of the UI name, in the encoding form requested. Call gr_label_destroy() after use. |
333 | * @param pfeatureref gr_feature_ref of the feature |
334 | * @param langId This is a pointer since the face may not support a string in the requested |
335 | * language. The actual language of the string is returned in langId |
336 | * @param utf Encoding form for the string |
337 | * @param length Used to return the length of the string returned in bytes. |
338 | */ |
339 | GR2_API void* gr_fref_label(const gr_feature_ref* pfeatureref, gr_uint16 *langId, enum gr_encform utf, gr_uint32 *length); |
340 | |
341 | /** Return a UI string for a possible value of a feature |
342 | * |
343 | * @return string of the UI name, in the encoding form requested. nul terminated. Call gr_label_destroy() |
344 | * after use. |
345 | * @param pfeatureref gr_feature_ref of the feature |
346 | * @param settingno Value setting index |
347 | * @param langId This is a pointer to the requested language. The requested language id is |
348 | * replaced by the actual language id of the string returned. |
349 | * @param utf Encoding form for the string |
350 | * @param length Returns the length of the string returned in bytes. |
351 | */ |
352 | GR2_API void* gr_fref_value_label(const gr_feature_ref* pfeatureref, gr_uint16 settingno/*rather than a value*/, gr_uint16 *langId, enum gr_encform utf, gr_uint32 *length); |
353 | |
354 | /** Destroy a previously returned label string **/ |
355 | GR2_API void gr_label_destroy(void * label); |
356 | |
357 | /** Copies a gr_feature_val **/ |
358 | GR2_API gr_feature_val* gr_featureval_clone(const gr_feature_val* pfeatures); |
359 | |
360 | /** Destroys a gr_feature_val **/ |
361 | GR2_API void gr_featureval_destroy(gr_feature_val *pfeatures); |
362 | |
363 | #ifdef __cplusplus |
364 | } |
365 | #endif |
366 | |