@thi.ng/wasm-api-canvas

[!NOTE] This is one of 192 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

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Installation

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

ESM import:

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

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/wasm-api-canvas"></script>

JSDelivr documentation

For Node.js REPL:

const wac = await import("@thi.ng/wasm-api-canvas");

Package sizes (brotli'd, pre-treeshake): ESM: 2.65 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

Zig bindings

• api.zig
• lib.zig

Minimal example

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);

HDPI support

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.

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:

@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 - 2024 Karsten Schmidt // Apache License 2.0