[HarfBuzz] On hb_shape_plan() and other API for 1.0

[Behdad Esfahbod]

Hi list,

As we get closer to a 1.0 release of harfbuzz-ng, I thought I put out there
API questions that are still open, hoping that we can come to a conclusion
before the HarfBuzz hackfest in May.  So here we go.

- Sanitize API: I'm not sure how critical this is.  Conceptually, the main use
of this API is to make fontconfig call hb_sanitize() (or whatever it ends up
being called) and cache the results, such that clients using that information
can tell HarfBuzz when a font file is /clean/ and hence can skip sanitize
process.  It's purely an optimization, and hence without numbers, I'm hesitant
to pursue it since I'm not sure about the API itself and how that plays with
logic changes between versions.


- hb_shape_plan():  Currently, every time you call hb_shape(), we compile the
list of lookups and sort through them.  This process is independent of the
text being shaped and hence can be cached.  The big issue on the table is that
this process *is* dependent on the font features being enabled and their
values, but not the exact cluster ranges for those features.

In the past, I was thinking about a hb_shape_plan() and
hb_shape_plan_execute() or hb_shape_planned() that would take the computed
plan, text, and features, and do the shaping faster.  However, my main issue
with that API is that it's extremely error-prone for people to use a plan with
different features than those used to build the plan.  So today I had this
idea of allow pre-planning only for when there are no user features.  Ie.
whereas we currently have:

void
hb_shape (hb_font_t           *font,
          hb_buffer_t         *buffer,
          const hb_feature_t  *features,
          unsigned int         num_features);

The proposed API will add:

hb_shape_plan_t *
hb_shape_plan (hb_font_t           *font,
               hb_segment_properties_t *props);

void
hb_shape_planned (hb_shape_plan *plan,
                  hb_buffer_t    *buffer);

hb_shape_plan_destroy (hb_shape_plan_t *plan);

This would expose the currently unexposed hb_segment_properties_t type which
is simply a tuple of script, language, and direction.

If going ahead with this, we need to figure out the hb_shape_full() parallel also.

Comments?  Any other API bits I'm missing?

Cheers,
behdad