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 14

## 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 More...
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 More...
typedef float(* | gr_advance_fn) (const void *appFontHandle, gr_uint16 glyphid)
| query function to find the hinted advance of a glyph More...

## 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. More...
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. More...
GR2_DEPRECATED_API gr_face * | gr_make_face (const void *appFaceHandle, gr_get_table_fn getTable, unsigned int faceOptions)
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)
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)
GR2_API gr_uint32 | gr_str_to_tag (const char *str)
| Convert a tag in a string into a gr_uint32. More...
GR2_API void | gr_tag_to_str (gr_uint32 tag, char *str)
| Convert a gr_uint32 tag into a string. More...
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. More...
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. More...
GR2_API gr_uint16 | gr_face_n_fref (const gr_face *pFace)
| Returns number of feature references in a face. More...
GR2_API const gr_feature_ref * | gr_face_fref (const gr_face *pFace, gr_uint16 i)
| Returns feature reference at given index in face. More...
GR2_API unsigned short | gr_face_n_languages (const gr_face *pFace)
| Return number of languages the face knows about. More...
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. More...
GR2_API void | gr_face_destroy (gr_face *face)
| Destroy the given face and free its memory. More...
GR2_API unsigned short | gr_face_n_glyphs (const gr_face *pFace)
| Returns the number of glyphs in the face. More...
GR2_API const gr_faceinfo * | gr_face_info (const gr_face *pFace, gr_uint32 script)
| Returns a faceinfo for the face and script. More...
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. More...
GR2_API gr_face * | gr_make_file_face (const char *filename, unsigned int faceOptions)
| Create gr_face from a font file. More...
GR2_DEPRECATED_API gr_face * | gr_make_file_face_with_seg_cache (const char *filename, unsigned int segCacheMaxSize, unsigned int faceOptions)
GR2_API gr_font * | gr_make_font (float ppm, const gr_face *face)
| Create a font from a face. More...
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. More...
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. More...
GR2_API void | gr_font_destroy (gr_font *font)
| Free a font. More...
GR2_API gr_uint16 | gr_fref_feature_value (const gr_feature_ref *pfeatureref, const gr_feature_val *feats)
| get a feature value More...
GR2_API int | gr_fref_set_feature_value (const gr_feature_ref *pfeatureref, gr_uint16 val, gr_feature_val *pDest)
| set a feature value More...
GR2_API gr_uint32 | gr_fref_id (const gr_feature_ref *pfeatureref)
| Returns the id tag for a gr_feature_ref. More...
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. More...
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. More...
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. More...
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. More...
GR2_API void | gr_label_destroy (void *label)
| Destroy a previously returned label string. More...
GR2_API gr_feature_val * | gr_featureval_clone (const gr_feature_val *pfeatures)
| Copies a gr_feature_val. More...
GR2_API void | gr_featureval_destroy (gr_feature_val *pfeatures)
| Destroys a gr_feature_val. More...

## Macro Definition Documentation

## GR2_VERSION_BUGFIX

#define GR2_VERSION_BUGFIX 14

## GR2_VERSION_MAJOR

#define GR2_VERSION_MAJOR 1

## GR2_VERSION_MINOR

#define GR2_VERSION_MINOR 3

## Typedef Documentation

## gr_advance_fn

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

query function to find the hinted advance of a glyph

Parameters

  appFontHandle | is the unique information passed to gr_make_font_with_advance()
  glyphid | is the glyph to retireve the hinted advance for.

## gr_face

typedef struct gr_face gr_face

## gr_feature_ref

typedef struct gr_feature_ref gr_feature_ref

## gr_feature_val

typedef struct gr_feature_val gr_feature_val

## gr_font

typedef struct gr_font gr_font

## gr_get_table_fn

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

  appFaceHandle | is the unique information passed to gr_make_face()
  name | is a 32bit tag to the table name.
  len | returned by this function to say how long the table is in memory.

## gr_release_table_fn

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

  appFaceHandle | is the unique information passed to gr_make_face()
  pointer | to table memory returned by get_table.

## Enumeration Type Documentation

## gr_face_options

enum gr_face_options

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.

Deprecated:
  Since 1.311

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

## gr_engine_version()

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

Returns version information on this engine.

## gr_face_destroy()

GR2_API void gr_face_destroy | ( | gr_face * | face | ) |

Destroy the given face and free its memory.

## gr_face_featureval_for_lang()

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

  pFace | The font face to get feature values from
  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.

## gr_face_find_fref()

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

  pFace | Font face to get information on.
  featId | Feature id tag to get reference to.

## gr_face_fref()

GR2_API const gr_feature_ref* gr_face_fref | ( | const gr_face * | pFace,
|  | gr_uint16 | i
| ) |  |

Returns feature reference at given index in face.

## gr_face_info()

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

Returns a faceinfo for the face and script.

## gr_face_is_char_supported()

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

  pFace | face to test within
  usv | Unicode Scalar Value of character to test
  script | Tag of script for selecting which set of pseudo glyphs to test. May be NULL.

## gr_face_lang_by_index()

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.

## gr_face_n_fref()

GR2_API gr_uint16 gr_face_n_fref | ( | const gr_face * | pFace | ) |

