OpenType Font Handling

OpenType Font Handling — Obtaining information from OpenType tables

Synopsis




typedef             PangoOTTag;
                    PangoOTInfo;
                    PangoOTBuffer;
                    PangoOTGlyph;
                    PangoOTRuleset;
enum                PangoOTTableType;
#define             PANGO_OT_ALL_GLYPHS
#define             PANGO_OT_DEFAULT_LANGUAGE
PangoOTInfo*        pango_ot_info_get                   (FT_Face face);
gboolean            pango_ot_info_find_script           (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         PangoOTTag script_tag,
                                                         guint *script_index);
gboolean            pango_ot_info_find_language         (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         guint script_index,
                                                         PangoOTTag language_tag,
                                                         guint *language_index,
                                                         guint *required_feature_index);
gboolean            pango_ot_info_find_feature          (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         PangoOTTag feature_tag,
                                                         guint script_index,
                                                         guint language_index,
                                                         guint *feature_index);
PangoOTTag*         pango_ot_info_list_scripts          (PangoOTInfo *info,
                                                         PangoOTTableType table_type);
PangoOTTag*         pango_ot_info_list_languages        (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         guint script_index,
                                                         PangoOTTag language_tag);
PangoOTTag*         pango_ot_info_list_features         (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         PangoOTTag tag,
                                                         guint script_index,
                                                         guint language_index);
PangoOTBuffer*      pango_ot_buffer_new                 (PangoFcFont *font);
void                pango_ot_buffer_destroy             (PangoOTBuffer *buffer);
void                pango_ot_buffer_clear               (PangoOTBuffer *buffer);
void                pango_ot_buffer_add_glyph           (PangoOTBuffer *buffer,
                                                         guint glyph,
                                                         guint properties,
                                                         guint cluster);
void                pango_ot_buffer_set_rtl             (PangoOTBuffer *buffer,
                                                         gboolean rtl);
void                pango_ot_buffer_set_zero_width_marks
                                                        (PangoOTBuffer *buffer,
                                                         gboolean zero_width_marks);
void                pango_ot_buffer_get_glyphs          (PangoOTBuffer *buffer,
                                                         PangoOTGlyph **glyphs,
                                                         int *n_glyphs);
void                pango_ot_buffer_output              (PangoOTBuffer *buffer,
                                                         PangoGlyphString *glyphs);
PangoOTRuleset*     pango_ot_ruleset_new                (PangoOTInfo *info);
void                pango_ot_ruleset_add_feature        (PangoOTRuleset *ruleset,
                                                         PangoOTTableType table_type,
                                                         guint feature_index,
                                                         gulong property_bit);
void                pango_ot_ruleset_substitute         (PangoOTRuleset *ruleset,
                                                         PangoOTBuffer *buffer);
void                pango_ot_ruleset_position           (PangoOTRuleset *ruleset,
                                                         PangoOTBuffer *buffer);

Description

Functions and macros in this section are used to implement the OpenType Layout features and algorithms. These are mostly useful when writing Fontconfig-based shaping engines

Details

PangoOTTag

typedef guint32  PangoOTTag;

The PangoOTTag typedef is used to represent TrueType and OpenType four letter tags inside Pango. Use the FT_MAKE_TAG() macro defined in the FreeType2 header freetype/freetype.h to create PangoOTTags manually.


PangoOTInfo

typedef struct _PangoOTInfo PangoOTInfo;

The PangoOTInfo struct contains the various tables associated with an OpenType font. It contains only private fields and should only be accessed via the pango_ot_info_* functions which are documented below. To obtain a PangoOTInfo, use pango_ot_info_new().


PangoOTBuffer

typedef struct _PangoOTBuffer PangoOTBuffer;

The PangoOTBuffer structure is used to store strings of glyphs associated with a PangoFcFont, suitable for OpenType layout processing. It contains only private fields and should only be accessed via the pango_ot_buffer_* functions which are documented below. To obtain a PangoOTBuffer, use pango_ot_buffer_new().


PangoOTGlyph

typedef struct {
  guint    glyph;
  guint    properties;
  guint    cluster;
  gushort  component;
  gushort  ligID;
  gushort  property_cache;    /* Internal */
} PangoOTGlyph;

The PangoOTGlyph structure represents a single glyph together with information used for OpenType layout processing of the glyph. It contains the following fields.

guint glyph; the glyph itself.
guint properties; the properties value, identifying which features should be applied on this glyph. See pango_ruleset_add_feature().
guint cluster; the cluster that this glyph belongs to.
gushort component; a component value, set by the OpenType layout engine.
gushort ligID; a ligature index value, set by the OpenType layout engine.
gushort property_cache; for internal use.

