1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Obtaining information from OpenType tables
7 <!-- ##### SECTION Long_Description ##### -->
9 Functions and macros in this section are used to implement the OpenType Layout
10 features and algorithms. These are mostly useful when writing Fontconfig-based
14 <!-- ##### SECTION See_Also ##### -->
19 <!-- ##### SECTION Stability_Level ##### -->
22 <!-- ##### TYPEDEF PangoOTTag ##### -->
24 The <type>PangoOTTag</type> typedef is used to represent TrueType and OpenType
25 four letter tags inside Pango. Use PANGO_OT_TAG_MAKE()
26 or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create <type>PangoOTTag</type>s manually.
30 <!-- ##### STRUCT PangoOTInfo ##### -->
32 The #PangoOTInfo struct contains the various
33 tables associated with an OpenType font. It contains only private fields and
34 should only be accessed via the <function>pango_ot_info_*</function> functions
35 which are documented below. To obtain a #PangoOTInfo,
36 use pango_ot_info_new().
40 <!-- ##### STRUCT PangoOTBuffer ##### -->
42 The #PangoOTBuffer structure is used to store strings of glyphs associated
43 with a #PangoFcFont, suitable for OpenType layout processing. It contains
44 only private fields and should only be accessed via the
45 <function>pango_ot_buffer_*</function> functions which are documented below.
46 To obtain a #PangoOTBuffer, use pango_ot_buffer_new().
50 <!-- ##### STRUCT PangoOTGlyph ##### -->
52 The #PangoOTGlyph structure represents a single glyph together with
53 information used for OpenType layout processing of the glyph.
54 It contains the following fields.
57 @glyph: the glyph itself.
58 @properties: the properties value, identifying which features should be
59 applied on this glyph. See pango_ruleset_add_feature().
60 @cluster: the cluster that this glyph belongs to.
61 @component: a component value, set by the OpenType layout engine.
62 @ligID: a ligature index value, set by the OpenType layout engine.
63 @internal: for Pango internal use
65 <!-- ##### STRUCT PangoOTRuleset ##### -->
67 The #PangoOTRuleset structure holds a
68 set of features selected from the tables in an OpenType font.
69 (A feature is an operation such as adjusting glyph positioning
70 that should be applied to a text feature such as a certain
71 type of accent.) A #PangoOTRuleset
72 is created with pango_ot_ruleset_new(), features are added
73 to it with pango_ot_ruleset_add_feature(), then it is
74 applied to a #PangoGlyphString with pango_ot_ruleset_shape().
78 <!-- ##### STRUCT PangoOTRulesetDescription ##### -->
80 The #PangoOTRuleset structure holds all the information needed
81 to build a complete #PangoOTRuleset from an OpenType font.
82 The main use of this struct is to act as the key for a per-font
83 hash of rulesets. The user populates a ruleset description and
84 gets the ruleset using pango_ot_ruleset_get_for_description()
85 or create a new one using pango_ot_ruleset_new_from_description().
88 @script: a #PangoScript.
89 @language: a #PangoLanguage.
90 @static_gsub_features: static map of GSUB features, or %NULL.
91 @n_static_gsub_features: length of @static_gsub_features, or 0.
92 @static_gpos_features: static map of GPOS features, or %NULL.
93 @n_static_gpos_features: length of @static_gpos_features, or 0.
94 @other_features: map of extra features to add to both GSUB and GPOS, or %NULL.
95 Unlike the static maps, this pointer need not live beyond
96 the life of function calls taking this struct.
97 @n_other_features: length of @other_features, or 0.
100 <!-- ##### ENUM PangoOTTableType ##### -->
102 The <type>PangoOTTableType</type> enumeration values are used to
103 identify the various OpenType tables in the
104 <function>pango_ot_info_*</function> functions.
107 @PANGO_OT_TABLE_GSUB: The GSUB table.
108 @PANGO_OT_TABLE_GPOS: The GPOS table.
110 <!-- ##### STRUCT PangoOTFeatureMap ##### -->
112 The <type>PangoOTFeatureMap</type> typedef is used to represent an OpenType
113 feature with the property bit associated with it. The feature tag is
114 represented as a char array instead of a #PangoOTTag for convenience.
117 @feature_name: feature tag in represented as four-letter ASCII string.
118 @property_bit: the property bit to use for this feature. See
119 pango_ot_ruleset_add_feature() for details.
122 <!-- ##### MACRO PANGO_OT_TAG_MAKE ##### -->
124 Creates a #PangoOTTag from four characters. This is similar and
125 compatible with the <function>FT_MAKE_TAG()</function> macro from
129 @c1: First character.
130 @c2: Second character.
131 @c3: Third character.
132 @c4: Fourth character.
135 <!-- ##### MACRO PANGO_OT_TAG_MAKE_FROM_STRING ##### -->
137 Creates a #PangoOTTag from a string. The string should be at least
138 four characters long (pad with space characters if needed), and need
139 not be nul-terminated. This is a convenience wrapper around
140 PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for
141 example, as a switch expression, as it dereferences pointers.
144 @s: The string representation of the tag.
147 <!-- ##### MACRO PANGO_OT_ALL_GLYPHS ##### -->
149 This is used as the property bit in pango_ot_ruleset_add_feature() when a
150 feature should be applied to all glyphs.
156 <!-- ##### MACRO PANGO_OT_NO_FEATURE ##### -->
158 This is used as a feature index that represent no feature, that is, should be
159 skipped. It may be returned as feature index by pango_ot_info_find_feature()
160 if the feature is not found, and pango_ot_rulset_add_feature() function
161 automatically skips this value, so no special handling is required by the
168 <!-- ##### MACRO PANGO_OT_NO_SCRIPT ##### -->
170 This is used as a script index that represent no script, that is, when the
171 requested script was not found, and a default ('DFLT') script was not found
172 either. It may be returned as script index by pango_ot_info_find_script()
173 if the script or a default script are not found, all other functions
174 taking a script index essentially return if the input script index is
175 this value, so no special handling is required by the user.
181 <!-- ##### MACRO PANGO_OT_DEFAULT_LANGUAGE ##### -->
183 This is used as the language index in pango_ot_info_find_feature() when
184 the default language system of the script is desired.
186 It is also returned by pango_ot_info_find_language() if the requested language
187 is not found, or the requested language tag was PANGO_OT_TAG_DEFAULT_LANGUAGE.
188 The end result is that one can always call pango_ot_tag_from_language()
189 followed by pango_ot_info_find_language() and pass the result to
190 pango_ot_info_find_feature() without having to worry about falling back to
191 default language system explicitly.
197 <!-- ##### MACRO PANGO_OT_TAG_DEFAULT_LANGUAGE ##### -->
199 This is a #PangoOTTag representing a special language tag 'dflt'. It is
200 returned as language tag by pango_ot_tag_from_language() if the requested
201 language is not found. It is safe to pass this value to
202 pango_ot_info_find_language() as that function falls back to returning default
203 language-system if the requested language tag is not found.
209 <!-- ##### MACRO PANGO_OT_TAG_DEFAULT_SCRIPT ##### -->
211 This is a #PangoOTTag representing the special script tag 'DFLT'. It is
212 returned as script tag by pango_ot_tag_from_script() if the requested script
219 <!-- ##### FUNCTION pango_ot_info_get ##### -->
228 <!-- ##### FUNCTION pango_ot_info_find_script ##### -->
240 <!-- ##### FUNCTION pango_ot_info_find_language ##### -->
250 @required_feature_index:
254 <!-- ##### FUNCTION pango_ot_info_find_feature ##### -->
268 <!-- ##### FUNCTION pango_ot_info_list_scripts ##### -->
278 <!-- ##### FUNCTION pango_ot_info_list_languages ##### -->
290 <!-- ##### FUNCTION pango_ot_info_list_features ##### -->
303 <!-- ##### FUNCTION pango_ot_buffer_new ##### -->
312 <!-- ##### FUNCTION pango_ot_buffer_destroy ##### -->
320 <!-- ##### FUNCTION pango_ot_buffer_clear ##### -->
328 <!-- ##### FUNCTION pango_ot_buffer_add_glyph ##### -->
339 <!-- ##### FUNCTION pango_ot_buffer_set_rtl ##### -->
348 <!-- ##### FUNCTION pango_ot_buffer_set_zero_width_marks ##### -->
357 <!-- ##### FUNCTION pango_ot_buffer_get_glyphs ##### -->
367 <!-- ##### FUNCTION pango_ot_buffer_output ##### -->
376 <!-- ##### FUNCTION pango_ot_ruleset_get_for_description ##### -->
386 <!-- ##### FUNCTION pango_ot_ruleset_new ##### -->
395 <!-- ##### FUNCTION pango_ot_ruleset_new_for ##### -->
406 <!-- ##### FUNCTION pango_ot_ruleset_new_from_description ##### -->
416 <!-- ##### FUNCTION pango_ot_ruleset_add_feature ##### -->
427 <!-- ##### FUNCTION pango_ot_ruleset_maybe_add_feature ##### -->
439 <!-- ##### FUNCTION pango_ot_ruleset_maybe_add_features ##### -->
451 <!-- ##### FUNCTION pango_ot_ruleset_get_feature_count ##### -->
462 <!-- ##### FUNCTION pango_ot_ruleset_substitute ##### -->
471 <!-- ##### FUNCTION pango_ot_ruleset_position ##### -->
480 <!-- ##### FUNCTION pango_ot_ruleset_description_copy ##### -->
489 <!-- ##### FUNCTION pango_ot_ruleset_description_equal ##### -->
499 <!-- ##### FUNCTION pango_ot_ruleset_description_free ##### -->
507 <!-- ##### FUNCTION pango_ot_ruleset_description_hash ##### -->
516 <!-- ##### FUNCTION pango_ot_tag_from_language ##### -->
525 <!-- ##### FUNCTION pango_ot_tag_from_script ##### -->
534 <!-- ##### FUNCTION pango_ot_tag_to_language ##### -->
543 <!-- ##### FUNCTION pango_ot_tag_to_script ##### -->