textmode.js 0.4.1-beta.1 → 0.6.0-beta.2

package/dist/types/textmode/interfaces/ITextmodifier.d.ts

@@ -0,0 +1,275 @@
+import type { TextmodeGrid } from '../Grid';
+import type { TextmodeFont } from '../loadables/font';
+import type { TextmodeImage } from '../loadables/TextmodeImage';
+import type { TextmodeCanvas } from '../Canvas';
+import type { AnimationController } from '../AnimationController';
+import type { GLFramebuffer, Shader } from '../../rendering';
+import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
+import type { MouseManager } from '../managers/MouseManager';
+import type { KeyboardManager } from '../managers/KeyboardManager';
+import type { TouchManager } from '../managers/TouchManager';
+import type { IRenderingMixin } from '../mixins/interfaces/IRenderingMixin';
+import type { IFontMixin } from '../mixins/interfaces/IFontMixin';
+import type { IKeyboardMixin } from '../mixins/interfaces/IKeyboardMixin';
+import type { ITouchMixin } from '../mixins/interfaces/ITouchMixin';
+import type { IMouseMixin } from '../mixins/interfaces/IMouseMixin';
+import type { IAnimationMixin } from '../mixins/interfaces/IAnimationMixin';
+import type { LoadingScreenManager } from '../loading/LoadingScreenManager';
+/**
+ * Manages textmode rendering on a [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) and provides methods for drawing,
+ * exporting, font management, event handling, and animation control.
+ *
+ * If the `Textmodifier` instance is created without a canvas parameter,
+ * it creates a new `HTMLCanvasElement` to draw on using the `textmode.js` drawing API.
+ * If a canvas is provided, it will use that canvas instead.
+ */
+export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMixin, IMouseMixin, ITouchMixin, IKeyboardMixin {
+    /** Core WebGL renderer @ignore */
+    readonly _renderer: GLRenderer;
+    /** Font management @ignore */
+    readonly _font: TextmodeFont;
+    /** Canvas management @ignore */
+    readonly _canvas: TextmodeCanvas;
+    /** Grid management @ignore */
+    readonly _grid: TextmodeGrid;
+    /** Animation controller for managing rendering loop @ignore */
+    readonly _animationController: AnimationController;
+    /** Mouse interaction manager @ignore */
+    readonly _mouseManager: MouseManager;
+    /** Touch interaction manager @ignore */
+    readonly _touchManager: TouchManager;
+    /** Keyboard interaction manager @ignore */
+    readonly _keyboardManager: KeyboardManager;
+    /** Framebuffer used for offscreen rendering @ignore */
+    readonly _textmodeDrawFramebuffer: GLFramebuffer;
+    /** Shader used for converting pixels to textmode grid format @ignore */
+    readonly _textmodeConversionShader: Shader;
+    /** Framebuffer used for textmode conversion @ignore */
+    readonly _textmodeFramebuffer: GLFramebuffer;
+    /** Shader used for final presentation to the screen @ignore */
+    readonly _presentShader: Shader;
+    /** Loading screen manager for boot-time UX @ignore */
+    readonly _loading: LoadingScreenManager;
+    /** Main render method @ignore */
+    $render(): void;
+    /**
+     * Set a setup callback function that will be executed once when initialization is complete.
+     *
+     * This callback is called after font loading and grid initialization, allowing access to
+     * properties like `textmodifier.grid.cols` for calculating layout or setup variables.
+     *
+     * @param callback The function to call when setup is complete
+     *
+     * @example
+     * ```javascript
+     * const textmodifier = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     *   fontSize: 16
+     * });
+     *
+     * // Setup callback - called once when ready
+     * textmodifier.setup(() => {
+     *   // Now you can access grid properties
+     *   const cols = textmodifier.grid.cols;
+     *   const rows = textmodifier.grid.rows;
+     *
+     *   // Initialize any variables that depend on grid size
+     *   rectWidth = Math.floor(cols / 3);
+     *   rectHeight = Math.floor(rows / 2);
+     * });
+     *
+     * // Draw callback - called every frame
+     * textmodifier.draw(() => {
+     *   textmodifier.background(128);
+     *   textmodifier.char('A');
+     *   textmodifier.rotateZ(textmodifier.frameCount * 2);
+     *   textmodifier.rect(rectWidth, rectHeight);
+     * });
+     * ```
+     */
+    setup(callback: () => void): void;
+    /**
+     * Set a draw callback function that will be executed before each render.
+     *
+     * This callback function is where all drawing commands should be placed for textmode rendering.
+     *
+     * @param callback The function to call before each render
+     *
+     * @example
+     * ```javascript
+     * // Create a textmodifier instance
+     * const t = textmode.create({
+     *  width: 800,
+     *  height: 600,
+     * });
+     *
+     * // Set up draw callback
+     * t.draw(() => {
+     *   // Set background color
+     *   t.background(128);
+     *
+     *   // Draw a textmode rectangle
+     *   t.char('A');
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(16, 16);
+     * });
+     * ```
+     */
+    draw(callback: () => void): void;
+    /**
+     * Set a callback function that will be called when the window is resized.
+     * @param callback The function to call when the window is resized.
+     *
+     * @example
+     * ```javascript
+     * // Create a standalone textmodifier instance
+     * const t = textmode.create({
+     *   width: window.innerWidth,
+     *   height: window.innerHeight,
+     * });
+     *
+     * // Draw callback to update content
+     * t.draw(() => {
+     *  // Set background color
+     *  t.background(128);
+     *  t.char('A');
+     *  t.rotateZ(t.frameCount * 2);
+     *  t.rect(16, 16);
+     * });
+     *
+     * // Set up window resize callback
+     * t.windowResized(() => {
+     *   // Resize the canvas to match window size
+     *   t.resizeCanvas(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    windowResized(callback: () => void): void;
+    /**
+     * Resize the canvas and adjust all related components accordingly.
+     *
+     * @param width The new width of the canvas.
+     * @param height The new height of the canvas.
+     *
+     * @example
+     * ```javascript
+     * // Create a standalone textmodifier instance
+     * const t = textmode.create({
+     *   width: window.innerWidth,
+     *   height: window.innerHeight,
+     * });
+     *
+     * // Draw callback to update content
+     * t.draw(() => {
+     *  // Set background color
+     *  t.background(128);
+     *  t.char('A');
+     *  t.rotateZ(t.frameCount * 2);
+     *  t.rect(16, 16);
+     * });
+     *
+     * // Set up window resize callback
+     * t.windowResized(() => {
+     *   // Resize the canvas to match window size
+     *   t.resizeCanvas(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    resizeCanvas(width: number, height: number): void;
+    /**
+     * Completely destroy this Textmodifier instance and free all associated resources.
+     *
+     * After calling this method, the instance should not be used and will be eligible for garbage collection.
+     *
+     * @example
+     * ```javascript
+     * // Create a textmodifier instance
+     * const textmodifier = textmode.create();
+     *
+     * // ...
+     *
+     * // When done, completely clean up
+     * textmodifier.destroy();
+     *
+     * // Instance is now safely disposed and ready for garbage collection
+     * ```
+     */
+    destroy(): void;
+    /** Get the current grid object used for rendering. */
+    readonly grid: TextmodeGrid;
+    /** Get the current font object used for rendering. */
+    readonly font: TextmodeFont;
+    /** Get the width of the canvas in pixels. */
+    readonly width: number;
+    /** Get the height of the canvas in pixels. */
+    readonly height: number;
+    /** Get the textmodifier canvas containing the rendered output. */
+    readonly canvas: HTMLCanvasElement;
+    /** Get the WebGL framebuffer used for drawing operations in {@link Textmodifier.draw}. */
+    readonly drawFramebuffer: GLFramebuffer;
+    /** Check if the instance has been disposed/destroyed. */
+    readonly isDisposed: boolean;
+    /**
+     * If in overlay mode, returns the {@link TextmodeImage} instance capturing the target canvas/video content,
+     * allowing further configuration of the conversion parameters.
+     *
+     * @example
+     * ```javascript
+     * // Create the textmode instance using the p5 canvas as input overlay
+     * const t = textmode.create({ fontSize: 16, canvas: p.canvas, overlay: true });
+     *
+     * // Configure overlay conversion once fonts and grid are ready
+     * t.setup(() => {
+     *   t.overlay
+     *     .characters(' .:-=+*#%@')        // Character set for brightness mapping
+     *     .cellColorMode('fixed')          // Use fixed background cell color
+     *     .cellColor(0, 0, 0)              // Black background for each cell
+     *     .charColorMode('sampled')        // Sample the character color from the image
+     *     .background(0, 0, 0, 255);       // Black fallback for transparent pixels
+     * });
+     *
+     * // In the draw loop, pass the overlay into the text grid
+     * t.draw(() => {
+     *   t.clear();
+     *   t.image(t.overlay, t.grid.cols, t.grid.rows);
+     * });
+     *```
+     */
+    readonly overlay: TextmodeImage | undefined;
+    /**
+     * Provides access to the loading screen manager to control boot-time loading UX.
+     *
+     * @example
+    * ```javascript
+    * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'loading...' } });
+    *
+    * t.setup(async () => {
+    *   // Initialize two loading phases
+    *   const phase1 = t.loading.addPhase('Loading assets');
+    *   const phase2 = t.loading.addPhase('Initializing game');
+    *
+    *   // Start the first phase and simulate asset loading
+    *   await phase1.track(async () => {
+    *     for (let i = 0; i <= 5; i++) {
+    *       phase1.report(i / 5);
+    *       // Small delay — increases visibility of the loading animation
+    *       await new Promise((r) => setTimeout(r, 200));
+    *     }
+    *   });
+    *
+    *   // Start the second phase and simulate initialization
+    *   await phase2.track(async () => {
+    *     for (let i = 0; i <= 5; i++) {
+    *       phase2.report(i / 5);
+    *       await new Promise((r) => setTimeout(r, 150));
+    *     }
+    *   });
+    *
+    *   // Optionally set a final message before the screen transitions away
+    *   t.loading.message('Ready - enjoy!');
+    * });
+    * ```
+     */
+    readonly loading: LoadingScreenManager;
+}