PangoOTRuleset

typedef struct _PangoOTRuleset PangoOTRuleset;

The PangoOTRuleSet structure holds a set of features selected from the tables in an OpenType font. (A feature is an operation such as adjusting glyph positioning that should be applied to a text feature such as a certain type of accent.) A PangoOTRuleSet is created with pango_ot_ruleset_new(), features are added to it with pango_ot_ruleset_add_feature(), then it is applied to a PangoGlyphString with pango_ot_ruleset_shape().


enum PangoOTTableType

typedef enum
{
  PANGO_OT_TABLE_GSUB,
  PANGO_OT_TABLE_GPOS
} PangoOTTableType;

The PangoOTTableType enumeration values are used to identify the various OpenType tables in the pango_ot_info_* functions.

PANGO_OT_TABLE_GSUB The GSUB table.
PANGO_OT_TABLE_GPOS The GPOS table.

PANGO_OT_ALL_GLYPHS

#define PANGO_OT_ALL_GLYPHS		((guint)0xFFFF)

This is used as the property bit in pango_ot_ruleset_add_feature() when a feature should be applied to all glyphs.


PANGO_OT_DEFAULT_LANGUAGE

#define PANGO_OT_DEFAULT_LANGUAGE	((guint)0xFFFF)

This is used as the language index in pango_ot_info_find_feature() when a the default language system of the script is desired.


pango_ot_info_get ()

PangoOTInfo*        pango_ot_info_get                   (FT_Face face);

Returns the PangoOTInfo structure for the given FreeType font.

face : a FT_Face.
Returns : the PangoOTInfo for face. This object will have the same lifetime as face.

Since 1.2


pango_ot_info_find_script ()

gboolean            pango_ot_info_find_script           (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         PangoOTTag script_tag,
                                                         guint *script_index);

Finds the index of a script.

info : a PangoOTInfo.
table_type : the table type to obtain information about.
script_tag : the tag of the script to find.
script_index : location to store the index of the script, or NULL.
Returns : TRUE if the script was found.

pango_ot_info_find_language ()

gboolean            pango_ot_info_find_language         (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         guint script_index,
                                                         PangoOTTag language_tag,
                                                         guint *language_index,
                                                         guint *required_feature_index);

Finds the index of a language and its required feature index.

info : a PangoOTInfo.
table_type : the table type to obtain information about.
script_index : the index of the script whose languages are searched.
language_tag : the tag of the language to find.
language_index : location to store the index of the language, or NULL.
required_feature_index : location to store the required feature index of the language, or NULL.
Returns : TRUE if the language was found.

pango_ot_info_find_feature ()

gboolean            pango_ot_info_find_feature          (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         PangoOTTag feature_tag,
                                                         guint script_index,
                                                         guint language_index,
                                                         guint *feature_index);

Finds the index of a feature.

info : a PangoOTInfo.
table_type : the table type to obtain information about.
feature_tag : the tag of the feature to find.
script_index : the index of the script.
language_index : the index of the language whose features are searched, or PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script.
feature_index : location to store the index of the feature, or NULL.
Returns : TRUE if the feature was found.

pango_ot_info_list_scripts ()

PangoOTTag*         pango_ot_info_list_scripts          (PangoOTInfo *info,
                                                         PangoOTTableType table_type);

Obtains the list of available scripts.

info : a PangoOTInfo.
table_type : the table type to obtain information about.
Returns : a newly-allocated array containing the tags of the available scripts.

pango_ot_info_list_languages ()

PangoOTTag*         pango_ot_info_list_languages        (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         guint script_index,
                                                         PangoOTTag language_tag);

Obtains the list of available languages for a given script.

info : a PangoOTInfo.
table_type : the table type to obtain information about.
script_index : the index of the script to list languages for.
language_tag : unused parameter.
Returns : a newly-allocated array containing the tags of the available languages.

pango_ot_info_list_features ()

PangoOTTag*         pango_ot_info_list_features         (PangoOTInfo *info,
                                                         PangoOTTableType table_type,
                                                         PangoOTTag tag,
                                                         guint script_index,
                                                         guint language_index);

Obtains the list of features for the given language of the given script.

info : a PangoOTInfo.
table_type : the table type to obtain information about.
tag : unused parameter.
script_index : the index of the script to obtain information about.
language_index : the index of the language to list features for, or PANGO_OT_DEFAULT_LANGUAGE, to list features for the default language of the script.
Returns : a newly-allocated array containing the tags of the available features.

pango_ot_buffer_new ()

