API referenceasciipaintThree()
asciipaintThree()
Makes a pass that paints a three.js scene as glyphs on the renderer's own canvas and context.
Signature
import { asciipaintThree, type ThreePaint } from "asciipaint/three";
function asciipaintThree(renderer: WebGLRenderer, options?: Omit<Options, "dpr">): ThreePaint;three (>=0.170) is an optional peer dependency, needed only for asciipaint/three.
Parameters
renderer: your three.jsWebGLRenderer. The pass paints on its canvas and its WebGL2 context, and makes no context of its own.options: every option butdpr. The pass followsrenderer.getPixelRatio()instead.
Returns
A ThreePaint:
interface ThreePaint {
readonly canvas: HTMLCanvasElement; // renderer.domElement
render(scene: Object3D, camera: Camera): void;
set(o: LiveOptions): void;
resize(): void;
compile(): Promise<void>;
dispose(): void;
}render(scene, camera): renderssceneinto a half-float target, two samples per cell each way, then paints it as glyphs on the renderer’s canvas. Use it in place ofrenderer.render(scene, camera). It draws nothing while the renderer has no size.set(live): changesbackground,edgeFadeandsparklewithout a rebuild.resize(): sizes the renderer to its canvas’s CSS size.autoRender()calls it when the canvas resizes.compile(): compiles the shaders up front without blocking; optional.dispose(): frees the target and the pass’s GPU programs. The renderer stays yours.
const pass = asciipaintThree(renderer, options);
pass.render(scene, camera); // replaces renderer.render(scene, camera)
await pass.compile(); // optional: compile the shaders up front, without blockingColour
It always tone-maps with ACES Filmic at renderer.toneMappingExposure and outputs sRGB, whatever renderer.toneMapping and outputColorSpace say. Set renderer.toneMapping = ACESFilmicToneMapping if you want the raw render to match. The scene’s alpha is ignored: every cell is covered. See three.js for a full scene.
Errors
RangeErrorfromasciipaintThree()for an option out of range, as withasciipaint(): a badcell, arampof fewer than 2 glyphs, anedgeFadeoutside 0–0.5, or abackgroundthat isn’t a valid colour or is fully transparent.RangeErrorfromset()for a badbackgroundoredgeFade.Error: asciipaint: shader link failedfromcompile()or the firstrender()if the shaders don’t link.