jpayne@69: /* GRAPHITE2 LICENSING jpayne@69: jpayne@69: Copyright 2010, SIL International jpayne@69: All rights reserved. jpayne@69: jpayne@69: This library is free software; you can redistribute it and/or modify jpayne@69: it under the terms of the GNU Lesser General Public License as published jpayne@69: by the Free Software Foundation; either version 2.1 of License, or jpayne@69: (at your option) any later version. jpayne@69: jpayne@69: This program is distributed in the hope that it will be useful, jpayne@69: but WITHOUT ANY WARRANTY; without even the implied warranty of jpayne@69: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU jpayne@69: Lesser General Public License for more details. jpayne@69: jpayne@69: You should also have received a copy of the GNU Lesser General Public jpayne@69: License along with this library in the file named "LICENSE". jpayne@69: If not, write to the Free Software Foundation, 51 Franklin Street, jpayne@69: Suite 500, Boston, MA 02110-1335, USA or visit their web page on the jpayne@69: internet at http://www.fsf.org/licenses/lgpl.html. jpayne@69: jpayne@69: Alternatively, the contents of this file may be used under the terms jpayne@69: of the Mozilla Public License (http://mozilla.org/MPL) or the GNU jpayne@69: General Public License, as published by the Free Software Foundation, jpayne@69: either version 2 of the License or (at your option) any later version. jpayne@69: */ jpayne@69: #pragma once jpayne@69: jpayne@69: #include "graphite2/Types.h" jpayne@69: jpayne@69: #define GR2_VERSION_MAJOR 1 jpayne@69: #define GR2_VERSION_MINOR 3 jpayne@69: #define GR2_VERSION_BUGFIX 13 jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: extern "C" jpayne@69: { jpayne@69: #endif jpayne@69: jpayne@69: typedef struct gr_face gr_face; jpayne@69: typedef struct gr_font gr_font; jpayne@69: typedef struct gr_feature_ref gr_feature_ref; jpayne@69: typedef struct gr_feature_val gr_feature_val; jpayne@69: jpayne@69: /** jpayne@69: * Returns version information on this engine jpayne@69: */ jpayne@69: GR2_API void gr_engine_version(int *nMajor, int *nMinor, int *nBugFix); jpayne@69: jpayne@69: /** jpayne@69: * The Face Options allow the application to require that certain tables are jpayne@69: * read during face construction. This may be of concern if the appFaceHandle jpayne@69: * used in the gr_get_table_fn may change. jpayne@69: * The values can be combined jpayne@69: */ jpayne@69: enum gr_face_options { jpayne@69: /** No preload, no cmap caching, fail if the graphite tables are invalid */ jpayne@69: gr_face_default = 0, jpayne@69: /** Dumb rendering will be enabled if the graphite tables are invalid. @deprecated Since 1.311 */ jpayne@69: gr_face_dumbRendering = 1, jpayne@69: /** preload glyphs at construction time */ jpayne@69: gr_face_preloadGlyphs = 2, jpayne@69: /** Cache the lookup from code point to glyph ID at construction time */ jpayne@69: gr_face_cacheCmap = 4, jpayne@69: /** Preload everything */ jpayne@69: gr_face_preloadAll = gr_face_preloadGlyphs | gr_face_cacheCmap jpayne@69: }; jpayne@69: jpayne@69: /** Holds information about a particular Graphite silf table that has been loaded */ jpayne@69: struct gr_faceinfo { jpayne@69: gr_uint16 extra_ascent; /**< The extra_ascent in the GDL, in design units */ jpayne@69: gr_uint16 extra_descent; /**< The extra_descent in the GDL, in design units */ jpayne@69: gr_uint16 upem; /**< The design units for the font */ jpayne@69: enum gr_space_contextuals { jpayne@69: gr_space_unknown = 0, /**< no information is known. */ jpayne@69: gr_space_none = 1, /**< the space character never occurs in any rules. */ jpayne@69: gr_space_left_only = 2, /**< the space character only occurs as the first element in a rule. */ jpayne@69: gr_space_right_only = 3, /**< the space character only occurs as the last element in a rule. */ jpayne@69: gr_space_either_only = 4, /**< the space character only occurs as the only element in a rule. */ jpayne@69: gr_space_both = 5, /**< the space character may occur as the first or last element of a rule. */ jpayne@69: gr_space_cross = 6 /**< the space character occurs in a rule not as a first or last element. */ jpayne@69: } space_contextuals; jpayne@69: unsigned int has_bidi_pass : 1; /**< the table specifies that a bidirectional pass should run */ jpayne@69: unsigned int line_ends : 1; /**< there are line end contextuals somewhere */ jpayne@69: unsigned int justifies : 1; /**< there are .justify properties set somewhere on some glyphs */ jpayne@69: }; jpayne@69: jpayne@69: typedef struct gr_faceinfo gr_faceinfo; jpayne@69: jpayne@69: /** type describing function to retrieve font table information jpayne@69: * jpayne@69: * @return a pointer to the table in memory. The pointed to memory must exist as jpayne@69: * long as the gr_face which makes the call. jpayne@69: * @param appFaceHandle is the unique information passed to gr_make_face() jpayne@69: * @param name is a 32bit tag to the table name. jpayne@69: * @param len returned by this function to say how long the table is in memory. jpayne@69: */ jpayne@69: typedef const void *(*gr_get_table_fn)(const void* appFaceHandle, unsigned int name, size_t *len); jpayne@69: jpayne@69: /** type describing function to release any resources allocated by the above get_table table function jpayne@69: * jpayne@69: * @param appFaceHandle is the unique information passed to gr_make_face() jpayne@69: * @param pointer to table memory returned by get_table. jpayne@69: */ jpayne@69: typedef void (*gr_release_table_fn)(const void* appFaceHandle, const void *table_buffer); jpayne@69: jpayne@69: /** struct housing function pointers to manage font table buffers for the graphite engine. */ jpayne@69: struct gr_face_ops jpayne@69: { jpayne@69: /** size in bytes of this structure */ jpayne@69: size_t size; jpayne@69: /** a pointer to a function to request a table from the client. */ jpayne@69: gr_get_table_fn get_table; jpayne@69: /** is a pointer to a function to notify the client the a table can be released. jpayne@69: * This can be NULL to signify that the client does not wish to do any release handling. */ jpayne@69: gr_release_table_fn release_table; jpayne@69: }; jpayne@69: typedef struct gr_face_ops gr_face_ops; jpayne@69: jpayne@69: /** Create a gr_face object given application information and a table functions. jpayne@69: * jpayne@69: * @return gr_face or NULL if the font fails to load for some reason. jpayne@69: * @param appFaceHandle This is application specific information that is passed jpayne@69: * to the getTable function. The appFaceHandle must stay jpayne@69: * alive as long as the gr_face is alive. jpayne@69: * @param face_ops Pointer to face specific callback structure for table jpayne@69: * management. Must stay alive for the duration of the jpayne@69: * call only. jpayne@69: * @param faceOptions Bitfield describing various options. See enum gr_face_options for details. jpayne@69: */ jpayne@69: GR2_API gr_face* gr_make_face_with_ops(const void* appFaceHandle/*non-NULL*/, const gr_face_ops *face_ops, unsigned int faceOptions); jpayne@69: jpayne@69: /** @deprecated Since v1.2.0 in favour of gr_make_face_with_ops. jpayne@69: * Create a gr_face object given application information and a getTable function. jpayne@69: * jpayne@69: * @return gr_face or NULL if the font fails to load for some reason. jpayne@69: * @param appFaceHandle This is application specific information that is passed jpayne@69: * to the getTable function. The appFaceHandle must stay jpayne@69: * alive as long as the gr_face is alive. jpayne@69: * @param getTable Callback function to get table data. jpayne@69: * @param faceOptions Bitfield describing various options. See enum gr_face_options for details. jpayne@69: */ jpayne@69: GR2_DEPRECATED_API gr_face* gr_make_face(const void* appFaceHandle/*non-NULL*/, gr_get_table_fn getTable, unsigned int faceOptions); jpayne@69: jpayne@69: /** @deprecated Since 1.3.7 this function is now an alias for gr_make_face_with_ops(). jpayne@69: * jpayne@69: * Create a gr_face object given application information, with subsegmental caching support jpayne@69: * jpayne@69: * @return gr_face or NULL if the font fails to load. jpayne@69: * @param appFaceHandle is a pointer to application specific information that is passed to getTable. jpayne@69: * This may not be NULL and must stay alive as long as the gr_face is alive. jpayne@69: * @param face_ops Pointer to face specific callback structure for table management. Must stay jpayne@69: * alive for the duration of the call only. jpayne@69: * @param segCacheMaxSize Unused. jpayne@69: * @param faceOptions Bitfield of values from enum gr_face_options jpayne@69: */ jpayne@69: 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); jpayne@69: jpayne@69: /** @deprecated Since 1.3.7 this function is now an alias for gr_make_face(). jpayne@69: * jpayne@69: * Create a gr_face object given application information, with subsegmental caching support. jpayne@69: * This function is deprecated as of v1.2.0 in favour of gr_make_face_with_seg_cache_and_ops. jpayne@69: * jpayne@69: * @return gr_face or NULL if the font fails to load. jpayne@69: * @param appFaceHandle is a pointer to application specific information that is passed to getTable. jpayne@69: * This may not be NULL and must stay alive as long as the gr_face is alive. jpayne@69: * @param getTable The function graphite calls to access font table data jpayne@69: * @param segCacheMaxSize How large the segment cache is. jpayne@69: * @param faceOptions Bitfield of values from enum gr_face_options jpayne@69: */ jpayne@69: 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); jpayne@69: jpayne@69: /** Convert a tag in a string into a gr_uint32 jpayne@69: * jpayne@69: * @return gr_uint32 tag, zero padded jpayne@69: * @param str a nul terminated string of which at most the first 4 characters are read jpayne@69: */ jpayne@69: GR2_API gr_uint32 gr_str_to_tag(const char *str); jpayne@69: jpayne@69: /** Convert a gr_uint32 tag into a string jpayne@69: * jpayne@69: * @param tag contains the tag to convert jpayne@69: * @param str is a pointer to a char array of at least size 4 bytes. The first 4 bytes of this array jpayne@69: * will be overwritten by this function. No nul is appended. jpayne@69: */ jpayne@69: GR2_API void gr_tag_to_str(gr_uint32 tag, char *str); jpayne@69: jpayne@69: /** Get feature values for a given language or default jpayne@69: * jpayne@69: * @return a copy of the default feature values for a given language. The application must call jpayne@69: * gr_featureval_destroy() to free this object when done. jpayne@69: * @param pFace The font face to get feature values from jpayne@69: * @param langname The language tag to get feature values for. If there is no such language or jpayne@69: * langname is 0, the default feature values for the font are returned. jpayne@69: * langname is right 0 padded and assumes lowercase. Thus the en langauge jpayne@69: * would be 0x656E0000. Langname may also be space padded, thus 0x656E2020. jpayne@69: */ jpayne@69: GR2_API gr_feature_val* gr_face_featureval_for_lang(const gr_face* pFace, gr_uint32 langname); jpayne@69: jpayne@69: /** Get feature reference for a given feature id from a face jpayne@69: * jpayne@69: * @return a feature reference corresponding to the given id. This data is part of the gr_face and jpayne@69: * will be freed when the face is destroyed. jpayne@69: * @param pFace Font face to get information on. jpayne@69: * @param featId Feature id tag to get reference to. jpayne@69: */ jpayne@69: GR2_API const gr_feature_ref* gr_face_find_fref(const gr_face* pFace, gr_uint32 featId); jpayne@69: jpayne@69: /** Returns number of feature references in a face **/ jpayne@69: GR2_API gr_uint16 gr_face_n_fref(const gr_face* pFace); jpayne@69: jpayne@69: /** Returns feature reference at given index in face **/ jpayne@69: GR2_API const gr_feature_ref* gr_face_fref(const gr_face* pFace, gr_uint16 i); jpayne@69: jpayne@69: /** Return number of languages the face knows about **/ jpayne@69: GR2_API unsigned short gr_face_n_languages(const gr_face* pFace); jpayne@69: jpayne@69: /** Returns a language id corresponding to a language of given index in the face **/ jpayne@69: GR2_API gr_uint32 gr_face_lang_by_index(const gr_face* pFace, gr_uint16 i); jpayne@69: jpayne@69: /** Destroy the given face and free its memory **/ jpayne@69: GR2_API void gr_face_destroy(gr_face *face); jpayne@69: jpayne@69: /** Returns the number of glyphs in the face **/ jpayne@69: GR2_API unsigned short gr_face_n_glyphs(const gr_face* pFace); jpayne@69: jpayne@69: /** Returns a faceinfo for the face and script **/ jpayne@69: GR2_API const gr_faceinfo *gr_face_info(const gr_face *pFace, gr_uint32 script); jpayne@69: jpayne@69: /** Returns whether the font supports a given Unicode character jpayne@69: * jpayne@69: * @return true if the character is supported. jpayne@69: * @param pFace face to test within jpayne@69: * @param usv Unicode Scalar Value of character to test jpayne@69: * @param script Tag of script for selecting which set of pseudo glyphs to test. May be NULL. jpayne@69: */ jpayne@69: GR2_API int gr_face_is_char_supported(const gr_face *pFace, gr_uint32 usv, gr_uint32 script); jpayne@69: jpayne@69: #ifndef GRAPHITE2_NFILEFACE jpayne@69: /** Create gr_face from a font file jpayne@69: * jpayne@69: * @return gr_face that accesses a font file directly. Returns NULL on failure. jpayne@69: * @param filename Full path and filename to font file jpayne@69: * @param faceOptions Bitfile from enum gr_face_options to control face options. jpayne@69: */ jpayne@69: GR2_API gr_face* gr_make_file_face(const char *filename, unsigned int faceOptions); jpayne@69: jpayne@69: /** @deprecated Since 1.3.7. This function is now an alias for gr_make_file_face(). jpayne@69: * jpayne@69: * Create gr_face from a font file, with subsegment caching support. jpayne@69: * jpayne@69: * @return gr_face that accesses a font file directly. Returns NULL on failure. jpayne@69: * @param filename Full path and filename to font file jpayne@69: * @param segCacheMaxSize Specifies how big to make the cache in segments. jpayne@69: * @param faceOptions Bitfield from enum gr_face_options to control face options. jpayne@69: */ jpayne@69: GR2_DEPRECATED_API gr_face* gr_make_file_face_with_seg_cache(const char *filename, unsigned int segCacheMaxSize, unsigned int faceOptions); jpayne@69: #endif // !GRAPHITE2_NFILEFACE jpayne@69: jpayne@69: /** Create a font from a face jpayne@69: * jpayne@69: * @return gr_font Call font_destroy to free this font jpayne@69: * @param ppm Resolution of the font in pixels per em jpayne@69: * @param face Face this font corresponds to. This must stay alive as long as the font is alive. jpayne@69: */ jpayne@69: GR2_API gr_font* gr_make_font(float ppm, const gr_face *face); jpayne@69: jpayne@69: /** query function to find the hinted advance of a glyph jpayne@69: * jpayne@69: * @param appFontHandle is the unique information passed to gr_make_font_with_advance() jpayne@69: * @param glyphid is the glyph to retireve the hinted advance for. jpayne@69: */ jpayne@69: typedef float (*gr_advance_fn)(const void* appFontHandle, gr_uint16 glyphid); jpayne@69: jpayne@69: /** struct housing function pointers to manage font hinted metrics for the jpayne@69: * graphite engine. */ jpayne@69: struct gr_font_ops jpayne@69: { jpayne@69: /** size of the structure in bytes to allow for future extensibility */ jpayne@69: size_t size; jpayne@69: /** a pointer to a function to retrieve the hinted jpayne@69: * advance width of a glyph which the font cannot jpayne@69: * provide without client assistance. This can be jpayne@69: * NULL to signify no horizontal hinted metrics are necessary. */ jpayne@69: gr_advance_fn glyph_advance_x; jpayne@69: /** a pointer to a function to retrieve the hinted jpayne@69: * advance height of a glyph which the font cannot jpayne@69: * provide without client assistance. This can be jpayne@69: * NULL to signify no horizontal hinted metrics are necessary. */ jpayne@69: gr_advance_fn glyph_advance_y; jpayne@69: }; jpayne@69: typedef struct gr_font_ops gr_font_ops; jpayne@69: jpayne@69: /** Creates a font with hinted advance width query functions jpayne@69: * jpayne@69: * @return gr_font to be destroyed via font_destroy jpayne@69: * @param ppm size of font in pixels per em jpayne@69: * @param appFontHandle font specific information that must stay alive as long jpayne@69: * as the font does jpayne@69: * @param font_ops pointer font specific callback structure for hinted metrics. jpayne@69: * Need only stay alive for the duration of the call. jpayne@69: * @param face the face this font corresponds to. Must stay alive as long as jpayne@69: * the font does. jpayne@69: */ jpayne@69: GR2_API gr_font* gr_make_font_with_ops(float ppm, const void* appFontHandle, const gr_font_ops * font_ops, const gr_face *face); jpayne@69: jpayne@69: /** Creates a font with hinted advance width query function. jpayne@69: * This function is deprecated. Use gr_make_font_with_ops instead. jpayne@69: * jpayne@69: * @return gr_font to be destroyed via font_destroy jpayne@69: * @param ppm size of font in pixels per em jpayne@69: * @param appFontHandle font specific information that must stay alive as long jpayne@69: * as the font does jpayne@69: * @param getAdvance callback function reference that returns horizontal advance in pixels for a glyph. jpayne@69: * @param face the face this font corresponds to. Must stay alive as long as jpayne@69: * the font does. jpayne@69: */ jpayne@69: GR2_API gr_font* gr_make_font_with_advance_fn(float ppm, const void* appFontHandle, gr_advance_fn getAdvance, const gr_face *face); jpayne@69: jpayne@69: /** Free a font **/ jpayne@69: GR2_API void gr_font_destroy(gr_font *font); jpayne@69: jpayne@69: /** get a feature value jpayne@69: * jpayne@69: * @return value of specific feature or 0 if any problems. jpayne@69: * @param pfeatureref gr_feature_ref to the feature jpayne@69: * @param feats gr_feature_val containing all the values jpayne@69: */ jpayne@69: GR2_API gr_uint16 gr_fref_feature_value(const gr_feature_ref* pfeatureref, const gr_feature_val* feats); jpayne@69: jpayne@69: /** set a feature value jpayne@69: * jpayne@69: * @return false if there were any problems (value out of range, etc.) jpayne@69: * @param pfeatureref gr_feature_ref to the feature jpayne@69: * @param val value to set the feature to jpayne@69: * @param pDest the gr_feature_val containing all the values for all the features jpayne@69: */ jpayne@69: GR2_API int gr_fref_set_feature_value(const gr_feature_ref* pfeatureref, gr_uint16 val, gr_feature_val* pDest); jpayne@69: jpayne@69: /** Returns the id tag for a gr_feature_ref **/ jpayne@69: GR2_API gr_uint32 gr_fref_id(const gr_feature_ref* pfeatureref); jpayne@69: jpayne@69: /** Returns number of values a feature may take, given a gr_feature_ref **/ jpayne@69: GR2_API gr_uint16 gr_fref_n_values(const gr_feature_ref* pfeatureref); jpayne@69: jpayne@69: /** Returns the value associated with a particular value in a feature jpayne@69: * jpayne@69: * @return value jpayne@69: * @param pfeatureref gr_feature_ref of the feature of interest jpayne@69: * @param settingno Index up to the return value of gr_fref_n_values() of the value jpayne@69: */ jpayne@69: GR2_API gr_int16 gr_fref_value(const gr_feature_ref* pfeatureref, gr_uint16 settingno); jpayne@69: jpayne@69: /** Returns a string of the UI name of a feature jpayne@69: * jpayne@69: * @return string of the UI name, in the encoding form requested. Call gr_label_destroy() after use. jpayne@69: * @param pfeatureref gr_feature_ref of the feature jpayne@69: * @param langId This is a pointer since the face may not support a string in the requested jpayne@69: * language. The actual language of the string is returned in langId jpayne@69: * @param utf Encoding form for the string jpayne@69: * @param length Used to return the length of the string returned in bytes. jpayne@69: */ jpayne@69: GR2_API void* gr_fref_label(const gr_feature_ref* pfeatureref, gr_uint16 *langId, enum gr_encform utf, gr_uint32 *length); jpayne@69: jpayne@69: /** Return a UI string for a possible value of a feature jpayne@69: * jpayne@69: * @return string of the UI name, in the encoding form requested. nul terminated. Call gr_label_destroy() jpayne@69: * after use. jpayne@69: * @param pfeatureref gr_feature_ref of the feature jpayne@69: * @param settingno Value setting index jpayne@69: * @param langId This is a pointer to the requested language. The requested language id is jpayne@69: * replaced by the actual language id of the string returned. jpayne@69: * @param utf Encoding form for the string jpayne@69: * @param length Returns the length of the string returned in bytes. jpayne@69: */ jpayne@69: 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); jpayne@69: jpayne@69: /** Destroy a previously returned label string **/ jpayne@69: GR2_API void gr_label_destroy(void * label); jpayne@69: jpayne@69: /** Copies a gr_feature_val **/ jpayne@69: GR2_API gr_feature_val* gr_featureval_clone(const gr_feature_val* pfeatures); jpayne@69: jpayne@69: /** Destroys a gr_feature_val **/ jpayne@69: GR2_API void gr_featureval_destroy(gr_feature_val *pfeatures); jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: } jpayne@69: #endif