Graphiteng
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros
Classes | Macros | Typedefs | Enumerations | Functions
Font.h File Reference
#include "graphite2/Types.h"

Go to the source code of this file.

Classes

struct  gr_faceinfo
 Holds information about a particular Graphite silf table that has been loaded. More...
struct  gr_face_ops
 struct housing function pointers to manage font table buffers for the graphite engine. More...
struct  gr_font_ops
 struct housing function pointers to manage font hinted metrics for the graphite engine. More...

Macros

#define GR2_VERSION_MAJOR   1
#define GR2_VERSION_MINOR   3
#define GR2_VERSION_BUGFIX   5

Typedefs

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
typedef const void *(* gr_get_table_fn )(const void *appFaceHandle, unsigned int name, size_t *len)
 type describing function to retrieve font table information
typedef void(* gr_release_table_fn )(const void *appFaceHandle, const void *table_buffer)
 type describing function to release any resources allocated by the above get_table table function
typedef float(* gr_advance_fn )(const void *appFontHandle, gr_uint16 glyphid)
 query function to find the hinted advance of a glyph

Enumerations

enum  gr_face_options {
  gr_face_default = 0, gr_face_dumbRendering = 1, gr_face_preloadGlyphs = 2, gr_face_cacheCmap = 4,
  gr_face_preloadAll = gr_face_preloadGlyphs | gr_face_cacheCmap
}
 The Face Options allow the application to require that certain tables are read during face construction. More...

Functions

GR2_API void gr_engine_version (int *nMajor, int *nMinor, int *nBugFix)
 Returns version information on this engine.
GR2_API gr_facegr_make_face_with_ops (const void *appFaceHandle, const gr_face_ops *face_ops, unsigned int faceOptions)
 Create a gr_face object given application information and a table functions.
GR2_API gr_facegr_make_face (const void *appFaceHandle, gr_get_table_fn getTable, unsigned int faceOptions)
 Create a gr_face object given application information and a getTable function.
GR2_API gr_facegr_make_face_with_seg_cache_and_ops (const void *appFaceHandle, const gr_face_ops *face_ops, unsigned int segCacheMaxSize, unsigned int faceOptions)
 Create a gr_face object given application information, with subsegmental caching support.
GR2_API gr_facegr_make_face_with_seg_cache (const void *appFaceHandle, gr_get_table_fn getTable, unsigned int segCacheMaxSize, unsigned int faceOptions)
 Create a gr_face object given application information, with subsegmental caching support.
GR2_API gr_uint32 gr_str_to_tag (const char *str)
 Convert a tag in a string into a gr_uint32.
GR2_API void gr_tag_to_str (gr_uint32 tag, char *str)
 Convert a gr_uint32 tag into a string.
GR2_API gr_feature_valgr_face_featureval_for_lang (const gr_face *pFace, gr_uint32 langname)
 Get feature values for a given language or default.
GR2_API const gr_feature_refgr_face_find_fref (const gr_face *pFace, gr_uint32 featId)
 Get feature reference for a given feature id from a face.
GR2_API gr_uint16 gr_face_n_fref (const gr_face *pFace)
 Returns number of feature references in a face.
GR2_API const gr_feature_refgr_face_fref (const gr_face *pFace, gr_uint16 i)
 Returns feature reference at given index in face.
GR2_API unsigned short gr_face_n_languages (const gr_face *pFace)
 Return number of languages the face knows about.
GR2_API gr_uint32 gr_face_lang_by_index (const gr_face *pFace, gr_uint16 i)
 Returns a language id corresponding to a language of given index in the face.
GR2_API void gr_face_destroy (gr_face *face)
 Destroy the given face and free its memory.
GR2_API unsigned short gr_face_n_glyphs (const gr_face *pFace)
 Returns the number of glyphs in the face.
GR2_API const gr_faceinfogr_face_info (const gr_face *pFace, gr_uint32 script)
 Returns a faceinfo for the face and script.
GR2_API int gr_face_is_char_supported (const gr_face *pFace, gr_uint32 usv, gr_uint32 script)
 Returns whether the font supports a given Unicode character.
GR2_API gr_facegr_make_file_face (const char *filename, unsigned int faceOptions)
 Create gr_face from a font file.
