asciipaint/ docs

API referenceasciipaint()

asciipaint()

Makes a paint on a canvas, which turns any image, video or canvas you draw into coloured glyphs on WebGL2.

Signature

asciipaint.d.ts
import { asciipaint, type Options, type Paint } from "asciipaint";

function asciipaint(canvas: HTMLCanvasElement, options?: Options): Paint;

Parameters

  • canvas: the canvas to paint on, sized with CSS. asciipaint takes an opaque WebGL2 context on it and measures it straight away; an off-DOM canvas can be sized with resize().
  • options: cell, ramp, font, background, edgeFade, sparkle and dpr. All are optional; see Options for each one and its default.

Returns

A Paint:

paint.d.ts
interface Paint {
  readonly canvas: HTMLCanvasElement;
  draw(source: TexImageSource): void;
  set(o: LiveOptions): void; // LiveOptions: background, edgeFade, sparkle
  resize(css?: { width: number; height: number }): void;
  dispose(): void;
}
  • canvas: the canvas you passed.
  • draw(source): paints one frame of an image, video, canvas, ImageBitmap or VideoFrame, cover-fitted to the canvas. A source that isn’t ready yet is skipped: an image still loading, or a video with no current frame.
  • set(live): changes background, edgeFade and sparkle without a rebuild. The change shows on the next draw() or resize().
  • resize(css?): measures the canvas’s CSS size, or with css sizes it (CSS px, for example an off-DOM canvas), then repaints the last frame. autoRender() calls it for you.
  • dispose(): frees the paint’s GPU programs, shaders, textures and framebuffer.
main.ts
const paint = asciipaint(canvas, { cell: [2.4, 3.4], ramp: "-=+*#%@" });
paint.draw(source); // image | video | canvas | ImageBitmap | VideoFrame
paint.set({ background: "#F4EEDF", sparkle: true, edgeFade: 0.076 }); // live, no rebuild
paint.resize(); // or let autoRender do it
paint.dispose();

Errors

asciipaint() throws:

  • Error: asciipaint needs WebGL2 when the canvas can’t give it a WebGL2 context.
  • Error: asciipaint: the WebGL2 context is lost when the canvas’s context is already lost.
  • RangeError for an option out of range: a cell size that isn’t finite and above 0, a ramp of fewer than 2 glyphs, an edgeFade outside 0–0.5, a dpr that isn’t finite and above 0, or a background that isn’t a valid colour or is fully transparent (or an [r, g, b] outside 0–1). A partly transparent colour is accepted and its alpha ignored.

set() throws the same RangeErrors for background and edgeFade. The first draw() links the shaders and throws asciipaint: shader link failed with the GPU’s log if they don’t link.