API referenceasciipaint()
asciipaint()
Makes a paint on a canvas, which turns any image, video or canvas you draw into coloured glyphs on WebGL2.
Signature
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 withresize().options:cell,ramp,font,background,edgeFade,sparkleanddpr. All are optional; see Options for each one and its default.
Returns
A Paint:
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,ImageBitmaporVideoFrame, 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): changesbackground,edgeFadeandsparklewithout a rebuild. The change shows on the nextdraw()orresize().resize(css?): measures the canvas’s CSS size, or withcsssizes 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.
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 WebGL2when the canvas can’t give it a WebGL2 context.Error: asciipaint: the WebGL2 context is lostwhen the canvas’s context is already lost.RangeErrorfor an option out of range: acellsize that isn’t finite and above 0, arampof fewer than 2 glyphs, anedgeFadeoutside 0–0.5, adprthat isn’t finite and above 0, or abackgroundthat 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.