Merge pull request #1679 from n8willis/docs-gtkdoc-extern

[Docs] Add GTK-Doc comments for external APIs
This commit is contained in:
Khaled Hosny 2020-09-26 10:41:38 +02:00 committed by GitHub
commit 5539d158b7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 601 additions and 222 deletions

View File

@ -41,8 +41,10 @@
* @short_description: Font face objects * @short_description: Font face objects
* @include: hb.h * @include: hb.h
* *
* Font face is objects represent a single face in a font family. * A font face is an object that represents a single face from within a
* More exactly, a font face represents a single face in a binary font file. * font family.
*
* More precisely, a font face represents a single face in a binary font file.
* Font faces are typically built from a binary blob and a face index. * Font faces are typically built from a binary blob and a face index.
* Font faces are used to create fonts. * Font faces are used to create fonts.
**/ **/
@ -52,7 +54,7 @@
* hb_face_count: * hb_face_count:
* @blob: a blob. * @blob: a blob.
* *
* Get number of faces in a blob. * Fetches the number of faces in a blob.
* *
* Return value: Number of faces in @blob * Return value: Number of faces in @blob
* *
@ -96,13 +98,19 @@ DEFINE_NULL_INSTANCE (hb_face_t) =
/** /**
* hb_face_create_for_tables: * hb_face_create_for_tables:
* @reference_table_func: (closure user_data) (destroy destroy) (scope notified): * @reference_table_func: (closure user_data) (destroy destroy) (scope notified): Table-referencing function
* @user_data: * @user_data: A pointer to the user data
* @destroy: * @destroy: (optional): A callback to call when @data is not needed anymore
* *
* Variant of hb_face_create(), built for those cases where it is more
* convenient to provide data for individual tables instead of the whole font
* data. With the caveat that hb_face_get_table_tags() does not currently work
* with faces created this way.
*
* Creates a new face object from the specified @user_data and @reference_table_func,
* with the @destroy callback.
* *
* * Return value: (transfer full): The new face object
* Return value: (transfer full)
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -182,12 +190,15 @@ _hb_face_for_data_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void
/** /**
* hb_face_create: (Xconstructor) * hb_face_create: (Xconstructor)
* @blob: * @blob: #hb_blob_t to work upon
* @index: * @index: The index of the face within @blob
* *
* Constructs a new face object from the specified blob and
* a face index into that blob. This is used for blobs of
* file formats such as Dfont and TTC that can contain more
* than one face.
* *
* * Return value: (transfer full): The new face object
* Return value: (transfer full):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -222,9 +233,9 @@ hb_face_create (hb_blob_t *blob,
/** /**
* hb_face_get_empty: * hb_face_get_empty:
* *
* Fetches the singleton empty face object.
* *
* * Return value: (transfer full) The empty face object
* Return value: (transfer full)
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -237,11 +248,11 @@ hb_face_get_empty ()
/** /**
* hb_face_reference: (skip) * hb_face_reference: (skip)
* @face: a face. * @face: A face object
* *
* Increases the reference count on a face object.
* *
* * Return value: The @face object
* Return value:
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -253,9 +264,11 @@ hb_face_reference (hb_face_t *face)
/** /**
* hb_face_destroy: (skip) * hb_face_destroy: (skip)
* @face: a face. * @face: A face object
* *
* * Decreases the reference count on a face object. When the
* reference count reaches zero, the face is destroyed,
* freeing all memory.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -283,15 +296,15 @@ hb_face_destroy (hb_face_t *face)
/** /**
* hb_face_set_user_data: (skip) * hb_face_set_user_data: (skip)
* @face: a face. * @face: A face object
* @key: * @key: The user-data key to set
* @data: * @data: A pointer to the user data
* @destroy: * @destroy: (optional): A callback to call when @data is not needed anymore
* @replace: * @replace: Whether to replace an existing data with the same key
* *
* Attaches a user-data key/data pair to the given face object.
* *
* * Return value: %true if success, false otherwise
* Return value:
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -307,12 +320,13 @@ hb_face_set_user_data (hb_face_t *face,
/** /**
* hb_face_get_user_data: (skip) * hb_face_get_user_data: (skip)
* @face: a face. * @face: A face object
* @key: * @key: The user-data key to query
* *
* Fetches the user data associated with the specified key,
* attached to the specified face object.
* *
* * Return value: (transfer none): A pointer to the user data
* Return value: (transfer none):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -325,9 +339,9 @@ hb_face_get_user_data (const hb_face_t *face,
/** /**
* hb_face_make_immutable: * hb_face_make_immutable:
* @face: a face. * @face: A face object
*
* *
* Makes the given face object immutable.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -342,11 +356,11 @@ hb_face_make_immutable (hb_face_t *face)
/** /**
* hb_face_is_immutable: * hb_face_is_immutable:
* @face: a face. * @face: A face object
* *
* Tests whether the given face object is immutable.
* *
* * Return value: True is @face is immutable, false otherwise
* Return value:
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -359,12 +373,13 @@ hb_face_is_immutable (const hb_face_t *face)
/** /**
* hb_face_reference_table: * hb_face_reference_table:
* @face: a face. * @face: A face object
* @tag: * @tag: The #hb_tag_t of the table to query
* *
* Fetches a reference to the specified table within
* the specified face.
* *
* * Return value: (transfer full): A pointer to the @tag table within @face
* Return value: (transfer full):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -380,11 +395,13 @@ hb_face_reference_table (const hb_face_t *face,
/** /**
* hb_face_reference_blob: * hb_face_reference_blob:
* @face: a face. * @face: A face object
* *
* Fetches a pointer to the binary blob that contains the
* specified face. Returns an empty blob if referencing face data is not
* possible.
* *
* * Return value: (transfer full): A pointer to the blob for @face
* Return value: (transfer full):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -396,10 +413,13 @@ hb_face_reference_blob (hb_face_t *face)
/** /**
* hb_face_set_index: * hb_face_set_index:
* @face: a face. * @face: A face object
* @index: * @index: The index to assign
* *
* Assigns the specified face-index to @face. Fails if the
* face is immutable.
* *
* <note>Note: face indices within a collection are zero-based.</note>
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -415,11 +435,13 @@ hb_face_set_index (hb_face_t *face,
/** /**
* hb_face_get_index: * hb_face_get_index:
* @face: a face. * @face: A face object
* *
* Fetches the face-index corresponding to the given face.
* *
* <note>Note: face indices within a collection are zero-based.</note>
* *
* Return value: * Return value: The index of @face.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -431,10 +453,10 @@ hb_face_get_index (const hb_face_t *face)
/** /**
* hb_face_set_upem: * hb_face_set_upem:
* @face: a face. * @face: A face object
* @upem: * @upem: The units-per-em value to assign
*
* *
* Sets the units-per-em (upem) for a face object to the specified value.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -450,11 +472,11 @@ hb_face_set_upem (hb_face_t *face,
/** /**
* hb_face_get_upem: * hb_face_get_upem:
* @face: a face. * @face: A face object
* *
* Fetches the units-per-em (upem) value of the specified face object.
* *
* * Return value: The upem value of @face
* Return value:
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -466,10 +488,10 @@ hb_face_get_upem (const hb_face_t *face)
/** /**
* hb_face_set_glyph_count: * hb_face_set_glyph_count:
* @face: a face. * @face: A face object
* @glyph_count: * @glyph_count: The glyph-count value to assign
*
* *
* Sets the glyph count for a face object to the specified value.
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -485,11 +507,11 @@ hb_face_set_glyph_count (hb_face_t *face,
/** /**
* hb_face_get_glyph_count: * hb_face_get_glyph_count:
* @face: a face. * @face: A face object
* *
* Fetches the glyph-count value of the specified face object.
* *
* * Return value: The glyph-count value of @face
* Return value:
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -501,14 +523,16 @@ hb_face_get_glyph_count (const hb_face_t *face)
/** /**
* hb_face_get_table_tags: * hb_face_get_table_tags:
* @face: a face. * @face: A face object
* @start_offset: index of first tag to return. * @start_offset: The index of first table tag to retrieve
* @table_count: input length of @table_tags array, output number of items written. * @table_count: (inout): Input = the maximum number of table tags to return;
* @table_tags: array to write tags into. * Output = the actual number of table tags returned (may be zero)
* @table_tags: (out) (array length=table_count): The array of table tags found
* *
* Retrieves table tags for a face, if possible. * Fetches a list of all table tags for a face, if possible. The list returned will
* begin at the offset provided
* *
* Return value: total number of tables, or 0 if not possible to list. * Return value: Total number of tables, or zero if it is not possible to list
* *
* Since: 1.6.0 * Since: 1.6.0
**/ **/
@ -542,8 +566,11 @@ hb_face_get_table_tags (const hb_face_t *face,
#ifndef HB_NO_FACE_COLLECT_UNICODES #ifndef HB_NO_FACE_COLLECT_UNICODES
/** /**
* hb_face_collect_unicodes: * hb_face_collect_unicodes:
* @face: font face. * @face: A face object
* @out: set to add Unicode characters covered by @face to. * @out: The set to add Unicode characters to
*
* Collects all of the Unicode characters covered by @face and adds
* them to the #hb_set_t set @out.
* *
* Since: 1.9.0 * Since: 1.9.0
*/ */
@ -555,10 +582,11 @@ hb_face_collect_unicodes (hb_face_t *face,
} }
/** /**
* hb_face_collect_variation_selectors: * hb_face_collect_variation_selectors:
* @face: font face. * @face: A face object
* @out: set to add Variation Selector characters covered by @face to. * @out: The set to add Variation Selector characters to
*
* *
* Collects all Unicode "Variation Selector" characters covered by @face and adds
* them to the #hb_set_t set @out.
* *
* Since: 1.9.0 * Since: 1.9.0
*/ */
@ -570,10 +598,12 @@ hb_face_collect_variation_selectors (hb_face_t *face,
} }
/** /**
* hb_face_collect_variation_unicodes: * hb_face_collect_variation_unicodes:
* @face: font face. * @face: A face object
* @out: set to add Unicode characters for @variation_selector covered by @face to. * @variation_selector: The Variation Selector to query
* * @out: The set to add Unicode characters to
* *
* Collects all Unicode characters for @variation_selector covered by @face and adds
* them to the #hb_set_t set @out.
* *
* Since: 1.9.0 * Since: 1.9.0
*/ */
@ -708,6 +738,9 @@ hb_face_builder_create ()
/** /**
* hb_face_builder_add_table: * hb_face_builder_add_table:
* @face: A face object created with hb_face_builder_create()
* @tag: The #hb_tag_t of the table to add
* @blob: The blob containing the table data to add
* *
* Add table for @tag with data provided by @blob to the face. @face must * Add table for @tag with data provided by @blob to the face. @face must
* be created using hb_face_builder_create(). * be created using hb_face_builder_create().

View File

@ -46,6 +46,12 @@ hb_face_count (hb_blob_t *blob);
* hb_face_t * hb_face_t
*/ */
/**
* hb_face_t:
*
* Data type for holding font faces.
*
**/
typedef struct hb_face_t hb_face_t; typedef struct hb_face_t hb_face_t;
HB_EXTERN hb_face_t * HB_EXTERN hb_face_t *

