@f1stnpm2/harum-officiis-itaque v1.0.0

Canvas HyperTxt 🚀📐✍

A zero dependency featherweight library to layout text on a canvas.

Quickstart ⚡

import { split } from "@f1stnpm2/harum-officiis-itaque";

function renderWrappedText(ctx: CanvasRenderingContext2D, value: string, width: number, x: number, y: number) {
    ctx.font = "12px sans-serif"; // ideally don't do this every time, it is really slow.
    ctx.textBaseline = "top"; // just makes positioning easier to predict, not essential
    const lines = split(ctx, value, "12px sans-serif", width);
    for (const line of lines) {
        ctx.fillText(line, x, y);
        y += 15;
    }
}

function renderWrappedTextCentered(ctx: CanvasRenderingContext2D, value: string, width: number, x: number, y: number) {
    // ideally don't do this every time, it is really slow.
    ctx.font = "12px sans-serif";
    ctx.textAlign = "center";
    ctx.textBaseline = "top";
    const lines = split(ctx, value, "12px sans-serif", width);
    for (const line of lines) {
        ctx.fillText(line, x + width / 2, y);
        y += 15;
    }
}

Who is this for?

This library is inspired by the excellent canvas-txt but focuses instead on being a part of the rendering pipeline instead of drawing the text for you. This offers greater flexibility for those who need it. Additionally @f1stnpm2/harum-officiis-itaque focuses on layout performance, allowing for much faster overall layout and rendering performance compared to the original library. Some sacrifices are made in the name of performance (justify). This library is internally integrated and used in glide-data-grid and now is available as a standalone.

Comparison vs canvas-txt

While @f1stnpm2/harum-officiis-itaque does not set out to be a drop-in replacement to canvas-txt, we can drag race them.

All tests were done with 5000 iterations. To ensure a fair comparison times include font rendering time.

Benchmark code can be found here. You can run benchmarks on your machine here

canvas-multiline-text is not included in this chart because it fails to pass a basic correctness test. It can't handle wrapping correctly if there are no words to break at, nor does it handle newlines. Due to this it ends up making fewer draw calls and a significant amount of rendering happens off-canvas reducing drawing overhead further due to the correctness errors.

That said @f1stnpm2/harum-officiis-itaque tends to be around 20-30% faster than canvas-multiline-text without hyper wrapping, and about 1.2x faster with.

How is this so much faster?

Canvas-txt is an excellent library but takes a very inefficient approach to finding wrap points. It is clearly not written with performance in mind, but rather with features and bundle size. Overall it is a fantastic library if raw speed is not important to your use case.

HyperWrapping

One of the major items introduced by @f1stnpm2/harum-officiis-itaque is the concept of hyper wrapping. When enabled the font engine will train a weighting model to provide estimates for string sizes. Once the model is sufficiently trained it will perform string wrapping without calling ctx.measureText once. This leads to massive performance gains at the cost of accuracy. In practice with most fonts and text bodies, once trained the hyper wrap guesses will be within 1% of the actual measured size. A buffer is added to ensure the text wraps slightly too early instead of clipping.

The end result is text that is correctly wrapped the vast majority of the time, with a very small number of errors where the text wraps too early by a single word. The performance gains in the measure pass are over 100x, with hyper wrapped text basically having zero cost vs unwrapped text of the same size.

What am I missing using @f1stnpm2/harum-officiis-itaque?

You miss some features.

Managed rendering

canvas-txt will render your string for you, figure out line heights, etc. With @f1stnpm2/harum-officiis-itaque this is on you. It's not hard to do but it is a bit of extra lifting. You could easily wrap the @f1stnpm2/harum-officiis-itaque split function to do the same thing canvas-txt does. Examples provided in the quickstart.

Justify

I didn't feel like implementing it, patches welcome. This will 100% be slower than non-justified text due to the large amounts of string manipulation and extra measurement required. If you need justification canvas-txt can do it.

Debug mode

Because @f1stnpm2/harum-officiis-itaque doesn't actually render the text, it also can't render debug boxes for you.

Automatic text alignment

Text alignment with @f1stnpm2/harum-officiis-itaque is not as simple as setting a flag, though it's close. Set the ctx.textAlign appropriately and change the x value you pass to fillText to correspond to the left, center, or right edge of the bounding box.

Why are these all missing?

@f1stnpm2/harum-officiis-itaque is intended to be used as part of larger libraries which need wrapping text. In these cases text-alignment or actual text rendering is handled by existing functions which may provide additional functionality. By not rendering the text for the consumer, more flexibility is granted, however it comes at the cost of simplicity.

Usage

This library consists of two methods.

export function split(
    ctx: CanvasRenderingContext2D,
    value: string,
    fontStyle: string,
    width: number,
    hyperWrappingAllowed: boolean
): readonly string[];

split takes the following parameters

export function clearCache(): void;

Clear all size caches the library has collected so far. Ideally do this when fonts have finished loading.

async function clearCacheOnLoad() {
    if (document?.fonts?.ready === undefined) return;
    await document.fonts.ready;
    clearCache();
}

void clearCacheOnLoad();