GR2_API gr_facegr_make_file_face_with_seg_cache (const char *filename, unsigned int segCacheMaxSize, unsigned int faceOptions)
 Create gr_face from a font file, with subsegment caching support.
GR2_API gr_fontgr_make_font (float ppm, const gr_face *face)
 Create a font from a face.
GR2_API gr_fontgr_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 functions.
GR2_API gr_fontgr_make_font_with_advance_fn (float ppm, const void *appFontHandle, gr_advance_fn getAdvance, const gr_face *face)
 Creates a font with hinted advance width query function.
GR2_API void gr_font_destroy (gr_font *font)
 Free a font.
GR2_API gr_uint16 gr_fref_feature_value (const gr_feature_ref *pfeatureref, const gr_feature_val *feats)
 get a feature value
GR2_API int gr_fref_set_feature_value (const gr_feature_ref *pfeatureref, gr_uint16 val, gr_feature_val *pDest)
 set a feature value
GR2_API gr_uint32 gr_fref_id (const gr_feature_ref *pfeatureref)
 Returns the id tag for a gr_feature_ref.
GR2_API gr_uint16 gr_fref_n_values (const gr_feature_ref *pfeatureref)
 Returns number of values a feature may take, given a gr_feature_ref.
GR2_API gr_int16 gr_fref_value (const gr_feature_ref *pfeatureref, gr_uint16 settingno)
 Returns the value associated with a particular value in a feature.
GR2_API void * gr_fref_label (const gr_feature_ref *pfeatureref, gr_uint16 *langId, enum gr_encform utf, gr_uint32 *length)
 Returns a string of the UI name of a feature.
GR2_API void * gr_fref_value_label (const gr_feature_ref *pfeatureref, gr_uint16 settingno, gr_uint16 *langId, enum gr_encform utf, gr_uint32 *length)
 Return a UI string for a possible value of a feature.
GR2_API void gr_label_destroy (void *label)
 Destroy a previously returned label string.
GR2_API gr_feature_valgr_featureval_clone (const gr_feature_val *pfeatures)
 Copies a gr_feature_val.
GR2_API void gr_featureval_destroy (gr_feature_val *pfeatures)
 Destroys a gr_feature_val.

Macro Definition Documentation

#define GR2_VERSION_BUGFIX   5
#define GR2_VERSION_MAJOR   1
#define GR2_VERSION_MINOR   3

Typedef Documentation

typedef float(* gr_advance_fn)(const void *appFontHandle, gr_uint16 glyphid)

query function to find the hinted advance of a glyph

Parameters
appFontHandleis the unique information passed to gr_make_font_with_advance()
glyphidis the glyph to retireve the hinted advance for.
typedef struct gr_face gr_face
typedef struct gr_font gr_font
typedef const void*(* gr_get_table_fn)(const void *appFaceHandle, unsigned int name, size_t *len)

type describing function to retrieve font table information

Returns
a pointer to the table in memory. The pointed to memory must exist as long as the gr_face which makes the call.
Parameters
appFaceHandleis the unique information passed to gr_make_face()
nameis a 32bit tag to the table name.
lenreturned by this function to say how long the table is in memory.
typedef void(* gr_release_table_fn)(const void *appFaceHandle, const void *table_buffer)

type describing function to release any resources allocated by the above get_table table function

Parameters
appFaceHandleis the unique information passed to gr_make_face()
pointerto table memory returned by get_table.

Enumeration Type Documentation

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

Enumerator:
gr_face_default 

No preload, no cmap caching, fail if the graphite tables are invalid.

gr_face_dumbRendering 

Dumb rendering will be enabled if the graphite tables are invalid.

gr_face_preloadGlyphs 

preload glyphs at construction time

gr_face_cacheCmap 

Cache the lookup from code point to glyph ID at construction time.

gr_face_preloadAll 

Preload everything.

Function Documentation

GR2_API void gr_engine_version ( int *  nMajor,
int *  nMinor,
int *  nBugFix 
)

Returns version information on this engine.

GR2_API void gr_face_destroy ( gr_face face)

Destroy the given face and free its memory.

GR2_API gr_feature_val* gr_face_featureval_for_lang ( const gr_face pFace,
gr_uint32  langname 
)

Get feature values for a given language or default.

Returns
a copy of the default feature values for a given language. The application must call gr_featureval_destroy() to free this object when done.
Parameters
pFaceThe font face to get feature values from
langnameThe 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 const gr_feature_ref* gr_face_find_fref ( const gr_face pFace,
gr_uint32  featId 
)

