Public API for COLR/CPAL

[ebraminio]

Now that we have COLR/CPAL tables parsing, it would be nice if we expose some of it as a public API for clients so they won't need to write their own font parsing logic. All what is needed here is signature of public APIs we like to have (which of course is not that easy...). Some useful links:

• https://codereview.chromium.org/1984943002/
• https://bugzilla.mozilla.org/show_bug.cgi?id=889401
• https://bug889401.bmoattachments.org/attachment.cgi?id=8424617
• http://msdn.microsoft.com/en-us/goglobal/bb688099.aspx
• http://msdn.microsoft.com/en-us/library/windows/desktop/hh802480%28v=vs.85%29.aspx
• http://www.getcodesamples.com/src/712F9685/B41B1957
• https://gist.github.com/egtra/6045976
• https://github.com/wine-mirror/wine/blob/5ec6b8f807f61ee77b9a96d94798c8e3f3db7af4/dlls/dwrite/dwrite_private.h#L220-L238
• http://savannah.nongnu.org/bugs/?44689
• ShaoYuZhang/freetype@27d9e6f
• ShaoYuZhang/freetype@27d9e6f#diff-b4b664c297e0aefa0ecc9dd995dffdf2R30

Using our current CPAL/COLR structs helpers (private API) it can be implemented like this:

  const OT::COLR &colr = _get_colr(font->face);
  const OT::CPAL &cpal = _get_cpal(font->face);

  FT_Face ftface = hb_ft_font_get_face (font);
  for (unsigned int i = 0; i < buffer->len; ++i)
  {
    hb_codepoint_t code_point = buffer->info[i].codepoint;

    FT_Load_Glyph (ftface, code_point, FT_LOAD_DEFAULT);
    FT_GlyphSlot slot = ftface->glyph;
    FT_Render_Glyph (slot, FT_RENDER_MODE_NORMAL);

    int width = slot->bitmap.width;
    int height = slot->bitmap.rows;
    int left = slot->bitmap_left;
    int top = slot->bitmap_top;

    unsigned char* image = (unsigned char*) calloc (width * height * 16, sizeof(char));

    unsigned int first_layer_index, num_layers;
    if (colr.get_base_glyph_record (code_point, first_layer_index, num_layers))
    {
      for (unsigned int j = 0; j < num_layers; ++j)
      {
        hb_codepoint_t glyph_id;
        unsigned int color_index;
        colr.get_layer_record(first_layer_index + j, glyph_id, color_index);

        uint32_t color = cpal.get_color_record_argb(color_index, 0);

        FT_Load_Glyph(ftface, glyph_id, FT_LOAD_DEFAULT);
        FT_Render_Glyph(slot, FT_RENDER_MODE_NORMAL);

        drawBitmap(&slot->bitmap,
          slot->bitmap_left - left,
          top - slot->bitmap_top,
          image, width, height,
          color);
      }
    }
  }

(considering #859 is merged)

[behdad]

I think I like a hb_color_t type that is either a typedef to uint32_t and stored as ARGB; or a union type that has uint32_t as well as four uint8_t b, g, r, a channels.

[ebraminio]

There is something similar developed by @brawer on https://github.com/harfbuzz/harfbuzz/blob/master/src/hb-ot-color.h#L51-L54 (that struct and enum are the only things currently exposed publicly and better to be decided about before the release)
Also #859

[ebraminio]

Interestingly it seems macOS has added COLR/CPAL and Chrome on macOS is currently befitting from it (but with the switch to freetype for sbix rendering, that will be regressed I guess).

[ebraminio]

The fonts related to COLR/CPAL test on Mozilla, emoji-yellow.zip https://bug889401.bmoattachments.org/attachment.cgi?id=8428570

[ebraminio]

I liked to add tests for this @behdad but was thinking that you are going to add the public APIs (someday) and the tests better to be dependent to them. If the procedure is like first I submit a PR about public API then you review it till perfection then I guess I can afford some time on tests also (which I guessed isn't the case).

[khaledhosny]

How about something like this as a minimal API?

unsigned int
hb_ot_color_get_palette_count (hb_font_t font);

unsigned int
hb_ot_color_get_color_layers (hb_font_t font,
                              hb_codepoint_t   gid,
                              unsigned int     palette,
                              unsigned int     offset,
                              unsigned int    *count, /* IN/OUT */
                              hb_codepoint_t **gids,  /* OUT */
                              hb_ot_color_t  **colors /* OUT */ );

[ebraminio]

This looks great! However considering the need of resolving CPAL values separately and letting clients override them separately with --color0 per SVG spec and such I believe we can go for this,

void
hb_ot_color_get_color_layers (hb_font_t        font,
                              hb_codepoint_t   gid,
                              unsigned int     offset,
                              unsigned int    *count, /* IN/OUT */
                              hb_codepoint_t **gids,  /* OUT */
                              unsigned int   **color_indices /* OUT */ );

In addition to @brawer's hb_ot_color_get_palette_count and hb_ot_color_get_palette_colors

And clients should resolve color_indices to actual colors of hb_ot_color_get_palette_colors by their own and we can show that by adopting our example. And the CPAL thing can be reused for SVG support on the clients.

WDYT?

[khaledhosny]

I’m trying to side with simplicity of (what I think would be) the common use case. Clients needing to handle CPAL with SVG will need a separate API to access palette colors, but users of CPAL with COLR can do without the complexity (one API to call instead of two).

[ebraminio]

Makes sense. WDYT Behdad?

[khaledhosny]

Looks like I forget to account for layers that does not have a color set (using palette in index 0xFFFF), may be your version is better after all.