textmode.js 0.4.0 → 0.6.0-beta.1

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

@@ -0,0 +1,21 @@
+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.
+ */
+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 or TextmodeColor for the character
+     * @param g Additional green component if using RGB
+     * @param b Additional blue component if using RGB
+     * @param a Additional alpha component if using RGBA
+     * @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 or TextmodeColor for the cell
+     * @param g Additional green component if using RGB
+     * @param b Additional blue component if using RGB
+     * @param a Additional alpha component if using RGBA
+     * @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 or TextmodeColor for the background
+     * @param g Additional green component if using RGB
+     * @param b Additional blue component if using RGB
+     * @param a Additional alpha component if using RGBA
+     * @returns This instance for chaining.
+     */
+    background(colorOrGray: number | TextmodeColor, 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 {};

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

@@ -0,0 +1,237 @@
+import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
+import type { Material } from '../../rendering/webgl/materials/Material';
+import { TextmodeSource } from './TextmodeSource';
+type TextmodeVideoPreloadStrategy = 'captureStream' | 'seeking';
+export interface TextmodeVideoPreloadProgress {
+    percent: number;
+    loadedFrames: number;
+    totalFrames: number;
+    strategy: TextmodeVideoPreloadStrategy;
+}
+export interface TextmodeVideoPreloadComplete {
+    totalFrames: number;
+    strategy: TextmodeVideoPreloadStrategy;
+}
+/**
+ * Options for preloading video frames in {@link TextmodeVideo}.
+ *
+ * When providing this options object as a second argument to {@link Textmodifier.loadVideo},
+ * you can choose to preload all video frames at a specified frame rate before using the video.
+ *
+ * When preloading, the video will not play live asynchronously. Instead, all frames will be captured
+ * upfront, allowing for frame-accurate seeking and rendering.
+ *
+ * This is especially useful for scenarios where precise frame control is needed,
+ * like capturing GIFs/videos from textmode.js canvas using the `textmode.export.js` add-on library without
+ * missing frames due to asynchronous video playback.
+ *
+ * Preloading takes time proportional to the video length and frame rate, which introduces significant delays
+ * before the sketch can start rendering. Therefore, it is recommended to use this feature only when intending
+ * to capture or export frames, rather than for real-time playback.
+ */
+export interface TextmodeVideoOptions {
+    /** Frame rate to use when preloading video frames. If not specified, video will not be preloaded. */
+    frameRate?: number;
+    /** Callback invoked periodically during preloading to report progress. */
+    onProgress?: (progress: TextmodeVideoPreloadProgress) => void;
+    /** Callback invoked once preloading is complete. */
+    onComplete?: (summary: TextmodeVideoPreloadComplete) => void;
+    /** Callback invoked if an error occurs during preloading. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Represents a video element for textmode rendering via {@link Textmodifier.loadVideo}.
+ *
+ * It can be drawn to the canvas via {@link Textmodifier.image}.
+ *
+ * A video uploaded currently runs through an adjustable brightness-converter that converts
+ * the video frames into a textmode representation using characters.
+ * Those adjustable options are available via chainable methods on this class.
+ */
+export declare class TextmodeVideo extends TextmodeSource {
+    private _videoElement;
+    private _isPreloaded;
+    private _preloadedFrames;
+    private _frameRate;
+    private _totalFrames;
+    private _currentFrameIndex;
+    private _lastProgressBucket;
+    /**
+     * Create a new TextmodeVideo instance.
+     * @param gl WebGL2 rendering context
+     * @param renderer GLRenderer instance
+     * @param texture WebGL texture for video frames
+     * @param videoElement The HTML video element
+     * @param originalWidth Original video width in pixels
+     * @param originalHeight Original video height in pixels
+     * @param gridCols Number of columns in the grid (for auto-sizing)
+     * @param gridRows Number of rows in the grid (for auto-sizing)
+     *
+     * @ignore
+     */
+    constructor(gl: WebGL2RenderingContext, renderer: GLRenderer, texture: WebGLTexture, videoElement: HTMLVideoElement, originalWidth: number, originalHeight: number, gridCols: number, gridRows: number);
+    /**
+     * Dispose of GPU resources and cleanup video element.
+     * @ignore
+     */
+    dispose(): void;
+    /**
+     * Update the texture with the current video frame if needed.
+     * For preloaded videos, this returns the appropriate frame texture.
+     * For live videos, this updates the texture with current video data.
+     * @ignore
+     */
+    $updateTexture(): void;
+    /**
+     * Get the active texture for the current frame.
+     * For preloaded videos, returns the texture at the current frame index.
+     * For live videos, returns the live texture.
+     * @ignore
+     */
+    protected $getActiveTexture(): WebGLTexture;
+    /**
+     * Get or create the material for rendering this video.
+     * Always updates the material to ensure the latest video frame is used.
+     * @ignore
+     */
+    $getMaterial(): Material;
+    protected $beforeMaterialUpdate(): void;
+    /**
+     * Preload all frames of the video at the specified frame rate.
+     * Chooses the most optimal strategy based on browser capabilities.
+     * @param frameRate Frame rate to use for capturing frames
+     * @ignore
+     */
+    private _preloadFrames;
+    private _initializePreloadState;
+    private _finalizePreloadSuccess;
+    private _captureSourceToTexture;
+    private _reportPreloadProgress;
+    private _tryPreloadWithTrackProcessor;
+    private _preloadWithLegacySeeking;
+    private _waitForSeek;
+    /**
+     * For preloaded videos, set or get the current frame index.
+     * When called without arguments, returns this video instance for use with t.image().
+     * When called with an index, sets the frame and returns this instance.
+     *
+     * The frame index automatically wraps using modulo, so you can pass t.frameCount directly
+     * and it will loop through the video frames seamlessly.
+     *
+     * For non-preloaded videos, this method does nothing and returns the instance.
+     *
+     * @param index Optional frame index to set (0-based, automatically wraps)
+     * @returns This instance for chaining.
+     *
+     * @example
+     * ```javascript
+     * // Draw specific frame
+     * t.image(video.frame(0), x, y);
+     *
+     * // Draw frame based on frameCount (automatically wraps)
+     * t.image(video.frame(t.frameCount), x, y);
+     *
+     * video.frame(t.frameCount);
+     * t.image(video, x, y);
+     * ```
+     */
+    frame(index?: number): this;
+    /**
+     * Create a TextmodeVideo instance from a video source (URL or HTMLVideoElement).
+     * @param renderer GLRenderer instance
+     * @param source Video URL string or HTMLVideoElement
+     * @param gridCols Number of columns in the grid
+     * @param gridRows Number of rows in the grid
+     * @param glyphResolver Function to resolve character strings to glyph colors
+     * @param options Optional preload configuration (frameRate, onProgress, onComplete, onError).
+     * @returns Promise resolving to TextmodeVideo instance
+     * @ignore
+     */
+    static $fromSource(renderer: GLRenderer, source: string | HTMLVideoElement, gridCols: number, gridRows: number, glyphResolver: (s: string) => ([number, number, number])[], options?: TextmodeVideoOptions): Promise<TextmodeVideo>;
+    /**
+     * Play the video.
+     * @returns Promise that resolves when playback starts
+     */
+    play(): Promise<void>;
+    /**
+     * Pause the video.
+     */
+    pause(): void;
+    /**
+     * Stop the video and reset to beginning.
+     */
+    stop(): void;
+    /**
+     * Set the playback speed.
+     * @param rate Playback rate (1.0 = normal speed)
+     */
+    speed(rate: number): this;
+    /**
+     * Set whether the video should loop.
+     * @param shouldLoop Whether to loop (defaults to true)
+     */
+    loop(shouldLoop?: boolean): this;
+    /**
+     * Set the current time position in the video.
+     * @param seconds Time in seconds
+     */
+    time(seconds: number): this;
+    /**
+     * Set the volume.
+     * @param level Volume level (0.0-1.0)
+     */
+    volume(level: number): this;
+    /**
+     * WebGL texture handle containing the current video frame.
+     */
+    get texture(): WebGLTexture;
+    /**
+     * Ideal width to draw the video at (in grid cells), calculated to fit the grid while preserving aspect ratio.
+     */
+    get width(): number;
+    /**
+     * Ideal height to draw the video at (in grid cells), calculated to fit the grid while preserving aspect ratio.
+     */
+    get height(): number;
+    /**
+     * Original pixel width of the video.
+     */
+    get originalWidth(): number;
+    /**
+     * Original pixel height of the video.
+     */
+    get originalHeight(): number;
+    /**
+     * The underlying HTML video element.
+     */
+    get videoElement(): HTMLVideoElement;
+    /**
+     * Current playback time in seconds.
+     */
+    get currentTime(): number;
+    /**
+     * Total duration of the video in seconds.
+     */
+    get duration(): number;
+    /**
+     * Whether the video is currently playing.
+     */
+    get isPlaying(): boolean;
+    /**
+     * Whether this video has been preloaded with frames.
+     */
+    get isPreloaded(): boolean;
+    /**
+     * Total number of preloaded frames. Returns 0 for non-preloaded videos.
+     */
+    get totalFrames(): number;
+    /**
+     * The frame rate used for preloading. Returns null for non-preloaded videos.
+     */
+    get preloadFrameRate(): number | null;
+    /**
+     * Current frame index for preloaded videos. Returns 0 for non-preloaded videos.
+     */
+    get currentFrameIndex(): number;
+}
+export {};

package/dist/types/textmode/{font → loadables/font}/CharacterColorMapper.d.ts

@@ -17,7 +17,7 @@ export declare class CharacterColorMapper {
     /**
      * Generates a unique RGB color for a character based on its index.
      * @param index The index of the character
-     * @returns RGB color as a tuple [r, g, b] with values from 0-1 for shader use
+     * @returns RGB color as a tuple [r, g, 0] with values from 0-1 for shader use
      */
     private _generateCharacterColor;
     /**

package/dist/types/textmode/{font → loadables/font}/CharacterExtractor.d.ts

@@ -10,12 +10,6 @@ export declare class CharacterExtraction {
      * @returns Array of unique character strings
      */
     $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[];
     /**
      * Extracts characters from a Format 4 cmap table (Basic Multilingual Plane).
      */
@@ -28,8 +22,4 @@ export declare class CharacterExtraction {
      * Calculates the glyph index for a character in a Format 4 cmap table.
      */
     private _calculateGlyphIndexFormat4;
-    /**
-     * Checks if a character is valid for rendering.
-     */
-    private _isValidCharacter;
 }

package/dist/types/textmode/{font → loadables/font}/TextmodeFont.d.ts

@@ -1,9 +1,9 @@
-import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
-import type { GLFramebuffer } from '../../rendering/webgl/Framebuffer.ts';
+import type { GLRenderer } from '../../../rendering/webgl/core/Renderer.ts';
+import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer.ts';
 import type { TextmodeCharacter } from './types.ts';
 import type { TyprFont, GlyphData } from './typr/types.ts';
 /**
- * Manages the font used for rendering characters.
+ * Manages the font used for rendering characters via {@link Textmodifier.loadFont}.
  *
  * This class coordinates font loading, character extraction, texture atlas creation,
  * and provides character information.
@@ -75,9 +75,12 @@ export declare class TextmodeFont {
     $getCharacterColors(characters: string): [number, number, number][];
     /**
      * Lazily retrieves glyph data for the given Unicode code point.
+     *
      * Glyph data is cached after the first access to avoid repeated Typr parsing.
+     *
      * @param codePoint Unicode code point
      * @returns Parsed glyph data or null if unavailable
+     * @ignore
      */
     getGlyphData(codePoint: number): GlyphData | null;
     private _getGlyphIndex;

package/dist/types/textmode/{font → loadables/font}/TextureAtlas.d.ts

@@ -1,6 +1,6 @@
 import type { TextmodeCharacter, GlyphDimensions } from './types.ts';
-import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
-import type { GLFramebuffer } from '../../rendering/webgl/Framebuffer.ts';
+import type { GLRenderer } from '../../../rendering/webgl/core/Renderer.ts';
+import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer.ts';
 import type { TyprFont } from './typr/types.ts';
 /**
  * Handles creation of texture atlases for font rendering.
@@ -23,10 +23,10 @@ export declare class TextureAtlasCreation {
      * @param characters Array of TextmodeCharacter objects
      * @param maxGlyphDimensions Maximum dimensions of glyphs
      * @param fontSize Font size for rendering
-     * @param fontDataOrFamilyName Either Typr.js font data object for path rendering, or font family name string for fillText rendering
+     * @param font Either Typr.js font data object for path rendering, or font family name string for fillText rendering
      * @returns Object containing framebuffer, columns, and rows
      */
-    createTextureAtlas(characters: TextmodeCharacter[], maxGlyphDimensions: GlyphDimensions, fontSize: number, fontDataOrFamilyName: TyprFont | string): {
+    $createTextureAtlas(characters: TextmodeCharacter[], maxGlyphDimensions: GlyphDimensions, fontSize: number, font: TyprFont): {
         framebuffer: GLFramebuffer;
         columns: number;
         rows: number;
@@ -53,13 +53,6 @@ export declare class TextureAtlasCreation {
      * @returns Parsed glyph data or null if not found
      */
     private _getGlyphData;
-    /**
-     * Gets the advance width for a glyph
-     * @param fontData The Typr.js font data
-     * @param glyphIndex The glyph index
-     * @returns The advance width in font units
-     */
-    private _getGlyphAdvanceWidth;
     /**
      * Renders a glyph to the canvas using direct path rendering from glyph outline data.
      * @param glyphData Glyph data from Typr.js

package/dist/types/textmode/{font → loadables/font}/typr/types.d.ts

@@ -18,12 +18,6 @@ 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/loadables/index.d.ts

@@ -0,0 +1,5 @@
+export { TextmodeImage } from './TextmodeImage';
+export { TextmodeVideo } from './TextmodeVideo';
+export { TextmodeFont } from './font/TextmodeFont';
+export type { TextmodeCharacter } from './font/types';
+export type { TextmodeVideoOptions } from './TextmodeVideo';

package/dist/types/textmode/loading/LoadingPhaseTracker.d.ts

@@ -0,0 +1,20 @@
+import type { LoadingPhaseSnapshot } from './types';
+/**
+ * Tracks loading phases and their progress.
+ * @ignore
+ */
+export declare class LoadingPhaseTracker {
+    private _phases;
+    private _phaseOrder;
+    private _totalWeight;
+    private _lastReportedProgress;
+    private _onProgressChange?;
+    get totalWeight(): number;
+    get progress(): number;
+    setProgressChangeCallback(callback: (progress: number) => void): void;
+    createPhase(label: string, weight?: number): string;
+    updatePhaseProgress(id: string, progress: number): void;
+    completePhase(id: string): void;
+    failPhase(id: string): void;
+    snapshotPhases(): LoadingPhaseSnapshot[];
+}