OpenType Font Handling

## OpenType Font Handling OpenType Font Handling — Obtaining information from OpenType tables |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    typedef             PangoOTTag;
                        PangoOTInfo;
                        PangoOTBuffer;
                        PangoOTGlyph;
                        PangoOTRuleset;
                        PangoOTRulesetDescription;
    enum                PangoOTTableType;
                        PangoOTFeatureMap;
    #define             PANGO_OT_TAG_MAKE                   (c1,c2,c3,c4)
    #define             PANGO_OT_TAG_MAKE_FROM_STRING       (s)
    #define             PANGO_OT_ALL_GLYPHS
    #define             PANGO_OT_NO_FEATURE
    #define             PANGO_OT_NO_SCRIPT
    #define             PANGO_OT_DEFAULT_LANGUAGE
    #define             PANGO_OT_TAG_DEFAULT_LANGUAGE
    #define             PANGO_OT_TAG_DEFAULT_SCRIPT
    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          (const PangoOTBuffer *buffer,
                                                             PangoOTGlyph **glyphs,
                                                             int *n_glyphs);
    void                pango_ot_buffer_output              (const PangoOTBuffer *buffer,
                                                             PangoGlyphString *glyphs);
    const PangoOTRuleset* pango_ot_ruleset_get_for_description
                                                            (PangoOTInfo *info,
                                                             const PangoOTRulesetDescription *desc);
    PangoOTRuleset*     pango_ot_ruleset_new                (PangoOTInfo *info);
    PangoOTRuleset*     pango_ot_ruleset_new_for            (PangoOTInfo *info,
                                                             PangoScript script,
                                                             PangoLanguage *language);
    PangoOTRuleset*     pango_ot_ruleset_new_from_description
                                                            (PangoOTInfo *info,
                                                             const PangoOTRulesetDescription *desc);
    void                pango_ot_ruleset_add_feature        (PangoOTRuleset *ruleset,
                                                             PangoOTTableType table_type,
                                                             guint feature_index,
                                                             gulong property_bit);
    gboolean            pango_ot_ruleset_maybe_add_feature  (PangoOTRuleset *ruleset,
                                                             PangoOTTableType table_type,
                                                             PangoOTTag feature_tag,
                                                             gulong property_bit);
    guint               pango_ot_ruleset_maybe_add_features (PangoOTRuleset *ruleset,
                                                             PangoOTTableType table_type,
                                                             const PangoOTFeatureMap *features,
                                                             guint n_features);
    guint               pango_ot_ruleset_get_feature_count  (const PangoOTRuleset *ruleset,
                                                             guint *n_gsub_features,
                                                             guint *n_gpos_features);
    void                pango_ot_ruleset_substitute         (const PangoOTRuleset *ruleset,
                                                             PangoOTBuffer *buffer);
    void                pango_ot_ruleset_position           (const PangoOTRuleset *ruleset,
                                                             PangoOTBuffer *buffer);
    PangoOTRulesetDescription* pango_ot_ruleset_description_copy
                                                            (const PangoOTRulesetDescription *desc);
    gboolean            pango_ot_ruleset_description_equal  (const PangoOTRulesetDescription *desc1,
                                                             const PangoOTRulesetDescription *desc2);
    void                pango_ot_ruleset_description_free   (PangoOTRulesetDescription *desc);
    guint               pango_ot_ruleset_description_hash   (const PangoOTRulesetDescription *desc);
    PangoOTTag          pango_ot_tag_from_language          (PangoLanguage *language);
    PangoOTTag          pango_ot_tag_from_script            (PangoScript script);
    PangoLanguage*      pango_ot_tag_to_language            (PangoOTTag language_tag);
    PangoScript         pango_ot_tag_to_script              (PangoOTTag script_tag);

## Object Hierarchy

      GObject
       +----PangoOTInfo

      GObject
       +----PangoOTRuleset

## 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 `PANGO_OT_TAG_MAKE()` or `PANGO_OT_TAG_MAKE_FROM_STRING()` macros 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()`.