Get feature reference for a given feature id from a face.

Returns
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.
Parameters
pFaceFont face to get information on.
featIdFeature id tag to get reference to.
GR2_API const gr_feature_ref* gr_face_fref ( const gr_face pFace,
gr_uint16  i 
)

Returns feature reference at given index in face.

GR2_API const gr_faceinfo* gr_face_info ( const gr_face pFace,
gr_uint32  script 
)

Returns a faceinfo for the face and script.

GR2_API int gr_face_is_char_supported ( const gr_face pFace,
gr_uint32  usv,
gr_uint32  script 
)

Returns whether the font supports a given Unicode character.

Returns
true if the character is supported.
Parameters
pFaceface to test within
usvUnicode Scalar Value of character to test
scriptTag of script for selecting which set of pseudo glyphs to test. May be NULL.
GR2_API gr_uint32 gr_face_lang_by_index ( const gr_face pFace,
gr_uint16  i 
)

Returns a language id corresponding to a language of given index in the face.

GR2_API gr_uint16 gr_face_n_fref ( const gr_face pFace)

Returns number of feature references in a face.

GR2_API unsigned short gr_face_n_glyphs ( const gr_face pFace)

Returns the number of glyphs in the face.

GR2_API unsigned short gr_face_n_languages ( const gr_face pFace)

Return number of languages the face knows about.

GR2_API gr_feature_val* gr_featureval_clone ( const gr_feature_val pfeatures)

Copies a gr_feature_val.

GR2_API void gr_featureval_destroy ( gr_feature_val pfeatures)

Destroys a gr_feature_val.

GR2_API void gr_font_destroy ( gr_font font)

Free a font.

GR2_API gr_uint16 gr_fref_feature_value ( const gr_feature_ref pfeatureref,
const gr_feature_val feats 
)

get a feature value

Returns
value of specific feature or 0 if any problems.
Parameters
pfeaturerefgr_feature_ref to the feature
featsgr_feature_val containing all the values
GR2_API gr_uint32 gr_fref_id ( const gr_feature_ref pfeatureref)

Returns the id tag for a gr_feature_ref.

GR2_API void* gr_fref_label ( const gr_feature_ref pfeatureref,
gr_uint16 langId,
enum gr_encform  utf,
gr_uint32 length 
)

Returns a string of the UI name of a feature.

Returns
string of the UI name, in the encoding form requested. Call gr_label_destroy() after use.
Parameters
pfeaturerefgr_feature_ref of the feature
langIdThis 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
utfEncoding form for the string
lengthUsed to return the length of the string returned in bytes.
GR2_API gr_uint16 gr_fref_n_values ( const gr_feature_ref pfeatureref)

Returns number of values a feature may take, given a gr_feature_ref.

GR2_API int gr_fref_set_feature_value ( const gr_feature_ref pfeatureref,
gr_uint16  val,
gr_feature_val pDest 
)

set a feature value

Returns
false if there were any problems (value out of range, etc.)
Parameters
pfeaturerefgr_feature_ref to the feature
valvalue to set the feature to
pDestthe gr_feature_val containing all the values for all the features
GR2_API gr_int16 gr_fref_value ( const gr_feature_ref pfeatureref,
gr_uint16  settingno 
)

Returns the value associated with a particular value in a feature.

Returns
value
Parameters
pfeaturerefgr_feature_ref of the feature of interest
settingnoIndex up to the return value of gr_fref_n_values() of the value
GR2_API void* gr_fref_value_label ( const gr_feature_ref pfeatureref,
gr_uint16  settingno,
gr_uint16 langId,
enum gr_encform  utf,
gr_uint32 length 
)

Return a UI string for a possible value of a feature.

Returns
string of the UI name, in the encoding form requested. nul terminated. Call gr_label_destroy() after use.
Parameters
pfeaturerefgr_feature_ref of the feature
settingnoValue setting index
langIdThis is a pointer to the requested language. The requested language id is replaced by the actual language id of the string returned.
utfEncoding form for the string
lengthReturns the length of the string returned in bytes.
GR2_API void gr_label_destroy ( void *  label)

Destroy a previously returned label string.

