[var] Deprecated axis enumeration API and add new version

New version has axis flags.

New API:
+hb_ot_var_axis_info_t
+hb_ot_var_find_axis_info()
+hb_ot_var_get_axis_infos()

Deprecated API:
-HB_OT_VAR_NO_AXIS_INDEX
-hb_ot_var_axis_t
-hb_ot_var_find_axis()
-hb_ot_var_get_axes()

docs/harfbuzz-sections.txt

@@ -161,6 +161,10 @@ hb_ot_layout_table_choose_script
 hb_ot_layout_table_find_script
 hb_ot_tag_from_language
 hb_ot_tags_from_script
+HB_OT_VAR_NO_AXIS_INDEX
+hb_ot_var_axis_t
+hb_ot_var_find_axis
+hb_ot_var_get_axes
 hb_set_invert
 hb_unicode_eastasian_width_func_t
 hb_unicode_eastasian_width
@@ -581,14 +585,12 @@ HB_OT_TAG_VAR_AXIS_OPTICAL_SIZE
 HB_OT_TAG_VAR_AXIS_SLANT
 HB_OT_TAG_VAR_AXIS_WEIGHT
 HB_OT_TAG_VAR_AXIS_WIDTH
-HB_OT_VAR_NO_AXIS_INDEX
-hb_ot_var_axis_t
 hb_ot_var_has_data
-hb_ot_var_find_axis
-hb_ot_var_get_axis_count
-hb_ot_var_get_axes
 hb_ot_var_axis_flags_t
-hb_ot_var_axis_get_flags
+hb_ot_var_axis_info_t
+hb_ot_var_find_axis_info
+hb_ot_var_get_axis_count
+hb_ot_var_get_axis_infos
 hb_ot_var_get_named_instance_count
 hb_ot_var_named_instance_get_subfamily_name_id
 hb_ot_var_named_instance_get_postscript_name_id

src/hb-deprecated.h

@@ -241,6 +241,43 @@ HB_EXTERN HB_DEPRECATED_FOR (hb_ot_tags_from_script_and_language) hb_tag_t
 hb_ot_tag_from_language (hb_language_t language);
 
 
+typedef unsigned int hb_ot_name_id_t; /* Since is in hb-ot.h */
+
+/**
+ * HB_OT_VAR_NO_AXIS_INDEX:
+ *
+ * Since: 1.4.2
+ * Deprecated: REPLACEME
+ */
+#define HB_OT_VAR_NO_AXIS_INDEX		0xFFFFFFFFu
+
+/**
+ * hb_ot_var_axis_t:
+ *
+ * Since: 1.4.2
+ * Deprecated: REPLACEME
+ */
+typedef struct hb_ot_var_axis_t
+{
+  hb_tag_t tag;
+  hb_ot_name_id_t name_id;
+  float min_value;
+  float default_value;
+  float max_value;
+} hb_ot_var_axis_t;
+
+HB_EXTERN HB_DEPRECATED_FOR (hb_ot_var_get_axis_infos) unsigned int
+hb_ot_var_get_axes (hb_face_t        *face,
+		    unsigned int      start_offset,
+		    unsigned int     *axes_count /* IN/OUT */,
+		    hb_ot_var_axis_t *axes_array /* OUT */);
+
+HB_EXTERN HB_DEPRECATED_FOR (hb_ot_var_find_axis_info) hb_bool_t
+hb_ot_var_find_axis (hb_face_t        *face,
+		     hb_tag_t          axis_tag,
+		     unsigned int     *axis_index,
+		     hb_ot_var_axis_t *axis_info);
+
 #endif
 
 HB_END_DECLS

src/hb-ot-var-fvar-table.hh

@@ -115,28 +115,40 @@ struct fvar
   inline unsigned int get_axis_count (void) const
   { return axisCount; }
 
-  inline bool get_axis (unsigned int index, hb_ot_var_axis_t *info) const
+  inline void get_axis_deprecated (unsigned int axis_index,
+				   hb_ot_var_axis_t *info) const
   {
-    if (info)
+    const AxisRecord &axis = get_axes ()[axis_index];
-    {
+    info->tag = axis.axisTag;
-      const AxisRecord &axis = get_axes ()[index];
+    info->name_id =  axis.axisNameID;
-      info->tag = axis.axisTag;
+    info->default_value = axis.defaultValue / 65536.;
-      info->name_id =  axis.axisNameID;
+    /* Ensure order, to simplify client math. */
-      info->default_value = axis.defaultValue / 65536.;
+    info->min_value = MIN<float> (info->default_value, axis.minValue / 65536.);
-      /* Ensure order, to simplify client math. */
+    info->max_value = MAX<float> (info->default_value, axis.maxValue / 65536.);
-      info->min_value = MIN<float> (info->default_value, axis.minValue / 65536.);
-      info->max_value = MAX<float> (info->default_value, axis.maxValue / 65536.);
-    }
-
-    return true;
   }
 
