!@thi.ng/wasm-api-canvas

!npm downloads

> [!NOTE]
> This is one of 214 standalone projects, maintained as part
> of the @thi.ng/umbrella monorepo
> and anti-framework.
>
> 🚀 Please help me to work full-time on these projects by sponsoring me on
> GitHub. Thank you! ❤️

- About
- Status
- Installation
- Dependencies
- Usage examples
- API
- Zig bindings
- Minimal example
- HDPI support
- Authors
- License

About

HTML Canvas2D bridge API for hybrid TypeScript & WASM (Zig) applications. This is a support package for @thi.ng/wasm-api.

This package already covers ~80-90% of the HTML Canvas2D features and provides
some additional drawing utilities to minimize boilerplate & WASM/JS cross-calling.

Status

STABLE - used in production

Search or submit any issues for this package

Installation

``bash
yarn add @thi.ng/wasm-api-canvas
`

ESM import:

`ts
import * as wac from "@thi.ng/wasm-api-canvas";
`

Browser ESM import:

`html

`

JSDelivr documentation

Package sizes (brotli'd, pre-treeshake): ESM: 2.62 KB

Dependencies

- @thi.ng/binary
- @thi.ng/wasm-api
- @thi.ng/wasm-api-dom

Usage examples

One project in this repo's
/examples
directory is using this package:

| Screenshot | Description | Live demo | Source |
|:--------------------------------------------------------------------------------------------------------------------|:----------------------------------------------|:---------------------------------------------------|:--------------------------------------------------------------------------------|
| | Zig-based 2D multi-behavior cellular automata | Demo | Source |

API

Generated API docs

$3

- api.zig
- lib.zig

$3

!example output

`zig
const canvas2d = @import("wasm-api-canvas");
const dom = @import("wasm-api-dom");

// ...

// create canvas element and attached to document.body
const canvas = dom.createCanvas(&.{
.width = 320,
.height = 320,
.parent = dom.body,
// can be customized for HDPI screens (aka window.devicePixelRatio)
// see readme section below
.dpr = 1,
.index = 0,
});

// start using this canvas
canvas2d.beginCtx(canvas);

// set fill color (any CSS color)
canvas2d.setFill("#f0f");

// draw a triangle
canvas2d.beginPath();
canvas2d.moveTo(250, 50);
canvas2d.lineTo(150, 250);
canvas2d.lineTo(50, 100);
canvas2d.fill();

// (could also be shortened via this helper:)
// canvas2d.polyline(&.{ .{ 250, 50 }, .{ 150, 250 }, .{ 50, 100 } }, true);

// pre-define gradient
const gradient = canvas2d.createLinearGradient(0, 0, 0, 100, &.{
.{ .pos = 0.0, .color = "#ff0" },
.{ .pos = 1.0, .color = "#0ff" },
});
// use gradient as fill color
canvas2d.setGradientFill(gradient);

// configure & draw text
canvas2d.setFont("100px Menlo");
canvas2d.setTextBaseline(.top);
canvas2d.fillText("HELLO", 10, 10, 0);

// create a bitmap pattern (ABGR pixel format)
const pixels = [4]u32{ 0xff000000, 0, 0, 0xff000000 };
const pattern = canvas2d.createPattern(&pixels, 2, 2, .repeat);
// use pattern as fill color
canvas2d.setPatternFill(pattern);
canvas2d.fillText("WORLD", 10, 120, 0);
`

$3

By default, canvas elements are created with a dpr (aka
window.devicePixelRatio) of 1. Use dom.getWindowInfo() prior to creating the
canvas to obtain the actual device pixel ratio and adapt the canvas to it.

`zig
const canvas2d = @import("wasm-api-canvas");
const dom = @import("wasm-api-dom");

var window: dom.WindowInfo = undefined;
dom.getWindowInfo(&window);

// create full-window canvas element with correct DPR
const canvas = dom.createCanvas(&.{
.width = window.innerWidth,
.height = window.innerHeight,
.dpr = window.dpr,
.parent = dom.body,
});
`

Authors

- Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

`bibtex
@misc{thing-wasm-api-canvas,
title = "@thi.ng/wasm-api-canvas",
author = "Karsten Schmidt",
note = "https://thi.ng/wasm-api-canvas",
year = 2022
}
``

License

© 2022 - 2026 Karsten Schmidt // Apache License 2.0