### PangoOTRulesetDescription

    typedef struct {
      PangoScript               script;
      PangoLanguage            *language;
      const PangoOTFeatureMap  *static_gsub_features;
      guint                   n_static_gsub_features;
      const PangoOTFeatureMap  *static_gpos_features;
      guint                   n_static_gpos_features;
      const PangoOTFeatureMap  *other_features;
      guint                   n_other_features;
    } PangoOTRulesetDescription;

The PangoOTRuleset structure holds all the information needed to build a complete PangoOTRuleset from an OpenType font. The main use of this struct is to act as the key for a per-font hash of rulesets. The user populates a ruleset description and gets the ruleset using `pango_ot_ruleset_get_for_description()` or create a new one using `pango_ot_ruleset_new_from_description()`.

PangoScript `script`; | a PangoScript.
PangoLanguage *`language`; | a PangoLanguage.
const PangoOTFeatureMap *`static_gsub_features`; | static map of GSUB features, or `NULL`.
guint `n_static_gsub_features`; | length of `static_gsub_features`, or 0.
const PangoOTFeatureMap *`static_gpos_features`; | static map of GPOS features, or `NULL`.
guint `n_static_gpos_features`; | length of `static_gpos_features`, or 0.
const PangoOTFeatureMap *`other_features`; | map of extra features to add to both GSUB and GPOS, or `NULL`. Unlike the static maps, this pointer need not live beyond the life of function calls taking this struct.
guint `n_other_features`; | length of `other_features`, or 0.

Since 1.18

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

### PangoOTFeatureMap

    typedef struct {
      char     feature_name[5];
      gulong   property_bit;
    } PangoOTFeatureMap;

The PangoOTFeatureMap typedef is used to represent an OpenType feature with the property bit associated with it. The feature tag is represented as a char array instead of a PangoOTTag for convenience.

char `feature_name`[5]; | feature tag in represented as four-letter ASCII string.
gulong `property_bit`; | the property bit to use for this feature. See `pango_ot_ruleset_add_feature()` for details.

Since 1.18

### PANGO_OT_TAG_MAKE()

    #define PANGO_OT_TAG_MAKE(c1,c2,c3,c4)		((PangoOTTag) FT_MAKE_TAG (c1, c2, c3, c4))

Creates a PangoOTTag from four characters. This is similar and compatible with the ``FT_MAKE_TAG()`` macro from FreeType.

`c1` : | First character.
`c2` : | Second character.
`c3` : | Third character.
`c4` : | Fourth character.

### PANGO_OT_TAG_MAKE_FROM_STRING()

    #define             PANGO_OT_TAG_MAKE_FROM_STRING(s)

Creates a PangoOTTag from a string. The string should be at least four characters long (pad with space characters if needed), and need not be nul-terminated. This is a convenience wrapper around `PANGO_OT_TAG_MAKE()`, but cannot be used in certain situations, for example, as a switch expression, as it dereferences pointers.

`s` : | The string representation of the tag.

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

Since 1.16

### PANGO_OT_NO_FEATURE

    #define PANGO_OT_NO_FEATURE			((guint) 0xFFFF)

This is used as a feature index that represent no feature, that is, should be skipped. It may be returned as feature index by `pango_ot_info_find_feature()` if the feature is not found, and `pango_ot_rulset_add_feature()` function automatically skips this value, so no special handling is required by the user.

Since 1.18

### PANGO_OT_NO_SCRIPT

    #define PANGO_OT_NO_SCRIPT			((guint) 0xFFFF)

This is used as a script index that represent no script, that is, when the requested script was not found, and a default ('DFLT') script was not found either. It may be returned as script index by `pango_ot_info_find_script()` if the script or a default script are not found, all other functions taking a script index essentially return if the input script index is this value, so no special handling is required by the user.

Since 1.18

### 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 the default language system of the script is desired. It is also returned by `pango_ot_info_find_language()` if the requested language is not found, or the requested language tag was PANGO_OT_TAG_DEFAULT_LANGUAGE. The end result is that one can always call `pango_ot_tag_from_language()` followed by `pango_ot_info_find_language()` and pass the result to `pango_ot_info_find_feature()` without having to worry about falling back to default language system explicitly.

