Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/graphite2/Font.h @ 69:33d812a61356

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