textmode.js 0.2.1-beta.4 → 0.2.1-beta.6

package/dist/types/rendering/webgl/Renderer.d.ts

@@ -2,7 +2,7 @@ import { GLFramebuffer } from "./Framebuffer";
 import type { FramebufferOptions } from '../webgl/Framebuffer';
 import { GLShader } from "./Shader";
 import { RenderState } from "./RenderState";
-import type { ShaderSource } from './types/ShaderTypes';
+import type { TextmodeImage } from "../../textmode/TextmodeImage";
 /**
  * Core WebGL renderer that manages the WebGL context and provides high-level rendering operations
  */
@@ -25,7 +25,7 @@ export declare class GLRenderer {
      * Set the current shader
      */
     $shader(shader: GLShader): void;
-    $createShader(vertexSource: ShaderSource, fragmentSource: ShaderSource): GLShader;
+    $createShader(vertexSource: string, fragmentSource: string): GLShader;
     /**
      * Get the shared MRT copy shader
      */
@@ -38,6 +38,8 @@ export declare class GLRenderer {
      * Get the ASCII conversion shader
      */
     $getConversionShader(): GLShader;
+    /** Internal: image to MRT shader */
+    private $getImageToMRTShader;
     /**
      * Set a custom user shader for subsequent rendering operations
      */
@@ -59,6 +61,15 @@ export declare class GLRenderer {
      * This uses the internal copy shader and preserves draw ordering within the pipeline.
      */
     $imageRect(src: GLFramebuffer, x: number, y: number, width: number, height: number): void;
+    /**
+     * Enqueue drawing of an RGBA texture by converting to MRT attachments on the fly.
+     * The texture is sampled and resized into the target rect, writing brightness to character and grayscale to primary color.
+     */
+    /**
+     * Enqueue drawing of a TextmodeImage by converting its RGBA texture to MRT attachments on the fly.
+     * The method accepts only TextmodeImage to make the intent explicit and simplify callers.
+     */
+    $imageTexture(image: TextmodeImage, x: number, y: number, width: number, height: number): void;
     /**
      * Draw a quad covering the pixel rectangle (x, y, width, height) on the canvas.
      * The quad is converted to NDC and rendered with the current shader using only a_position.

package/dist/types/rendering/webgl/Shader.d.ts

@@ -1,5 +1,4 @@
 import { GLFramebuffer } from './Framebuffer';
-import type { ShaderSource } from './types/ShaderTypes';
 /**
  * Supported uniform value types
  */
@@ -17,11 +16,11 @@ export declare class GLShader {
     /**
      * Creates a new GLShader instance.
      * @param gl The WebGL rendering context.
-     * @param vertexSource The source code for the vertex shader (or ShaderData object).
-     * @param fragmentSource The source code for the fragment shader (or ShaderData object).
+     * @param vertexSource The source code for the vertex shader.
+     * @param fragmentSource The source code for the fragment shader.
      * @ignore
      */
-    constructor(gl: WebGLRenderingContext, vertexSource: ShaderSource, fragmentSource: ShaderSource);
+    constructor(gl: WebGLRenderingContext, vertexSource: string, fragmentSource: string);
     private _cacheLocations;
     private _createProgram;
     private _createShader;

package/dist/types/rendering/webgl/ShaderManager.d.ts

@@ -1,12 +1,12 @@
 import { GLShader } from './Shader';
-import type { ShaderSource } from './types/ShaderTypes';
 /**
  * Registry keys for built-in shaders
  */
 export declare enum BuiltInShader {
     MRT_DRAW = "mrt-draw",
     MRT_COPY = "mrt-copy",
-    ASCII_CONVERSION = "ascii-conversion"
+    ASCII_CONVERSION = "ascii-conversion",
+    IMAGE_TO_MRT = "image-to-mrt"
 }
 /**
  * Centralized shader management system for textmode.js
@@ -22,16 +22,12 @@ export declare enum BuiltInShader {
  * - Consistent resource management
  */
 export declare class ShaderManager {
-    private _shaders;
     private _gl;
+    private _copyShader;
+    private _mainDrawShader;
+    private _conversionShader;
+    private _imageToMRTShader;
     constructor(gl: WebGL2RenderingContext);
-    /**
-     * Get or create a shader with lazy initialization
-     * @param key Unique identifier for the shader
-     * @param factory Function that creates the shader if it doesn't exist
-     * @returns The shader instance
-     */
-    $getOrCreateShader(key: string, factory: () => GLShader): GLShader;
     /**
      * Get the shared MRT copy shader used for framebuffer compositing
      * This shader handles copying 5-attachment MRT data with proper transparency
@@ -47,6 +43,11 @@ export declare class ShaderManager {
      * This shader converts MRT data to final ASCII characters
      */
     $getConversionShader(): GLShader;
+    /**
+     * Get the shader that converts a single RGBA texture into MRT attachments.
+     * It writes brightness into o_character and grayscale into o_primaryColor.
+     */
+    $getImageToMRTShader(): GLShader;
     /**
      * Create a custom filter shader using the standard instanced vertex shader
      * These shaders are not cached as they are user-specific
@@ -56,7 +57,7 @@ export declare class ShaderManager {
      * Create a custom shader with arbitrary vertex and fragment sources
      * These shaders are not cached as they are user-specific
      */
-    $createCustomShader(vertexSource: ShaderSource, fragmentSource: ShaderSource): GLShader;
+    $createShader(vertexSource: string, fragmentSource: string): GLShader;
     /**
      * Dispose of all managed shaders and clear the registry
      * This method is idempotent and safe to call multiple times

package/dist/types/rendering/webgl/geometries/BaseGeometry.d.ts

@@ -4,6 +4,7 @@
 import type { InstanceBatch } from '../InstanceBatch';
 import type { InstanceData } from '../InstanceData';
 import type { IGeometry, GeometryType, UnitGeometryData } from '../types/GeometryTypes';
+import type { IRenderState } from '../RenderState';
 /**
  * Abstract base class for all instanced geometries.
  * Provides common functionality for instance data creation and batch management.
@@ -28,7 +29,7 @@ export declare abstract class BaseGeometry implements IGeometry {
      * This method handles the common instance data creation logic.
      * Subclasses can override this to add geometry-specific data.
      */
-    protected _createBaseInstanceData(x: number, y: number, width: number, height: number, renderState: any): InstanceData;
+    protected _createBaseInstanceData(x: number, y: number, width: number, height: number, renderState: IRenderState): InstanceData;
     /**
      * Convert screen coordinates to NDC for compatibility with existing code
      */

package/dist/types/rendering/webgl/types/DrawCommand.d.ts

@@ -1,5 +1,5 @@
 import type { GeometryParams, GeometryType } from './GeometryTypes';
-import type { IRenderState } from '../RenderState';
+import type { RenderState } from '../RenderState';
 import type { GLShader } from '../Shader';
 export type CustomRectParams = {
     x: number;
@@ -14,5 +14,5 @@ export interface DrawCommand {
     id: number;
     type: GeometryType;
     params: DrawParams;
-    state: IRenderState;
+    state: RenderState;
 }

package/dist/types/textmode/Canvas.d.ts

@@ -5,6 +5,8 @@ import type { TextmodeOptions } from "./Textmodifier";
  */
 export declare class TextmodeCanvas {
     private _canvas;
+    private _targetCanvas;
+    private _isOverlay;
     private _resizeObserver?;
     private _canvasCreatedByUs;
     /**
@@ -14,6 +16,9 @@ export declare class TextmodeCanvas {
      */
     constructor(opts?: TextmodeOptions);
     private _createCanvas;
+    private _createOverlayCanvas;
+    private _setupOverlayPositioning;
+    private _positionOverlayCanvas;
     /**
      * Resize the canvas to the specified width and height.
      * If width or height is not provided, it retains the current dimension.
@@ -34,6 +39,7 @@ export declare class TextmodeCanvas {
      */
     $dispose(): void;
     get canvas(): HTMLCanvasElement;
+    get targetCanvas(): HTMLCanvasElement | HTMLVideoElement | null;
     get width(): number;
     get height(): number;
 }

package/dist/types/textmode/TextmodeImage.d.ts

@@ -0,0 +1,92 @@
+import type { GLRenderer } from '../rendering/webgl/Renderer';
+/**
+ * TextmodeImage represents an image source uploaded to a WebGL texture.
+ * It can be drawn via the textmode image() API, which resizes into the MRT pipeline.
+ */
+export declare class TextmodeImage {
+    /**
+     * Underlying WebGL texture handle.
+     */
+    readonly texture: WebGLTexture;
+    /** Original pixel dimensions of the source image. */
+    readonly width: number;
+    readonly height: number;
+    private _gl;
+    private _invert;
+    private _flipX;
+    private _flipY;
+    private _charRotation;
+    private _charColorMode;
+    private _cellColorMode;
+    private _charColor;
+    private _cellColor;
+    private _backgroundColor;
+    private _glyphColors;
+    private _glyphColorResolver;
+    constructor(gl: WebGL2RenderingContext, texture: WebGLTexture, width: number, height: number);
+    /** Dispose of GPU resources. */
+    $dispose(): void;
+    /** Normalize boolean | number to 0/1 */
+    private _to01;
+    /**
+     * Invert the image colors indicator flag to pass into MRT transform (stored in o_transform.r).
+     * Does not modify the source texture pixels; downstream stages can respond accordingly.
+     */
+    invert(v?: boolean | number): this;
+    /**
+     * Set horizontal flip indicator flag (stored in o_transform.g).
+     */
+    flipX(v?: boolean | number): this;
+    /**
+     * Set vertical flip indicator flag (stored in o_transform.b).
+     */
+    flipY(v?: boolean | number): this;
+    /**
+     * Set character rotation in degrees, encoded into two channels as in RenderState.
+     */
+    charRotation(degrees: number): this;
+    /** Snapshot of flags for renderer uniform binding */
+    get flags(): Readonly<{
+        invert: number;
+        flipX: number;
+        flipY: number;
+    }>;
+    /** Encoded (r,g) rotation channels */
+    get charRotationRG(): Readonly<[number, number]>;
+    /** Set character color mode: 'sampled' (from image) or 'fixed' (use charColor) */
+    charColorMode(mode: 'sampled' | 'fixed'): this;
+    /** Set cell color mode: 'sampled' (from image) or 'fixed' (use cellColor) */
+    cellColorMode(mode: 'sampled' | 'fixed'): this;
+    /** Set fixed character color; numbers are 0..255 like other APIs */
+    charColor(r: number, g?: number, b?: number): this;
+    /** Set fixed cell color; numbers are 0..255 like other APIs */
+    cellColor(r: number, g?: number, b?: number): this;
+    /** Set background color for transparent pixels; numbers are 0..255 like other APIs */
+    background(r: number, g?: number, b?: number, a?: number): this;
+    /**
+     * Define the characters to use for brightness mapping, as a string.
+     * The string will be translated to glyph shader colors externally and stored here (max 64).
+     * Note: In this core class we only accept the precomputed colors via a helper; the public method is wired through RenderingMixin.
+     */
+    charactersFromColors(colors: ([number, number, number] | null)[]): this;
+    /** Convert a string to glyph colors using the resolver (from Textmodifier font) and store. */
+    characters(chars: string): this;
+    /** Internal: uniforms for character list */
+    get characterListUniforms(): Readonly<{
+        count: number;
+        list: number[][];
+    }>;
+    /** Internal: snapshot of color uniforms for renderer */
+    get colorUniforms(): Readonly<{
+        charColorFixed: boolean;
+        _charColor: [number, number, number];
+        cellColorFixed: boolean;
+        cellColor: [number, number, number];
+        backgroundColor: [number, number, number, number];
+    }>;
+    /**
+     * Create a TextmodeImage from an HTML image/video/canvas element.
+     * Texture parameters use NEAREST and CLAMP to align with grid sampling.
+     */
+    static fromSource(renderer: GLRenderer, source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, glyphResolver: (s: string) => ([number, number, number])[]): TextmodeImage;
+}

package/dist/types/textmode/Textmodifier.d.ts

@@ -2,6 +2,7 @@ import { GLRenderer } from '../rendering/webgl/Renderer';
 import { TextmodeFont } from './font';
 import { TextmodeGrid } from './Grid';
 import { TextmodeCanvas } from './Canvas';
+import { TextmodeImage } from './TextmodeImage';
 import { AnimationController } from './AnimationController';
 import { MouseManager } from './managers';
 import { KeyboardManager } from './managers';
@@ -35,6 +36,17 @@ export type TextmodeOptions = {
      * Optional for full builds *(will override embedded font if provided)*.
      */
     fontSource?: string;
+    /**
+     * Use `textmode.js` in overlay mode,
+     * which sets up the textmode <canvas> on top of an existing HTMLCanvasElement or HTMLVideoElement,
+     * automatically resizing and positioning it to match the target element.
+     *
+     * In this mode `textmode.js` fetches the content of the target element and applies it with adjustable textmode conversion
+     * as a first layer to the textmode canvas.
+     *
+     * Useful for applying textmode conversion to p5.js sketches, YouTube videos, and sooo much more.
+     */
+    overlay?: boolean;
 };
 /**
  * Base class for mixin application.
@@ -50,6 +62,8 @@ declare class TextmodifierCore implements TextmodifierContext {
     _textmodeDrawShader: Shader;
     _textmodeDrawFramebuffer: GLFramebuffer;
     _textmodeConversionShader: Shader;
+    _asciiColorFramebuffer: GLFramebuffer;
+    _presentShader: Shader;
     $render(): void;
 }
 declare const Textmodifier_base: typeof TextmodifierCore;
@@ -67,6 +81,9 @@ export declare class Textmodifier extends Textmodifier_base {
     private _drawCallback;
     private _resizedCallback;
     private _windowResizeListener;
+    private _resizeObserver?;
+    private _isOverlay;
+    private _targetCanvasImage?;
     /**
      * Creates an instance of Textmodifier.
      * @param opts Optional configuration options for the Textmodifier instance.
@@ -216,8 +233,7 @@ export declare class Textmodifier extends Textmodifier_base {
     get canvas(): HTMLCanvasElement;
     /** Check if the instance has been disposed/destroyed. */
     get isDisposed(): boolean;
-    /** Get the draw framebuffer used for offscreen rendering. @ignore */
-    get drawFramebuffer(): GLFramebuffer;
+    get overlay(): TextmodeImage | undefined;
 }
 export interface Textmodifier extends RenderingCapabilities, ExportCapabilities, FontCapabilities, AnimationCapabilities, MouseCapabilities, KeyboardCapabilities {
 }

package/dist/types/textmode/font/CharacterExtractor.d.ts

@@ -4,32 +4,32 @@ import type { TyprFont } from './typr/types.ts';
  * This class encapsulates the complex logic for reading different cmap table formats.
  */
 export declare class CharacterExtraction {
-    private _cmapParser;
-    constructor();
     /**
      * Extracts all available characters from a font's cmap tables.
      * @param font The parsed font object from Typr
      * @returns Array of unique character strings
      */
-    extractCharacters(font: TyprFont): string[];
+    $extractCharacters(font: TyprFont): string[];
     /**
      * Filters out problematic characters that might cause rendering issues.
      * @param characters Array of character strings to filter
      * @returns Filtered array of character strings
      */
-    filterProblematicCharacters(characters: string[]): string[];
+    $filterProblematicCharacters(characters: string[]): string[];
     /**
-     * Checks if a character exists in the font.
-     * @param font The parsed font object from Typr
-     * @param character The character to check
-     * @returns True if the character exists in the font
+     * Extracts characters from a Format 4 cmap table (Basic Multilingual Plane).
      */
-    characterExists(font: TyprFont, character: string): boolean;
+    private _extractCharactersFromFormat4;
     /**
-     * Checks if all characters in a string exist in the font.
-     * @param font The parsed font object from Typr
-     * @param text The text string to check
-     * @returns True if all characters exist in the font
+     * Extracts characters from a Format 12 cmap table (Extended Unicode ranges).
+     */
+    private _extractCharactersFromFormat12;
+    /**
+     * Calculates the glyph index for a character in a Format 4 cmap table.
+     */
+    private _calculateGlyphIndexFormat4;
+    /**
+     * Checks if a character is valid for rendering.
      */
-    allCharactersExist(font: TyprFont, text: string): boolean;
+    private _isValidCharacter;
 }

package/dist/types/textmode/font/MetricsCalculator.d.ts

@@ -19,27 +19,7 @@ export declare class FontMetricsCalculator {
      * @param font Parsed TyprFont object containing font data
      * @returns Object containing width and height dimensions
      */
-    calculateMaxGlyphDimensions(characters: string[], fontSize: number, font: TyprFont): GlyphDimensions;
-    /**
-     * Gets the character advance width for a specific character and font size.
-     * @param character The character to measure
-     * @param fontSize Font size to use for scaling
-     * @param font Parsed TyprFont object
-     * @returns Advance width in pixels
-     */
-    getCharacterAdvanceWidth(character: string, fontSize: number, font: TyprFont): number;
-    /**
-     * Gets the font-level ascender, descender, and line gap values for a given font size.
-     * @param fontSize Font size to use for scaling
-     * @param font Parsed TyprFont object
-     * @returns Object containing ascender, descender, and lineGap in pixels
-     */
-    getFontMetrics(fontSize: number, font: TyprFont): {
-        ascender: number;
-        descender: number;
-        lineGap: number;
-        lineHeight: number;
-    };
+    $calculateMaxGlyphDimensions(characters: string[], fontSize: number, font: TyprFont): GlyphDimensions;
     /**
      * Clears internal caches. Useful for memory management.
      */

package/dist/types/textmode/font/typr/Typr.d.ts

@@ -11,8 +11,10 @@
  * @license MIT
  */
 import type { TyprStatic } from './types';
+declare function woffToOtfSync(buff: ArrayBuffer): ArrayBuffer;
 /**
  * Main Typr class implementation
  */
 declare const Typr: TyprStatic;
 export default Typr;
+export declare const convertWoffToOtf: typeof woffToOtfSync;

package/dist/types/textmode/font/typr/types.d.ts

@@ -18,6 +18,12 @@ export interface TyprBinary {
     readUint: (buff: Uint8Array, p: number) => number;
     /** Read ASCII string */
     readASCII: (buff: Uint8Array, p: number, l: number) => string;
+    /** Write unsigned 16-bit integer (big-endian) */
+    writeUshort: (buff: Uint8Array, p: number, n: number) => void;
+    /** Write unsigned 32-bit integer (big-endian) */
+    writeUint: (buff: Uint8Array, p: number, n: number) => void;
+    /** Write ASCII string */
+    writeASCII: (buff: Uint8Array, p: number, s: string) => void;
     /** Shared typed array buffers for efficient reading */
     t: {
         uint8: Uint8Array;

package/dist/types/textmode/font/utils/index.d.ts

@@ -5,4 +5,3 @@
  * across the font system components.
  */
 export { FontTableReader } from './FontTableReader.ts';
-export { CmapParser } from './CmapParser.ts';

package/dist/types/textmode/mixins/AnimationMixin.d.ts

@@ -111,7 +111,13 @@ export interface AnimationCapabilities {
      * ```
      */
     isLooping(): boolean;
+    /**
+     * Get the current frame count.
+     */
     get frameCount(): number;
+    /**
+     * Set the current frame count.
+     */
     set frameCount(value: number);
 }
 /**

package/dist/types/textmode/mixins/FontMixin.d.ts

@@ -13,10 +13,10 @@ export interface FontCapabilities {
      * const textmodifier = textmode.create();
      *
      * // Load a custom font from a URL
-     * await textmodifier.loadFont('https://example.com/fonts/myfont.ttf');
+     *  textmodifier.loadFont('https://example.com/fonts/myfont.ttf');
      *
      * // Local font example
-     * // await textmodifier.loadFont('./fonts/myfont.ttf');
+     * // textmodifier.loadFont('./fonts/myfont.ttf');
      * ```
      */
     loadFont(fontSource: string): Promise<void>;
@@ -27,13 +27,53 @@ export interface FontCapabilities {
      * @example
      * ```javascript
      * // Create a Textmodifier instance
-     * const textmodifier = await textmode.create();
+     * const textmodifier = textmode.create();
      *
      * // Set the font size to 32
      * textmodifier.fontSize(32);
      * ```
      */
     fontSize(size: number): void;
+    /**
+     * Get the RGB shader color of a specific character in the current font.
+     *
+     * Useful for custom shaders to control the character to render.
+     *
+     * @param char The character to get the color for.
+     * @returns An array representing the RGB color, or null if the character is not found.
+     * @example
+     * ```javascript
+     * // Create a Textmodifier instance
+     * const textmodifier = textmode.create();
+     *
+     * // Get the color of the character 'A'
+     * textmodifier.setup(() => {
+     *   const color = textmodifier.glyphColor('A');
+     *   console.log(color); // e.g., [1, 0, 0] for red
+     * });
+     * ```
+     */
+    glyphColor(char: string): [number, number, number] | null;
+    /**
+     * Get the RGB shader colors of all characters in a string for the current font.
+     *
+     * Useful for custom shaders to control the characters to render.
+     *
+     * @param str The string to get the colors for.
+     * @returns An array of RGB color arrays, or null if a character is not found.
+     * @example
+     * ```javascript
+     * // Create a Textmodifier instance
+     * const textmodifier = textmode.create();
+     *
+     * // Get the colors of the string 'Hello'
+     * textmodifier.setup(() => {
+     *   const colors = textmodifier.glyphColors('Hello');
+     *   console.log(colors); // e.g., [[0.1, 0, 0], ...]
+     * });
+     * ```
+     */
+    glyphColors(str: string): ([number, number, number] | null)[];
 }
 /**
  * Mixin that adds font capabilities to a class

package/dist/types/textmode/mixins/KeyboardMixin.d.ts

@@ -1,5 +1,4 @@
 import type { Mixin } from './TextmodifierMixin';
-import type { KeyboardEventHandler } from '../managers';
 /**
  * Capabilities provided by the KeyboardMixin
  */
@@ -62,7 +61,7 @@ export interface KeyboardCapabilities {
      * });
      * ```
      */
-    keyPressed(callback: KeyboardEventHandler): void;
+    keyPressed(callback: () => void): void;
     /**
      * Set a callback function that will be called when a key is released.
      *
@@ -80,7 +79,7 @@ export interface KeyboardCapabilities {
      * });
      * ```
      */
-    keyReleased(callback: KeyboardEventHandler): void;
+    keyReleased(callback: () => void): void;
 }
 /**
  * Mixin that adds keyboard interaction capabilities to Textmodifier.

package/dist/types/textmode/mixins/MouseMixin.d.ts

@@ -1,5 +1,5 @@
 import type { Mixin } from './TextmodifierMixin';
-import type { MousePosition, MouseEventHandler } from '../managers';
+import type { MousePosition } from '../managers';
 /**
  * Capabilities provided by the MouseMixin
  */
@@ -19,7 +19,7 @@ export interface MouseCapabilities {
      * });
      * ```
      */
-    mouseClicked(callback: MouseEventHandler): void;
+    mouseClicked(callback: () => void): void;
     /**
      * Set a callback function that will be called when the mouse is pressed down.
      *
@@ -34,7 +34,7 @@ export interface MouseCapabilities {
      * });
      * ```
      */
-    mousePressed(callback: MouseEventHandler): void;
+    mousePressed(callback: () => void): void;
     /**
      * Set a callback function that will be called when the mouse is released.
      *
@@ -49,7 +49,7 @@ export interface MouseCapabilities {
      * });
      * ```
      */
-    mouseReleased(callback: MouseEventHandler): void;
+    mouseReleased(callback: () => void): void;
     /**
      * Set a callback function that will be called when the mouse moves.
      *
@@ -67,7 +67,7 @@ export interface MouseCapabilities {
      * });
      * ```
      */
-    mouseMoved(callback: MouseEventHandler): void;
+    mouseMoved(callback: () => void): void;
     /**
      * Set a callback function that will be called when the mouse wheel is scrolled.
      *
@@ -83,7 +83,7 @@ export interface MouseCapabilities {
      * });
      * ```
      */
-    mouseScrolled(callback: MouseEventHandler): void;
+    mouseScrolled(callback: () => void): void;
     /**
      * Get the current mouse position in grid coordinates.
      *

package/dist/types/textmode/mixins/RenderingMixin.d.ts

@@ -1,6 +1,7 @@
 import type { Mixin } from './TextmodifierMixin';
 import type { GLShader } from '../../rendering/webgl/Shader';
 import type { GLFramebuffer } from '../../rendering';
+import { TextmodeImage } from '../TextmodeImage';
 /**
  * Options for creating a framebuffer.
  */
@@ -128,7 +129,12 @@ export interface RenderingCapabilities {
      * });
      * ```
      */
-    image(framebuffer: GLFramebuffer, x: number, y: number, width?: number, height?: number): void;
+    image(source: GLFramebuffer | TextmodeImage, x: number, y: number, width?: number, height?: number): void;
+    /**
+     * Load an image and return a TextmodeImage that can be drawn with image().
+     * @param src URL or existing HTMLImageElement
+     */
+    loadImage(src: string | HTMLImageElement): Promise<TextmodeImage>;
     /**
      * Set a uniform value for the current custom shader.
      * @param name The name of the uniform variable
@@ -240,7 +246,10 @@ export interface RenderingCapabilities {
      */
     createFilterShader(fragmentSource: string): GLShader;
     /**
-     * Sets the rotation angles for subsequent shape rendering operations
+     * Sets the rotation angles for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
      * @param degreesX The rotation angle in degrees around the X-axis (optional, defaults to 0)
      * @param degreesY The rotation angle in degrees around the Y-axis (optional, defaults to 0)
      * @param degreesZ The rotation angle in degrees around the Z-axis (optional, defaults to 0)
@@ -267,7 +276,10 @@ export interface RenderingCapabilities {
      */
     rotate(degreesX?: number, degreesY?: number, degreesZ?: number): void;
     /**
-     * Sets the X-axis rotation angle for subsequent shape rendering operations
+     * Sets the X-axis rotation angle for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
      * @param degrees The rotation angle in degrees around the X-axis
      *
      * @example
@@ -286,7 +298,10 @@ export interface RenderingCapabilities {
      */
     rotateX(degrees: number): void;
     /**
-     * Sets the Y-axis rotation angle for subsequent shape rendering operations
+     * Sets the Y-axis rotation angle for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
      * @param degrees The rotation angle in degrees around the Y-axis
      *
      * @example
@@ -305,7 +320,10 @@ export interface RenderingCapabilities {
      */
     rotateY(degrees: number): void;
     /**
-     * Sets the Z-axis rotation angle for subsequent shape rendering operations
+     * Sets the Z-axis rotation angle for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
      * @param degrees The rotation angle in degrees around the Z-axis
      *
      * @example