From b918cd8c76a6333e43b9be23178afc9e74e17024 Mon Sep 17 00:00:00 2001 From: Ben Wagner Date: Thu, 10 Oct 2019 15:30:48 -0400 Subject: [PATCH] Document hb_feature_t. This documents hb_feature_t. This is motivated mostly by the ambiguity of the units for 'start' and 'end' (clusters) and whether they are inclusive or exclusive. This also documents that for lookup type 3 the value is the one based index into the alternates and that in a list of features later feature values override previous feature values with the same tag. --- src/hb-common.h | 15 +++++++++++++++ src/hb-shape.cc | 4 +++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/src/hb-common.h b/src/hb-common.h index 9f1764bdc..9cfaab11b 100644 --- a/src/hb-common.h +++ b/src/hb-common.h @@ -425,6 +425,21 @@ typedef void (*hb_destroy_func_t) (void *user_data); */ #define HB_FEATURE_GLOBAL_END ((unsigned int) -1) +/** + * hb_feature_t: + * @tag: a feature tag + * @value: 0 disables the feature, non-zero (usually 1) enables the feature. + * For features implemented as lookup type 3 (like 'salt') the @value is a one + * based index into the alternates. + * @start: the cluster to start applying this feature setting (inclusive). + * @end: the cluster to end applying this feature setting (exclusive). + * + * The hb_feature_t is the structure that holds information about requested + * feature application. The feature will be applied with the given value to all + * glyphs which are in clusters between @start (inclusive) and @end (exclusive). + * Setting start to @HB_FEATURE_GLOBAL_START and end to @HB_FEATURE_GLOBAL_END + * specifies that the feature always applies to the entire buffer. + */ typedef struct hb_feature_t { hb_tag_t tag; uint32_t value; diff --git a/src/hb-shape.cc b/src/hb-shape.cc index deff77bed..cf4e1525a 100644 --- a/src/hb-shape.cc +++ b/src/hb-shape.cc @@ -154,7 +154,9 @@ hb_shape_full (hb_font_t *font, * * Shapes @buffer using @font turning its Unicode characters content to * positioned glyphs. If @features is not %NULL, it will be used to control the - * features applied during shaping. + * features applied during shaping. If two @features have the same tag but + * overlapping ranges the value of the feature with the higher index takes + * precedence. * * Since: 0.9.2 **/