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
12extern "C"
13{
14#endif
15
16typedef struct gr_face gr_face;
17typedef struct gr_font gr_font;
18typedef struct gr_feature_ref gr_feature_ref;
19typedef struct gr_feature_val gr_feature_val;
20
21/**
22* Returns version information on this engine
23*/
24GR2_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*/
32enum 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 */
46struct gr_faceinfo {
47 gr_uint16 extra_ascent; /**< The extra_ascent in the GDL, in design units */
48 gr_uint16 extra_descent; /**< 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
64typedef 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 */
74typedef 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 */
81typedef 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. */
84struct 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};
94typedef 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 */
107GR2_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 */
119GR2_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 */
133GR2_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 */
147GR2_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 */
154GR2_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 */
162GR2_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 */
174GR2_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 */
183GR2_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 **/
186GR2_API gr_uint16 gr_face_n_fref(const gr_face* pFace);
187
188/** Returns feature reference at given index in face **/
189GR2_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 **/
192GR2_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 **/
195GR2_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 **/
198GR2_API void gr_face_destroy(gr_face *face);
199
200/** Returns the number of glyphs in the face **/
201GR2_API unsigned short gr_face_n_glyphs(const gr_face* pFace);
202
203/** Returns a faceinfo for the face and script **/
204GR2_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 */
213GR2_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 */
222GR2_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 */
233GR2_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 */
242GR2_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 */
249typedef 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. */
253struct 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};
268typedef 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 */
281GR2_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 */
294GR2_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 **/
297GR2_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 */
305GR2_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 */
314GR2_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 **/
317GR2_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 **/
320GR2_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 */
328GR2_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 */
339GR2_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 */
352GR2_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 **/
355GR2_API void gr_label_destroy(void * label);
356
357/** Copies a gr_feature_val **/
358GR2_API gr_feature_val* gr_featureval_clone(const gr_feature_val* pfeatures);
359
360/** Destroys a gr_feature_val **/
361GR2_API void gr_featureval_destroy(gr_feature_val *pfeatures);
362
363#ifdef __cplusplus
364}
365#endif
366