-  inline unsigned int get_axis_infos (unsigned int      start_offset,
+  inline void get_axis_info (unsigned int axis_index,
-				      unsigned int     *axes_count /* IN/OUT */,
+			     hb_ot_var_axis_info_t *info) const
-				      hb_ot_var_axis_t *axes_array /* OUT */) const
+  {
+    const AxisRecord &axis = get_axes ()[axis_index];
+    info->axis_index = axis_index;
+    info->tag = axis.axisTag;
+    info->name_id =  axis.axisNameID;
+    info->flags = (hb_ot_var_axis_flags_t) (unsigned int) axis.flags;
+    info->default_value = axis.defaultValue / 65536.;
+    /* Ensure order, to simplify client math. */
+    info->min_value = MIN<float> (info->default_value, axis.minValue / 65536.);
+    info->max_value = MAX<float> (info->default_value, axis.maxValue / 65536.);
+    info->reserved = 0;
+  }
+
+  inline unsigned int get_axes_deprecated (unsigned int      start_offset,
+					   unsigned int     *axes_count /* IN/OUT */,
+					   hb_ot_var_axis_t *axes_array /* OUT */) const
   {
     if (axes_count)
     {
+      /* TODO Rewrite as hb_array_t<>::sub-array() */
       unsigned int count = axisCount;
       start_offset = MIN (start_offset, count);
 
@@ -147,32 +159,70 @@ struct fvar
       *axes_count = count;
 
       for (unsigned int i = 0; i < count; i++)
-	get_axis (start_offset + i, axes_array + i);
+	get_axis_deprecated (start_offset + i, axes_array + i);
     }
     return axisCount;
   }
 