Returns number of feature references in a face.

## gr_face_n_glyphs()

GR2_API unsigned short gr_face_n_glyphs | ( | const gr_face * | pFace | ) |

Returns the number of glyphs in the face.

## gr_face_n_languages()

GR2_API unsigned short gr_face_n_languages | ( | const gr_face * | pFace | ) |

Return number of languages the face knows about.

## gr_featureval_clone()

GR2_API gr_feature_val* gr_featureval_clone | ( | const gr_feature_val * | pfeatures | ) |

Copies a gr_feature_val.

## gr_featureval_destroy()

GR2_API void gr_featureval_destroy | ( | gr_feature_val * | pfeatures | ) |

Destroys a gr_feature_val.

## gr_font_destroy()

GR2_API void gr_font_destroy | ( | gr_font * | font | ) |

Free a font.

## gr_fref_feature_value()

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

  pfeatureref | gr_feature_ref to the feature
  feats | gr_feature_val containing all the values

## gr_fref_id()

GR2_API gr_uint32 gr_fref_id | ( | const gr_feature_ref * | pfeatureref | ) |

Returns the id tag for a gr_feature_ref.

## gr_fref_label()

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

  pfeatureref | gr_feature_ref of the feature
  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
  utf | Encoding form for the string
  length | Used to return the length of the string returned in bytes.

## gr_fref_n_values()

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.

## gr_fref_set_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

Returns
  false if there were any problems (value out of range, etc.)

Parameters

  pfeatureref | gr_feature_ref to the feature
  val | value to set the feature to
  pDest | the gr_feature_val containing all the values for all the features

## gr_fref_value()

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

  pfeatureref | gr_feature_ref of the feature of interest
  settingno | Index up to the return value of gr_fref_n_values() of the value

## gr_fref_value_label()

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

  pfeatureref | gr_feature_ref of the feature
  settingno | Value setting index
  langId | This is a pointer to the requested language. The requested language id is replaced by the actual language id of the string returned.
  utf | Encoding form for the string
  length | Returns the length of the string returned in bytes.

## gr_label_destroy()

GR2_API void gr_label_destroy | ( | void * | label | ) |

Destroy a previously returned label string.

## gr_make_face()

GR2_DEPRECATED_API gr_face* gr_make_face | ( | const void * | appFaceHandle,
|  | gr_get_table_fn | getTable,
|  | 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.

Returns
  gr_face or NULL if the font fails to load for some reason.

Parameters

  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.
  getTable | Callback function to get table data.
  faceOptions | Bitfield describing various options. See enum gr_face_options for details.

## gr_make_face_with_ops()

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

  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.
  face_ops | Pointer to face specific callback structure for table management. Must stay alive for the duration of the call only.
  faceOptions | Bitfield describing various options. See enum gr_face_options for details.

## gr_make_face_with_seg_cache()

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
| ) |  |

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.

Returns
  gr_face or NULL if the font fails to load.

Parameters

  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.
  getTable | The function graphite calls to access font table data
  segCacheMaxSize | How large the segment cache is.
  faceOptions | Bitfield of values from enum gr_face_options

## gr_make_face_with_seg_cache_and_ops()

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_with_ops().

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

Returns
  gr_face or NULL if the font fails to load.

Parameters

  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.
  face_ops | Pointer to face specific callback structure for table management. Must stay alive for the duration of the call only.
  segCacheMaxSize | Unused.
  faceOptions | Bitfield of values from enum gr_face_options

## gr_make_file_face()

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

  filename | Full path and filename to font file
  faceOptions | Bitfile from enum gr_face_options to control face options.

## gr_make_file_face_with_seg_cache()

GR2_DEPRECATED_API gr_face* gr_make_file_face_with_seg_cache | ( | const char * | filename,
|  | unsigned int | segCacheMaxSize,
|  | 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.

Returns
  gr_face that accesses a font file directly. Returns NULL on failure.

Parameters

  filename | Full path and filename to font file
  segCacheMaxSize | Specifies how big to make the cache in segments.
  faceOptions | Bitfield from enum gr_face_options to control face options.

## gr_make_font()

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

  ppm | Resolution of the font in pixels per em
  face | Face this font corresponds to. This must stay alive as long as the font is alive.

## gr_make_font_with_advance_fn()

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

  ppm | size of font in pixels per em
  appFontHandle | font specific information that must stay alive as long as the font does
  getAdvance | callback function reference that returns horizontal advance in pixels for a glyph.
  face | the face this font corresponds to. Must stay alive as long as the font does.

## gr_make_font_with_ops()

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

  ppm | size of font in pixels per em
  appFontHandle | font specific information that must stay alive as long as the font does
  font_ops | pointer font specific callback structure for hinted metrics. Need only stay alive for the duration of the call.
  face | the face this font corresponds to. Must stay alive as long as the font does.

## gr_str_to_tag()

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

  str | a nul terminated string of which at most the first 4 characters are read

## gr_tag_to_str()

GR2_API void gr_tag_to_str | ( | gr_uint32 | tag,
|  | char * | str
| ) |  |

Convert a gr_uint32 tag into a string.

Parameters

  tag | contains the tag to convert
  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.