Skip to main content

Class: P5Asciifier

Defined in: Asciifier.ts:19

Manages a rendering pipeline for ASCII conversion, including font management, grid calculations, and ASCII renderers, which is applied to the main p5.js canvas or a selected texture.

Instances of this class are created and managed through the p5asciify object (see P5AsciifierManager).

Accessors

fontManager

Get Signature

get fontManager(): P5AsciifyFontManager

Defined in: Asciifier.ts:865

Returns the font manager, which manages the font and provides methods to access font properties like available characters and their corresponding rgb values, and the texture containing all the characters in the font.

Example
function setupAsciify() {
// Print all existing characters in the font to the console.
console.log(p5asciify.asciifier().fontManager.characters);
}
Returns

P5AsciifyFontManager


grid

Get Signature

get grid(): P5AsciifyGrid

Defined in: Asciifier.ts:851

Returns the P5AsciifyGrid instance, which contains information about grid properties.

Example
let framebuffer;

function setupAsciify() {
// Can be useful to create a framebuffer with the same dimensions as the grid.
framebuffer = createFramebuffer({
width: p5asciify.asciifier().grid.cols,
height: p5asciify.asciifier().grid.rows,
});
}
Returns

P5AsciifyGrid


texture

Get Signature

get texture(): Framebuffer

Defined in: Asciifier.ts:901

Returns the ASCII output texture as a p5.Framebuffer, which can be used for further processing or rendering. Can also be used via the p5.js texture() function.

Example
// Draw something on the canvas to asciify.
function draw() {
background(0);
fill(255);
box(100);
}

// Apply the asciified output as a texture to a 3D box.
function drawAsciify() {
orbitControl();

clear();
texture(p5asciify.asciifier().texture);
rotateX(frameCount * 0.01);
rotateY(frameCount * 0.01);
box(100);
}
Returns

Framebuffer

Methods

background()

background(color): void

Defined in: Asciifier.ts:282

Sets the background color for the resulting texture of the ASCII output, and the SVG export.

To make the background transparent, pass an appropriate color value with an alpha value of 0.

Parameters

ParameterTypeDescription
coloranyThe color to set. Needs to be a valid type to pass to the background() function provided by p5.js.

Returns

void

Throws

If the color is not a string, array or p5.Color.

Example

function setupAsciify() {
// Set the background color to black.
p5asciify.asciifier().background("#000000");
}

backgroundMode()

backgroundMode(mode): void

Defined in: Asciifier.ts:590

Sets the background mode for the ASCII output.

If the mode is set to fixed, the background color set via background will be used for transparent cells.

If the mode is set to sampled, the background color will be sampled from the pixel data of the texture that is being captured.

Parameters

ParameterTypeDefault valueDescription
mode"fixed" | "sampled""fixed"The background mode to set. Can be either "fixed" or "sampled".

Returns

void


fill()

fill(character): void

Defined in: Asciifier.ts:831

Sets the p5.js fill() color to the color of the given character in the font texture atlas.

This method can be useful when drawing to a custom renderers characterFramebuffer, which is used to convert the pixel data to ASCII characters.

Parameters

ParameterTypeDescription
characterstringThe character to get the color for.

Returns

void

Example

let characterFramebuffer;
let primaryColorFramebuffer;
let secondaryColorFramebuffer;

let asciifier;

function setup() {
createCanvas(400, 400, WEBGL);
}

function setupAsciify() {
asciifier = p5asciify.asciifier();

// Enable the default custom renderer
asciifier.renderers().get("custom").enable();

// Assign the ascii renderer's character framebuffer to a global variable
characterFramebuffer = asciifier
.renderers()
.get("custom").characterFramebuffer;
primaryColorFramebuffer = asciifier
.renderers()
.get("custom").primaryColorFramebuffer;
secondaryColorFramebuffer = asciifier
.renderers()
.get("custom").secondaryColorFramebuffer;
}

function draw() {
// Draw a rectangle with the character 'A' to the character framebuffer
characterFramebuffer.begin();
clear();
asciifier.fill("A");
rect(0, 0, 10, 10);
characterFramebuffer.end();

// Makes all ascii characters on the grid white.
primaryColorFramebuffer.begin();
background(255);
primaryColorFramebuffer.end();

// Makes all cell background colors black.
secondaryColorFramebuffer.begin();
background(0);
secondaryColorFramebuffer.end();
}