Since 1.16

### PANGO_OT_TAG_DEFAULT_LANGUAGE

    #define PANGO_OT_TAG_DEFAULT_LANGUAGE		PANGO_OT_TAG_MAKE ('d', 'f', 'l', 't')

This is a PangoOTTag representing a special language tag 'dflt'. It is returned as language tag by `pango_ot_tag_from_language()` if the requested language is not found. It is safe to pass this value to `pango_ot_info_find_language()` as that function falls back to returning default language-system if the requested language tag is not found.

Since 1.18

### PANGO_OT_TAG_DEFAULT_SCRIPT

    #define PANGO_OT_TAG_DEFAULT_SCRIPT		PANGO_OT_TAG_MAKE ('D', 'F', 'L', 'T')

This is a PangoOTTag representing the special script tag 'DFLT'. It is returned as script tag by `pango_ot_tag_from_script()` if the requested script is not found.

Since 1.18

### pango_ot_info_get ()

    PangoOTInfo*        pango_ot_info_get                   (FT_Face face);

Returns the PangoOTInfo structure for the given FreeType font face.

`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. If not found, tries to find the 'DFLT' and then 'dflt' scripts and return the index of that in `script_index`. If none of those is found either, `PANGO_OT_NO_SCRIPT` is placed in `script_index`.

All other functions taking an input script_index parameter know how to handle `PANGO_OT_NO_SCRIPT`, so one can ignore the return value of this function completely and proceed, to enjoy the automatic fallback to the 'DFLT'/'dflt' 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. If the language is not found, sets `language_index` to PANGO_OT_DEFAULT_LANGUAGE and the required feature of the default language system is returned in required_feature_index. For best compatibility with some fonts, also searches the language system tag 'dflt' before falling back to the default language system, but that is transparent to the user. The user can simply ignore the return value of this function to automatically fall back to the default language system.

`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. If the feature is not found, sets `feature_index` to PANGO_OT_NO_FEATURE, which is safe to pass to `pango_ot_ruleset_add_feature()` and similar functions.

In the future, this may set `feature_index` to an special value that if used in `pango_ot_ruleset_add_feature()` will ask Pango to synthesize the requested feature based on Unicode properties and data. However, this function will still return `FALSE` in those cases. So, users may want to ignore the return value of this function in certain cases.