View File

@ -306,6 +306,9 @@ _hb_ot_get_font_funcs ()
/** /**
* hb_ot_font_set_funcs: * hb_ot_font_set_funcs:
* @font: #hb_font_t to work upon
*
* Sets the font functions to use when working with @font.
* *
* Since: 0.9.28 * Since: 0.9.28
**/ **/

View File

@ -76,7 +76,7 @@
* Tests whether a face includes any kerning data in the 'kern' table. * Tests whether a face includes any kerning data in the 'kern' table.
* Does NOT test for kerning lookups in the GPOS table. * Does NOT test for kerning lookups in the GPOS table.
* *
* Return value: true if data found, false otherwise * Return value: %true if data found, false otherwise
* *
**/ **/
bool bool
@ -92,7 +92,7 @@ hb_ot_layout_has_kerning (hb_face_t *face)
* Tests whether a face includes any state-machine kerning in the 'kern' table. * Tests whether a face includes any state-machine kerning in the 'kern' table.
* Does NOT examine the GPOS table. * Does NOT examine the GPOS table.
* *
* Return value: true if data found, false otherwise * Return value: %true if data found, false otherwise
* *
**/ **/
bool bool
@ -112,7 +112,7 @@ hb_ot_layout_has_machine_kerning (hb_face_t *face)
* *
* Does NOT examine the GPOS table. * Does NOT examine the GPOS table.
* *
* Return value: true is data found, false otherwise * Return value: %true is data found, false otherwise
* *
**/ **/
bool bool
@ -268,7 +268,7 @@ _hb_ot_layout_set_glyph_props (hb_font_t *font,
* *
* Tests whether a face has any glyph classes defined in its GDEF table. * Tests whether a face has any glyph classes defined in its GDEF table.
* *
* Return value: true if data found, false otherwise * Return value: %true if data found, false otherwise
* *
**/ **/
hb_bool_t hb_bool_t
@ -444,7 +444,7 @@ hb_ot_layout_table_get_script_tags (hb_face_t *face,
* Fetches the index if a given script tag in the specified face's GSUB table * Fetches the index if a given script tag in the specified face's GSUB table
* or GPOS table. * or GPOS table.
* *
* Return value: true if the script is found, false otherwise * Return value: %true if the script is found, false otherwise
* *
**/ **/
hb_bool_t hb_bool_t
@ -598,7 +598,7 @@ hb_ot_layout_table_get_feature_tags (hb_face_t *face,
* Fetches the index for a given feature tag in the specified face's GSUB table * Fetches the index for a given feature tag in the specified face's GSUB table
* or GPOS table. * or GPOS table.
* *
* Return value: true if the feature is found, false otherwise * Return value: %true if the feature is found, false otherwise
**/ **/
bool bool
hb_ot_layout_table_find_feature (hb_face_t *face, hb_ot_layout_table_find_feature (hb_face_t *face,
@ -663,7 +663,7 @@ hb_ot_layout_script_get_language_tags (hb_face_t *face,
* Fetches the index of a given language tag in the specified face's GSUB table * Fetches the index of a given language tag in the specified face's GSUB table
* or GPOS table, underneath the specified script tag. * or GPOS table, underneath the specified script tag.
* *
* Return value: true if the language tag is found, false otherwise * Return value: %true if the language tag is found, false otherwise
* *
* Since: ?? * Since: ??
* Deprecated: ?? * Deprecated: ??
@ -697,7 +697,7 @@ hb_ot_layout_script_find_language (hb_face_t *face,
* Fetches the index of a given language tag in the specified face's GSUB table * Fetches the index of a given language tag in the specified face's GSUB table
* or GPOS table, underneath the specified script index. * or GPOS table, underneath the specified script index.
* *
* Return value: true if the language tag is found, false otherwise * Return value: %true if the language tag is found, false otherwise
* *
* Since: 2.0.0 * Since: 2.0.0
**/ **/
@ -739,7 +739,7 @@ hb_ot_layout_script_select_language (hb_face_t *face,
* Fetches the index of a requested feature in the given face's GSUB or GPOS table, * Fetches the index of a requested feature in the given face's GSUB or GPOS table,
* underneath the specified script and language. * underneath the specified script and language.
* *
* Return value: true if the feature is found, false otherwise * Return value: %true if the feature is found, false otherwise
* *
**/ **/
hb_bool_t hb_bool_t
@ -770,7 +770,7 @@ hb_ot_layout_language_get_required_feature_index (hb_face_t *face,
* Fetches the tag of a requested feature index in the given face's GSUB or GPOS table, * Fetches the tag of a requested feature index in the given face's GSUB or GPOS table,
* underneath the specified script and language. * underneath the specified script and language.
* *
* Return value: true if the feature is found, false otherwise * Return value: %true if the feature is found, false otherwise
* *
* Since: 0.9.30 * Since: 0.9.30
**/ **/
@ -877,7 +877,7 @@ hb_ot_layout_language_get_feature_tags (hb_face_t *face,
* Fetches the index of a given feature tag in the specified face's GSUB table * Fetches the index of a given feature tag in the specified face's GSUB table
* or GPOS table, underneath the specified script and language. * or GPOS table, underneath the specified script and language.
* *
* Return value: true if the feature is found, false otherwise * Return value: %true if the feature is found, false otherwise
* *
**/ **/
hb_bool_t hb_bool_t
@ -1196,7 +1196,7 @@ hb_ot_layout_collect_lookups (hb_face_t *face,
* @glyphs_before: (out): Array of glyphs preceding the substitution range * @glyphs_before: (out): Array of glyphs preceding the substitution range
* @glyphs_input: (out): Array of input glyphs that would be substituted by the lookup * @glyphs_input: (out): Array of input glyphs that would be substituted by the lookup
* @glyphs_after: (out): Array of glyphs following the substitution range * @glyphs_after: (out): Array of glyphs following the substitution range
* @glyphs_output: (out): Array of glyphs that would be the substitued output of the lookup * @glyphs_output: (out): Array of glyphs that would be the substituted output of the lookup
* *
* Fetches a list of all glyphs affected by the specified lookup in the * Fetches a list of all glyphs affected by the specified lookup in the
* specified face's GSUB table or GPOS table. * specified face's GSUB table or GPOS table.
@ -1245,7 +1245,7 @@ hb_ot_layout_lookup_collect_glyphs (hb_face_t *face,
* @face: #hb_face_t to work upon * @face: #hb_face_t to work upon
* @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS
* @coords: The variation coordinates to query * @coords: The variation coordinates to query
* @num_coords: The number of variation coorinates * @num_coords: The number of variation coordinates
* @variations_index: (out): The array of feature variations found for the query * @variations_index: (out): The array of feature variations found for the query
* *
* Fetches a list of feature variations in the specified face's GSUB table * Fetches a list of feature variations in the specified face's GSUB table
@ -1310,7 +1310,7 @@ hb_ot_layout_feature_with_variations_get_lookups (hb_face_t *face,
* *
* Tests whether the specified face includes any GSUB substitutions. * Tests whether the specified face includes any GSUB substitutions.
* *
* Return value: true if data found, false otherwise * Return value: %true if data found, false otherwise
* *
**/ **/
hb_bool_t hb_bool_t
@ -1331,7 +1331,7 @@ hb_ot_layout_has_substitution (hb_face_t *face)
* Tests whether a specified lookup in the specified face would * Tests whether a specified lookup in the specified face would
* trigger a substitution on the given glyph sequence. * trigger a substitution on the given glyph sequence.
* *
* Return value: true if a substitution would be triggered, false otherwise * Return value: %true if a substitution would be triggered, false otherwise
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -1488,7 +1488,7 @@ hb_ot_layout_lookups_substitute_closure (hb_face_t *face,
* hb_ot_layout_has_positioning: * hb_ot_layout_has_positioning:
* @face: #hb_face_t to work upon * @face: #hb_face_t to work upon
* *
* Return value: true if the face has GPOS data, false otherwise * Return value: %true if the face has GPOS data, false otherwise
* *
**/ **/
hb_bool_t hb_bool_t
@ -1561,7 +1561,7 @@ hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer)
* For more information on this distinction, see the [`size` feature documentation]( * For more information on this distinction, see the [`size` feature documentation](
* https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). * https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size).
* *
* Return value: true if data found, false otherwise * Return value: %true if data found, false otherwise
* *
* Since: 0.9.10 * Since: 0.9.10
**/ **/
@ -1625,7 +1625,7 @@ hb_ot_layout_get_size_params (hb_face_t *face,
* Fetches name indices from feature parameters for "Stylistic Set" ('ssXX') or * Fetches name indices from feature parameters for "Stylistic Set" ('ssXX') or
* "Character Variant" ('cvXX') features. * "Character Variant" ('cvXX') features.
* *
* Return value: true if data found, false otherwise * Return value: %true if data found, false otherwise
* *
* Since: 2.0.0 * Since: 2.0.0
**/ **/

View File

@ -1155,6 +1155,12 @@ _hb_ot_shape (hb_shape_plan_t *shape_plan,
/** /**
* hb_ot_shape_plan_collect_lookups: * hb_ot_shape_plan_collect_lookups:
* @shape_plan: #hb_shape_plan_t to query
* @table_tag: GSUB or GPOS
* @lookup_indexes: (out): The #hb_set_t set of lookups returned
*
* Computes the complete set of GSUB or GPOS lookups that are applicable
* under a given @shape_plan.
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -1189,6 +1195,15 @@ add_char (hb_font_t *font,
/** /**
* hb_ot_shape_glyphs_closure: * hb_ot_shape_glyphs_closure:
* @font: #hb_font_t to work upon
* @buffer: The input buffer to compute from
* @features: (array length=num_features): The features enabled on the buffer
* @num_features: The number of features enabled on the buffer
* @glyphs: (out): The #hb_set_t set of glyphs comprising the transitive closure of the query
*
* Computes the transitive closure of glyphs needed for a specified
* input buffer under the given font and feature list. The closure is
* computed as a set, not as a list.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/

View File

@ -37,10 +37,17 @@
* @short_description: Object representing a shaping plan * @short_description: Object representing a shaping plan
* @include: hb.h * @include: hb.h
* *
* Shape plans are not used for shaping directly, but can be access to query * Shape plans are an internal mechanism. Each plan contains state
* certain information about how shaping will perform given a set of input * describing how HarfBuzz will shape a particular text segment, based on
* parameters (script, language, direction, features, etc.) * the combination of segment properties and the capabilities in the
* Most client would not need to deal with shape plans directly. * font face in use.
*
* Shape plans are not used for shaping directly, but can be queried to
* access certain information about how shaping will perform, given a set
* of specific input parameters (script, language, direction, features,
* etc.).
*
* Most client programs will not need to deal with shape plans directly.
**/ **/
@ -164,15 +171,16 @@ hb_shape_plan_key_t::equal (const hb_shape_plan_key_t *other)
/** /**
* hb_shape_plan_create: (Xconstructor) * hb_shape_plan_create: (Xconstructor)
* @face: * @face: #hb_face_t to use
* @props: * @props: The #hb_segment_properties_t of the segment
* @user_features: (array length=num_user_features): * @user_features: (array length=num_user_features): The list of user-selected features
* @num_user_features: * @num_user_features: The number of user-selected features
* @shaper_list: (array zero-terminated=1): * @shaper_list: (array zero-terminated=1): List of shapers to try
* *
* Constructs a shaping plan for a combination of @face, @user_features, @props,
* and @shaper_list.
* *
* * Return value: (transfer full): The shaping plan
* Return value: (transfer full):
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -189,6 +197,24 @@ hb_shape_plan_create (hb_face_t *face,
shaper_list); shaper_list);
} }
/**
* hb_shape_plan_create2: (Xconstructor)
* @face: #hb_face_t to use
* @props: The #hb_segment_properties_t of the segment
* @user_features: (array length=num_user_features): The list of user-selected features
* @num_user_features: The number of user-selected features
* @coords: (array length=num_coords): The list of variation-space coordinates
* @num_coords: The number of variation-space coordinates
* @shaper_list: (array zero-terminated=1): List of shapers to try
*
* The variable-font version of #hb_shape_plan_create.
* Constructs a shaping plan for a combination of @face, @user_features, @props,
* and @shaper_list, plus the variation-space coordinates @coords.
*
* Return value: (transfer full): The shaping plan
*
* Since: 1.4.0
**/
hb_shape_plan_t * hb_shape_plan_t *
hb_shape_plan_create2 (hb_face_t *face, hb_shape_plan_create2 (hb_face_t *face,
const hb_segment_properties_t *props, const hb_segment_properties_t *props,
@ -248,9 +274,9 @@ bail:
/** /**
* hb_shape_plan_get_empty: * hb_shape_plan_get_empty:
* *
* Fetches the singleton empty shaping plan.
* *
* * Return value: (transfer full): The empty shaping plan
* Return value: (transfer full):
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -262,11 +288,11 @@ hb_shape_plan_get_empty ()
/** /**
* hb_shape_plan_reference: (skip) * hb_shape_plan_reference: (skip)
* @shape_plan: a shape plan. * @shape_plan: A shaping plan
* *
* Increases the reference count on the given shaping plan.
* *
* * Return value: (transfer full): @shape_plan
* Return value: (transfer full):
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -278,9 +304,11 @@ hb_shape_plan_reference (hb_shape_plan_t *shape_plan)
/** /**
* hb_shape_plan_destroy: (skip) * hb_shape_plan_destroy: (skip)
* @shape_plan: a shape plan. * @shape_plan: A shaping plan
*
* *
* Decreases the reference count on the given shaping plan. When the
* reference count reaches zero, the shaping plan is destroyed,
* freeing all memory.
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -298,13 +326,13 @@ hb_shape_plan_destroy (hb_shape_plan_t *shape_plan)
/** /**
* hb_shape_plan_set_user_data: (skip) * hb_shape_plan_set_user_data: (skip)
* @shape_plan: a shape plan. * @shape_plan: A shaping plan
* @key: * @key: The user-data key to set
* @data: * @data: A pointer to the user data
* @destroy: * @destroy: A callback to call when @data is not needed anymore
* @replace: * @replace: Whether to replace an existing data with the same key
*
* *
* Attaches a user-data key/data pair to the given shaping plan.
* *
* Return value: * Return value:
* *
@ -322,12 +350,13 @@ hb_shape_plan_set_user_data (hb_shape_plan_t *shape_plan,
/** /**
* hb_shape_plan_get_user_data: (skip) * hb_shape_plan_get_user_data: (skip)
* @shape_plan: a shape plan. * @shape_plan: A shaping plan
* @key: * @key: The user-data key to query
* *
* Fetches the user data associated with the specified key,
* attached to the specified shaping plan.
* *
* * Return value: (transfer none): A pointer to the user data
* Return value: (transfer none):
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -340,11 +369,11 @@ hb_shape_plan_get_user_data (hb_shape_plan_t *shape_plan,
/** /**
* hb_shape_plan_get_shaper: * hb_shape_plan_get_shaper:
* @shape_plan: a shape plan. * @shape_plan: A shaping plan
* *
* Fetches the shaper from a given shaping plan.
* *
* * Return value: (transfer none): The shaper
* Return value: (transfer none):
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -400,15 +429,16 @@ _hb_shape_plan_execute_internal (hb_shape_plan_t *shape_plan,
} }
/** /**
* hb_shape_plan_execute: * hb_shape_plan_execute:
* @shape_plan: a shape plan. * @shape_plan: A shaping plan
* @font: a font. * @font: The #hb_font_t to use
* @buffer: a buffer. * @buffer: The #hb_buffer_t to work upon
* @features: (array length=num_features): * @features: (array length=num_features): Features to enable
* @num_features: * @num_features: The number of features to enable
* *
* Executes the given shaping plan on the specified buffer, using
* the given @font and @features.
* *
* * Return value:
* Return value:
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -435,15 +465,16 @@ hb_shape_plan_execute (hb_shape_plan_t *shape_plan,
/** /**
* hb_shape_plan_create_cached: * hb_shape_plan_create_cached:
* @face: * @face: #hb_face_t to use
* @props: * @props: The #hb_segment_properties_t of the segment
* @user_features: (array length=num_user_features): * @user_features: (array length=num_user_features): The list of user-selected features
* @num_user_features: * @num_user_features: The number of user-selected features
* @shaper_list: (array zero-terminated=1): * @shaper_list: (array zero-terminated=1): List of shapers to try
* *
* Creates a cached shaping plan suitable for reuse, for a combination
* of @face, @user_features, @props, and @shaper_list.
* *
* * Return value: (transfer full): The shaping plan
* Return value: (transfer full):
* *
* Since: 0.9.7 * Since: 0.9.7
**/ **/
@ -460,6 +491,25 @@ hb_shape_plan_create_cached (hb_face_t *face,
shaper_list); shaper_list);
} }
/**
* hb_shape_plan_create_cached2:
* @face: #hb_face_t to use
* @props: The #hb_segment_properties_t of the segment
* @user_features: (array length=num_user_features): The list of user-selected features
* @num_user_features: The number of user-selected features
* @coords: (array length=num_coords): The list of variation-space coordinates
* @num_coords: The number of variation-space coordinates
* @shaper_list: (array zero-terminated=1): List of shapers to try
*
* The variable-font version of #hb_shape_plan_create_cached.
* Creates a cached shaping plan suitable for reuse, for a combination
* of @face, @user_features, @props, and @shaper_list, plus the
* variation-space coordinates @coords.
*
* Return value: (transfer full): The shaping plan
*
* Since: 1.4.0
**/
hb_shape_plan_t * hb_shape_plan_t *
hb_shape_plan_create_cached2 (hb_face_t *face, hb_shape_plan_create_cached2 (hb_face_t *face,
const hb_segment_properties_t *props, const hb_segment_properties_t *props,

View File

@ -36,6 +36,20 @@
HB_BEGIN_DECLS HB_BEGIN_DECLS
/**
* hb_shape_plan_t:
*
* Data type for holding a shaping plan.
*
* Shape plans contain information about how HarfBuzz will shape a
* particular text segment, based on the segment's properties and the
* capabilities in the font face in use.
*
* Shape plans can be queried about how shaping will perform, given a set
* of specific input parameters (script, language, direction, features,
* etc.).
*
**/
typedef struct hb_shape_plan_t hb_shape_plan_t; typedef struct hb_shape_plan_t hb_shape_plan_t;
HB_EXTERN hb_shape_plan_t * HB_EXTERN hb_shape_plan_t *

View File

@ -40,11 +40,16 @@
* @include: hb.h * @include: hb.h
* *
* Unicode functions are used to access Unicode character properties. * Unicode functions are used to access Unicode character properties.
* Client can pass its own Unicode functions to HarfBuzz, or access * With these functions, client programs can query various properties from
* the built-in Unicode functions that come with HarfBuzz. * the Unicode Character Database for any code point, such as General
* Category (gc), Script (sc), Canonical Combining Class (ccc), etc.
* *
* With the Unicode functions, one can query variour Unicode character * Client programs can optionally pass in their own Unicode functions
* properties, such as General Category, Script, Combining Class, etc. * that implement the same queries. The set of functions available is
* defined by the virtual methods in #hb_unicode_funcs_t.
*
* HarfBuzz provides built-in default functions for each method in
* #hb_unicode_funcs_t.
**/ **/
@ -133,6 +138,16 @@ hb_unicode_decompose_compatibility_nil (hb_unicode_funcs_t *ufuncs HB_UNUSED
#include "hb-icu.h" #include "hb-icu.h"
#endif #endif
/**
* hb_unicode_funcs_get_default:
*
* Fetches a pointer to the default Unicode-functions structure that is used
* when no functions are explicitly set on #hb_buffer_t.
*
* Return value: (transfer none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure
*
* Since: 0.9.2
**/
hb_unicode_funcs_t * hb_unicode_funcs_t *
hb_unicode_funcs_get_default () hb_unicode_funcs_get_default ()
{ {
@ -155,11 +170,11 @@ hb_unicode_funcs_get_default ()
/** /**
* hb_unicode_funcs_create: (Xconstructor) * hb_unicode_funcs_create: (Xconstructor)
* @parent: (nullable): * @parent: (nullable): Parent Unicode-functions structure
* *
* Creates a new #hb_unicode_funcs_t structure of Unicode functions.
* *
* * Return value: (transfer full): The Unicode-functions structure
* Return value: (transfer full):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -203,9 +218,9 @@ DEFINE_NULL_INSTANCE (hb_unicode_funcs_t) =
/** /**
* hb_unicode_funcs_get_empty: * hb_unicode_funcs_get_empty:
* *
* Fetches the singleton empty Unicode-functions structure.
* *
* * Return value: (transfer full): The empty Unicode-functions structure
* Return value: (transfer full):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -217,11 +232,11 @@ hb_unicode_funcs_get_empty ()
/** /**
* hb_unicode_funcs_reference: (skip) * hb_unicode_funcs_reference: (skip)
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* *
* Increases the reference count on a Unicode-functions structure.
* *
* * Return value: (transfer full): The Unicode-functions structure
* Return value: (transfer full):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -233,9 +248,11 @@ hb_unicode_funcs_reference (hb_unicode_funcs_t *ufuncs)
/** /**
* hb_unicode_funcs_destroy: (skip) * hb_unicode_funcs_destroy: (skip)
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
*
* *
* Decreases the reference count on a Unicode-functions structure. When
* the reference count reaches zero, the Unicode-functions structure is
* destroyed, freeing all memory.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -256,15 +273,15 @@ hb_unicode_funcs_destroy (hb_unicode_funcs_t *ufuncs)
/** /**
* hb_unicode_funcs_set_user_data: (skip) * hb_unicode_funcs_set_user_data: (skip)
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* @key: * @key: The user-data key
* @data: * @data: A pointer to the user data
* @destroy: * @destroy: A callback to call when @data is not needed anymore
* @replace: * @replace: Whether to replace an existing data with the same key
* *
* Attaches a user-data key/data pair to the specified Unicode-functions structure.
* *
* * Return value: %true if success, false otherwise
* Return value:
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -280,12 +297,13 @@ hb_unicode_funcs_set_user_data (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_funcs_get_user_data: (skip) * hb_unicode_funcs_get_user_data: (skip)
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* @key: * @key: The user-data key to query
* *
* Fetches the user-data associated with the specified key,
* attached to the specified Unicode-functions structure.
* *
* * Return value: (transfer none): A pointer to the user data
* Return value: (transfer none):
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -299,9 +317,10 @@ hb_unicode_funcs_get_user_data (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_funcs_make_immutable: * hb_unicode_funcs_make_immutable:
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
*
* *
* Makes the specified Unicode-functions structure
* immutable.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -316,11 +335,12 @@ hb_unicode_funcs_make_immutable (hb_unicode_funcs_t *ufuncs)
/** /**
* hb_unicode_funcs_is_immutable: * hb_unicode_funcs_is_immutable:
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* *
* Tests whether the specified Unicode-functions structure
* is immutable.
* *
* * Return value: %true if @ufuncs is immutable, false otherwise
* Return value:
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -332,11 +352,12 @@ hb_unicode_funcs_is_immutable (hb_unicode_funcs_t *ufuncs)
/** /**
* hb_unicode_funcs_get_parent: * hb_unicode_funcs_get_parent:
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* *
* Fetches the parent of the Unicode-functions structure
* @ufuncs.
* *
* * Return value: The parent Unicode-functions structure
* Return value:
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -389,14 +410,18 @@ HB_UNICODE_FUNCS_IMPLEMENT_CALLBACKS_SIMPLE
/** /**
* hb_unicode_compose: * hb_unicode_compose:
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* @a: * @a: The first Unicode code point to compose
* @b: * @b: The second Unicode code point to compose
* @ab: (out): * @ab: (out): The composition of @a, @b
* *
* Fetches the composition of a sequence of two Unicode
* code points.
* *
* Calls the composition function of the specified
* Unicode-functions structure @ufuncs.
* *
* Return value: * Return value: %true if @a and @b composed, false otherwise
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -411,14 +436,17 @@ hb_unicode_compose (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_decompose: * hb_unicode_decompose:
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* @ab: * @ab: Unicode code point to decompose
* @a: (out): * @a: (out): The first code point of the decomposition of @ab
* @b: (out): * @b: (out): The second code point of the decomposition of @ab
* *
* Fetches the decomposition of a Unicode code point.
* *
* Calls the decomposition function of the specified
* Unicode-functions structure @ufuncs.
* *
* Return value: * Return value: %true if @ab was decomposed, false otherwise
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -434,11 +462,12 @@ hb_unicode_decompose (hb_unicode_funcs_t *ufuncs,
#ifndef HB_DISABLE_DEPRECATED #ifndef HB_DISABLE_DEPRECATED
/** /**
* hb_unicode_decompose_compatibility: * hb_unicode_decompose_compatibility:
* @ufuncs: Unicode functions. * @ufuncs: The Unicode-functions structure
* @u: * @u: Code point to decompose
* @decomposed: (out): * @decomposed: (out): Compatibility decomposition of @u
*
* *
* Fetches the compatibility decomposition of a Unicode
* code point. Deprecated.
* *
* Return value: * Return value:
* *

View File

@ -48,7 +48,42 @@ HB_BEGIN_DECLS
#define HB_UNICODE_MAX 0x10FFFFu #define HB_UNICODE_MAX 0x10FFFFu
/* hb_unicode_general_category_t */ /**
* hb_unicode_general_category_t:
* @HB_UNICODE_GENERAL_CATEGORY_CONTROL: (Cc)
* @HB_UNICODE_GENERAL_CATEGORY_FORMAT: (Cf)
* @HB_UNICODE_GENERAL_CATEGORY_UNASSIGNED: (Cn)
* @HB_UNICODE_GENERAL_CATEGORY_PRIVATE_USE: (Co)
* @HB_UNICODE_GENERAL_CATEGORY_SURROGATE: (Cs)
* @HB_UNICODE_GENERAL_CATEGORY_LOWERCASE_LETTER: (Ll)
* @HB_UNICODE_GENERAL_CATEGORY_MODIFIER_LETTER: (Lm)
* @HB_UNICODE_GENERAL_CATEGORY_OTHER_LETTER: (Lo)
* @HB_UNICODE_GENERAL_CATEGORY_TITLECASE_LETTER: (Lt)
* @HB_UNICODE_GENERAL_CATEGORY_UPPERCASE_LETTER: (Lu)
* @HB_UNICODE_GENERAL_CATEGORY_SPACING_MARK: (Mc)
* @HB_UNICODE_GENERAL_CATEGORY_ENCLOSING_MARK: (Me)
* @HB_UNICODE_GENERAL_CATEGORY_NON_SPACING_MARK: (Mn)
* @HB_UNICODE_GENERAL_CATEGORY_DECIMAL_NUMBER: (Nd)
* @HB_UNICODE_GENERAL_CATEGORY_LETTER_NUMBER: (Nl)
* @HB_UNICODE_GENERAL_CATEGORY_OTHER_NUMBER: (No)
* @HB_UNICODE_GENERAL_CATEGORY_CONNECT_PUNCTUATION: (Pc)
* @HB_UNICODE_GENERAL_CATEGORY_DASH_PUNCTUATION: (Pd)
* @HB_UNICODE_GENERAL_CATEGORY_CLOSE_PUNCTUATION: (Pe)
* @HB_UNICODE_GENERAL_CATEGORY_FINAL_PUNCTUATION: (Pf)
* @HB_UNICODE_GENERAL_CATEGORY_INITIAL_PUNCTUATION: (Pi)
* @HB_UNICODE_GENERAL_CATEGORY_OTHER_PUNCTUATION: (Po)
* @HB_UNICODE_GENERAL_CATEGORY_OPEN_PUNCTUATION: (Ps)
* @HB_UNICODE_GENERAL_CATEGORY_CURRENCY_SYMBOL: (Sc)
* @HB_UNICODE_GENERAL_CATEGORY_MODIFIER_SYMBOL: (Sk)
* @HB_UNICODE_GENERAL_CATEGORY_MATH_SYMBOL: (Sm)
* @HB_UNICODE_GENERAL_CATEGORY_OTHER_SYMBOL: (So)
* @HB_UNICODE_GENERAL_CATEGORY_LINE_SEPARATOR: (Zl)
* @HB_UNICODE_GENERAL_CATEGORY_PARAGRAPH_SEPARATOR: (Zp)
* @HB_UNICODE_GENERAL_CATEGORY_SPACE_SEPARATOR: (Zs)
*
* Data type for the "General_Category" (gc) property from
* the Unicode Character Database.
**/
/* Unicode Character Database property: General_Category (gc) */ /* Unicode Character Database property: General_Category (gc) */
typedef enum typedef enum
@ -85,13 +120,72 @@ typedef enum
HB_UNICODE_GENERAL_CATEGORY_SPACE_SEPARATOR /* Zs */ HB_UNICODE_GENERAL_CATEGORY_SPACE_SEPARATOR /* Zs */
} hb_unicode_general_category_t; } hb_unicode_general_category_t;
/* hb_unicode_combining_class_t */ /**
* hb_unicode_combining_class_t:
/* Note: newer versions of Unicode may add new values. Clients should be ready to handle * @HB_UNICODE_COMBINING_CLASS_NOT_REORDERED
* any value in the 0..254 range being returned from hb_unicode_combining_class(). * @HB_UNICODE_COMBINING_CLASS_OVERLAY
*/ * @HB_UNICODE_COMBINING_CLASS_NUKTA
* @HB_UNICODE_COMBINING_CLASS_KANA_VOICING
/* Unicode Character Database property: Canonical_Combining_Class (ccc) */ * @HB_UNICODE_COMBINING_CLASS_VIRAMA
* @HB_UNICODE_COMBINING_CLASS_CCC11: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC12: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC13: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC14: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC15: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC16: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC17: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC18: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC19: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC20: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC21: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC22: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC23: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC24: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC25: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC26: (Hebrew)
* @HB_UNICODE_COMBINING_CLASS_CCC28: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC29: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC30: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC31: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC32: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC33: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC34: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC35: (Arabic)
* @HB_UNICODE_COMBINING_CLASS_CCC36: (Syriac)
* @HB_UNICODE_COMBINING_CLASS_CCC84: (Telugu)
* @HB_UNICODE_COMBINING_CLASS_CCC91: (Telugu)
* @HB_UNICODE_COMBINING_CLASS_CCC103: (Thai)
* @HB_UNICODE_COMBINING_CLASS_CCC107: (Thai)
* @HB_UNICODE_COMBINING_CLASS_CCC118: (Lao)
* @HB_UNICODE_COMBINING_CLASS_CCC122: (Lao)
* @HB_UNICODE_COMBINING_CLASS_CCC129: (Tibetan)
* @HB_UNICODE_COMBINING_CLASS_CCC130: (Tibetan)
* @HB_UNICODE_COMBINING_CLASS_CCC133: (Tibetan)
* @HB_UNICODE_COMBINING_CLASS_ATTACHED_BELOW_LEFT
* @HB_UNICODE_COMBINING_CLASS_ATTACHED_BELOW
* @HB_UNICODE_COMBINING_CLASS_ATTACHED_ABOVE
* @HB_UNICODE_COMBINING_CLASS_ATTACHED_ABOVE_RIGHT
* @HB_UNICODE_COMBINING_CLASS_BELOW_LEFT
* @HB_UNICODE_COMBINING_CLASS_BELOW
* @HB_UNICODE_COMBINING_CLASS_BELOW_RIGHT
* @HB_UNICODE_COMBINING_CLASS_LEFT
* @HB_UNICODE_COMBINING_CLASS_RIGHT
* @HB_UNICODE_COMBINING_CLASS_ABOVE_LEFT
* @HB_UNICODE_COMBINING_CLASS_ABOVE
* @HB_UNICODE_COMBINING_CLASS_ABOVE_RIGHT
* @HB_UNICODE_COMBINING_CLASS_DOUBLE_BELOW
* @HB_UNICODE_COMBINING_CLASS_DOUBLE_ABOVE
* @HB_UNICODE_COMBINING_CLASS_IOTA_SUBSCRIPT
* @HB_UNICODE_COMBINING_CLASS_INVALID: 255
*
* Data type for the Canonical_Combining_Class (ccc) property
* from the Unicode Character Database.
*
* <note>Note: newer versions of Unicode may add new values.
* Client programs should be ready to handle any value in the 0..254 range
* being returned from hb_unicode_combining_class().</note>
*
**/
typedef enum typedef enum
{ {
HB_UNICODE_COMBINING_CLASS_NOT_REORDERED = 0, HB_UNICODE_COMBINING_CLASS_NOT_REORDERED = 0,
@ -176,6 +270,18 @@ typedef enum
* hb_unicode_funcs_t * hb_unicode_funcs_t
*/ */
/**
* hb_unicode_funcs_t:
*
* Data type containing a set of virtual methods used for
* accessing various Unicode character properties.
*
* HarfBuzz provides a default function for each of the
* methods in #hb_unicode_funcs_t. Client programs can implement
* their own replacements for the individual Unicode functions, as
* needed, and replace the default by calling the setter for a
* method.
**/
typedef struct hb_unicode_funcs_t hb_unicode_funcs_t; typedef struct hb_unicode_funcs_t hb_unicode_funcs_t;
@ -227,40 +333,107 @@ hb_unicode_funcs_get_parent (hb_unicode_funcs_t *ufuncs);
/* typedefs */ /* typedefs */
/**
* hb_unicode_combining_class_func_t:
*
* A virtual method for the #hb_unicode_funcs_t structure.
*
* This method should retrieve the Canonical Combining Class (ccc)
* property for a specified Unicode code point.
*
**/
typedef hb_unicode_combining_class_t (*hb_unicode_combining_class_func_t) (hb_unicode_funcs_t *ufuncs, typedef hb_unicode_combining_class_t (*hb_unicode_combining_class_func_t) (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t unicode, hb_codepoint_t unicode,
void *user_data); void *user_data);
/**
* hb_unicode_general_category_func_t:
*
* A virtual method for the #hb_unicode_funcs_t structure.
*
* This method should retrieve the General Category property for
* a specified Unicode code point.
*
**/
typedef hb_unicode_general_category_t (*hb_unicode_general_category_func_t) (hb_unicode_funcs_t *ufuncs, typedef hb_unicode_general_category_t (*hb_unicode_general_category_func_t) (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t unicode, hb_codepoint_t unicode,
void *user_data); void *user_data);
/**
* hb_unicode_mirroring_func_t:
*
* A virtual method for the #hb_unicode_funcs_t structure.
*
* This method should retrieve the Bi-Directional Mirroring Glyph
* code point for a specified Unicode code point.
*
* <note>Note: If a code point does not have a specified
* Bi-Directional Mirroring Glyph defined, the method should
* return the original code point.</note>
*
**/
typedef hb_codepoint_t (*hb_unicode_mirroring_func_t) (hb_unicode_funcs_t *ufuncs, typedef hb_codepoint_t (*hb_unicode_mirroring_func_t) (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t unicode, hb_codepoint_t unicode,
void *user_data); void *user_data);
/**
* hb_unicode_script_func_t:
*
* A virtual method for the #hb_unicode_funcs_t structure.
*
* This method should retrieve the Script property for a
* specified Unicode code point.
*
**/
typedef hb_script_t (*hb_unicode_script_func_t) (hb_unicode_funcs_t *ufuncs, typedef hb_script_t (*hb_unicode_script_func_t) (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t unicode, hb_codepoint_t unicode,
void *user_data); void *user_data);
/**
* hb_unicode_compose_func_t:
*
* A virtual method for the #hb_unicode_funcs_t structure.
*
* This method should compose a sequence of two input Unicode code
* points by canonical equivalence, returning the composed code
* point in a #hb_codepoint_t output parameter (if successful).
* The method must return an #hb_bool_t indicating the success
* of the composition.
*
**/
typedef hb_bool_t (*hb_unicode_compose_func_t) (hb_unicode_funcs_t *ufuncs, typedef hb_bool_t (*hb_unicode_compose_func_t) (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t a, hb_codepoint_t a,
hb_codepoint_t b, hb_codepoint_t b,
hb_codepoint_t *ab, hb_codepoint_t *ab,
void *user_data); void *user_data);
/**
* hb_unicode_decompose_func_t:
*
* A virtual method for the #hb_unicode_funcs_t structure.
*
* This method should decompose an input Unicode code point,
* returning the two decomposed code points in #hb_codepoint_t
* output parameters (if successful). The method must return an
* #hb_bool_t indicating the success of the composition.
*
**/
typedef hb_bool_t (*hb_unicode_decompose_func_t) (hb_unicode_funcs_t *ufuncs, typedef hb_bool_t (*hb_unicode_decompose_func_t) (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t ab, hb_codepoint_t ab,
hb_codepoint_t *a, hb_codepoint_t *a,
hb_codepoint_t *b, hb_codepoint_t *b,
void *user_data); void *user_data);
/* setters */ /* func setters */
/** /**
* hb_unicode_funcs_set_combining_class_func: * hb_unicode_funcs_set_combining_class_func:
* @ufuncs: a Unicode function structure * @ufuncs: A Unicode-functions structure
* @func: (closure user_data) (destroy destroy) (scope notified): * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
* @user_data: * @user_data: Data to pass to @func
* @destroy: * @destroy: The function to call when @user_data is not needed anymore
*
* *
* Sets the implementation function for #hb_unicode_combining_class_func_t.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -271,12 +444,12 @@ hb_unicode_funcs_set_combining_class_func (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_funcs_set_general_category_func: * hb_unicode_funcs_set_general_category_func:
* @ufuncs: a Unicode function structure * @ufuncs: A Unicode-functions structure
* @func: (closure user_data) (destroy destroy) (scope notified): * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
* @user_data: * @user_data: Data to pass to @func
* @destroy: * @destroy: The function to call when @user_data is not needed anymore
*
* *
* Sets the implementation function for #hb_unicode_general_category_func_t.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -287,12 +460,12 @@ hb_unicode_funcs_set_general_category_func (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_funcs_set_mirroring_func: * hb_unicode_funcs_set_mirroring_func:
* @ufuncs: a Unicode function structure * @ufuncs: A Unicode-functions structure
* @func: (closure user_data) (destroy destroy) (scope notified): * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
* @user_data: * @user_data: Data to pass to @func
* @destroy: * @destroy: The function to call when @user_data is not needed anymore
*
* *
* Sets the implementation function for #hb_unicode_mirroring_func_t.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -303,12 +476,12 @@ hb_unicode_funcs_set_mirroring_func (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_funcs_set_script_func: * hb_unicode_funcs_set_script_func:
* @ufuncs: a Unicode function structure * @ufuncs: A Unicode-functions structure
* @func: (closure user_data) (destroy destroy) (scope notified): * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
* @user_data: * @user_data: Data to pass to @func
* @destroy: * @destroy: The function to call when @user_data is not needed anymore
*
* *
* Sets the implementation function for #hb_unicode_script_func_t.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -319,12 +492,12 @@ hb_unicode_funcs_set_script_func (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_funcs_set_compose_func: * hb_unicode_funcs_set_compose_func:
* @ufuncs: a Unicode function structure * @ufuncs: A Unicode-functions structure
* @func: (closure user_data) (destroy destroy) (scope notified): * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
* @user_data: * @user_data: Data to pass to @func
* @destroy: * @destroy: The function to call when @user_data is not needed anymore
*
* *
* Sets the implementation function for #hb_unicode_compose_func_t.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -335,12 +508,12 @@ hb_unicode_funcs_set_compose_func (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_funcs_set_decompose_func: * hb_unicode_funcs_set_decompose_func:
* @ufuncs: a Unicode function structure * @ufuncs: A Unicode-functions structure
* @func: (closure user_data) (destroy destroy) (scope notified): * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
* @user_data: * @user_data: Data to pass to @func
* @destroy: * @destroy: The function to call when @user_data is not needed anymore
*
* *
* Sets the implementation function for #hb_unicode_decompose_func_t.
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -353,6 +526,13 @@ hb_unicode_funcs_set_decompose_func (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_combining_class: * hb_unicode_combining_class:
* @ufuncs: The Unicode-functions structure
* @unicode: The code point to query
*
* Retrieves the Canonical Combining Class (ccc) property
* of code point @unicode.
*
* Return value: The #hb_unicode_combining_class_t of @unicode
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -362,6 +542,13 @@ hb_unicode_combining_class (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_general_category: * hb_unicode_general_category:
* @ufuncs: The Unicode-functions structure
* @unicode: The code point to query
*
* Retrieves the General Category (gc) property
* of code point @unicode.
*
* Return value: The #hb_unicode_general_category_t of @unicode
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -371,6 +558,13 @@ hb_unicode_general_category (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_mirroring: * hb_unicode_mirroring:
* @ufuncs: The Unicode-functions structure
* @unicode: The code point to query
*
* Retrieves the Bi-directional Mirroring Glyph code
* point defined for code point @unicode.
*
* Return value: The #hb_codepoint_t of the Mirroring Glyph for @unicode
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -380,6 +574,13 @@ hb_unicode_mirroring (hb_unicode_funcs_t *ufuncs,
/** /**
* hb_unicode_script: * hb_unicode_script:
* @ufuncs: The Unicode-functions structure
* @unicode: The code point to query
*
* Retrieves the #hb_script_t script to which code
* point @unicode belongs.
*
* Return value: The #hb_script_t of @unicode
* *
* Since: 0.9.2 * Since: 0.9.2
**/ **/
@ -387,12 +588,40 @@ HB_EXTERN hb_script_t
hb_unicode_script (hb_unicode_funcs_t *ufuncs, hb_unicode_script (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t unicode); hb_codepoint_t unicode);
/**
* hb_unicode_compose:
* @ufuncs: The Unicode-functions structure
* @a: The first code point to compose
* @b: The second code point to compose
* @ab: (out): The composed code point
*
* Composes the code point sequence @a,@b by canonical equivalence into
* code point @ab.
*
* Return value: True is @a,@b composed, false otherwise
*
* Since: 0.9.2
**/
HB_EXTERN hb_bool_t HB_EXTERN hb_bool_t
hb_unicode_compose (hb_unicode_funcs_t *ufuncs, hb_unicode_compose (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t a, hb_codepoint_t a,
hb_codepoint_t b, hb_codepoint_t b,
hb_codepoint_t *ab); hb_codepoint_t *ab);
/**
* hb_unicode_decompose:
* @ufuncs: The Unicode-functions structure
* @ab: The code point to decompose
* @a: (out): The first decomposed code point
* @b: (out): The second decomposed code point
*
* Decomposes code point @ab by canonical equivalence, into code points
* @a and @b.
*
* Return value: True if @ab decomposed, false otherwise
*
* Since: 0.9.2
**/
HB_EXTERN hb_bool_t HB_EXTERN hb_bool_t
hb_unicode_decompose (hb_unicode_funcs_t *ufuncs, hb_unicode_decompose (hb_unicode_funcs_t *ufuncs,
hb_codepoint_t ab, hb_codepoint_t ab,