Celtra readme

We use this repo to store compiled WebAssembly version of Raqm library which is then used in UAB project since we do not want to add all C source files and entire LLVM and binaryen suites to uab repo and build the library during docker build. We need to do some modifications to the library or compilation process and thus cannot use the original version from harfbuzz/harfbuzzjs. Currently (November 2021) we just additionaly exposed one function which is removed from original to save a few bytes.

Building

• Build guide is below, additionally you need to install meson and ninja. First build harfbuzz, then fribidi, then raqm.

General notes, useful links

• Learn about pointers and memory allocation in C, since it's required to call web assembly functions. We expose the results as normal JS objects but gluie code is required to do that (see the example below).
• Read the introduction guide to text shaping: https://harfbuzz.github.io/what-is-harfbuzz.html
• Harfbuzz manual, function signatures: https://harfbuzz.github.io/reference-manual.html
• Harfbuzz source: https://github.com/harfbuzz/harfbuzz (sometimes you need this since the reference funciton signatures don't include all the memory you need to allocate or is simply a bit wrong)
• Raqm (tiny wrapper around fribidi and harfbuzz to handle bidirectional text) source: https://github.com/HOST-Oman/libraqm
• Note that this repo already also includes fribidi and raqm and build configs for wasm compilation

harfbuzzjs

Providing HarfBuzz shaping library for client/server side JavaScript projects.

See the demo here.

Building

1. Install emscripten
2. ./build.sh

Download

Download the pack from releases tab of the project, or just download the demo page (the demo source is in gh-pages branch).

Usage and testing

TDLR

hb = require("hbjs.js")
WebAssembly.instantiateStreaming(fetch("hb.wasm")).then(function (result) {
  fetch('myfont.ttf').then(function (data) {
    return data.arrayBuffer();
  }).then(function (fontdata) {
    var blob = hb.createBlob(fontdata); // Load the font data into something Harfbuzz can use
    var face = hb.createFace(blob, 0);  // Select the first font in the file (there's normally only one!)
    var font = hb.createFont(face);     // Create a Harfbuzz font object from the face
    var buffer = hb.createBuffer();     // Make a buffer to hold some text
    buffer.addText('abc');              // Fill it with some stuff
    buffer.guessSegmentProperties();    // Set script, language and direction
    hb.shape(font, buffer);             // Shape the text, determining glyph IDs and positions
    var output = shape.json();

    // Enumerate the glyphs
    var xCursor = 0;
    var yCursor = 0;
    for (glyph of output) {
        var glyphId = glyph.g;
        var xAdvance = glyph.ax;
        var xDisplacement = glyph.dx;
        var yDisplacement = glyph.dy;

        var svgPath = font.glyphToPath(glyphId);
        // You need to supply this bit
        drawAGlyph(svgPath, xCursor + xDisplacement, yDisplacement);

        xCursor += xAdvance;
    }

    // Release memory
    buffer.destroy();
    font.destroy();
    face.destroy();
    blob.destroy();
})

More examples:

Browser

1. npx pad.js
2. Open http://127.0.0.1/examples/hbjs.example.html or http://127.0.0.1/examples/nohbjs.html

Node.js

1. (cd examples && node hbjs.example.node.js)

We provide a tiny wrapper (hbjs.js) around the main functionality of harfbuzz, but it's also easy to use other parts. (See example/nohbjs.js as an example. However, you may need a custom build to expose additional functionality.)

npm

Can be added with npm i harfbuzzjs or yarn add harfbuzzjs, see the examples for how to use it.

Need more of the library?

harfbuzzjs uses a stripped-down version of Harfbuzz generated by compiling Harfbuzz with -DHB_TINY. This may mean that some functions you need are not available. Look at src/hb-config.hh in the Harfbuzz source directory to see what has been removed. For example, HB_TINY defines HB_LEAN which (amongst other things) defines HB_NO_OT_GLYPH_NAMES. If, for example, you really need to get at the glyph names:

1. First, undefine the macro in question, by adding e.g. #undef HB_NO_OT_GLYPH_NAMES to config-override.h.
2. Next, export any function that you need by adding a line to hbjs.symbols; in this case _hb_ot_get_glyph_name.
3. Now the function will be exported through the WASM object, but you need to add Javascript to bridge to it - in this case, handling the memory allocation of the char * parameter name and marshalling it to a JavaScript string with heapu8.subarray. The best way to do this is to look at hbjs.js for functions which use similar signatures.

If you have extended harfbuzzjs in ways that you think others will also benefit from, please raise a pull request. If there are parts of Harfbuzz that you need but the instructions above don't work, describe what you are trying to do in an issue.

Using the library in a bigger emscripten project?

See harfbuzz port inside emscripten and emscripten-ports/HarfBuzz, basically all you need is to use -s USE_HARFBUZZ=1 in your build.

binaryen

Optionally you can install binaryen and use wasm-opt like:

wasm-opt -Oz hb.wasm -o hb.wasm

binaryen also provides wasm-dis which can be used for,

wasm-dis hb.wasm | grep export
wasm-dis hb.wasm | grep import

with that you can check if the built wasm file only exports things you need and doesn't need to import anything, as usual with wasm files built here.