## 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 addded 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 indes 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 positionoing on `buffer` using the features in `ruleset`

`ruleset` : | a PangoOTRuleset.
`buffer` : | a PangoOTBuffer.

Since 1.4