Graphiteng
Defines | Typedefs | Enumerations | Functions
Font.h File Reference
#include "graphite2/Types.h"

Go to the source code of this file.

Defines

#define GR2_VERSION_MAJOR   1
#define GR2_VERSION_MINOR   1
#define GR2_VERSION_BUGFIX   1

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 float(* gr_advance_fn )(const void *appFontHandle, gr_uint16 glyphid)
 query function to find the hinted advance width 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 = 6
}
 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 (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 (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 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_advance_fn (float ppm, const void *appFontHandle, gr_advance_fn advance, 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.

Define Documentation

#define GR2_VERSION_BUGFIX   1
#define GR2_VERSION_MAJOR   1
#define GR2_VERSION_MINOR   1

Typedef Documentation

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

query function to find the hinted advance width of a glyph

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.

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.

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.

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

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.

Copies a gr_feature_val.

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.

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.

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.
getTableThis function is called whenever graphite needs access to a table of data in the font.
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.

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_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  advance,
const gr_face face 
)

Creates a font with hinted advance width query function.

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
advancefunction to call with appFontHandle and glyphid to get horizontal advance in pixels.
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.
 All Files Functions Typedefs Enumerations Enumerator Defines