`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 zero-terminated array containing the tags of the available scripts. Should be freed using `g_free()`.

### 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 zero-terminated array containing the tags of the available languages. Should be freed using `g_free()`.

### 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 zero-terminated array containing the tags of the available features. Should be freed using `g_free()`.

### 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          (const 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              (const 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_get_for_description ()

    const PangoOTRuleset* pango_ot_ruleset_get_for_description
                                                            (PangoOTInfo *info,
                                                             const PangoOTRulesetDescription *desc);

Returns a ruleset for the given OpenType info and ruleset description. Rulesets are created on demand using `pango_ot_ruleset_new_from_description()`. The returned ruleset should not be modified or destroyed.

The static feature map members of `desc` should be alive as long as `info` is.

`info` : | a PangoOTInfo.
`desc` : | a PangoOTRulesetDescription.
Returns : | the PangoOTRuleset for `desc`. This object will have the same lifetime as `info`.

Since 1.18

### 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_new_for ()

    PangoOTRuleset*     pango_ot_ruleset_new_for            (PangoOTInfo *info,
                                                             PangoScript script,
                                                             PangoLanguage *language);

Creates a new PangoOTRuleset for the given OpenType info, script, and language.

This function is part of a convenience scheme that highly simplifies using a PangoOTRuleset to represent features for a specific pair of script and language. So one can use this function passing in the script and language of interest, and later try to add features to the ruleset by just specifying the feature name or tag, without having to deal with finding script, language, or feature indices manually.

In excess to what `pango_ot_ruleset_new()` does, this function will:

- Find the PangoOTTag script and language tags associated with `script` and `language` using `pango_ot_tag_from_script()` and `pango_ot_tag_from_language()`,
- For each of table types `PANGO_OT_TABLE_GSUB` and `PANGO_OT_TABLE_GPOS`, find the script index of the script tag found and the language system index of the language tag found in that script system, using `pango_ot_info_find_script()` and `pango_ot_info_find_language()`,
- For found language-systems, if they have required feature index, add that feature to the ruleset using `pango_ot_ruleset_add_feature()`,
- Remember found script and language indices for both table types, and use them in future `pango_ot_ruleset_maybe_add_feature()` and `pango_ot_ruleset_maybe_add_features()`.

Because of the way return values of `pango_ot_info_find_script()` and `pango_ot_info_find_language()` are ignored, this function automatically finds and uses the 'DFLT' script and the default language-system.

`info` : | a PangoOTInfo.
`script` : | a PangoScript.
`language` : | a PangoLanguage.
Returns : | the newly allocated PangoOTRuleset, which should be freed with `g_object_unref()`.

Since 1.18

### pango_ot_ruleset_new_from_description ()

    PangoOTRuleset*     pango_ot_ruleset_new_from_description
                                                            (PangoOTInfo *info,
                                                             const PangoOTRulesetDescription *desc);

Creates a new PangoOTRuleset for the given OpenType infor and matching the given ruleset description.

This is a convenience function that calls `pango_ot_ruleset_new_for()` and adds the static GSUB/GPOS features to the resulting ruleset, followed by adding other features to both GSUB and GPOS.

The static feature map members of `desc` should be alive as long as `info` is.

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

Since 1.18

### 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_maybe_add_feature ()

    gboolean            pango_ot_ruleset_maybe_add_feature  (PangoOTRuleset *ruleset,
                                                             PangoOTTableType table_type,
                                                             PangoOTTag feature_tag,
                                                             gulong property_bit);

This is a convenience function that first tries to find the feature using `pango_ot_info_find_feature()` and the ruleset script and language passed to `pango_ot_ruleset_new_for()`, and if the feature is found, adds it to the ruleset.

If `ruleset` was not created using `pango_ot_ruleset_new_for()`, this function does nothing.

`ruleset` : | a PangoOTRuleset.
`table_type` : | the table type to add a feature to.
`feature_tag` : | the tag 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.
Returns : | `TRUE` if the feature was found and added to ruleset, `FALSE` otherwise.

Since 1.18

### pango_ot_ruleset_maybe_add_features ()

    guint               pango_ot_ruleset_maybe_add_features (PangoOTRuleset *ruleset,
                                                             PangoOTTableType table_type,
                                                             const PangoOTFeatureMap *features,
                                                             guint n_features);

This is a convenience function that for each feature in the feature map array `features` converts the feature name to a PangoOTTag feature tag using `PANGO_OT_TAG_MAKE()` and calls `pango_ot_ruleset_maybe_add_feature()` on it.

`ruleset` : | a PangoOTRuleset.
`table_type` : | the table type to add features to.
`features` : | array of feature name and property bits to add.
`n_features` : | number of feature records in `features` array.
Returns : | The number of features in `features` that were found and added to `ruleset`.

Since 1.18

### pango_ot_ruleset_get_feature_count ()

    guint               pango_ot_ruleset_get_feature_count  (const PangoOTRuleset *ruleset,
                                                             guint *n_gsub_features,
                                                             guint *n_gpos_features);

Gets the number of GSUB and GPOS features in the ruleset.

`ruleset` : | a PangoOTRuleset.
`n_gsub_features` : | location to store number of GSUB features, or `NULL`.
`n_gpos_features` : | location to store number of GPOS features, or `NULL`.
Returns : | Total number of features in the `ruleset`.

Since 1.18

### pango_ot_ruleset_substitute ()

    void                pango_ot_ruleset_substitute         (const 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           (const 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

### pango_ot_ruleset_description_copy ()

    PangoOTRulesetDescription* pango_ot_ruleset_description_copy
                                                            (const PangoOTRulesetDescription *desc);

Creates a copy of `desc`, which should be freed with `pango_ot_ruleset_description_free()`. Primarily used internally by `pango_ot_ruleset_get_for_description()` to cache rulesets for ruleset descriptions.

`desc` : | ruleset description to copy
Returns : | the newly allocated PangoOTRulesetDescription, which should be freed with `pango_ot_ruleset_description_free()`.

Since 1.18

### pango_ot_ruleset_description_equal ()

    gboolean            pango_ot_ruleset_description_equal  (const PangoOTRulesetDescription *desc1,
                                                             const PangoOTRulesetDescription *desc2);

Compares two ruleset descriptions for equality. Two ruleset descriptions are considered equal if the rulesets they describe are provably identical. This means that their script, language, and all feature sets should be equal. For static feature sets, the array addresses are compared directly, while for other features, the list of features is compared one by one. (Two ruleset descriptions may result in identical rulesets being created, but still compare `FALSE`.)

`desc1` : | a ruleset description
`desc2` : | a ruleset description
Returns : | `TRUE` if two ruleset descriptions are identical, `FALSE` otherwise.

Since 1.18

### pango_ot_ruleset_description_free ()

    void                pango_ot_ruleset_description_free   (PangoOTRulesetDescription *desc);

Frees a ruleset description allocated by `pango_ot_ruleset_description_copy()`.

`desc` : | an allocated PangoOTRulesetDescription

Since 1.18

### pango_ot_ruleset_description_hash ()

    guint               pango_ot_ruleset_description_hash   (const PangoOTRulesetDescription *desc);

Computes a hash of a PangoOTRulesetDescription structure suitable to be used, for example, as an argument to `g_hash_table_new()`.

`desc` : | a ruleset description
Returns : | the hash value.

Since 1.18

### pango_ot_tag_from_language ()

    PangoOTTag          pango_ot_tag_from_language          (PangoLanguage *language);

Finds the OpenType language-system tag best describing `language`.

`language` : | A PangoLanguage, or `NULL`
Returns : | PangoOTTag best matching `language` or `PANGO_OT_TAG_DEFAULT_LANGUAGE` if none found or if `language` is `NULL`.

Since 1.18

### pango_ot_tag_from_script ()

    PangoOTTag          pango_ot_tag_from_script            (PangoScript script);

Finds the OpenType script tag corresponding to `script`.

The `PANGO_SCRIPT_COMMON`, `PANGO_SCRIPT_INHERITED`, and `PANGO_SCRIPT_UNKNOWN` scripts are mapped to the OpenType 'DFLT' script tag that is also defined as `PANGO_OT_TAG_DEFAULT_SCRIPT`.

Note that multiple PangoScript values may map to the same OpenType script tag. In particular, `PANGO_SCRIPT_HIRAGANA` and `PANGO_SCRIPT_KATAKANA` both map to the OT tag 'kana'.

`script` : | A PangoScript
Returns : | PangoOTTag corresponding to `script` or `PANGO_OT_TAG_DEFAULT_SCRIPT` if none found.

Since 1.18

### pango_ot_tag_to_language ()

    PangoLanguage*      pango_ot_tag_to_language            (PangoOTTag language_tag);

Finds a PangoLanguage corresponding to `language_tag`.

`language_tag` : | A PangoOTTag OpenType language-system tag
Returns : | PangoLanguage best matching `language_tag` or PangoLanguage corresponding to the string "xx" if none found.

Since 1.18

### pango_ot_tag_to_script ()

    PangoScript         pango_ot_tag_to_script              (PangoOTTag script_tag);

Finds the PangoScript corresponding to `script_tag`.

The 'DFLT' script tag is mapped to `PANGO_SCRIPT_COMMON`.

Note that an OpenType script tag may correspond to multiple PangoScript values. In such cases, the PangoScript value with the smallest value is returned. In particular, `PANGO_SCRIPT_HIRAGANA` and `PANGO_SCRIPT_KATAKANA` both map to the OT tag 'kana'. This function will return `PANGO_SCRIPT_HIRAGANA` for 'kana'.

`script_tag` : | A PangoOTTag OpenType script tag
Returns : | PangoScript corresponding to `script_tag` or `PANGO_SCRIPT_UNKNOWN` if none found.

Since 1.18