package/dist/types/textmode/interfaces/index.d.ts

@@ -0,0 +1 @@
+export type { ITextmodifier } from './ITextmodifier';

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

@@ -0,0 +1,47 @@
+import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
+import { TextmodeSource } from './TextmodeSource';
+/**
+ * Represents an image uploaded for textmode rendering via {@link Textmodifier.loadImage}.
+ *
+ * It can be drawn to the canvas via {@link Textmodifier.image}.
+ *
+ * An image uploaded currently runs through an adjustable brightness-converter that converts
+ * the original image into a textmode representation using characters.
+ * Those adjustable options are available via chainable methods on this class.
+ *
+ * @example
+ * ```javascript
+ * const t = textmode.create({
+ *     width: 800,
+ *     height: 600,
+ * });
+ *
+ * let img;
+ *
+ * t.setup(async () => {
+ *     img = await t.loadImage('https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&q=80');
+ *     img.characters(" .:-=+*#%@");
+ *     // ... other adjustments like img.flipX(boolean), img.cellColorMode('sampled' | 'fixed'), etc.
+ *     // (can also be chained or updated during runtime)
+ * });
+ *
+ * t.draw(() => {
+ *     t.background(0);
+ *
+ *     if (img) {
+ *         // Draw the loaded image
+ *         t.image(img);
+ *     }
+ * });
+ * ```
+ */
+export declare class TextmodeImage extends TextmodeSource {
+    private constructor();
+    /**
+     * Create a TextmodeImage from an HTML image/video/canvas element.
+     * Texture parameters use NEAREST and CLAMP to align with grid sampling.
+     * @ignore
+     */
+    static $fromSource(renderer: GLRenderer, source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, gridCols: number, gridRows: number, glyphResolver: (s: string) => ([number, number, number])[]): TextmodeImage;
+    protected $getActiveTexture(): WebGLTexture;
+}

