/* SPDX-License-Identifier: MIT OR MPL-2.0 OR LGPL-2.1-or-later OR GPL-2.0-or-later */ /* Copyright 2010, SIL International, All rights reserved. */ #pragma once #include "graphite2/Types.h" #define GR2_VERSION_MAJOR … #define GR2_VERSION_MINOR … #define GR2_VERSION_BUGFIX … #ifdef __cplusplus extern "C" { #endif gr_face; gr_font; gr_feature_ref; gr_feature_val; /** * Returns version information on this engine */ GR2_API void gr_engine_version(int *nMajor, int *nMinor, int *nBugFix); /** * The Face Options allow the application to require that certain tables are * read during face construction. This may be of concern if the appFaceHandle * used in the gr_get_table_fn may change. * The values can be combined */ enum gr_face_options { … }; /** Holds information about a particular Graphite silf table that has been loaded */ struct gr_faceinfo { … }; gr_faceinfo; /** type describing function to retrieve font table information * * @return a pointer to the table in memory. The pointed to memory must exist as * long as the gr_face which makes the call. * @param appFaceHandle is the unique information passed to gr_make_face() * @param name is a 32bit tag to the table name. * @param len returned by this function to say how long the table is in memory. */ gr_get_table_fn; /** type describing function to release any resources allocated by the above get_table table function * * @param appFaceHandle is the unique information passed to gr_make_face() * @param pointer to table memory returned by get_table. */ gr_release_table_fn; /** struct housing function pointers to manage font table buffers for the graphite engine. */ struct gr_face_ops { … }; gr_face_ops; /** Create a gr_face object given application information and a table functions. * * @return gr_face or NULL if the font fails to load for some reason. * @param appFaceHandle This is application specific information that is passed * to the getTable function. The appFaceHandle must stay * alive as long as the gr_face is alive. * @param face_ops Pointer to face specific callback structure for table * management. Must stay alive for the duration of the * call only. * @param faceOptions Bitfield describing various options. See enum gr_face_options for details. */ GR2_API gr_face* gr_make_face_with_ops(const void* appFaceHandle/*non-NULL*/, const gr_face_ops *face_ops, unsigned int faceOptions); /** @deprecated Since v1.2.0 in favour of gr_make_face_with_ops. * Create a gr_face object given application information and a getTable function. * * @return gr_face or NULL if the font fails to load for some reason. * @param appFaceHandle This is application specific information that is passed * to the getTable function. The appFaceHandle must stay * alive as long as the gr_face is alive. * @param getTable Callback function to get table data. * @param faceOptions Bitfield describing various options. See enum gr_face_options for details. */ GR2_DEPRECATED_API gr_face* gr_make_face(const void* appFaceHandle/*non-NULL*/, gr_get_table_fn getTable, unsigned int faceOptions); /** @deprecated Since 1.3.7 this function is now an alias for gr_make_face_with_ops(). * * Create a gr_face object given application information, with subsegmental caching support * * @return gr_face or NULL if the font fails to load. * @param appFaceHandle is a pointer to application specific information that is passed to getTable. * This may not be NULL and must stay alive as long as the gr_face is alive. * @param face_ops Pointer to face specific callback structure for table management. Must stay * alive for the duration of the call only. * @param segCacheMaxSize Unused. * @param faceOptions Bitfield of values from enum gr_face_options */ 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); /** @deprecated Since 1.3.7 this function is now an alias for gr_make_face(). * * Create a gr_face object given application information, with subsegmental caching support. * This function is deprecated as of v1.2.0 in favour of gr_make_face_with_seg_cache_and_ops. * * @return gr_face or NULL if the font fails to load. * @param appFaceHandle is a pointer to application specific information that is passed to getTable. * This may not be NULL and must stay alive as long as the gr_face is alive. * @param getTable The function graphite calls to access font table data * @param segCacheMaxSize How large the segment cache is. * @param faceOptions Bitfield of values from enum gr_face_options */ 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); /** Convert a tag in a string into a gr_uint32 * * @return gr_uint32 tag, zero padded * @param str a nul terminated string of which at most the first 4 characters are read */ GR2_API gr_uint32 gr_str_to_tag(const char *str); /** Convert a gr_uint32 tag into a string * * @param tag contains the tag to convert * @param str is a pointer to a char array of at least size 4 bytes. The first 4 bytes of this array * will be overwritten by this function. No nul is appended. */ GR2_API void gr_tag_to_str(gr_uint32 tag, char *str); /** Get feature values for a given language or default * * @return a copy of the default feature values for a given language. The application must call * gr_featureval_destroy() to free this object when done. * @param pFace The font face to get feature values from * @param langname The language tag to get feature values for. If there is no such language or * langname is 0, the default feature values for the font are returned. * langname is right 0 padded and assumes lowercase. Thus the en langauge * would be 0x656E0000. Langname may also be space padded, thus 0x656E2020. */ GR2_API gr_feature_val* gr_face_featureval_for_lang(const gr_face* pFace, gr_uint32 langname); /** Get feature reference for a given feature id from a face * * @return a feature reference corresponding to the given id. This data is part of the gr_face and * will be freed when the face is destroyed. * @param pFace Font face to get information on. * @param featId Feature id tag to get reference to. */ GR2_API const gr_feature_ref* gr_face_find_fref(const gr_face* pFace, gr_uint32 featId); /** Returns number of feature references in a face **/ GR2_API gr_uint16 gr_face_n_fref(const gr_face* pFace); /** Returns feature reference at given index in face **/ GR2_API const gr_feature_ref* gr_face_fref(const gr_face* pFace, gr_uint16 i); /** Return number of languages the face knows about **/ GR2_API unsigned short gr_face_n_languages(const gr_face* pFace); /** Returns a language id corresponding to a language of given index in the face **/ GR2_API gr_uint32 gr_face_lang_by_index(const gr_face* pFace, gr_uint16 i); /** Destroy the given face and free its memory **/ GR2_API void gr_face_destroy(gr_face *face); /** Returns the number of glyphs in the face **/ GR2_API unsigned short gr_face_n_glyphs(const gr_face* pFace); /** Returns a faceinfo for the face and script **/ GR2_API const gr_faceinfo *gr_face_info(const gr_face *pFace, gr_uint32 script); /** Returns whether the font supports a given Unicode character * * @return true if the character is supported. * @param pFace face to test within * @param usv Unicode Scalar Value of character to test * @param script Tag of script for selecting which set of pseudo glyphs to test. May be NULL. */ GR2_API int gr_face_is_char_supported(const gr_face *pFace, gr_uint32 usv, gr_uint32 script); #ifndef GRAPHITE2_NFILEFACE /** Create gr_face from a font file * * @return gr_face that accesses a font file directly. Returns NULL on failure. * @param filename Full path and filename to font file * @param faceOptions Bitfile from enum gr_face_options to control face options. */ GR2_API gr_face* gr_make_file_face(const char *filename, unsigned int faceOptions); /** @deprecated Since 1.3.7. This function is now an alias for gr_make_file_face(). * * Create gr_face from a font file, with subsegment caching support. * * @return gr_face that accesses a font file directly. Returns NULL on failure. * @param filename Full path and filename to font file * @param segCacheMaxSize Specifies how big to make the cache in segments. * @param faceOptions Bitfield from enum gr_face_options to control face options. */ GR2_DEPRECATED_API gr_face* gr_make_file_face_with_seg_cache(const char *filename, unsigned int segCacheMaxSize, unsigned int faceOptions); #endif // !GRAPHITE2_NFILEFACE /** Create a font from a face * * @return gr_font Call font_destroy to free this font * @param ppm Resolution of the font in pixels per em * @param face Face this font corresponds to. This must stay alive as long as the font is alive. */ GR2_API gr_font* gr_make_font(float ppm, const gr_face *face); /** query function to find the hinted advance of a glyph * * @param appFontHandle is the unique information passed to gr_make_font_with_advance() * @param glyphid is the glyph to retireve the hinted advance for. */ gr_advance_fn; /** struct housing function pointers to manage font hinted metrics for the * graphite engine. */ struct gr_font_ops { … }; gr_font_ops; /** Creates a font with hinted advance width query functions * * @return gr_font to be destroyed via font_destroy * @param ppm size of font in pixels per em * @param appFontHandle font specific information that must stay alive as long * as the font does * @param font_ops pointer font specific callback structure for hinted metrics. * Need only stay alive for the duration of the call. * @param face the face this font corresponds to. Must stay alive as long as * the font does. */ GR2_API gr_font* gr_make_font_with_ops(float ppm, const void* appFontHandle, const gr_font_ops * font_ops, const gr_face *face); /** Creates a font with hinted advance width query function. * This function is deprecated. Use gr_make_font_with_ops instead. * * @return gr_font to be destroyed via font_destroy * @param ppm size of font in pixels per em * @param appFontHandle font specific information that must stay alive as long * as the font does * @param getAdvance callback function reference that returns horizontal advance in pixels for a glyph. * @param face the face this font corresponds to. Must stay alive as long as * the font does. */ GR2_API gr_font* gr_make_font_with_advance_fn(float ppm, const void* appFontHandle, gr_advance_fn getAdvance, const gr_face *face); /** Free a font **/ GR2_API void gr_font_destroy(gr_font *font); /** get a feature value * * @return value of specific feature or 0 if any problems. * @param pfeatureref gr_feature_ref to the feature * @param feats gr_feature_val containing all the values */ GR2_API gr_uint16 gr_fref_feature_value(const gr_feature_ref* pfeatureref, const gr_feature_val* feats); /** set a feature value * * @return false if there were any problems (value out of range, etc.) * @param pfeatureref gr_feature_ref to the feature * @param val value to set the feature to * @param pDest the gr_feature_val containing all the values for all the features */ GR2_API int gr_fref_set_feature_value(const gr_feature_ref* pfeatureref, gr_uint16 val, gr_feature_val* pDest); /** Returns the id tag for a gr_feature_ref **/ GR2_API gr_uint32 gr_fref_id(const gr_feature_ref* pfeatureref); /** Returns number of values a feature may take, given a gr_feature_ref **/ GR2_API gr_uint16 gr_fref_n_values(const gr_feature_ref* pfeatureref); /** Returns the value associated with a particular value in a feature * * @return value * @param pfeatureref gr_feature_ref of the feature of interest * @param settingno Index up to the return value of gr_fref_n_values() of the value */ GR2_API gr_int16 gr_fref_value(const gr_feature_ref* pfeatureref, gr_uint16 settingno); /** Returns a string of the UI name of a feature * * @return string of the UI name, in the encoding form requested. Call gr_label_destroy() after use. * @param pfeatureref gr_feature_ref of the feature * @param langId This is a pointer since the face may not support a string in the requested * language. The actual language of the string is returned in langId * @param utf Encoding form for the string * @param length Used to return the length of the string returned in bytes. */ GR2_API void* gr_fref_label(const gr_feature_ref* pfeatureref, gr_uint16 *langId, enum gr_encform utf, gr_uint32 *length); /** Return a UI string for a possible value of a feature * * @return string of the UI name, in the encoding form requested. nul terminated. Call gr_label_destroy() * after use. * @param pfeatureref gr_feature_ref of the feature * @param settingno Value setting index * @param langId This is a pointer to the requested language. The requested language id is * replaced by the actual language id of the string returned. * @param utf Encoding form for the string * @param length Returns the length of the string returned in bytes. */ 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); /** Destroy a previously returned label string **/ GR2_API void gr_label_destroy(void * label); /** Copies a gr_feature_val **/ GR2_API gr_feature_val* gr_featureval_clone(const gr_feature_val* pfeatures); /** Destroys a gr_feature_val **/ GR2_API void gr_featureval_destroy(gr_feature_val *pfeatures); #ifdef __cplusplus } #endif
Codebase Browser
godot