2022-12-13 10:05:26 +01:00
/* 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. */
2020-08-11 11:10:23 +02:00
# pragma once
# include "graphite2/Types.h"
# define GR2_VERSION_MAJOR 1
# define GR2_VERSION_MINOR 3
# define GR2_VERSION_BUGFIX 14
# ifdef __cplusplus
extern " C "
{
# endif
typedef struct gr_face gr_face ;
typedef struct gr_font gr_font ;
typedef struct gr_feature_ref gr_feature_ref ;
typedef struct gr_feature_val 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 {
/** No preload, no cmap caching, fail if the graphite tables are invalid */
gr_face_default = 0 ,
/** Dumb rendering will be enabled if the graphite tables are invalid. @deprecated Since 1.311 */
gr_face_dumbRendering = 1 ,
/** preload glyphs at construction time */
gr_face_preloadGlyphs = 2 ,
/** Cache the lookup from code point to glyph ID at construction time */
gr_face_cacheCmap = 4 ,
/** Preload everything */
gr_face_preloadAll = gr_face_preloadGlyphs | gr_face_cacheCmap
} ;
/** Holds information about a particular Graphite silf table that has been loaded */
struct gr_faceinfo {
gr_uint16 extra_ascent ; /**< The extra_ascent in the GDL, in design units */
gr_uint16 extra_descent ; /**< The extra_descent in the GDL, in design units */
gr_uint16 upem ; /**< The design units for the font */
enum gr_space_contextuals {
gr_space_unknown = 0 , /**< no information is known. */
gr_space_none = 1 , /**< the space character never occurs in any rules. */
gr_space_left_only = 2 , /**< the space character only occurs as the first element in a rule. */
gr_space_right_only = 3 , /**< the space character only occurs as the last element in a rule. */
gr_space_either_only = 4 , /**< the space character only occurs as the only element in a rule. */
gr_space_both = 5 , /**< the space character may occur as the first or last element of a rule. */
gr_space_cross = 6 /**< the space character occurs in a rule not as a first or last element. */
} space_contextuals ;
unsigned int has_bidi_pass : 1 ; /**< the table specifies that a bidirectional pass should run */
unsigned int line_ends : 1 ; /**< there are line end contextuals somewhere */
unsigned int justifies : 1 ; /**< there are .justify properties set somewhere on some glyphs */
} ;
typedef 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 32 bit tag to the table name .
* @ param len returned by this function to say how long the table is in memory .
*/
typedef const void * ( * gr_get_table_fn ) ( const void * appFaceHandle , unsigned int name , size_t * len ) ;
/** 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 .
*/
typedef void ( * gr_release_table_fn ) ( const void * appFaceHandle , const void * table_buffer ) ;
/** struct housing function pointers to manage font table buffers for the graphite engine. */
struct gr_face_ops
{
/** size in bytes of this structure */
size_t size ;
/** a pointer to a function to request a table from the client. */
gr_get_table_fn get_table ;
/** is a pointer to a function to notify the client the a table can be released.
* This can be NULL to signify that the client does not wish to do any release handling . */
gr_release_table_fn release_table ;
} ;
typedef 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 .
*/
typedef float ( * gr_advance_fn ) ( const void * appFontHandle , gr_uint16 glyphid ) ;
/** struct housing function pointers to manage font hinted metrics for the
* graphite engine . */
struct gr_font_ops
{
/** size of the structure in bytes to allow for future extensibility */
size_t size ;
/** a pointer to a function to retrieve the hinted
* advance width of a glyph which the font cannot
* provide without client assistance . This can be
* NULL to signify no horizontal hinted metrics are necessary . */
gr_advance_fn glyph_advance_x ;
/** a pointer to a function to retrieve the hinted
* advance height of a glyph which the font cannot
* provide without client assistance . This can be
* NULL to signify no horizontal hinted metrics are necessary . */
gr_advance_fn glyph_advance_y ;
} ;
typedef 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
