textmode.js

Appearance

textmode.js / Textmodifier

Class: Textmodifier ​

Manages textmode rendering on a canvas or video element.

Each Textmodifier instance can be applied to a specific HTML canvas or video element via textmode.create, or created as a standalone instance for independent rendering.

Accessors ​

font ​

Get Signature ​

ts
get font(): TextmodeFont;

Get the current font object used for rendering.

Returns ​

TextmodeFont

frameCount ​

Get Signature ​

ts
get frameCount(): number;

Get the current frame count.

Returns ​

number

grid ​

Get Signature ​

ts
get grid(): TextmodeGrid;

Get the current grid object used for rendering.

Returns ​

TextmodeGrid

height ​

Get Signature ​

ts
get height(): number;

Get the height of the canvas.

Returns ​

number

mode ​

Get Signature ​

ts
get mode(): "manual" | "auto";

Get the current rendering mode.

Returns ​

"manual" | "auto"

pipeline ​

Get Signature ​

ts
get pipeline(): TextmodeConversionPipeline;

Get the current textmode conversion pipeline.

Returns ​

TextmodeConversionPipeline

width ​

Get Signature ​

ts
get width(): number;

Get the width of the canvas.

Returns ​

number

Methods ​

background() ​

ts
background(
   r, 
   g, 
   b, 
   a): void;

Set the background color for the canvas.

Parameters ​

r ​

number

Red component (0-255)

g ​

number = r

Green component (0-255, optional)

b ​

number = r

Blue component (0-255, optional)

a ​

number = 255

Alpha component (0-255, optional)

Returns ​

void

Example ​

javascript
const t = await textmode.create({
  width: 800,
  height: 600,
})

t.draw(() => {
  // Set the background color to black
  t.background(0);

  const centerX = t.width / 2;
  const centerY = t.height / 2;
  const radius = Math.min(t.width, t .height) / 3;
  const speed = 0.02; // Adjust speed of rotation

  const angle = t.frameCount * speed;
  const x = centerX + Math.cos(angle) * radius - 100;
  const y = centerY + Math.sin(angle) * radius - 50;

  // Set the fill color to white
  t.fill(255);

  // Draw a rectangle with the fill color
  t.rect(x, y, 200, 150);
});

converter() ​

ts
converter(name): 
  | void
  | TextmodeConverter;

Get a specific converter by name.

Parameters ​

name ​

string

The name of the converter to retrieve.

Returns ​

| void | TextmodeConverter

The requested TextmodeConverter instance.

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas);

// Get the pre-defined brightness converter from the pipeline
const brightnessConverter = textmodifier.converter('brightness');

// Update properties of the brightness converter
brightnessConverter.invert(true);
brightnessConverter.characters(" .,;:*");

createShader() ​

ts
createShader(vertexSource, fragmentSource): Shader;

Create a shader program from vertex and fragment source code.

Parameters ​

vertexSource ​

string

The GLSL source code for the vertex shader.

fragmentSource ​

string

The GLSL source code for the fragment shader.

Returns ​

Shader

The created shader program for use in textmode.js.

draw() ​

ts
draw(callback): void;

Set a draw callback function that will be executed before each render. This method is primarily useful for standalone textmodifier instances.

Parameters ​

callback ​

() => void

The function to call before each render

Returns ​

void

Example ​

javascript
// Create a standalone textmodifier instance
const t = await textmode.create({
 width: 800,
 height: 600,
});

// Set up draw callback
t.draw(() => {
  // Set background color
  t.background(128);
  
  // Draw some content
  t.fill(255, 0, 0); // Set fill color to red
  t.rect(50, 50, 100, 100);
});

fill() ​

ts
fill(
   r, 
   g?, 
   b?, 
   a?): void;

Sets the fill color for subsequent rendering operations

Parameters ​

r ​

number

Red component (0-255)

g? ​

number

Green component (0-255, optional)

b? ​

number

Blue component (0-255, optional)

a? ​

number

Alpha component (0-255, optional)

Returns ​

void

Example ​

javascript
const t = await textmode.create({
  width: 800,
  height: 600,
})

