[font] Load named-instance if face index has top bits set

[behdad]

In fontconfig and freetype I added a special wiring to make named-instances work in older applications transparently. The way it works is this: The high word of face_index is used to pass-through the named-instance index (plus-one). For example, if face-index is 0x00030000 then we load the third named-instance.

HarfBuzz can do the same. In #3347 I already made hb_face_create() only use the lower 16 bit of face_index. When a hb_font_t is created from a hb_face_t, we can look at the face_index of the face and use the higher 16 bits to choose which named-instance to load by default. This will match FreeType behavior.

[matthiasclasen]

I am always a bit puzzled by the status of named instances, and I don't think this would make it much clearer.

Does a hb_face_t just contain predefined coordinates for a bunch of named instances that I have to pull out manually and apply to my font if I want that instance, or is the hb_face_t one particular named instance (the one that corresponds to the high bits of the index). And in that case, what is the status of a font that I create from that face ? Can I still set other coordinates on it even though that messes up the correspondence beween the index of the face and the effective coordinates of the font?

[behdad]

Does a hb_face_t just contain predefined coordinates for a bunch of named instances that I have to pull out manually and apply to my font if I want that instance, or is the hb_face_t one particular named instance (the one that corresponds to the high bits of the index). And in that case, what is the status of a font that I create from that face ? Can I still set other coordinates on it even though that messes up the correspondence beween the index of the face and the effective coordinates of the font?

Short answer is /both/. A face contains an entire variation space, which includes a set of named instances. However, when you create a hb_font_t from it, by default, it corresponds to a particular point in the variation space. Currently that always corresponds to the "default-instance" of the variation space. After this proposed change, you can use the high-bits of the index to choose a named-instance. You can still change the font to point somewhere else.

[behdad]

cc @drott

[matthiasclasen]

Should there be a separate api to get/set the named instance that is 'current' on a hb_face_t? That would save callers from having to fiddle with bits to create a combined index+instance_id to pass to hb_face_set_index().

It would be great if the docs for hb_font_create() talked about this.

[behdad]

Should there be a separate api to get/set the named instance that is 'current' on a hb_face_t? That would save callers from having to fiddle with bits to create a combined index+instance_id to pass to hb_face_set_index().

I suppose we can do that.

It would be great if the docs for hb_font_create() talked about this.

I added a few words there. Check the commit. Improvements welcome.