-  inline bool find_axis (hb_tag_t tag, unsigned int *index, hb_ot_var_axis_t *info) const
+  inline unsigned int get_axis_infos (unsigned int           start_offset,
+				      unsigned int          *axes_count /* IN/OUT */,
+				      hb_ot_var_axis_info_t *axes_array /* OUT */) const
+  {
+    if (axes_count)
+    {
+      /* TODO Rewrite as hb_array_t<>::sub-array() */
+      unsigned int count = axisCount;
+      start_offset = MIN (start_offset, count);
+
+      count -= start_offset;
+      axes_array += start_offset;
+
+      count = MIN (count, *axes_count);
+      *axes_count = count;
+
+      for (unsigned int i = 0; i < count; i++)
+	get_axis_info (start_offset + i, axes_array + i);
+    }
+    return axisCount;
+  }
+
+  inline bool find_axis_deprecated (hb_tag_t tag,
+				    unsigned int *axis_index,
+				    hb_ot_var_axis_t *info) const
   {
     const AxisRecord *axes = get_axes ();
     unsigned int count = get_axis_count ();
     for (unsigned int i = 0; i < count; i++)
       if (axes[i].axisTag == tag)
       {
-        if (index)
+        if (axis_index)
-	  *index = i;
+	  *axis_index = i;
-	return get_axis (i, info);
+	get_axis_deprecated (i, info);
+	return true;
+      }
+    if (axis_index)
+      *axis_index = HB_OT_VAR_NO_AXIS_INDEX;
+    return false;
+  }
+
+  inline bool find_axis_info (hb_tag_t tag,
+			      hb_ot_var_axis_info_t *info) const
+  {
+    const AxisRecord *axes = get_axes ();
+    unsigned int count = get_axis_count ();
+    for (unsigned int i = 0; i < count; i++)
+      if (axes[i].axisTag == tag)
+      {
+	get_axis_info (i, info);
+	return true;
       }
-    if (index)
-      *index = HB_OT_VAR_NO_AXIS_INDEX;
     return false;
   }
 
   inline int normalize_axis_value (unsigned int axis_index, float v) const
   {
-    hb_ot_var_axis_t axis;
+    hb_ot_var_axis_info_t axis;
-    if (!get_axis (axis_index, &axis))
+    get_axis_info (axis_index, &axis);
-      return 0;
 
     v = MAX (MIN (v, axis.max_value), axis.min_value); /* Clamp. */
 
@@ -188,25 +238,25 @@ struct fvar
   inline unsigned int get_instance_count (void) const
   { return instanceCount; }
 
-  inline hb_ot_name_id_t get_instance_subfamily_name_id (unsigned int index) const
+  inline hb_ot_name_id_t get_instance_subfamily_name_id (unsigned int instance_index) const
   {
-    const InstanceRecord &instance = get_instance (index);
+    const InstanceRecord &instance = get_instance (instance_index);
     return instance.subfamilyNameID;
   }
 
-  inline hb_ot_name_id_t get_instance_postscript_name_id (unsigned int index) const
+  inline hb_ot_name_id_t get_instance_postscript_name_id (unsigned int instance_index) const
   {
-    const InstanceRecord &instance = get_instance (index);
+    const InstanceRecord &instance = get_instance (instance_index);
     if (instanceSize >= axisCount * 4 + 6)
       return StructAfter<NameID> (instance.get_coordinates (axisCount));
     return HB_OT_NAME_ID_INVALID;
   }
 
-  inline unsigned int get_instance_coords (unsigned int  index,
+  inline unsigned int get_instance_coords (unsigned int  instance_index,
 					   unsigned int *coords_length, /* IN/OUT */
 					   float        *coords         /* OUT */) const
   {
-    if (unlikely (index >= instanceCount))
+    if (unlikely (instance_index >= instanceCount))
     {
       if (coords_length)
         *coords_length = 0;
@@ -215,7 +265,7 @@ struct fvar
 
     if (coords_length && *coords_length)
     {
-      const InstanceRecord &instance = get_instance (index);
+      const InstanceRecord &instance = get_instance (instance_index);
       hb_array_t<const Fixed> instanceCoords = instance.get_coordinates (axisCount)
 						       .sub_array (0, *coords_length);
       for (unsigned int i = 0; i < instanceCoords.len; i++)

src/hb-ot-var.cc

@@ -53,7 +53,6 @@
  * @face: #hb_face_t to test
  *
  * This function allows to verify the presence of OpenType variation data on the face.
- * Alternatively, use hb_ot_var_get_axis_count().
  *
  * Return value: true if face has a `fvar' table and false otherwise
  *
@@ -80,6 +79,7 @@ hb_ot_var_get_axis_count (hb_face_t *face)
  * hb_ot_var_get_axes:
  *
  * Since: 1.4.2
+ * Deprecated: REPLACEME
  **/
 unsigned int
 hb_ot_var_get_axes (hb_face_t        *face,
@@ -87,13 +87,14 @@ hb_ot_var_get_axes (hb_face_t        *face,
 		    unsigned int     *axes_count /* IN/OUT */,
 		    hb_ot_var_axis_t *axes_array /* OUT */)
 {
-  return face->table.fvar->get_axis_infos (start_offset, axes_count, axes_array);
+  return face->table.fvar->get_axes_deprecated (start_offset, axes_count, axes_array);
 }
 
 /**
  * hb_ot_var_find_axis:
  *
  * Since: 1.4.2
+ * Deprecated: REPLACEME
  **/
 hb_bool_t
 hb_ot_var_find_axis (hb_face_t        *face,
@@ -101,9 +102,37 @@ hb_ot_var_find_axis (hb_face_t        *face,
 		     unsigned int     *axis_index,
 		     hb_ot_var_axis_t *axis_info)
 {
-  return face->table.fvar->find_axis (axis_tag, axis_index, axis_info);
+  return face->table.fvar->find_axis_deprecated (axis_tag, axis_index, axis_info);
 }
 
+/**
+ * hb_ot_var_get_axis_infos:
+ *
+ * Since: REPLACEME
+ **/
+HB_EXTERN unsigned int
+hb_ot_var_get_axis_infos (hb_face_t             *face,
+			  unsigned int           start_offset,
+			  unsigned int          *axes_count /* IN/OUT */,
+			  hb_ot_var_axis_info_t *axes_array /* OUT */)
+{
+  return face->table.fvar->get_axis_infos (start_offset, axes_count, axes_array);
+}
+
+/**
+ * hb_ot_var_find_axis_info:
+ *
+ * Since: REPLACEME
+ **/
+HB_EXTERN hb_bool_t
+hb_ot_var_find_axis_info (hb_face_t             *face,
+			  hb_tag_t               axis_tag,
+			  hb_ot_var_axis_info_t *axis_info)
+{
+  return face->table.fvar->find_axis_info (axis_tag, axis_info);
+}
+
+
 /*
  * Named instances.
  */
@@ -156,10 +185,10 @@ hb_ot_var_normalize_variations (hb_face_t            *face,
   const OT::fvar &fvar = *face->table.fvar;
   for (unsigned int i = 0; i < variations_length; i++)
   {
-    unsigned int axis_index;
+    hb_ot_var_axis_info_t info;
-    if (hb_ot_var_find_axis (face, variations[i].tag, &axis_index, nullptr) &&
+    if (hb_ot_var_find_axis_info (face, variations[i].tag, &info) &&
-	axis_index < coords_length)
+	info.axis_index < coords_length)
-      coords[axis_index] = fvar.normalize_axis_value (axis_index, variations[i].value);
+      coords[info.axis_index] = fvar.normalize_axis_value (info.axis_index, variations[i].value);
   }
 
   face->table.avar->map_coords (coords, coords_length);

src/hb-ot-var.h

@@ -55,42 +55,10 @@ hb_ot_var_has_data (hb_face_t *face);
  * Variation axes.
  */
 
-/**
- * HB_OT_VAR_NO_AXIS_INDEX:
- *
- * Since: 1.4.2
- */
-#define HB_OT_VAR_NO_AXIS_INDEX		0xFFFFFFFFu
 
 HB_EXTERN unsigned int
 hb_ot_var_get_axis_count (hb_face_t *face);
 
-/**
- * hb_ot_var_axis_t:
- *
- * Since: 1.4.2
- */
-typedef struct hb_ot_var_axis_t
-{
-  hb_tag_t tag;
-  hb_ot_name_id_t name_id;
-  float min_value;
-  float default_value;
-  float max_value;
-} hb_ot_var_axis_t;
-
-HB_EXTERN unsigned int
-hb_ot_var_get_axes (hb_face_t        *face,
-		    unsigned int      start_offset,
-		    unsigned int     *axes_count /* IN/OUT */,
-		    hb_ot_var_axis_t *axes_array /* OUT */);
-
-HB_EXTERN hb_bool_t
-hb_ot_var_find_axis (hb_face_t        *face,
-		     hb_tag_t          axis_tag,
-		     unsigned int     *axis_index,
-		     hb_ot_var_axis_t *axis_info);
-
 /**
  * hb_ot_var_axis_flags_t:
  * @HB_OT_VAR_AXIS_FLAG_HIDDEN: The axis should not be exposed directly in user interfaces.
@@ -103,6 +71,35 @@ typedef enum { /*< flags >*/
   _HB_OT_VAR_AXIS_FLAG_MAX_VALUE= 0x7FFFFFFFu, /*< skip >*/
 } hb_ot_var_axis_flags_t;
 
+/**
+ * hb_ot_var_axis_info_t:
+ *
+ * Since: REPLACEME
+ */
+typedef struct hb_ot_var_axis_info_t
+{
+  unsigned int			axis_index;
+  hb_tag_t			tag;
+  hb_ot_name_id_t		name_id;
+  hb_ot_var_axis_flags_t	flags;
+  float				min_value;
+  float				default_value;
+  float				max_value;
+  /*< private >*/
+  unsigned int			reserved;
+} hb_ot_var_axis_info_t;
+
+HB_EXTERN unsigned int
+hb_ot_var_get_axis_infos (hb_face_t             *face,
+			  unsigned int           start_offset,
+			  unsigned int          *axes_count /* IN/OUT */,
+			  hb_ot_var_axis_info_t *axes_array /* OUT */);
+
+HB_EXTERN hb_bool_t
+hb_ot_var_find_axis_info (hb_face_t             *face,
+			  hb_tag_t               axis_tag,
+			  hb_ot_var_axis_info_t *axis_info);
+
 
 /*
  * Named instances.

test/api/test-ot-face.c

@@ -93,7 +93,7 @@ test_face (hb_face_t *face,
   hb_ot_name_get_utf32 (face, cp, NULL, NULL, NULL);
 
   hb_ot_var_get_axis_count (face);
-  hb_ot_var_get_axes (face, 0, NULL, NULL);
+  hb_ot_var_get_axis_infos (face, 0, NULL, NULL);
   hb_ot_var_normalize_variations (face, NULL, 0, NULL, 0);
   hb_ot_var_normalize_coords (face, 0, NULL, NULL);