GR2_API gr_face* gr_make_face ( const void *  appFaceHandle,
gr_get_table_fn  getTable,
unsigned int  faceOptions 
)

Create a gr_face object given application information and a getTable function.

This function is deprecated as of v1.2.0 in favour of gr_make_face_with_ops.

Returns
gr_face or NULL if the font fails to load for some reason.
Parameters
appFaceHandleThis is application specific information that is passed to the getTable function. The appFaceHandle must stay alive as long as the gr_face is alive.
getTableCallback function to get table data.
faceOptionsBitfield describing various options. See enum gr_face_options for details.
GR2_API gr_face* gr_make_face_with_ops ( const void *  appFaceHandle,
const gr_face_ops face_ops,
unsigned int  faceOptions 
)

Create a gr_face object given application information and a table functions.

Returns
gr_face or NULL if the font fails to load for some reason.
Parameters
appFaceHandleThis is application specific information that is passed to the getTable function. The appFaceHandle must stay alive as long as the gr_face is alive.
face_opsPointer to face specific callback structure for table management. Must stay alive for the duration of the call only.
faceOptionsBitfield describing various options. See enum gr_face_options for details.
GR2_API gr_face* gr_make_face_with_seg_cache ( const void *  appFaceHandle,
gr_get_table_fn  getTable,
unsigned int  segCacheMaxSize,
unsigned int  faceOptions 
)

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.

Returns
gr_face or NULL if the font fails to load.
Parameters
appFaceHandleis 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.
getTableThe function graphite calls to access font table data
segCacheMaxSizeHow large the segment cache is.
faceOptionsBitfield of values from enum gr_face_options
GR2_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 
)

Create a gr_face object given application information, with subsegmental caching support.

Returns
gr_face or NULL if the font fails to load.
Parameters
appFaceHandleis 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.
face_opsPointer to face specific callback structure for table management. Must stay alive for the duration of the call only.
segCacheMaxSizeHow large the segment cache is.
faceOptionsBitfield of values from enum gr_face_options
GR2_API gr_face* gr_make_file_face ( const char *  filename,
unsigned int  faceOptions 
)

Create gr_face from a font file.

Returns
gr_face that accesses a font file directly. Returns NULL on failure.
Parameters
filenameFull path and filename to font file
faceOptionsBitfile from enum gr_face_options to control face options.
GR2_API gr_face* gr_make_file_face_with_seg_cache ( const char *  filename,
unsigned int  segCacheMaxSize,
unsigned int  faceOptions 
)

Create gr_face from a font file, with subsegment caching support.

Returns
gr_face that accesses a font file directly. Returns NULL on failure.
Parameters
filenameFull path and filename to font file
segCacheMaxSizeSpecifies how big to make the cache in segments.
faceOptionsBitfield from enum gr_face_options to control face options.
GR2_API gr_font* gr_make_font ( float  ppm,
const gr_face face 
)

Create a font from a face.

Returns
gr_font Call font_destroy to free this font
Parameters
ppmResolution of the font in pixels per em
faceFace this font corresponds to. This must stay alive as long as the font is alive.
GR2_API gr_font* gr_make_font_with_advance_fn ( float  ppm,
const void *  appFontHandle,
gr_advance_fn  getAdvance,
const gr_face face 
)

Creates a font with hinted advance width query function.

This function is deprecated. Use gr_make_font_with_ops instead.

Returns
gr_font to be destroyed via font_destroy
Parameters
ppmsize of font in pixels per em
appFontHandlefont specific information that must stay alive as long as the font does
getAdvancecallback function reference that returns horizontal advance in pixels for a glyph.
facethe 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 functions.

Returns
gr_font to be destroyed via font_destroy
Parameters
ppmsize of font in pixels per em
appFontHandlefont specific information that must stay alive as long as the font does
font_opspointer font specific callback structure for hinted metrics. Need only stay alive for the duration of the call.
facethe face this font corresponds to. Must stay alive as long as the font does.
GR2_API gr_uint32 gr_str_to_tag ( const char *  str)

Convert a tag in a string into a gr_uint32.

Returns
gr_uint32 tag, zero padded
Parameters
stra nul terminated string of which at most the first 4 characters are read
GR2_API void gr_tag_to_str ( gr_uint32  tag,
char *  str 
)

Convert a gr_uint32 tag into a string.

Parameters
tagcontains the tag to convert
stris 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.