PangoOTBuffer*      pango_ot_buffer_new                 (PangoFcFont *font);

Creates a new PangoOTBuffer for the given OpenType font.

font : a PangoFcFont
Returns : the newly allocated PangoOTBuffer, which should be freed with pango_ot_buffer_destroy().

Since 1.4


pango_ot_buffer_destroy ()

void                pango_ot_buffer_destroy             (PangoOTBuffer *buffer);

Destroys a PangoOTBuffer and free all associated memory.

buffer : a PangoOTBuffer

Since 1.4


pango_ot_buffer_clear ()

void                pango_ot_buffer_clear               (PangoOTBuffer *buffer);

Empties a PangoOTBuffer, make it ready to add glyphs to.

buffer : a PangoOTBuffer

Since 1.4


pango_ot_buffer_add_glyph ()

void                pango_ot_buffer_add_glyph           (PangoOTBuffer *buffer,
                                                         guint glyph,
                                                         guint properties,
                                                         guint cluster);

Appends a glyph to a PangoOTBuffer, with properties identifying which features should be applied on this glyph. See pango_ruleset_add_feature().

buffer : a PangoOTBuffer
glyph : the glyph index to add, like a PangoGlyph
properties : the glyph properties
cluster : the cluster that this glyph belongs to

Since 1.4


pango_ot_buffer_set_rtl ()

void                pango_ot_buffer_set_rtl             (PangoOTBuffer *buffer,
                                                         gboolean rtl);

Sets whether glyphs will be rendered right-to-left. This setting is needed for proper horizontal positioning of right-to-left scripts.

buffer : a PangoOTBuffer
rtl : TRUE for right-to-left text

Since 1.4


pango_ot_buffer_set_zero_width_marks ()

void                pango_ot_buffer_set_zero_width_marks
                                                        (PangoOTBuffer *buffer,
                                                         gboolean zero_width_marks);

Sets whether characters with a mark class should be forced to zero width. This setting is needed for proper positioning of Arabic accents, but will produce incorrect results with standard OpenType Indic fonts.

buffer : a PangoOTBuffer
zero_width_marks : TRUE if characters with a mark class should be forced to zero width.

Since 1.6


pango_ot_buffer_get_glyphs ()

void                pango_ot_buffer_get_glyphs          (PangoOTBuffer *buffer,
                                                         PangoOTGlyph **glyphs,
                                                         int *n_glyphs);

Gets the glyph array contained in a PangoOTBuffer. The glyphs are owned by the buffer and should not be freed, and are only valid as long as buffer is not modified.

buffer : a PangoOTBuffer
glyphs : location to store the array of glyphs, or NULL
n_glyphs : location to store the number of glyphs, or NULL

Since 1.4


pango_ot_buffer_output ()

void                pango_ot_buffer_output              (PangoOTBuffer *buffer,
                                                         PangoGlyphString *glyphs);

Exports the glyphs in a PangoOTBuffer into a PangoGlyphString. This is typically used after the OpenType layout processing is over, to convert the resulting glyphs into a generic Pango glyph string.

buffer : a PangoOTBuffer
glyphs : a PangoGlyphString

Since 1.4


pango_ot_ruleset_new ()

PangoOTRuleset*     pango_ot_ruleset_new                (PangoOTInfo *info);

Creates a new PangoOTRuleset for the given OpenType info.

info : a PangoOTInfo.
Returns : the newly allocated PangoOTRuleset, which should be freed with g_object_unref().

pango_ot_ruleset_add_feature ()

void                pango_ot_ruleset_add_feature        (PangoOTRuleset *ruleset,
                                                         PangoOTTableType table_type,
                                                         guint feature_index,
                                                         gulong property_bit);

Adds a feature to the ruleset.

ruleset : a PangoOTRuleset.
table_type : the table type to add a feature to.
feature_index : the index of the feature to add.
property_bit : the property bit to use for this feature. Used to identify the glyphs that this feature should be applied to, or PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.

pango_ot_ruleset_substitute ()

void                pango_ot_ruleset_substitute         (PangoOTRuleset *ruleset,
                                                         PangoOTBuffer *buffer);

Performs the OpenType GSUB substitution on buffer using the features in ruleset

ruleset : a PangoOTRuleset.
buffer : a PangoOTBuffer.

Since 1.4


pango_ot_ruleset_position ()

void                pango_ot_ruleset_position           (PangoOTRuleset *ruleset,
                                                         PangoOTBuffer *buffer);

Performs the OpenType GPOS positioning on buffer using the features in ruleset

ruleset : a PangoOTRuleset.
buffer : a PangoOTBuffer.

Since 1.4