lorp/samsa-core

Library for processing TrueType font files. Includes variations, COLR, and SVG generation.

samsa-core

Library for processing TrueType font files.

Features:

• variations
• avar1 and avar2
• COLRv0 and COLRv1
• SVG generation
• shaping:
  • GSUB (includes basic ligatures and Emoji)
  • GPOS (includes class pair kerning with exceptions)
  • Feature Variations
  • script and language selection

This repo is for Version 2 development. Version 1 is managed in the Samsa GUI repo.

How to use

The essential steps are:

• load a font file into an ArrayBuffer
• create a SamsaBuffer object from the ArrayBuffer
• create a SamsaFont object from the SamsaBuffer
• create a SamsaInstance object from the SamsaFont
• call renderText() on the SamsaInstance to obtain SVG strings

Here is sample code for Node.js that loads filename from disk, creates a SamsaFont object, creates a SamsaInstance object with variation axes set to certain locations, renders the string hello, world! as SVG, then saves the SVG to the file render.svg.

const nodeBuffer = fs.readFileSync(filename);
const arrayBuffer = nodeBuffer.buffer;
const samsaBuffer = new SamsaBuffer(arrayBuffer);
const font = new SamsaFont(buffer);
const instance = font.instance({ wght: 900, wdth: 200 });
const svg = instance.renderText({ text: "hello, world!", fontSize: 72 });
fs.writeFileSync("render.svg", svg);

In a browser, you obtain an ArrayBuffer and process it similarly. The resulting SVG can be inserted into the DOM.

const buffer = new SamsaBuffer(arrayBuffer);
const font = new SamsaFont(buffer);
const instance = font.instance({ wght: 900, wdth: 200 });
const svg = instance.renderText({ text: "hello, world!", fontSize: 72 });
document.getElementById("myDiv").innerHTML = svg;

If loading a font file from a remote URL, you’ll probably use fetch() then response.arrayBuffer() to obtain the ArrayBuffer. If a font file is dragged onto the browser, the ArrayBuffer is obtained by enumerating the e.dataTransfer.items array, where e is the drop event. For each item in the array (there may be multiple items), if its kind property is equal to file, set file = item.getAsFile() and the promise file.arrayBuffer() will yield the ArrayBuffer.

Flow diagram

The diagram illustrates how Samsa creates a SamsaFont object from an ArrayBuffer, creates a SamsaInstance from the SamsaFont, then renders text as SVG.

flowchart TD
    F1[TTF] --> A[ArrayBuffer]
    F2[WOFF2] --> A[ArrayBuffer]
    A[ArrayBuffer] --> B[SamsaBuffer]
    B --> C[SamsaFont]
    B[SamsaBuffer] --> |"SamsaBuffer.decodeWOFF2()"| C[SamsaFont]
    C --> |"SamsaFont.instance(axisSettings)"| D(SamsaInstance)
    D --> |"SamsaInstance.renderText({text: myText, fontSize: mySize, color: myColor})"| E(SVG)

In use

• samsa-core v2 simple demo (CodePen)
• RenderStack (repo)
• figma-colrv1
• Samsa-GUI (repo, uses Version 1, upgrade planned)

Links

• GitHub repo
• npm package

samsa-core's Issues

Implement gradient extend modes

Should be fine, SVG seems compatible with COLRv1 here https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod

ItemVariationStore should allow just-in-time evaluation

Current behaviour is to evaluate all ItemVariationStores in the font when a SamsaInstance is created. This is almost certainly a bad idea, since only a tiny number of the values will get used in the session, and some fonts may struggle to generate instances quickly.

Therefore it makes sense to evaluate all the IVS scalars upon instantiation (since that’s cheap), and create an array of empty arrays to hold the interpolated delta values at column:row, or outer:inner. Thus initially an IVS would populate a scalars array for each IVD. Then when an outer:inner pair was requested, the relevant deltaSet is add-multiplied by the relevant scalar set, yielding a value that is stored and returned. Whether it’s worth storing the result should be tested.

SamsaFont constructor should accept other types of input data

Currently the SamsaFont constructor only accepts a SamsaBuffer containing a TTF. It makes sense to allow it to accept:

• ArrayBuffer containing a TTF
• ArrayBuffer containing a WOFF2-compressed TTF
• SamsaBuffer containing a TTF
• SamsaBuffer containing a WOFF2-compressed TTF

Implement sweep (conic) gradients

Sweep gradients are not representable directly in SVG. However sweep gradients are available (called conic gradients) in HTML canvas. So if/when canvas output is added to Samsa, it can be implemented. CanvasRenderingContext2D: createConicGradient() method

Sweep gradients are also available in Skia. Because of that, they are available in CanvasKit - Skia + WebAssembly. This was used by @underware to polyfill COLRv1 in Safari for the Plakato Moiré demo.

Sweep ("conic") gradients are also available in CSS:

background-image: conic-gradient(red, orange, yellow, green, blue);

… and this CSS Tricks article talks about including regular DIVs in SVG as <foreignObject>:
My Struggle to Use and Animate a Conic Gradient in SVG

Implement radial gradients

Should be fine https://developer.mozilla.org/en-US/docs/Web/SVG/Element/radialGradient