font()

font(font, options): void

Defined in: Asciifier.ts:232

Sets the font for the ascii renderers in the rendering pipeline of the asciifier.

Parameters

ParameterTypeDescription
fontFontThe p5.Font object to use for ASCII rendering.
options{ updateCharacters: boolean; }An object containing options affecting what happens after the font is loaded.
options.updateCharactersbooleanIf true (default), updates set character sets in pre-defined renderers like the brightness-based ASCII renderer. This might cause an error if the new font does not contain the character sets used with the previous font. If false, those character sets are not updated, potentially leading to missing/different characters in the ASCII output if the mapping is not the same.

Returns

void

Throws

If the font parameter is invalid.

Example

let font;

function preload() {
// Load font during preload using p5.js `loadFont` function.
font = loadFont("path/to/font.ttf");
}

function setupAsciify() {
// Set the font to the default asciifier instance.
p5asciify.asciifier().font(font);
}

fontSize()

fontSize(fontSize): void

Defined in: Asciifier.ts:140

Sets the font size for the ASCII renderers of the asciifier.

Parameters

ParameterTypeDescription
fontSizenumberThe font size to set.

Returns

void

Throws

If the font size is not a positive number.

Example

function setupAsciify() {
// Set the font size to 32 to use for all ASCII renderers of the asciifier.
p5asciify.asciifier().fontSize(32);
}

gridDimensions()

gridDimensions(gridCols, gridRows): void

Defined in: Asciifier.ts:313

Sets the grid dimensions for the ASCII renderers. Calling this method will make the grid dimensions fixed, no longer adjusting automatically when the canvas size changes.

To make the grid dimensions responsive to the canvas size again, use the gridResponsive method.

Parameters

ParameterTypeDescription
gridColsnumberThe number of columns in the grid.
gridRowsnumberThe number of rows in the grid.

Returns

void

Example

function setupAsciify() {
// Set the grid dimensions to 100 columns, 50 rows.
p5asciify.asciifier().gridDimensions(100, 50);
}

gridResponsive()

gridResponsive(bool): void

Defined in: Asciifier.ts:333

Adjust the grid dimensions to be responsive to the canvas size or fixed.

If true, the grid dimensions will be adjusted every time the canvas size changes to create a perfect grid on the x and y axes.

If false, the grid dimensions will be fixed and not change when the canvas size changes.

Parameters

ParameterTypeDefault valueDescription
boolbooleantrueDetermines if the grid dimensions should be responsive to the canvas size.

Returns

void


loadJSON()

loadJSON(json): object

Defined in: Asciifier.ts:616

Loads a JSON string or object and returns the framebuffers for the character, primary color, secondary color, transform, and rotation.

This method is useful for loading JSON exports from the saveJSON method in custom renderers. The framebuffers match the dimensions of the grid defined in the JSON. Each framebuffer contains the pixel data for the respective properties, which can be drawn to the respective custom renderers framebuffers via the image() function.

Parameters

ParameterTypeDescription
jsonstring | objectThe JSON string or object to load.

Returns

object

An object containing the framebuffers for character, primary color, secondary color, transform, and rotation.

NameTypeDefined in
characterFramebufferanyAsciifier.ts:617
primaryColorFramebufferanyAsciifier.ts:618
rotationFramebufferanyAsciifier.ts:621
secondaryColorFramebufferanyAsciifier.ts:619
transformFramebufferanyAsciifier.ts:620

Throws

If the JSON format is invalid or unsupported.


renderers()

renderers(): P5AsciifyRendererManager

Defined in: Asciifier.ts:181

Returns the P5AsciifyRendererManager, containing all ASCII renderers in the rendering pipeline of the asciifier.

Returns

P5AsciifyRendererManager

The renderer manager.

Example

let defaultBrightnessRenderer;

function setupAsciify() {
// Fetch the default brightness renderer from the renderer manager.
defaultBrightnessRenderer = p5asciify
.asciifier()
.renderers()
.get("brightness");

// Update any options for the renderer.
defaultBrightnessRenderer.update({ invertMode: true });
}

renderToCanvas()

renderToCanvas(bool): void

Defined in: Asciifier.ts:566

Sets whether the ASCII output should be rendered to the canvas or not.