package/dist/types/textmode/loadables/TextmodeSource.d.ts

@@ -0,0 +1,130 @@
+import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
+import type { Material } from '../../rendering/webgl/materials/Material';
+import { TextmodeColor } from '../TextmodeColor';
+type GlyphColor = [number, number, number];
+/**
+ * Base class for drawable textmode sources (images, videos, canvas, etc.).
+ * Handles shared WebGL texture state, material creation, and color/character settings.
+ */
+export declare abstract class TextmodeSource {
+    protected _gl: WebGL2RenderingContext;
+    protected _renderer: GLRenderer;
+    protected _texture: WebGLTexture;
+    protected _originalWidth: number;
+    protected _originalHeight: number;
+    protected _width: number;
+    protected _height: number;
+    protected _material: Material | null;
+    protected _invert: number;
+    protected _flipX: number;
+    protected _flipY: number;
+    protected _charRotation: number;
+    protected _charColorMode: 'sampled' | 'fixed';
+    protected _cellColorMode: 'sampled' | 'fixed';
+    protected _charColor: [number, number, number, number];
+    protected _cellColor: [number, number, number, number];
+    protected _backgroundColor: [number, number, number, number];
+    protected _glyphColors: GlyphColor[];
+    protected _glyphColorResolver: (s: string) => GlyphColor[];
+    private static _sharedShader;
+    protected constructor(gl: WebGL2RenderingContext, renderer: GLRenderer, texture: WebGLTexture, originalWidth: number, originalHeight: number, width: number, height: number);
+    /**
+     * Dispose of the underlying WebGL texture. Subclasses may extend for additional cleanup.
+     * @ignore
+     */
+    $dispose(): void;
+    /**
+     * Set the invert flag, swapping character and cell colors when enabled.
+     * @param v Invert flag
+     * @returns This instance for chaining.
+     */
+    invert(v?: boolean | number): this;
+    /**
+     * Set horizontal flip indicator flag.
+     * @param v Flip flag
+     * @returns This instance for chaining.
+     */
+    flipX(v?: boolean | number): this;
+    /**
+     * Set vertical flip indicator flag.
+     * @param v Flip flag
+     * @returns This instance for chaining.
+     */
+    flipY(v?: boolean | number): this;
+    /**
+     * Set the character rotation in degrees (0-360).
+     * @param degrees Rotation in degrees
+     * @returns This instance for chaining.
+     */
+    charRotation(degrees: number): this;
+    /**
+     * Set character color mode: `'sampled'` *(from source)* or `'fixed'`.
+     * @param mode The character color mode
+     * @returns This instance for chaining.
+     */
+    charColorMode(mode: 'sampled' | 'fixed'): this;
+    /**
+     * Set cell color mode: `'sampled'` *(from source)* or `'fixed'`.
+     * @param mode The cell color mode
+     * @returns This instance for chaining.
+     */
+    cellColorMode(mode: 'sampled' | 'fixed'): this;
+    /**
+     * Defines the character color when {@link charColorMode} is `'fixed'`.
+     * @param colorOrGray A grayscale value (0-255), hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), or TextmodeColor instance
+     * @param g Green component (0-255) if using RGB format
+     * @param b Blue component (0-255) if using RGB format
+     * @param a Alpha component (0-255) if using RGBA format
+     * @returns This instance for chaining.
+     */
+    charColor(colorOrGray: number | string | TextmodeColor, g?: number, b?: number, a?: number): this;
+    /**
+     * Defines the cell color when {@link cellColorMode} is `'fixed'`.
+     * @param colorOrGray A grayscale value (0-255), hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), or TextmodeColor instance
+     * @param g Green component (0-255) if using RGB format
+     * @param b Blue component (0-255) if using RGB format
+     * @param a Alpha component (0-255) if using RGBA format
+     * @returns This instance for chaining.
+     */
+    cellColor(colorOrGray: number | string | TextmodeColor, g?: number, b?: number, a?: number): this;
+    /**
+     * Defines the background color used for transparent pixels.
+     * @param colorOrGray A grayscale value (0-255), hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), or TextmodeColor instance
+     * @param g Green component (0-255) if using RGB format
+     * @param b Blue component (0-255) if using RGB format
+     * @param a Alpha component (0-255) if using RGBA format
+     * @returns This instance for chaining.
+     */
+    background(colorOrGray: number | TextmodeColor | string, g?: number, b?: number, a?: number): this;
+    /**
+     * Define the characters to use for brightness mapping as a string.
+     * Maximum length is 64; excess characters are ignored.
+     * @param chars String of characters to map
+     * @returns This instance for chaining.
+     */
+    characters(chars: string): this;
+    /** Return the WebGL texture currently backing this source. */
+    get texture(): WebGLTexture;
+    /** Ideal width in grid cells. */
+    get width(): number;
+    /** Ideal height in grid cells. */
+    get height(): number;
+    /** Original pixel width. */
+    get originalWidth(): number;
+    /** Original pixel height. */
+    get originalHeight(): number;
+    /**
+     * Get or create the material for rendering this source.
+     * @ignore
+     */
+    $getMaterial(): Material;
+    /** Hook for subclasses to run logic before material updates (e.g., upload latest frame). */
+    protected $beforeMaterialUpdate(): void;
+    /** Subclasses must supply the active texture handle to bind as u_image. */
+    protected abstract $getActiveTexture(): WebGLTexture;
+    private _updateMaterial;
+    private _setColor;
+    private _ensureShader;
+    protected _createUniforms(): Record<string, any>;
+}
+export {};