t.draw(() => {
  // Set the background color to black
  t.background(0);

  const centerX = t.width / 2;
  const centerY = t.height / 2;
  const radius = Math.min(t.width, t .height) / 3;
  const speed = 0.02; // Adjust speed of rotation

  const angle = t.frameCount * speed;
  const x = centerX + Math.cos(angle) * radius - 100;
  const y = centerY + Math.sin(angle) * radius - 50;

  // Set the fill color to white
  t.fill(255);

  // Draw a rectangle with the fill color
  t.rect(x, y, 200, 150);
});

fontSize() ​

ts
fontSize(size): void;

Set the font size used for rendering.

Parameters ​

size ​

number

The font size to set.

Returns ​

void

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas);

// Set the font size to 24
textmodifier.fontSize(24);

frameRate() ​

ts
frameRate(fps?): number | void;

Set the maximum frame rate for auto rendering. If called without arguments, returns the current measured frame rate.

Parameters ​

fps? ​

number

The maximum frames per second for auto rendering.

Returns ​

number | void

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas);

// Set the maximum frame rate to 30 FPS
textmodifier.frameRate(30);

loadFont() ​

ts
loadFont(fontSource): Promise<void>;

Update the font used for rendering.

Parameters ​

fontSource ​

string

The URL of the font to load.

Returns ​

Promise<void>

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas);

// Load a custom font from a URL
await textmodifier.loadFont('https://example.com/fonts/myfont.ttf');

// Local font example
// await textmodifier.loadFont('./fonts/myfont.ttf');

rect() ​

ts
rect(
   x, 
   y, 
   width, 
   height): void;

Draw a rectangle with the current shader or fill color.

Parameters ​

x ​

number

X-coordinate of the rectangle

y ​

number

Y-coordinate of the rectangle

width ​

number = 1

Width of the rectangle

height ​

number = 1

Height of the rectangle

Returns ​

void

Example ​

javascript
const t = await textmode.create({
  width: 800,
  height: 600,
})

t.draw(() => {
  // Set the background color to black
  t.background(0);

  const centerX = t.width / 2;
  const centerY = t.height / 2;
  const radius = Math.min(t.width, t .height) / 3;
  const speed = 0.02; // Adjust speed of rotation

  const angle = t.frameCount * speed;
  const x = centerX + Math.cos(angle) * radius - 100;
  const y = centerY + Math.sin(angle) * radius - 50;

  // Set the fill color to white
  t.fill(255);

  // Draw a rectangle with the fill color
  t.rect(x, y, 200, 150);
});

render() ​

ts
render(): void;

Apply textmode rendering to the canvas.

Note: In 'auto' mode, this is called automatically. In 'manual' mode, you need to call this method when you want to update the textmode rendering.

Returns ​

void

Example ​

javascript
// p5.js example

let textmodifier;

// p5.js setup function
async function setup() {

  // Create a p5.js canvas
  const canvas = createCanvas(800, 600);

  // Create a Textmodifier instance
  textmodifier = await textmode.create(canvas.elt);

  // Update the rendering mode to 'manual'
  textmodifier.renderMode('manual');
}

// p5.js draw function
function draw() {

  // Draw something on the p5.js canvas
  background(220);
  fill(255, 0, 0);
  rect(50, 50, 100, 100);

  // Apply textmode rendering
  textmodifier.render();
}

renderMode() ​

ts
renderMode(mode?): void | "manual" | "auto";

Update the rendering mode.

If called without arguments, returns the current mode.

Parameters ​

mode? ​

The new rendering mode to set.

"manual" | "auto"

Returns ​

void | "manual" | "auto"

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas);

// Update the rendering mode to 'manual'
textmodifier.renderMode('manual');

// Now you need to call textmodifier.render() manually in your animation loop

resizeCanvas() ​

ts
resizeCanvas(width, height): void;

Resize the textmode.js canvas.

Parameters ​

width ​

number

The new width of the canvas.

height ​

number

The new height of the canvas.

Returns ​

void

saveCanvas() ​

ts
saveCanvas(
   filename, 
   format, 
options): Promise<void>;