If this is set to false, the canvas will remain clear/empty until you start drawing stuff again in drawAsciify() after the draw()function finishes. This is because p5.asciify wraps your draw() loop inside a framebuffer's begin() and end().

By default, this is set to true, meaning the ASCII output will be rendered to the canvas after the draw() function ends, but before the drawAsciify() function is called.

Parameters

ParameterTypeDescription
boolbooleantrue to render to the canvas, false to not render.

Returns

void


saveJSON()

saveJSON(options): void

Defined in: Asciifier.ts:417

Saves the current ASCII output as a JSON file.

Parameters

ParameterTypeDescription
optionsJSONExportOptionsThe options for saving the JSON file.

Returns

void

Throws

If no renderer is available to fetch ASCII output from.


saveStrings()

saveStrings(filename): void

Defined in: Asciifier.ts:544

Saves the ASCII output to a text file.

Parameters

ParameterTypeDescription
filenamestringThe filename to save the text file as. If not provided, a default filename is used.

Returns

void

Throws

If no renderer is available to fetch ASCII output from.

Example

function drawAsciify() {
// Save the ASCII output to a text file.
if (frameCount === 11100110110111101101100) {
p5asciify.asciifier().saveStrings("ascii_output");
}
}

saveSVG()

saveSVG(options): void

Defined in: Asciifier.ts:364

Saves the current ASCII output as an SVG file.

Parameters

ParameterTypeDescription
optionsSVGExportOptionsThe options for saving the SVG file.

Returns

void

Throws

If no renderer is available to fetch ASCII output from.

Example

function drawAsciify() {
// Save the ASCII output as an SVG file with default options
if (frameCount === 60) {
p5asciify.asciifier().saveSVG("asciify_output");
}

// Save without cell background rectangles
if (frameCount === 120) {
p5asciify.asciifier().saveSVG({
filename: "asciify_clean",
includeBackgrounds: false,
});
}
}

setCaptureTexture()

setCaptureTexture(captureFramebuffer): void

Defined in: Asciifier.ts:195

Sets the framebuffer or graphics object to capture for ASCII conversion.

Updates the capture source that will be processed by the ASCII rendering pipeline. This allows switching between different rendering targets without recreating the asciifier.

Parameters

ParameterTypeDescription
captureFramebufferanyThe framebuffer or graphics object to capture from. Can be a p5.Framebuffer or p5.Graphics.

Returns

void


toJSON()

toJSON(options): string

Defined in: Asciifier.ts:453

Returns the current ASCII output as a JSON string.

Parameters

ParameterTypeDescription
optionsOmit<JSONExportOptions, "filename">Options for JSON generation (same as saveJSON options except filename)

Returns

string

JSON string representation of the ASCII output

Throws

If no renderer is available to fetch ASCII output from.

Example

function drawAsciify() {
// Get the ASCII output as a JSON string
if (frameCount === 60) {
const jsonString = p5asciify.asciifier().toJSON();
console.log(jsonString);
}

// Get JSON without empty cells and without pretty printing
if (frameCount === 120) {
const compactJson = p5asciify.asciifier().toJSON({
includeEmptyCells: false,
prettyPrint: false,
});
console.log(compactJson);
}
}

toString()

toString(): string

Defined in: Asciifier.ts:525

Returns the current ASCII output as a string.

Returns

string

Multi-line string representation of the ASCII output.

Throws

If no renderer is available to fetch ASCII output from.

Example

function drawAsciify() {
// Print the ASCII output to the console.
if (frameCount === 1101100011101010110111001100001) {
console.log(p5asciify.asciifier().toString());
}
}

toSVG()

toSVG(options): string

Defined in: Asciifier.ts:401

Returns the current ASCII output as an SVG string.

Parameters

ParameterTypeDescription
optionsOmit<SVGExportOptions, "filename">Options for SVG generation (same as saveSVG options except filename)

Returns

string

SVG string representation of the ASCII output

Throws

If no renderer is available to fetch ASCII output from.

Example

function drawAsciify() {
// Get the ASCII output as an SVG string
if (frameCount === 60) {
const svgString = p5asciify.asciifier().toSVG();
console.log(svgString);
}

// Get SVG without background rectangles and in text mode
if (frameCount === 120) {
const svgString = p5asciify.asciifier().toSVG({
includeBackgroundRectangles: false,
drawMode: "text",
});
console.log(svgString);
}
}