Export the current textmode rendering to an image file.

Parameters ​

filename ​

string

The filename (without extension) to save the image as

format ​

The image format ('png', 'jpg', or 'webp')

"png" | "jpg" | "webp"

options ​

Omit<ImageExportOptions, "filename" | "format"> = {}

Additional options for image export

Returns ​

Promise<void>

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});

// Render a single frame
textmodifier.render();

// Export the current rendering to a PNG file
textmodifier.saveCanvas('my_textmode_rendering', 'png');

// Export with custom options
textmodifier.saveCanvas('my_textmode_rendering', 'jpg', {
  quality: 0.8,
  scale: 2.0,
  backgroundColor: 'white'
});

saveStrings() ​

ts
saveStrings(options): void;

Export the current textmode rendering to a TXT file.

Parameters ​

options ​

TXTExportOptions = {}

Options for TXT export

Returns ​

void

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});

// Render a single frame
textmodifier.render();

// Export the current rendering to a TXT file
textmodifier.saveStrings({
  filename: 'my_textmode_rendering',
  preserveTrailingSpaces: false
});

saveSVG() ​

ts
saveSVG(options): void;

Export the current textmode rendering to an SVG file.

Parameters ​

options ​

SVGExportOptions = {}

Options for SVG export

Returns ​

void

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});

// Render a single frame
textmodifier.render();

// Export the current rendering to an SVG file
textmodifier.saveSVG({
  filename: 'my_textmode_rendering',
});

setUniform() ​

ts
setUniform(name, value): void;

Set a uniform variable for the current shader.

Parameters ​

name ​

string

The name of the uniform variable to set.

value ​

any

The value to set for the uniform variable.

Returns ​

void

shader() ​

ts
shader(shader): void;

Set the current shader for rendering.

Parameters ​

shader ​

Shader

The shader program to use for rendering.

Returns ​

void

toString() ​

ts
toString(options): string;

Generate the current textmode rendering as a text string.

Parameters ​

options ​

Omit<TXTExportOptions, "filename"> = {}

Options for text generation (excluding filename)

Returns ​

string

Textmode grid content as a string.

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});

// Render a single frame
textmodifier.render();

// Get the current rendering as a text string
const textString = textmodifier.toString({
  preserveTrailingSpaces: false,
  lineEnding: 'lf'
});

// Print to console or use otherwise
console.log(textString);

////////

// Example with video element
const video = document.querySelector('video#myVideo');
const videoTextmodifier = await textmode.create(video);

// The textmode overlay will automatically update as the video plays
video.play();

// Get current frame as ASCII
const videoFrame = videoTextmodifier.toString();

toSVG() ​

ts
toSVG(options): string;

Generate the current textmode rendering as an SVG string.

Parameters ​

options ​

Omit<SVGExportOptions, "filename"> = {}

Options for SVG generation (excluding filename)

Returns ​

string

SVG content as a string.

Example ​

javascript
// Fetch a canvas element to apply textmode rendering to
const canvas = document.querySelector('canvas#myCanvas');

// Create a Textmodifier instance
const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});

// Render a single frame
textmodifier.render();

// Get the current rendering as an SVG string
const svgString = textmodifier.toSVG({
  includeBackgroundRectangles: true,
  drawMode: 'fill'
});

// Print to console or use otherwise
console.log(svgString);

windowResized() ​

ts
windowResized(callback): void;

Set a callback function that will be called when the window is resized.

Parameters ​

callback ​

() => void

The function to call when the window is resized.

Returns ​

void

Example ​

javascript
// Create a standalone textmodifier instance
const t = await textmode.create({
 width: window.innerWidth,
 height: window.innerHeight,
});

// Draw callback to update content
t.draw(() => {
  // Set background color
  t.background(128);

  // Draw some content
  t.fill(255, 0, 0); // Set fill color to red
  t.rect(50, 50, 100, 100);
});

// Set up window resize callback
t.windowResized(() => {
  // Resize the canvas to match window size
  t.resizeCanvas(window.innerWidth, window.innerHeight);
});